murillodutt/cellm/skills/spec

Spec Thinking — Before Action

Every spec is an atomic puzzle in the database. Never a markdown file.

Routing

| Argument | Action | |----------|--------| | (empty) | spec_get_counters + spec_search(state: "pending"\|"in_progress") → compact table | | create <title> | Briefing → check → phases → tasks (all in DB) | | status | All checks → counters per check → [x] [~] [ ] [!] summary | | treat <query> | Delegate to /cellm:spec-treat |

Create: The Briefing

Before any node exists, commit to a direction:

1. Context — Where are we? What exists? One sentence.
2. Problem — What is wrong or missing? One sentence.
3. Principle — The rule that guides every decision. One sentence.

These three sentences ARE the spec. Everything else is decomposition.

After the check: decompose into phases (work groups) and tasks (atomic actions). Each task has an imperative action, optional fileRef, optional diffExpected. Phases form the dependency DAG.

Project: always git rev-parse --show-toplevel → last segment. Pass sessionId (current session) to spec_create_node for audit trail. Auto-chain supported: calling completed from pending/active resolves intermediate states automatically. Auto-rollup: when all child tasks complete, the parent phase auto-completes — but YOU must call spec_transition on each leaf task for rollup to trigger.

NEVER

• Markdown files — specs live in compass.db, never on disk
• Create without all 3 briefing fields — Context, Problem, Principle are mandatory
• Skip project detection — always derive from git root
• Vague tasks — every task action is imperative and atomic
• Write in any language other than English — all titles, briefings, actions, and descriptions must be in English for optimal LLM processing and tokenization efficiency
• Omit sessionId — always pass sessionId (current session) to spec_create_node and spec_add_verification for audit trail
• Ignore BLOCKED_BY_DEPENDENCY — if spec_transition returns this error, check predecessor phase status before proceeding
• Invalid parent-child hierarchies — check→phase/task/gap/decision/requirement/verification, phase→task/gap/decision/verification, task→gap/verification. Service rejects violations with INVALID_CHILD_TYPE.