learning_ai_common_plat/AI.dev/PROMPTS/roadmap-execution.md

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

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:

   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:

   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.