volt-framework 0.1.0

package/src/templates/commands/map-brownfield/checklist.md

@@ -0,0 +1,66 @@
+# Map Brownfield -- Validation Checklist
+
+Before marking the workflow as complete, verify every item below.
+
+---
+
+## Scan and Resumability
+
+- [ ] State file created at workflow start and updated after each sub-phase
+- [ ] State file contains all required fields per schema
+- [ ] Resumability prompt shown if state file exists and is < 24 hours old
+- [ ] Old state files (> 24 hours) automatically archived
+- [ ] Resume functionality loads previous state correctly and jumps to correct phase
+
+## Write-as-you-go Architecture
+
+- [ ] Each document written to disk IMMEDIATELY after generation
+- [ ] Document validation performed right after writing (section-level)
+- [ ] Detailed findings purged from context after writing (only summaries kept)
+- [ ] No accumulation of full project analysis in memory
+
+## Project Detection and Classification
+
+- [ ] Project type correctly identified and matches actual technology stack
+- [ ] Multi-part vs single-part structure accurately detected
+- [ ] Conditional documents correctly flagged (API contracts, data models)
+
+## Pattern Validation
+
+- [ ] All conflicts presented to user with evidence and percentages
+- [ ] User decisions recorded for every conflict
+- [ ] Non-conflicting patterns confirmed by user
+- [ ] No patterns remain as "uncertain" after Phase 3
+
+## Document Quality
+
+- [ ] All documents saved to `.kc1t/docs/`
+- [ ] Each document has generation header with date and version
+- [ ] No generic placeholders or TODO items remain
+- [ ] Mermaid diagrams included where applicable
+- [ ] File paths and references are correct
+- [ ] Terminology consistent across all documents
+
+## Brownfield Context Specific
+
+- [ ] "What NOT to change" section is comprehensive and user-validated
+- [ ] User was explicitly asked about untouchable areas
+- [ ] Tech debt prioritized by severity
+- [ ] Scope classification included
+
+## File Completeness
+
+- [ ] Architecture generated
+- [ ] Source Tree generated
+- [ ] Coding Standards generated
+- [ ] Brownfield Context generated and user-validated
+- [ ] `api-contracts.md` generated (if APIs detected)
+- [ ] `data-models.md` generated (if database detected)
+- [ ] `deep-dive-{area}.md` generated (if deep-dive mode used)
+
+## Brownfield PRD Readiness
+
+- [ ] Documentation provides enough context for AI to understand existing system
+- [ ] Reusable components identified for leveraging in new work
+- [ ] Architecture constraints clear for informed decision-making
+- [ ] Code conventions captured for consistency in future tasks

package/src/templates/commands/map-brownfield/steps/step-00-state-check.md

@@ -0,0 +1,69 @@
+# Step 00: State Check & Mode Router
+
+## RULES
+
+- You are a state machine router -- determine workflow mode and delegate to the correct phase.
+- HALT at every user prompt and wait for their response before proceeding.
+- Never auto-proceed without user confirmation when no CLI argument is provided.
+- Never overwrite an existing state file without archiving it first.
+- Every state file mutation must record: phase id, sub-phase id, human-readable summary, timestamp, and outputs written.
+
+## INSTRUCTIONS
+
+1. **Check for existing state.** Look for `.kc1t/scan-state.json` in the project root.
+   - If it does not exist, set `resume_mode = false` and go to step 3.
+
+2. **Route based on state.** Read the file and extract `lastUpdatedAt`, `mode`, `currentPhase`, `currentSubPhase`, `completedPhases`, `classification`, `status`.
+
+   **If age >= 24 hours:** Archive to `.kc1t/.archive/scan-state-{timestamp}.json`. Inform the user the old state was archived. Set `resume_mode = false`, go to step 3.
+
+   **If status == "completed":** Present options:
+   - `[1]` Incremental rescan -- update only what changed
+   - `[2]` Deep-dive -- exhaustive analysis of a specific area
+   - `[3]` Start over from scratch (archives old state)
+   - `[4]` Cancel -- keep existing documentation
+
+   HALT. On 1: set `mode = "rescan"`, continue to step 01. On 2: set `mode = "deep-dive"`, jump to step 02 deep-dive section. On 3: archive and go to step 3. On 4: exit.
+
+   **If status == "in-progress":** Present options:
+   - `[1]` Resume from Phase {currentPhase}, sub-phase {currentSubPhase}
+   - `[2]` Start over from scratch (archives old state)
+   - `[3]` Cancel
+
+   HALT. On 1: load findings summaries and cached classification, jump to recorded phase/sub-phase. On 2: archive and go to step 3. On 3: exit.
+
+3. **Mode selection (fresh starts).** If mode was passed as CLI argument (`initial`, `rescan`, `deep-dive`), use it directly. Otherwise present:
+   - `[1]` Initial scan -- full scan from scratch (recommended for first time)
+   - `[2]` Deep-dive -- exhaustive analysis of a specific module/area
+
+   HALT. On 1: set `mode = "initial"`. On 2: set `mode = "deep-dive"`, jump to step 02 deep-dive section.
+
+4. **Initialize state file.** Create `.kc1t/` if missing. Write `.kc1t/scan-state.json`:
+   ```json
+   {
+     "version": "1.0",
+     "projectName": "",
+     "startedAt": "{timestamp}",
+     "lastUpdatedAt": "{timestamp}",
+     "currentPhase": 1,
+     "currentSubPhase": "1.0",
+     "completedPhases": [],
+     "mode": "{mode}",
+     "status": "in-progress",
+     "classification": {},
+     "conditionalDocs": { "apiContracts": false, "dataModels": false },
+     "modulesScanned": [],
+     "modulesRemaining": [],
+     "conflicts": [],
+     "userDecisions": [],
+     "scopeClassification": "",
+     "documentsGenerated": [],
+     "scanMetrics": { "totalFiles": 0, "totalModules": 0, "estimatedLines": 0, "externalDependencies": 0 }
+   }
+   ```
+
+If the user wants to discuss or go deeper on any point, shift to interactive mode. Otherwise, proceed.
+
+## NEXT
+
+Read fully and follow `./step-01-classify.md`.

package/src/templates/commands/map-brownfield/steps/step-01-classify.md

@@ -0,0 +1,51 @@
+# Step 01: Project Classification
+
+## RULES
+
+- Detect every manifest, config, and infrastructure file to build an accurate classification.
+- Present classification to the user for confirmation before proceeding -- never assume correctness.
+- If evidence is insufficient for a dimension, mark it as "unknown" and ask the user. Never guess.
+- Always check for multi-part structures, even for seemingly simple projects.
+- Save classification to state only after user confirmation.
+
+## INSTRUCTIONS
+
+1. **Detect project manifests.** Search root and up to 2 levels deep for:
+   - Package manifests: `package.json`, `composer.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`, `Gemfile`, `*.csproj`, `setup.py`
+   - Language configs: `tsconfig.json`, `jsconfig.json`, `.python-version`, `rust-toolchain.toml`, `.nvmrc`
+   - Infrastructure: `Dockerfile`, `docker-compose.yml`, `.env.example`, `terraform/`, `serverless.yml`
+   - Framework configs: `next.config.*`, `nuxt.config.*`, `angular.json`, `vite.config.*`, `nest-cli.json`, `remix.config.*`, `astro.config.*`, `svelte.config.*`
+   - CI/CD: `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `.circleci/`, `azure-pipelines.yml`
+   - Linter/formatter: `.eslintrc*`, `.prettierrc*`, `biome.json`, `.editorconfig`, `ruff.toml`, `.golangci.yml`
+
+   For each detected file, extract key fields (dependencies, scripts, compiler options).
+
+2. **Classify across 8 dimensions.** For each dimension, record the evidence source (which file and field):
+
+   | Dimension | Examples |
+   |---|---|
+   | Type | frontend, backend, fullstack, monorepo, library, CLI, worker, mobile |
+   | Language | TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby |
+   | Framework | Next.js, NestJS, Express, FastAPI, Django, Rails, Spring, Laravel |
+   | Package Manager | npm, yarn, pnpm, bun, pip, poetry, cargo, go modules, maven |
+   | Database | PostgreSQL, MySQL, MongoDB, Redis, SQLite, DynamoDB |
+   | ORM | Prisma, TypeORM, Drizzle, SQLAlchemy, GORM, ActiveRecord |
+   | Tests | Jest, Vitest, Pytest, Go test, JUnit, RSpec, Cypress, Playwright |
+   | Infrastructure | Docker, Kubernetes, Serverless, Vercel, AWS, GCP, Azure |
+
+3. **Detect multi-part structure.** Determine if the project is monolith, monorepo, or multi-part (e.g. `client/` + `server/`). If multiple parts are detected, list them with paths and ask the user to confirm. HALT. If single project, set `repository_type = "monolith"`.
+
+4. **Set conditional document flags.**
+   - HTTP endpoints detected (routes, controllers, API handlers) -> `conditionalDocs.apiContracts = true`
+   - Database detected (ORM config, migrations, schema files) -> `conditionalDocs.dataModels = true`
+
+5. **Present and confirm.** Show classification in a compact table with evidence. Ask: `Is this classification correct? [y/n/edit]`. HALT.
+   - y: proceed. n: ask what is wrong, correct, re-present. edit: ask which dimension to change.
+
+6. **Save state.** Update `scan-state.json` with classification, conditionalDocs, completedPhases entry, set `currentPhase = 2`, `currentSubPhase = "2.1"`. Purge detailed scan data from memory -- keep only the summary string.
+
+If the user wants to discuss or go deeper on any point, shift to interactive mode. Otherwise, proceed.
+
+## NEXT
+
+Read fully and follow `./step-02-scan.md`.

package/src/templates/commands/map-brownfield/steps/step-02-scan.md

@@ -0,0 +1,126 @@
+# Step 02: Scan Execution
+
+## RULES
+
+- Complete every sub-scan (2.1 through 2.7) unless its precondition is not met.
+- Update state after every sub-scan with `currentSubPhase`, timestamp, and a precise summary.
+- After each sub-scan: write findings, then purge detailed data from context -- keep only 1-2 sentence summaries.
+- Respect mode depth: initial reads excerpts, rescan reads diffs only, deep-dive reads everything (no sampling).
+- In deep-dive mode, halt after each module batch for user review before continuing.
+- Exclude from all scans: `node_modules/`, `.git/`, `dist/`, `build/`, `coverage/`, `*.min.js`, `*.map`.
+
+## INSTRUCTIONS
+
+**Mode behavior:**
+- **Initial**: Read relevant excerpts (imports, exports, signatures). Do not read entire files.
+- **Rescan**: Execute only for modified modules (via `git diff` or timestamps). Skip unchanged.
+- **Deep-dive**: Every file read in full. No sampling, no guessing. Organize batches by subfolder: read files, extract info, write output, validate, purge context, move on.
+
+### 2.1 -- Structure Scan
+
+1. Generate directory tree (3 levels in initial/rescan, unlimited in deep-dive).
+2. Classify organizational pattern: feature-based, layer-based, domain-driven, mixed.
+3. Identify ambiguous directories (empty, single-file, overlapping purpose).
+4. Map special directories: config, scripts, migrations, seeds, assets, public, tests.
+
+Inform user: "Sub-scan 2.1 (Structure) complete." Update state.
+
+### 2.2 -- Module & Responsibility Scan
+
+1. List each module/feature with its inferred purpose (1 sentence).
+2. Map inter-module dependencies (who imports whom).
+3. Detect circular dependencies.
+4. Calculate fan-in / fan-out for each module.
+5. In deep-dive: list all public exports and their consumers.
+
+Inform user: "Sub-scan 2.2 (Modules) complete." Update state.
+
+### 2.3 -- Code Pattern Scan
+
+1. **Naming**: Convention by context (files, variables, functions, classes, constants). Adherence % and exceptions.
+2. **File structure**: Internal organization pattern (import order, types, constants, functions, export).
+3. **Functions**: Average size in lines. Functions exceeding 50 lines (list file + name).
+4. **Error handling**: Categorize (try/catch, error boundaries, Result pattern, custom errors). Percentage of each.
+5. **Logging**: console.log vs custom logger vs external service. Structured vs unstructured.
+6. **Validation**: Zod, Joi, class-validator, manual. Where in the call chain.
+7. **Imports**: Absolute vs relative. Barrel exports. Path aliases.
+
+In deep-dive: 3+ concrete examples with file path and snippet for each pattern. Flag conflicts for step 03.
+
+Inform user: "Sub-scan 2.3 (Patterns) complete." Update state.
+
+### 2.4 -- API & Contract Scan (Conditional)
+
+Skip if `conditionalDocs.apiContracts == false`. Inform user and move on.
+
+1. List endpoints: HTTP method, path, handler location.
+2. Classify route organization (by resource, feature, version).
+3. Identify middleware chain (auth, validation, logging, rate limiting, CORS).
+4. Detect response pattern (envelope, status codes, error format).
+5. Check for existing docs (Swagger/OpenAPI, GraphQL schema).
+6. In deep-dive: document request/response body for each main endpoint.
+
+Inform user: "Sub-scan 2.4 (APIs) complete." Update state.
+
+### 2.5 -- Data Model Scan (Conditional)
+
+Skip if `conditionalDocs.dataModels == false`. Inform user and move on.
+
+1. List entities/models with fields and types.
+2. Map relationships (1:1, 1:N, N:N).
+3. Identify migration and seed patterns.
+4. Classify data access pattern (repository, active record, service layer, raw queries).
+5. In deep-dive: document indexes, constraints, triggers, defaults.
+
+Inform user: "Sub-scan 2.5 (Data Models) complete." Update state.
+
+### 2.6 -- Tech Debt Scan
+
+1. Search for `TODO`, `FIXME`, `HACK`, `XXX`, `WORKAROUND` comments with locations.
+2. Identify commented-out code blocks (>5 lines).
+3. List functions >50 lines and files >300 lines.
+4. Check for outdated or deprecated dependencies.
+5. Identify areas without test coverage.
+6. Detect code smells: god objects, feature envy, shotgun surgery, long parameter lists.
+7. Classify each finding by severity: high (operational risk), medium (maintainability), low (cosmetic).
+
+Inform user: "Sub-scan 2.6 (Tech Debt) complete." Update state.
+
+### 2.7 -- Dependency Analysis
+
+1. Separate production vs development dependencies.
+2. Identify known vulnerabilities (via audit if possible).
+3. Detect abandoned dependencies (>2 years without update).
+4. Identify functional duplications (libraries doing the same thing).
+5. Estimate bundle weight for frontend projects.
+6. List critical dependencies (used in >50% of modules).
+
+Inform user: "Sub-scan 2.7 (Dependencies) complete. Phase 2 complete." Update state.
+
+### Deep-Dive Module Pause
+
+In deep-dive mode, after each module/subfolder batch present:
+- `[1]` View details before continuing
+- `[2]` Continue to next module
+- `[3]` Mark as sensitive area (goes to "What NOT to change" in brownfield.md)
+
+HALT and wait before proceeding.
+
+### Deep-Dive Area Analysis
+
+When `mode = "deep-dive"`, this replaces standard sub-scans:
+
+1. **Select target area.** Present detected modules with file counts. Accept folder path, file path, or feature name. HALT for confirmation.
+2. **Exhaustive scan.** Read every line. Document: purpose, exports, imports, dependents, side effects, error handling, test coverage, TODOs, per-file risks.
+3. **Relationship analysis.** Build dependency graph, trace data flow, identify integration points.
+4. **Related code discovery.** Search outside scanned area for similar patterns and reusable utilities.
+5. **Generate document.** Write to `.kc1t/docs/deep-dive-{target_name}.md`.
+6. **Continue or complete.** `[1]` Deep-dive another area, `[2]` Continue to step 03. HALT.
+
+Mark Phase 2 complete. Update `completedPhases`, set `currentPhase = 3`.
+
+If the user wants to discuss or go deeper on any point, shift to interactive mode. Otherwise, proceed.
+
+## NEXT
+
+Read fully and follow `./step-03-validate.md`.

package/src/templates/commands/map-brownfield/steps/step-03-validate.md

@@ -0,0 +1,44 @@
+# Step 03: Pattern Conflict Validation
+
+## RULES
+
+- No pattern may remain as "uncertain" or "conflicting" after this step completes.
+- Never resolve a conflict on the user's behalf -- every conflict requires an explicit user decision.
+- Present at least 2 concrete code examples (file path + snippet) per competing pattern in a conflict.
+- Record every user decision with category, question, decision, rationale, and timestamp.
+- Do not proceed to step 04 until all conflicts are resolved and all patterns are confirmed.
+
+## INSTRUCTIONS
+
+1. **Present structured pattern summary.** Group all detected patterns by category (naming, error handling, file organization, validation, logging, imports) with adherence percentages and evidence. Mark conflicts clearly.
+
+   Present options:
+   - `[1]` Confirm all non-conflicting patterns (proceed to conflict resolution only)
+   - `[2]` Review one by one
+   - `[3]` Add a pattern manually
+
+   HALT and wait.
+
+2. **Resolve conflicts.** For each conflict, present it in isolation with full evidence:
+   - Show Pattern A and Pattern B with percentages and 2-3 concrete code examples each (file path + snippet).
+   - Ask which is the official pattern:
+     - `[A]` Pattern A is the standard
+     - `[B]` Pattern B is the standard
+     - `[C]` Both are accepted (document when to use each)
+     - `[D]` Neither -- specify a different approach
+
+   HALT after each conflict. Record the decision:
+   ```json
+   { "category": "...", "question": "...", "decision": "...", "rationale": "...", "decidedAt": "..." }
+   ```
+
+3. **Confirm final pattern list.** Present the complete confirmed pattern list. Ask: `Is this correct, or does anything need adjustment? [y/n/edit]`. HALT.
+   - y: proceed. n/edit: ask which pattern to adjust, record correction.
+
+4. **Save state.** Update `scan-state.json`: store `conflicts` array, `userDecisions` array, add completedPhases entry with summary, set `currentPhase = 4`, `currentSubPhase = "4.1"`.
+
+If the user wants to discuss or go deeper on any point, shift to interactive mode. Otherwise, proceed.
+
+## NEXT
+
+Read fully and follow `./step-04-generate.md`.

package/src/templates/commands/map-brownfield/steps/step-04-generate.md

@@ -0,0 +1,89 @@
+# Step 04: Document Generation
+
+## RULES
+
+- Write each document to disk immediately after generation. Do not accumulate all documents in memory.
+- After writing each document: validate structure, update state, purge detailed findings from context.
+- Include the header `<!-- Generated by map-brownfield | Date: {date} | Version: {version} -->` in every document.
+- The brownfield.md user review is mandatory -- never skip it.
+- Conditional documents (api-contracts, data-models) are only generated when their flag is true.
+
+## INSTRUCTIONS
+
+Generate up to 6 documents (4 mandatory + 2 conditional) into `.kc1t/docs/`. After each, ask: `Review now or continue? [review/continue]`. HALT.
+
+### 4.1 -- `architecture.md`
+
+Generate:
+- High-level architecture pattern (MVC, Clean, Hexagonal, Layered, Event-Driven, etc.)
+- Module relationship diagram (Mermaid `graph TD` or `flowchart LR`) -- at least one diagram required
+- Main data flow (request lifecycle)
+- Detected architectural decisions (implicit ADRs)
+- Entry points (HTTP server, CLI, workers, cron)
+- External service integrations (APIs, databases, queues, caches)
+- Deployment architecture from config files
+
+Write to `.kc1t/docs/architecture.md`. Validate. Update state. Purge.
+
+### 4.2 -- `source-tree.md`
+
+Generate:
+- Complete directory tree with purpose annotation per directory
+- Key files highlighted and described (entry points, config, main modules)
+- Organization convention explained
+- Entry points marked, integration paths noted for multi-part projects
+
+Write to `.kc1t/docs/source-tree.md`. Validate. Update state. Purge.
+
+### 4.3 -- `coding-standards.md`
+
+Generate with concrete codebase examples for every pattern:
+- Naming conventions with file paths and snippets
+- File structure patterns (import order, types, export style)
+- Error handling approach (including Phase 3 conflict resolutions)
+- Logging, validation, testing patterns
+- Import/export conventions
+- All user decisions from Phase 3 with rationale
+
+Write to `.kc1t/docs/coding-standards.md`. Validate. Update state. Purge.
+
+### 4.4 -- `brownfield.md` (Main Document)
+
+This is the most important document -- primary reference for all future development.
+
+Structure:
+- **Executive summary** (3-5 lines): what the project is, its state, its health
+- **Classification and Scope**: Phase 1 table + Phase 5 scope metrics
+- **Current state**: overall health (good / acceptable / concerning) with justification
+- **"What NOT to change"**: established patterns, explicit user decisions, sensitive areas, protected dependencies
+- **"What to improve"**: tech debt by severity (high/medium/low) with estimated effort
+- **"Known risks"**: problematic dependencies, fragile areas, security concerns, missing tests
+- **"Suggested next steps"**: prioritized by impact vs effort
+
+Write to `.kc1t/docs/brownfield.md`. Validate. Update state. Purge.
+
+Present the full draft. Ask: **"Please review brownfield.md carefully. Is there anything in this project you consider untouchable? Anything that should NOT be refactored, even if it looks like tech debt?"** HALT. Incorporate the answer into "What NOT to change" and rewrite.
+
+### 4.5 -- `api-contracts.md` (Conditional)
+
+Skip if `conditionalDocs.apiContracts == false`. Log skip reason in state.
+
+Generate: endpoints (method, path, handler, description), request/response patterns, auth requirements, middleware chain, versioning, error format.
+
+Write to `.kc1t/docs/api-contracts.md`. Validate. Update state. Purge.
+
+### 4.6 -- `data-models.md` (Conditional)
+
+Skip if `conditionalDocs.dataModels == false`. Log skip reason in state.
+
+Generate: entities with fields/types/constraints, relationships (list + Mermaid ER diagram), migration patterns, indexes, data access pattern.
+
+Write to `.kc1t/docs/data-models.md`. Validate. Update state. Purge.
+
+Mark Phase 4 complete. Update `documentsGenerated` in state.
+
+If the user wants to discuss or go deeper on any point, shift to interactive mode. Otherwise, proceed.
+
+## NEXT
+
+Read fully and follow `./step-05-scope.md`.

package/src/templates/commands/map-brownfield/steps/step-05-scope.md

@@ -0,0 +1,50 @@
+# Step 05: Scope Classification and Completion
+
+## RULES
+
+- Classify project size from actual metrics in the state file -- never estimate from memory.
+- Do not declare the workflow complete without running the validation checklist.
+- The final "untouchable areas" prompt is a safety net -- never skip it.
+- Save scope classification to both state file and brownfield.md.
+
+## INSTRUCTIONS
+
+1. **Classify project size.** Read metrics from `scan-state.json`:
+
+   | Classification | Files | Modules | Typical Team |
+   |---|---|---|---|
+   | Small | < 50 | < 5 | 1 developer |
+   | Medium | 50-200 | 5-15 | 2-5 developers |
+   | Large | 200-1000 | 15-50 | 5-15 developers |
+   | Very Large | > 1000 | > 50 | Multiple teams |
+
+   Record: total code files, total modules, estimated LOC, external dependency count (production).
+
+2. **Save scope.** Update `scan-state.json` with `scopeClassification` and `scanMetrics`. Update `brownfield.md` "Classification and Scope" section with metrics table.
+
+3. **Present future workflow guidance** tailored to scope:
+   - **Small**: Bug fix -> /quick-dev. New feature -> /new-task (lean mode).
+   - **Medium**: Bug fix -> /quick-dev. Small feature (1-3 tasks) -> /new-task lean. Larger -> /new-task full + QA.
+   - **Large / Very Large**: Bug fix -> /quick-dev with brownfield context. Any feature -> /new-task full + QA. Cross-module -> mandatory architecture review.
+
+   Recommend running `/map-brownfield rescan` after significant changes.
+
+4. **Final untouchable areas prompt.** Ask: **"Is there anything in this project you consider untouchable? Anything that should NOT be refactored, even if it looks like tech debt?"** HALT.
+   - If items provided: incorporate into brownfield.md "What NOT to change" and rewrite.
+   - If nothing to add: acknowledge and proceed.
+
+5. **Mark scan complete.** Update state: `status = "completed"`, `lastUpdatedAt`, add completedPhases entry.
+
+6. **Run validation checklist.** Read and execute `../checklist.md`. Verify every item. If any fail, report which and offer to fix. Do not declare complete until all pass.
+
+   Present final summary: list all generated documents with paths, scan status, and classification.
+
+If the user wants to discuss or go deeper on any point, shift to interactive mode. Otherwise, proceed.
+
+## NEXT
+
+This is the final step. The documentation in `.kc1t/docs/` is now available for all future workflow commands.
+
+## Handoff Protocol
+
+Recommend: `/new-task` (greenfield) or `/init-context` (if docs incomplete) in fresh chat. Fresh context avoids anchoring bias from this session.

package/src/templates/commands/map-brownfield/workflow.md

@@ -0,0 +1,77 @@
+# Map Brownfield -- Workflow
+
+## Execution Modes
+
+| Invocation | Behavior |
+|---|---|
+| `/map-brownfield` | Ask the user which mode to run |
+| `/map-brownfield initial` | Full scan from scratch |
+| `/map-brownfield rescan` | Update only what changed since last scan |
+| `/map-brownfield deep-dive` | Exhaustive module-by-module analysis (full file reads, no sampling) |
+
+## Step Processing Rules
+
+- Read the entire step before acting.
+- Execute sections in order. No skipping.
+- Halt at checkpoints and wait for the user.
+- Only load the next step when directed.
+
+## Initialization
+
+1. Check for `.kc1t/` directory. Create if missing.
+2. Check for `.kc1t/docs/` directory. Create if missing.
+3. Load `.kc1t/config.yaml` if it exists. Extract: `project_name`, `language`, `user_name`.
+4. Set `date` as current datetime.
+5. Proceed to Step 00.
+
+## Step Sequence
+
+| Step | File | Description |
+|------|------|-------------|
+| 00 | `./steps/step-00-state-check.md` | State check and mode router |
+| 01 | `./steps/step-01-classify.md` | Project classification |
+| 02 | `./steps/step-02-scan.md` | Scan execution (initial, rescan, deep-dive) |
+| 03 | `./steps/step-03-validate.md` | Pattern conflict validation |
+| 04 | `./steps/step-04-generate.md` | Document generation |
+| 05 | `./steps/step-05-scope.md` | Scope classification and completion |
+
+## Interaction Flow
+
+1. Greet the user. Briefly explain the command's purpose.
+2. **Step 00**: Check state, offer resume if applicable, select mode.
+3. **Step 01**: Classify project, request confirmation.
+4. **Step 02**: Execute sub-scans, inform progress at each. (Or deep-dive: exhaustive area analysis.)
+5. **Step 03**: Present patterns, resolve conflicts one by one.
+6. **Step 04**: Generate documents, offer review. Present brownfield.md for validation.
+7. **Step 05**: Classify scope, present metrics, final untouchable-areas prompt.
+8. Mark scan complete.
+
+## Special Project Handling
+
+**Monorepos**: Map each package individually. Map inter-package dependencies. Generate per-package docs + consolidated overview.
+
+**No framework**: Focus on custom structure. Identify homegrown patterns that act as an internal framework. Document conventions with extra care.
+
+**Multi-language**: Map each language separately. Identify integration points (FFI, API calls, shared schemas, protobuf). Document which language owns which responsibility.
+
+## State Management
+
+File: `.kc1t/scan-state.json`. After each sub-phase, update `lastUpdatedAt`, `currentPhase`, `currentSubPhase`, and relevant arrays. This guarantees granular resume. See step-00 for the full schema.
+
+## Document Output Format
+
+- Valid Markdown with hierarchical headings.
+- Code blocks with language specified. Mermaid diagrams when applicable.
+- Header: `<!-- Generated by map-brownfield | Date: {date} | Version: {version} -->`
+- No generic placeholders or TODO items in final output.
+- Terminology consistent across all documents. File paths verified.
+
+## Implementation Notes
+
+- Read priority: configs > entrypoints > services/controllers > models > utils > tests.
+- Initial/rescan: read relevant excerpts. Deep-dive: read every file in full.
+- Write-as-you-go: write each document immediately, validate, purge detailed findings.
+- Large projects: process in module batches, save progress frequently.
+- Weight patterns by frequency. A single isolated file does not define a pattern.
+
+After completing all steps, run the validation checklist: `./checklist.md`