5-phase-workflow 1.8.6 → 1.8.7

package/README.md

@@ -130,6 +130,7 @@ All commands are available under the `/5:` namespace:
 | `/5:review-code` | 5 | AI-powered code review (Claude or CodeRabbit) |
 | `/5:address-review-findings` | 5 | Apply annotated findings and address PR comments |
 | `/5:quick-implement` | Fast | Streamlined workflow for small tasks |
+| `/5:eject` | Utility | Permanently remove update infrastructure |
 | `/5:unlock` | Utility | Remove planning guard lock |
 
 ## Configuration
@@ -264,6 +265,7 @@ After installation, your `.claude/` directory will contain:
 │   ├── discuss-feature.md
 │   ├── quick-implement.md
 │   ├── configure.md
+│   ├── eject.md
 │   └── unlock.md
 ├── skills/                   # Atomic operations
 │   ├── build-project/
@@ -364,6 +366,21 @@ npx 5-phase-workflow
 - User-created commands, agents, skills, hooks, and templates are preserved
 - Only workflow-managed files are updated
 
+### Ejecting
+
+If you want to permanently opt out of the update system (e.g., to customize workflow files without future updates overwriting them), run:
+
+```bash
+/5:eject
+```
+
+This permanently removes the update infrastructure:
+- Deletes `check-updates.js` hook, `update.md` and `eject.md` commands
+- Deletes `.5/version.json` and `.5/.update-cache.json`
+- Removes the update check hook entry from `.claude/settings.json`
+
+All other workflow files remain untouched. **This is irreversible.** To restore update functionality, reinstall with `npx 5-phase-workflow`.
+
 ## Development
 
 ### Running Tests

package/bin/install.js

@@ -258,7 +258,11 @@ const LEGACY_REMOVED_FILES = [
   'agents/integration-agent.md',
   'agents/step-fixer.md',
   'agents/step-verifier.md',
-  'agents/verification-agent.md'
+  'agents/verification-agent.md',
+  'templates/STACK.md',
+  'templates/STRUCTURE.md',
+  'templates/CONVENTIONS.md',
+  'templates/INTEGRATIONS.md'
 ];
 
 // Get list of workflow-owned files/directories (not user-created)
@@ -274,8 +278,6 @@ function getWorkflowManagedFiles() {
 
     // Skills: specific skill directories
     skills: [
-      'build-project',
-      'run-tests',
       'configure-project',
       'generate-readme'
     ],
@@ -299,10 +301,6 @@ function getWorkflowManagedFiles() {
       // Project documentation templates
       'ARCHITECTURE.md',
       'CONCERNS.md',
-      'CONVENTIONS.md',
-      'INTEGRATIONS.md',
-      'STACK.md',
-      'STRUCTURE.md',
       'TESTING.md',
       // Workflow output templates
       'workflow/FEATURE-SPEC.md',
@@ -626,6 +624,7 @@ function showCommandsHelp(isGlobal) {
   log.info('  /5:address-review-findings   - Apply review findings & PR comments');
   log.info('  /5:configure                 - Interactive project setup');
   log.info('  /5:reconfigure               - Refresh docs/skills (no Q&A)');
+  log.info('  /5:eject                     - Eject from update mechanism');
   log.info('  /5:unlock                    - Remove planning guard lock');
   log.info('');
   log.info(`Config file: ${path.join(getDataPath(isGlobal), 'config.json')}`);

package/docs/workflow-guide.md

@@ -74,7 +74,7 @@ The installer copies workflow files to `.claude/` directory. **It does NOT creat
 After completing these steps, you have:
 - `.5/config.json` with your project settings
 - `CLAUDE.md` with comprehensive project documentation
-- `.5/STRUCTURE.md`, `.5/STACK.md`, etc. with modular documentation
+- `.5/ARCHITECTURE.md`, `.5/TESTING.md`, `.5/CONCERNS.md` with focused documentation
 - Project-specific skills in `.claude/skills/`
 
 **Without configuration, workflow commands will fail.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "5-phase-workflow",
-  "version": "1.8.6",
+  "version": "1.8.7",
   "description": "A 5-phase feature development workflow for Claude Code",
   "bin": {
     "5-phase-workflow": "bin/install.js"

package/src/commands/5/address-review-findings.md

@@ -296,8 +296,8 @@ If `gh api` is unavailable or fails, log the failure and continue. Do NOT abort
 
 After all fixes are applied:
 
-1. **Build:** Use the `/build-project` skill: `Skill tool: skill="build-project", args="target=compile"`
-2. **Test:** Use the `/run-tests` skill: `Skill tool: skill="run-tests", args="target=all"`
+1. **Build:** Use the project's build skill (e.g., `run-build`) generated during configure
+2. **Test:** Use the project's test skill (e.g., `run-tests`) generated during configure
 3. **Lint:** Check for any lint warnings and errors
 
 If build fails:

package/src/commands/5/configure.md

@@ -312,21 +312,16 @@ Generates CLAUDE.md with codebase analysis and creates project-specific skills.
 ## Requirements
 
 ### Requirement 1: Generate Documentation Files
-Analyze the codebase and generate modular documentation:
-
-**Create separate documentation files in `.5/` folder:**
-- `.5/ARCHITECTURE.md` - Architectural patterns and layers
-- `.5/STACK.md` - Technology stack and dependencies
-- `.5/STRUCTURE.md` - Directory layout and organization
-- `.5/CONVENTIONS.md` - Coding standards and patterns
-- `.5/TESTING.md` - Test framework and patterns
-- `.5/INTEGRATIONS.md` - External services and APIs
-- `.5/CONCERNS.md` - Tech debt, bugs, and risks
-
-**Create CLAUDE.md as navigation hub:**
-- Quick reference section with links to all `.5/*.md` files
+Analyze the codebase and generate focused documentation capturing only non-derivable knowledge (skip version numbers, dependency lists, directory layouts, linter configs — Claude Code can look these up directly):
+
+**Create documentation files in `.5/` folder:**
+- `.5/ARCHITECTURE.md` - Architecture pattern, layers & data flow, key abstractions, non-obvious conventions, where to add new code
+- `.5/TESTING.md` - Test organization, patterns, mocking approach, gotchas
+- `.5/CONCERNS.md` - Tech debt, known issues, security/integration/performance notes (**only if concerns found — skip file entirely if nothing detected**)
+
+**Create CLAUDE.md:**
 - Project overview and build commands
-- "Getting Started" guide with references to appropriate files
+- Links to whichever `.5/` documentation files were created
 - Workflow rules section (verbatim):
   ```
   ## Workflow Rules
@@ -370,17 +365,13 @@ Only generate rules for patterns that were actually detected:
 
 ## Acceptance Criteria
 - [ ] `.5/` directory created
-- [ ] All 7 documentation files exist and are populated:
-  - [ ] `.5/ARCHITECTURE.md`
-  - [ ] `.5/STACK.md`
-  - [ ] `.5/STRUCTURE.md`
-  - [ ] `.5/CONVENTIONS.md`
-  - [ ] `.5/TESTING.md`
-  - [ ] `.5/INTEGRATIONS.md`
-  - [ ] `.5/CONCERNS.md`
-- [ ] `CLAUDE.md` exists with references to `.5/` files
+- [ ] Documentation files exist and contain only non-derivable knowledge:
+  - [ ] `.5/ARCHITECTURE.md` — architecture, conventions, where to add code
+  - [ ] `.5/TESTING.md` — test patterns and gotchas
+  - [ ] `.5/CONCERNS.md` — only if concerns were found (omit if empty)
+- [ ] Empty sections omitted (no "Not detected" / "None found" placeholders)
+- [ ] `CLAUDE.md` exists with references to created `.5/` files
 - [ ] CLAUDE.md contains 6 coding guidelines
-- [ ] No placeholder text like `{YYYY-MM-DD}` remains unfilled
 - [ ] All specified project-specific skills are generated in `.claude/skills/`
 - [ ] Generated skills reference actual project conventions
 - [ ] If CLAUDE.md existed before, user-written sections are preserved

package/src/commands/5/eject.md

@@ -0,0 +1,91 @@
+---
+name: 5:eject
+description: Eject from the update mechanism — permanently removes update infrastructure
+allowed-tools: Bash, Read, Edit, AskUserQuestion
+user-invocable: true
+model: haiku
+context: fork
+---
+
+<role>
+You are a Workflow Ejector. You permanently remove the update infrastructure from this installation.
+After ejecting, you are DONE.
+</role>
+
+# Eject from Update Mechanism
+
+Ejecting permanently removes the update system from this installation. After ejecting:
+- The update check hook (`check-updates.js`) is deleted
+- The update command (`/5:update`) is deleted
+- The eject command (`/5:eject`) is deleted
+- Version tracking (`.5/version.json`) is deleted
+- The update cache (`.5/.update-cache.json`) is deleted
+- The `check-updates.js` hook entry is removed from `.claude/settings.json`
+
+All other workflow files (commands, skills, hooks, templates) remain untouched.
+
+**This is irreversible.** To restore update functionality, reinstall with `npx 5-phase-workflow`.
+
+## Step 1: Check Current State
+
+Read `.5/version.json`. If it doesn't exist, tell the user: "No 5-Phase Workflow installation found (or already ejected)." and stop.
+
+Note the `packageVersion` for the confirmation message.
+
+## Step 2: Confirm with User
+
+Tell the user what ejecting means:
+
+> **Eject from 5-Phase Workflow updates?**
+>
+> This will permanently delete:
+> - `.claude/hooks/check-updates.js` (update check hook)
+> - `.claude/commands/5/update.md` (update command)
+> - `.claude/commands/5/eject.md` (this command)
+> - `.5/version.json` (version tracking)
+> - `.5/.update-cache.json` (update cache)
+>
+> The `check-updates.js` hook entry will also be removed from `.claude/settings.json`.
+>
+> All other workflow files remain untouched. To restore updates later, reinstall with `npx 5-phase-workflow`.
+
+Ask: "Proceed with eject?"
+
+If the user declines, stop here.
+
+## Step 3: Delete Update Files
+
+Run this command to delete the update-related files:
+
+```bash
+rm -f .claude/hooks/check-updates.js .claude/commands/5/update.md .claude/commands/5/eject.md .5/version.json .5/.update-cache.json
+```
+
+## Step 4: Clean Up settings.json
+
+Read `.claude/settings.json`. Remove the hook entry from the `hooks.SessionStart` array where the command is `node .claude/hooks/check-updates.js`.
+
+Specifically, find and remove the object in the `SessionStart` array that looks like:
+
+```json
+{
+  "matcher": "startup",
+  "hooks": [
+    {
+      "type": "command",
+      "command": "node .claude/hooks/check-updates.js",
+      "timeout": 10
+    }
+  ]
+}
+```
+
+If the `SessionStart` array becomes empty after removal, remove the `SessionStart` key entirely. Write the updated settings back.
+
+## Step 5: Confirm
+
+Tell the user:
+
+> Ejected successfully. Update infrastructure has been removed from this installation (was v{packageVersion}).
+>
+> To restore update functionality, reinstall with: `npx 5-phase-workflow`

package/src/commands/5/reconfigure.md

@@ -117,7 +117,7 @@ Use the existing skills in `.claude/skills/` (from Step 2e) as the source of tru
 
 Use `AskUserQuestion` to show a summary and get confirmation. Present:
 
-1. **Documentation files that will be rewritten** — list all 7 `.5/*.md` files + CLAUDE.md
+1. **Documentation files that will be rewritten** — list `.5/ARCHITECTURE.md`, `.5/TESTING.md`, `.5/CONCERNS.md` (conditional) + CLAUDE.md
 2. **Skills that will be refreshed** — list ALL skills found in `.claude/skills/` (both workflow-generated and user-created)
 3. **Rules that will be refreshed** (if rules enabled) — list workflow-generated rule files in `.claude/rules/`
 4. **New patterns detected** (if any) — "These patterns were found in your codebase but don't have skills yet: [list]. Create skills for them?"
@@ -152,14 +152,16 @@ Refresh rules in .claude/rules/ (if rules.generate is true):
 - New rules to create: [if applicable]
 
 Re-analyze the entire codebase (A1 analysis) and:
-1. Rewrite all 7 .5/*.md documentation files
-2. Update CLAUDE.md (preserve user-written sections)
-3. Refresh ALL skills in .claude/skills/ — read current conventions from codebase and update each skill
-4. Create new skills for newly-added patterns
-5. Remove skills the user chose to drop
-6. Refresh all workflow-generated rule files in .claude/rules/ with updated conventions
-7. Create new rule files for newly-detected patterns
-8. Remove rule files the user chose to drop"
+1. Rewrite .5/ARCHITECTURE.md and .5/TESTING.md
+2. Rewrite .5/CONCERNS.md (or delete if no concerns found)
+3. Delete legacy docs if they exist: .5/STACK.md, .5/STRUCTURE.md, .5/CONVENTIONS.md, .5/INTEGRATIONS.md
+4. Update CLAUDE.md (preserve user-written sections)
+5. Refresh ALL skills in .claude/skills/ — read current conventions from codebase and update each skill
+6. Create new skills for newly-added patterns
+7. Remove skills the user chose to drop
+8. Refresh all workflow-generated rule files in .claude/rules/ with updated conventions
+9. Create new rule files for newly-detected patterns
+10. Remove rule files the user chose to drop"
 ```
 
 Use `subagent_type: "general-purpose"` for the Task.

package/src/hooks/statusline.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 // Claude Code Statusline
-// Shows: model | directory | context usage
+// Shows: model | folder | branch | off-peak | 5hr-usage | cost | context | reset-time
 
 const fs = require('fs');
 const path = require('path');
-const os = require('os');
+const { execSync } = require('child_process');
 
 // Read JSON from stdin
 let input = '';
@@ -13,77 +13,116 @@ process.stdin.on('data', chunk => input += chunk);
 process.stdin.on('end', () => {
   try {
     const data = JSON.parse(input);
+    const parts = [];
+
+    // 🤖 Model
     const model = data.model?.display_name || 'Claude';
+    parts.push(`\x1b[36m🤖 ${model}\x1b[0m`);
+
+    // 📁 Folder (basename only)
     const dir = data.workspace?.current_dir || process.cwd();
-    const session = data.session_id || '';
-    const remaining = data.context_window?.remaining_percentage;
+    const folderName = path.basename(dir);
+    parts.push(`\x1b[90m📁 ${folderName}\x1b[0m`);
 
-    // Context window display (shows USED percentage)
-    let ctx = '';
-    if (remaining != null) {
-      const rem = Math.round(remaining);
-      const used = Math.max(0, Math.min(100, 100 - rem));
+    // 🌿 Branch
+    let branch = data.worktree?.branch || '';
+    if (!branch) {
+      try {
+        branch = execSync('git rev-parse --abbrev-ref HEAD', {
+          encoding: 'utf8', cwd: dir, stdio: ['pipe', 'pipe', 'pipe']
+        }).trim();
+      } catch (e) { branch = ''; }
+    }
+    if (branch && branch !== 'HEAD') {
+      parts.push(`\x1b[32m🌿 ${branch}\x1b[0m`);
+    }
 
-      // Build progress bar (10 segments)
+    // 🚀 Off-peak indicator (weekdays before 5 AM or after 11 AM PT; all weekends)
+    // PT = UTC-8 (PST) or UTC-7 (PDT). Use UTC-7 as approximation (covers PDT/PST conservatively).
+    const nowUtc = new Date();
+    const ptHour = (nowUtc.getUTCHours() - 7 + 24) % 24; // approximate PT
+    const ptDay = new Date(nowUtc.getTime() - 7 * 3600 * 1000).getUTCDay(); // 0=Sun,6=Sat
+    const isWeekend = ptDay === 0 || ptDay === 6;
+    const isPeak = !isWeekend && ptHour >= 5 && ptHour < 11;
+    if (!isPeak) {
+      parts.push('\x1b[32m🚀 off-peak\x1b[0m');
+    }
+
+    // ⚡ 5-hour session usage
+    const fiveHrUsed = data.rate_limits?.five_hour?.used_percentage;
+    if (fiveHrUsed != null) {
+      const pct = Math.round(fiveHrUsed);
+      const color = pct < 50 ? '\x1b[32m' : pct < 75 ? '\x1b[33m' : '\x1b[31m';
+      parts.push(`${color}⚡ ${pct}%\x1b[0m`);
+    }
+
+    // 💰 Cost
+    const costUsd = data.cost?.total_cost_usd;
+    if (costUsd != null) {
+      const fmt = costUsd < 0.01 ? costUsd.toFixed(3) : costUsd.toFixed(2);
+      parts.push(`\x1b[33m💰 $${fmt}\x1b[0m`);
+    }
+
+    // 📊 Context window (progress bar)
+    const ctxUsed = data.context_window?.used_percentage;
+    const ctxRemaining = data.context_window?.remaining_percentage;
+    if (ctxUsed != null || ctxRemaining != null) {
+      const used = ctxUsed != null
+        ? Math.round(ctxUsed)
+        : Math.max(0, Math.min(100, 100 - Math.round(ctxRemaining)));
       const filled = Math.floor(used / 10);
       const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);
+      let color;
+      if (used < 50)      color = '\x1b[32m';
+      else if (used < 65) color = '\x1b[33m';
+      else if (used < 80) color = '\x1b[38;5;208m';
+      else                color = '\x1b[5;31m';
+      parts.push(`${color}🧠 ${bar} ${used}%\x1b[0m`);
+    }
 
-      // Color based on usage
-      if (used < 50) {
-        ctx = ` \x1b[32m${bar} ${used}%\x1b[0m`;
-      } else if (used < 65) {
-        ctx = ` \x1b[33m${bar} ${used}%\x1b[0m`;
-      } else if (used < 80) {
-        ctx = ` \x1b[38;5;208m${bar} ${used}%\x1b[0m`;
-      } else {
-        ctx = ` \x1b[5;31m💀 ${bar} ${used}%\x1b[0m`;
+    // ⏱ Reset time (time until 5hr window resets)
+    const resetAt = data.rate_limits?.five_hour?.resets_at;
+    if (resetAt) {
+      const remaining = resetAt - Math.floor(Date.now() / 1000);
+      if (remaining > 0) {
+        const h = Math.floor(remaining / 3600);
+        const m = Math.floor((remaining % 3600) / 60);
+        const label = h > 0 ? `${h}h${m}m` : `${m}m`;
+        parts.push(`\x1b[90m⏱ ${label}\x1b[0m`);
       }
     }
 
-    // Shorten directory path for display
-    const shortDir = dir.replace(os.homedir(), '~');
-
-    // Check for available update and reconfigure reminder
-    let updateIndicator = '';
-    let reconfigIndicator = '';
+    // Update and reconfigure indicators
     try {
       const versionFile = path.join(dir, '.5', 'version.json');
       const versionData = JSON.parse(fs.readFileSync(versionFile, 'utf8'));
 
-      // Update check — read latestAvailableVersion from cache file (gitignored)
       const cacheFile = path.join(dir, '.5', '.update-cache.json');
       let latest = null;
       if (fs.existsSync(cacheFile)) {
         try {
           const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
           latest = cache.latestAvailableVersion || null;
-        } catch(e) {}
+        } catch (e) {}
       }
-      const installed = versionData.packageVersion;
-      if (latest && installed && compareVersions(installed, latest) < 0) {
-        updateIndicator = ` | \x1b[33m↑${latest} → /5:update\x1b[0m`;
+      if (latest && versionData.packageVersion && compareVersions(versionData.packageVersion, latest) < 0) {
+        parts.push(`\x1b[33m↑${latest} → /5:update\x1b[0m`);
       }
 
-      // Reconfigure check (reads flag file in .5/, gitignored)
       const flagFile = path.join(dir, '.5', '.reconfig-reminder');
       if (fs.existsSync(flagFile)) {
-        reconfigIndicator = ` | \x1b[35m↻ /5:reconfigure\x1b[0m`;
+        parts.push(`\x1b[35m↻ /5:reconfigure\x1b[0m`);
       }
-    } catch (e) {
-      // No version file or parse error — no indicator
-    }
+    } catch (e) {}
 
-    // Build and output statusline: model | directory | context | update | reconfig
-    const statusline = `\x1b[36m${model}\x1b[0m | \x1b[90m${shortDir}\x1b[0m${ctx}${updateIndicator}${reconfigIndicator}`;
-    process.stdout.write(statusline);
+    process.stdout.write(parts.join(' | '));
 
   } catch (e) {
-    // Silent fail - don't break statusline on parse errors
+    // Silent fail — don't break statusline on parse errors
   }
 });
 
 // Compare semver versions: returns -1 if v1 < v2, 0 if equal, 1 if v1 > v2
-// Uses parseInt to handle pre-release tags (e.g., "2-beta" → 2)
 function compareVersions(v1, v2) {
   const parts1 = v1.split('.').map(p => parseInt(p, 10) || 0);
   const parts2 = v2.split('.').map(p => parseInt(p, 10) || 0);
@@ -92,4 +131,4 @@ function compareVersions(v1, v2) {
     if (parts1[i] < parts2[i]) return -1;
   }
   return 0;
-}
+}

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

@@ -49,97 +49,48 @@ In both modes, the analysis and generation logic is identical — only where the
 
 **Process:**
 
-### A1. Unified Codebase Analysis
+### A1. Codebase Analysis
 
-Perform comprehensive analysis once to gather data for ALL templates:
-
-**Structure Analysis** (for STRUCTURE.md):
-- Use Glob to map directory tree: `**/*` (with depth limits to avoid overwhelming results)
-- Identify source directories (`src/`, `lib/`, `app/`, etc.)
-- Identify test directories and their organization
-- Identify configuration directories
-- Determine file naming conventions (camelCase, kebab-case, PascalCase)
-- Locate key files (entry points, configurations)
-
-**Stack Analysis** (for STACK.md):
-- Read package manifests: `package.json`, `Cargo.toml`, `go.mod`, `pom.xml`, `requirements.txt`, `Gemfile`
-- Extract: language, version, runtime, package manager
-- Identify frameworks in dependencies (React, Express, Django, Rails, etc.)
-- List critical dependencies and their versions
-- Find config files: `tsconfig.json`, `.eslintrc`, etc.
+Perform focused analysis to gather data for documentation templates. Only capture information that **cannot be derived** by reading project files directly — skip version numbers, dependency lists, directory layouts, linter configs, and other facts that Claude Code can look up on demand.
 
 **Architecture Analysis** (for ARCHITECTURE.md):
 - Identify architectural pattern (MVC, layered, modular, microservices) from directory structure
 - Map layers by directory structure (controllers/, services/, models/, routes/, etc.)
 - Trace data flow patterns (read 2-3 example files from different layers)
 - Identify key abstractions (interfaces, base classes, common patterns)
-- Find entry points (`index.ts`, `main.go`, `app.py`, `server.js`)
-- Analyze error handling strategy (try/catch, Result types, middleware, error boundaries)
-
-**Conventions Analysis** (for CONVENTIONS.md):
-- Sample 5-10 files from main source directory
-- Extract naming patterns: files, functions, variables, types/classes
-- Find formatters/linters: `.prettierrc`, `.eslintrc`, `black.toml`, `.rubocop.yml`
-- Identify import organization patterns (order, grouping, aliases)
-- Determine logging approach (console, winston, log4j, etc.)
-- Check comment/documentation patterns (JSDoc, Javadoc, etc.)
+- Identify non-obvious conventions: implicit rules not enforced by tooling (e.g., "all services extend BaseService", "barrel exports required per module"). Skip anything in .eslintrc, .prettierrc, tsconfig, etc.
+- Determine where new code should go (new features, tests, utilities)
 
 **Testing Analysis** (for TESTING.md):
-- Find test files: `**/*.test.{ts,js}`, `**/*.spec.{ts,js}`, `**/*_test.go`, `test_*.py`, `*_spec.rb`
-- Read test config: `jest.config.js`, `vitest.config.ts`, `pytest.ini`, `spec/spec_helper.rb`
 - Determine test organization (co-located vs separate `test/` or `spec/`)
-- Extract test naming patterns
-- Identify mocking framework (jest.mock, sinon, pytest-mock, etc.)
+- Identify mocking framework and project-specific mocking conventions
 - Find fixture/factory patterns
-- Extract test run commands from package.json, Makefile, or similar
-
-**Integration Analysis** (for INTEGRATIONS.md):
-- Scan dependencies for SDK packages (axios, @aws-sdk, stripe, @google-cloud, etc.)
-- Identify database clients/ORMs (prisma, mongoose, sqlalchemy, activerecord, etc.)
-- Find auth providers (passport, next-auth, devise, etc.)
-- Detect monitoring/logging services (datadog, sentry, newrelic)
-- Read CI/CD config: `.github/workflows/`, `.gitlab-ci.yml`, `.circleci/config.yml`
-- Grep for environment variables: `process.env`, `os.getenv`, `ENV[`, etc.
+- Note gotchas: setup/teardown quirks, env requirements, flaky areas
 
-**Concerns Analysis** (for CONCERNS.md):
+**Concerns Analysis** (for CONCERNS.md — conditional):
 - Grep for TODO/FIXME/HACK/XXX/DEPRECATED comments across all code
 - Check for common security issues (SQL injection patterns, XSS vulnerabilities)
-- Identify deprecated dependencies (check for warnings in package manifests)
-- Look for complex code sections (deeply nested conditionals, long functions)
+- Identify non-obvious integration details: auth flows, required env vars not documented elsewhere, webhook contracts, gotchas with external services
+- Look for performance bottlenecks or scaling limits mentioned in comments/docs
 
 ### A2. Fill Templates
 
-For each template in `src/templates/`:
+For each template in `.claude/templates/`:
 
 1. Read template content with Read tool
-2. Replace placeholders with analyzed data:
-   - Date placeholders: `{YYYY-MM-DD}`, `{date}` → current date (format: YYYY-MM-DD)
-   - Template-specific placeholders → actual project data from B1 analysis
-3. Handle missing data gracefully: mark sections as "Not detected" or "None found" rather than omitting
+2. Replace placeholders with analyzed data from A1
+3. **Omit sections entirely if no data was found** — do not write "Not detected" or "None found"
+4. For CONCERNS.md: if ALL sections would be empty, **do not create the file at all**
 
 **Placeholder mapping examples**:
 
 ARCHITECTURE.md:
 - `{Pattern name}` → "Layered Architecture" or "MVC" or "Modular Monolith"
-- `{Layer Name}` → "Controllers", "Services", "Repositories"
+- `{Layer}` → "Controllers", "Services", "Repositories"
 - `{path}` → "src/controllers/", "src/services/"
 
-STACK.md:
-- `{Language} {Version}` → "TypeScript 5.3.3", "Python 3.11"
-- `{Framework} {Version}` → "Express 4.18.2", "Django 4.2"
-- `{Package} {Version}` → "axios 1.6.0"
-
-CONVENTIONS.md:
-- `{Pattern observed}` → "PascalCase for classes, camelCase for functions"
-- `{Tool used}` → "Prettier with 2-space indent"
-
 TESTING.md:
-- `{Framework} {Version}` → "Jest 29.5.0"
-- `{command}` → "npm test", "pytest"
-
-INTEGRATIONS.md:
-- `{Service}` → "PostgreSQL", "Stripe API"
-- `{package}` → "@stripe/stripe-js"
+- Describe actual patterns observed, not framework names/versions (those are in config files)
 
 CONCERNS.md:
 - `{file paths}` → Actual file paths from grep results
@@ -149,22 +100,17 @@ CONCERNS.md:
 Write filled templates to `.5/` folder:
 
 1. Ensure `.5/` directory exists: `mkdir -p .5`
-2. Write each filled template:
-   - `.5/ARCHITECTURE.md`
-   - `.5/STACK.md`
-   - `.5/STRUCTURE.md`
-   - `.5/CONVENTIONS.md`
-   - `.5/TESTING.md`
-   - `.5/INTEGRATIONS.md`
-   - `.5/CONCERNS.md`
+2. Write filled templates:
+   - `.5/ARCHITECTURE.md` — always created
+   - `.5/TESTING.md` — always created
+   - `.5/CONCERNS.md` — **only if concerns were found** (skip if all sections empty)
 
-### A4. Create Master CLAUDE.md
+### A4. Create CLAUDE.md
 
-Generate CLAUDE.md as a navigation hub:
+Generate CLAUDE.md:
 
 CLAUDE.md structure:
-- **Quick Reference:** Links to all 7 `.5/*.md` files (STACK, STRUCTURE, ARCHITECTURE, CONVENTIONS, TESTING, INTEGRATIONS, CONCERNS)
-- **Project Overview:** 1-2 paragraphs from README/package.json
+- **Project Overview:** 1-2 sentences from README/package.json
 - **Build & Run Commands:** Build, test, and other detected commands
 - **Workflow Rules:** Include this section verbatim:
   ```
@@ -174,7 +120,7 @@ CLAUDE.md structure:
   Each phase produces a specific artifact — do not create artifacts belonging to other phases.
   ```
 - **Coding Guidelines:** The 6 mandatory principles (types, concise docs, short files, extract methods, SRP/DRY, maintainable/modular)
-- **Getting Started:** Links to relevant `.5/` files for new devs and specific tasks
+- **Project Documentation:** Links to whichever `.5/` files were created (only list files that exist)
 
 ### A5. Preserve Existing Content
 
@@ -430,15 +376,11 @@ When running in REFRESH MODE:
 Returns structured results for each component:
 
 ```
-Component A (Documentation): SUCCESS - Created 7 documentation files + index
+Component A (Documentation): SUCCESS - Created documentation files + CLAUDE.md
   - .5/ARCHITECTURE.md (Pattern: Layered, 4 layers identified)
-  - .5/STACK.md (TypeScript + Express, 23 dependencies)
-  - .5/STRUCTURE.md (8 top-level directories mapped)
-  - .5/CONVENTIONS.md (PascalCase/camelCase, Prettier formatting)
-  - .5/TESTING.md (Jest framework, 45 test files)
-  - .5/INTEGRATIONS.md (PostgreSQL, 2 APIs, GitHub Actions)
-  - .5/CONCERNS.md (3 TODO items, 1 deprecated dependency)
-  - CLAUDE.md (index with references)
+  - .5/TESTING.md (mocking patterns, gotchas documented)
+  - .5/CONCERNS.md (3 TODO items, 1 security note) [or "skipped — no concerns found"]
+  - CLAUDE.md (updated with references)
 Component B (Pattern Skills): SUCCESS - Generated 3 create-* skills (create-component, create-hook, create-context)
 Component C (Command Skills): SUCCESS - Generated 2 run-* skills (run-tests, run-lint)
 Component D (Rules): SUCCESS - Generated 3 rule files (code-style, testing, dependencies)

package/src/skills/generate-readme/SKILL.md

@@ -76,8 +76,7 @@ Check for:
 
 Look for patterns in project documentation:
 
-- Check `.5/ARCHITECTURE.md` for architectural patterns (MVC, Clean Architecture, etc.)
-- Check `.5/CONVENTIONS.md` for coding conventions and design patterns
+- Check `.5/ARCHITECTURE.md` for architectural patterns and non-obvious conventions
 - Check `.5/TESTING.md` for test patterns and conventions
 - Fall back to CLAUDE.md if `.5/` documentation not present
 - Check module-specific documentation