volt-framework 0.1.0

package/src/templates/docs/source-tree.md

@@ -0,0 +1,163 @@
+# Source Tree
+
+> Last updated: {date}
+
+<!-- REQUIRED: Definitive map of the project's file structure. Tells developers and AI agents
+     WHERE things live, WHAT each directory contains, and HOW modules connect.
+     Fill every {placeholder}, remove comments once done. -->
+
+## Complete Directory Structure
+
+<!-- REQUIRED: Full tree with inline annotations. Mark generated dirs with (generated). -->
+
+```
+{root}/
+├── .github/                    # CI/CD workflows and PR templates
+│   └── workflows/
+├── prisma/                     # database schema and migrations
+│   ├── schema.prisma           # source of truth for DB schema
+│   ├── migrations/             # (generated) migration history
+│   └── seed.ts                 # database seed script
+├── src/
+│   ├── main.ts                 # application entry point
+│   ├── app.module.ts           # root module
+│   ├── common/                 # shared utilities across all modules
+│   │   ├── decorators/
+│   │   ├── filters/
+│   │   ├── guards/
+│   │   ├── interceptors/
+│   │   └── utils/
+│   ├── config/                 # configuration and env validation
+│   └── modules/                # feature modules (one folder per domain)
+│       ├── auth/
+│       ├── user/
+│       └── {domain}/
+├── test/                       # e2e and integration tests
+├── .kc1t/                      # framework config, docs, epics, tasks
+│   ├── docs/                   # context framework documentation
+│   ├── epics/                  # epic specifications
+│   └── tasks/                  # task breakdowns
+├── .env.example                # environment variable template
+├── package.json
+└── Dockerfile
+```
+
+## Critical Directories
+
+<!-- REQUIRED: Deeper description of the top 3-5 most important directories. -->
+
+### {src/modules/auth/}
+
+| Property           | Value                                                  |
+|--------------------|--------------------------------------------------------|
+| **Purpose**        | {handles user authentication and session management}   |
+| **Entry point**    | {auth.module.ts}                                       |
+| **Key files**      | {auth.service.ts, jwt.strategy.ts}                     |
+| **Depends on**     | {user module, config}                                  |
+| **Depended on by** | {every protected module via AuthGuard}                 |
+
+### {src/modules/user/}
+
+| Property           | Value                                                  |
+|--------------------|--------------------------------------------------------|
+| **Purpose**        | {user CRUD operations and profile management}          |
+| **Entry point**    | {user.module.ts}                                       |
+| **Key files**      | {user.service.ts, user.repository.ts}                  |
+| **Depends on**     | {database (Prisma client)}                             |
+| **Depended on by** | {auth module, billing module}                          |
+
+### {src/common/}
+
+| Property           | Value                                                  |
+|--------------------|--------------------------------------------------------|
+| **Purpose**        | {shared infrastructure used across all feature modules}|
+| **Key files**      | {auth.guard.ts, validation.pipe.ts, http-exception.filter.ts}|
+| **Depends on**     | {nothing -- leaf dependency}                           |
+| **Depended on by** | {all modules}                                          |
+
+## Entry Points
+
+| Entry point         | Path                  | Purpose                   | Trigger                   |
+|---------------------|-----------------------|---------------------------|---------------------------|
+| **Main app**        | {src/main.ts}         | {bootstraps the app}      | {pnpm start / pnpm dev}  |
+| **DB seed**         | {prisma/seed.ts}      | {populates dev database}  | {pnpm db:seed}            |
+| **E2E tests**       | {test/app.e2e-spec.ts}| {end-to-end test suite}   | {pnpm test:e2e}           |
+
+## Configuration Files
+
+| File                   | Purpose                                   |
+|------------------------|-------------------------------------------|
+| {tsconfig.json}        | {TypeScript compiler options + aliases}    |
+| {.eslintrc.js}         | {linting rules}                            |
+| {.prettierrc}          | {code formatting rules}                    |
+| {Dockerfile}           | {container build definition}               |
+| {docker-compose.yml}   | {local dev services (DB, Redis)}           |
+| {.env.example}         | {environment variable template}            |
+| {prisma/schema.prisma} | {database schema definition}               |
+
+## Asset Locations
+
+<!-- OPTIONAL: Delete if not applicable. -->
+
+| Asset type       | Path                          | Notes                           |
+|------------------|-------------------------------|---------------------------------|
+| {static files}   | {public/}                     | {served directly by web server} |
+| {user uploads}   | {S3 bucket / uploads/}        | {presigned URL upload flow}     |
+| {generated types}| {node_modules/.prisma/client} | {auto-generated by Prisma}      |
+| {build output}   | {dist/}                       | {gitignored, created by build}  |
+
+## Integration Points Between Modules
+
+```mermaid
+graph LR
+  Auth --> User
+  Billing --> User
+  Billing --> Stripe[Stripe API]
+  Auth --> Config
+  User --> DB[(Database)]
+  Billing --> DB
+```
+
+| From       | To             | Method                    | Notes                   |
+|------------|----------------|---------------------------|-------------------------|
+| {auth}     | {user}         | {direct service injection}| {user lookup for login} |
+| {billing}  | {notification} | {event emitter / queue}   | {payment confirmation}  |
+
+## File Organization Patterns
+
+<!-- REQUIRED: Rules that determine where new files go. -->
+
+- **New feature module:** {create src/modules/{feature}/ with controller, service, module, dto/}
+- **Shared utility:** {add to src/common/utils/ and re-export from barrel}
+- **New migration:** {run prisma migrate dev --name {description}}
+- **New env variable:** {add to .env.example, config/env.ts, and tech-stack.md}
+
+## Entry Points by Domain
+
+<!-- REQUIRED: Quick-reference for jumping into any feature area. -->
+
+### {User Management}
+- **Controller:** `{src/modules/user/user.controller.ts}`
+- **Service:** `{src/modules/user/user.service.ts}`
+- **Routes:** {GET /users, GET /users/:id, POST /users, PATCH /users/:id, DELETE /users/:id}
+- **Dependencies:** {Prisma client, auth guard}
+
+### {Authentication}
+- **Controller:** `{src/modules/auth/auth.controller.ts}`
+- **Service:** `{src/modules/auth/auth.service.ts}`
+- **Routes:** {POST /auth/login, POST /auth/register, POST /auth/refresh}
+- **Dependencies:** {user service, JWT config}
+
+## Available Scripts
+
+```bash
+{pnpm dev}           # start with hot reload
+{pnpm build}         # compile to dist/
+{pnpm test}          # run unit tests
+{pnpm test:cov}      # tests with coverage
+{pnpm test:e2e}      # end-to-end tests
+{pnpm db:migrate}    # apply pending migrations
+{pnpm db:seed}       # seed development data
+{pnpm lint}          # run ESLint
+{pnpm typecheck}     # run tsc --noEmit
+```

package/src/templates/docs/tech-stack.md

@@ -0,0 +1,123 @@
+# Tech Stack
+
+> Last updated: {date}
+
+<!-- REQUIRED: Single source of truth for "what do I need installed?" and "what services
+     does this project talk to?" Fill every {placeholder}, remove comments once done. -->
+
+## Prerequisites
+
+<!-- REQUIRED: What must be installed BEFORE anything else. -->
+
+| Tool      | Version | Install                | Notes        |
+|-----------|---------|------------------------|--------------|
+| {Node.js} | {>= 20} | {https://nodejs.org}   |              |
+| {Docker}  | {>= 24} | {https://docker.com}   | {for local DB}|
+| {pnpm}    | {>= 9}  | {npm i -g pnpm}       |              |
+
+## Key Commands
+
+<!-- REQUIRED: The commands a developer runs every day. -->
+
+```bash
+{pnpm install}       # install dependencies
+{pnpm dev}           # start development server
+{pnpm build}         # build for production
+{pnpm test}          # run tests
+{pnpm lint}          # run linter
+{pnpm typecheck}     # type checking
+{pnpm db:migrate}    # apply database migrations
+{pnpm db:seed}       # seed database
+```
+
+## Package Manager
+
+- **Manager:** {pnpm / npm / yarn / bun}
+- **Lock file:** {pnpm-lock.yaml}
+- **Workspace:** {pnpm workspaces / turborepo / none}
+- **CI notes:** {e.g.: use --frozen-lockfile in CI}
+
+## Runtime
+
+| Item         | Version  | Notes                 |
+|--------------|----------|-----------------------|
+| {Node.js}    | {20 LTS} | {specified in .nvmrc} |
+| {TypeScript} | {5.x}    | {strict mode enabled} |
+
+## Frontend
+
+<!-- OPTIONAL: Delete if the project has no frontend. -->
+
+| Library / Framework | Version | Usage                    |
+|---------------------|---------|--------------------------|
+| {React}             | {18.x}  | {UI library}             |
+| {Next.js}           | {14.x}  | {framework -- app router}|
+| {Tailwind CSS}      | {3.x}   | {utility-first styling}  |
+
+## Backend
+
+<!-- OPTIONAL: Delete if the project has no backend. -->
+
+| Library / Framework | Version | Usage                |
+|---------------------|---------|----------------------|
+| {NestJS}            | {10.x}  | {API framework}      |
+| {Prisma}            | {5.x}   | {ORM + migrations}   |
+
+## Database
+
+| DB           | Version | Usage           | ORM / Driver | Notes          |
+|--------------|---------|-----------------|--------------|----------------|
+| {PostgreSQL} | {15}    | {primary store} | {Prisma}     |                |
+| {Redis}      | {7}     | {cache + queue} | {ioredis}    | {used by BullMQ}|
+
+## Infrastructure
+
+| Service       | Provider | Usage               |
+|---------------|----------|---------------------|
+| {ECS Fargate} | {AWS}    | {container hosting} |
+| {RDS}         | {AWS}    | {managed PostgreSQL}|
+| {S3}          | {AWS}    | {file uploads}      |
+
+## CI/CD Tooling
+
+| Tool / Service   | Config file               | Purpose                         |
+|------------------|---------------------------|---------------------------------|
+| {GitHub Actions} | {.github/workflows/*.yml} | {CI: lint, test, build, deploy} |
+| {Docker}         | {Dockerfile}              | {container build}               |
+
+## External Services (SaaS and APIs)
+
+<!-- REQUIRED: Every third-party service the app calls at runtime. -->
+
+| Service  | Purpose          | Auth      | Env var(s)          |
+|----------|------------------|-----------|---------------------|
+| {Stripe} | {payments}       | {API key} | {STRIPE_SECRET_KEY} |
+| {Sentry} | {error tracking} | {DSN}     | {SENTRY_DSN}        |
+
+## Development Tools
+
+| Tool          | Config file    | Purpose                       |
+|---------------|----------------|-------------------------------|
+| {ESLint}      | {.eslintrc.js} | {code linting}                |
+| {Prettier}    | {.prettierrc}  | {code formatting}             |
+| {Husky}       | {.husky/}      | {git hooks -- pre-commit lint}|
+| {lint-staged} | {.lintstagedrc}| {lint only staged files}      |
+
+## Packages That Influence Patterns
+
+<!-- REQUIRED: Libraries that dictate HOW code is written, not just what it does. -->
+
+| Package           | Why it matters                                               |
+|-------------------|--------------------------------------------------------------|
+| {zod}             | {all validation uses zod schemas -- never manual checks}     |
+| {react-hook-form} | {all forms use RHF + zod resolver}                           |
+| {prisma}          | {DB access always through generated client, never raw SQL}   |
+
+## Environment Variables
+
+| Variable       | Type     | Required | Default       |
+|----------------|----------|----------|---------------|
+| {DATABASE_URL} | {string} | {yes}    | {none}        |
+| {JWT_SECRET}   | {string} | {yes}    | {none}        |
+| {NODE_ENV}     | {enum}   | {no}     | {development} |
+| {PORT}         | {number} | {no}     | {3000}        |

package/src/templates/registry.csv

@@ -0,0 +1,19 @@
+command,display-name,menu-code,description,phase,after,before,required,outputs
+help,kc1t Help,H,Analyze project state and recommend next command,anytime,,,false,
+init-context,Init Context,IC,Configure context docs and integrations,1-setup,,,true,docs/*
+map-brownfield,Map Brownfield,MB,Scan existing codebase and generate documentation,1-setup,init-context,,true,docs/* + .kc1t/scan-state.json
+architect,Winston (Architect),AR,Architecture design readiness and project context,anytime,,,false,docs/architecture.md
+pm,John (PM),PM,PRD creation epics stories and scope,2-planning,init-context,,false,docs/prd.md + epics/*
+ux,Sally (UX),UX,UX design flows and consistency,2-planning,init-context,,false,docs/ux-design.md
+new-task,Party Mode,NT,Multi-persona collaborative task planning,2-planning,init-context,,true,epics/* + tasks/*
+dev,Dev Agent,DV,Execute task implementation with full discipline,3-implementation,new-task,,true,code changes + tasks/*
+quick-dev,Quick Dev,QD,Lightweight implement-review-present cycle,3-implementation,,,false,code changes
+quick-spec,Quick Spec,QS,Plan only — produce spec without implementing,3-implementation,,,false,tasks/spec-*.md
+review,Code Review,CR,Adversarial 3-layer code review,3-implementation,dev,,false,review report
+qa,Quinn (QA),QA,Test generation and risk assessment,3-implementation,,,false,test files
+debug,Bug Investigation,DB,Structured evidence-based bug investigation,anytime,,,false,tasks/TASK-fix-*.md
+standup,Daily Briefing,SU,Sprint status risks and priority suggestion,anytime,,,false,
+correct-course,Correct Course,CC,Mid-sprint change management,anytime,,,false,change proposal
+ask,Quick Question,AK,Project-aware conversational answer,anytime,,,false,
+devops,DevOps,DO,Deploy assessment infra audit observability,anytime,,,false,
+tech-writer,Paige (Tech Writer),TW,Documentation validation and diagram generation,anytime,,,false,docs/*

package/src/templates/templates/EPIC-template.md

@@ -0,0 +1,65 @@
+# EPIC-{N}: {title}
+
+**Status:** draft | in-progress | done | superseded
+**Created:** {date}
+**Last updated:** {date}
+**Azure DevOps:** #{ID} (if linked)
+
+---
+
+## Epic User Story
+
+As {user/system}
+I want {goal of the entire epic}
+So that {business value delivered}
+
+---
+
+## Objective
+
+{2-3 sentences describing what this epic delivers and why it exists now.}
+
+## Epic Done Criteria
+
+- [ ] {verifiable criterion}
+- [ ] {verifiable criterion}
+
+## Out of Scope
+
+- {what was discussed but consciously left out}
+
+---
+
+## Architecture Decisions
+
+> Recorded during /new-task sessions that generated this epic.
+
+- **{date} — {decision}:** {context and consequences}
+
+## References
+
+- PRD: `.kc1t/docs/prd.md#{section}` (if exists)
+- Architecture: `.kc1t/docs/architecture.md#{section}`
+- Brownfield: `.kc1t/docs/brownfield.md#{affected area}`
+
+---
+
+## Stories
+
+| # | Title | Status | Azure |
+|---|-------|--------|-------|
+| {N}.1 | {title} | ready | #{ID} |
+| {N}.2 | {title} | draft | — |
+| {N}.3 | {title} | draft | — |
+
+> Progressive generation — only expand the next story when the previous one is done.
+
+---
+
+## Iteration History
+
+### {date} — /new-task session
+{summary of what was discussed and decided}
+
+### {date} — /correct-course session (if any)
+{what changed and why}

package/src/templates/templates/TASK-template.md

@@ -0,0 +1,120 @@
+# TASK {N}.{M}: {title}
+
+**Status:** draft | ready | in-progress | done
+**Epic:** `.kc1t/epics/EPIC-{N}-{slug}.md`
+**Created:** {date}
+**Azure DevOps:** #{ID} (if linked)
+
+---
+
+## User Story
+
+As {user/system}
+I want {specific action for this task}
+So that {value delivered by this task}
+
+---
+
+## Context
+
+{1-2 sentences on where this task fits in the epic and why it comes in this order.}
+
+## Learnings from Previous Task
+
+> Automatically filled by /dev when completing task {N}.{M-1}
+> If first task in epic: "First task in epic — no prior learnings."
+
+{discoveries, patterns found, decisions that affect this task}
+
+---
+
+## Acceptance Criteria
+
+| # | Criterion | Source |
+|---|-----------|--------|
+| AC-1 | {specific, verifiable criterion} | epic #{N} |
+| AC-2 | {specific, verifiable criterion} | architecture §{section} |
+| AC-3 | {specific, verifiable criterion} | brownfield §{area} |
+
+---
+
+## Implementation
+
+### Affected Files
+
+| Action | File | Risk Area |
+|--------|------|-----------|
+| create | `src/modules/{x}/{y}.ts` | none |
+| modify | `src/modules/{x}/{z}.ts` | HIGH — see brownfield.md |
+
+### Technical Tasks
+
+- [ ] T1 — {what to do} `(AC: #1, #2)`
+- [ ] T2 — {what to do} `(AC: #3)`
+- [ ] T3 — {what to do} `(AC: #1)`
+
+### Dependencies
+
+```
+Depends on: TASK {N}.{M-1} — {reason}
+Next task depends on this: TASK {N}.{M+1} — {reason}
+```
+
+### Brownfield Risks
+
+- {risk identified by QA or ARCH during /new-task}
+- If none: "Low risk area."
+
+---
+
+## Dev Agent Record
+
+> Filled by /dev during and after implementation.
+
+**Started:** {date}
+**Completed:** {date}
+
+### What Was Implemented
+
+{description of what was done — different from planned? record here}
+
+### Code Decisions Made
+
+- {decision that wasn't in the plan but was necessary}
+
+### Deviations from Original Plan
+
+- {what changed and why} or "None."
+
+### Learnings for Next Task
+
+> This section is automatically copied to TASK {N}.{M+1}
+
+- {pattern discovered in the codebase}
+- {pitfall encountered}
+- {decision that impacts the next implementation}
+
+---
+
+## QA Risk Assessment
+
+> Automatically filled by /dev on completion (brownfield projects).
+> Skip if project.type = greenfield.
+
+**Regression probability:** low | medium | high
+**Affected systems:** {list}
+**Rollback complexity:** low | medium | high
+**Test strategy:** {what specifically needs to be tested}
+
+---
+
+## Done Checklist
+
+- [ ] All ACs met
+- [ ] Technical tasks completed
+- [ ] Coding-standards patterns followed
+- [ ] No "do not change" area touched without confirmation
+- [ ] Dev Agent Record filled
+- [ ] Learnings written for next task
+- [ ] QA risk assessment done (brownfield)
+- [ ] Azure card updated (if linked)

package/src/templates/templates/deferred-work.md

@@ -0,0 +1,7 @@
+# Deferred Work
+
+> Items discovered during implementation that are out of scope for the current task.
+> Review periodically. Convert to tasks when ready.
+
+| # | Source | Description | Discovered during | Priority | Status |
+|---|--------|-------------|-------------------|----------|--------|