---
name: roadmap-execution
description: 'Execute a phased roadmap with checkpoint commits, incremental validation, and progress tracking.'
argument-hint: 'Roadmap file path or inline description, e.g. "docs/ROADMAP.md", "Phase 2 of FlowMonk backend", "implement push notifications"'
agent: agent
---

# Roadmap Execution Prompt

Execute a phased implementation roadmap with disciplined checkpoint commits, incremental validation, and progress tracking.

## Context — ByteLyst Ecosystem

You are working in the ByteLyst multi-repo ecosystem (`D:\BYTELYST\CODE\`).

**Key conventions:**
- **Package manager:** pnpm (workspace). Never use npm or yarn.
- **Module system:** ESM everywhere (`"type": "module"`, `.js` extensions in imports)
- **Backend pattern:** Fastify 5 + Zod validation. Modules follow `types.ts` → `repository.ts` → `routes.ts`
- **Shared packages:** `@bytelyst/*` in `learning_ai_common_plat/packages/`
- **Services:** `@lysnrai/*` in `learning_ai_common_plat/services/`
- **Product identity:** Every Cosmos document MUST include `productId` field
- **Design tokens:** Never hardcode colors — use `@bytelyst/design-tokens` CSS custom properties
- **Commit format:** `type(scope): description` — types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
- **Tests:** Vitest for TS, pytest for Python. Never modify tests to make them pass — fix the code.

## Execution Protocol

### Phase 0: Understand the Roadmap

1. **Read the roadmap document** (if provided as file path) or parse the inline description
2. **Identify all phases/milestones** and their dependencies
3. **Estimate scope** for each phase (files touched, tests needed, risk level)
4. **Create a tracker** — write a `docs/IMPLEMENTATION_TRACKER.md` with:
   - Phase list with `[ ]` / `[/]` / `[x]` status
   - Key files to create/modify per phase
   - Validation criteria per phase
   - Commit message for each checkpoint

### Phase N: Execute Each Phase

For each phase, follow this cycle:

#### Step 1: Plan
- List files to create or modify
- Identify which `@bytelyst/*` packages are needed
- Note any new dependencies

#### Step 2: Implement
- Write code following the established patterns in this repo
- Use existing `src/lib/` re-exports for shared packages
- Every new API endpoint gets Zod schema validation
- Every new Cosmos container uses `productId` partition-aware queries

#### Step 3: Test
- Add tests alongside implementation (same module directory or `__tests__/`)
- Run tests: `pnpm test` or `pnpm --filter <package> test`
- Run typecheck: `pnpm typecheck` or `pnpm --filter <package> typecheck`
- Fix any failures before proceeding

#### Step 4: Validate
- Verify the feature works end-to-end (API → UI if applicable)
- Check for regressions: run the full test suite
- Review for ecosystem compliance:
  - ✅ `productId` on all Cosmos docs
  - ✅ No `console.log` (use `req.log` / `app.log`)
  - ✅ No `any` types
  - ✅ No hardcoded colors
  - ✅ No hardcoded secrets

#### Step 5: Checkpoint Commit
```bash
git add .
git commit -m "feat(<scope>): <phase-description>

- <key change 1>
- <key change 2>
- Tests: <N> new tests, all passing"
git push
```

#### Step 6: Update Tracker
- Mark the phase `[x]` in `IMPLEMENTATION_TRACKER.md`
- Add the commit hash
- Note any deferred items or follow-ups

### Completion

After all phases:

1. **Run full validation:**
   ```bash
   pnpm build && pnpm typecheck && pnpm test
   ```
2. **Update AGENTS.md** if the repo layout, API endpoints, or test counts changed
3. **Update README.md** if new features, commands, or setup steps were added
4. **Final commit:**
   ```bash
   git add .
   git commit -m "docs(<scope>): update docs for <roadmap-name> completion"
   git push
   ```

## Output Format

Report progress after each phase:

```
## Phase N: <Name> ✅

**Commit:** `abc1234`
**Files changed:** 5 created, 2 modified
**Tests:** 12 new tests, all passing
**Validation:** typecheck ✅, lint ✅, test ✅
**Notes:** <any deferred items or follow-ups>
```

## Guardrails

- **Never skip tests.** Every phase must include test validation.
- **Never make big-bang commits.** Each phase gets its own checkpoint.
- **Never break existing tests.** If a test fails, fix the code, not the test.
- **Never hardcode values.** Use config, env vars, and design tokens.
- **Always verify before committing.** Run typecheck + test before every commit.