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:**

```markdown

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

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

**If section exists, append row:**

```markdown
| {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
```