saravanakumardb
32c7b1ba7e
- roadmap-execution: phased roadmap execution with checkpoints - new-product-scaffold: scaffold new ByteLyst product repos - prd-to-implementation: convert PRDs to concrete plans - cross-repo-debug: systematic multi-repo debugging - backend-module-crud: Fastify CRUD modules (types/repo/routes/tests) - platform-integration: wire products into common platform - refactor-with-tests: test-first safe refactoring - test-gap-analysis: coverage gap identification and remediation - type-safety-sweep: TypeScript error triage and fix - dependency-health-check: cross-repo dependency audit - pre-release-validation: comprehensive release checklist - docker-production-prep: production Docker images - agents-md-sync: keep AI instruction files accurate - ecosystem-audit: full ecosystem health dashboard
125 lines
4.3 KiB
Markdown
125 lines
4.3 KiB
Markdown
---
|
|
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.
|