Project Implementation

Overview

docs/

• NEVER stop between phases. Implement ALL phases from start to finish in one continuous session. Do NOT pause after completing a phase to ask if you should continue — just continue.
• NEVER ask the user questions. If you encounter ambiguity, uncertainty, or need to make a decision, make your best judgment based on the documentation and record the question/decision in

  docs/questions.md

  for later review. NEVER use AskUserQuestion or stop to ask for input.
• Never skip tests. Never mark a task as done without verified implementation. Always commit after each completed section. Always update tracking files before moving to the next task.

Questions Protocol

1. DO NOT stop or ask the user — make the best decision you can based on available documentation
2. Record it in

   docs/questions.md

   with the following format:
   markdown

   ## [Phase X — Section Name]
   
   **Q:** What is the expected behavior when X happens?
   **Decision:** I chose to do Y because Z.
   **Impact:** Low/Medium/High — affects [description].

3. Continue implementing — the user will review

   docs/questions.md

   after all development is complete

The Process

Phase 1: Read Project Documentation

1. Read all files in

   docs/

   bash

   find docs/ -type f -name '*.md' | sort

   Read every documentation file to understand the full project scope, architecture, and requirements.
2. Read

   docs/implementation.md

   (Implementation Plan)
   • If it exists → read it carefully to understand the phases, order of execution, and dependencies
   • If it does NOT exist → create it from the specification files in

     docs/

     :
     • Analyze all spec documents
     • Break the project into logical implementation phases (Phase 0: Setup, Phase 1: Core, Phase 2: Features, etc.)
     • Each phase should have clear deliverables and acceptance criteria
     • Write the plan to

       docs/implementation.md

3. Read

   docs/todo.md

   (Task Checklist)
   • If it exists → read it to understand what needs to be done
   • If it does NOT exist → create it from

     docs/implementation.md

     :
     • Convert each phase into a section with checkbox items
     • Each item should be a single, atomic, implementable task
     • Use the format

       - [ ]

       for pending and

       - [x]

       for completed
     • Group by phase, with clear section headers
     • Example structure:
       markdown

       # Project Name — TODO
       
       ---
       
       ## Phase 0 — Setup
       
       ### Initialization
       - [ ] Create `package.json`
       - [ ] Create `tsconfig.json`
       - [ ] Create `.gitignore`
       
       ### Build
       - [ ] Install dev dependencies
       - [ ] Create build config
       - [ ] Validate `npm run build` works
       - [ ] Validate `npm run test` works
       
       ### Directory Structure
       - [ ] Create `src/` directories
       - [ ] Create `__tests__/` directories
       
       ---
       
       ## Phase 1 — Core Feature
       
       ### Sub-feature A
       - [ ] Implement X
       - [ ] Implement Y
       - [ ] Write tests for X and Y

4. Read

   docs/implemented.md

   (Implementation Log)
   • If it exists → read it to understand what was already done and where to resume
   • If it does NOT exist → create it with this initial content:
     markdown

     # Implementation Log
     
     > Auto-updated after each implementation cycle.
     
     ---

Phase 2: Determine Where to Resume

1. Compare

   docs/todo.md

   with

   docs/implemented.md

2. Find the first unchecked item (

   - [ ]

   ) in

   todo.md

3. That is the starting point for this session

Phase 3: Implementation Loop

todo.md

3a. Implement

• Read the task description
• Implement the minimum required to complete all items in the current section/group
• Follow project conventions found in the documentation
• Stay focused on the scope — no "while I'm here" changes

3b. Run Tests

# Run the project's test command (detect from package.json, Makefile, etc.)
npm run test
# or
bundle exec rspec
# or
pytest
# or whatever the project uses

• All tests MUST pass before proceeding
• If tests fail, fix them before moving on
• If the section introduces new behavior, write tests for it

3c. Commit

git add <changed files>
git commit -m "feat: <description of what was implemented>

Co-Authored-By: Claude <noreply@anthropic.com>"

• One commit per completed section/group
• Use conventional commits:

  feat:

  ,

  fix:

  ,

  chore:

  ,

  refactor:

  ,

  test:

• Commit message in the project's language (follow existing commit style)

3d. Update

docs/todo.md

- [x] Create `package.json`  ← was `- [ ]`

3e. Update

docs/implemented.md

## Phase 0 — Setup > Initialization

- Created `package.json` with scope `@project/name`
- Created `tsconfig.json` targeting ES2022
- Created `.gitignore`

**Commit:** `abc1234`

3f. Commit Tracking Updates and Continue

1. Commit the tracking file updates:
   bash

   git add docs/todo.md docs/implemented.md docs/questions.md
   git commit -m "docs: update implementation progress
   
   Co-Authored-By: Claude <noreply@anthropic.com>"

2. Immediately continue to the next unchecked section — do NOT stop, do NOT ask the user, do NOT restart the process. Loop back to step 3a with the next section.

todo.md

Phase 4: Completion

todo.md

- [x]

1. Run the full test suite one final time
2. Update

   docs/implemented.md

   with a completion summary
3. If

   docs/questions.md

   has entries, inform the user to review it
4. Inform the user that implementation is complete

Quick Reference

Red Flags — STOP and Reassess

• Implementing without reading ALL docs first
• Skipping test execution after implementation
• Marking tasks done without actually implementing them
• Making changes outside the scope of the current section
• Committing without running tests
• Not updating tracking files after each cycle
• Stopping between phases to ask the user questions — save questions to

  docs/questions.md

  and continue
• Pausing after a phase to ask "Shall I continue?" — ALWAYS continue automatically
• Moving to the next section when tests are failing

Common Rationalizations

docs/questions.md

Notes

• NEVER stop between phases — implement ALL phases in one continuous session
• NEVER ask the user questions — save decisions and questions to

  docs/questions.md

• One section per commit — keeps commits atomic and history clean
• The todo.md is the source of truth — if it's not checked, it's not done
• The implemented.md is the audit log — always record what was done and the commit hash
• Detect the project's tech stack from docs and existing files to use the correct test/build commands
• The questions.md is for post-implementation review — the user reads it after everything is done