5-phase-workflow 2.0.4 → 2.0.5

package/bin/install.js

@@ -354,7 +354,6 @@ const LEGACY_REMOVED_FILES = [
   'agents/step-verifier.md',
   'templates/STACK.md',
   'templates/STRUCTURE.md',
-  'templates/CONVENTIONS.md',
   'templates/INTEGRATIONS.md',
   'commands/5/plan-feature.md',
   'commands/5/plan-implementation.md',
@@ -422,6 +421,7 @@ function getWorkflowManagedFiles() {
       'AGENTS.md',
       'ARCHITECTURE.md',
       'CONCERNS.md',
+      'CONVENTIONS.md',
       'TESTING.md',
       // Workflow output templates
       'workflow/PLAN.md',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "5-phase-workflow",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "A dev-workflow for Claude Code and Codex",
   "bin": {
     "foifi": "bin/install.js"

package/src/agents/step-executor-agent.md

@@ -19,7 +19,9 @@ You follow the plan, state entry, and existing codebase patterns. You do not wid
 6. Run every verify command assigned to your component. If none is assigned, verify touched files exist and run the narrowest relevant test/build command you can infer.
 7. Fix local mechanical issues you caused. Stop for architectural changes, auth gates, missing external services, or unclear product decisions.
 
-## Output
+## Simplicity
+
+Write the minimum that satisfies the component. Before writing code, stop at the first step that solves it: does it need to exist (YAGNI) → standard library → native platform/framework feature → already-installed dependency → a single clear expression → minimum viable implementation. Add no new dependency for this. Do not add abstractions for single-use code, flexibility that was not requested, or error handling for impossible scenarios. Follow `Simplicity First` in the project `AGENTS.md`. This sharpens "smallest coherent change" — it never widens scope.
 
 End with exactly:
 

package/src/commands/5/configure.md

@@ -262,6 +262,12 @@ If no patterns/commands detected:
     1. "Yes, add to .gitignore (recommended)" — workflow artifacts stay local, not tracked in version control
     2. "No, track in git" — useful if you want to share specs and plans with your team
 
+**2n. Code Conventions:**
+- "Generate `.5/CONVENTIONS.md` with coding conventions for this project? It will include a default set of strict rules (typing, code structure, naming, error handling, testing, and documentation standards) plus project-specific conventions derived from your codebase."
+  - Options:
+    1. "Yes (recommended)" → `conventions.generate: true`
+    2. "Skip" → `conventions.generate: false`
+
 ### Step 2.5: Write config.json
 
 Using the values gathered from Steps 1 and 2, write `.5/config.json` directly.
@@ -274,7 +280,7 @@ Using the values gathered from Steps 1 and 2, write `.5/config.json` directly.
 mkdir -p .5
 ```
 
-**Schema:** Read `.claude/references/configure-tables.md` section "Config Schema" for the full JSON structure. Fill all values from user responses (including `rules.generate` from step 2k2). Write with pretty-printed JSON. Read back to verify correctness.
+**Schema:** Read `.claude/references/configure-tables.md` section "Config Schema" for the full JSON structure. Fill all values from user responses (including `rules.generate` from step 2k2 and `conventions.generate` from step 2n). Write with pretty-printed JSON. Read back to verify correctness.
 
 **Update `.5/version.json` with configure timestamp:**
 
@@ -350,6 +356,7 @@ Generates AGENTS.md, CLAUDE.md shim, a rebuildable codebase index, and project-s
 - [ ] `.5/ARCHITECTURE.md` exists when architecture knowledge was found.
 - [ ] `.5/TESTING.md` exists when test knowledge was found.
 - [ ] `.5/CONCERNS.md` exists only if concerns were found.
+- [ ] `.5/CONVENTIONS.md` exists when `conventions.generate` is true.
 - [ ] `.5/index/rebuild-index.sh` exists and rebuilds the index.
 - [ ] `.5/index/README.md` documents generated index files.
 - [ ] `AGENTS.md` references created `.5/` files and the index rebuild rule.
@@ -388,6 +395,7 @@ Analyze the codebase and generate focused documentation capturing only non-deriv
 - `.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**)
+- `.5/CONVENTIONS.md` - Default strict coding conventions plus project-specific conventions derived from codebase analysis (**only when `conventions.generate` is true**)
 
 **Create a rebuildable codebase index in `.5/index/`:**
 - Generate a repository-local script at `.5/index/rebuild-index.sh`

package/src/commands/5/plan.md

@@ -122,6 +122,8 @@ Discuss naturally until you can articulate:
 
 Ask only useful questions. Prefer proposing a concrete understanding and letting the user correct it.
 
+Apply a necessity gate to every component before it enters the plan. For each one, ask "does this need to exist?" and prefer the simplest approach that meets the acceptance criteria: reuse the standard library, a native platform/framework feature, or an already-installed dependency before adding anything new. Push speculative or "might need later" work to `[DEFERRED]`. Do not plan abstractions, flexibility, or configurability that no acceptance criterion requires.
+
 ## Step 5: Write `plan.md`
 
 Determine a short kebab-case feature folder name. If a ticket ID is known, use `{ticket-id}-{feature-name}`. Sanitize folder names to alphanumeric, dash, and underscore only.
@@ -153,6 +155,7 @@ Verify:
 - Acceptance criteria are checkboxes.
 - Decisions are labeled `[DECIDED]`, `[FLEXIBLE]`, or `[DEFERRED]`.
 - Every component traces to scope or acceptance criteria.
+- No component adds abstraction, flexibility, or configurability beyond what an acceptance criterion requires.
 - No implementation code or pseudo-code is present.
 
 Output exactly:

package/src/commands/5/reconfigure.md

@@ -116,7 +116,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 `.5/ARCHITECTURE.md`, `.5/TESTING.md`, `.5/CONCERNS.md` (conditional), `.5/index/rebuild-index.sh`, `.5/index/*.md`, and `AGENTS.md`
+1. **Documentation files that will be rewritten** — list `.5/ARCHITECTURE.md`, `.5/TESTING.md`, `.5/CONCERNS.md` (conditional), `.5/CONVENTIONS.md` (when `conventions.generate` is true), `.5/index/rebuild-index.sh`, `.5/index/*.md`, and `AGENTS.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?"
@@ -138,7 +138,7 @@ Write `.5/reconfigure-manifest.json` with the compact decisions needed by refres
 ```json
 {
   "mode": "refresh",
-  "docs": ["ARCHITECTURE.md", "TESTING.md", "CONCERNS.md", "index", "AGENTS.md"],
+  "docs": ["ARCHITECTURE.md", "TESTING.md", "CONCERNS.md", "CONVENTIONS.md", "index", "AGENTS.md"],
   "skills": {
     "refresh": ["skill names"],
     "create": ["new skill names"],
@@ -185,7 +185,7 @@ rm -f .5/.reconfig-reminder .5/.migration-v2
 ### Step 9: Report
 
 Show the user a summary:
-- List of documentation files updated
+- List of documentation files updated (including `.5/CONVENTIONS.md` when applicable)
 - Mention whether the codebase index script and index files were regenerated
 - List of skills refreshed
 - List of new skills created (if any)

package/src/commands/5/review.md

@@ -51,7 +51,8 @@ Process:
 4. For medium-risk files, read targeted symbols or nearby changed sections plus direct imports only when needed.
 5. For low-risk mechanical/docs/config changes, review the diff without reading full files unless something looks inconsistent.
 6. Review for bugs, security, performance, code quality, API design, and missing tests.
-7. Categorize findings as Fixable, Questions, or Manual.
+7. Review for over-engineering: unnecessary abstractions, single-use indirection, unused flexibility or configurability, speculative generality, and reinventing standard-library or existing-dependency behavior. Report clear cases as Fixable and judgment calls as Questions.
+8. Categorize findings as Fixable, Questions, or Manual.
 
 Output:
 Status: success | failed

package/src/references/configure-tables.md

@@ -112,6 +112,9 @@ For each command found: record exact syntax, note variants (e.g., `test:unit`, `
   },
   "rules": {
     "generate": true
+  },
+  "conventions": {
+    "generate": true
   }
 }
 ```

package/src/skills/configure-docs-index/SKILL.md

@@ -71,6 +71,14 @@ Perform focused analysis to gather data for documentation templates. Only captur
 - 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
 
+**Conventions Analysis** (for CONVENTIONS.md — when `conventions.generate` is true in config.json):
+- Identify the primary language(s) and runtime (TypeScript, Java, Python, Go, etc.) for the summary line
+- **Typing patterns:** Check tsconfig.json for `strict` mode (TypeScript); check mypy.ini or pyproject.toml `[tool.mypy]` for strict settings (Python); scan source files for `any` type usage count, non-null assertion (`!`) patterns, and missing return types
+- **Error handling patterns:** Scan for try/catch structures, custom error classes/types, and patterns of silent catches (empty catch blocks)
+- **Test assertion patterns:** Read 3-5 test files to identify assertion library (Jest `expect`, Chai, JUnit `assertEquals`, etc.), mocking approach, and whether factories/builders exist
+- **Naming patterns:** Observe the dominant casing and naming conventions already established in the codebase
+- **Code structure patterns:** Note average file lengths and any consistent structural patterns across modules
+
 ### A2. Fill Templates
 
 For each template in `.claude/templates/`:
@@ -86,6 +94,7 @@ ARCHITECTURE.md:
 - `{Pattern name}` → "Layered Architecture" or "MVC" or "Modular Monolith"
 - `{Layer}` → "Controllers", "Services", "Repositories"
 - `{path}` → "src/controllers/", "src/services/"
+- `{skill links}` → slash-command links to project-specific skills installed in `.claude/skills/` that correspond to this layer (e.g., `/controller`, `/service`). Check which `create-*` skills exist for this layer's pattern. If none exist, use "—".
 
 TESTING.md:
 - Describe actual patterns observed, not framework names/versions (those are in config files)
@@ -102,6 +111,29 @@ Write filled templates to `.5/` folder:
    - `.5/ARCHITECTURE.md` — always created
    - `.5/TESTING.md` — always created
    - `.5/CONCERNS.md` — **only if concerns were found** (skip if all sections empty)
+   - `.5/CONVENTIONS.md` — **only when `conventions.generate` is true in config.json** (see A3.1)
+
+### A3.1. Generate CONVENTIONS.md
+
+Skip this section entirely if `conventions.generate` is `false` in `.5/config.json`.
+
+Read `.claude/templates/CONVENTIONS.md` as the source template.
+
+**Placeholder mapping:**
+
+- `{PROJECT_CONVENTIONS_SUMMARY}` → 1 sentence naming the primary language/runtime and any detected strict-mode tooling (e.g., "TypeScript project with `strict: true` in tsconfig." or "Python 3.11 service with mypy strict mode enabled."). Remove the placeholder if nothing useful can be stated.
+- `{PROJECT_TYPING}` → Project-specific findings from Conventions Analysis: detected tsconfig settings, any `any` usage count, non-null assertion patterns, absence of return types. Frame as imperative directives ("Enable `strict: true` in tsconfig — currently disabled." or "49 usages of `any` detected; prioritize removal in new code."). Remove placeholder if nothing project-specific to add.
+- `{PROJECT_STRUCTURE}` → Observed structural patterns or deviations from defaults (e.g., "Files in `src/controllers/` average 380 lines — respect the 300-line default; split controllers that exceed it."). Remove placeholder if no notable findings.
+- `{PROJECT_NAMING}` → Casing or naming patterns specific to this codebase beyond the defaults (e.g., "This project uses `kebab-case` for file names and `PascalCase` for classes — match existing files."). Remove placeholder if defaults already cover it.
+- `{PROJECT_ERROR_HANDLING}` → Detected error-handling patterns or gaps (e.g., "Custom `AppError` class in `src/errors/` — use it for all domain errors." or "3 empty catch blocks found in `src/services/` — always log or rethrow."). Remove placeholder if no notable findings.
+- `{PROJECT_TESTING}` → Project-specific testing directives beyond the defaults: assertion library in use, factory/builder location, any detected weak assertions or disabled tests (e.g., "Use `src/test/factories/` helpers for test data — do not inline objects." or "12 uses of `toBeDefined()` as sole assertion detected — always assert the actual value."). Remove placeholder if defaults already cover it.
+- `{PROJECT_COMMENTS}` → Any documentation patterns or gaps observed (e.g., "Public controllers lack JSDoc — add docblocks to all new public methods."). Remove placeholder if defaults already cover it.
+
+**Rules for filling placeholders:**
+- Write project-specific sections as imperative directives, not observations.
+- Remove (do not leave) any placeholder whose section has nothing project-specific to add.
+- Do not duplicate the default convention text — project sections supplement, not restate, the defaults.
+- Keep each project-specific addition under 5 bullet points.
 
 ### A3.5. Generate Codebase Index Script and Index Files
 
@@ -147,8 +179,9 @@ Use `.claude/templates/AGENTS.md` as the source template.
 Placeholder mapping:
 - `{PROJECT_OVERVIEW}` → 1-2 sentences from README/package.json
 - `{BUILD_RUN_COMMANDS}` → build, test, and other detected commands
-- `{PROJECT_DOCUMENTATION_LINKS}` → links to whichever `.5/` files were created (only list files that exist)
+- `{PROJECT_DOCUMENTATION_LINKS}` → links to whichever `.5/` files were created (only list files that exist — includes CONVENTIONS.md when generated)
 - `{CODEBASE_INDEX_LINKS}` → links to `.5/index/README.md`, generated index files, and `.5/index/rebuild-index.sh`
+- `{CONVENTIONS_REFERENCE}` → when `.5/CONVENTIONS.md` was generated: `"Read \`.5/CONVENTIONS.md\` before writing any code. It defines the full convention set for this project: typing rules, code structure limits, naming, error handling, and testing standards."` — when not generated: remove the placeholder entirely
 - `{CUSTOM_DOCUMENTATION}` → preserved user-authored sections under `## Custom Documentation`; remove the placeholder entirely if there is no custom content
 
 Preserve the static template sections exactly as written, including skill usage, commit messages, workflow rules, coding guidelines, simplicity, testing, surgical changes, goal-driven execution, and index freshness.
@@ -189,6 +222,7 @@ Component A (Documentation + Index): SUCCESS - Created documentation files, code
   - .5/ARCHITECTURE.md (Pattern: Layered, 4 layers identified)
   - .5/TESTING.md (mocking patterns, gotchas documented)
   - .5/CONCERNS.md (3 TODO items, 1 security note) [or "skipped — no concerns found"]
+  - .5/CONVENTIONS.md (defaults + project-specific typing/testing findings) [or "skipped — conventions.generate is false"]
   - .5/index/rebuild-index.sh (generated index rebuild script)
   - .5/index/*.md (focused codebase index files)
   - AGENTS.md (updated with references)

package/src/templates/AGENTS.md

@@ -24,6 +24,8 @@ Each phase produces a specific artifact - do not create artifacts belonging to o
 
 ## Coding Guidelines
 
+{CONVENTIONS_REFERENCE}
+
 1. Prefer explicit types or contracts for public APIs, data transfer shapes, service methods, hooks, and async return values where the language supports them.
 2. Keep comments and docs concise; document constraints and non-obvious behavior, not the obvious.
 3. Keep files focused and bounded; split broad controllers, services, hooks, and components early.
@@ -33,6 +35,19 @@ Each phase produces a specific artifact - do not create artifacts belonging to o
 
 ## Simplicity First
 
+Before writing code, walk this decision hierarchy and stop at the first step that solves the problem:
+
+1. **Does this need to exist at all?** If the requirement is speculative, don't build it (YAGNI).
+2. Does the **language or standard library** already solve it?
+3. Is there a **native platform or framework** feature for it?
+4. Does an **already-installed dependency** cover it? Don't add a new dependency for this.
+5. Can it be a **single, clear expression** instead of a new abstraction?
+6. Only then: write the **minimum viable implementation**.
+
+Non-negotiable regardless of the above: security, data integrity, correctness, and accessibility.
+
+Then apply these rules:
+
 - No features beyond what was asked.
 - No abstractions for single-use code.
 - No flexibility or configurability that was not requested.

package/src/templates/ARCHITECTURE.md

@@ -8,9 +8,9 @@
 
 ## Layers & Data Flow
 
-| Layer | Location | Depends On | Notes |
-|-------|----------|------------|-------|
-| {Layer} | `{path}` | {Dependencies} | {Key responsibility or constraint} |
+| Layer | Location | Depends On | Notes | Skills |
+|-------|----------|------------|-------|--------|
+| {Layer} | `{path}` | {Dependencies} | {Key responsibility or constraint} | {skill links} |
 
 ## Key Abstractions
 

package/src/templates/CONVENTIONS.md

@@ -0,0 +1,74 @@
+# 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.*