Workflow
Every change in a Coograph-initialized project goes through the same five-step pipeline: Plan → Propose → Apply → Review → Archive. The only exemptions are narrow and literal — typo fixes, comment-only edits, user-dictated config-value bumps, and follow-ups on an already-approved in-progress proposal.
“Trivial,” “obvious,” “small,” and “just one tweak” are not exemptions. If in doubt, propose.
The point of the workflow isn’t ceremony. It’s that AI agents are uniquely good at confidently shipping the wrong thing, and the workflow forces an interrupt point before that happens.
Plan
/project:plan (Claude Code) or @Planner (VS Code Copilot).
The Planner agent investigates the codebase and asks one focused clarifying question at a time. It never writes code. Output is a clear understanding of what the change requires — files, integration points, risks.
Skip planning when:
- Review output already exists in conversation.
- The user has specified the problem, files, and fix direction.
- The fix is a one-line exempt change per the literal list above.
Propose
The openspec-propose skill creates an OpenSpec change directory at openspec/changes/<YYYY-MM-DD>-<slug>/ with:
.openspec.yaml
proposal.md ← Why, Goals, Non-Goals, Decisions, Impact, Risks
specs/<capability>/spec.md ← Requirements + Scenarios
tasks.md ← 3–8 task groups, last is VerificationThe user reviews and either says “proceed” or sends edits. No code is written before approval.
Apply
The agent works through tasks.md in order, marking tasks done as it goes.
- Read every file before editing.
- Check API spec / generated types before assuming names.
- If a build error is non-obvious, run
/project:debug. - Mid-implementation requirement changes update the OpenSpec, then continue.
After all tasks are done, run quality gates: typecheck, lint, format, tests. Fix until clean.
Review
/project:review or @Reviewer.
The Reviewer is read-only. Every finding cites a verbatim quote from a fresh file read — diffs and conversation memory are not valid sources.
Findings are severity-rated: Critical (must fix before merge), Warning (should fix), Suggestion (could fix). The implementor fixes Critical/Warning findings, re-runs quality gates, and re-reviews only if fixes were substantial.
Archive
Move the completed proposal:
mv openspec/changes/<slug>/ openspec/changes/archive/<slug>/This keeps openspec/changes/ populated only with active work — agents read in-progress proposals on session start.
Agents
There is no separate @Implementer. The agent that plans also implements.
| Agent | Purpose | Key constraint |
|---|---|---|
| Planner | Interview-driven planning | One question at a time. Never implements. |
| Reviewer | Strict read-only code review | Every finding cites a verbatim quote. |
| Debugger | Root-cause analysis, minimal fixes | Reproduce → Evidence → Fix → Verify. 3-attempt circuit breaker. |
| Verifier | Evidence-based completion checks | Runs commands itself. PASS/FAIL/INCOMPLETE verdict. |
| Explore | Fast read-only codebase Q&A | Quick / medium / thorough depth levels. |
All agents are required to call code-graph first. Fallback to sqlite3 .code-graph/graph.db, and only then to grep, is permitted only when the graph DB is genuinely absent. Convenience is not a valid reason to skip.
Lifecycle hooks
Claude Code lifecycle hooks live in .claude/hooks/:
| Hook | What it does |
|---|---|
block-generated.py | Blocks edits to files under generated/, dist/, build/, etc., and to anything with @generated / DO NOT EDIT in its first 5 lines. |
log-bash.py | Appends every bash command to .claude/session.log (gitignored). Audit trail. |
report-graph.py | Reports code-graph state at session start. Prints a rebuild hint if graph.db is missing. |
warn-scope.py | If an active OpenSpec exists, warns when editing a file not referenced in tasks.md. Surfaces scope creep without stopping work. |
These run automatically — no agent decision, no prompt engineering required.
Reliability properties
- Anti-hallucination. Reviewer findings need verbatim quotes from a fresh read. Agents grep for every name before using it. Files are re-read after 10+ turns of conversation; agents never cite their own prior output as evidence.
- Circuit breakers. 3-retry limit on fixes, 3-cycle limit on review loops.
- Feature inventory. Before editing any file, list its existing features and verify each is preserved.
- Scope-creep detection. The Debugger reviews its own diff after every fix and reverts unrelated changes.
- Risk-based classification. Auth, security, payments, and migrations always get Complex treatment regardless of file count.
These are not promises about correctness. They’re constraints designed to fail loudly when an agent is about to do something wrong.