Part 1

Implementing Roadmaps with AI

Turning plans into code

Quick Recap: Where We Are

PRD  -->  Plans  -->  Roadmaps  -->  ???
 (what)    (how)      (checklist)    (CODE)
                        

You have the planning docs. Now we turn them into working software.

The Implementation Prompt Pattern

Review @context.md. Implement the roadmap
at ai/roadmaps/[your-roadmap].md.
                        

What Happens Next

AI will:

• Read the roadmap and understand the scope
• Read architecture.md for system design
• Read coding-style.md for conventions
• Implement the code
• May ask clarifying questions — answer them

What you do:

• Watch the implementation unfold
• Answer questions when asked
• Don't micromanage — let it work

In Practice

Part 2

Verifying Roadmap Implementation

Did AI build what we planned?

Did AI Build What We Planned?

Verification implements the Law of Witnesses — a second perspective to ensure truth and correctness.

After implementation, verify against the roadmap.

Review the roadmap at ai/roadmaps/[your-roadmap].md.
Check off what was completed from phase 1.
Flag anything that was missed or implemented
differently than planned.
Don't make any code changes — just report.
                        

What Verification Looks Like

AI will:

• Cross-reference roadmap tasks against actual code
• Mark completed items
• Flag anything missed or changed
• Note any deviations from the plan

You review:

• Are the deviations reasonable?
• Was anything critical missed?
• Does the code match your expectations?

Update Your Roadmap

After verification, update the roadmap:

Update the roadmap to reflect what was completed.
Add notes on any changes from the original plan.
Mark phase 1 as complete if everything checks out.
                        

The Complete Recipe

The prompt sequence you'll use every time you implement from a roadmap:

Step 1 — Review Context

Review @context.md and the roadmap at ai/roadmaps/[your-roadmap].md.
                        

Step 2 — Implement

Implement phase [N] of the roadmap.
Follow the architecture in aiDocs/architecture.md
and coding style in aiDocs/coding-style.md.
Check off tasks in the roadmap as you complete them.
                        

Step 3 — Verify with a Sub-Agent

Deploy a sub-agent to verify all implementation from phase [N].
Compare what was built against the roadmap requirements.
Flag anything missed or implemented differently than planned.
Don't make code changes — just report.
                        

Step 4 — Archive When Complete

Once all phases are done and verified:
Move both the plan and roadmap to ai/roadmaps/completed/
                        

Part 3

Creating CLI Testing Scripts

The full loop

The Key Insight

"When AI can test itself, you have the full loop."

AI implements --> AI tests --> AI reads output --> AI fixes
     ^                                                  |
     └──────────────────────────────────────────────────┘
                        

Without CLI scripts, YOU are the bottleneck.

The Prompt

Create CLI scripts in scripts/ that exercise
the features we just built.
Each script should:
- Accept inputs as command-line arguments
- Run the feature
- Output JSON results to stdout
- Use proper exit codes (0 = success, non-zero = failure)
- Send errors to stderr
                        

The scripts/ Folder Pattern

scripts/
├── build.sh      # Compile/build the project
├── test.sh       # Run all tests
├── run.sh        # Run the application
└── dev.sh        # Start dev server (optional)
                        

Minimum viable set: build.sh and test.sh

AI can run your entire workflow from the command line

Example: test.sh

#!/bin/bash
echo "Building project..."
./scripts/build.sh || { echo '{"status":"fail","step":"build"}' >&2; exit 1; }
echo "Running tests..."
if npm test 2>&1; then
    echo '{"status": "pass", "message": "All tests passed"}'
    exit 0
else
    echo '{"status": "fail", "message": "Tests failed"}' >&2
    exit 1
fi
                        

Cross-Platform Note

Shell scripts don't work on all machines.
For Windows/Mac compatibility, consider Node.js scripts:

// scripts/test.js
const { execSync } = require('child_process');
try {
  execSync('npm test', { stdio: 'inherit' });
  console.log(JSON.stringify({ status: 'pass' }));
  process.exit(0);
} catch (err) {
  console.error(JSON.stringify({ status: 'fail', error: err.message }));
  process.exit(1);
}
                        

Run with: node scripts/test.js

In Practice

Part 4

Testing with CLI Tools

Run and validate

Run the Scripts

# Build first
./scripts/build.sh

# Then test
./scripts/test.sh
                        

AI reads the output and knows:

• Did it work? (exit code 0)
• What failed? (JSON error output)
• What to fix? (error details in stderr)

The Autonomous Loop

1. AI runs: ./scripts/test.sh
2. AI reads output
3. If exit code 0: Done! Tests pass.
4. If exit code != 0: AI reads error output
5. AI diagnoses the issue
6. AI fixes the code
7. Go to step 1
                        

What Success Looks Like

$ ./scripts/test.sh
{"status": "pass", "tests": 12, "failures": 0}
$ echo $?
0
                        

Part 5

The Fix Loop

Autonomous bug fixing

When Tests Fail

Run ./scripts/test.sh.
If any tests fail, analyze the output,
fix the issues, and run again.
Continue until all tests pass.
                        

Then step back and let AI work.

When to Intervene

Let AI work. Step back. Only intervene if:

• Same error repeating 3+ times
• AI trying increasingly complex "solutions"
• Fix is making things worse
• AI is clearly confused about the root cause

Intervention prompt:

Stop. Let's step back.
What have we tried so far?
What's the actual root cause?
Is there a different approach entirely?
                        

The Full Picture

PLAN         -->  IMPLEMENT  -->  TEST    -->  FIX     -->  VERIFY
(roadmap)         (AI codes)      (CLI)       (loop)       (check roadmap)
                                    ^            |
                                    └────────────┘