Turn uncertain requests into approved specs and controlled code

Turns an uncertain software request into a frozen specification, controlled multi-agent implementation, and evidence-backed acceptance, keeping five durable documents as the source of truth instead of the chat transcript: PRD.md (why and what - scope, user behavior, business rules, assumptions), TECH_DESIGN.md (how - architecture, contracts, data, operations, security), ACCEPTANCE.md (observable pass/fail criteria and required evidence), AGENT_PLAN.md (who does approved implementation work, with explicit file ownership), and LOOP.md (current recoverable execution state and an append-only attempt history). Before asking the user anything, it inspects the actual system - AGENTS.md, existing specs, architecture, interfaces, database, tests, and code conventions - and resolves every discoverable fact itself, reserving user questions for genuine product decisions or consequential technical tradeoffs.

Unresolved decisions are worked as a dependency tree: each round picks one to three independent "frontier" questions the user can answer right now, states why each matters with concrete options, an impact per option, and a recommendation with rationale, then immediately updates the PRD and its decision log and recomputes the frontier - never dumping a backlog of dependent questions. Core product behavior, data ownership, permission/security behavior, migrations, payments, destructive actions, and anything that changes final acceptance can never be silently assumed; they stay explicit blockers until answered. The same frontier method grills consequential technical choices for TECH_DESIGN.md once product behavior is settled. ACCEPTANCE.md then gives every criterion a stable AC-xxx ID linked to one or more FR-xxx requirement IDs, covering happy paths, boundaries, permissions, failure/recovery, idempotency, concurrency, and regression - explicitly rejecting subjective criteria like "good performance" or "mostly works" in favor of evidence such as a test result, an API response, database state, logs, or a precise manual check. Production code cannot start until the user has explicitly approved the frozen specification, scope, and acceptance contract for a specific, named implementation.

Only after that approval does AGENT_PLAN.md split work into independently verifiable vertical slices with explicit allowed/forbidden file paths per task, frozen shared interfaces and schemas before any parallel work, and serialized handling for anything with overlapping ownership - multiple agents are used only when tasks are genuinely independent, never to display parallelism. A subagent's completion report is evidence, not acceptance: the main agent alone owns integration and the final judgment, comparing the actual diff and behavior against the frozen specification, running the highest feasible end-to-end validation, and producing an acceptance matrix (Acceptance ID | Result | Evidence | Defect/Caveat) with exactly one of four allowed verdicts (ACCEPTED, ACCEPTED_WITH_CAVEATS, CHANGES_REQUESTED, BLOCKED) - missing evidence for a blocking criterion is always a failure, regardless of what a subagent or a passing unit test claims. If the same acceptance criterion fails judgment three consecutive times, automatic rework stops and the user is asked to choose redesign, a scope change, an accepted limitation, or termination of that part, rather than letting the loop grind indefinitely.

Use it for new products, medium-to-large features, cross-module changes, or any request that genuinely needs a PRD/technical design, active clarification, multi-agent execution, or an independent main-agent judge. Do NOT use it for a small single-file change, a tiny bug fix, code explanation, review-only or diagnostic work, pure research, or a task whose specification is already complete - the overhead isn't worth it there.

Input is the user's initial request plus whatever the agent can discover by inspecting the existing codebase, conventions, and any prior frozen specs. Output is the five living documents above, kept in the repository's established documentation location (or docs/spec-driven/<feature-slug>/ otherwise), each owning a distinct set of facts referenced by stable IDs elsewhere rather than duplicated. A minimal invocation: $spec-driven-loop Build a multi-tenant job dashboard with role-based access and evidence-backed acceptance.

Designed around Codex-style multi-agent delegation, where the main agent assigns subagents a strict task contract (objective, linked FR/AC IDs, allowed/forbidden paths, required evidence, explicit stop-and-report conditions) and requires a matching completion-report format for comparable integration evidence. Its requirements-grilling stage is explicitly built on Matt Pocock's MIT-licensed grill-me/grilling decision-tree and frontier method.

Teams and orchestrating agents running medium-to-large feature work who want a frozen, evidence-backed contract between product intent, technical design, and acceptance before committing implementation effort or delegating to multiple subagents. Self-authored by Linji-x under the MIT license, added 2026-08-25.