@juicesharp/rpiv-pi 0.4.0

package/skills/plan/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: plan
+description: Create phased implementation plans from design artifacts. Decomposes designs into parallelized atomic phases with success criteria in thoughts/shared/plans/. Use after design.
+argument-hint: [design artifact path]
+---
+
+# Write Plan
+
+You are tasked with creating phased implementation plans from design artifacts. The design artifact contains all architectural decisions, full implementation code, and ordering constraints. Your job is to decompose that design into parallelized atomic phases with success criteria that implement can execute.
+
+## Step 1: Read Design Artifact
+
+When this command is invoked:
+
+1. **Determine input mode**:
+
+   **Design artifact provided** (path to a `.md` file in `thoughts/shared/designs/`):
+   - Read the design artifact FULLY using the Read tool WITHOUT limit/offset
+   - Extract: Architecture (the code changes), File Map, Ordering Constraints, Verification Notes, Performance Considerations, Scope
+   - These are the inputs for phasing
+   - Design decisions are settled — do not re-evaluate them
+   - If the design has unresolved questions, STOP — tell the developer to return to design
+
+   **No arguments provided**:
+   ```
+   I'll create an implementation plan from a design artifact. Please provide the path:
+
+   `/skill:plan thoughts/shared/designs/2025-01-20_09-30-00_feature.md`
+
+   Run `/skill:design` first to produce the design artifact. There is no standalone path.
+   ```
+   Then wait for input.
+
+2. **Read any additional files mentioned** in the design's References — research documents, tickets. Read them FULLY for context.
+
+## Step 2: Decompose into Phases
+
+Read the Ordering Constraints and File Map from the design artifact. Apply phasing rules:
+
+1. **Independently implementable**: Each phase must compile and pass tests on its own — no cross-phase runtime state
+2. **Parallelizable**: Phases that don't depend on each other are explicitly marked (e.g., "Phases 2 and 3 can run in parallel")
+3. **Worktree-sized**: Each phase should be appropriate for a single implement session in a worktree (~3-8 files changed, 1-3 components touched)
+4. **Dependency-ordered**: Phase ordering follows the design artifact's Ordering Constraints
+5. **Grouped coherently**: Related file changes go in the same phase (e.g., import change + hook setup + JSX modification for one component)
+
+**If the design's Ordering Constraints say "all files independent"**, consider whether a single phase is appropriate. Don't split into phases just for the sake of it — if all changes can be done in one worktree session, one phase is correct.
+
+Present phase outline and get developer feedback BEFORE writing details:
+
+```
+Here's my proposed plan structure based on the design at [path]:
+
+## Implementation Phases:
+1. [Phase name] - [what it accomplishes] ([N] files)
+2. [Phase name] - [what it accomplishes] ([N] files)
+3. [Phase name] - [what it accomplishes] ([N] files)
+
+Phases [2] and [3] can run in parallel after Phase 1.
+Total: [N] files across [M] phases.
+
+Does this phasing make sense? Should I adjust the order or granularity?
+```
+
+Use the `ask_user_question` tool to confirm the phase structure. Question: "[N] phases, [M] total files. Does this structure work?". Header: "Phases". Options: "Proceed (Recommended)" (Write the detailed plan with code blocks and success criteria); "Adjust phases" (Split, merge, or reorder phases before writing); "Change scope" (Add or remove files from the plan).
+
+Get feedback on structure before writing details.
+
+## Step 3: Write Plan
+
+After structure approval, write the plan **incrementally** — skeleton first, then fill each phase:
+
+1. **Write the plan skeleton** to `thoughts/shared/plans/YYYY-MM-DD_HH-MM-SS_description.md`
+   - Format: `YYYY-MM-DD_HH-MM-SS_description.md` where:
+     - YYYY-MM-DD is today's date
+     - HH-MM-SS is the current time in 24-hour format
+     - description is a brief kebab-case description (may include ticket number)
+   - Examples:
+     - With ticket: `2025-01-08_14-30-00_ENG-1478-parent-child-tracking.md`
+     - Without ticket: `2025-01-08_14-30-00_improve-error-handling.md`
+   - The skeleton includes everything EXCEPT large code blocks: frontmatter, Overview, Desired End State, What We're NOT Doing, full phase structure (Overview, Changes Required with file paths and change summaries, Success Criteria, parallelism annotations), Testing Strategy, Performance Considerations, References. All phasing and structural decisions happen in this pass.
+
+2. **Fill code blocks using Edit** — one phase at a time:
+   - For each phase, Edit to insert the before/after code blocks from the design's Architecture section into the Changes Required subsections
+
+3. **Use this template structure**:
+
+```markdown
+---
+date: [Current date and time with timezone in ISO format]
+planner: [User from injected git context]
+git_commit: [Current commit hash]
+branch: [Current branch name]
+repository: [Repository name]
+topic: "[Feature/Task Name]"
+tags: [plan, relevant-component-names]
+status: ready
+design_source: "[path to design artifact]"
+last_updated: [Current date in YYYY-MM-DD format]
+last_updated_by: [User from injected git context]
+---
+
+# [Feature/Task Name] Implementation Plan
+
+## Overview
+
+[Brief description of what we're implementing and why. Reference design artifact.]
+
+## Desired End State
+
+[From design artifact's Desired End State / Summary — what "done" looks like and how to verify it]
+
+## What We're NOT Doing
+
+[From design artifact's Scope → Not Building]
+
+## Phase 1: [Descriptive Name]
+
+### Overview
+[What this phase accomplishes]
+
+### Changes Required:
+
+#### 1. [Component/File Group]
+**File**: `path/to/file.ext`
+**Changes**: [Summary of changes]
+
+```[language]
+// Code from design artifact's Architecture section
+```
+
+### Success Criteria:
+
+#### Automated Verification:
+- [ ] Type checking passes: `pnpm typecheck`
+- [ ] Linting passes: `pnpm lint`
+- [ ] Tests pass: `pnpm test`
+
+#### Manual Verification:
+- [ ] [From design's Verification Notes — specific visual/behavioral check]
+- [ ] [Component-specific verification]
+
+---
+
+## Phase 2: [Descriptive Name]
+
+[Similar structure with both automated and manual success criteria...]
+
+---
+
+## Testing Strategy
+
+### Automated:
+- [Standard project checks from success criteria]
+
+### Manual Testing Steps:
+1. [From design's Verification Notes — converted to step-by-step]
+2. [Another verification step]
+
+## Performance Considerations
+
+[From design artifact — copied directly]
+
+## Migration Notes
+
+[From design artifact — copied directly. If applicable: schema changes, data migration, rollback strategy, backwards compatibility. Empty if not applicable.]
+
+## References
+
+- Design: `thoughts/shared/designs/[file].md`
+- Research: `thoughts/shared/research/[file].md`
+- Original ticket: `thoughts/me/tickets/[file].md`
+```
+
+## Step 4: Review
+
+1. **Present the plan location**:
+   ```
+   Implementation plan written to:
+   `thoughts/shared/plans/[filename].md`
+
+   [N] phases, [M] total file changes.
+
+   Please review:
+   - Are the phases properly scoped for worktree execution?
+   - Are the success criteria specific enough?
+   - Any phase that should be split or merged?
+
+   When ready, run `/skill:implement thoughts/shared/plans/[filename].md Phase 1`
+   ```
+
+2. **Iterate based on feedback** — be ready to:
+   - Split large phases
+   - Merge small phases
+   - Adjust success criteria
+   - Reorder phases
+
+3. **Continue refining** until the developer is satisfied
+
+## Guidelines
+
+1. **Trust the Design**:
+   - Design decisions are fixed — do not re-evaluate architectural choices
+   - If something in the design seems wrong, flag it to the developer
+   - Don't silently change the approach or add scope
+   - The design is the source of truth for what to build
+
+2. **Be Interactive**:
+   - Don't write the full plan in one shot
+   - Get buy-in on phase structure first
+   - Allow course corrections on granularity
+   - Work collaboratively
+
+3. **Be Practical**:
+   - Focus on incremental, testable changes
+   - Each phase should leave the codebase in a working state
+   - Think about what can be verified independently
+   - Include "what we're NOT doing" from the design's scope
+
+4. **Phase for Worktrees**:
+   - Each phase should be implementable in an isolated worktree
+   - No phase should depend on another phase's uncommitted changes
+   - If the design says "all independent," one phase may be correct
+   - Don't split for the sake of splitting
+
+5. **Track Progress**:
+   - Use a todo list to track planning tasks
+   - Mark planning tasks complete when done
+
+6. **No Open Questions in Final Plan**:
+   - If you encounter open questions during planning, STOP
+   - If the design artifact has unresolved questions, send the developer back to design
+   - Do NOT write the plan with unresolved questions
+   - The implementation plan must be complete and actionable
+
+## Success Criteria Guidelines
+
+**Always separate success criteria into two categories:**
+
+1. **Automated Verification** (can be run by execution agents):
+   - Commands that can be run: `make test`, `npm run lint`, etc.
+   - Specific files that should exist
+   - Code compilation/type checking
+   - Automated test suites
+
+2. **Manual Verification** (requires human testing):
+   - UI/UX functionality
+   - Performance under real conditions
+   - Edge cases that are hard to automate
+   - User acceptance criteria
+
+**Format example:**
+```markdown
+### Success Criteria:
+
+#### Automated Verification:
+- [ ] Database migration runs successfully: `make migrate`
+- [ ] All unit tests pass: `go test ./...`
+- [ ] No linting errors: `golangci-lint run`
+- [ ] API endpoint returns 200: `curl localhost:8080/api/new-endpoint`
+
+#### Manual Verification:
+- [ ] New feature appears correctly in the UI
+- [ ] Performance is acceptable with 1000+ items
+- [ ] Error messages are user-friendly
+- [ ] Feature works correctly on mobile devices
+```
+
+**Convert design's Verification Notes to success criteria:**
+- Prose warnings → specific automated commands or manual steps
+- "Test production builds" → `pnpm build && verify in built app`
+- "Verify scrollbar appearance" → `[ ] Open [component], scroll, observe slim scrollbar`
+- "Do NOT use X" → `grep -r "X" src/ should return 0 matches`
+
+## Important Notes
+
+- NEVER edit source files — this skill produces a plan document, not implementation
+- Always read the design artifact FULLY before decomposing into phases
+- The plan template must be compatible with implement — preserve the phase/success criteria structure
+- If the design artifact has unresolved questions, STOP — send the developer back to design
+- Code in the plan comes from the design artifact's Architecture section — do not invent new code
+- **Frontmatter consistency**: Use snake_case for multi-word field names in plan frontmatter

package/skills/research/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: research
+description: Answer structured research questions via targeted parallel analysis agents. Consumes question artifacts from discover. Produces research documents in thoughts/shared/research/. Second stage of the research pipeline — always requires a questions artifact.
+argument-hint: [path to discover artifact]
+---
+
+## Questions Source
+
+If the user has not already provided a specific discover artifact path, ask them for it before proceeding. Their input will appear as a follow-up paragraph after this skill body.
+
+# Research
+
+You are tasked with answering structured research questions by spawning targeted analysis agents and synthesizing their findings into a comprehensive research document. This skill consumes questions artifacts produced by the `discover` skill.
+
+## Step 1: Read Questions Artifact
+
+1. **Determine input:**
+
+   **Questions artifact provided** (path to a `.md` file in `thoughts/`):
+   - Read the questions artifact FULLY using the Read tool WITHOUT limit/offset
+   - Extract: Discovery Summary, Questions (dense paragraphs), frontmatter metadata (topic, tags)
+   - The Discovery Summary provides the file landscape overview — no need to re-discover
+
+   **No arguments provided:**
+   ```
+   I'll answer research questions from a questions artifact. Please provide the path:
+   `/skill:research thoughts/shared/questions/YYYY-MM-DD_HH-MM-SS_topic.md`
+
+   This skill requires a questions artifact from discover.
+   There is no standalone path — run /skill:discover first to produce a questions artifact.
+   ```
+   Then wait for input.
+
+2. **Read key shared files** referenced across multiple questions into main context — especially shared utilities, type definitions, and integration points that multiple questions mention.
+
+3. **Analyze question overlap for grouping:**
+   - Parse all question paragraphs and extract file references from each
+   - Identify questions that share 2+ file references — these are candidates for grouping
+   - Group related questions together (2-3 questions per group max)
+   - Questions with no significant file overlap remain standalone
+   - Target: 3-6 agent dispatches total (grouped + standalone)
+
+4. **Report chained status:**
+   ```
+   [Chained]: Found research questions for "[topic]". [N] questions in [G] groups, [M] shared files.
+   ```
+
+## Step 2: Dispatch Analysis Agents
+
+Spawn analysis agents using the Agent tool. All agents run in parallel.
+
+**Default agent**: `codebase-analyzer` for all codebase questions. This agent has Read, Grep, Glob, LS — it can trace code paths, find patterns, and analyze integration points.
+
+**Exception**: Questions that explicitly reference external documentation, web APIs, or third-party libraries → `web-search-researcher`.
+
+**Agent prompt — question-as-prompt:**
+
+Each agent receives the dense question paragraph(s) directly as its prompt. The question IS the instruction.
+
+For standalone questions (no grouping):
+```
+Research topic: [topic from frontmatter]
+
+Answer the following research question thoroughly with file:line references. Read the files mentioned, trace the code paths described, and provide a complete analysis.
+
+[Full dense question paragraph]
+
+Provide your analysis with exact file:line references. Focus on DEPTH — trace the actual code, don't just locate it.
+```
+
+For grouped questions:
+```
+Research topic: [topic from frontmatter]
+
+Answer the following related research questions thoroughly with file:line references. These questions share overlapping code paths — use your cross-question context to provide deeper, more connected analysis.
+
+Question 1: [Full dense question paragraph]
+
+Question 2: [Full dense question paragraph]
+
+For each question, provide your analysis with exact file:line references. Note connections between the questions where the same code serves multiple roles. Focus on DEPTH — trace the actual code, don't just locate it.
+```
+
+**Precedent sweep (always spawn):**
+Spawn one `precedent-locator` agent alongside the question agents:
+"Find similar past changes involving [list key files from Discovery Summary]. Search git log for commits that touched these files, similar commit messages, and follow-up fixes. Research topic: [original query]."
+
+This agent runs with full knowledge of discovered files — its findings go into Precedents & Lessons, not tied to a specific question.
+
+**Wait for ALL agents to complete** before proceeding.
+
+## Step 3: Synthesize and Checkpoint
+
+1. **Compile findings:**
+   - Match each agent's response to the question(s) it answered
+   - Cross-reference findings across questions — look for patterns, conflicts, and connections
+   - Prioritize live codebase findings as primary source of truth
+   - Use thoughts/ findings as supplementary historical context
+   - Include specific file paths and line numbers
+   - Build Code References as jump-table entries for the planner, not narrative (file:startLine-endLine format)
+   - No multi-line code blocks (>3 lines) — use file:line refs + prose. No implementation recipes — facts only.
+   - No artifact summaries — link plans/designs in Historical Context, don't summarize their contents. Research describes current codebase state.
+
+2. **Developer checkpoint — grounded questions one at a time:**
+
+   Start with grounded questions referencing real findings with file:line evidence. Ask ONE question at a time, waiting for the answer before the next. Use a **❓ Question:** prefix. Each question must pull NEW information from the developer — not confirm what you already found:
+
+   Every question MUST embed at least one `file:line` reference in the question text — not just in surrounding context. Examples:
+
+   - "❓ Question: `src/events/orders.ts:45-67` has 3 event hooks but no error recovery path. Is there a retry mechanism elsewhere I'm not seeing?"
+   - "❓ Question: Pattern-finder found manual mapping at `src/services/OrderService.ts:45` (8 uses) vs AutoMapper at `src/services/UserService.ts:12` (2 uses). Which should new code follow?"
+   - "❓ Question: Precedent commit `abc123` required a follow-up fix at `src/handlers/key.ts:158` for connection leak. Should we account for that pattern in this design?"
+
+   Anti-patterns — NEVER ask these:
+   - "Is this research to understand X or prepare for Y?" — confirmatory, pulls zero new information
+   - "Does this look correct?" / "Should I continue?" — asks developer to validate YOUR work instead of providing NEW context
+   - Questions without `file:line` — if you can't ground it in code, it's not a research question
+
+   **Question patterns by finding type:**
+
+   - **Pattern conflict**: "Found 2 implementations of [X] — which is canonical?" with options citing `file:line` + occurrence count
+   - **Scope boundary**: "Question [N] references files [A,B,C] but analysis shows [D] is the real integration point. Extend scope?" with yes/no + "describe what I missed"
+   - **Priority override**: "Questions Q1 and Q2 have competing implications for [area]. Which is load-bearing?" with options
+   - **Integration ambiguity**: "Found no connection between [X] and [Y]. Is there an indirect path?" (free-text — can't predict the answer)
+
+   **Choosing question format:**
+
+   - **`ask_user_question` tool** — when your question has 2-4 concrete options from code analysis (pattern conflicts, integration choices, scope boundaries, priority overrides). The user can always pick "Other" for free-text. Example:
+
+     > Use the `ask_user_question` tool with the following question: "Found 2 patterns for retry logic — which is canonical?". Header: "Pattern". Options: "Event-sourced retry (Recommended)" (`src/events/orders.ts:45-67` — 3 hooks, matches precedent commit `abc123`); "Direct retry loop" (`src/services/OrderService.ts:112` — single use, no event traceability).
+
+   - **Free-text with ❓ Question: prefix** — when the question is open-ended and options can't be predicted (discovery, "what am I missing?", corrections). Example:
+     "❓ Question: `src/events/orders.ts:45-67` has 3 event hooks but no error recovery path. Is there a retry mechanism elsewhere I'm not seeing?"
+
+   **Anti-pattern** — do NOT dump a verbose paragraph mixing analysis with a trailing question:
+
+   ❌ "The premise inversion is load-bearing for prioritization — it means Site A is a no-op, and the real bloat only hits general-purpose dispatches. Given this, where is the bloat actually landing? Do your skills dispatch named bundled agents — in which case append-mode is irrelevant — or general-purpose — in which case it IS the dominant source?"
+
+   ✅ Extract the 2 concrete options and call `ask_user_question`: "Where is the prompt bloat landing?". Header: "Bloat source". Options: "Named bundled agents (Recommended)" (Skills dispatch `codebase-analyzer` etc. — `prompt_mode: "replace"`, no parent inheritance); "General-purpose agent" (`default-agents.ts:11-28` — `promptMode: "append"`, inherits full parent prompt).
+
+   **Batching**: When you have 2-4 independent questions (answers don't depend on each other), you MAY batch them in a single `ask_user_question` call. Keep dependent questions sequential.
+
+   **CRITICAL**: Ask ONE question at a time. Wait for the answer before asking the next. Lead with your most significant finding.
+
+3. **Present compiled scan** (under 30 lines):
+   ```
+   Task: [one-line summary]
+   Scope: [N files across M layers, K integration points]
+
+   [Layer name] — [key files and what they do]
+   [Layer name] — [key files and what they do]
+   Integration — [N inbound, M outbound, K wiring. Top concern if any]
+   History — [N relevant docs. Key insight if any]
+
+   Best template: [implementation to model after]
+   Precedents — [N similar changes found. Top lesson if any]
+   Inconsistencies: [count] found ([short names])
+   ```
+
+   Wait for the developer's response before proceeding.
+
+4. **Incorporate developer input:**
+
+   Classify each response:
+
+   **Corrections** (e.g., "skip the job scheduler", "use CreateProduct not GetUser"):
+   - Incorporate directly into synthesis. Record in Developer Context.
+
+   **New areas** (e.g., "you missed the events module"):
+   - Spawn targeted rescan: **codebase-locator** + **codebase-analyzer** on the new area (max 2 agents).
+   - Merge results into synthesis. Record in Developer Context.
+
+   **Decisions** (e.g., "yes, hook into that event chain"):
+   - Record in Developer Context. Remove corresponding item from Open Questions.
+
+   **Scope/focus** (e.g., "focus on API layer, UI is out of scope"):
+   - Record in Developer Context.
+
+   After incorporating all input, proceed to Step 4.
+
+## Step 4: Write Research Document
+
+1. **Determine metadata:**
+   - Filename: `thoughts/shared/research/YYYY-MM-DD_HH-MM-SS_[topic].md`
+     - YYYY-MM-DD_HH-MM-SS: Current date and time
+     - topic: Brief kebab-case description
+   - Repository name: from git root basename, or current directory basename if not a git repo
+   - Use the git branch and commit from the git context injected at the start of the session (or run `git branch --show-current` / `git rev-parse --short HEAD` directly)
+   - Researcher: use the User from the git context injected at the start of the session (fallback: "unknown")
+   - If metadata unavailable: use "unknown" for commit/branch
+
+2. **Write the research document** — this document is compressed context for a new session. Include everything the planner needs to make architectural decisions without re-researching:
+
+   ```markdown
+   ---
+   date: [Current date and time with timezone in ISO format]
+   researcher: [User from injected git context]
+   git_commit: [Current commit hash]
+   branch: [Current branch name]
+   repository: [Repository name]
+   topic: "[User's Research Topic]"
+   tags: [research, codebase, relevant-component-names]
+   status: complete
+   questions_source: "[path to questions artifact]"
+   last_updated: [Current date in YYYY-MM-DD format]
+   last_updated_by: [User from injected git context]
+   ---
+
+   # Research: [User's Research Topic]
+
+   ## Research Question
+   [Original user query from questions artifact]
+
+   ## Summary
+   [High-level findings answering the user's question]
+
+   ## Detailed Findings
+
+   ### [Component/Area 1]
+   - Finding with reference (`file.ext:line`)
+   - Connection to other components
+   - Implementation details
+
+   ### [Component/Area 2]
+   ...
+
+   ## Code References
+   - `path/to/file.py:123` — Description of what's there
+   - `another/file.ts:45-67` — Description of the code block
+
+   ## Integration Points
+   [All connections to the researched area. Enumerate each consumer, dependency, and wiring point with file:line. Source from the questions artifact's Discovery Summary + new connections found by analysis agents.]
+
+   ### Inbound References
+   - `path/to/consumer.ext:line` — [What references the component and how]
+
+   ### Outbound Dependencies
+   - `path/to/dependency.ext:line` — [What the component depends on]
+
+   ### Infrastructure Wiring
+   - `path/to/config.ext:line` — [DI, routes, events, jobs, middleware]
+
+   ## Architecture Insights
+   [Patterns, conventions, and design decisions discovered]
+
+   ## Precedents & Lessons
+   [N] similar past changes analyzed. Key commits: `hash` (description).
+
+   - [Composite lesson 1 — with relevant `commit hash` inline]
+   - [Composite lesson 2]
+
+   ## Historical Context (from thoughts/)
+   [Links only — one line per doc, no summaries of their contents]
+   - `thoughts/shared/something.md` — [one-line description of what this doc covers]
+   ## Developer Context
+   **Q (`file.ext:line`): [Question grounded in specific code reference]**
+   A: [Developer's answer]
+
+   ## Related Research
+   - Questions source: `[path to questions artifact]`
+   - [Links to other research documents]
+
+   ## Open Questions
+   [Only questions NOT resolved during checkpoint]
+   ```
+
+## Step 5: Present and Chain
+
+```
+Research document written to:
+`thoughts/shared/research/[filename].md`
+
+[N] questions answered, [M] findings across [K] files.
+
+Please review and let me know if you have follow-up questions.
+
+When ready:
+`/skill:design thoughts/shared/research/[filename].md`
+```
+
+## Step 6: Handle Follow-ups
+
+- If the user has follow-up questions, append to the same research document
+- Update frontmatter: `last_updated` and `last_updated_by`
+- Add `last_updated_note: "Added follow-up research for [brief description]"` to frontmatter
+- Add section: `## Follow-up Research [timestamp]`
+- Spawn new analysis agents as needed
+
+## Important Notes
+
+- **Analysis only**: This skill answers questions. It does NOT discover what to ask — that's discover's job.
+- **Always chained**: This skill requires a questions artifact from discover. There is no standalone path.
+- **Grouped dispatch**: Related questions are batched per agent based on file overlap. Default agent: codebase-analyzer. This reduces token waste from redundant file reads and lets agents build cross-question context.
+- **Downstream compatible**: Research documents feed directly into design and plan — the same Code References / Integration Points / Architecture Insights sections they expect.
+- **File reading**: Always read the questions artifact FULLY (no limit/offset) before dispatching agents
+- **Critical ordering**: Follow the numbered steps exactly
+  - ALWAYS read the questions artifact first (Step 1)
+  - ALWAYS analyze question overlap for grouping (Step 1)
+  - ALWAYS wait for all agents to complete (Step 2)
+  - ALWAYS run developer checkpoint before writing (Step 3)
+  - ALWAYS gather metadata before writing (Step 4)
+  - NEVER write the document with placeholder values
+- **Frontmatter consistency**: Always include frontmatter, use snake_case fields, include `questions_source`
+- CC auto-loads CLAUDE.md files when agents read files in a directory — no need to scan for them explicitly