cap-pro 1.0.0

package/cap/templates/UAT.md

@@ -0,0 +1,265 @@
+# UAT Template
+
+Template for `.planning/phases/XX-name/{phase_num}-UAT.md` — persistent UAT session tracking.
+
+---
+
+## File Template
+
+```markdown
+---
+status: testing | partial | complete | diagnosed
+phase: XX-name
+source: [list of SUMMARY.md files tested]
+started: [ISO timestamp]
+updated: [ISO timestamp]
+---
+
+## Current Test
+<!-- OVERWRITE each test - shows where we are -->
+
+number: [N]
+name: [test name]
+expected: |
+  [what user should observe]
+awaiting: user response
+
+## Tests
+
+### 1. [Test Name]
+expected: [observable behavior - what user should see]
+result: [pending]
+
+### 2. [Test Name]
+expected: [observable behavior]
+result: pass
+
+### 3. [Test Name]
+expected: [observable behavior]
+result: issue
+reported: "[verbatim user response]"
+severity: major
+
+### 4. [Test Name]
+expected: [observable behavior]
+result: skipped
+reason: [why skipped]
+
+### 5. [Test Name]
+expected: [observable behavior]
+result: blocked
+blocked_by: server | physical-device | release-build | third-party | prior-phase
+reason: [why blocked]
+
+...
+
+## Summary
+
+total: [N]
+passed: [N]
+issues: [N]
+pending: [N]
+skipped: [N]
+blocked: [N]
+
+## Gaps
+
+<!-- YAML format for plan-phase --gaps consumption -->
+- truth: "[expected behavior from test]"
+  status: failed
+  reason: "User reported: [verbatim response]"
+  severity: blocker | major | minor | cosmetic
+  test: [N]
+  root_cause: ""     # Filled by diagnosis
+  artifacts: []      # Filled by diagnosis
+  missing: []        # Filled by diagnosis
+  debug_session: ""  # Filled by diagnosis
+```
+
+---
+
+<section_rules>
+
+**Frontmatter:**
+- `status`: OVERWRITE - "testing", "partial", or "complete"
+- `phase`: IMMUTABLE - set on creation
+- `source`: IMMUTABLE - SUMMARY files being tested
+- `started`: IMMUTABLE - set on creation
+- `updated`: OVERWRITE - update on every change
+
+**Current Test:**
+- OVERWRITE entirely on each test transition
+- Shows which test is active and what's awaited
+- On completion: "[testing complete]"
+
+**Tests:**
+- Each test: OVERWRITE result field when user responds
+- `result` values: [pending], pass, issue, skipped, blocked
+- If issue: add `reported` (verbatim) and `severity` (inferred)
+- If skipped: add `reason` if provided
+- If blocked: add `blocked_by` (tag) and `reason` (if provided)
+
+**Summary:**
+- OVERWRITE counts after each response
+- Tracks: total, passed, issues, pending, skipped
+
+**Gaps:**
+- APPEND only when issue found (YAML format)
+- After diagnosis: fill `root_cause`, `artifacts`, `missing`, `debug_session`
+- This section feeds directly into /gsd:plan-phase --gaps
+
+</section_rules>
+
+<diagnosis_lifecycle>
+
+**After testing complete (status: complete), if gaps exist:**
+
+1. User runs diagnosis (from verify-work offer or manually)
+2. diagnose-issues workflow spawns parallel debug agents
+3. Each agent investigates one gap, returns root cause
+4. UAT.md Gaps section updated with diagnosis:
+   - Each gap gets `root_cause`, `artifacts`, `missing`, `debug_session` filled
+5. status → "diagnosed"
+6. Ready for /gsd:plan-phase --gaps with root causes
+
+**After diagnosis:**
+```yaml
+## Gaps
+
+- truth: "Comment appears immediately after submission"
+  status: failed
+  reason: "User reported: works but doesn't show until I refresh the page"
+  severity: major
+  test: 2
+  root_cause: "useEffect in CommentList.tsx missing commentCount dependency"
+  artifacts:
+    - path: "src/components/CommentList.tsx"
+      issue: "useEffect missing dependency"
+  missing:
+    - "Add commentCount to useEffect dependency array"
+  debug_session: ".planning/debug/comment-not-refreshing.md"
+```
+
+</diagnosis_lifecycle>
+
+<lifecycle>
+
+**Creation:** When /gsd:verify-work starts new session
+- Extract tests from SUMMARY.md files
+- Set status to "testing"
+- Current Test points to test 1
+- All tests have result: [pending]
+
+**During testing:**
+- Present test from Current Test section
+- User responds with pass confirmation or issue description
+- Update test result (pass/issue/skipped)
+- Update Summary counts
+- If issue: append to Gaps section (YAML format), infer severity
+- Move Current Test to next pending test
+
+**On completion:**
+- status → "complete"
+- Current Test → "[testing complete]"
+- Commit file
+- Present summary with next steps
+
+**Partial completion:**
+- status → "partial" (if pending, blocked, or unresolved skipped tests remain)
+- Current Test → "[testing paused — {N} items outstanding]"
+- Commit file
+- Present summary with outstanding items highlighted
+
+**Resuming partial session:**
+- `/gsd:verify-work {phase}` picks up from first pending/blocked test
+- When all items resolved, status advances to "complete"
+
+**Resume after /clear:**
+1. Read frontmatter → know phase and status
+2. Read Current Test → know where we are
+3. Find first [pending] result → continue from there
+4. Summary shows progress so far
+
+</lifecycle>
+
+<severity_guide>
+
+Severity is INFERRED from user's natural language, never asked.
+
+| User describes | Infer |
+|----------------|-------|
+| Crash, error, exception, fails completely, unusable | blocker |
+| Doesn't work, nothing happens, wrong behavior, missing | major |
+| Works but..., slow, weird, minor, small issue | minor |
+| Color, font, spacing, alignment, visual, looks off | cosmetic |
+
+Default: **major** (safe default, user can clarify if wrong)
+
+</severity_guide>
+
+<good_example>
+```markdown
+---
+status: diagnosed
+phase: 04-comments
+source: 04-01-SUMMARY.md, 04-02-SUMMARY.md
+started: 2025-01-15T10:30:00Z
+updated: 2025-01-15T10:45:00Z
+---
+
+## Current Test
+
+[testing complete]
+
+## Tests
+
+### 1. View Comments on Post
+expected: Comments section expands, shows count and comment list
+result: pass
+
+### 2. Create Top-Level Comment
+expected: Submit comment via rich text editor, appears in list with author info
+result: issue
+reported: "works but doesn't show until I refresh the page"
+severity: major
+
+### 3. Reply to a Comment
+expected: Click Reply, inline composer appears, submit shows nested reply
+result: pass
+
+### 4. Visual Nesting
+expected: 3+ level thread shows indentation, left borders, caps at reasonable depth
+result: pass
+
+### 5. Delete Own Comment
+expected: Click delete on own comment, removed or shows [deleted] if has replies
+result: pass
+
+### 6. Comment Count
+expected: Post shows accurate count, increments when adding comment
+result: pass
+
+## Summary
+
+total: 6
+passed: 5
+issues: 1
+pending: 0
+skipped: 0
+
+## Gaps
+
+- truth: "Comment appears immediately after submission in list"
+  status: failed
+  reason: "User reported: works but doesn't show until I refresh the page"
+  severity: major
+  test: 2
+  root_cause: "useEffect in CommentList.tsx missing commentCount dependency"
+  artifacts:
+    - path: "src/components/CommentList.tsx"
+      issue: "useEffect missing dependency"
+  missing:
+    - "Add commentCount to useEffect dependency array"
+  debug_session: ".planning/debug/comment-not-refreshing.md"
+```
+</good_example>

package/cap/templates/claude-md.md

@@ -0,0 +1,175 @@
+# CLAUDE.md Template
+
+Template for project-root `CLAUDE.md` — auto-generated by `gsd-tools generate-claude-md`.
+
+Contains 6 marker-bounded sections. Each section is independently updatable.
+The `generate-claude-md` subcommand manages 5 sections (project, stack, conventions, architecture, workflow enforcement).
+The profile section is managed exclusively by `generate-claude-profile`.
+
+---
+
+## Section Templates
+
+### Project Section
+```
+<!-- GSD:project-start source:PROJECT.md -->
+## Project
+
+{{project_content}}
+<!-- GSD:project-end -->
+```
+
+**Fallback text:**
+```
+Project not yet initialized. Run /gsd:new-project to set up.
+```
+
+### Stack Section
+```
+<!-- GSD:stack-start source:STACK.md -->
+## Technology Stack
+
+{{stack_content}}
+<!-- GSD:stack-end -->
+```
+
+**Fallback text:**
+```
+Technology stack not yet documented. Will populate after codebase mapping or first phase.
+```
+
+### Conventions Section
+```
+<!-- GSD:conventions-start source:CONVENTIONS.md -->
+## Conventions
+
+{{conventions_content}}
+<!-- GSD:conventions-end -->
+```
+
+**Fallback text:**
+```
+Conventions not yet established. Will populate as patterns emerge during development.
+```
+
+### Architecture Section
+```
+<!-- GSD:architecture-start source:ARCHITECTURE.md -->
+## Architecture
+
+{{architecture_content}}
+<!-- GSD:architecture-end -->
+```
+
+**Fallback text:**
+```
+Architecture not yet mapped. Follow existing patterns found in the codebase.
+```
+
+### Workflow Enforcement Section
+```
+<!-- CAP:workflow-start source:CAP 7.0 auto-trigger contract -->
+## CAP Workflow
+
+Code-First: build first, extract structure from `@cap-feature` and `@cap-todo` tags. The slash commands (`/cap:brainstorm`, `/cap:prototype`, `/cap:iterate`, `/cap:test`, `/cap:review`) exist for explicit power-user invocation, but in normal use Claude should recognize the workflow moment and invoke the matching Skill — or simply do the work directly when the change is small.
+
+**Auto-trigger contract — invoke the matching CAP Skill when:**
+
+| Situation | Skill |
+|-----------|------|
+| User describes a new feature without a FEATURE-MAP.md entry ("we need X / let's add Y") | `cap:brainstorm` |
+| Feature in state `planned`, user says "build / implement it" | `cap:prototype` |
+| Feature in state `prototyped` with open `@cap-todo` tags, user says "refine / iterate / keep going" | `cap:iterate` |
+| Feature has code but not yet `tested` | `cap:test` |
+| Feature in state `tested`, user says "review / ready to ship" | `cap:review` |
+| User reports a bug or unexpected behavior | `cap:debug` |
+| User asks "where are we / what's the status" | `cap:status` (or `cap-curator` STATUS mode) |
+
+**Do NOT invoke a Skill when:**
+- The change is a one-line edit, typo, or trivial refactor — just edit
+- The user explicitly says "skip cap / just do it"
+- The work is exploratory chat, not yet a feature
+- The user is in a Frontend Sprint (see below)
+
+### Frontend Sprint Pattern (Phase-1 / Phase-2)
+
+UI work has a different shape: fast tweaks where agent ceremony costs more than the edit. Two-phase pattern, no slash command needed.
+
+**Phase 1 — Free Edit Sprint** (stay out of the way):
+Triggers — file is `*.tsx/*.jsx/*.css/*.scss`, OR user asks for visual changes (padding, color, spacing, hover, animation, layout), OR rapid back-and-forth (3+ edits same file), OR user says "schnell / quick / probieren".
+→ Edit directly. No Skill invocation. No tag pressure. No research gate.
+
+**Phase 2 — Catch-up** (auto-invoke at sprint end):
+Triggers — user says "fertig / passt / aufräumen / commit ready", OR shifts topic away from visual.
+→ Invoke `cap:annotate` (retroactive tags) + `cap:test` sequentially. Optionally suggest `/cap:save`.
+
+### Multi-User Workflow (optional, only if the project has multiple contributors)
+
+Projects with role-split contributors (e.g. frontend ↔ backend) can drive Skill behavior off `.cap/SESSION.json:activeUser`. Detection order: explicit `--user=` flag → `git config user.email` → ask once + persist.
+
+For each user role, document in this CLAUDE.md:
+- **Owns** (file globs, packages, layers)
+- **Skill priorities** (Skills to lean on)
+- **Do NOT auto-invoke for this user** (Skills out of scope)
+- **Do NOT push to this user** (topics out of scope)
+
+**Handoff snapshots** between users are first-class: `cap-historian` MODE: SAVE writes a snapshot with frontmatter:
+```yaml
+handoff_to: <recipient>
+handoff_from: <sender>
+handoff_date: <ISO timestamp>
+feature: F-XXX
+phase: <next-phase>
+files_changed: [list]
+open_acs: [list]
+exit_notes: |
+  What's done and what's open.
+```
+The recipient's next `cap:start` surfaces the unconsumed handoff via `cap-historian` MODE: CONTINUE. Handoff is consumed implicitly once the recipient writes a follow-up snapshot or runs a state-changing Skill on the same feature.
+
+Skip this section entirely for single-contributor projects.
+
+**Macro-agents (`cap-historian`, `cap-curator`, `cap-architect`, `cap-migrator`) are spawned via Task() when the user wants a step back** — architecture review, snapshot/fork, stakeholder report, or migration. They are not slash commands.
+
+Tag annotations matter: every feature implementation must carry `@cap-feature(feature:F-NNN)` plus `@cap-todo(ac:F-NNN/AC-N)` for each AC. Without tags, the Feature Map drifts from reality.
+<!-- CAP:workflow-end -->
+```
+
+### Profile Section (Placeholder Only)
+```
+<!-- GSD:profile-start -->
+## Developer Profile
+
+> Profile not yet configured. Run `/gsd:profile-user` to generate your developer profile.
+> This section is managed by `generate-claude-profile` — do not edit manually.
+<!-- GSD:profile-end -->
+```
+
+**Note:** This section is NOT managed by `generate-claude-md`. It is managed exclusively
+by `generate-claude-profile`. The placeholder above is only used when creating a new
+CLAUDE.md file and no profile section exists yet.
+
+---
+
+## Section Ordering
+
+1. **Project** — Identity and purpose (what this project is)
+2. **Stack** — Technology choices (what tools are used)
+3. **Conventions** — Code patterns and rules (how code is written)
+4. **Architecture** — System structure (how components fit together)
+5. **Workflow Enforcement** — Default GSD entry points for file-changing work
+6. **Profile** — Developer behavioral preferences (how to interact)
+
+## Marker Format
+
+- Start: `<!-- GSD:{name}-start source:{file} -->`
+- End: `<!-- GSD:{name}-end -->`
+- Source attribute enables targeted updates when source files change
+- Partial match on start marker (without closing `-->`) for detection
+
+## Fallback Behavior
+
+When a source file is missing, fallback text provides Claude-actionable guidance:
+- Guides Claude's behavior in the absence of data
+- Not placeholder ads or "missing" notices
+- Each fallback tells Claude what to do, not just what's absent

package/cap/templates/codebase/architecture.md

@@ -0,0 +1,255 @@
+# Architecture Template
+
+Template for `.planning/codebase/ARCHITECTURE.md` - captures conceptual code organization.
+
+**Purpose:** Document how the code is organized at a conceptual level. Complements STRUCTURE.md (which shows physical file locations).
+
+---
+
+## File Template
+
+```markdown
+# Architecture
+
+**Analysis Date:** [YYYY-MM-DD]
+
+## Pattern Overview
+
+**Overall:** [Pattern name: e.g., "Monolithic CLI", "Serverless API", "Full-stack MVC"]
+
+**Key Characteristics:**
+- [Characteristic 1: e.g., "Single executable"]
+- [Characteristic 2: e.g., "Stateless request handling"]
+- [Characteristic 3: e.g., "Event-driven"]
+
+## Layers
+
+[Describe the conceptual layers and their responsibilities]
+
+**[Layer Name]:**
+- Purpose: [What this layer does]
+- Contains: [Types of code: e.g., "route handlers", "business logic"]
+- Depends on: [What it uses: e.g., "data layer only"]
+- Used by: [What uses it: e.g., "API routes"]
+
+**[Layer Name]:**
+- Purpose: [What this layer does]
+- Contains: [Types of code]
+- Depends on: [What it uses]
+- Used by: [What uses it]
+
+## Data Flow
+
+[Describe the typical request/execution lifecycle]
+
+**[Flow Name] (e.g., "HTTP Request", "CLI Command", "Event Processing"):**
+
+1. [Entry point: e.g., "User runs command"]
+2. [Processing step: e.g., "Router matches path"]
+3. [Processing step: e.g., "Controller validates input"]
+4. [Processing step: e.g., "Service executes logic"]
+5. [Output: e.g., "Response returned"]
+
+**State Management:**
+- [How state is handled: e.g., "Stateless - no persistent state", "Database per request", "In-memory cache"]
+
+## Key Abstractions
+
+[Core concepts/patterns used throughout the codebase]
+
+**[Abstraction Name]:**
+- Purpose: [What it represents]
+- Examples: [e.g., "UserService, ProjectService"]
+- Pattern: [e.g., "Singleton", "Factory", "Repository"]
+
+**[Abstraction Name]:**
+- Purpose: [What it represents]
+- Examples: [Concrete examples]
+- Pattern: [Pattern used]
+
+## Entry Points
+
+[Where execution begins]
+
+**[Entry Point]:**
+- Location: [Brief: e.g., "src/index.ts", "API Gateway triggers"]
+- Triggers: [What invokes it: e.g., "CLI invocation", "HTTP request"]
+- Responsibilities: [What it does: e.g., "Parse args, route to command"]
+
+## Error Handling
+
+**Strategy:** [How errors are handled: e.g., "Exception bubbling to top-level handler", "Per-route error middleware"]
+
+**Patterns:**
+- [Pattern: e.g., "try/catch at controller level"]
+- [Pattern: e.g., "Error codes returned to user"]
+
+## Cross-Cutting Concerns
+
+[Aspects that affect multiple layers]
+
+**Logging:**
+- [Approach: e.g., "Winston logger, injected per-request"]
+
+**Validation:**
+- [Approach: e.g., "Zod schemas at API boundary"]
+
+**Authentication:**
+- [Approach: e.g., "JWT middleware on protected routes"]
+
+---
+
+*Architecture analysis: [date]*
+*Update when major patterns change*
+```
+
+<good_examples>
+```markdown
+# Architecture
+
+**Analysis Date:** 2025-01-20
+
+## Pattern Overview
+
+**Overall:** CLI Application with Plugin System
+
+**Key Characteristics:**
+- Single executable with subcommands
+- Plugin-based extensibility
+- File-based state (no database)
+- Synchronous execution model
+
+## Layers
+
+**Command Layer:**
+- Purpose: Parse user input and route to appropriate handler
+- Contains: Command definitions, argument parsing, help text
+- Location: `src/commands/*.ts`
+- Depends on: Service layer for business logic
+- Used by: CLI entry point (`src/index.ts`)
+
+**Service Layer:**
+- Purpose: Core business logic
+- Contains: FileService, TemplateService, InstallService
+- Location: `src/services/*.ts`
+- Depends on: File system utilities, external tools
+- Used by: Command handlers
+
+**Utility Layer:**
+- Purpose: Shared helpers and abstractions
+- Contains: File I/O wrappers, path resolution, string formatting
+- Location: `src/utils/*.ts`
+- Depends on: Node.js built-ins only
+- Used by: Service layer
+
+## Data Flow
+
+**CLI Command Execution:**
+
+1. User runs: `gsd new-project`
+2. Commander parses args and flags
+3. Command handler invoked (`src/commands/new-project.ts`)
+4. Handler calls service methods (`src/services/project.ts` → `create()`)
+5. Service reads templates, processes files, writes output
+6. Results logged to console
+7. Process exits with status code
+
+**State Management:**
+- File-based: All state lives in `.planning/` directory
+- No persistent in-memory state
+- Each command execution is independent
+
+## Key Abstractions
+
+**Service:**
+- Purpose: Encapsulate business logic for a domain
+- Examples: `src/services/file.ts`, `src/services/template.ts`, `src/services/project.ts`
+- Pattern: Singleton-like (imported as modules, not instantiated)
+
+**Command:**
+- Purpose: CLI command definition
+- Examples: `src/commands/new-project.ts`, `src/commands/plan-phase.ts`
+- Pattern: Commander.js command registration
+
+**Template:**
+- Purpose: Reusable document structures
+- Examples: PROJECT.md, PLAN.md templates
+- Pattern: Markdown files with substitution variables
+
+## Entry Points
+
+**CLI Entry:**
+- Location: `src/index.ts`
+- Triggers: User runs `gsd <command>`
+- Responsibilities: Register commands, parse args, display help
+
+**Commands:**
+- Location: `src/commands/*.ts`
+- Triggers: Matched command from CLI
+- Responsibilities: Validate input, call services, format output
+
+## Error Handling
+
+**Strategy:** Throw exceptions, catch at command level, log and exit
+
+**Patterns:**
+- Services throw Error with descriptive messages
+- Command handlers catch, log error to stderr, exit(1)
+- Validation errors shown before execution (fail fast)
+
+## Cross-Cutting Concerns
+
+**Logging:**
+- Console.log for normal output
+- Console.error for errors
+- Chalk for colored output
+
+**Validation:**
+- Zod schemas for config file parsing
+- Manual validation in command handlers
+- Fail fast on invalid input
+
+**File Operations:**
+- FileService abstraction over fs-extra
+- All paths validated before operations
+- Atomic writes (temp file + rename)
+
+---
+
+*Architecture analysis: 2025-01-20*
+*Update when major patterns change*
+```
+</good_examples>
+
+<guidelines>
+**What belongs in ARCHITECTURE.md:**
+- Overall architectural pattern (monolith, microservices, layered, etc.)
+- Conceptual layers and their relationships
+- Data flow / request lifecycle
+- Key abstractions and patterns
+- Entry points
+- Error handling strategy
+- Cross-cutting concerns (logging, auth, validation)
+
+**What does NOT belong here:**
+- Exhaustive file listings (that's STRUCTURE.md)
+- Technology choices (that's STACK.md)
+- Line-by-line code walkthrough (defer to code reading)
+- Implementation details of specific features
+
+**File paths ARE welcome:**
+Include file paths as concrete examples of abstractions. Use backtick formatting: `src/services/user.ts`. This makes the architecture document actionable for Claude when planning.
+
+**When filling this template:**
+- Read main entry points (index, server, main)
+- Identify layers by reading imports/dependencies
+- Trace a typical request/command execution
+- Note recurring patterns (services, controllers, repositories)
+- Keep descriptions conceptual, not mechanical
+
+**Useful for phase planning when:**
+- Adding new features (where does it fit in the layers?)
+- Refactoring (understanding current patterns)
+- Identifying where to add code (which layer handles X?)
+- Understanding dependencies between components
+</guidelines>