Spec-Driven Development

The big picture: A spec turns a rough idea into durable, reviewable artifacts — requirements.md, design.md, and tasks.md — and then into working code. Each phase has a human approval gate, every task can be dispatched to an agent, and every step is recorded with who did it and when.

Why it matters: Chat is great for exploration, but large features need structure that survives across sessions and people. A spec is the shared, versioned source of truth: what we're building, how, the ordered task list, and the full history of decisions.

Spec vs. Plan

Use a Plan for a focused change you'll finish in one sitting. Use a Spec when the work spans multiple sessions, people, or waves of parallel tasks — and you want an auditable trail.

File layout

Specs live in your repository so they review and version like code:

.cfactory/specs/<feature>/
  requirements.md   # what & why (user stories, EARS acceptance criteria)
  design.md         # how (architecture, components, trade-offs)
  tasks.md          # ordered checklist with dependencies
  meta.yaml         # owner + provenance (service-owned, never LLM-edited)
  history.jsonl     # append-only event log (service-owned)

bugfix specs use a single bugfix.md in place of requirements/design.

The workflow

1. Create a spec (kind: feature, bugfix, or quick). CFactory seeds the templates and sets you as the owner.
2. Requirements → Design → Tasks. The spec agent fills each artifact, then calls the question tool asking you to Approve or Revise. Nothing advances without your gate.
3. Implement. Run tasks — one at a time, or the next wave of independent tasks in parallel.

quick specs skip the gates and generate all artifacts in one pass, for small, well-understood work.

The task graph and waves

tasks.md is a normal Markdown checklist. CFactory derives an execution order from it:

- [ ] 1. Add the HTTP endpoint
  - [x] 1.1 Define the schema
  - [~] 1.2 Wire the handler
- [P] 2. Build the TUI list        # [P] = safe to run in parallel
- [ ] 3. Wire the IDE view
  - _Depends: 1, 2_                 # explicit dependency edge
  - _Requirements: 1.2_             # traceability back to requirements
  - _Optional_                      # excluded from "run all"

• Checkbox state maps to status: [ ] pending, [~] in progress, [x] done.
• Nested items depend on their parent; _Depends:_ adds explicit edges.
• CFactory groups tasks into waves — each wave is a set of tasks with no unmet dependencies, so they can run together.

Running waves & background dispatch

When you run a task, CFactory dispatches a worker session. Choose the isolation:

• inline — runs in the current context.
• background — a detached agent session you can monitor while you keep working.
• worktree — an isolated git worktree, ideal for parallel waves that touch overlapping files.

As workers finish, CFactory flips the checkboxes in tasks.md and records the result.

Owner & history

Every spec has an owner, and every meaningful action is appended to history.jsonl: spec created, phase approved/revised (with your comment), owner changed, task dispatched, task completed. The actor is resolved in priority order — your signed-in CFactory account, then your git identity, then the dispatching agent, then the local host — so the log answers "who validated this phase?" and "who ran this task?" at a glance.

In the IDE

Open Specs from the CFactory sidebar toolbar. You get:

• A list of specs with phase, task progress, and owner.
• A detail panel with the phase stepper, task tree, wave breakdown, live workers, and recent history.
• Actions to Approve / Request revision on the current gate, Run the next wave, and Abort a running worker.

The view is powered by the same backend as the CLI, so status stays in sync — checkbox and phase changes on disk are reflected live.

In the CLI

The same spec is available from a terminal:

cfactory spec list                              # table of specs
cfactory spec new --kind feature --title "Checkout flow"
cfactory spec show checkout-flow                # phase stepper, task tree, waves, history
cfactory spec run checkout-flow                 # dispatch the next wave
cfactory spec run checkout-flow --task 1.2 --isolation worktree
cfactory spec history checkout-flow --type phase.approved

Add --json to any read command to script against the raw data.

Customizing templates & the spec agent

The artifact templates and the per-phase agent prompts resolve through a layered overlay, each layer overriding the one before it:

1. Built-in defaults shipped with CFactory.
2. User global — your personal overrides.
3. Organization — policies published to your org (may lock templates/prompts so projects can't override them).
4. Project — files under .cfactory/spec/templates/ and .cfactory/spec/prompts/ in the repo.

Instructions append across layers (user → org → project). When an org locks a template, project and user files for it are ignored and the resolved source is marked org.