implement

What this skill does

# Implement from Spec (with GitHub Spec Kit)

Step 6 of 6 in the Reverse Engineering to Spec-Driven Development process.

## Directory Convention

All artifact paths use a single convention:
- `specs/` -- canonical location for all specifications and implementation plans
- `docs/gap-analysis-report.md` -- phased implementation roadmap
- `.stackshift-state.json` -- session state and progress tracking

---

## Context Routing

Determine execution context before proceeding.

Run `git branch --show-current` to get the current branch name.

**If the branch is `main` or `master`:** Execute Context A (Handoff). Read `operations/handoff.md` and follow the handoff procedure.

**If the branch matches pattern `NNN-*` (e.g., `002-feature-name`):** Execute Context B (Standard Implementation). Proceed to the Process Overview below.

**If neither pattern matches:** Ask the user which context applies -- are they starting fresh from reverse engineering (Context A) or working on an existing feature (Context B)?

The handoff (Context A) happens only once after initial reverse engineering. After that, always use Context B on feature branches.

---

## Process Overview (Context B: Standard Implementation)

### Step 1: Review Implementation Roadmap

Read `docs/gap-analysis-report.md` and identify the phased plan:
- Phase 1 (P0 Critical) -- essential features, security fixes, blocking issues
- Phase 2 (P1 High Value) -- important features, high user impact
- Phase 3 (P2/P3) -- nice-to-have, future enhancements

Confirm with the user:
- Start with Phase 1 (P0 items)?
- Any blockers to address first?
- Time constraints?

Report: "Starting Phase [X]. [Y] features to implement. First feature: [name]."

### Step 2: Generate Tasks for Current Feature

Run `/speckit.tasks [feature-name]` to generate actionable tasks from the implementation plan.

This reads `specs/[feature-name].md`, breaks down the plan into specific tasks, and creates a task checklist.

**If `/speckit.tasks` fails:** Read `operations/error-recovery.md` and follow the `/speckit.tasks` recovery procedure.

### Step 3: Implement Feature

Run `/speckit.implement [feature-name]` to execute the implementation plan.

This command:
1. Loads tasks from the `/speckit.tasks` output
2. Walks through each task systematically
3. Generates code for each task
4. Tests against acceptance criteria
5. Updates specification status markers
6. Commits changes with descriptive messages

Review all generated code before committing. Do not blindly accept generated output.

**If `/speckit.implement` fails or partially completes:** Read `operations/error-recovery.md` and follow the `/speckit.implement` recovery procedure.

### Step 4: Validate Implementation

Run `/speckit.analyze` to verify the implementation.

This checks:
- Implementation matches the specification
- All acceptance criteria are met
- No inconsistencies with related specs
- Status markers are accurate

**If `/speckit.analyze` reports issues:**
- If the implementation is incomplete (missing feature), fix the implementation to match the spec.
- If the spec is outdated (requirements changed during implementation), update the spec first, then re-run `/speckit.analyze`.
- If uncertain, ask the user which should be the source of truth.

Repeat validation until `/speckit.analyze` reports no issues.

**If `/speckit.analyze` fails:** Read `operations/error-recovery.md` and follow the `/speckit.analyze` recovery procedure.

### Step 5: Update Progress and Commit

After each feature:

1. Run `/speckit.analyze` to confirm feature status (X/Y features complete).
2. Mark the feature as complete in `docs/gap-analysis-report.md`.
3. Update `.stackshift-state.json` with current phase and feature progress.
4. Commit: `git commit -m "feat: implement [feature-name] ([spec-file].md)"`
5. Report: "Phase [X]: [completed]/[total] features complete. Next: [feature-name]."

### Step 6: Iterate Until Complete

Repeat Steps 2-5 for each feature in the roadmap.

**Priority checkpoint after all P0 features complete:** Pause and report status to the user. Confirm before proceeding to P1. Example: "Phase 1 complete ([N] P0 features implemented). Ready to start Phase 2 ([M] P1 features). Proceed?"

**Priority checkpoint after all P1 features complete:** Pause and report status. Confirm before proceeding to P2/P3.

**Iteration bound:** If more than 20 features need implementation, pause after every 5 features and report cumulative progress to the user.

---

## Progress Tracking

After each feature implementation cycle, report progress in this format:

```
Phase [X]: [completed]/[total] features complete.
Overall: [total_completed]/[total_all] features ([percentage]%).
Current feature: [COMPLETE/FAILED].
Next: [next-feature-name].
```

Update `.stackshift-state.json` after each feature so sessions can resume from the correct point.

On session resume, read `.stackshift-state.json` to determine the current phase and which feature to continue with.

---

## Post-Implementation

After all features are implemented:
1. Read `operations/post-implementation.md` and follow the validation, review, and coverage mapping procedures.
2. Report the final status to the user.

For ongoing development workflows (new features, refactoring, bug fixes), read `operations/continuous-development.md`.

---

## Success Criteria

After this skill completes:
- All P0 features implemented (Phase 1 complete)
- All P1 features implemented (Phase 2 complete)
- P2/P3 features implemented or intentionally deferred
- All specifications in `specs/` marked COMPLETE
- `/speckit.analyze` reports no issues
- All tests passing
- `.stackshift-state.json` updated with final status