5-phase-workflow 3.0.0 → 3.1.0

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

@@ -1,141 +0,0 @@
-# Module README Template
-
-Use this template structure for all module READMEs. Keep them concise and focused.
-
----
-
-# [Module Name]
-
-## Purpose
-
-[1-3 sentences describing what this module does and its role in the system]
-
-Example: "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."
-
-## Key Components
-
-[List only the 3-5 most important components - not exhaustive]
-
-- `EntityName` - Brief description of key entity
-- `EntityFactory` - Key factory operations (create, addX, updateY)
-- `EntityRepository` - Repository interface with implementations
-- Package references for groups: "Validators in `validation/` package"
-
-**Guidelines:**
-
-- **DO NOT** list every file
-- **DO** use package references for groups of related files
-- **DO** focus on what developers will use most frequently
-- **DO** mention main interfaces/abstractions, not every implementation
-
-## Testing
-
-[Brief description of test fixtures and key testing patterns]
-
-**Only include this section if:**
-
-- Module has test fixtures in `src/testFixtures/`
-- Module has a separate `-testing` sibling
-- Testing approach is non-standard or important to document
-
-Example:
-
-```java
-// Simple example
-var entity = entityTestFixture.create();
-
-// Customized example
-var entity = entityTestFixture.createBuilder()
-    .withProperty(value)
-    .build();
-```
-
----
-
-## Optional Sections
-
-Include these sections only if they add significant value:
-
-### Critical Patterns
-
-[List only 3-5 most important patterns specific to this module]
-
-Focus on patterns that:
-
-- Will break things if not followed
-- Are non-obvious
-- Are critical to understanding the module
-
-Examples:
-
-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
-
-**DO NOT include:**
-
-- General patterns covered in AGENTS.md
-- Obvious patterns like "use builders for construction"
-- Implementation details
-
-### Dependencies
-
-**Only include if:**
-
-- Dependencies are non-obvious
-- There are critical ordering or version requirements
-- External systems are involved
-
-**Depends on:** [Brief list of key dependencies]
-
-**Used by:** [Brief list of main consumers]
-
-### Related Documentation
-
-**Don't include:**
-
-- Links to AGENTS.md sections relevant to this module
-- Don't repeat things and patterns already documented in AGENTS.md
-
-**Include for:**
-
-- Parent or sibling module READMEs
-- External documentation
-- [Related module READMEs](../path/README.md)
-
----
-
-## Anti-Patterns in READMEs
-
-**DO NOT:**
-
-1. List every validator, query, or handler class individually
-2. Document implementation details
-3. Copy content from AGENTS.md
-4. Include exhaustive method signatures
-5. Create walls of text
-6. Document every package
-7. Include obvious information
-
-**DO:**
-
-1. Focus on top-level overview
-2. List 3-5 key components only
-3. Reference AGENTS.md for patterns
-4. Keep it under 100 lines
-5. Use examples sparingly
-6. Use package references for groups
-7. Document only critical information
-
----
-
-## Example README Lengths
-
-- **ID module**: 10-30 lines (very simple)
-- **Model module**: 20-80 lines
-- **Handler module**: 20-80 lines
-- **Service module**: 20-80 lines
-- **Testing module**: 20-60 lines
-
-If your README exceeds 150 lines, it's too detailed.

package/src/skills/use-index/SKILL.md

@@ -1,49 +0,0 @@
----
-name: use-index
-description: Navigate the .5/index/ codebase index to quickly identify target files and understand project structure. Use before running broad Glob/Grep scans when you need to find where a feature lives, where new code should go, which routes exist, or what the data model looks like.
-allowed-tools: Read, Bash
-user-invocable: false
----
-
-# Use Index
-
-Use `.5/index/` to orient in the codebase quickly before resorting to broad file scans.
-
-## Step 1: Check existence
-
-```bash
-ls .5/index/ 2>/dev/null
-```
-
-If the directory is missing or empty, inform the user they can run `/5:reconfigure` to generate it, then fall back to Glob/Grep.
-
-## Step 2: Read the manifest
-
-Read `.5/index/README.md`. It lists every generated index file, its purpose, and the generation timestamp.
-
-## Step 3: Check freshness
-
-Look for the `Generated:` timestamp in README.md.
-
-- **Fresh (≤ 1 day):** proceed with the index.
-- **Stale (> 1 day):** run `.5/index/rebuild-index.sh` to rebuild it, then proceed with the refreshed index.
-
-## Step 4: Read only the relevant file(s)
-
-Pick the file that matches the task. Skip unrelated ones.
-
-| Task | File |
-|------|------|
-| Where does new code go / what modules exist? | `modules.md` |
-| API surface, HTTP routes, or handlers | `routes.md` |
-| Data models, schemas, or migrations | `models.md` |
-| Shared helpers, utilities, or exported functions | `libraries.md` |
-| Build, run, test, or dev-workflow commands | `commands.md` |
-
-## Step 5: Interpret entries
-
-Each file has compact entries — path plus a short descriptor (HTTP method, exported name, key field, etc.). Use them to identify target files directly. Do not read the full index file if a handful of entries answer the question.
-
-## Step 6: Fall back gracefully
-
-If a file is too sparse or an area is missing from the index, note the gap and fall back to a targeted Grep/Glob for that area only. Do not re-scan sections already covered by a fresh index entry.

package/src/templates/ARCHITECTURE.md

@@ -1,33 +0,0 @@
-# Architecture
-
-## Pattern
-
-**Overall:** {Pattern name — e.g., Layered, MVC, Modular Monolith}
-
-{1-2 sentences explaining the architectural approach and key design decisions}
-
-## Layers & Data Flow
-
-| Layer | Location | Depends On | Notes | Skills |
-|-------|----------|------------|-------|--------|
-| {Layer} | `{path}` | {Dependencies} | {Key responsibility or constraint} | {skill links} |
-
-## Key Abstractions
-
-**{Abstraction Name}:**
-- Purpose: {What it represents}
-- Pattern: {How it's used across the codebase}
-- Examples: `{file paths}`
-
-## Non-Obvious Conventions
-
-{ONLY conventions not enforced by tooling or visible in config files. Skip anything in .eslintrc, .prettierrc, tsconfig, etc.}
-
-- {e.g., "All services must extend BaseService for lifecycle hooks"}
-- {e.g., "Barrel exports required in each module directory"}
-
-## Where to Add New Code
-
-- New feature: `{path}`
-- New tests: `{path}`
-- Shared utilities: `{path}`

package/src/templates/CONCERNS.md

@@ -1,33 +0,0 @@
-# Concerns
-
-## Tech Debt
-
-**{Area/Component}:**
-- Issue: {What's the shortcut/workaround}
-- Files: `{file paths}`
-- Impact: {What breaks or degrades}
-
-## Known Issues
-
-**{Issue description}:**
-- Symptoms: {What happens}
-- Files: `{file paths}`
-- Trigger/Workaround: {How to reproduce, how to avoid}
-
-## Security Notes
-
-**{Area}:**
-- Risk: {What could go wrong}
-- Current mitigation: {What's in place}
-
-## Integration Notes
-
-**{Service/System}:**
-- {Non-obvious details: auth flows, required env vars, webhook contracts, gotchas with external services}
-
-## Performance Notes
-
-**{Slow operation or scaling limit}:**
-- Problem: {What's slow or where it breaks}
-- Files: `{file paths}`
-- Improvement path: {How to address}

package/src/templates/CONVENTIONS.md

@@ -1,74 +0,0 @@
-# Code Conventions
-
-{PROJECT_CONVENTIONS_SUMMARY}
-
-## Typing
-
-- Never use implicit `any` types; if unavoidable, add a `// reason:` comment explaining why.
-- Enable strict null checks: treat `null` and `undefined` as distinct types.
-- Avoid non-null assertions (`!`) without an explanatory comment.
-- Prefer explicit return types on all public functions and methods.
-- Use typed/domain types for IDs, money, dates, and other value objects; avoid raw primitives.
-
-{PROJECT_TYPING}
-
-## Code Structure
-
-- Maximum function or method body: 40 lines of logic.
-- Maximum file length: 300 lines (excluding generated or vendor code).
-- One primary responsibility per file, class, or module — split when in doubt.
-- No more than three levels of nesting; use early returns to flatten control flow.
-- Extract helpers when logic mixes orchestration, IO, parsing, and mapping in one place.
-
-{PROJECT_STRUCTURE}
-
-## Naming
-
-- Names must express intent; avoid abbreviations (exceptions: `i`, `j`, `err`, `ctx`, `req`, `res`).
-- No magic numbers or strings: extract to named constants with descriptive names.
-- Booleans: prefix with `is`, `has`, `can`, `should`, or `needs`.
-- Collections and arrays: plural noun names (`users`, `errors`, `pendingItems`).
-- Functions and methods: verb phrases that describe the action (`fetchUser`, `validateEmail`, `parseResponse`).
-
-{PROJECT_NAMING}
-
-## Error Handling
-
-- Never silently swallow exceptions or errors — always log, rethrow, or convert to a typed result.
-- Distinguish recoverable errors from unrecoverable ones; do not use exceptions for control flow.
-- All async code must handle error paths: catch rejected promises and wrap `async/await` in `try/catch`.
-- Use typed/structured errors with context, not raw strings.
-
-{PROJECT_ERROR_HANDLING}
-
-## Testing
-
-- Follow AAA structure in each test: **Arrange** (set up state), **Act** (call the subject), **Assert** (verify the outcome).
-- One behavior per test — a single test function must cover exactly one scenario.
-- Test names describe the behavior being tested, not the method: `"returns 404 when user not found"`, not `"test getUserById"`.
-- Assert on meaningful, observable outcomes. Forbidden:
-  - `expect(result).toBeDefined()` as the only assertion
-  - `expect(true).toBe(true)` or any trivially-passing assertion
-  - Empty or body-less tests
-- Mock only at system boundaries: external HTTP, databases, filesystem, and clocks.
-- Never mock internal modules or pure functions — test them directly.
-- Cover all paths: happy path, known error cases, boundary values, and null/empty inputs.
-- No disabled tests (`skip`, `xtest`, `xit`, `@Ignore`) without a linked issue comment.
-- New code must reach ≥ 80% branch coverage; bug fixes must include a regression test.
-- Use factories or builders for test data; avoid inline hardcoded objects duplicated across tests.
-
-{PROJECT_TESTING}
-
-## Comments and Documentation
-
-- Comment the **why**, not the what; well-named code should be self-documenting.
-- Forbidden: comments that restate the code (`// increment counter`, `// call save()`).
-- Document: non-obvious invariants, workarounds, performance trade-offs, and cross-system constraints.
-- All public APIs (functions, classes, interfaces, endpoints) require a docstring or docblock.
-- Never leave commented-out code; use version control history instead.
-
-{PROJECT_COMMENTS}
-
----
-
-*Project-specific conventions above were derived from codebase analysis and supplement the defaults.*

package/src/templates/TESTING.md

@@ -1,24 +0,0 @@
-# Testing Patterns
-
-## Organization
-
-{Co-located with source or separate directory? Naming pattern for test files?}
-
-## Patterns
-
-{Project-specific test structure — describe how tests are organized within a file, setup/teardown conventions}
-
-## Mocking
-
-**Approach:**
-- {Mocking framework/tool used}
-
-**What to mock:**
-- {Guidelines — e.g., external APIs, database calls}
-
-**What NOT to mock:**
-- {Guidelines — e.g., pure business logic, utility functions}
-
-## Gotchas
-
-{Things that trip people up: setup/teardown quirks, env requirements, flaky areas, test-specific config}

package/src/templates/workflow/FIX-PLAN.md

@@ -1,55 +0,0 @@
-# Fix Plan: {TICKET-ID}
-
-**Feature:** {feature-name}
-**Generated:** {timestamp}
-**Verification Status:** PARTIAL | FAILED
-
----
-
-## Infrastructure Fixes
-
-{If no infrastructure issues: "No infrastructure issues found."}
-
-| # | File | Issue | Fix | Complexity |
-|---|------|-------|-----|------------|
-| 1 | {path} | {description} | {what to do} | simple / moderate / complex |
-
-## Feature Gap Fixes
-
-{If no feature gaps or Layer 2 was skipped: "No feature gaps found." or "Skipped — no plan.md available."}
-
-| # | File | Issue | Fix | Complexity |
-|---|------|-------|-----|------------|
-| 1 | {path} | {criterion or requirement not met} | {what to change} | simple / moderate / complex |
-
-## Quality Fixes
-
-{If no quality issues: "No quality issues found."}
-
-| # | File | Issue | Fix | Complexity |
-|---|------|-------|-----|------------|
-| 1 | {test-file-path} | No test file for {component} | Create test file | simple / moderate |
-
----
-
-## Summary
-
-| Category | Count |
-|----------|-------|
-| Infrastructure | {N} |
-| Feature Gaps | {N} |
-| Quality | {N} |
-| **Total** | **{N}** |
-
----
-
-## Results
-
-{Populated after fixes are applied}
-
-| # | File | Fix | Status |
-|---|------|----|--------|
-| 1 | {path} | {description} | APPLIED / FAILED |
-
-**Build after fixes:** {status}
-**Tests after fixes:** {status}

package/src/templates/workflow/PLAN-COMPACT.md

@@ -1,42 +0,0 @@
----
-ticket: {TICKET-ID}
-feature: {feature-name}
-created: {ISO-timestamp}
-planFormat: compact
----
-
-<!-- PLAN RULES:
-- Use only for low-risk changes with 1-2 components.
-- Write requirements and implementation intent, not code.
-- Keep the Component Checklist human-readable. Do not add step/model/pattern/verify columns.
-- Decisions must be labeled [DECIDED], [FLEXIBLE], or [DEFERRED].
--->
-
-# Plan: {TICKET-ID} - {Title}
-
-## Overview
-
-{Short narrative describing the problem and desired outcome.}
-
-## Scope
-
-- In: {included work}
-- Out: {excluded work}
-
-## Acceptance Criteria
-
-- [ ] {Observable success criterion}
-
-## Decisions
-
-- [DECIDED] {Decision and rationale}
-
-## Existing Patterns to Follow
-
-- `{path}` - {what pattern this provides}
-
-## Component Checklist
-
-| Component | Action | Target Path | Intent |
-|-----------|--------|-------------|--------|
-| {component-name} | modify | `{path}` | {one-sentence intent} |

package/src/templates/workflow/PLAN.md

@@ -1,76 +0,0 @@
----
-ticket: {TICKET-ID}
-feature: {feature-name}
-created: {ISO-timestamp}
----
-
-<!-- PLAN RULES:
-- One planning artifact only: this file.
-- Write requirements and implementation intent, not code.
-- Keep the Component Checklist human-readable. Do not add step/model/pattern/verify columns; step-orchestrator-agent derives those into state.json.
-- Existing Patterns to Follow should name high-value files and conventions so the orchestrator can wire executor prompts cheaply.
-- Decisions must be labeled [DECIDED], [FLEXIBLE], or [DEFERRED].
-- Omit optional sections when they would only contain "none", "n/a", or placeholder content.
--->
-
-# Plan: {TICKET-ID} - {Title}
-
-## Overview
-
-{Short narrative describing the problem, desired outcome, and why this change is needed.}
-
-## What Changes
-
-- {Logical behavior or capability that changes}
-- {User-visible or system-visible outcome}
-
-## Existing Patterns to Follow
-
-- `{path}` - {what pattern this provides}
-- `{path}` - {what convention this establishes}
-
-## Constraints
-
-- {Technical, product, compatibility, performance, or rollout constraint}
-
-## Scope
-
-### In
-
-- {Included work}
-
-### Out
-
-- {Explicitly excluded work}
-
-## Acceptance Criteria
-
-- [ ] {Observable success criterion}
-- [ ] {Observable success criterion}
-
-## Decisions
-
-- [DECIDED] {Decision and rationale}
-- [FLEXIBLE] {Area where implementation may choose the best local pattern}
-- [DEFERRED] {Work intentionally not included}
-
-## Module Impact
-
-| Module/Area | Impact |
-|-------------|--------|
-| {module} | {create/modify/delete behavior at a high level} |
-
-## Component Checklist
-
-| Component | Action | Target Path | Intent |
-|-----------|--------|-------------|--------|
-| {component-name} | create | `{path}` | {one-sentence intent} |
-| {component-name} | modify | `{path}` | {one-sentence intent} |
-
-## Technical Notes
-
-- {Important implementation context, invariants, or migration notes}
-
-## Alternatives Considered
-
-- {Alternative}: {why it was not chosen}

package/src/templates/workflow/REVIEW-SUMMARY.md

@@ -1,53 +0,0 @@
-# Code Review Summary
-
-**Reviewed:** {scope}
-**Timestamp:** {ISO-timestamp}
-**User Decisions:** {summary of user choices}
-
-## Summary
-
-- **Total Issues:** {N}
-- **Applied with User Approval:** {N}
-- **User-Resolved Questions:** {N}
-- **Manual Review Needed:** {N}
-- **Skipped by User:** {N}
-- **Deferred by User:** {N}
-
-## Applied Fixes (User Approved)
-
-- `{file-path}:{line}` - {description of fix}
-- `{file-path}:{line}` - {description of fix}
-
-## User-Resolved Questions
-
-- `{file-path}:{line}` - {description} (user answered: {answer})
-
-## Manual Review Needed
-
-- `{file-path}:{line}` - {description}
-
-## Skipped Issues
-
-- `{file-path}:{line}` - User chose not to apply
-
-## Deferred Issues
-
-- `{file-path}:{line}` - User chose to wait
-
-## Files Modified
-
-- {file-path} ({N} fixes applied)
-
-## PR Comment Replies
-
-- **Posted:** {N}
-- **Failed:** {N}
-- **Skipped:** {N} - {reason}
-- **Errors:** {none-or-summary}
-
-## Post-Fix Verification
-
-- **Build:** {passed/failed/skipped} - `{command-or-none}` - {one-line summary}
-- **Tests:** {passed/failed/skipped} - `{command-or-none}` - {one-line summary}
-- **E2E:** {passed/failed/skipped} - `{command-or-none}` - {one-line summary}
-- **Lint:** {passed/failed/skipped} - `{command-or-none}` - {one-line summary}