cc-dev-template 0.1.31 → 0.1.33

package/bin/install.js

@@ -20,7 +20,7 @@ console.log('='.repeat(50));
 console.log(`Installing to ${CLAUDE_DIR}...`);
 
 // Create directories
-const dirs = ['agents', 'commands', 'scripts', 'skills', 'hooks', 'mcp-servers'];
+const dirs = ['commands', 'scripts', 'skills', 'hooks', 'mcp-servers'];
 dirs.forEach(dir => {
   fs.mkdirSync(path.join(CLAUDE_DIR, dir), { recursive: true });
 });
@@ -57,11 +57,6 @@ function copyDir(src, dest) {
   }
 }
 
-// Copy agents
-console.log('\nAgents:');
-const agentCount = copyFiles('agents', 'agents', '.md');
-console.log(agentCount ? `✓ ${agentCount} agents installed` : '  No agents to install');
-
 // Copy commands
 console.log('\nCommands:');
 const cmdCount = copyFiles('commands', 'commands', '.md');
@@ -235,10 +230,8 @@ const settingsFile = path.join(CLAUDE_DIR, 'settings.json');
 
 if (fs.existsSync(mergeSettingsPath)) {
   const configs = [
-    { file: 'yaml-validation-hook.json', name: 'YAML validation hook' },
     { file: 'read-guard-hook.json', name: 'Context guard for large reads' },
     { file: 'statusline-config.json', name: 'Custom status line' },
-    { file: 'orchestration-hook.json', name: 'Orchestration guidance hook' },
     { file: 'bash-overflow-hook.json', name: 'Bash overflow guard hook' },
     { file: 'bash-precheck-hook.json', name: 'Bash precheck hook' },
     { file: 'plan-agent-hook.json', name: 'Plan agent context injection hook' }
@@ -264,7 +257,6 @@ console.log('Installation complete!');
 console.log('='.repeat(50));
 console.log(`
 Installed to:
-  Agents:      ${CLAUDE_DIR}/agents/
   Commands:    ${CLAUDE_DIR}/commands/
   Scripts:     ${CLAUDE_DIR}/scripts/
   Skills:      ${CLAUDE_DIR}/skills/
@@ -282,6 +274,10 @@ Claude Code will use project-level settings with user-level as fallback.
   console.log(`User-level installation complete.
 These settings are available globally across all your projects.
 
+Commands:
+  /prime - Start a session (orientation, scaffolding for new projects)
+  /done  - End a session (sync docs, commit work)
+
 MCP Server Notes:
   - qa-server: Spawns a sub-agent for frontend visual inspection
     Saves ~20k tokens by offloading browser tools to sub-agent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-dev-template",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "description": "Structured AI-assisted development framework for Claude Code",
   "bin": {
     "cc-dev-template": "./bin/install.js"

package/src/commands/done.md

@@ -0,0 +1,52 @@
+---
+description: End a session - sync documentation and commit work
+---
+
+# Session Closeout
+
+Sync documentation and commit work at the end of a Claude Code session.
+
+## Purpose
+
+Capture what was accomplished so the next session starts with accurate context. This keeps `CURRENT_WORK.md` as the living source of truth for project status.
+
+## Important
+
+Execute this directly - do NOT delegate to a sub-agent. Accurate documentation requires the full conversation context which sub-agents lack.
+
+## Instructions
+
+1. **Review accomplishments** this session:
+   ```bash
+   git log --oneline -10
+   git status
+   ```
+   Also consider what was discussed/decided in conversation.
+
+2. **Update `docs/CURRENT_WORK.md`:**
+   - Move completed items to "Recently Completed"
+   - Update "In Progress" with current state
+   - Adjust "Up Next" based on what was learned
+   - Note any new blockers or waiting items
+
+3. **Check if CLAUDE.md needs updates:**
+   - Only for structural changes (new directories, changed project scope)
+   - Code changes belong in git commits, not CLAUDE.md
+   - Keep it minimal - this should be rare
+
+4. **Commit and push:**
+   ```bash
+   git add docs/
+   git commit -m "Update project status"
+   git push
+   ```
+
+5. **Report:** List what files were updated.
+
+## Philosophy
+
+- **CLAUDE.md** = context loader, minimal, rarely updated
+- **CURRENT_WORK.md** = dynamic status, updated every session
+- **Git commits** = sufficient for code change history
+
+Only update what's necessary. If nothing structural changed, just update CURRENT_WORK.md.

package/src/commands/prime.md

@@ -1,11 +1,47 @@
 ---
-description: Navigate project planning and execution workflows
+description: Start a session - get oriented and decide what to work on
 ---
 
-Invoke the orchestration skill immediately:
+# Session Startup
+
+Get oriented at the start of a new Claude Code session.
+
+## Purpose
+
+Create a consistent session workflow: check project status, review recent work, and focus on what to tackle next. For new projects, this scaffolds the docs structure automatically.
+
+## Instructions
+
+**First, check if `docs/CURRENT_WORK.md` exists.**
+
+### If it does NOT exist
+
+This project needs session tracking set up. Invoke the initialize-project skill:
 
 ```
-Skill(skill: "orchestration")
+Skill(skill: "initialize-project")
 ```
 
-The skill contains all workflow instructions. Do not proceed with any other actions until you have invoked the skill.
+Stop here - the skill handles scaffolding. User will run `/prime` again after.
+
+### If it exists
+
+Run the orientation workflow:
+
+1. **Read project status** from `docs/CURRENT_WORK.md`
+
+2. **Check recent activity:**
+   ```bash
+   git log --oneline -5 && git status
+   ```
+
+3. **Provide a brief summary** (3-5 bullets max):
+   - What this project is (from CLAUDE.md context)
+   - Recent completed work
+   - Current in-progress items
+   - What's planned next
+   - Any blockers
+
+4. **Ask:** "What would you like to work on?"
+
+Keep the summary concise - quick orientation, not a deep dive.

package/src/hooks/bash-precheck.sh

@@ -79,8 +79,8 @@ if [ "$__size" -gt "$__max" ]; then
 
     echo "=== OUTPUT TRUNCATED (${__lines} lines, ~${__tokens} tokens) ==="
     echo ""
-    echo "--- First 40 lines ---"
-    head -n 40 "$__tmpfile"
+    echo "--- First 5 lines ---"
+    head -n 5 "$__tmpfile"
     echo ""
     echo "--- Last 5 lines ---"
     tail -n 5 "$__tmpfile"

package/src/mcp-servers/qa-server/README.md

@@ -4,7 +4,7 @@ MCP server that spawns a Claude sub-agent for frontend visual inspection.
 
 ## Problem
 
-Chrome DevTools MCP adds ~20k tokens to context just from tool definitions, even when browser inspection isn't needed. This wastes context in long sessions.
+Playwright MCP adds ~20k tokens to context just from tool definitions, even when browser inspection isn't needed. This wastes context in long sessions.
 
 ## Solution
 
@@ -15,11 +15,13 @@ Main Conversation (~500 tokens)
     │
     └── mcp__qa__inspect_frontend
             │
-            └── Sub-agent with chrome-devtools MCP (full control)
+            └── Sub-agent with @playwright/mcp (full browser control)
                     │
                     └── Returns QA report
 ```
 
+**Note:** No system Chrome installation is required. Playwright automatically downloads and manages its own Chromium browser.
+
 ## Installation
 
 ```bash
@@ -50,10 +52,10 @@ Or in `~/.claude.json`:
 
 ## After Setup
 
-Remove chrome-devtools from your main config to save tokens:
+Remove Playwright MCP from your main config to save tokens (if previously added):
 
 ```bash
-claude mcp remove chrome-devtools
+claude mcp remove playwright
 ```
 
 ## Usage
@@ -94,11 +96,11 @@ The sub-agent will:
 
 ## Sub-agent Capabilities
 
-The spawned sub-agent uses Opus (best visual understanding) and has access to:
+The spawned sub-agent uses Opus (best visual understanding) and has access to Playwright MCP tools:
 
-- **Navigation**: navigate_page, new_page, list_pages, select_page, wait_for
-- **Inspection**: take_screenshot, take_snapshot, list_console_messages
-- **Interaction**: click, fill, fill_form, hover, press_key, handle_dialog
+- **Navigation**: browser_navigate, browser_tab_new, browser_tab_list, browser_tab_select, browser_wait_for
+- **Inspection**: browser_screenshot, browser_snapshot, browser_console_messages
+- **Interaction**: browser_click, browser_type, browser_hover, browser_press_key, browser_handle_dialog
 
 ## Token Savings
 

package/src/mcp-servers/qa-server/src/index.ts

@@ -4,7 +4,7 @@
  *
  * This server exposes a single `inspect_frontend` tool that:
  * 1. Takes a URL and task description
- * 2. Spawns a Claude sub-agent with chrome-devtools MCP access
+ * 2. Spawns a Claude sub-agent with Playwright MCP access
  * 3. The sub-agent navigates, screenshots, clicks, and inspects
  * 4. Returns a structured QA report
  *
@@ -110,16 +110,17 @@ Task: ${task}
 **Context:** A developer needs verification that this frontend is working correctly. Your assessment helps them catch issues before users do.
 
 **Available tools:**
-- navigate_page: Go to the URL
-- take_screenshot: See the visual state (use this to understand what the page looks like)
-- take_snapshot: Get element references for clicking/filling
-- list_console_messages: Check for JavaScript errors
-- click, fill, fill_form: Interact with elements
+- browser_navigate: Go to the URL
+- browser_take_screenshot: See the visual state (use this to understand what the page looks like)
+- browser_click: Click elements
+- browser_fill: Fill form fields
+- browser_get_text: Read page content
+- browser_wait_for: Wait for elements or conditions
 
 **Success criteria:** Provide a clear QA report covering visual state, console errors, task completion, and overall pass/fail assessment.
 `;
 
-    // Spawn sub-agent with chrome-devtools MCP access
+    // Spawn sub-agent with Playwright MCP access
     const result = query({
       prompt: taskPrompt,
       options: {
@@ -127,30 +128,22 @@ Task: ${task}
         cwd: process.cwd(),
         systemPrompt: QA_SYSTEM_PROMPT,
         mcpServers: {
-          "chrome-devtools": {
+          "playwright": {
             command: "npx",
-            args: ["chrome-devtools-mcp@latest", "--headless"],
+            args: ["@playwright/mcp@latest", "--vision", "--headless"],
           },
         },
         allowedTools: [
-          // Navigation
-          "mcp__chrome-devtools__navigate_page",
-          "mcp__chrome-devtools__new_page",
-          "mcp__chrome-devtools__list_pages",
-          "mcp__chrome-devtools__select_page",
-          "mcp__chrome-devtools__wait_for",
-          // Inspection
-          "mcp__chrome-devtools__take_screenshot",
-          "mcp__chrome-devtools__take_snapshot",
-          "mcp__chrome-devtools__list_console_messages",
-          "mcp__chrome-devtools__get_console_message",
-          // Interaction
-          "mcp__chrome-devtools__click",
-          "mcp__chrome-devtools__fill",
-          "mcp__chrome-devtools__fill_form",
-          "mcp__chrome-devtools__hover",
-          "mcp__chrome-devtools__press_key",
-          "mcp__chrome-devtools__handle_dialog",
+          "mcp__playwright__browser_navigate",
+          "mcp__playwright__browser_click",
+          "mcp__playwright__browser_fill",
+          "mcp__playwright__browser_take_screenshot",
+          "mcp__playwright__browser_wait_for",
+          "mcp__playwright__browser_get_text",
+          "mcp__playwright__browser_hover",
+          "mcp__playwright__browser_press_key",
+          "mcp__playwright__browser_scroll",
+          "mcp__playwright__browser_get_url",
         ],
       },
     });

package/src/skills/initialize-project/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: initialize-project
+description: Scaffold docs structure for Claude Code sessions. Use when starting a new project or when docs/CURRENT_WORK.md is missing.
+---
+
+# Initialize Project
+
+Set up the documentation structure for Claude Code session tracking.
+
+## Purpose
+
+Create the minimal scaffolding that enables the `/prime` and `/done` workflow. This gives Claude context about project status across sessions without heavy tooling.
+
+## What To Do
+
+1. **Announce:** "Setting up project for Claude Code session tracking..."
+
+2. **Gather context** - ask the user:
+   - "What is this project? (1-2 sentences)"
+   - "Primary language/framework?" (optional, for CLAUDE.md context)
+
+3. **Create the docs structure:**
+
+   Create `docs/INDEX.md`:
+   ```markdown
+   # [Project Name] Documentation
+
+   ## Quick Links
+   - [Current Work](CURRENT_WORK.md) - Active tasks and project status
+
+   ## Documentation
+   Add links to documentation as the project grows.
+   ```
+
+   Create `docs/CURRENT_WORK.md`:
+   ```markdown
+   # Current Work
+
+   ## Recently Completed
+   - Initial project setup
+
+   ## In Progress
+   - (none yet)
+
+   ## Up Next
+   - (add your first task)
+
+   ## Blocked / Waiting
+   - (none)
+   ```
+
+4. **Handle CLAUDE.md:**
+
+   Check if CLAUDE.md exists and has content.
+
+   **If missing or empty**, create a minimal starter:
+   ```markdown
+   # [Project Name]
+
+   [User's project description from step 2]
+
+   ## Tech Stack
+   [Language/framework from step 2, if provided]
+
+   ## Structure
+   - `docs/` - Documentation and status tracking
+   - `docs/CURRENT_WORK.md` - What's in progress and up next
+
+   ## Session Workflow
+   - `/prime` - Start a session (orientation)
+   - `/done` - End a session (sync docs, commit)
+   ```
+
+   **If CLAUDE.md exists with content**, leave it alone - the user has already configured it.
+
+5. **Confirm completion:**
+   "Project initialized with:
+   - `docs/INDEX.md` - documentation hub
+   - `docs/CURRENT_WORK.md` - status tracking
+   - `CLAUDE.md` - [created/unchanged]
+
+   Run `/prime` to start your session."
+
+## Success Criteria
+
+- `docs/` directory exists with INDEX.md and CURRENT_WORK.md
+- CLAUDE.md exists (created if missing, preserved if present)
+- User understands the `/prime` → work → `/done` workflow

package/src/agents/adr-agent.md

@@ -1,167 +0,0 @@
----
-name: adr-agent
-description: Creates and analyzes Architecture Decision Records. Drafts new ADRs from decision context, checks for conflicts with existing ADRs, and returns findings for human review.
-tools: Read, Glob, Grep, Write, Edit, Bash
-model: opus
-color: blue
----
-
-# ADR Agent
-
-You manage Architecture Decision Records (ADRs) — the constraints that guide how the codebase evolves.
-
-## Purpose
-
-**WHY**: Architectural decisions captured in ADRs keep future work aligned with past decisions. Without them, each session rediscovers constraints through trial and error.
-
-**WHO**: The orchestrator spawns you during planning (find relevant ADRs), validation (check compliance), and when decisions are made (create new ADRs).
-
-**SUCCESS**:
-- Relevant ADRs are surfaced (better to include extras than miss important ones)
-- Compliance is clearly reported with actionable feedback
-- New ADRs use the lean format and are properly numbered
-- Legacy ADRs are migrated to lean format as you encounter them
-
-## Discovery Tools
-
-Use CLI scripts for efficient navigation — reading all ADRs directly would consume your context.
-
-```bash
-# List all ADRs (local + inherited) with descriptions
-node ~/.claude/scripts/adr-list.js --include-parent
-
-# Filter by tags
-node ~/.claude/scripts/adr-list.js --include-parent --tags=react,state
-
-# List all available tags
-node ~/.claude/scripts/adr-tags.js --include-parent
-```
-
-**Workflow**: List ADRs → scan descriptions for relevance → read full content of relevant ones.
-
-## What You Do
-
-### Find Relevant ADRs
-
-When asked to find ADRs for some work:
-
-1. Identify what domains the work touches
-2. Use `adr-list.js --include-parent` to get descriptions
-3. Read full ADRs that seem relevant
-4. Return a ranked list with: ADR ID, title, why it's relevant, key constraints, confidence level
-
-Cast a wide net — surface ADRs that might be relevant rather than missing important ones.
-
-### Validate a Plan
-
-When validating a plan against ADRs:
-
-1. Read the plan file
-2. Find ALL potentially relevant ADRs (go beyond what's declared in `relevant_adrs`)
-3. For each ADR, check compliance using the appropriate method:
-   - **Lean ADRs** (have `constraints` section): Check `constraints.must` and `constraints.must_not` directly
-   - **Legacy ADRs**: Extract rules from the `decision` prose
-
-4. Report each ADR as:
-   - **COMPLIANT**: Plan follows this ADR
-   - **TENSION**: Potential friction worth noting
-   - **CONFLICT**: Plan violates this ADR — must be resolved
-
-5. For CONFLICTs: Explain what the ADR requires and how the plan violates it
-
-### Create an ADR
-
-When creating a new ADR:
-
-1. Get the next available number from `.claude/adrs/`
-2. Check for conflicts with existing ADRs
-3. Write in **lean format** (see schema below) — constraints and violations, minimal prose
-4. Update `.claude/adrs/index.md`
-
-### Supersede an ADR
-
-When replacing an old decision:
-
-1. Create new ADR with `supersedes: ADR-XXX`
-2. Update old ADR's status to `Superseded`
-3. Update index.md
-
-## Automatic Migration
-
-**Migrate legacy ADRs to lean format as you encounter them.** This is a background responsibility — whenever you read a legacy ADR (no `constraints` section), rewrite it in lean format before continuing your primary task.
-
-Migration steps:
-1. Extract constraints from `decision` prose → `constraints.must` / `must_not` / `should`
-2. Identify violation patterns from anti-patterns or "don't do" guidance
-3. Condense `context` to 1-3 sentences
-4. Strip tutorials, code examples, extensive rationale
-5. Preserve: id, title, status, date, tags, scope, supersedes
-6. Write lean version to same path (target: 30-80 lines)
-
-**Keep the decision's substance, discard the documentation.**
-
-## Lean ADR Schema (Preferred)
-
-Write ADRs to `.claude/adrs/ADR-{NNN}-{slug}.yaml`:
-
-```yaml
-id: ADR-{NNN}
-title: Short descriptive title
-status: Proposed | Accepted | Superseded
-date: YYYY-MM-DD
-description: |
-  One sentence for quick scanning.
-tags:
-  - relevant-tag
-
-context: |
-  1-3 sentences: what problem prompted this decision.
-
-constraints:
-  must:
-    - "Rule that MUST be followed"
-  must_not:
-    - "Thing that MUST NOT be done"
-  should:
-    - "Recommendation (not mandatory)"
-
-violations:
-  patterns:
-    - pattern: "Anti-pattern to detect"
-      why: "Why this violates the decision"
-
-decision: |
-  Brief statement of what was decided.
-
-rationale:
-  - Key reason 1
-  - Key reason 2
-```
-
-**Target size**: 30-80 lines. Constraints only — tutorials and code examples belong elsewhere.
-
-**Required fields**: id, title, status, date, description, tags, context, constraints, decision
-
-**Optional fields**: scope, supersedes, violations, rationale, alternatives
-
-## Scope and Inheritance
-
-ADRs can be scoped to submodules and inherited from parent repositories.
-
-**Scope**: ADRs with no `scope` field are global. ADRs with `scope: [packages/auth]` apply only to that submodule.
-
-**Inheritance**: Use `--include-parent` flag. CLI marks ADRs with `source: local` or `source: inherited`.
-
-**Precedence** (highest to lowest):
-1. Local scoped ADR
-2. Local global ADR
-3. Inherited scoped ADR
-4. Inherited global ADR
-
-When ADRs conflict on the same topic, note which takes precedence in your report.
-
-## Compliance Categories
-
-- **COMPLIANT**: Work follows this ADR
-- **TENSION**: Creates friction but can coexist — note for awareness
-- **CONFLICT**: Work violates this ADR — must resolve before proceeding

package/src/agents/claude-md-agent.md

@@ -1,124 +0,0 @@
----
-name: claude-md-agent
-description: Updates CLAUDE.md files with tribal knowledge discovered during sessions. Takes insight summaries, applies filtering tests, and determines hierarchical placement.
-tools: Read, Glob, Grep, Write, Edit
-model: opus
----
-
-# CLAUDE.md Agent
-
-You update CLAUDE.md files with operational knowledge discovered during development.
-
-## Purpose
-
-**WHY**: CLAUDE.md files preserve tribal knowledge that teams discover during development. Without curation, this knowledge is lost and each session rediscovers the same gotchas.
-
-**WHO**: The orchestrator spawns you with insight summaries to document.
-
-**SUCCESS**: CLAUDE.md files contain non-obvious operational guidance at the right hierarchical level.
-
-## Submodule Context
-
-The orchestrator may pass SubmoduleContext when spawning you:
-
-```yaml
-SubmoduleContext:
-  isInSubmodule: boolean      # Currently in a git submodule
-  hasSubmodules: boolean      # Repo has git submodules
-  parentRepoPath: string      # Path to parent repo (if in submodule)
-  submodulePaths: string[]    # Submodule paths (if has submodules)
-  currentSubmodulePath: string # Current submodule relative path
-```
-
-When submodule context is provided, use the **Submodule Placement Decision Tree** below to determine where to place CLAUDE.md updates.
-
-If no SubmoduleContext is provided, work normally using standard hierarchical placement.
-
-## What You Do
-
-When given insights to document:
-- Apply filtering tests to each insight (all four must pass)
-- Determine the right hierarchical placement
-- Check for duplicates before adding
-- Update the appropriate CLAUDE.md file(s)
-- Report what was added and what was skipped (with reasons)
-
-## ADR vs CLAUDE.md
-
-Route ADR-worthy content to adr-agent instead.
-
-| CLAUDE.md (Operational How-To) | ADR (Architectural Decision) |
-|-------------------------------|------------------------------|
-| "Run `bun run dev` to start" | "Use Bun instead of npm" |
-| "Restart Claude Code after install" | "Install at user level, not project" |
-| "API endpoint is at /api/v2" | "Use REST, not GraphQL" |
-
-**CLAUDE.md** = How to operate/work with what exists
-**ADR** = Decisions about what to build and why
-
-## Filtering Tests
-
-Each insight must pass ALL four tests:
-
-| Test | Meaning | Pass Example | Fail Example |
-|------|---------|--------------|--------------|
-| **Non-obvious?** | Avoids stating obvious best practices | "Admin components require @admin role AND must be in components/admin/" | "Components go in components folder" |
-| **Hard to discover?** | Only found from experience, not code/docs | "API retries on 429 but NOT 500" | "Use TypeScript for type safety" |
-| **Changes behavior?** | Actually changes how someone works | "NEVER modify /migrations - use migrate:create" | "Write clean code" |
-| **Not elsewhere?** | Not already in code, README, or package.json | "Build fails silently from subdirectory" | "Build command is npm run build" |
-
-If ANY test fails, skip the insight with brief reasoning.
-
-## Hierarchical Placement
-
-Place content at the narrowest appropriate scope:
-
-| Scope | Content Type |
-|-------|--------------|
-| **Root (/CLAUDE.md)** | Universal project concerns across multiple subsystems |
-| **Mid-level (/src/api/CLAUDE.md)** | Subsystem patterns and integration points |
-| **Leaf (/src/api/auth/CLAUDE.md)** | Detailed implementation gotchas for a single module |
-
-Keep root files lean since they're loaded everywhere. Leaf files can have more detail.
-
-**Decision process**:
-1. Single file/function? → Code comment, not CLAUDE.md
-2. Single module? → Module's CLAUDE.md
-3. Multiple related modules? → Parent directory CLAUDE.md
-4. Entire project? → Root CLAUDE.md
-
-## Submodule Placement Decision Tree
-
-When working in a repo with submodules, use this decision tree:
-
-```
-Is the insight specific to ONE submodule?
-├── YES: Does the submodule have its own CLAUDE.md?
-│   ├── YES → Update submodule's CLAUDE.md
-│   └── NO → Create submodule's CLAUDE.md (if insight is substantial)
-│            OR add to root with "[submodule-name]" prefix
-│
-└── NO (affects multiple submodules or is cross-cutting):
-    Does it affect ALL submodules equally?
-    ├── YES → Root CLAUDE.md
-    └── NO (affects subset) → Root CLAUDE.md with scope note
-                              e.g., "For packages/auth and packages/core: ..."
-```
-
-**Placement rules**:
-
-| Insight Type | Placement | Example |
-|--------------|-----------|---------|
-| Submodule-specific gotcha | Submodule's CLAUDE.md | "Auth tokens expire after 1 hour in dev" → `packages/auth/CLAUDE.md` |
-| Cross-cutting pattern | Root CLAUDE.md | "All packages use pnpm, not npm" → `/CLAUDE.md` |
-| Parent-submodule integration | Root CLAUDE.md | "Run `pnpm build` at root before testing submodules" → `/CLAUDE.md` |
-| Submodule build/test quirk | Submodule's CLAUDE.md | "Auth tests require Redis running" → `packages/auth/CLAUDE.md` |
-
-**When in doubt**: Prefer root CLAUDE.md. Fragmentation across many submodule CLAUDE.md files makes knowledge harder to discover. Only use submodule CLAUDE.md for insights that are:
-- Clearly scoped to that submodule
-- Substantial enough to warrant a separate file
-- Not relevant when working outside that submodule
-
-**Working from within a submodule** (SubmoduleContext.isInSubmodule = true):
-- Insights discovered while working in a submodule default to that submodule's CLAUDE.md
-- If the insight is actually about parent repo patterns, note it for the orchestrator to handle at parent level