Task Persistence System - Never Lose Context Again

Tasks of medium or higher complexity create a persistent task directory. This is the core mechanism behind CCG’s cross-session state recovery and phase gating.

Directory Structure

.ccg/tasks/add-jwt-auth/
├── task.json         # Status, strategy, current phase, gate
├── requirements.md   # Enhanced requirements document
├── plan.md           # Approved implementation plan
├── context.jsonl     # Spec files needed by sub-agents
├── review.md         # Review results
└── research/         # Persisted research findings

task.json

The core file of the task system, recording the complete task state:

{
  "id": "add-jwt-auth",
  "status": "in_progress",
  "strategy": "full-collaborate",
  "phase": "4-implementation",
  "gate": "approved",
  "created": "2026-05-16T10:00:00Z",
  "updated": "2026-05-16T11:30:00Z",
  "classification": {
    "type": "feature",
    "complexity": "L",
    "domain": "backend",
    "risk": "high"
  }
}

requirements.md

The enhanced requirements document produced during the full-collaborate strategy’s dual-model analysis phase. It contains:

Original user requirements
Codex’s backend analysis additions
Gemini’s frontend analysis additions
Identified constraints and risks

plan.md

The implementation plan approved after the HARD STOP human review, including:

Implementation steps
File modification list
Builder assignments (when using Agent Teams)
Acceptance criteria

context.jsonl

The sub-agent injection manifest, one JSON object per line:

{"type": "spec", "path": ".ccg/spec/backend/index.md"}
{"type": "spec", "path": ".ccg/spec/guides/auth.md"}
{"type": "plan", "path": ".ccg/tasks/add-jwt-auth/plan.md"}

The subagent-context.js hook reads this file and injects the referenced content into the prompts for codeagent-wrapper calls and Team Builder spawns.

review.md

Dual-model cross-review results, graded by severity:

Critical — Must fix before delivery
Warning — Should fix
Info — Optional improvement

Phase Gates

A task progresses through multiple phases from creation to completion. Some phases enforce a mandatory HARD STOP:

Phase 1: Context collection
    ↓
Phase 2: Analysis (dual-model parallel)
    ↓
Phase 3: Plan generation
    ↓
  ██ HARD STOP — Awaiting human approval ██
    ↓
Phase 4: Implementation (Agent Teams / direct coding)
    ↓
Phase 5: Verification (quality gates)
    ↓
Phase 6: Review (dual-model cross-review)
    ↓
  ██ HARD STOP — Confirm results ██
    ↓
Phase 7: Completion

State Recovery Mechanism

The task system works with the hook engine to achieve cross-session state recovery:

Per-turn injection — workflow-state.js reads task.json every turn and injects state into Claude’s context
Post-compaction recovery — After context compaction, session-start.js re-injects full task state
New session recovery — When a new session opens, session-start.js detects unfinished tasks and injects them

Session 1: Create task → Analyze → Plan → HARD STOP
    (user leaves)

Session 2: session-start.js detects unfinished task
    → Injects task.json + plan.md
    → Claude knows "stopped at HARD STOP, awaiting approval"
    → User says "continue" → Enters implementation phase

Task Lifecycle

Status	Meaning
`created`	Task directory created
`in_progress`	Currently executing
`hard_stop`	Awaiting human decision
`completed`	Finished successfully
`failed`	Execution failed
`cancelled`	Cancelled by user

Which Strategies Create Task Directories

Strategy	Creates Task Directory
`direct-fix`	No
`quick-implement`	No
`guided-develop`	Yes
`full-collaborate`	Yes
`debug-investigate`	Yes
`refactor-safely`	Yes
`deep-research`	Yes
`optimize-measure`	Yes
`review-audit`	No (results output directly)
`git-action`	No