Skip to main content

​
Specification Index

GENERATED FILE - This markdown is generated from SPEC-INDEX.json. For programmatic access, use the JSON file directly.
Purpose: Human-readable view of the specification catalog Last Updated: 2025-12-29 Total Specifications: 22 | Implementation Reports: 6 Index Version: 1.1.0

​
LLM Agent Usage (Preferred)

# Query authoritative source for a domain
jq '.authorities["task-ids"]' docs/archive/specs-md/SPEC-INDEX.json
# → "LLM-TASK-ID-SYSTEM-DESIGN-SPEC.md"

# List all IMMUTABLE specs
jq '.specs[] | select(.status == "IMMUTABLE") | .file' docs/archive/specs-md/SPEC-INDEX.json

# Get dependencies for a spec
jq '.specs[] | select(.file == "TASK-HIERARCHY-SPEC.md") | .dependsOn' docs/archive/specs-md/SPEC-INDEX.json

# Find specs by domain
jq '.specs[] | select(.domain == "phase-lifecycle")' docs/archive/specs-md/SPEC-INDEX.json

# Get implementation progress
jq '.reports[] | {file, progress, notes}' docs/archive/specs-md/SPEC-INDEX.json

​
Why JSON?

AspectJSONMarkdown
Parsingjq, nativeRegex, heuristics
ValidationSchema-enforcedNone
QueriesStructured (select, map)Text search
UpdatesProgrammaticManual editing
Token efficiencyCompactFormatting overhead

​
Human Navigation

​
For Developers

  1. Start with Status to understand document maturity
  2. Check Synopsis for quick understanding
  3. Follow Implementation Report links for current progress

​
Quick Reference

​
Spec Status Legend

StatusMeaningCan ChangeWhen to Use
IMMUTABLELocked forever, authoritative referenceNEVERPermanent design decisions
ACTIVECurrent design, may evolve carefullyYes (versioned)Evolving features
APPROVEDEndorsed for implementationYes (formal amendments)Stable designs
DRAFTWork in progressYes (freely)New designs under review
DEPRECATEDHistorical only, supersededNoLegacy reference

​
Document Type Legend

TypePurposeContains
SPECRequirements and contractsWHAT system does
IMPLEMENTATION-REPORTProgress trackingStatus, checklists, %
GUIDELINESStandards and best practicesHOW to write specs
PLANImplementation strategySequencing, tasks

​
Status Distribution

StatusCountDocuments
IMMUTABLE2SPEC-BIBLE-GUIDELINES, LLM-TASK-ID-SYSTEM-DESIGN-SPEC
ACTIVE5LLM-AGENT-FIRST, CONFIG-SYSTEM, FILE-LOCKING, PHASE-SYSTEM, TODOWRITE-SYNC
APPROVED1HIERARCHY-ENHANCEMENT
DRAFT2FIND-COMMAND, RELEASE-VERSION-MANAGEMENT
PLANNING1LLM-AGENT-FIRST-FINALIZATION-PLAN
IMPLEMENTED3PHASE-DELETE, PHASE-RENAME, PHASE-ROLLBACK

​
All Specifications

​
Core System Specifications

DocumentVersionStatusLast UpdatedSynopsis
SPEC-BIBLE-GUIDELINES.md1.0.0IMMUTABLE2025-12-17Authoritative standards for writing specifications. Defines SPEC vs IMPLEMENTATION-REPORT separation, RFC 2119 usage, status lifecycle.
LLM-TASK-ID-SYSTEM-DESIGN-SPEC.md1.0.0 FINALIMMUTABLE2025-01-17Task ID system design (T001 format). Flat sequential IDs with parentId for hierarchy. Six guarantees: unique, immutable, stable, sequential, referenceable, recoverable.
LLM-AGENT-FIRST-SPEC.md3.0ACTIVE2025-12-18CLI design standard for LLM agents. JSON output by default, TTY auto-detection, 32 commands, standardized exit/error codes, universal flags.
PHASE-SYSTEM-SPEC.mdv2.2.0+ACTIVE2025-12-17Dual-level phase model: project lifecycle phases vs task categorization. Defines phase transitions, history, validation rules.
CONFIG-SYSTEM-SPEC.md1.0.0ACTIVE2025-12-19Configuration system with global (~/.cleo/config.json) and project (.cleo/config.json) configs. Priority resolution, environment variables.
FILE-LOCKING-SPEC.md1.0.0ACTIVE2025-12-19File locking & concurrency safety. Exclusive locks via flock, 30s timeout, atomic write operations, error recovery.

​
Feature Specifications

DocumentVersionStatusLast UpdatedSynopsis
TASK-HIERARCHY-SPEC.md2.0.0APPROVED2025-12-29Epic → Task → Subtask taxonomy with max depth 3, unlimited siblings by default. Flat ID + parentId design. LLM-Agent-First.
TODOWRITE-SYNC-SPEC.md1.0.0ACTIVE2025-12-18Bidirectional sync between cleo (durable) and Claude Code TodoWrite (ephemeral). Lossy by design with ID preservation via [T###] prefix.
FIND-COMMAND-SPEC.md1.0DRAFT2025-12-18Fuzzy task search command. Context reduction 355KB→1KB (99.7%). ID prefix matching, match scoring, minimal output.
RELEASE-VERSION-MANAGEMENT-SPEC.md2.0.0DRAFT2025-12-18Release version tracking with 4-state lifecycle (planning→development→released/cancelled). VERSION file integration, git tags.

​
Pipeline & Orchestration Specifications

DocumentVersionStatusLast UpdatedSynopsis
CLEO-SYSTEM-ARCHITECTURE-SPEC.md1.0.0DRAFT2025-12-29High-level architecture connecting all CLEO subsystems. Complete lifecycle from idea to release. Exit code allocation.
RCSD-PIPELINE-SPEC.md2.0.0DRAFT2025-12-29Research-Consensus-Spec-Decompose pipeline. 4-stage workflow transforming research into atomic tasks. Exit codes 30-39.
CONSENSUS-FRAMEWORK-SPEC.md2.0.0ACTIVE2025-12-237-agent consensus framework (5 workers + synthesis + orchestrator). Adversarial validation with HITL gates.
TASK-DECOMPOSITION-SPEC.md1.0.0ACTIVE2025-12-23HTN-style task decomposition with atomicity validation. Wave computation from dependency DAG.
IMPLEMENTATION-ORCHESTRATION-SPEC.md1.1.0DRAFT2025-12-297-agent implementation workflow (Planner→Coder→Testing→QA→Cleanup→Security→Docs). Verification gates. Exit codes 40-49.
RELEASE-MANAGEMENT-SPEC.md1.0.0DRAFT2025-12-29Release lifecycle (planned→staging→released). Changelog generation, roadmap, git tags. Exit codes 50-59.
ISSUE-LIFECYCLE-SPEC.md1.0.0DRAFT2025-12-29Bug/issue tracking via origin field. Triage, severity, verification protocol. Exit codes 60-69.

​
Session & Lifecycle Specifications

DocumentVersionStatusLast UpdatedSynopsis
MULTI-SESSION-SPEC.md1.0.0ACTIVE2025-12-27Concurrent agent sessions with scope isolation. Epic-bound session architecture. Exit codes 20-29.
EPIC-SESSION-SPEC.md1.0.0ACTIVE2025-12-27Epic-scoped session binding. Session-task relationship management.
PROJECT-LIFECYCLE-SPEC.md1.0.0DRAFT2025-12-22Greenfield/brownfield/grayfield patterns. Two-dimensional work model (Epics × Phases).

​
Planning Documents

DocumentVersionStatusLast UpdatedSynopsis
LLM-AGENT-FIRST-FINALIZATION-PLAN.md-PLANNING2025-12-18Addresses 47 findings from 5 adversarial agents. 4 phases (P0-P3) with 28 tasks. Performance (689 jq calls→~50), test coverage (0%→80%).

​
Phase Implementation Guides

DocumentVersionStatusLast UpdatedSynopsis
PHASE-DELETE-IMPLEMENTATION.md-IMPLEMENTEDv0.16.0+phase delete command with orphan prevention, force flag, task reassignment.
PHASE-RENAME-IMPLEMENTATION.md-IMPLEMENTEDv0.16.0+Atomic phase rename with task reference updates and rollback safety.
PHASE-ROLLBACK-IMPLEMENTATION.md-IMPLEMENTEDv0.14.0Rollback detection with —rollback flag, interactive confirmation, JSON mode.

​
Implementation Reports

SpecificationImplementation ReportProgressNotes
LLM-AGENT-FIRST-SPECLLM-AGENT-FIRST-IMPLEMENTATION-REPORT.md100%All 32 commands have complete _meta envelopes
TODOWRITE-SYNC-SPECTODOWRITE-SYNC-IMPLEMENTATION-REPORT.md85%16/18 core features complete, v1 stable
FILE-LOCKING-SPECFILE-LOCKING-IMPLEMENTATION-REPORT.md~70%Core done, script integration partial
CONFIG-SYSTEM-SPECCONFIG-SYSTEM-IMPLEMENTATION-REPORT.md~60%8/14 components complete (T382 epic)
LLM-TASK-ID-SYSTEM-DESIGN-SPECLLM-TASK-ID-SYSTEM-DESIGN-IMPLEMENTATION-REPORT.mdVariesID system works, hierarchy pending
RELEASE-VERSION-MANAGEMENT-SPECRELEASE-VERSION-MANAGEMENT-IMPLEMENTATION-REPORT.md0%Research complete, v0.20.0 target

​
Domain Authority Map

What is this? Declares which specification is the AUTHORITATIVE source for each domain. When specs conflict, defer to the authoritative source.
DomainAuthoritative SpecDefers To
System ArchitectureCLEO-SYSTEM-ARCHITECTURE-SPEC.mdAll domain specs for details
Task IDsLLM-TASK-ID-SYSTEM-DESIGN-SPEC.md-
Specification WritingSPEC-BIBLE-GUIDELINES.md-
LLM-First DesignLLM-AGENT-FIRST-SPEC.mdSPEC-BIBLE-GUIDELINES for spec structure
Phase LifecyclePHASE-SYSTEM-SPEC.mdLLM-TASK-ID-SYSTEM-DESIGN-SPEC for ID handling
Task HierarchyTASK-HIERARCHY-SPEC.mdLLM-TASK-ID-SYSTEM-DESIGN-SPEC for ID contract
TodoWrite SyncTODOWRITE-SYNC-SPEC.mdLLM-TASK-ID-SYSTEM-DESIGN-SPEC for IDs, PHASE-SYSTEM-SPEC for phases
ConfigurationCONFIG-SYSTEM-SPEC.md-
File OperationsFILE-LOCKING-SPEC.md-
VersioningRELEASE-VERSION-MANAGEMENT-SPEC.md-
SearchFIND-COMMAND-SPEC.mdLLM-TASK-ID-SYSTEM-DESIGN-SPEC for ID validation
RCSD PipelineRCSD-PIPELINE-SPEC.mdCONSENSUS-FRAMEWORK-SPEC, TASK-DECOMPOSITION-SPEC
Multi-Agent ConsensusCONSENSUS-FRAMEWORK-SPEC.md-
Task DecompositionTASK-DECOMPOSITION-SPEC.mdPHASE-SYSTEM-SPEC for phases
Implementation OrchestrationIMPLEMENTATION-ORCHESTRATION-SPEC.mdMULTI-SESSION-SPEC for sessions
Release ManagementRELEASE-MANAGEMENT-SPEC.mdIMPLEMENTATION-ORCHESTRATION-SPEC
Issue LifecycleISSUE-LIFECYCLE-SPEC.mdRELEASE-MANAGEMENT-SPEC
Multi-SessionMULTI-SESSION-SPEC.md-
Project LifecyclePROJECT-LIFECYCLE-SPEC.mdPHASE-SYSTEM-SPEC

​
Specification Dependencies

​
Dependency Graph

SPEC-BIBLE-GUIDELINES.md (Meta-level authority)
    │
    ├─► All specifications follow these guidelines
    │
    └─► LLM-TASK-ID-SYSTEM-DESIGN-SPEC.md (ID authority - IMMUTABLE)
            │
            ├─► PHASE-SYSTEM-SPEC.md
            │       ├─► PHASE-DELETE-IMPLEMENTATION.md
            │       ├─► PHASE-RENAME-IMPLEMENTATION.md
            │       └─► PHASE-ROLLBACK-IMPLEMENTATION.md
            │
            ├─► TASK-HIERARCHY-SPEC.md
            │       └─► Depends on: flat ID + parentId design
            │
            ├─► TODOWRITE-SYNC-SPEC.md
            │       └─► Depends on: ID format, PHASE-SYSTEM-SPEC
            │
            └─► FIND-COMMAND-SPEC.md
                    └─► Depends on: ID validation patterns

LLM-AGENT-FIRST-SPEC.md (Design philosophy)
    │
    └─► Influences: all command implementations

FILE-LOCKING-SPEC.md (Infrastructure)
    │
    └─► Depended on by: all write operations

CONFIG-SYSTEM-SPEC.md (Infrastructure)
    │
    └─► Provides config for: all features

​
Dependency Table

SpecificationDepends OnDepended On By
SPEC-BIBLE-GUIDELINES-All specs (meta)
LLM-TASK-ID-SYSTEM-DESIGN-SPEC-PHASE-SYSTEM, HIERARCHY, TODOWRITE-SYNC, FIND-COMMAND
PHASE-SYSTEM-SPECLLM-TASK-ID-SYSTEM-DESIGN-SPECTODOWRITE-SYNC, phase implementation guides
TASK-HIERARCHY-SPECLLM-TASK-ID-SYSTEM-DESIGN-SPEC-
TODOWRITE-SYNC-SPECLLM-TASK-ID-SYSTEM-DESIGN-SPEC, PHASE-SYSTEM-
CONFIG-SYSTEM-SPEC-All features (config provider)
FILE-LOCKING-SPEC-All write operations
LLM-AGENT-FIRST-SPECSPEC-BIBLE-GUIDELINESAll command implementations
FIND-COMMAND-SPECLLM-TASK-ID-SYSTEM-DESIGN-SPEC-
RELEASE-VERSION-MANAGEMENT-SPEC-All deliverables

​
Specifications by Category

​
Architecture & Design Philosophy

​
Core Systems

​
Task Management

​
Pipeline & Orchestration

​
Session Management

​
Release & Issue Management

​
Integration

​
Specifications by Status

​
IMMUTABLE (Locked Forever)

​
ACTIVE (Current, May Evolve)

​
APPROVED (Endorsed, Formal Amendments)

​
DRAFT (Work in Progress)

​
Recent Changes Log

Maintenance: Add entries when specs are created, updated, or status changes. Keep last 20 entries.
DateSpecificationChangeVersionDescription
2025-12-29CLEO-SYSTEM-ARCHITECTURE-SPECCreated1.0.0High-level system architecture
2025-12-29IMPLEMENTATION-ORCHESTRATION-SPECUpdated1.1.0Added Epic lifecycle integration
2025-12-29RELEASE-MANAGEMENT-SPECCreated1.0.0Release lifecycle, changelog, roadmap
2025-12-29ISSUE-LIFECYCLE-SPECCreated1.0.0Bug/issue tracking via origin field
2025-12-29SCHEMA-CHANGES-SUMMARYCreated1.0.0Consolidated schema changes reference
2025-12-29SPEC-INDEX.mdUpdated1.1.0Added pipeline & orchestration specs
2025-12-29TASK-HIERARCHY-SPECUpdated2.0.0Schema v2.4.0
2025-12-27MULTI-SESSION-SPECUpdated1.0.0Epic-bound session architecture
2025-12-23RCSD-PIPELINE-SPECUpdated2.0.0Python Agent SDK implementation
2025-12-23CONSENSUS-FRAMEWORK-SPECUpdated2.0.07-agent architecture
2025-12-22PROJECT-LIFECYCLE-SPECCreated1.0.0Greenfield/brownfield patterns
2025-12-19SPEC-INDEX.mdCreated1.0.0Initial specification index
2025-12-19CONFIG-SYSTEM-SPECUpdated1.0.0Status updated
2025-12-19FILE-LOCKING-SPECUpdated1.0.0Status updated
2025-12-18LLM-AGENT-FIRST-SPECUpdated3.0Compliance scoring rubric
2025-12-18TODOWRITE-SYNC-SPECUpdated1.0.0v1 stable release
2025-12-18FIND-COMMAND-SPECCreated1.0New search command spec
2025-12-18RELEASE-VERSION-MANAGEMENT-SPECUpdated2.0.0Research complete
2025-12-17SPEC-BIBLE-GUIDELINESFinalized1.0.0Set to IMMUTABLE
2025-12-17PHASE-SYSTEM-SPECUpdatedv2.2.0+Phase lifecycle commands

​
How to Add a New Specification

​
Process

  1. Create the specification
    • Use template from SPEC-BIBLE-GUIDELINES.md
    • Follow naming: [DOMAIN]-SPEC.md or [DOMAIN]-[FEATURE]-SPEC.md
    • Set initial status to DRAFT
  2. Create implementation report (optional)
    • Use template from SPEC-BIBLE-GUIDELINES Part 8
    • Naming: [SPEC-NAME]-IMPLEMENTATION-REPORT.md
  3. Update this index
    • Add entry to appropriate “All Specifications” table
    • Add to “Domain Authority Map” if authoritative
    • Add to “Specification Dependencies” if dependencies exist
    • Add to “Recent Changes Log”
    • Add to appropriate “By Category” section
    • Add to “By Status” section

​
Checklist

  • Specification file created following SPEC-BIBLE-GUIDELINES
  • Implementation report created (if tracking needed)
  • Added to “All Specifications” table with synopsis
  • Domain authority declared (if authoritative)
  • Dependencies documented
  • Recent changes log entry added
  • Categorized by domain and status
  • Cross-referenced in main INDEX.md

​
Critical Documents for Development

​
Must-Read for Any Changes

  1. SPEC-BIBLE-GUIDELINES.md - How to write/update specs
  2. LLM-AGENT-FIRST-SPEC.md - All CLI output requirements
  3. LLM-TASK-ID-SYSTEM-DESIGN-SPEC.md - ID system rules (NEVER change)

​
Implementation References

  • LLM-AGENT-FIRST-IMPLEMENTATION-REPORT.md - Current compliance status
  • CONFIG-SYSTEM-IMPLEMENTATION-REPORT.md - Config work tracking
  • FILE-LOCKING-IMPLEMENTATION-REPORT.md - Locking work tracking
DocumentPurpose
../INDEX.mdMain documentation index
../architecture/ARCHITECTURE.mdSystem architecture
../QUICK-REFERENCE.mdDeveloper reference
Last validated: 2025-12-29