technical-spec

Generate a technical specification document for the current project.

Workflow

Copy this checklist and track progress:

Technical Spec Progress:
- [ ] Step 1: Directory guard
- [ ] Step 2: Project root confirmation
- [ ] Step 3: Plan status guard
- [ ] Step 4: Check prerequisites (plans/​greenfield/​PRODUCT_SPEC.md)
- [ ] Step 5: Check for existing plans/​greenfield/​TECHNICAL_SPEC.md
- [ ] Step 6: Conduct guided Q&A with user
- [ ] Step 7: Cross-verify against PRODUCT_SPEC.md
- [ ] Step 8: Update plans/​PLAN_STATUS.md
- [ ] Step 9: Handle deferred decisions
- [ ] Step 10: Review and refine with user
- [ ] Step 11: Suggest next step (/​generate-plan)

Lean Mode (--lean)

When --lean is passed:

• Web research runs in background: Launch all WebSearch research as background Agent calls (run_in_background: true). Continue the Q&A without waiting. When results arrive, only interrupt the flow if a finding would materially change a recommendation (e.g., a critical production issue with a chosen technology, a clearly superior alternative, a deprecation or breaking change). Skip routine benchmark comparisons and ecosystem summaries.
• Skip all post-generation gates. Do not run /​verify-spec, /​codex-consult, or /​criteria-audit. Report each as LEAN_SKIP in the output.

Directory Guard

1. If .toolkit-marker exists in the current working directory → STOP: "You're in the toolkit repo. Run this from your project directory instead: cd ~/​Projects/​your-project && /​technical-spec"

Project Root Confirmation

Before generating any files, confirm the output location with the user:

Will write TECHNICAL_SPEC.md to: {absolute path of cwd}/​plans/​greenfield/
Continue? (Yes / Change directory)

If the user says "Change directory", ask for the correct path and instruct them to cd there first.

Plan Status Guard

Read ~/​.claude/​skills/​shared/​PLAN_STATUS.md before writing files.

1. Ensure plans/ exists.
2. Read plans/​PLAN_STATUS.md if it exists.
3. If another path is listed as Current plan with Current status: active, ask whether the greenfield plan supersedes it, should remain non-current, or should abort.
4. If plans/​PLAN_STATUS.md is missing, create it after writing the technical spec.
5. If this technical spec replaces an existing technical direction, archive a greenfield snapshot under plans/​archive/​YYYYMMDD-HHMMSS-greenfield/ before overwriting downstream files.

Prerequisites

• Check for plans/​greenfield/​PRODUCT_SPEC.md first.
• If it does not exist, fall back to legacy PRODUCT_SPEC.md in the current directory.
• If the legacy root file is used, copy it to plans/​greenfield/​PRODUCT_SPEC.md before continuing so the project adopts the canonical layout.
• If neither exists: "PRODUCT_SPEC.md not found. Run /​product-spec first."

Existing File Guard (Prevent Overwrite)

Before asking any questions, ensure plans/​greenfield/ exists, then check whether plans/​greenfield/​TECHNICAL_SPEC.md already exists.

• If it does not exist: continue normally.
• If it exists: STOP and ask the user what to do:
  1. Archive then overwrite (recommended): copy the existing greenfield plan set to plans/​archive/​YYYYMMDD-HHMMSS-greenfield/, mark the archived snapshot as superseded when practical, then write the new document to plans/​greenfield/​TECHNICAL_SPEC.md
  2. Overwrite: replace plans/​greenfield/​TECHNICAL_SPEC.md with the new document
  3. Abort: do not write anything; suggest they rename/​move the existing file first

Process

Read .claude/​skills/​technical-spec/​PROMPT.md and follow its instructions exactly:

1. Read plans/​greenfield/​PRODUCT_SPEC.md as input
2. Work through each question category (Architecture, Stack, Data, APIs, Implementation)
3. Make recommendations with confidence levels
4. Generate the final TECHNICAL_SPEC.md document

Output

Write the completed specification to plans/​greenfield/​TECHNICAL_SPEC.md.

Update plans/​PLAN_STATUS.md so:

• Current plan is plans/​greenfield/
• Current type is greenfield
• Current stage is technical-spec
• Current status is active
• the history table records any archived or superseded plan snapshot

Post-Generation Gates (MANDATORY unless --lean)

These gates MUST execute before you produce the "Next Step" output. The output template requires results from each gate. Reporting SKIPPED without --lean is a skill violation — go back and run the gate.

Gate 1: Spec Verification

After writing plans/​greenfield/​TECHNICAL_SPEC.md, run the spec-verification workflow:

1. Read .claude/​skills/​spec-verification/​SKILL.md for the verification process
2. Verify context preservation: Check that all key items from PRODUCT_SPEC.md appear in TECHNICAL_SPEC.md
3. Run quality checks for vague language, missing rationale, undefined contracts
4. Present any CRITICAL issues to the user with resolution options
5. Apply fixes based on user choices
6. Re-verify until clean or max iterations reached

IMPORTANT: Do not proceed to Gate 2 until verification passes or user explicitly chooses to proceed with noted issues.

Deferred Requirements Capture (During Q&A)

IMPORTANT: Capture deferred requirements interactively during the Q&A process, not after.

When to Trigger

During the Q&A, watch for signals that the user is deferring a technical decision:

• "out of scope"
• "not for MVP" / "post-MVP"
• "v2" / "future version"
• "premature optimization"
• "over-engineering" / "overkill"
• "later" / "eventually"
• "we'll skip that for now"
• "keep it simple for now"

Capture Flow

When you detect a deferral signal, immediately use AskUserQuestion:

Question: "Would you like to save this to your deferred requirements?"
Header: "Defer?"
Options:
  - "Yes, capture it" — I'll ask a few quick questions to document it
  - "No, skip" — Don't record this

If user selects "Yes, capture it":

Ask these clarifying questions:

1. What's being deferred? "In one sentence, what's the technical decision or feature?" (Pre-fill with your understanding from context)

2. Why defer it? Options: "Premature optimization" / "Over-engineering for MVP" / "Needs more research" / "V2 feature" / "Other"

3. Notes for later? "Any technical context that will help when revisiting this?" (Optional — user can skip)

Write to DEFERRED.md Immediately

After collecting answers, append to DEFERRED.md right away.

If this is the first technical spec entry, add a new section:

## From plans/​greenfield/​TECHNICAL_SPEC.md ({date})

| Requirement | Reason | Notes |
|-------------|--------|-------|
| {user's answer} | {selected reason} | {notes or "—"} |

If section exists, append row:

| {user's answer} | {selected reason} | {notes or "—"} |

Continue Q&A

After capturing (or skipping), continue the spec Q&A where you left off.

Gate 2: Cross-Model Review

After verification passes, run cross-model review if Codex CLI is available:

1. Check if Codex CLI is installed: codex --version
2. If available, run /​codex-consult with upstream context
3. Present any findings to the user before proceeding

Consultation invocation:

/​codex-consult --upstream plans/​greenfield/​PRODUCT_SPEC.md --research "{detected technologies}" plans/​greenfield/​TECHNICAL_SPEC.md

If Codex finds issues:

• Show critical issues and recommendations
• Ask user: "Address findings before proceeding?" (Yes/​No)
• If Yes: Apply suggested fixes
• If No: Continue with noted issues

If Codex CLI is not installed or not authenticated: Report UNAVAILABLE (not SKIPPED — the distinction matters).

Error Handling

Next Step

Pre-condition: All gates above have completed, or --lean was explicitly passed. If you have not run them, STOP and run them now. Reporting SKIPPED without --lean is a skill violation.

When complete, inform the user:

TECHNICAL_SPEC.md created and verified at ./​plans/​greenfield/​TECHNICAL_SPEC.md

Verification: PASSED | PASSED WITH NOTES | NEEDS REVIEW | LEAN_SKIP
Cross-Model Review: PASSED | PASSED WITH NOTES | UNAVAILABLE | LEAN_SKIP
Deferred Requirements: {count} items captured to DEFERRED.md

Next: Run /​generate-plan