specs

<supported_workflows>

This skill supports four workflows. The primary workflow uses the forgectl scaffold to generate specs from plans. The other three are reference methodologies for spec maintenance and review — they operate independently of forgectl.

</supported_workflows>

<step_preflight> Domain Verification

Run forgectl domains before authoring the spec queue. Every queue entry must reference a declared domain and its file must live under <path>/specs/ — a mismatch causes init to reject. If domains are missing or wrong, edit .forgectl/config now; config is locked at init time.

For multi-subsystem projects with no domains configured, add [[domains]] entries before proceeding. See getting_started/references/domains-and-specs.md.

</step_preflight>

<step_0> Search — Identify Specs to Write

The user provides a plan (plan.json or equivalent). Use the sub-agent prompt in references/search-specs-for-specifying.md to analyze the plan and produce a spec queue JSON file.

The spec queue lists every specification that must be written or revised, with topics of concern, domains, file paths, planning source references, and dependency ordering.

See: references/search-specs-for-specifying.md </step_0>

<step_1> Init — Start the Forgectl Session

Feed the spec queue JSON to forgectl:

forgectl init --phase specifying --from <spec-queue.json>

This creates forgectl-state.json and sets the state to ORIENT. All batch sizes, round limits, and guided settings are configured in .forgectl/config (TOML).

Run forgectl status to see the full session overview.

See: references/forgectl-state-schema.md See: references/forgectl-state-example.json </step_1>

<step_2> Loop — Follow the State Machine

For each spec in the queue, follow the forgectl state machine:

2a. ORIENT — Read the planning sources and any existing specs. Understand what exists before writing. 2b. SELECT — Pull the next spec from the queue. If guided, discuss scope with the user. 2c. DRAFT — Write the spec file following the format in ../shared/spec-format.md. Advance with forgectl advance (optionally --file <path> to override the output path). 2d. EVALUATE — Spawn an Opus sub-agent to adversarially review the draft. Record the verdict with forgectl advance --verdict PASS|FAIL --eval-report <path>. 2e. REFINE — If evaluation failed, fix the deficiencies and advance back to EVALUATE. 2f. ACCEPT — Spec finalized. Forgectl loops to ORIENT for the next spec, or moves to DONE when the queue is empty.

Use forgectl status at any point to see current state and what action is needed.

See: ../shared/spec-format.md </step_2>

<step_3> Reconcile — Cross-Spec Consistency

After all individual specs in a domain are accepted, forgectl enters per-domain cross-referencing. After all domains are cross-referenced, it enters cross-domain reconciliation:

3a. CROSS_REFERENCE — After the last batch for a domain is accepted, cross-reference ALL specs in that domain (session specs and existing specs). Spawn sub-agents to review. 3b. CROSS_REFERENCE_EVAL — Sub-agent evaluates intra-domain cross-reference consistency. 3c. CROSS_REFERENCE_REVIEW — Review cross-reference eval. Add specs or set code search roots for the domain. Then proceed to the next domain or DONE. 3d. RECONCILE — After all domains pass cross-referencing, fix cross-references across all specs and all domains. Stage the changes. 3e. RECONCILE_EVAL — Spawn a sub-agent to evaluate cross-domain consistency from git diff --staged. 3f. RECONCILE_REVIEW — Human reviews the reconciliation eval. Accept or grant another pass.

Reconciliation checklist:

• Every Depends On reference points to a spec that exists
• Every Depends On entry has a corresponding Integration Points row in the referenced spec
• Integration Points are symmetric: if A mentions B, B mentions A
• Spec names are consistent across all references (no aliases or stale names)
• No circular dependencies in the Depends On graph
• The Implements section in each spec names the correct planning topics </step_3>

<step_4> Complete

After reconciliation passes, the session is complete. If the workflow continues to a planning or implementing phase, forgectl transitions via PHASE_SHIFT. </step_4>

<contextual_information>

Spec File Naming and Placement

Convention: kebab-case, no suffix.

• Place specs in <project>/specs/ adjacent to the project's source code
• Name reflects the topic of concern, not the planning document it came from
• Protocol specs go in protocols/<name>/specs/

<domain>/
├── src/
├── specs/
│   ├── reservation-booking.md
│   └── ledger-reconciliation.md
└── ...

Scoping Multi-Responsibility Plans

When a planning document bundles multiple responsibilities:

1. Identify distinct topics — each one must pass the Topic of Concern test. See ../shared/topic-of-concern.md.
2. Write explicit scope exclusion notes in each spec's Context section.
3. Cross-reference via Integration Points so readers can trace the full picture.

Eval Output Convention

Evaluation sub-agents write output to:

<project>/specs/.eval/
├── <spec-name>-r1.md
├── <spec-name>-r2.md
├── reconciliation-r1.md
└── ...

Add .eval/ to .gitignore if eval output should not be committed.

</contextual_information>

Plans are read-only

Planning documents are input, not output. Never modify, delete, or annotate them.

No planning references in specs

Do not reference planning file paths in the spec. The Implements section may name the planning topic but not the file location.

No open questions in specs

If something is unresolved, it does not go in the spec. Exclude it or resolve it.

Split rather than overload

If a topic is too broad, produce multiple spec files. Each must pass the Topic of Concern test. See ../shared/topic-of-concern.md.

Track upstream spec impacts

When generating a spec, identify any existing specs that need updates due to new integration points or dependencies. Note these in the ACCEPT phase.

The architect decides

Resolve open questions by reading plans carefully and making judgment calls. Document decisions in the spec's edge cases and rationale sections.

Specs are technology-aware, not technology-coupled

Reference technology when it's part of the interface contract. Don't prescribe internal implementation choices.

<anti_patterns>

</anti_patterns>

<common_eval_findings>

These patterns are found repeatedly during evaluation. Avoid them during drafting:

• Phantom Observability Entries — Logging section references a behavior (e.g., "parsing retry") that no Behavior section defines. Every log entry must correspond to a defined behavior step or error handling path.
• Unverifiable Invariants — An invariant describes intent rather than a verifiable system property. Invariants must be testable. If you can't write a Given/When/Then for it, demote it to an edge case.
• Missing Observability Section — Every spec with behaviors that can fail needs at minimum INFO for success, ERROR for failures, and DEBUG for diagnostics.
• Untested Invariants — Every invariant needs a Given/When/Then test. If you can't test it, it's not an invariant.
• Internal Architecture as Invariants — Don't prescribe concurrency strategy or internal data structures as invariants. Reformulate as externally observable properties.
• Silent Omissions — Every item from the planning source must appear in the spec (covered), in a scope exclusion note (excluded with rationale), or marked as out of scope (belongs to another spec).

</common_eval_findings>

<checklist_before_finalizing>

• Topic of concern passes the test in ../shared/topic-of-concern.md
• Declarative voice throughout (no "should", "could", "might")
• Every behavior has testing criteria (Given/When/Then)
• Error handling is exhaustive — every failure mode named
• Edge cases capture judgment calls
• Invariants are always-true properties, not postconditions
• No references to planning file paths
• No open questions
• File is kebab-case, placed in correct project's specs/ directory
• Spec follows spec-format.md structure
• Passed evaluation sub-agent review (or user accepted after max rounds)

</checklist_before_finalizing>

<IMPORTANT_INFO> 99999. Implement functionality completely. No placeholders, no stubs. 999999. When a planning document bundles multiple responsibilities, split into multiple specs — each with its own topic of concern. 9999999. Every item from the planning source must be accounted for: covered in the spec, explicitly excluded with rationale, or marked out of scope. 99999999. Use the forgectl scaffold to manage state. Run forgectl status to see what action is needed next. </IMPORTANT_INFO>