5-phase-workflow 3.0.0 → 3.1.0

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

@@ -0,0 +1,146 @@
+---
+name: configure-rules
+description: Generates file-scoped `.claude/rules/` from the conventions the codebase actually follows. Used during /5:implement CONFIGURE and /5:reconfigure.
+allowed-tools: Read, Write, Bash, Glob, Grep
+model: sonnet
+user-invocable: false
+---
+
+# Configure Rules Skill
+
+Generates `.claude/rules/*.md`: short directives that load only when Claude works on matching files. Claude explores the code on its own, so rules carry only what exploration gets wrong: conventions that tooling does not enforce and that differ from common defaults.
+
+- **Full mode (default):** used by `/5:implement CONFIGURE`. Runs when `rules.generate` is `true` in `.5/config.json`.
+- **Refresh mode:** used by `/5:reconfigure`. The prompt includes "REFRESH MODE" and points at `.5/reconfigure-manifest.json`.
+
+**On Codex** (this skill runs as part of `$5-configure` or `$5-reconfigure`), write no rule files: Codex reads only `AGENTS.md`. Write the same rules, in the same order, into the foifi block of `AGENTS.md` instead — see [Codex: rules in AGENTS.md](#codex-rules-in-agentsmd).
+
+Rules are **concise directives** (15-40 lines each), not documentation. Rules tell Claude what to do when working with specific file types.
+
+The repository's own standards win over rules. These are the files `.claude/skills/review-style/SKILL.md` step 2 lists, such as `CONTRIBUTING.md`. A rule never restates or contradicts them.
+
+## 1. Determine Which Rules to Generate
+
+Scan the codebase for the file types each rule needs, then pick the rules that apply:
+
+| Rule File | Generate When | What to Analyze |
+|-----------|---------------|-----------------|
+| `code-style.md` | Always (if source files exist) | 2-3 source files: naming, imports, exports, and structure that tooling does not enforce |
+| `testing.md` | Test files detected | 3-5 test files: organization, assertions, mocking, fixtures, setup gotchas |
+| `api-patterns.md` | Controller/route/handler patterns detected | 2-3 handlers: validation, error responses, auth checks |
+| `dependencies.md` | External integrations detected | Clients for external services, env var access, required setup |
+
+**Skip** any rule whose prerequisite patterns were not detected. Do not generate empty or placeholder rule files.
+
+## 2. Extract Directives and Write Rules
+
+For each applicable rule:
+
+1. **Derive `paths:` globs** from detected file locations (e.g., if tests are at `src/**/*.test.ts` and `tests/**/*.spec.ts`, use those patterns)
+2. **Convert analysis observations into imperative directives** — "Use X", "Always Y", "Never Z"
+3. **Keep each file 15-40 lines** — be concise and actionable
+4. **Do not repeat** the general guidance sections from `AGENTS.md`, the style skills, or the repository's own standards
+
+Write files to `.claude/rules/`:
+
+```bash
+mkdir -p .claude/rules
+```
+
+## 3. Rule File Format
+
+Each rule file uses YAML frontmatter with `paths:` for scoping, followed by the marker line `<!-- foifi:generated -->` as the first body line. Rules without `paths:` load unconditionally.
+
+**Example — `testing.md`:**
+
+```markdown
+---
+paths:
+  - "**/*.test.ts"
+  - "**/*.spec.ts"
+---
+<!-- foifi:generated -->
+
+# Testing Conventions
+
+- Use `describe`/`it` blocks with descriptive names
+- Mock external dependencies with jest.mock, never mock internal modules
+- Use factory functions from `tests/factories/` for test data
+- Each test file mirrors its source file path: `src/foo/Bar.ts` → `src/foo/__tests__/Bar.test.ts`
+- Assert one behavior per test
+```
+
+**Example — `code-style.md`:**
+
+```markdown
+---
+paths:
+  - "src/**/*.{ts,tsx}"
+---
+<!-- foifi:generated -->
+
+# Code Style
+
+- Use PascalCase for classes and types, camelCase for functions and variables
+- Import order: external packages → internal modules → relative imports
+- Use absolute imports with `@/` alias
+- Prefer named exports over default exports
+```
+
+**Example — `dependencies.md` (unconditional):**
+
+```markdown
+<!-- foifi:generated -->
+# Dependency Conventions
+
+- Database access through Prisma client only, never raw SQL
+- HTTP requests use axios instance from `src/lib/http.ts`
+- Environment variables accessed via `src/config/env.ts`, never `process.env` directly
+```
+
+## Codex: rules in AGENTS.md
+
+Put one section just before the `<!-- foifi:end -->` line of `AGENTS.md`, replacing an existing one:
+
+```markdown
+<!-- 5-sync:rules-start -->
+## File-Scoped Rules
+
+### testing
+Applies to: `**/*.test.ts`, `**/*.spec.ts`
+
+- Use `describe`/`it` blocks with descriptive names
+<!-- 5-sync:rules-end -->
+```
+
+One `###` subsection per rule, named like the rule file, starting with `Applies to:` and its globs (`Applies to: all files` for an unconditional rule). Change nothing else in `AGENTS.md`. Without a foifi block, stop and report that `configure-agents-md` must run first.
+
+## Refresh Mode
+
+When running in REFRESH MODE:
+- Refresh, create, and remove only the rule files `.5/reconfigure-manifest.json` lists.
+- A rule file counts as workflow-generated only when it contains the `<!-- foifi:generated -->` marker line, or, for files from earlier versions without the marker, when the manifest lists it. Never modify or remove any other rule file.
+- On Codex, rewrite the `File-Scoped Rules` section with the manifest's refreshed and new rules, minus the removed ones.
+
+---
+
+## Output Contract
+
+```
+Component B (Rules): SUCCESS - Generated 3 rule files (code-style, testing, dependencies)
+```
+
+Or:
+
+```
+Component B (Rules): SKIPPED - rules.generate is false in config
+```
+
+## DO NOT
+
+- DO NOT generate rules for file types that do not exist in the project.
+- DO NOT generate empty or placeholder rule files.
+- DO NOT hardcode conventions - always derive them from the actual code.
+- DO NOT repeat the general guidance from `AGENTS.md` in rule files.
+- DO NOT restate or contradict the repository's own standards.
+- DO NOT generate skills. Earlier versions generated pattern and `run-*` skills; leave any that exist untouched.

package/src/skills/documentation-style/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: documentation-style
+description: How to write documents, Javadoc and code comments. Short plain sentences, one idea each. Use when writing or reviewing comments, doc comments or Markdown.
+---
+
+# Communication and Documentation Style
+
+When communicating or documenting anything (a document, JavaDoc, comments in the code, etc.),
+write it as short, plain sentences, without jargon, and one idea per sentence.
+Never chain multiple ideas into a single sentence with semicolons or em-dashes.
+If a comment covers more than one concern (e.g., "why this setup looks odd" vs.
+"what this test actually checks"), split it into separate sentences, or separate
+paragraphs (blank `//` line) if the concerns are distinct enough. A comment should
+read like a short explanation to a colleague, not a dense clause-stacked run-on.
+
+For reference, here's the failure mode it's meant to block, and the fix, so you can sanity-check the wording still points at the right thing:
+
+Bad (what I wrote first):
+// These two are the "projected new missions" the mocked projection returns for this saga run;
+// they must be move participants (i.e. targets of a movedOrder from sourceMissionId) so the
+// reprojector's participant filter keeps them — the hard fail this test exercises is that
+// NEITHER has a corresponding entry in newMissionRequest's OWN movedOrders (which target an
+// unrelated random MissionId), not that they were pruned as non-participants.
+
+Good (the rewrite):
+// These two missions are what the mocked projection returns as the new missions for this run.
+// They must be move participants, so give them entries in the stubbed movedOrders as targets
+// of sourceMissionId. Otherwise the reprojector's participant filter would prune them, and the
+// test would no longer exercise the hard fail it's meant to check.
+//
+// The hard fail itself comes from something else: newMissionRequest's own movedOrders target
+// an unrelated random MissionId, so neither mission has a matching entry there.

package/src/skills/fowler-code-smells/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: fowler-code-smells
+description: Martin Fowler's code smells (Refactoring, ch. 3), each with its fix. Use when writing, refactoring or reviewing code.
+---
+
+# Fowler code smells
+
+A smell is a heuristic, never a hard rule. It hints that the design could be better. Each smell reads
+_what it is_ → _how to fix_:
+
+- **Mysterious Name**: a function, variable, or type whose name doesn't reveal what it does or holds. → Rename it. If no honest name comes, the design is murky.
+- **Duplicated Code**: the same logic shape appears in more than one place. → Extract the shared shape and call it from both.
+- **Feature Envy**: a method that reaches into another object's data more than its own. → Move the method onto the data it envies.
+- **Data Clumps**: the same few fields or parameters keep travelling together. A type wants to be born. → Bundle them into one type and pass that.
+- **Primitive Obsession**: a primitive or string standing in for a domain concept that deserves its own type. → Give the concept its own small type.
+- **Repeated Switches**: the same `switch` or `if` cascade on the same type recurs in several places. → Replace it with polymorphism, or with one map all sites share.
+- **Shotgun Surgery**: one logical change forces scattered edits across many files. → Gather what changes together into one module.
+- **Divergent Change**: one file or module is edited for several unrelated reasons. → Split it so each module changes for one reason.
+- **Speculative Generality**: abstraction, parameters, or hooks that nothing in the code uses yet. → Delete them. Inline back until a real need shows.
+- **Message Chains**: long `a.b().c().d()` navigation the caller shouldn't depend on. → Hide the walk behind one method on the first object.
+- **Middle Man**: a class or function that mostly just delegates onward. → Cut it and call the real target directly.
+- **Refused Bequest**: a subclass or implementer that ignores or overrides most of what it inherits. → Drop the inheritance and use composition.
+
+Source: Martin Fowler, _Refactoring_ (2nd ed.), chapter 3. The selection and wording follow Matt Pocock's
+[code-review skill](https://github.com/mattpocock/skills/blob/main/skills/engineering/code-review/SKILL.md).

package/src/skills/review-style/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: review-style
+description: Review changes against coding and documentation standards (repo standards plus a list of style skills), then optionally fix the findings. Use when the user wants a style, standards or conventions review of a branch, a commit range or uncommitted work.
+---
+
+# Review style
+
+Review a change against two kinds of standards:
+
+- **Repo standards**: whatever the repository documents about how code is written.
+- **Styles**: the style skills listed below. They apply in every repository.
+
+Repo standards always win. Where a repo standard endorses something a style would flag, the style finding is
+**suppressed**.
+
+## Styles
+
+Each path is relative to this skill's base directory. Add a style by adding one line.
+
+- `../fowler-code-smells/SKILL.md`
+- `../cognitive-load/SKILL.md`
+- `../documentation-style/SKILL.md`. It applies only to code comments, doc comments and Markdown files.
+- `../baseline-conventions/SKILL.md`
+
+## Process
+
+### 1. Pin the scope
+
+The caller's words pick one of these modes:
+
+| Mode | Example | Diff |
+|------|---------|------|
+| Since fixed point plus uncommitted (default) | `/review-style master` | `git diff $(git merge-base <fixed-point> HEAD)`, plus untracked files |
+| Committed only | `/review-style master committed only` | `git diff <fixed-point>...HEAD` |
+| Uncommitted only | `/review-style uncommitted` | `git diff HEAD`, plus untracked files |
+| Staged only | `/review-style staged` | `git diff --cached` |
+| Unstaged only | `/review-style unstaged` | `git diff`, plus untracked files |
+
+When the words don't clearly name a mode, ask. When a mode needs a fixed point and none is given, ask for it.
+Offer the merge-base with the default branch (`master` or `main`) as the suggested answer.
+
+When the caller names files, limit the diff to them, for example `git diff <fixed-point> -- <files>`. Other
+changed files stay out of the review and out of the fixes.
+
+Untracked files are those from `git ls-files --others --exclude-standard`. In the modes whose diff says "plus
+untracked files", add each one to the diff as a new file whose every line is added. The other modes leave them out.
+
+Confirm the fixed point resolves with `git rev-parse`. Stop when the diff is empty. Write the diff to one temp
+file, in the scratchpad when there is one. Also note `git log <fixed-point>..HEAD --oneline` when the mode
+includes commits.
+
+The step is done when one diff file exists and every reviewer will read that same file.
+
+### 2. Collect the repo standards
+
+Search the repository for every file that documents how code is written:
+
+- `CODING_STANDARDS.md`, `CONTRIBUTING.md`, `CODESTYLE.md`, `STYLEGUIDE.md`, and docs about style or conventions.
+  Look at the repository root, `.github/` and `docs/`.
+- `CLAUDE.md` and `AGENTS.md` at every level, plus every file they link to about code, tests or docs.
+  The block between `<!-- foifi:start` and `<!-- foifi:end -->` holds workflow rules, not repository
+  standards; count only the files it links under "Standards". In a legacy file that says a workflow generated it
+  from a template, count only the parts it names as repository standards.
+
+Skip linter and formatter configs. Tooling enforces them already.
+
+### 3. Resolve the styles
+
+Turn each path in [Styles](#styles) into an absolute path from this skill's base directory. Reviewers don't
+know that directory, so they only get absolute paths.
+
+### 4. Review in parallel
+
+Start both reviewers in one message, as foreground sub-agents:
+
+- One **repo reviewer** for all repo standards together, when step 2 found any.
+- One **style reviewer** for all styles together. Two reviewers keep the token cost flat as styles are added.
+
+Each prompt carries:
+
+- The diff file path and the commit list.
+- Its standards: the repo standard files, or the absolute paths of every style's `SKILL.md`. The style
+  reviewer reads each `SKILL.md` and every file it links to, and applies each style only where it says it
+  applies.
+- For the style reviewer, the repo standard files too, so they can suppress overridden findings.
+- The **context rule**: before judging a hunk, read its whole enclosing method and type. Follow the calls,
+  types and parents it touches whenever a rule needs them. Search the repository when a rule asks about
+  duplication.
+- The **scope rule**: anchor every finding on a changed line. Flag a problem in surrounding code only when the
+  change creates or worsens it, such as adding a fourth level of nesting. Leave problems that already existed
+  alone. Lift this rule only when the caller asked for it.
+- The brief:
+
+  > Apply every rule of your standard to every changed hunk. Report each finding as:
+  > `path:line`, a title of a few words, the quoted code, the rule (standard file plus rule name), hard or judgement, and a suggested
+  > fix in a few words. Every finding gets a suggested fix. Use one sentence when a few words can't carry it. A breach of a repo standard may be hard. A style finding is always a judgement call. Skip anything
+  > tooling enforces.
+  >
+  > Style reviewer only: when a repo standard endorses what your style would flag, report it under
+  > **Suppressed**, citing the repo rule that overrides it.
+
+### 5. Merge and report
+
+- Merge findings that flag the same line for the same reason. Cite every rule involved.
+- Number the findings `F1`, `F2`, … and group them by file.
+- Write each finding in this shape. ⛔️ marks a hard breach of a repo standard. ⚠️ marks a judgement call.
+  The title names the problem in a few words.
+  ```
+  - <icon> **<ID> <title>** _(<lines>)_
+    <what is wrong and why>
+    → <fix> _(<standards>)_
+  ```
+  For example:
+  ```
+  - ⛔️ **F1 Javadoc repeats the accessor** _(:71)_
+    `@return the entity links.` adds nothing the method name doesn't say.
+    → Drop the line. _(Repo comment rules, Doc)_
+  - ⚠️ **F7 Plural name on an invariant checker** _(:12)_
+    The plural name suggests a collection, but the class checks an invariant.
+    → Rename to `DocumentEntityLinkInvariantHelper`. _(Cog)_
+  ```
+- Every finding shows its fix. When a reviewer sent none, write one.
+- List suppressed findings in a separate **Suppressed** section, each with its overriding repo rule.
+- End with one line: findings per standard, hard violations count, and the worst issue.
+
+### 6. Fix
+
+When the caller asked for a report only, stop after step 5. When the caller asked for fixes up front, fix every
+finding. Otherwise, and only when there are findings, ask: fix all, fix hard violations only, fix the IDs I list,
+or fix nothing.
+
+Start one **fixer** sub-agent with:
+
+- The selected findings, verbatim, with their rule references.
+- The absolute paths of all standards, so it can look a rule up.
+- The brief:
+
+  > Fix each finding in the working tree. Then run the repository's documented cheap check, such as compile
+  > and format, the way its `CLAUDE.md` or `CONTRIBUTING.md` says. Leave the changes uncommitted. Report
+  > each ID as fixed or skipped, with the reason for every skip.
+
+Suppressed findings are never fixed. Relay the fixer's report.

package/src/templates/AGENTS.md

@@ -1,48 +1,49 @@
-# Repository Guide
+<!-- foifi:start — Managed by foifi. /5:reconfigure rewrites everything up to foifi:end. Everything outside this block belongs to the repository and ranks above it: it is part of the repository's own standards. -->
 
-{PROJECT_OVERVIEW}
+# Workflow Rules (foifi)
 
 ## Build & Run Commands
 
 {BUILD_RUN_COMMANDS}
 
-## Skill Usage
+## Commit Messages
 
-Before implementing changes, always check the available skills for relevant implementation guidance.
+{COMMIT_MESSAGE_RULE}
 
-Use skills to understand project-specific workflows, commands, testing expectations, and implementation conventions before editing code.
+## Standards
 
-## Commit Messages
+These rules decide how code is written here, in this order:
+
+1. **This repository's own standards always win.** They are everything in `AGENTS.md` and `CLAUDE.md` outside this block, plus these files:
 
-Use the `/5:commit` command or `$5-commit` skill when creating commits. It reads `.5/config.json` and applies the configured `git.commitMessage.pattern`, including ticket IDs from branch names when configured.
+{REPO_STANDARDS_LINKS}
 
-## Workflow Rules
+2. **The workflow's style skills set the baseline** wherever the repository's standards say nothing: `fowler-code-smells`, `cognitive-load`, `documentation-style`, and `baseline-conventions`. Follow them when you write or review code. Where a repository standard endorses something a style would flag, the repository standard wins.
+3. **The workflow rules below** (Simplicity First, Testing, Surgical Changes, Goal-Driven Execution) apply as well. When a repository standard asks for more, such as a changelog entry or a test, do what it asks.
 
-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.
+Run the `review-style` skill to check a change against all of them.
 
-## Coding Guidelines
+## Planning
 
-{CONVENTIONS_REFERENCE}
+Plan non-trivial changes in plan mode (Codex: run `$5-plan`). Shape each plan as the change needs; add a mermaid diagram when a flow, state machine, or component relationships explain the change better than text, and plan what the repository standards require, such as tests or a changelog entry.
 
-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.
-4. Extract helpers or classes when logic starts mixing orchestration, parsing, IO, and mapping in one place.
-5. Favor SRP and DRY, but follow surrounding module conventions before introducing new abstractions.
-6. Keep features modular: wire backend providers in feature modules, keep UI state in hooks, and avoid cross-layer shortcuts.
+When the request names a ticket, fetch it (Jira MCP or `gh issue view`) and confirm its content with the user before planning.
+
+After the user approves a plan, run `/5:implement {plan-path}` (Codex: `$5-implement {plan-path}`). Do not implement the plan any other way.
 
 ## 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**.
+2. Does it **already exist in this codebase**? Search before you write — reuse the helper, util, type, or pattern that is already here instead of re-implementing it.
+3. Does the **language or standard library** already solve it?
+4. Is there a **native platform or framework** feature for it?
+5. Does an **already-installed dependency** cover it? Don't add a new dependency for this.
+6. Can it be a **single, clear expression** instead of a new abstraction?
+7. Only then: write the **minimum viable implementation**.
+
+The hierarchy shortens the solution, never the reading: understand the code the change touches before picking a step.
 
 Non-negotiable regardless of the above: security, data integrity, correctness, and accessibility.
 
@@ -53,6 +54,9 @@ Then apply these rules:
 - No flexibility or configurability that was not requested.
 - No error handling for impossible scenarios.
 - If you write 200 lines and it could be 50, rewrite it.
+- Bug fix = root cause, not symptom: find every caller of the function you touch and fix the shared code path once.
+- Large or ambiguous request: build the smallest version that satisfies it and ask about the rest in the same response instead of building it speculatively.
+- When you finish, name what you deliberately left out in one line each (`skipped: X — add when Y`). No essays defending the simplification.
 
 Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
 
@@ -80,6 +84,8 @@ When your changes create orphans:
 
 The test: Every changed line should trace directly to the user's request.
 
+Before you report a task as done, check your own diff (`git status --short` and `git diff --stat`): revert files and changes that do not trace to the request. For every dependency the diff adds: keep it and name it in your reply if the user asked for it; otherwise remove it with the package manager and use existing code, the standard library, or an installed dependency instead. For a deeper pass, run `/5:lean-check` (Codex: `$5-lean-check`).
+
 ## Goal-Driven Execution
 
 Define success criteria. Loop until verified.
@@ -102,10 +108,4 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 
 {PROJECT_DOCUMENTATION_LINKS}
 
-## Codebase Index
-
-{CODEBASE_INDEX_LINKS}
-
-Use the `use-index` skill before running broad Glob/Grep scans. It handles freshness checks, file selection by task type, and fallback strategies. If index files are more than one day old, regenerate them by running `.5/index/rebuild-index.sh` before relying on them.
-
-{CUSTOM_DOCUMENTATION}
+<!-- foifi:end -->

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

@@ -8,12 +8,7 @@
 
 ## How to Use This File
 
-1. Review this file if you want context before applying fixes
-2. Run: `/5:address-review-findings`
-3. The command will present each finding one by one with a recommendation
-4. Choose `fix`, `wont_fix`, `wait`, or provide textual instructions
-
-The command records your decisions separately and applies only findings marked `fix`.
+`/5:review` hands this file to `/5:address-review-findings`, which fixes the clear findings on its own and asks you, one question at a time, about the rest. Run `/5:address-review-findings --interactive` to decide on every finding yourself.
 
 ---
 
@@ -44,6 +39,4 @@ The command records your decisions separately and applies only findings marked `
 - Questions: {N}
 - Manual Review: {N}
 
-**Next Steps:**
-1. Run: `/5:address-review-findings`
-2. Decide on each finding interactively
+**Next Step:** `/5:address-review-findings` (runs automatically after `/5:review`)