PROJECT 05

CLI Dev Tool

The framework works for ANY technology — no web, no API, just a CLI

⏱ ~50 min · 2 Sprints · Intermediate

What's New in This Project

Every project so far has been a web app. This one has no server, no API, no browser. It's a command-line tool. The framework applies identically — same stories, same TDD, same reviews. This proves it's technology-agnostic.

⚠️ Key Principle

New Commands Introduced

Command	What it does	When you use it
`/agile-code-pair`	Pair programming with AI — you and `@dev` alternate writing tests and implementation	Complex logic that benefits from back-and-forth collaboration
`/agile-code-debug`	Hypothesis-driven debugging — form a hypothesis, test it, verify, fix	When a bug's root cause is unclear, not for every bug

Roles You'll See in Action

Role	What they do in this project	When
📋 `@po`	Structures CLI feature requirements into stories with acceptance criteria	Story creation, sprint review, acceptance
🔄 `@sm`	Facilitates sprint planning, tracks velocity across 2 sprints	Sprint ceremonies
🏗️ `@arch`	Evaluates CLI frameworks (Commander.js, yargs, etc.) — no Express, no React	Project setup
👨‍💻 `@lead`	Reviews CLI-specific code quality, approves PRs	Code review, pair programming
⌨️ `@dev`	Implements CLI commands with TDD, pair programs, debugs cross-platform issues	Implementation, pairing, debugging
🧪 `@qa`	Verifies Definition of Done, checks CLI test coverage (stdout, exit codes, file system)	DoD verification

The Project: scaffold

A CLI tool that scaffolds project files from templates. Think create-react-app but customizable. Three commands:

scaffold init         → Initialize a new project from a template
scaffold add component → Add a component file from a template
scaffold list         → List all available templates

Phase 1: Project Setup

Same setup process as every project — but watch how the framework adapts to a non-web context.

Step 1: Tell Claude what you want to build

💬 You say

"I want to build a CLI tool that scaffolds project files from templates. Like create-react-app but customizable. No web server, no API — just a command-line tool."

Step 2: @arch evaluates CLI frameworks — `/agile-explore-brainstorm`

@arch adapts to the non-web context. No Express, no React — the evaluation focuses on CLI-specific frameworks:

🏗️ @arch responds with a scoring matrix:

## /agile-explore-brainstorm — Results

### Problem Statement
CLI scaffolding tool. Constraints: argument parsing,
subcommands, file system operations, cross-platform.

### Scoring Matrix

| Approach           | Feasibility | Maintainability | Performance | Risk | Total |
|--------------------|------------|-----------------|-------------|------|-------|
| Commander.js       | 9/10       | 9/10            | 8/10        | 9/10 | 35    |
| yargs              | 9/10       | 8/10            | 8/10        | 9/10 | 34    |
| oclif (Salesforce) | 7/10       | 9/10            | 7/10        | 7/10 | 30    |
| meow (minimalist)  | 8/10       | 7/10            | 9/10        | 8/10 | 32    |

### Recommendation
Commander.js — best balance of simplicity, ecosystem, and docs.
Subcommand support built in. Large community.

### What Would Change This
- If plugin architecture needed → oclif
- If minimal dependencies critical → meow

✅ You decide

"Let's go with Commander.js. I want something straightforward with good subcommand support."

Notice: @arch didn't suggest Express or React. The role adapts to the technology. Same evaluation process, different options.

Step 3: Initialize the project — `/agile-setup-init`

The framework detects this is a CLI project — no HTTP, no frontend:

🔄 @sm + 🏗️ @arch + ⌨️ @dev scan results:

## /agile-setup-init — Results

| Memory File             | Status       | Confidence |
|-------------------------|-------------|------------|
| semantic/project.md     | ✅ Populated | 95%        |
| semantic/architecture.md| ✅ Populated | 90%        |
| semantic/conventions.md | ✅ Populated | 85%        |
| semantic/codebase.md    | ✅ Populated | 95%        |
| semantic/testing.md     | ✅ Populated | 90%        |

### Detected Stack
- Language: JavaScript (Node.js 20)
- Framework: Commander.js 12.x
- Database: None (file system only)
- Test Framework: Jest
- Package Manager: npm
- Entry Point: bin/scaffold
- Type: CLI Application (no HTTP server detected)

The framework recognized: no HTTP server, no frontend, CLI entry point in bin/. Everything downstream adapts accordingly.

Phase 2: Sprint 1 — Core CLI

Step 4: Create stories

💬 /agile-story-create I need the CLI to parse arguments
   and show help text when run with --help or no arguments

   → @po creates US-001: "Parse CLI arguments" (3 pts)

💬 /agile-story-create I need an init command that creates
   a new project directory with template files copied into it

   → @po creates US-002: "Init command" (5 pts)

💬 /agile-story-create I need a list command that shows
   all available templates with their descriptions

   → @po creates US-003: "List templates" (2 pts)

Step 5: Sprint planning — `/agile-sprint-planning`

🔄 @sm facilitates:

## Sprint 1 Planning

### Sprint Goal
"Deliver a working CLI with init and list commands"

### Sprint Backlog
| Story  | Title              | Points | Priority |
|--------|--------------------|--------|----------|
| US-001 | Parse CLI arguments | 3      | P1       |
| US-002 | Init command        | 5      | P1       |
| US-003 | List templates      | 2      | P1       |

### Capacity: 10 points committed

Step 6: Build US-001 and US-002 (standard loop)

The standard loop applies — but notice how TDD adapts to CLI testing. Instead of HTTP status codes, you test stdout, exit codes, and file system effects:

US-001: Parse CLI arguments (3 pts)

/agile-code-branch feature US-001 parse-arguments
/agile-code-tdd US-001

  🔴 Test: running "scaffold --help" prints usage info → ❌
  🟢 Configure Commander with program description → ✅
  🔴 Test: running "scaffold" with no args shows help → ❌
  🟢 Add default help behavior → ✅
  🔴 Test: running "scaffold --version" prints version → ❌
  🟢 Read version from package.json → ✅

/agile-code-ci           → ✅ All green
/agile-code-commit       → feat(cli): add argument parsing and help text
/agile-code-pr           → PR created
/agile-code-pr-review    → ✅ Approved
/agile-code-merge        → Squash merged to develop
/agile-story-dod         → ✅ DONE
/agile-story-accept      → ✅ ACCEPTED (3 points)

US-002: Init command (5 pts)

/agile-code-branch feature US-002 init-command
/agile-code-tdd US-002

  🔴 Test: "scaffold init myapp" creates directory → ❌
  🟢 Implement directory creation → ✅
  🔴 Test: template files are copied into new directory → ❌
  🟢 Implement template copying with fs.cpSync → ✅
  🔴 Test: "scaffold init existing-dir" returns error → ❌
  🟢 Add directory-exists check → ✅

/agile-code-ci           → ✅ All green
/agile-code-commit       → feat(cli): add init command with template copying
/agile-code-pr           → PR created
/agile-code-pr-review    → ✅ Approved
/agile-code-merge        → Squash merged to develop
/agile-story-dod         → ✅ DONE
/agile-story-accept      → ✅ ACCEPTED (5 points)

Step 7: A bug appears — `/agile-code-debug`

While building US-003, a test starts failing intermittently. It passes on your macOS machine but fails in CI (Linux). The init command creates files in the wrong paths.

🚫 This Is NOT a Simple Bug

You can't just read the error and fix it. The test passes locally. The failure is intermittent. The root cause is unclear. This is when you use /agile-code-debug — not for every bug, only when the cause is unclear.

💬 You type

/agile-code-debug Tests pass on my machine but fail in CI. The init command creates files in wrong paths.

⌨️ @dev enters the hypothesis-driven debug cycle. This is a structured process, not random guessing:

1. Form Hypothesis

⌨️ @dev: Hypothesis #1
  "The path separator differs between macOS (/) and Linux (/).
  Wait — both use /. But CI might be running Windows too.
  Windows uses \\ as separator."

  Hypothesis: path.join() is correct, but the template paths
  are hardcoded with "/" instead of using path.join().

  Confidence: 70%

2. Test Hypothesis

⌨️ @dev: Testing...
  Searching codebase for hardcoded path separators:

  Found in src/commands/init.js:12
    const templatePath = templatesDir + '/' + templateName;

  ❌ This uses string concatenation with '/' instead of
     path.join(). On Windows, this creates invalid paths.

3. Verify Root Cause

⌨️ @dev: Verification
  - CI matrix includes: ubuntu-latest, windows-latest
  - Windows CI failures match this pattern
  - macOS and Linux both use "/" so they pass
  - Confirmed: hardcoded "/" breaks on Windows

  Root cause: CONFIRMED
  Confidence: 95%

4. Fix

⌨️ @dev: Fix applied
  Before: const templatePath = templatesDir + '/' + templateName;
  After:  const templatePath = path.join(templatesDir, templateName);

  Also fixed 3 other instances of hardcoded separators.
  Tests now pass on all platforms. ✅

✅ The Debug Cycle

Hypothesis → Test → Verify → Fix. This is structured debugging, not "change things and see what happens." /agile-code-debug forces @dev to think before coding — form a theory, prove it, then fix.

US-003: List templates (2 pts)

/agile-code-branch feature US-003 list-templates
/agile-code-tdd US-003

  🔴 Test: "scaffold list" prints available templates → ❌
  🟢 Read templates directory and print names → ✅
  🔴 Test: "scaffold list" shows descriptions from meta.json → ❌
  🟢 Parse meta.json from each template → ✅

/agile-code-ci           → ✅ All green (including Windows!)
/agile-code-commit       → feat(cli): add list command with template descriptions
/agile-code-pr           → PR created
/agile-code-pr-review    → ✅ Approved
/agile-code-merge        → Squash merged to develop
/agile-story-dod         → ✅ DONE
/agile-story-accept      → ✅ ACCEPTED (2 points)

Step 8: Sprint 1 ceremonies

/agile-sprint-review
  Sprint Goal: "Deliver a working CLI with init and list commands"
  Sprint Goal Met: ✅ Yes
  Velocity: 10 points (all 3 stories accepted)

/agile-sprint-retro
  What Went Well:
  - /agile-code-debug caught the cross-platform path bug
  - TDD for CLI works well — testing stdout and exit codes
  What To Improve:
  - Need cross-platform tests from the start
  - Template engine will be complex — consider pair programming

/agile-memory-learn → Sprint 1 velocity: 10 points, cross-platform
  lesson captured

Phase 3: Sprint 2 — Template Engine

Step 9: Create stories and plan

💬 /agile-story-create I need an "add component" command that
   creates a new file from a template, replacing {{variables}}
   like {{name}} and {{date}} with actual values

   → @po creates US-004: "Add component command" (5 pts)

💬 /agile-story-create I need an "add api-route" command
   similar to add component but for API route boilerplate

   → @po creates US-005: "Add api-route command" (3 pts)

💬 /agile-story-create I need clear error messages when
   templates are missing, directories don't exist, or
   variables aren't provided

   → @po creates US-006: "Error messages" (2 pts)

/agile-sprint-planning
  Sprint Goal: "Add template engine with variable substitution"
  Committed: 10 points (matches Sprint 1 velocity)

Step 10: Pair programming — `/agile-code-pair`

US-004 requires a template engine: variable substitution ({{name}}), conditional blocks, dynamic file naming. This is the most complex part of the project.

💬 You type

/agile-code-pair I need to build a template engine that replaces {{variables}} in files and handles conditional sections. Let's pair on this.

Pair programming means you and @dev alternate. One writes the test, the other implements. Then you swap:

Round 1: You write the test, @dev implements

// YOU write the test:
test('replaces {{name}} with provided value', () => {
  const template = 'Hello, {{name}}!';
  const result = render(template, { name: 'World' });
  expect(result).toBe('Hello, World!');
});

// ⌨️ @dev implements:
function render(template, variables) {
  return template.replace(
    /\{\{(\w+)\}\}/g,
    (_, key) => variables[key] ?? ''
  );
}
// ✅ PASS

Round 2: @dev writes the test, you implement

// ⌨️ @dev writes the test:
test('replaces multiple variables in same template', () => {
  const template = '{{name}} created on {{date}}';
  const result = render(template, {
    name: 'UserService',
    date: '2026-04-04'
  });
  expect(result).toBe('UserService created on 2026-04-04');
});

// YOU implement — the existing code already handles this!
// ✅ PASS (no change needed — good test, proves coverage)

Round 3: You write the test, @dev implements

// YOU write the test:
test('handles conditional blocks', () => {
  const template = `{{#if hasTests}}
import { test } from 'jest';
{{/if}}
export class {{name}} {}`;

  const result = render(template, {
    name: 'MyClass', hasTests: true
  });
  expect(result).toContain("import { test }");
  expect(result).toContain("export class MyClass {}");
});

// ⌨️ @dev implements:
function render(template, variables) {
  // First: process conditionals
  let result = template.replace(
    /\{\{#if (\w+)\}\}([\s\S]*?)\{\{\/if\}\}/g,
    (_, key, content) => variables[key] ? content : ''
  );
  // Then: replace variables
  result = result.replace(
    /\{\{(\w+)\}\}/g,
    (_, key) => variables[key] ?? ''
  );
  return result.trim();
}
// ✅ PASS

Round 4: @dev writes the test, you implement

// ⌨️ @dev writes the test:
test('throws on undefined required variable', () => {
  const template = '{{name}} in {{location}}';
  expect(() => render(template, { name: 'File' }, { strict: true }))
    .toThrow('Missing variable: location');
});

// YOU implement strict mode:
function render(template, variables, options = {}) {
  if (options.strict) {
    const required = [...template.matchAll(/\{\{(\w+)\}\}/g)]
      .map(m => m[1])
      .filter(key => !key.startsWith('#') && !key.startsWith('/'));
    const missing = required.filter(k => !(k in variables));
    if (missing.length) throw new Error(`Missing variable: ${missing[0]}`);
  }
  // ... rest of render logic
}
// ✅ PASS

✅ How Pair Programming Works

You alternate roles: one writes the test (defining the contract), the other implements (fulfilling it). Then swap. This creates better tests (the implementer didn't write them) and better code (two perspectives). /agile-code-pair orchestrates the back-and-forth.

Step 11: Complete remaining stories

US-005: Add api-route command (3 pts)

/agile-code-branch feature US-005 add-api-route
/agile-code-tdd US-005

  🔴 Test: "scaffold add api-route users" creates route file → ❌
  🟢 Implement add command with template selection → ✅
  🔴 Test: generated file contains correct route name → ❌
  🟢 Wire up template engine from US-004 → ✅

/agile-code-ci           → ✅ All green
/agile-code-commit       → feat(cli): add api-route scaffolding command
/agile-code-pr           → PR created
/agile-code-pr-review    → ✅ Approved
/agile-code-merge        → Squash merged to develop
/agile-story-dod         → ✅ DONE
/agile-story-accept      → ✅ ACCEPTED (3 points)

US-006: Error messages (2 pts)

/agile-code-branch feature US-006 error-messages
/agile-code-tdd US-006

  🔴 Test: missing template shows "Template not found: xyz" → ❌
  🟢 Add template existence check → ✅
  🔴 Test: missing directory shows helpful message → ❌
  🟢 Add directory validation with suggestion → ✅
  🔴 Test: exit code is 1 on error → ❌
  🟢 Set process.exitCode = 1 on errors → ✅

/agile-code-ci           → ✅ All green
/agile-code-commit       → feat(cli): add clear error messages with exit codes
/agile-code-pr           → PR created
/agile-code-pr-review    → ✅ Approved
/agile-code-merge        → Squash merged to develop
/agile-story-dod         → ✅ DONE
/agile-story-accept      → ✅ ACCEPTED (2 points)

Step 12: Sprint 2 ceremonies

/agile-sprint-review
  Sprint Goal: "Add template engine with variable substitution"
  Sprint Goal Met: ✅ Yes
  Velocity: 10 points (matches Sprint 1 — stable velocity)

/agile-sprint-retro
  What Went Well:
  - /agile-code-pair made the template engine much better —
    tests written by one person, code by another
  - Stable velocity across 2 sprints
  What To Improve:
  - Could add more built-in templates
  - Consider a plugin system for community templates

/agile-memory-learn → Sprint 2 velocity: 10 points, pair programming
  effectiveness captured

Phase 4: Release

This is where the framework adapts most visibly. There's no server to deploy to. The "deployment" target is the npm registry.

Step 13: Generate changelog — `/agile-ship-changelog`

## Changelog: v1.0.0 — 2026-04-04

### Added
- scaffold init — create project from template (US-002)
- scaffold add component — add component from template (US-004)
- scaffold add api-route — add API route from template (US-005)
- scaffold list — list available templates (US-003)
- Template engine with {{variable}} substitution and
  {{#if}} conditional blocks (US-004)
- Clear error messages with non-zero exit codes (US-006)

### Fixed
- Cross-platform path handling (macOS/Linux/Windows)

Step 14: Release and publish — `/agile-ship-release`

🚀 @devops: Release v1.0.0
  Branch: release/v1.0.0 from develop
  CI: ✅ Green
  Merged to main ✅
  Tagged: v1.0.0 ✅
  Back-merged to develop ✅

Step 15: "Deploy" = npm publish

No server to deploy to. Instead, @devops publishes to npm — the deployment model adapts to the technology:

🚀 @devops: Published to npm
  Package: @yourname/scaffold
  Version: 1.0.0
  Registry: https://registry.npmjs.org
  Install:  npm install -g @yourname/scaffold
  Smoke test: scaffold --version → 1.0.0 ✅

💡 Notice

/agile-ship-release still works — the command is the same. But the deployment target changed from a web server to the npm registry. The framework adapts; you don't need different commands for different technologies.

What You Built

Metric	Value
Stories completed	6/6
Story points delivered	20/20
Sprints	2 (stable velocity: 10 pts/sprint)
Sprint goals met	✅ Both
Release version	v1.0.0
Deployment target	npm registry (not a server)
Roles involved	@po, @sm, @arch, @lead, @dev, @qa

New Commands vs Previous Projects

Command	Status	What it proved
`/agile-code-pair`	✅ New	Alternating test/implementation with AI produces better code and better tests
`/agile-code-debug`	✅ New	Hypothesis-driven debugging catches cross-platform issues systematically

✅ Key Takeaway

The framework doesn't care about your technology. CLI, web app, mobile, desktop, library — the process is the same: stories → TDD → review → ship. The roles adapt to YOUR context: @arch evaluates CLI frameworks instead of web frameworks, @devops publishes to npm instead of deploying to a server. The two new commands — /agile-code-pair for complex logic and /agile-code-debug for unclear bugs — work the same regardless of what you're building.

🧠 Knowledge Check

Does the framework require a web server to work?

🧠 Knowledge Check

When do you use /agile-code-debug?

← Project 04: E-Commerce Cart Project 06: Chat App →

CLI Dev Tool

What's New in This Project

New Commands Introduced

Roles You'll See in Action

The Project: scaffold

Phase 1: Project Setup

Step 1: Tell Claude what you want to build

Step 2: @arch evaluates CLI frameworks — /agile-explore-brainstorm

Step 3: Initialize the project — /agile-setup-init

Phase 2: Sprint 1 — Core CLI

Step 4: Create stories

Step 5: Sprint planning — /agile-sprint-planning

Step 6: Build US-001 and US-002 (standard loop)

US-001: Parse CLI arguments (3 pts)

US-002: Init command (5 pts)

Step 7: A bug appears — /agile-code-debug

1. Form Hypothesis

2. Test Hypothesis

3. Verify Root Cause

4. Fix

US-003: List templates (2 pts)

Step 8: Sprint 1 ceremonies

Phase 3: Sprint 2 — Template Engine

Step 9: Create stories and plan

Step 10: Pair programming — /agile-code-pair

Round 1: You write the test, @dev implements

Round 2: @dev writes the test, you implement

Round 3: You write the test, @dev implements

Round 4: @dev writes the test, you implement

Step 11: Complete remaining stories

US-005: Add api-route command (3 pts)

US-006: Error messages (2 pts)

Step 12: Sprint 2 ceremonies

Phase 4: Release

Step 13: Generate changelog — /agile-ship-changelog

Step 14: Release and publish — /agile-ship-release

Step 15: "Deploy" = npm publish

What You Built

New Commands vs Previous Projects

🧠 Knowledge Check

🧠 Knowledge Check

Step 2: @arch evaluates CLI frameworks — `/agile-explore-brainstorm`

Step 3: Initialize the project — `/agile-setup-init`

Step 5: Sprint planning — `/agile-sprint-planning`

Step 7: A bug appears — `/agile-code-debug`

Step 10: Pair programming — `/agile-code-pair`

Step 13: Generate changelog — `/agile-ship-changelog`

Step 14: Release and publish — `/agile-ship-release`