Implementation Guide

February 4, 2026 · View on GitHub

This guide provides detailed instructions for executing implementation plans created via /shep-kit:plan.

Prerequisites: Completed plan.md and tasks.md in specs/NNN-feature-name/

Overview

Implementation follows a strict discipline:

TDD MANDATORY - RED → GREEN → REFACTOR for all code phases
Frequent Progress Updates - Update tasks.md as you work
Phase-by-Phase CI Validation - Watch CI after each phase, fix-loop until green
Never skip phases - Each phase builds on the previous one

The Implementation Loop

┌─────────────────────────────────────────────┐
│ For Each Phase in tasks.md:                │
│                                             │
│  1. Work through RED-GREEN-REFACTOR         │
│  2. UPDATE tasks.md checkboxes FREQUENTLY   │
│  3. Commit phase completion                 │
│  4. Push to remote                          │
│  5. Watch CI (gh run watch --exit-status)   │
│  6. IF CI fails: Fix-Commit-Push-Watch      │
│  7. ONLY proceed when CI passes             │
└─────────────────────────────────────────────┘

Phase Execution: Step-by-Step

Before Starting Phase

Read the phase tasks in tasks.md
Understand dependencies - What does this phase build on?
Review TDD structure - What tests come first?

During Phase: TDD Cycle (For Code Phases)

RED: Write Failing Tests First

# Example: Domain entity tests
pnpm test:watch  # Start watch mode

# Write test first (it will fail - that's expected!)
# tests/unit/domain/entities/feature.test.ts

CRITICAL: As soon as you write a test:

Run pnpm test to confirm it fails
Update tasks.md immediately:
```
- [x] Write unit test: feature.test.ts
```

Commit the test:

git add tests/unit/domain/entities/feature.test.ts specs/NNN-feature-name/tasks.md
git commit -m "test(domain): add failing test for Feature entity (RED phase)"

GREEN: Minimal Implementation

# Write minimal code to pass the test
# src/domain/entities/feature.ts

CRITICAL: As soon as the test passes:

Run pnpm test to confirm it passes
Update tasks.md immediately:
```
- [x] Implement Feature entity
```

Commit the implementation:

git add src/domain/entities/feature.ts specs/NNN-feature-name/tasks.md
git commit -m "feat(domain): implement Feature entity (GREEN phase)"

REFACTOR: Clean Up

# Improve code structure, extract helpers, etc.
# Keep tests running (pnpm test:watch)

CRITICAL: After refactoring:

Ensure pnpm test still passes

Update tasks.md immediately:

- [x] Refactor Feature entity for clarity

Commit the refactor:

git add src/domain/entities/feature.ts specs/NNN-feature-name/tasks.md
git commit -m "refactor(domain): improve Feature entity structure (REFACTOR phase)"

After Phase: CI Validation Loop

MANDATORY: Every phase completion MUST follow this workflow.

1. Final Phase Commit

# If you haven't committed recently, do a final phase commit
git add .
git commit -m "feat(scope): complete phase N - <brief description>"

2. Push to Remote

git push

3. Watch CI Immediately

# Get the run ID and watch
gh run watch --exit-status

CRITICAL: You MUST wait for CI to complete. Don't move to the next phase!

4. If CI Passes ✅

Move to the next phase. Update tasks.md:

### Phase 2: Domain Layer (TDD Cycle 1) ✅

**RED (Write Failing Tests First):**

- [x] Write unit test: feature.test.ts

...

5. If CI Fails ❌

Enter Fix Loop - Do NOT proceed to next phase:

# Step 1: Get failure logs
gh run view <run-id> --log-failed

# Step 2: Analyze the error
# Read the logs, understand what failed

# Step 3: Fix the issue
# Make necessary code changes

# Step 4: Commit the fix
git add .
git commit -m "fix(scope): resolve CI failure - <what you fixed>"

# Step 5: Push
git push

# Step 6: Watch CI again
gh run watch --exit-status

# Step 7: Repeat Steps 1-6 until CI passes

DO NOT SKIP THE FIX LOOP. A failing phase blocks all subsequent work.

Progress Tracking: tasks.md Updates

Rule: Immediate Updates

WRONG ❌:

- Work on 5 tasks
- Complete all 5 tasks
- Update tasks.md with all 5 checkboxes at once

RIGHT ✅:

- Complete task 1
- Immediately check it off in tasks.md
- Commit code + tasks.md together
- Complete task 2
- Immediately check it off in tasks.md
- Commit code + tasks.md together
...

Benefits of Frequent Updates

Real-time progress tracking - Anyone can see current status
Commit history matches progress - Each commit shows what was done
Easier recovery - If something breaks, you know exactly where you were
Better reviews - Reviewers can see incremental progress

Example: Good Commit Pattern

# Commit 1: RED phase
git add tests/unit/feature.test.ts specs/NNN-feature-name/tasks.md
git commit -m "test(domain): add Feature entity test (RED)"

# Commit 2: GREEN phase
git add src/domain/entities/feature.ts specs/NNN-feature-name/tasks.md
git commit -m "feat(domain): implement Feature entity (GREEN)"

# Commit 3: REFACTOR phase
git add src/domain/entities/feature.ts specs/NNN-feature-name/tasks.md
git commit -m "refactor(domain): extract helper methods (REFACTOR)"

Notice how every commit includes tasks.md with updated checkboxes!

Foundational Phases (No Tests)

Some phases don't require tests (TypeSpec models, build config, etc.).

Still follow the update discipline:

Complete a foundational task
Update tasks.md immediately

Commit:

git add <files> specs/NNN-feature-name/tasks.md
git commit -m "feat(tsp): add Feature domain model"

After phase completion: Push + Watch CI + Fix-loop

Common Mistakes

Mistake 1: Batch Updates

❌ Working for hours, then updating tasks.md at the end

✅ Update tasks.md after each item completion

Mistake 2: Skipping CI Watch

❌ Push and immediately start next phase

✅ Push, watch CI, fix-loop if needed, only then proceed

Mistake 3: Implementation Before Tests

❌ Write entity, then write tests

✅ Write tests FIRST (RED), then implement (GREEN)

Mistake 4: Moving On with Red CI

❌ "CI is flaky, I'll fix it later"

✅ Fix immediately in a loop until green

Quick Reference

Commands

Command	Purpose
`pnpm test:watch`	TDD mode - auto-run tests
`pnpm test`	Run all tests
`git add <files> specs/*/tasks.md`	Stage code + task updates
`git push`	Push to trigger CI
`gh run watch --exit-status`	Watch CI, exit 1 if fails
`gh run view <id> --log-failed`	Get CI failure logs
`gh run list --limit 5`	List recent CI runs

TDD Mantra

RED (write test, see it fail)
  ↓
GREEN (write code, make it pass)
  ↓
REFACTOR (improve while keeping tests green)
  ↓
UPDATE tasks.md + COMMIT
  ↓
PUSH + WATCH CI
  ↓
FIX-LOOP if needed
  ↓
NEXT PHASE

Integration Tests & E2E

For integration and E2E test phases, the same discipline applies:

RED: Write failing integration/E2E test
GREEN: Implement to pass
REFACTOR: Clean up
Update tasks.md
Commit + Push + Watch CI

When Complete

After all phases are done:

Final validation:

pnpm validate  # lint + format + typecheck + tsp
pnpm test      # all tests pass

Update spec files to "Complete" phase
Use /shep-kit:commit-pr for final PR creation with CI validation

Spec-Driven Workflow - Overview of the full process
TDD Guide - Deep dive into Test-Driven Development

Remember: Implementation discipline prevents bugs, makes reviews easier, and keeps the project maintainable. Follow the rules, update frequently, watch CI always.