technical-spec

name	technical-spec
description	Generate TECHNICAL_SPEC.md through guided Q&A. Use after /product-spec to define the technical architecture.
argument-hint	[--lean]
allowed-tools	Read, Write, Edit, AskUserQuestion, Grep, Glob, Bash, Agent

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

Situation	Action
PRODUCT_SPEC.md not found in plans/greenfield/ or project root	Stop and report "Run /product-spec first"
PROMPT.md not found at .claude/skills/technical-spec/PROMPT.md	Stop and report "Skill asset missing — reinstall toolkit or run /setup"
DEFERRED.md write fails (permissions or disk)	Output deferred items to terminal, warn user, continue with spec generation
Codex CLI invocation fails or times out	Log the error, skip cross-model review, proceed to Next Step

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