code-first-draft

Quick Start

1. Point me to a PRD or describe the feature to build
2. I explore your codebase (framework, patterns, structure) or switch to Prototype Mode if no codebase exists
3. I create an implementation plan and ask for your approval before writing code
4. I follow TDD: write failing tests first, then implement to make them pass, then refactor
5. I deliver a summary with files created/modified, test coverage, and next steps

Example: "Build the user preferences feature from thoughts/shared/prds/preferences.md"

Output: Code in your codebase + summary saved to thoughts/shared/prototypes/[feature]-first-draft.md

Time: 1-3 hours depending on feature complexity

Purpose

Connect to codebase and build initial implementation of a feature. Single-pass development with manual iteration.

Usage

• /code-first-draft - Build feature from PRD
• /code-first-draft [prd-name] - Build specific PRD
• /code-first-draft --explore-only - Just explore codebase, don't write code yet

Context Routing

Check first:

1. thoughts/shared/prds/ - PRD for requirements (if available)
2. Codebase (.git directory, source files)

Workflow

Step 1: Codebase Setup (First Time Only)

Detect codebase:

# Check if in codebase directory
ls -la | grep ".git"

If not in codebase:

• Ask: "Where's your codebase?"
• Options:
  1. "Navigate me there" (cd to directory)
  2. "Clone from GitHub" (provide repo URL, I'll clone with gh repo clone)
  3. "Connect via MCP" (GitHub MCP for remote access)

Explore codebase:

# Detect framework
ls package.json || ls requirements.txt || ls Gemfile || ls go.mod

# Find key directories
find . -type d -name "components" -o -name "src" -o -name "app" | head -10

# Understand structure
tree -L 2 -I 'node_modules|__pycache__|.git'

Step 2: PRD to Technical Requirements

Read PRD and extract:

• User stories → Features to build
• Success metrics → Analytics to instrument
• Edge cases → Error handling needed
• Non-goals → What NOT to build

Map to code:

• Which files need modification?
• Which new files needed?
• Which APIs to create/modify?
• Which database changes required?

Step 3: Implementation Plan

Before writing code, create plan:

# Implementation Plan: [Feature]

## Files to Create

- `tests/feature.test.ts` - Unit tests (written FIRST)
- `tests/feature.integration.test.ts` - Integration tests (written FIRST)
- `src/components/NewFeature.tsx` - Main component
- `src/api/feature.ts` - API routes

## Files to Modify

- `src/components/Dashboard.tsx` - Add new feature entry point
- `src/api/index.ts` - Register new routes
- `src/types/index.ts` - Add type definitions

## API Endpoints

- `POST /api/feature` - Create new item
- `GET /api/feature/:id` - Fetch item
- `PUT /api/feature/:id` - Update item

## Database Changes

- Add `features` table with columns: id, user_id, data, created_at

## Testing Approach (TDD)

Tests are written BEFORE implementation using Red → Green → Refactor:
1. **Red** — Write failing tests describing expected behavior
2. **Green** — Implement minimum code to make tests pass
3. **Refactor** — Clean up while keeping tests green

- Unit tests for core business logic (written first)
- Integration tests for API endpoints (written first)
- Edge case tests for error states (written first)
- E2E test for happy path

Ask user for approval: "This is my plan. Approve before I write code?"

Step 4: Implementation (TDD — Red → Green → Refactor)

Follow Test-Driven Development for each unit of work:

Step 4a: Write Failing Tests (Red)

• Write test files FIRST, before any implementation code
• Tests should describe the expected behavior from the PRD
• Run tests to confirm they fail (this validates the tests are meaningful)
• Cover: core logic, API contracts, edge cases, error states

Step 4b: Implement to Pass (Green)

• Write the minimum code to make tests pass
• Follow existing code patterns (match style)
• Follow framework conventions
• Don't over-engineer — just make the tests green

Step 4c: Refactor (Clean)

• Clean up implementation while keeping all tests green
• Extract shared logic, improve naming, simplify
• Run tests after each refactor step to ensure nothing breaks

Add inline comments for:

• Complex logic
• Edge case handling
• TODOs for future work

TDD rhythm per feature unit:

1. Write test → run → see it fail (Red)
2. Write implementation → run → see it pass (Green)
3. Clean up → run → still passing (Refactor)
4. Repeat for next unit

Step 5: Summary Document

Save to thoughts/shared/prototypes/[feature]-first-draft.md:

# First Draft Implementation: [Feature]

**Date:** [Date]
**PRD:** [Link]

## What Was Built

**Files created:** [X]
**Files modified:** [Y]
**Tests added:** [Z]

## Implementation Approach

[Brief description of technical approach]

## Testing

**Coverage:** [%]
**Tests passing:** [Y/N]
**Manual testing needed:** [What to test]

## Known Issues / TODOs

- [ ] [Issue 1]
- [ ] [TODO 1]

## Next Steps

- Run tests
- Manual QA
- For complex features: Consider `/catalyst-dev:create-plan` + `/catalyst-dev:implement-plan` for structured iteration

Prototype Mode (No Codebase Detected)

If no codebase is detected (no .git directory, no package.json, no source files in the workspace), switch to Prototype Mode automatically.

Tech Stack Detection (Prototype Mode)

Infer the tech stack from the user's request or use sensible defaults:

What changes:

• Instead of modifying an existing codebase, generate a standalone reference implementation
• Fall back to the most common stack for the feature type:
  • UI features: React + TypeScript + Tailwind CSS
  • Backend/API features: Python (FastAPI) or Node.js (Express + TypeScript)
  • Full-stack features: Next.js + TypeScript
  • Data processing: Python with standard libraries
• Include a README.md with setup instructions (npm install && npm run dev or equivalent)
• Add a header comment in every file: // Reference prototype - not production code.

Output: Save all files to thoughts/shared/prototypes/[feature]-reference-impl/

When presenting:

"No codebase detected, so I built a standalone reference prototype using [stack]. This is not production code — adapt it to your actual codebase patterns, auth system, and infrastructure."

Accessibility Guidance

For UI features, include basic accessibility in all generated code:

Required accessibility patterns:

• ARIA labels on all interactive elements (buttons, inputs, links, toggles)
• Keyboard navigation -- all interactive elements reachable via Tab, activatable via Enter/Space
• Sufficient color contrast -- avoid light-gray-on-white text; use WCAG AA minimum (4.5:1 for normal text)
• Screen reader-friendly ordering -- logical DOM order matches visual order; use semantic HTML (<nav>, <main>, <section>, <button>)
• Focus indicators -- visible focus ring on interactive elements (do not remove outline)
• Alt text on images and icons that convey meaning
• Error messages associated with form fields via aria-describedby

Check for additional accessibility requirements in project documentation (e.g., WCAG AAA, specific assistive technology support).

In code comments:

// a11y: Label describes the action for screen readers
<button aria-label="Save user preferences">Save</button>

// a11y: Error message linked to input for screen readers
<input aria-describedby="email-error" />
<span id="email-error" role="alert">Please enter a valid email</span>

Testing Depth (TDD)

All tests are written BEFORE implementation code using the detected testing framework. If no testing framework is detected, default to the standard for the stack (Jest for React/Node, Pytest for Python, Vitest for Vi