Build Feature

Workflow

0. Initialize or load progress.txt

Check if scripts/build-feature-loop/progress.txt exists:

If it doesn't exist or user is starting a new feature:

1. Ask the user to describe the feature and its tasks (or reference a PRD)
2. Create the progress file with the task list:

# Build Progress Log
Started: [today's date]
Feature: [feature name]

## Codebase Patterns
(Patterns discovered during this feature build)

---

## Tasks

- [ ] Task 1 title
  Description: What to do
  Files: path/to/file.ts
  Depends: none

- [ ] Task 2 title
  Description: What to do
  Depends: Task 1

- [ ] Task 3 title
  Description: What to do
  Depends: Task 1

- [ ] Task 4 title
  Description: What to do
  Depends: Task 2, Task 3

---

## Completed Work
(Entries added as tasks complete)

If it exists: Read it to understand current state.

1. Sync TodoWrite with progress.txt

Parse the tasks from progress.txt and update TodoWrite so the user can see progress:

• [ ] tasks → pending
• [x] tasks → completed
• Currently executing → in_progress

2. Find the next ready task

A task is ready when:

• Status is [ ] (not completed)
• All tasks listed in Depends: are completed [x]

Pick the next task:

• Prefer tasks related to what was just completed (same module/area)
• If no prior context, pick the first ready task

3. If no ready tasks

Check if all tasks are completed:

• If ALL tasks are [x]:

  1. Archive progress.txt:

     DATE=$(date +%Y-%m-%d)
     FEATURE="feature-name-here"
     mkdir -p scripts/build-feature-loop/archive/$DATE-$FEATURE
     mv scripts/build-feature-loop/progress.txt scripts/build-feature-loop/archive/$DATE-$FEATURE/
     

  2. Commit: git add scripts/build-feature-loop && git commit -m "chore: archive progress for [feature-name]"
  3. Stop and report "Build complete - all tasks finished!"

• If some tasks are blocked (dependencies not met): Report which tasks are blocked and why

4. Execute the task

Use the Task tool to spawn a subagent with this prompt:

Implement and verify: [task-title]

[task-description]

**Files:** [files from task]

FIRST: Read scripts/build-feature-loop/progress.txt - check the "Codebase Patterns" section for important context from previous iterations.

When complete:

1. Run quality checks: `npm run typecheck` and `npm test`
   - If either fails, FIX THE ISSUES and re-run until both pass
   - Do NOT proceed until quality checks pass

2. Update AGENTS.md files if you learned something important:
   - Check for AGENTS.md in directories where you edited files
   - Add learnings that future developers/agents should know (patterns, gotchas, dependencies)
   - This is LONG-TERM memory - things anyone editing this code should know

3. Update progress.txt:
   a. Mark this task complete: change `- [ ] [task-title]` to `- [x] [task-title]`
   b. Add entry to "## Completed Work" section:
      ```
      ## [Date] - [Task Title]
      - What was implemented
      - Files changed
      - **Learnings for future iterations:**
        - Patterns discovered
        - Gotchas encountered
      ---
      ```
   c. If you discovered a reusable pattern, add it to "## Codebase Patterns" at the top

4. Commit all changes with message: `feat: [Task Title]`

5. After subagent returns

1. Read the updated progress.txt
2. Update TodoWrite to reflect completed task
3. Check for more ready tasks → go to step 2
4. If all done or blocked → report status

Progress File Location

The progress file should be at scripts/build-feature-loop/progress.txt.

Task Format in progress.txt

- [ ] Short task title
  Description: Detailed description of what to do
  Files: path/to/file1.ts, path/to/file2.ts
  Depends: none

- [ ] Another task
  Description: What to implement
  Files: src/components/Thing.tsx
  Depends: Short task title

- [x] Completed task
  Description: What was done
  Files: src/lib/util.ts
  Depends: none

Dependency rules:

• Depends: none - Can start immediately
• Depends: Task A - Blocked until Task A is [x]
• Depends: Task A, Task B - Blocked until both are [x]

Task Discovery

While working, liberally add new tasks to progress.txt when you discover:

• Failing tests or test gaps
• Code that needs refactoring
• Missing error handling
• Documentation gaps
• TODOs or FIXMEs in the code
• Build/lint warnings
• Performance issues

Add them to the ## Tasks section with appropriate Depends: relationships.

Task Description Guidelines

Write descriptions that a future iteration can pick up without context:

- [ ] Add priority field to tasks table
  Description: Add 'priority' column with values 'high'|'medium'|'low', default 'medium'. Create migration.
  Files: prisma/schema.prisma, prisma/migrations/
  Depends: none
  Acceptance: npm run typecheck passes, migration runs successfully

Dependency ordering (typical):

1. Schema/database changes (migrations)
2. Server actions / backend logic
3. UI components that use the backend
4. Integration / E2E tests

Browser Verification

For UI tasks, specify the right verification method in the task description:

Functional testing (checking behavior, not appearance):

• Use browser_snapshot tool to read page content as accessibility tree
• Use for: button exists, text appears, form works

Visual testing (checking appearance):

• Use browser_take_screenshot tool to capture visual appearance
• Use for: layout, colors, styling, animations

Quality Requirements

Before marking any task complete:

• npm run typecheck must pass
• npm test must pass
• Changes must be committed
• Progress must be logged

Stop Condition

When no ready tasks remain AND all tasks are completed:

1. Output: "Build complete - all tasks finished!"
2. Summarize what was accomplished

Important Notes

• Each Task subagent runs with fresh context
• progress.txt is the memory between iterations - keep it updated
• Prefer tasks in the same area as just-completed work for better context continuity
• The Task prompt MUST include instructions to update progress.txt and commit

Pre-Flight Checklist

Before starting the loop, verify:

• progress.txt exists with tasks defined
• At least one task has Depends: none (can start)
• Each task is small enough for one iteration
• Each task has clear acceptance criteria
• UI tasks specify snapshot vs screenshot verification
• Task descriptions have enough detail to implement without context