create-specs

What this skill does

# Create Specifications (GitHub Spec Kit Integration)

**Gear 3 of 6** in the Reverse Engineering to Spec-Driven Development process.

**Estimated Time:** 30 minutes (specs only) to 90 minutes (specs + plans + tasks)
**Prerequisites:** Gear 2 completed (`docs/reverse-engineering/` exists with 11 files)
**Output:** `.specify/` directory with GitHub Spec Kit structure

---

## Thoroughness Options

Gear 3 generates different levels of detail based on configuration set in Gear 1:

**Option 1: Specs Only** (30 min)
- `.specify/specs/NNN-feature-name/spec.md` for all features
- Constitution and folder structure
- Ready for manual planning with `/speckit.plan`

**Option 2: Specs + Plans** (45-60 min)
- Everything from Option 1
- Auto-generated `plan.md` for PARTIAL/MISSING features
- Ready for manual task breakdown with `/speckit.tasks`

**Option 3: Specs + Plans + Tasks** (90-120 min)
- Everything from Option 2
- Auto-generated `tasks.md` (300-500 lines each)
- Complete roadmap ready for immediate implementation

Configuration is set during Gear 1 (Analyze) via initial questionnaire, stored in `.stackshift-state.json`.

---

## Step 1: Load Configuration

Verify the state file exists and load execution parameters.

```bash
# Guard: state file must exist
if [ ! -f .stackshift-state.json ]; then
  echo "ERROR: .stackshift-state.json not found. Run Gear 1 (Analyze) first."
  exit 1
fi

# Load configuration
THOROUGHNESS=$(cat .stackshift-state.json | jq -r '.config.gear3_thoroughness // "specs"')
ROUTE=$(cat .stackshift-state.json | jq -r '.route // .path')
SPEC_OUTPUT=$(cat .stackshift-state.json | jq -r '.config.spec_output_location // "."')

echo "Route: $ROUTE"
echo "Spec output: $SPEC_OUTPUT"
echo "Thoroughness: $THOROUGHNESS"

# Determine execution flags
case "$THOROUGHNESS" in
  "specs")
    echo "Will generate: Specs only"
    GENERATE_PLANS=false
    GENERATE_TASKS=false
    ;;
  "specs+plans")
    echo "Will generate: Specs + Plans"
    GENERATE_PLANS=true
    GENERATE_TASKS=false
    ;;
  "specs+plans+tasks")
    echo "Will generate: Specs + Plans + Tasks (complete roadmap)"
    GENERATE_PLANS=true
    GENERATE_TASKS=true
    ;;
  *)
    echo "Unknown thoroughness: $THOROUGHNESS, defaulting to specs only"
    GENERATE_PLANS=false
    GENERATE_TASKS=false
    ;;
esac

# If custom output location, create .specify directory there
if [ "$SPEC_OUTPUT" != "." ]; then
  echo "Creating .specify/ structure at custom location: $SPEC_OUTPUT"
  mkdir -p "$SPEC_OUTPUT/.specify/specs"
  mkdir -p "$SPEC_OUTPUT/.specify/memory"
  mkdir -p "$SPEC_OUTPUT/.specify/templates"
  mkdir -p "$SPEC_OUTPUT/.specify/scripts"
fi
```

**Where specs are written:**

| Route | Config | Specs Written To |
|-------|--------|------------------|
| Greenfield | `spec_output_location` set | `{spec_output_location}/.specify/specs/` |
| Greenfield | Not set (default) | `./.specify/specs/` (current repo) |
| Brownfield | Always current | `./.specify/specs/` (current repo) |

Log: "PROGRESS: Configuration loaded. Route=$ROUTE, Thoroughness=$THOROUGHNESS."

---

## Step 2: Install GitHub Spec Kit Scripts

Install prerequisite scripts needed by `/speckit.*` commands downstream.

```bash
if [ -f ~/git/stackshift/scripts/install-speckit-scripts.sh ]; then
  ~/git/stackshift/scripts/install-speckit-scripts.sh .
elif [ -f ~/stackshift/scripts/install-speckit-scripts.sh ]; then
  ~/stackshift/scripts/install-speckit-scripts.sh .
else
  mkdir -p .specify/scripts/bash
  BASE_URL="https://raw.githubusercontent.com/github/spec-kit/main/scripts"
  curl -sSLf "$BASE_URL/bash/check-prerequisites.sh" -o .specify/scripts/bash/check-prerequisites.sh
  curl -sSLf "$BASE_URL/bash/setup-plan.sh" -o .specify/scripts/bash/setup-plan.sh
  curl -sSLf "$BASE_URL/bash/create-new-feature.sh" -o .specify/scripts/bash/create-new-feature.sh
  curl -sSLf "$BASE_URL/bash/update-agent-context.sh" -o .specify/scripts/bash/update-agent-context.sh
  curl -sSLf "$BASE_URL/bash/common.sh" -o .specify/scripts/bash/common.sh
  chmod +x .specify/scripts/bash/*.sh
fi
```

Verify: confirm `.specify/scripts/bash/check-prerequisites.sh` exists. Without these scripts, Gear 4 (Gap Analysis) will fail when running `/speckit.analyze`.

Log: "PROGRESS: Spec Kit scripts installed."

---

## Step 3: Generate Specifications (Automated Path)

Execute the automated reconciliation prompt to generate all specs with 100% feature coverage.

```bash
cat web/reconcile-specs.md
```

Use the output of this prompt to:
1. Parse `docs/reverse-engineering/functional-specification.md`
2. Extract EVERY feature (complete, partial, missing)
3. Generate `.specify/memory/constitution.md`
4. Create `.specify/specs/NNN-feature-name/spec.md` for ALL features
5. Create `plan.md` for PARTIAL/MISSING features

### Checkpoint: Verify Automated Path Succeeded

After running the reconciliation prompt, verify ALL of these:

```bash
# Check 1: Constitution exists
test -f .specify/memory/constitution.md && echo "OK: constitution.md exists" || echo "FAIL: constitution.md missing"

# Check 2: At least one spec exists
SPEC_COUNT=$(find .specify/specs -name "spec.md" -type f 2>/dev/null | wc -l)
echo "Spec count: $SPEC_COUNT"
if [ "$SPEC_COUNT" -eq 0 ]; then
  echo "FAIL: No specs generated"
fi
```

**IF both checks pass:** Log "PROGRESS: Automated spec generation succeeded. $SPEC_COUNT specs created." Continue to Step 4.

**IF either check fails:** Execute the manual fallback in `operations/manual-spec-generation.md`. Read that file and follow its Fallback Steps 1-5. Then continue to Step 4.

---

## Step 4: Generate Plans (Thoroughness Level 2+)

**IF GENERATE_PLANS is false:** Skip this step. Log "PROGRESS: Plan generation skipped (thoroughness=specs)."

**IF GENERATE_PLANS is true:** Read and execute `operations/plan-generation.md`. This dispatches parallel subagents to generate `plan.md` for every PARTIAL/MISSING feature.

### Checkpoint: Verify Plan Coverage

```bash
INCOMPLETE=$(grep -rl "PARTIAL\|MISSING" .specify/specs/*/spec.md 2>/dev/null | wc -l)
PLANS=$(find .specify/specs -name "plan.md" -type f 2>/dev/null | wc -l)
echo "Incomplete features: $INCOMPLETE, Plans generated: $PLANS"
```

Confirm plan count matches incomplete feature count. Report any gaps.

Log: "PROGRESS: Plan generation complete. $PLANS plans for $INCOMPLETE incomplete features."

---

## Step 5: Generate Tasks (Thoroughness Level 3 Only)

**IF GENERATE_TASKS is false:** Skip this step. Log "PROGRESS: Task generation skipped (thoroughness does not include tasks)."

**IF GENERATE_TASKS is true:** Read and execute `operations/task-generation.md`. This dispatches parallel subagents to generate comprehensive `tasks.md` for every planned feature.

### Checkpoint: Verify Task Quality

```bash
TASK_COUNT=$(find .specify/specs -name "tasks.md" -type f 2>/dev/null | wc -l)
echo "Task files generated: $TASK_COUNT"
```

Confirm task count matches plan count. Flag any tasks.md under 200 lines.

Log: "PROGRESS: Task generation complete. $TASK_COUNT task files generated."

---

## Step 6: Copy to Output Location (Greenfield Only)

**IF `spec_output_location` is "." (default):** Skip this step.

**IF `spec_output_location` is a different path:** Copy the generated `.specify/` directory to the target location.

```bash
if [ "$SPEC_OUTPUT" != "." ]; then
  cp -r .specify/* "$SPEC_OUTPUT/.specify/"
  echo "Copied .specify/ to $SPEC_OUTPUT/.specify/"
fi
```

Verify: confirm `$SPEC_OUTPUT/.specify/memory/constitution.md` exists at the target.

Log: "PROGRESS: Specs copied to $SPEC_OUTPUT."

---

## Step 7: Final Verification

Run all success criteria checks for the configured thoroughness level.

**All Levels:**
- [ ] `.specify/` directory exists
- [ ] `.specify/memory/constitution.md` exists and is non-empty
- [ ] `.specify/specs/NNN-feature-name/` directories exist for ALL features
- [ ] Each feature has `spec.md` with status markers (COMPLETE/PARTIAL/MISSING)
- [ ] `.specify/scripts/bash/check-prerequisites.sh`