To Spec
Developmentto-specTo Spec is an Agent Skill for development published in the DanMcInerney/architect-loop repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Spec-writing stage skill for the architect factory: synthesizes the run's conversation, repo evidence, and research findings into `docs/spec/<run>.md` after grounding. Invoked by the strategist subagent the orchestrator dispatches during `/architect` intake — or directly by the orchestrator in `/architect-fast` (that skill's stage-skill deltas apply) — before decomposition into issues.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/DanMcInerney/architect-loop/blob/HEAD/skills/to-spec/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/to-spec, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
To Spec
Synthesize the spec from what grounding, intake, and research evidence already surfaced; do not interview. Anything genuinely unanswered goes through step 4.
Process
- Read the codebase-design
vocabulary (
skills/codebase-design/SKILL.md) before writing a line. Reuse its module, interface, seam, adapter, depth, and locality terms exactly; never substitute component, service, boundary, or API for module or interface. - Name the seam(s) this run will exercise before drafting any section.
Existing seams are preferred to new ones, at the highest point possible;
the ideal number is one. Record them under
## Implementation decisions. - Do not include specific file paths or code snippets in the spec body — they may end up being outdated very quickly. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts.
- Never run the timed-ruling protocol yourself or wait on the human:
return every open question to the orchestrator, one line each —
RULING NEEDED: <question> | options: <a | b> | default: <option> — <why>— and it runs the protocol (skills/architect/SKILL.md## Timed-ruling protocol). Rulings already present in your dispatch context are decided; record each as an## Assumptionsentry. (Direct orchestrator invocation only —/architect-fast: run the protocol yourself as that lane records.) - Shape the spec on the template below and write it to
docs/spec/<run>.mdin your working tree. Do NOT commit it and do NOT create or update the tracking issue — the spec commit and the tracking-issue update (spec pointer, assumptions digest, or the markdown-mode equivalent inskills/architect/tracker.md## Command mapping) are orchestrator actions after you return. End your reply withSPEC DRAFT: <path>plus anyRULING NEEDED:lines.
Template
Write the sections below in this order; the names are load-bearing for hardening and decomposition, so keep them exact.
## Goal— what the run adds and why, from the reader's side.## Target flow(optional) — a short numbered sequence, only when the run reorders or replaces a multi-step process; omit for additive or single-surface runs.## Non-goals— what the run deliberately leaves unchanged.## Assumptions— every timed-ruling default this run applied, one line each, dated.## Implementation decisions— modules, interfaces, and the seam(s) from step 2, described, never pathed; the one place a prototype snippet may appear, per step 3.## Validation strategy— how the run's own checks and the closing review confirm the seam(s) hold; name the check-runner and closing review, never new grading machinery.## Domain language— new or changed vocabulary this run introduces, defined once.## Open human decisions— anything unresolved once the timed-ruling protocol's timer expires; empty at freeze.## Verified facts— every claim sourced outside this conversation: source, date fetched, fact supported.## Preflight evidence— tool, auth, and repo-state evidence gathered before decomposition.