Dogfooding Workflow

CQ is built with CQ. Every feature ships through the same /pi → /plan → /run → /finish cycle that CQ exposes to users. This guide walks through that cycle from idea to merged commit.

Overview

/pi (Explore) → /plan (Design + Tasks) → /run (Parallel Workers) → /finish (Verify + Commit)

Each phase has a clear entry condition and a concrete output. No phase begins until the previous one produces its artifact.

Phase	Input	Output	Rule
`/pi`	Raw idea	`.c4/ideas/{slug}.md`	No code, no stack decisions
`/plan`	idea.md	`docs/specs/{slug}.md` + task queue	EARS requirements + DoD per task
`/run`	Task queue	Implemented, tested code	Workers in isolated worktrees
`/finish`	Working code	Committed, documented change	Integration review + smoke

/pi — Idea Exploration

/pi is a structured thinking mode. It helps you research, debate tradeoffs, and converge on a clear direction before any code is written.

What it does:

Searches the knowledge base for prior work on the topic
Generates competing approaches and forces explicit tradeoff analysis
Records the session as a knowledge entry so future sessions can build on it
Produces a concise idea document in .c4/ideas/

Example:

/pi "improve claim extraction quality"

After the session, .c4/ideas/improve-claim-extraction-quality.md contains:

markdown

## Problem
Claim extraction misses ~30% of implicit dependencies in large files.

## Options Considered
1. Increase chunk overlap (fast, marginal gain)
2. Tree-sitter AST pass before LLM extraction (accurate, slower)
3. Two-pass: coarse LLM → symbol resolver (balanced)

## Decision
Option 3. Coarse pass uses cheap model. Symbol resolver is deterministic.

## Risks
- Symbol resolver adds ~120ms per file on cold cache
- Needs language-server integration (Go, Python, TS only initially)

Key rule: /pi produces thinking, not code. No file paths, no library versions, no implementation details. If you catch yourself writing code during /pi, stop — that belongs in /plan or /run.

/plan — Design + Task Creation

/plan translates the idea into a concrete implementation plan with EARS requirements, architecture decisions, and a dependency-ordered task graph.

What it produces:

docs/specs/{slug}.md — full specification document
Tasks added to the queue, each with a DoD checklist and test strategy
Architecture Decision Records (DEC-XXX) for non-obvious choices

Spec structure:

markdown

## Requirements (EARS)
- WHEN a file is submitted, the system SHALL extract all explicit and implicit claims
- WHERE a symbol cannot be resolved, the system SHALL record a partial claim with `unresolved: true`

## Architecture
DEC-001: Two-pass extraction
  Rationale: Coarse LLM pass is cheap; resolver pass is deterministic and cacheable.
  Alternative rejected: Single-pass AST required language-server per language (high complexity).

## Tasks
- [ ] T-001: Add tree-sitter parser stub (DoD: parses Go + Python + TS, unit tests pass)
- [ ] T-002: Coarse LLM extraction (DoD: handles 10k token files, extracts >90% explicit claims)
- [ ] T-003: Symbol resolver integration (DoD: resolves local symbols, E2E test passes)
- [ ] T-004: Wire two-pass pipeline (DoD: integration test, smoke test against real codebase)

Running /plan:

/plan "improve-claim-extraction-quality"

CQ reads the idea file, interviews you on ambiguous requirements (if needed), and writes the spec. Tasks are added to the queue automatically.

To inspect the resulting queue:

cq status

Queue: 4 tasks (4 pending, 0 in-progress, 0 done)

T-001  Add tree-sitter parser stub          [pending]
T-002  Coarse LLM extraction               [pending]  ← T-001
T-003  Symbol resolver integration         [pending]  ← T-001
T-004  Wire two-pass pipeline              [pending]  ← T-002, T-003

/run — Parallel Execution

/run spawns worker agents in isolated git worktrees. Each worker claims one task, implements it, validates it, and submits. Workers run in parallel whenever the task graph allows.

What happens under the hood:

CQ reads the task graph and identifies tasks with no unmet dependencies
For each ready task, a worker agent is spawned in .claude/worktrees/{task-id}/
The worker implements the task following TDD: write failing test → implement → pass
On completion, the worker calls /finish internally to commit and merge back
CQ re-evaluates the graph and spawns new workers for newly unblocked tasks
Loop continues until the queue is empty

Starting /run:

/run

Or target a specific task:

/run T-002

Worker output (example):

[T-001] Spawning worker in worktrees/T-001...
[T-002] Waiting for T-001...
[T-003] Waiting for T-001...
[T-001] PASS: tree_sitter_test.go (3 tests)
[T-001] Merged. Unblocking T-002, T-003.
[T-002] Spawning worker in worktrees/T-002...
[T-003] Spawning worker in worktrees/T-003...
[T-002] PASS: extraction_test.go (12 tests)
[T-003] PASS: resolver_test.go (8 tests)
[T-002] Merged. T-004 still waiting for T-003.
[T-003] Merged. Unblocking T-004.
[T-004] Spawning worker in worktrees/T-004...
[T-004] PASS: integration_test.go (5 tests)
[T-004] Merged. Queue empty.

Worker limit: CQ enforces a maximum of 5 concurrent background workers. If all 5 slots are occupied, new workers queue until a slot opens. This prevents system overload on developer machines.

Contract tasks (TDD pipeline):

Tasks with a test_strategy: contract annotation follow a stricter pipeline:

Generate the failing test from the spec's DoD
Verify it fails for the right reason (not a compile error)
Implement until the test passes
No submission until go test (or equivalent) is green

/finish — Verify + Commit

/finish is the integration gate. It runs after all tasks are merged into the main branch, before the change is considered done.

Steps:

1. Integration Review

CQ scans all changes introduced since the plan was created and checks:

Does every task's DoD appear satisfied?
Are there any obvious gaps between the spec requirements and the implementation?
Is the change set coherent (no unrelated edits)?

2. Build + Test

go build ./... && go vet ./...
go test ./...

Build or vet failure blocks /finish. Tests with // +build integration tags are run if the INTEGRATION environment variable is set.

3. Wire Smoke (L2)

Four smoke scripts run against the local binary:

Script	What it checks
`wire-smoke.sh`	MCP tool registration, all expected tools present
`cf-smoke.sh`	Cloudflare Worker endpoints respond correctly
`edge-smoke.sh`	Edge function schema matches local types
`migration-lint.sh`	SQL migrations are idempotent and reversible

Any script exiting non-zero blocks /finish and prints a diff of what changed vs. what was expected.

4. Documentation Update

/finish checks whether the change affects:

Public API or CLI flags → updates docs/ accordingly
A behavior that differs from current documentation → flags it for manual review

5. Knowledge Recording

Key decisions and lessons from this cycle are recorded to the knowledge base:

cq_knowledge_record: "Two-pass claim extraction: coarse LLM + symbol resolver"
  tags: [claim-extraction, architecture, DEC-001]

Future /pi sessions on related topics will surface this automatically.

6. Git Commit

feat(extract): two-pass claim extraction with symbol resolver

Adds tree-sitter-based symbol resolution as a second pass after
coarse LLM extraction. Reduces missed implicit claims from ~30% to
~4% on the internal test corpus.

DEC-001: rejected single-pass AST approach (complexity, per-language LS required).

Conventional Commits format is enforced. Subject line under 72 characters. Body explains "why", not "what".

Team Areas and First Tasks

New contributors can pick any area and start with a /pi seed. The table below shows what experience to expect.

Area	/pi Seed	Expected Experience
Backend (Go)	`/pi "reduce p99 latency on knowledge_search"`	Work through profiling → hypothesis → targeted change cycle. Familiar if you've done Go pprof before.
Frontend (TypeScript)	`/pi "improve task status visibility in the TUI"`	Terminal UI work with Bubble Tea. Constraints are tight (80-char width, no color assumptions).
Install / CLI	`/pi "make cq init idempotent on re-run"`	Shell + Go flag parsing. High-impact, low surface area. Good first contribution.
Harness / Testing	`/pi "add contract test for cq_knowledge_record schema"`	Understand the MCP schema contract system. No domain knowledge required — spec is the source of truth.

Tips

Auto-implementation mode

Chaining phases is supported:

/pi "add rate limiting to hub job submissions" --plan --run

This runs /pi → /plan → /run sequentially without stopping for confirmation. Use when the idea is clear and you want CQ to drive. You can interrupt at any phase with Ctrl-C.

Worker count

The default is 3 concurrent workers. Override per session:

/run --workers 5

The hard cap is 5. Setting --workers above 5 is silently clamped.

Knowledge accumulation

Every /pi session records insights to the knowledge base under the dogfooding tag. Over time, CQ builds a map of which ideas led to which specs, which specs led to which bugs, and which bugs surfaced which design gaps. This loop is the primary source of CQ's self-improvement signal.

To query it:

"What have we learned about claim extraction?"

CQ calls cq_knowledge_search and returns ranked entries across all past sessions.

Dogfooding Workflow ​

Overview ​

/pi — Idea Exploration ​

/plan — Design + Task Creation ​

/run — Parallel Execution ​

/finish — Verify + Commit ​

1. Integration Review ​

2. Build + Test ​

3. Wire Smoke (L2) ​

4. Documentation Update ​

5. Knowledge Recording ​

6. Git Commit ​

Team Areas and First Tasks ​

Tips ​

Auto-implementation mode ​

Worker count ​

Knowledge accumulation ​