cc-sessions-core

name	cc-sessions-core
description	Provide comprehensive guidance for developing and maintaining the cc-sessions framework core functionality - primary skill for hooks, sessions, tasks, middleware, route handlers, and API endpoints
schema_version	1

cc-sessions-core

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

Trigger Reference

This skill activates on:

• Keywords: "hook", "session", "task", "middleware", "route handler", "api endpoint", "cc-sessions"
• Intent patterns: "(create|modify|refactor).?(hook|session|task)", "sessions.?development", "api.*?(implementation|development)"
• File patterns: sessions/**/*.js, sessions/hooks/**/*.js, sessions/api/**/*.js

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

Purpose

Provide comprehensive guidance for developing and maintaining the cc-sessions framework core functionality. This is the primary skill for all cc-sessions development work including hooks, sessions, tasks, middleware, route handlers, and API endpoints.

Core Behavior

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

1. Framework Core Development

   • Guide implementation of new cc-sessions features
   • Ensure DAIC discipline enforcement
   • Maintain write-gating integrity
   • Implement state persistence mechanisms
   • Handle session lifecycle management

2. Hook Development

   • Create/modify hooks in sessions/hooks/
   • Ensure hooks respect DAIC modes
   • Implement proper error handling and logging
   • Validate hook execution order and dependencies
   • Test hook integration with enforcement layer

3. API Endpoint Development

   • Create/modify routes in sessions/api/
   • Follow RESTful conventions where applicable
   • Implement proper request validation
   • Ensure consistent error responses
   • Document API contracts

4. Task Management Features

   • Implement task creation, startup, and completion workflows
   • Handle task state transitions
   • Manage task manifests and context
   • Implement todo tracking and progression
   • Support task resumption and recovery

5. Middleware & Route Handlers

   • Create Express-compatible middleware
   • Implement route handlers with proper error handling
   • Ensure consistent request/response patterns
   • Apply security best practices (input validation, sanitization)

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 weaken DAIC discipline or write-gating logic
• ✓ Never bypass framework safety mechanisms

Framework Integrity Rules:

• Never allow writes outside IMPLEMENT mode (core framework requirement)
• Never modify CC_SESSION_MODE or CC_SESSION_TASK_ID directly (only cc-sessions API may do this)
• Preserve SoT tier boundaries (Tier-1 canonical, Tier-2 task-scoped, Tier-3 ephemeral)
• Maintain backward compatibility when modifying core APIs
• Document breaking changes in context/gotchas.md

Code Quality Standards:

• Follow existing code style and patterns
• Add JSDoc comments for public APIs
• Include error handling for all async operations
• Validate inputs at API boundaries
• Write tests for new functionality (when test infrastructure exists)

Examples

When to Activate

✓ "Create a new hook for validating task manifests" ✓ "Modify the session state API to include timestamps" ✓ "Add a new command: sessions tasks archive" ✓ "Fix the write-gating enforcement in sessions_enforce.js" ✓ "Implement task resumption from state.json"

When NOT to Activate

✗ In DISCUSS/ALIGN/CHECK mode (framework development requires IMPLEMENT) ✗ No active cc-sessions task (violates write-gating) ✗ User is working on application code (not framework code) ✗ Changes would weaken safety mechanisms

Framework Architecture Awareness

Key Files & Responsibilities

Core:

• sessions/bin/sessions - CLI entry point
• sessions/api/router.js - Main API router
• sessions/sessions-state.json - Session state persistence

Hooks:

• sessions/hooks/sessions_enforce.js - Write-gating and DAIC enforcement
• Hook execution: UserPromptSubmit, SessionStart, PreToolUse, PostToolUse

API Modules:

• sessions/api/state_commands.js - State management (show, mode, task, todos, flags, update)
• sessions/api/task_commands.js - Task operations (idx, start)
• sessions/api/config_commands.js - Configuration management
• sessions/api/protocol_commands.js - Protocol execution

DAIC Flow

1. DISCUSS → Clarify, gather context, no writes
2. ALIGN → Design plan, create manifest, no writes
3. IMPLEMENT → Execute approved todos, writes allowed
4. CHECK → Verify, test, summarize, minimal writes

State Management

• Session state tracked in sessions/sessions-state.json
• Task state tracked in sessions/sessions-state.json (lightweight checkpoint)
• Hooks enforce state consistency
• State transitions logged for debugging

Decision Logging

When modifying core framework behavior, log in context/decisions.md:

### Framework Change: [Date]
- **Component:** sessions/hooks/sessions_enforce.js
- **Change:** Added todo list change detection
- **Rationale:** Users were bypassing execution boundary by silently changing todos
- **Impact:** All todo modifications now require explicit approval
- **Breaking:** No (additive change only)

Related Skills

• cc-sessions-hooks - Specialized hook development (defers to this when hooks are involved)
• cc-sessions-api - Specialized API development (defers to this when API commands are involved)
• skill-developer - For creating skills that integrate with cc-sessions
• framework_health_check - To validate framework health after changes
• framework_repair_suggester - If framework issues arise during development

---

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