5-phase-workflow 1.0.0

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

@@ -0,0 +1,355 @@
+---
+name: configure-project
+description: Creates project configuration files, analyzes codebase for CLAUDE.md, and generates project-specific skills. Used during /5:implement-feature CONFIGURE.
+allowed-tools: Read, Write, Bash, Glob, Grep
+model: sonnet
+context: fork
+user-invocable: false
+---
+
+# Configure Project Skill
+
+## Overview
+
+This skill does the heavy lifting during Phase 3 (implement-feature) for the CONFIGURE feature. It is called by step-executor to create the actual configuration files.
+
+It handles three distinct tasks, invoked with different parameters per component:
+
+- **A. Write config.json** - Creates the project configuration file
+- **B. Analyze Codebase and Create/Update CLAUDE.md** - Maps codebase and documents conventions
+- **C. Generate Project-Specific Skills** - Creates SKILL.md files for common project patterns
+
+---
+
+## A. Write config.json
+
+**Receives:** project type, ticket config, branch config, build/test commands, tool availability
+
+**Creates:** `.claude/.5/config.json`
+
+**Schema (no `steps` array):**
+
+```json
+{
+  "projectType": "{type}",
+  "ticket": {
+    "pattern": "{regex-pattern-or-null}",
+    "extractFromBranch": true
+  },
+  "branch": {
+    "convention": "{convention}"
+  },
+  "build": {
+    "command": "{build-command}",
+    "testCommand": "{test-command}",
+    "timeout": {
+      "compile": 120000,
+      "test": 300000
+    }
+  },
+  "tools": {
+    "coderabbit": {
+      "available": false,
+      "authenticated": false
+    },
+    "ide": {
+      "available": false,
+      "type": null
+    }
+  },
+  "reviewTool": "coderabbit" or "none"
+}
+```
+
+**Process:**
+1. Read all values from the feature spec (`.5/CONFIGURE/feature.md`)
+2. Ensure `.claude/.5/` directory exists (create with `mkdir -p` if needed)
+3. Write `config.json` with pretty-printed JSON
+4. Read back to verify correctness
+
+---
+
+## B. Analyze Codebase and Create/Update CLAUDE.md
+
+**Process:**
+
+### B1. Unified 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.
+
+**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.)
+
+**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.)
+- 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.
+
+**Concerns Analysis** (for CONCERNS.md):
+- 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)
+
+### B2. Fill Templates
+
+For each template in `src/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
+
+**Placeholder mapping examples**:
+
+ARCHITECTURE.md:
+- `{Pattern name}` → "Layered Architecture" or "MVC" or "Modular Monolith"
+- `{Layer Name}` → "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"
+
+CONCERNS.md:
+- `{file paths}` → Actual file paths from grep results
+
+### B3. Write Documentation Files
+
+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`
+
+### B4. Create Master CLAUDE.md
+
+Generate CLAUDE.md as a navigation hub:
+
+```markdown
+# {Project Name}
+
+> Generated: {YYYY-MM-DD}
+> Documentation is organized into focused files for better maintainability
+
+## Quick Reference
+
+- [Technology Stack](./.5/STACK.md) - Languages, frameworks, dependencies
+- [Codebase Structure](./.5/STRUCTURE.md) - Directory layout and organization
+- [Architecture](./.5/ARCHITECTURE.md) - Patterns, layers, and data flow
+- [Coding Conventions](./.5/CONVENTIONS.md) - Naming, style, and patterns
+- [Testing Patterns](./.5/TESTING.md) - Test framework and patterns
+- [External Integrations](./.5/INTEGRATIONS.md) - APIs, databases, services
+- [Codebase Concerns](./.5/CONCERNS.md) - Tech debt, bugs, and risks
+
+## Project Overview
+
+{1-2 paragraph summary from README or package.json description}
+
+## Build & Run Commands
+
+- Build: `{build-command}`
+- Test: `{test-command}`
+- {Other detected scripts}
+
+## Coding Guidelines
+
+When working with this codebase, follow these principles:
+
+1. Types should be clear and types should be available when possible
+2. Use doc (jsdoc, javadoc, pydoc, etc) concisely. No doc is better than meaningless doc
+3. Keep files short and structured
+4. Extract methods, classes
+5. Respect SRP and DRY
+6. Make code maintainable and modular
+
+## Getting Started
+
+**For new developers:**
+1. Review [Stack](./.5/STACK.md) for technology overview
+2. Read [Structure](./.5/STRUCTURE.md) to understand organization
+3. Study [Conventions](./.5/CONVENTIONS.md) for coding standards
+4. Check [Architecture](./.5/ARCHITECTURE.md) for design patterns
+
+**For specific tasks:**
+- Adding features → See [Architecture](./.5/ARCHITECTURE.md)
+- Writing tests → See [Testing](./.5/TESTING.md)
+- Integration work → See [Integrations](./.5/INTEGRATIONS.md)
+- Reviewing concerns → See [Concerns](./.5/CONCERNS.md)
+```
+
+### B5. Preserve Existing Content
+
+If CLAUDE.md already exists:
+- Read current content
+- Identify user-written custom sections (not matching template structure)
+- Preserve under "Custom Documentation" section in new CLAUDE.md
+- Ensure 6 mandatory coding guidelines are retained
+
+---
+
+## C. Generate Project-Specific Skills
+
+**Creates:** SKILL.md files in `.claude/skills/{name}/SKILL.md`
+
+Each skill follows the standard frontmatter pattern and contains instructions derived from analyzing the actual project structure (reads existing files to derive patterns/templates).
+
+### Skill Detection by Project Type
+
+| Project Type | Skills |
+|---|---|
+| Next.js | create-page, create-api-route, create-component |
+| NestJS | create-module, create-service, create-controller |
+| Express | create-route, create-middleware, create-service |
+| React | create-component, create-hook, create-context |
+| Django | create-model, create-view, create-serializer |
+| Flask | create-blueprint, create-model |
+| Java (Gradle/Maven) | create-entity, create-service, create-controller, create-repository |
+| Rust | create-module |
+| Go | create-handler, create-service |
+| Rails | create-model, create-controller |
+| Generic | create-module |
+
+### Skill Generation Process
+
+For each skill to generate:
+1. Identify existing examples of that pattern in the codebase (e.g., find existing components for `create-component`)
+2. Read 1-2 examples to extract the project's conventions and structure
+3. Create a SKILL.md that instructs the agent to follow those conventions
+4. Each generated SKILL.md should include:
+   - Standard frontmatter (name, description, allowed-tools, model: sonnet, context: fork, user-invocable: false)
+   - What the skill creates
+   - File naming and location conventions (derived from existing code)
+   - Template/pattern to follow (derived from existing code)
+   - Checklist of what to include
+
+### Example Generated Skill
+
+```yaml
+---
+name: create-component
+description: Creates a React component following project conventions.
+allowed-tools: Read, Write, Glob, Grep
+model: sonnet
+context: fork
+user-invocable: false
+---
+```
+
+```markdown
+# Create Component
+
+## What This Skill Creates
+A React component following this project's conventions.
+
+## Conventions (from project analysis)
+- Location: `src/components/{ComponentName}/`
+- Files: `index.tsx`, `{ComponentName}.tsx`, `{ComponentName}.test.tsx`
+- Style: CSS Modules at `{ComponentName}.module.css`
+- Exports: Named export from component file, re-exported from index
+
+## Template
+{Derived from existing components in the project}
+
+## Checklist
+- [ ] Component file created
+- [ ] Props interface defined
+- [ ] Test file created
+- [ ] Index file with re-export
+- [ ] Follows naming conventions
+```
+
+---
+
+## Output Contract
+
+Returns structured results for each component:
+
+```
+Component A (config.json): SUCCESS - Created .claude/.5/config.json
+Component B (Documentation): SUCCESS - Created 7 documentation files + index
+  - .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)
+Component C (Skills): SUCCESS - Generated 3 skills (create-component, create-hook, create-context)
+```
+
+Or on failure:
+
+```
+Component A (config.json): FAILED - Permission denied writing to .claude/.5/
+Component B (Documentation): FAILED - Unable to read template files
+```
+
+## DO NOT
+
+- DO NOT overwrite existing user-written CLAUDE.md sections
+- DO NOT generate skills for patterns that don't exist in the project
+- DO NOT include `steps` in config.json
+- DO NOT hardcode conventions - always derive from actual project analysis
+- DO NOT generate empty or placeholder skill files

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

@@ -0,0 +1,168 @@
+# README Examples
+
+This file contains approved examples of concise READMEs for different module types.
+
+---
+
+## Example 1: Model Module (user-model)
+
+**Module Type:** Model layer
+**Characteristics:** Domain entities, factory, CQRS requests, validators
+**Length:** 54 lines
+
+```markdown
+# user-model
+
+## Purpose
+
+This module contains the core Mission domain model, including the Mission aggregate root, Order, UnitOrder, and related
+entities. It provides the MissionFactory for creating and modifying missions according to business rules, along with
+validators, queries, and CQRS request objects for mission operations.
+
+## Key Components
+
+- `Mission` - Root aggregate containing orders, mission units, and mission unit groups
+- `MissionFactory` - Factory for all mission operations (create, addOrder, addUnitOrders, updateQuoteTerms)
+- CQRS requests in `request/` package for commands and queries
+- Validators in `validation/` package
+- Predicates in `model/*/Is*Predicate.ts` for business rules
+
+## Testing
+
+Test fixtures available in `src/testFixtures/`:
+
+\`\`\`java
+// Simple
+var mission = this.missionTestFixture.create();
+
+// Customized
+var mission = this.missionTestFixture.createBuilder()
+.withOrderTemplateType(OrderTemplateType.DOOR_DOOR)
+.withNumberOfUnitOrders(3)
+.build();
+
+// Customization of sub objects
+var mission = this.missionTestFixture.create(
+CreateMissionTestParameters.builderWithOrder(
+CreateOrderTestParameters.builderWithUnitOrders(
+CreateUnitOrderTestParameters.builder()
+.collectionHandoverGroup(collectionHandoverGroup)
+.deliveryHandoverGroup(deliveryHandoverGroup)
+.build())
+.id(orderId)
+.orderTemplateType(orderTemplateType)
+.build())
+.build());
+
+// Add order
+var result = missionTestFixture.addOrder(this.mission, addOrderParameters);
+\`\`\`
+
+## Critical Patterns
+
+1. **Always use MissionFactory** - Never manually create Mission/Order/UnitOrder connections
+2. **Factory manages state** - Offsets, aliases, and IDs are calculated automatically
+3. **Result objects** - Factory operations return result objects with both created entity and updated aggregate
+4. **Handovers regenerated** - Template type changes recreate entire handover structure
+```
+
+**Key observations:**
+
+- Purpose is 3 sentences, clear and specific
+- Only 5 key components listed (not exhaustive)
+- Uses package references ("Validators in `validation/` package")
+- Testing section shows fixture usage with real examples
+- Critical Patterns focus on what will break if not followed
+- No Dependencies, Local Development, or Related Documentation sections (not needed)
+- Total: 54 lines
+
+---
+
+## Example 2: Handler Module (user-handler)
+
+**Module Type:** Handler layer
+**Characteristics:** Handlers, validators, repository, storage models
+**Length:** ~60-70 lines
+
+```markdown
+# user-handler
+
+## Purpose
+
+This module contains the Mission domain handlers, validators, and repository implementations. It provides the business
+logic layer for mission operations, including CQRS command/query handlers, comprehensive validation, and both InMemory
+and MongoDB repository implementations for persistence.
+
+## Key Components
+
+- `MissionHandlerActive` - Handles write operations (insert, update, upsert, delete)
+- `MissionHandlerPassive` - Handles read operations (query, read by ID, read by alias)
+- `MissionRepository` - Repository interface with InMemory and MongoDB implementations
+- `MissionValidator` - Composite validator with 30+ business rules
+- Storage models in `storage/v1/model/` for persistence layer
+
+## Testing
+
+Test fixtures are primarily in `user-model` module's testFixtures.
+
+For repository testing:
+
+- Use `InMemoryMissionRepository` for unit tests
+- Use `MongoMissionRepository` with test container for integration tests
+
+## Critical Patterns
+
+1. **Use validator factories** - Don't instantiate validators directly, use `MissionValidatorFactory`
+2. **Repository creation** - Use static factory methods: `inMemory()`, `mongo(config)`, `create(config)`
+3. **Storage model versioning** - V1 models for backward compatibility, create V2 for breaking changes
+4. **Query conversion** - Use `MissionQueryConverter` to convert domain queries to storage queries
+5. **Validation is comprehensive** - Mission validation runs 30+ validators, can be slow for complex missions
+```
+
+**Key observations:**
+
+- Purpose clearly describes the handler layer responsibilities
+- Only 5 key components listed (handlers, repository, validator, storage models)
+- Uses package reference for storage models ("Storage models in `storage/v1/model/`")
+- Testing section mentions where fixtures are located and testing approach
+- Critical Patterns focus on how to use the module correctly
+- No exhaustive list of validators (just mentions "30+ business rules")
+- Concise and focused
+
+---
+
+## Example 3: ID Module Pattern
+
+**Module Type:** ID layer
+**Characteristics:** Only ID types, no dependencies
+**Length:** ~20-30 lines
+
+```markdown
+# user-id
+
+## Purpose
+
+This module contains ID types for the Mission domain, including MissionId, OrderId, UnitOrderId, MissionUnitId, and
+MissionUnitGroupId.
+
+## Key Components
+
+- `MissionId` - Mission aggregate identifier
+- `OrderId` - Order entity identifier
+- `UnitOrderId` - Unit order entity identifier
+- `MissionUnitId` - Mission unit identifier
+- `MissionUnitGroupId` - Mission unit group identifier
+
+## Critical Patterns
+
+1. **Use factory methods** - Always use `OrderId.of(value)`, never construct directly
+2. **Immutable** - All ID types are immutable value objects
+```
+
+**Key observations:**
+
+- Very simple, minimal structure
+- Lists the ID types (these are the key components)
+- Only 2 critical patterns (factory methods, immutability)
+- No Testing section (ID modules rarely have fixtures)
+- Total: ~25 lines

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

@@ -0,0 +1,123 @@
+---
+name: generate-readme
+description: Generates concise README.md files for monorepo modules by analyzing module structure, dependencies, key components, and testing patterns. Use when creating module documentation, documenting architecture, updating READMEs, or when user asks to generate/create README for a module.
+allowed-tools: Read, Glob, Grep, Write
+---
+
+# Generate Module README
+
+## Overview
+
+Analyzes a module's structure, dependencies, build configuration, and code patterns to generate concise, focused
+README.md files following the standardized template.
+
+READMEs should be **top-level overviews only** - not exhaustive documentation. Focus on:
+
+- Module purpose (1-3 sentences)
+- 3-5 key components only
+- Critical patterns that developers must know
+- Testing approach
+
+## Instructions
+
+When generating a README, follow these steps:
+
+### 1. Identify Module Information
+
+- **Module path**: Determine the full path to the module
+- **Module name**: Extract from path (e.g., `user-service`, `auth-middleware`)
+- **Module type**: Determine layer/purpose (models, services, controllers, routes, middleware, utils, etc.)
+- **Domain**: Extract domain/feature name (e.g., `user` from `user-service`)
+
+### 2. Analyze Module Structure
+
+Use `Glob` or `Read` to understand:
+
+- Key source files (detect from project structure: `src/`, `lib/`, `app/`, etc.)
+- Test files (`.test.ts`, `.spec.ts`, `_test.go`, `test_*.py`, etc.)
+- Build/config files (`package.json`, `Cargo.toml`, `go.mod`, `setup.py`, etc.)
+
+### 3. Identify Key Components (3-5 only)
+
+**DO NOT list every file.** Only identify the most important components:
+
+For **model/entity** modules:
+
+- Main data models or entities
+- Schema definitions
+- Validation logic
+
+For **service/business logic** modules:
+
+- Core service classes or functions
+- Repository/data access interfaces
+- Key business logic components
+
+For **API/route** modules:
+
+- Main route handlers or controllers
+- Request/response types
+- Middleware components
+
+For **utility** modules:
+
+- Main utility functions or helpers
+- Configuration handlers
+
+### 4. Document Testing Approach
+
+Check for:
+
+- Test files colocated with source or in separate test directory
+- Test fixtures or factories
+- Key test patterns (unit tests, integration tests)
+
+### 5. Identify Critical Patterns
+
+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/TESTING.md` for test patterns and conventions
+- Fall back to CLAUDE.md if `.5/` documentation not present
+- Check module-specific documentation
+
+Use these patterns to identify what's critical for the module README.
+
+### 6. Generate README
+
+Use the template from `TEMPLATE.md` to generate the README.
+
+**Critical guidelines:**
+
+- Keep Purpose to 1-3 sentences
+- List only 3-5 Key Components (never exhaustive lists)
+- Use package references instead of listing many files (e.g., "Validators in `validation/` package")
+- Focus Critical Patterns on what developers must know to avoid breaking things
+- Omit sections if not relevant (e.g., no Testing section if module has no fixtures)
+
+### 7. Write README
+
+Use the `Write` tool to create `README.md` in the module's root directory.
+
+## What to Provide
+
+When a user asks to generate a README, they should provide:
+
+- The module name or path (e.g., "user-service" or "/path/to/services/user-service")
+
+If not provided, ask for clarification.
+
+## Examples
+
+See [EXAMPLES.md](EXAMPLES.md) for complete examples of generated READMEs for different module types.
+
+## Template Structure
+
+See [TEMPLATE.md](TEMPLATE.md) for the standard README template structure.
+
+## Important Notes
+
+1. **Conciseness is key**: READMEs should be under 100 lines for most modules
+2. **Top-level overview only**: Don't document every class or method
+3. **Focus on "must know"**: What will break if developer doesn't know it?