cc-sessions-api

name	cc-sessions-api
description	Specialized guidance for developing cc-sessions API commands and subsystems for state management, task operations, configuration, and protocol execution
schema_version	1

cc-sessions-api

Type: WRITE-CAPABLE DAIC Modes: IMPLEMENT only Priority: High

Trigger Reference

This skill activates on:

• Keywords: "session command", "task command", "state command", "protocol command", "config command"
• Intent patterns: "(create|modify|fix).?(command|api)", "sessions.?api"
• File patterns: sessions/api/**/*.js

From: skill-rules.json - cc-sessions-api configuration

Purpose

Specialized guidance for developing cc-sessions API commands and subsystems. The API provides CLI commands for state management, task operations, configuration, and protocol execution.

Core Behavior

When activated in IMPLEMENT mode with an active cc-sessions task:

1. API Architecture

   Entry Point: sessions/bin/sessions (CLI binary) Router: sessions/api/router.js (command dispatch) Subsystems:

   • state_commands.js - State management
   • task_commands.js - Task operations
   • config_commands.js - Configuration
   • protocol_commands.js - Protocol execution

2. Command Subsystems

   State Commands (state_commands.js)

   sessions state show          # Display current session state
   sessions state mode [value]  # Get/set DAIC mode
   sessions state task [value]  # Get/set active task
   sessions state todos         # Manage todo list
   sessions state flags         # View/modify session flags
   sessions state update        # Update state values
   

   Task Commands (task_commands.js)

   sessions tasks idx list              # List task indexes
   sessions tasks idx <index-name>      # View tasks in index
   sessions tasks start <task-file>     # Start a task
   

   Config Commands (config_commands.js)

   sessions config show         # Display all configuration
   sessions config phrases      # View startup phrases
   sessions config git          # Git integration settings
   sessions config env          # Environment variables
   sessions config features     # Feature flags
   sessions config read <key>   # Read specific config value
   sessions config write        # Write config values
   sessions config tools        # Tool configurations
   

   Protocol Commands (protocol_commands.js)

   sessions protocol startup-load       # Startup initialization
   

3. Command Development Pattern

   Basic Command Structure:

   // sessions/api/example_commands.js
   module.exports = {
     name: 'example',
     description: 'Example command subsystem',
   
     async execute(args) {
       const [subcommand, ...rest] = args;
   
       switch (subcommand) {
         case 'action1':
           return this.handleAction1(rest);
         case 'action2':
           return this.handleAction2(rest);
         default:
           return this.showHelp();
       }
     },
   
     async handleAction1(args) {
       // Implementation
       return { success: true, message: 'Action completed' };
     },
   
     showHelp() {
       return {
         success: true,
         message: `
   

Usage: sessions example

Actions: action1 - Description of action1 action2 - Description of action2 `.trim() }; } };

4. **State Management Patterns**

**Reading State:**
```javascript
const fs = require('fs');
const path = require('path');

const statePath = path.join(__dirname, '../sessions-state.json');
const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));

console.log('Current mode:', state.mode);
console.log('Active task:', state.task.name);

Writing State:

// Read-modify-write pattern
const state = loadState();
state.mode = 'IMPLEMENT';
state.task.status = 'in_progress';
saveState(state);

Validation:

function validateMode(mode) {
  const validModes = ['DISCUSS', 'ALIGN', 'IMPLEMENT', 'CHECK'];
  if (!validModes.includes(mode)) {
    throw new Error(`Invalid mode: ${mode}. Must be one of: ${validModes.join(', ')}`);
  }
}

5. Error Handling

   Consistent Error Format:

   if (errorCondition) {
     return {
       success: false,
       error: 'Clear, actionable error message',
       hint: 'Optional suggestion for user'
     };
   }
   

   Input Validation:

   async execute(args) {
     if (args.length === 0) {
       return {
         success: false,
         error: 'Missing required argument: <action>',
         hint: 'Use "sessions example help" for usage'
       };
     }
     // ...
   }
   

6. Output Formatting

   Success Messages:

   return {
     success: true,
     message: '✓ Task started successfully',
     data: { taskName, branch }
   };
   

   Informational Output:

   console.log('=== Session State ===');
   console.log(`Mode: ${state.mode}`);
   console.log(`Task: ${state.task.name}`);
   

Safety Guardrails

CRITICAL WRITE-GATING RULES:

• ✓ Only execute write operations when in IMPLEMENT mode
• ✓ Verify active cc-sessions task exists before writing
• ✓ Follow approved manifest/todos from task file
• ✓ Never allow commands to bypass DAIC discipline
• ✓ Never allow direct modification of protected state (CC_SESSION_MODE, CC_SESSION_TASK_ID)

API-Specific Safety:

• Validate all user inputs before processing
• Never expose internal state structure directly
• Sanitize file paths to prevent directory traversal
• Use atomic read-modify-write for state changes
• Return consistent error formats
• Log command execution for debugging
• Never execute arbitrary code from user input

State Integrity:

• Always validate state structure before writing
• Preserve state schema compatibility
• Handle missing or corrupted state gracefully
• Provide clear error messages for invalid state
• Log state changes for auditability

Examples

When to Activate

✓ "Add a new command: sessions tasks archive" ✓ "Modify state show to include task branch" ✓ "Fix the task idx command to handle missing indexes" ✓ "Create a new subsystem for managing LCMP files" ✓ "Add validation to the state mode command"

When NOT to Activate

✗ In DISCUSS/ALIGN/CHECK mode (API development requires IMPLEMENT) ✗ No active cc-sessions task (violates write-gating) ✗ User wants to work on hooks (use cc-sessions-hooks) ✗ User wants general framework features (use cc-sessions-core)

Command Development Checklist

Before deploying a new or modified command:

• Command follows naming conventions (subsystem + action)
• Help text is clear and includes examples
• All inputs are validated
• Error messages are actionable
• State changes are atomic
• Command works with missing/invalid state
• Output format is consistent with other commands
• Edge cases are handled gracefully
• Command is documented in router.js
• Manual testing completed

Common Command Patterns

1. Get/Set Pattern

async execute(args) {
  if (args.length === 0) {
    // GET: Show current value
    return { success: true, data: state.value };
  } else {
    // SET: Update value
    state.value = args[0];
    saveState(state);
    return { success: true, message: 'Value updated' };
  }
}

2. List Pattern

async handleList() {
  const items = loadItems();
  if (items.length === 0) {
    return { success: true, message: 'No items found' };
  }

  console.log('Available items:');
  items.forEach(item => console.log(`  • ${item.name}`));
  return { success: true };
}

3. Subcommand Pattern

async execute(args) {
  const [subcommand, ...rest] = args;

  const handlers = {
    'list': this.handleList,
    'add': this.handleAdd,
    'remove': this.handleRemove
  };

  const handler = handlers[subcommand];
  if (!handler) {
    return { success: false, error: `Unknown subcommand: ${subcommand}` };
  }

  return handler.call(this, rest);
}

Decision Logging

When creating or modifying commands, log in context/decisions.md:

### API Change: [Date]
- **Command:** sessions tasks archive
- **Change:** New command to move completed tasks to done/ directory
- **Rationale:** Users need way to clean up task list without deleting history
- **API:** sessions tasks archive <task-name>
- **State Impact:** Updates task index, moves file, logs action
- **Testing:** Verified with 3 test tasks, handles missing files gracefully

Related Skills

• cc-sessions-core - For broader framework development beyond API
• cc-sessions-hooks - If commands need hook integration
• framework_health_check - To validate API behavior after changes
• framework_repair_suggester - If API commands malfunction
• daic_mode_guidance - For understanding mode transitions that commands trigger

---

Last Updated: 2025-11-15 Framework Version: 2.0