5-phase-workflow 1.8.5 → 1.8.7

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,25 +100,27 @@ 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:
+  ```
+  ## Workflow Rules
+  When running `/5:` workflow commands, follow the command instructions exactly as written.
+  Do not skip steps, combine phases, or proceed to actions not specified in the current command.
+  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
 
@@ -423,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

package/src/templates/ARCHITECTURE.md

@@ -1,64 +1,33 @@
 # Architecture
 
-**Analysis Date:** {YYYY-MM-DD}
+## Pattern
 
-## Pattern Overview
+**Overall:** {Pattern name — e.g., Layered, MVC, Modular Monolith}
 
-**Overall:** {Pattern name}
+{1-2 sentences explaining the architectural approach and key design decisions}
 
-**Key Characteristics:**
-- {Characteristic 1}
-- {Characteristic 2}
-- {Characteristic 3}
+## Layers & Data Flow
 
-## Layers
-
-**{Layer Name}:**
-- Purpose: {What this layer does}
-- Location: `{path}`
-- Contains: {Types of code}
-- Depends on: {What it uses}
-- Used by: {What uses it}
-
-## Data Flow
-
-**{Flow Name}:**
-
-1. {Step 1}
-2. {Step 2}
-3. {Step 3}
-
-**State Management:**
-- {How state is handled}
+| Layer | Location | Depends On | Notes |
+|-------|----------|------------|-------|
+| {Layer} | `{path}` | {Dependencies} | {Key responsibility or constraint} |
 
 ## Key Abstractions
 
 **{Abstraction Name}:**
 - Purpose: {What it represents}
+- Pattern: {How it's used across the codebase}
 - Examples: `{file paths}`
-- Pattern: {Pattern used}
-
-## Entry Points
-
-**{Entry Point}:**
-- Location: `{path}`
-- Triggers: {What invokes it}
-- Responsibilities: {What it does}
-
-## Error Handling
-
-**Strategy:** {Approach}
 
-**Patterns:**
-- {Pattern 1}
-- {Pattern 2}
+## Non-Obvious Conventions
 
-## Cross-Cutting Concerns
+{ONLY conventions not enforced by tooling or visible in config files. Skip anything in .eslintrc, .prettierrc, tsconfig, etc.}
 
-**Logging:** {Approach}
-**Validation:** {Approach}
-**Authentication:** {Approach}
+- {e.g., "All services must extend BaseService for lifecycle hooks"}
+- {e.g., "Barrel exports required in each module directory"}
 
----
+## Where to Add New Code
 
-*Architecture analysis: {date}*
+- New feature: `{path}`
+- New tests: `{path}`
+- Shared utilities: `{path}`

package/src/templates/CONCERNS.md

@@ -1,6 +1,4 @@
-# Codebase Concerns
-
-**Analysis Date:** {YYYY-MM-DD}
+# Concerns
 
 ## Tech Debt
 
@@ -8,68 +6,28 @@
 - Issue: {What's the shortcut/workaround}
 - Files: `{file paths}`
 - Impact: {What breaks or degrades}
-- Fix approach: {How to address it}
 
-## Known Bugs
+## Known Issues
 
-**{Bug description}:**
+**{Issue description}:**
 - Symptoms: {What happens}
 - Files: `{file paths}`
-- Trigger: {How to reproduce}
-- Workaround: {If any}
+- Trigger/Workaround: {How to reproduce, how to avoid}
 
-## Security Considerations
+## Security Notes
 
 **{Area}:**
 - Risk: {What could go wrong}
-- Files: `{file paths}`
 - Current mitigation: {What's in place}
-- Recommendations: {What should be added}
-
-## Performance Bottlenecks
-
-**{Slow operation}:**
-- Problem: {What's slow}
-- Files: `{file paths}`
-- Cause: {Why it's slow}
-- Improvement path: {How to speed up}
-
-## Fragile Areas
-
-**{Component/Module}:**
-- Files: `{file paths}`
-- Why fragile: {What makes it break easily}
-- Safe modification: {How to change safely}
-- Test coverage: {Gaps}
-
-## Scaling Limits
-
-**{Resource/System}:**
-- Current capacity: {Numbers}
-- Limit: {Where it breaks}
-- Scaling path: {How to increase}
-
-## Dependencies at Risk
 
-**{Package}:**
-- Risk: {What's wrong}
-- Impact: {What breaks}
-- Migration plan: {Alternative}
+## Integration Notes
 
-## Missing Critical Features
+**{Service/System}:**
+- {Non-obvious details: auth flows, required env vars, webhook contracts, gotchas with external services}
 
-**{Feature gap}:**
-- Problem: {What's missing}
-- Blocks: {What can't be done}
+## Performance Notes
 
-## Test Coverage Gaps
-
-**{Untested area}:**
-- What's not tested: {Specific functionality}
+**{Slow operation or scaling limit}:**
+- Problem: {What's slow or where it breaks}
 - Files: `{file paths}`
-- Risk: {What could break unnoticed}
-- Priority: {High/Medium/Low}
-
----
-
-*Concerns audit: {date}*
+- Improvement path: {How to address}

package/src/templates/TESTING.md

@@ -1,107 +1,24 @@
 # Testing Patterns
 
-**Analysis Date:** {YYYY-MM-DD}
+## Organization
 
-## Test Framework
+{Co-located with source or separate directory? Naming pattern for test files?}
 
-**Runner:**
-- {Framework} {Version}
-- Config: `{config file}`
+## Patterns
 
-**Assertion Library:**
-- {Library}
-
-**Run Commands:**
-```bash
-{command}              # Run all tests
-{command}              # Watch mode
-{command}              # Coverage
-```
-
-## Test File Organization
-
-**Location:**
-
-    {Pattern: co-located or separate}
-
-**Naming:**
-
-    {Pattern}
-
-**Structure:**
-
-{Directory pattern}
-
-## Test Structure
-
-**Suite Organization:**
-
-{Show actual pattern from codebase}
-
-**Patterns:**
-
-- {Setup pattern}
-- {Teardown pattern}
-- {Assertion pattern}
+{Project-specific test structure — describe how tests are organized within a file, setup/teardown conventions}
 
 ## Mocking
 
-**Framework:**
-- {Tool}
-
-**Patterns:**
-
-{Show actual mocking pattern from codebase}
-
-**What to Mock:**
-
-{Guidelines}
-
-**What NOT to Mock:**
-
-{Guidelines}
-
-## Fixtures and Factories
-
-**Test Data:**
-
-{Show pattern from codebase}
-
-**Location:**
-
-{Where fixtures live}
-
-## Coverage
-
-**Requirements:**
-- {Target or "None enforced"}
-
-**View Coverage:**
-
-```bash
-{command}
-```
-
-## Test Types
-
-**Unit Tests:**
-
-{Scope and approach}
-
-**Integration Tests:**
-
-{Scope and approach}
-
-**E2E Tests:**
-
-{Framework or "Not used"}
-
-## Common Patterns
+**Approach:**
+- {Mocking framework/tool used}
 
-**Async Testing:**
+**What to mock:**
+- {Guidelines — e.g., external APIs, database calls}
 
-{Pattern}
+**What NOT to mock:**
+- {Guidelines — e.g., pure business logic, utility functions}
 
-**Error Testing:**
+## Gotchas
 
-{Pattern}
+{Things that trip people up: setup/teardown quirks, env requirements, flaky areas, test-specific config}

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

@@ -1,151 +0,0 @@
----
-name: build-project
-description: Builds the project using auto-detected or configured build system. Supports npm, gradle, cargo, go, maven, make, and more. Use when compiling, building, or verifying project build status.
-allowed-tools: Bash, Read, Grep
-model: sonnet
-context: fork
-user-invocable: true
----
-
-# Build Project
-
-## Overview
-
-This skill executes build tasks with auto-detection of the build system and sufficient timeout for long-running builds. It provides structured error reporting and actionable suggestions when builds fail.
-
-## Build System Detection
-
-The skill automatically detects the build system using:
-
-1. **Config file** (`.5/config.json`) - if `build.command` is specified
-2. **Auto-detection** - by examining project files:
-   - `package.json` → npm/yarn/pnpm
-   - `build.gradle` or `build.gradle.kts` → Gradle
-   - `pom.xml` → Maven
-   - `Cargo.toml` → Cargo (Rust)
-   - `go.mod` → Go
-   - `Makefile` → Make
-   - `setup.py` or `pyproject.toml` → Python
-
-## Build Targets
-
-| Target | Use Case |
-|--------|----------|
-| `compile` | Fast compilation check (no tests, no packaging) |
-| `build` | Full build (may include tests depending on tool) |
-| `clean` | Clean build (removes previous artifacts first) |
-
-## Parameters
-
-When invoked, the skill expects:
-
-- **target** (optional, default: `build`): One of `compile`, `build`, `clean`
-- **module** (optional): Specific module to build (for monorepos)
-
-## Execution Process
-
-### 1. Load Configuration
-
-Read `.5/config.json` if it exists:
-
-```json
-{
-  "build": {
-    "command": "npm run build",
-    "compileCommand": "npm run compile",
-    "cleanCommand": "npm run clean"
-  }
-}
-```
-
-If commands are specified, use them. Otherwise, auto-detect.
-
-### 2. Detect Build System
-
-If no config, detect by checking project files: `package.json` + lock files (npm/yarn/pnpm), `build.gradle` (gradle), `pom.xml` (mvn), `Cargo.toml` (cargo), `go.mod` (go), `Makefile` (make).
-
-### 3. Determine Build Command
-
-Based on detected tool and target:
-
-| Tool | compile | build | clean |
-|------|---------|-------|-------|
-| npm | `npm run build` | `npm run build` | `rm -rf dist node_modules && npm install` |
-| yarn | `yarn build` | `yarn build` | `yarn clean` or `rm -rf dist` |
-| pnpm | `pnpm build` | `pnpm build` | `pnpm clean` or `rm -rf dist` |
-| gradle | `./gradlew compileJava -x test --offline` | `./gradlew build -x test --offline` | `./gradlew clean build` |
-| mvn | `mvn compile` | `mvn package -DskipTests` | `mvn clean package` |
-| cargo | `cargo check` | `cargo build` | `cargo clean && cargo build` |
-| go | `go build ./...` | `go build ./...` | `go clean && go build ./...` |
-| make | `make` | `make` | `make clean` |
-
-### 4. Execute Build with Proper Timeout
-
-**IMPORTANT**: Builds can take several minutes. Use generous timeout:
-
-```bash
-# Timeout based on target
-# - compile: 2 minutes (120000ms)
-# - build: 10 minutes (600000ms)
-# - clean: 15 minutes (900000ms)
-```
-
-Execute the command and capture output.
-
-### 5. Parse Build Output
-
-Determine success/failure from tool-specific patterns (exit code, `BUILD SUCCESSFUL`, `BUILD SUCCESS`, `Finished`, etc.). For failures, extract file paths, line numbers, and error messages. Identify error type (compilation, dependency, memory, tool not found) and suggest appropriate fix.
-
-### 6. Format Output
-
-Provide structured response:
-
-```
-BUILD STATUS: ✓ SUCCESS | ✗ FAILED
-DURATION: 2m 34s
-TOOL: {detected-tool}
-TARGET: {target}
-MODULE: {module or "all"}
-
-SUMMARY:
-- Build completed successfully
-OR
-- Build failed with X errors
-
-ERRORS: (if any)
-File: path/to/file.ext:42
-Error: {error message}
-
-File: path/to/another.ext:15
-Error: {error message}
-
-SUGGESTIONS:
-- {actionable suggestion based on error type}
-```
-
-## Error Handling
-
-- If build tool cannot be detected, return error with list of checked locations
-- If command times out, report timeout with suggestion to increase timeout or optimize build
-- If build fails, extract and format all errors for user
-- Always include the raw command that was executed for reproducibility
-
-## DO NOT
-
-- DO NOT modify source files
-- DO NOT install dependencies (unless explicitly part of clean target)
-- DO NOT run tests (use `/run-tests` skill for that)
-- DO NOT assume a specific build system - always detect or use config
-- DO NOT use overly short timeouts (builds can be slow)
-
-## Example
-
-```
-User: /build-project
-Skill: [Detects npm] → [Runs: npm run build] → [Reports success with duration]
-```
-
-## Related Documentation
-
-- [5-Phase Workflow Guide](../../docs/workflow-guide.md)
-- [/run-tests skill](../run-tests/SKILL.md)