5-phase-workflow 3.0.1 → 3.1.0

package/src/commands/5/review.md

@@ -1,8 +1,8 @@
 ---
 name: 5:review
-description: Reviews code changes via the built-in code-review skill. Categorizes findings and saves them for /5:address-review-findings.
+description: Reviews code changes for correctness via the built-in code-review skill, for security via security-review when the diff is security-sensitive, and for standards via review-style. Categorizes findings and saves them for /5:address-review-findings.
 allowed-tools: Bash, Read, Glob, Grep, AskUserQuestion, Agent, Skill, mcp__jetbrains__*
-argument-hint: [low|medium|high|max]
+argument-hint: [low|medium|high|max] [since {fixed-point} files: {paths} feature: {name} dirty: {paths}]
 user-invocable: true
 model: sonnet
 ---
@@ -16,7 +16,9 @@ You do NOT apply fixes. Fix application is handled by /5:address-review-findings
 
 ## Step 1: Determine Scope
 
-Ask what to review:
+When the arguments say `since {fixed-point} files: {paths} feature: {name} dirty: {paths}` — `/5:implement` passes this — review exactly those files' changes since that commit and skip the question. `/5:implement` runs this before it commits, so the changes are in the working tree. The working tree can also hold changes the user had before the run: in this scope, **drop every finding whose file is not in `{paths}`**, from every reviewer, before saving.
+
+Otherwise ask what to review:
 
 1. Staged changes (`git diff --cached`)
 2. Unstaged changes (`git diff`)
@@ -36,7 +38,23 @@ Never pass `--fix` or `--comment`. This command only records findings; applying
 Skill(skill: "code-review", args: "{target} {effort}")
 ```
 
-Derive `{target}` from the scope answer: options 1-3 review the current working-tree diff (no target argument needed); option 4 passes the branch. Use the findings it reports.
+Derive `{target}` from the scope answer: options 1-3 and the `since … files:` scope review the current working-tree diff (no target argument needed); option 4 passes the branch. Use the findings it reports.
+
+**Security review** — when the diff touches authentication, authorization, user input handling, secrets, cryptography, or SQL/shell/path construction, and the built-in `security-review` skill is available, invoke it on the same scope:
+
+```text
+Skill(skill: "security-review")
+```
+
+Use the vulnerabilities it reports. Skip it for diffs that touch none of these areas.
+
+**Standards review** — then invoke `review-style` in report-only mode. It checks the same changes against the repository's own standards and the style skills it lists, and repository standards win:
+
+```text
+Skill(skill: "review-style", args: "{mode} report only")
+```
+
+Derive `{mode}` from the scope answer: option 1 passes `staged`, option 2 `unstaged`, option 3 `uncommitted`, option 4 `{base-branch} committed only`, and the `since … files:` scope `{fixed-point} files: {paths}`.
 
 **Fallback path** — on Codex, or when the `code-review` skill is unavailable, spawn one review agent instead:
 
@@ -61,9 +79,11 @@ Manual Review:
 - file: {path}, line: {N}, description: {what}, severity: {level}
 ```
 
+On Codex, or when the `review-style` skill cannot be invoked, read `.claude/skills/review-style/SKILL.md` and follow it with the same arguments.
+
 ## Step 3: Save Findings
 
-Determine feature name from the most recent `.5/features/*/state.json`, or ask the user.
+Use the `feature:` argument when given. Otherwise use the feature of the most recently modified plan in `.5/planning/` — its `feature` frontmatter field, or its file name without `.md` — or ask the user.
 
 Write `.5/features/{feature-name}/review-findings-{YYYYMMDD-HHmmss}.md` using `.claude/templates/workflow/REVIEW-FINDINGS.md`.
 
@@ -81,9 +101,22 @@ When the findings come from the `code-review` skill, map its reported fields ont
 | the concrete fix, else `short_summary` | **Suggested Fix:** |
 | `failure_scenario` | **Original Reviewer Message:** |
 
+Findings from `security-review` map to **Category:** `Fixable` when the fix is local, otherwise `Manual`, always with **Severity:** `error`; its explanation of the exploit goes into **Original Reviewer Message:**.
+
 Findings from the fallback path map directly: Fixable Issues, Questions, and Manual Review become their matching categories.
 
-Do not ask the user to edit action markers in the findings file. The findings file is the review record; `/5:address-review-findings` will present each finding interactively and record decisions separately.
+Findings from `review-style` map like this. Leave out its Suppressed findings; a repository standard overrides them.
+
+| Reported finding | Template field |
+|---|---|
+| ⛔️ hard breach of a repository standard | **Category:** `Fixable`, **Severity:** `error` |
+| ⚠️ judgement call | **Category:** `Fixable`, **Severity:** `suggestion` |
+| `path:line` | **File:**, **Line:** |
+| ID, title, and what is wrong | **Description:** |
+| the `→` fix | **Suggested Fix:** |
+| the cited standards and rules | **Original Reviewer Message:** |
+
+Do not ask the user to edit action markers in the findings file. The findings file is the review record; `/5:address-review-findings` decides on the findings and records the decisions separately.
 
 ## Step 4: Report and Hand Off
 
@@ -101,12 +134,7 @@ Findings saved at `.5/features/{feature-name}/review-findings-{timestamp}.md`
 
 If there are no findings, stop here.
 
-Otherwise ask the user directly whether to continue:
-
-- "Address these findings now?"
-  - Options:
-    1. "Yes, run `/5:address-review-findings {feature-name}`" — decide on each finding interactively, then apply approved fixes
-    2. "No, stop here" — findings stay on disk for later
+Otherwise hand off to `/5:address-review-findings {feature-name}`. It fixes the clear findings on its own, asks the user one question at a time only about real decisions, and then runs build, test, and lint.
 
-- If the user chooses yes: invoke `/5:address-review-findings {feature-name}`.
-- If the user chooses no: tell them to run `/5:address-review-findings {feature-name}` when they are ready, and stop.
+- **Called by `/5:implement`** (the `since … files:` scope): run `/5:address-review-findings {feature-name} dirty: {dirty-paths}` right away. The user approved the plan, and these are the run's own files — except the dirty ones, which also hold the user's earlier work.
+- **Started on its own:** the reviewed code may come from someone else's branch, and the fixes are followed by the project's build and test commands. Ask once: "Fix the clear findings on my own and then run build, test, and lint?" On yes, run it. On no, stop and tell the user they can run `/5:address-review-findings {feature-name}` (or `--interactive`) later.

package/src/commands/5/synchronize-agents.md

@@ -13,7 +13,7 @@ You do NOT modify files manually. After reporting, you are DONE.
 
 # Synchronize Agent Runtimes
 
-Synchronizes user-generated content (skills, commands, agents, rules) between the Claude Code (`.claude/`) and Codex (`.codex/`) runtimes.
+Synchronizes user-generated content (skills, commands, agents, rules) between the Claude Code (`.claude/`) and Codex (`.codex/`) runtimes. Codex reads only `AGENTS.md`, so Claude rules and agent references go into the foifi block there.
 
 ## Step 1: Locate the Sync Script
 

package/src/commands/5/update.md

@@ -42,7 +42,7 @@ Read `.5/version.json` again. Compare the new `installedVersion` to the previous
 
 Run `git status` to show the files modified by the upgrade. Summarize the changes for the user using the correct runtime paths:
 - Claude Code installs typically update files in `.claude/commands/5/`, `.claude/skills/`, `.claude/hooks/`, `.claude/templates/`, `.claude/settings.json`, and `.5/version.json`
-- Codex installs typically update files in `.codex/skills/`, `.codex/templates/`, `.codex/references/`, `.codex/instructions.md`, and `.5/version.json`
+- Codex installs typically update files in `.codex/skills/`, `.codex/templates/`, `.codex/references/`, and `.5/version.json`
 
 ## Step 5: Ask to Commit
 
@@ -67,7 +67,7 @@ Build the commit message by applying the pattern:
 Stage **only** the workflow-managed files shown in `git status`.
 
 - For Claude Code installs, this usually means files inside `.claude/commands/5/`, `.claude/skills/`, `.claude/hooks/`, `.claude/templates/`, `.claude/settings.json`, and `.5/version.json`
-- For Codex installs, this usually means files inside `.codex/skills/`, `.codex/templates/`, `.codex/references/`, `.codex/instructions.md`, and `.5/version.json`
+- For Codex installs, this usually means files inside `.codex/skills/`, `.codex/templates/`, `.codex/references/`, and `.5/version.json`
 
 Never use `git add .` or `git add -A`.
 

package/src/hooks/statusline.js

@@ -103,9 +103,11 @@ process.stdin.on('end', () => {
         parts.push(`\x1b[35m↻ /5:reconfigure\x1b[0m`);
       }
 
-      const migrationFlag = path.join(dir, '.5', '.migration-v2');
-      if (fs.existsSync(migrationFlag)) {
-        parts.push(`\x1b[31m⚠ v1→v2: /5:reconfigure\x1b[0m`);
+      // The installer writes .migration-v{major} after a major upgrade
+      const migrationFlag = fs.readdirSync(path.join(dir, '.5')).find(f => /^\.migration-v\d+$/.test(f));
+      if (migrationFlag) {
+        const major = migrationFlag.slice('.migration-'.length);
+        parts.push(`\x1b[31m⚠ ${major}: /5:reconfigure\x1b[0m`);
       }
     } catch (e) {}
 

package/src/references/configure-tables.md

@@ -37,33 +37,6 @@ Check files in this order (first match wins):
 | rust | `cargo build` | `cargo test` |
 | go | `go build ./...` | `go test ./...` |
 
-## Codebase Pattern Categories to Scan
-
-Use Glob to scan for architectural patterns. For each, check both suffix-based (`*{Pattern}.{ts,js,java,py,rb}`) and directory-based (`{patterns}/**`) globs.
-
-- **Core:** Controllers, Services, Repositories, Models/Entities, Handlers
-- **Data Transfer:** DTOs, Requests, Responses, Mappers, Validators, Schemas
-- **Frontend:** Components, Hooks, Contexts, Stores, Pages, Layouts
-- **API/Routes:** API Routes, Middleware, Guards, Interceptors, Filters
-- **Testing:** Tests/Specs, Fixtures, Factories, Mocks
-- **Utilities:** Utils, Helpers, Constants, Types/Interfaces, Config
-- **Framework-Specific:** Modules, Pipes, Decorators, Blueprints, Views, Serializers
-- **Background/Async:** Jobs, Workers, Events, Listeners, Commands
-- **Database:** Migrations, Seeds
-- **Error Handling:** Exceptions, Errors
-
-For each pattern found: count matching files, identify primary location, sample 1 filename.
-
-## Runnable Command Categories
-
-Scan config files (`package.json` scripts, `Makefile` targets, `pyproject.toml` scripts, `Cargo.toml`, `build.gradle` tasks, `composer.json` scripts, `Rakefile` tasks) for commands in these categories:
-
-Build, Test, Lint, Format, Type Check, Dev Server, Database (migrate/seed), Docker, Deploy, Clean, Generate
-
-Skill naming: `run-{category}` (e.g., `run-build`, `run-tests`, `run-lint`).
-
-For each command found: record exact syntax, note variants (e.g., `test:unit`, `test:e2e`), and environment requirements. Only include commands that are actually detected.
-
 ## Config Schema
 
 ```json
@@ -91,9 +64,6 @@ For each command found: record exact syntax, note variants (e.g., `test:unit`, `
     },
     "context7": {
       "available": false
-    },
-    "skillCreator": {
-      "available": false
     }
   },
   "git": {
@@ -107,9 +77,6 @@ For each command found: record exact syntax, note variants (e.g., `test:unit`, `
   },
   "rules": {
     "generate": true
-  },
-  "conventions": {
-    "generate": true
   }
 }
 ```

package/src/settings.json

@@ -26,18 +26,6 @@
         ]
       }
     ],
-    "PreToolUse": [
-      {
-        "matcher": "Task|Agent",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node .claude/hooks/config-guard.js",
-            "timeout": 5
-          }
-        ]
-      }
-    ],
     "Stop": [
       {
         "hooks": [

package/src/skills/baseline-conventions/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: baseline-conventions
+description: Baseline rules for errors, types, names and tests. They keep a codebase clean when the repository documents no rules of its own. Use when writing, refactoring or reviewing code.
+---
+
+# Baseline conventions
+
+These rules fill the gaps a repository leaves open. A repository standard always wins over them. Each rule reads
+_what it is_ → _how to fix_:
+
+## Errors
+
+- **Swallowed error**: an empty catch, or a catch that ignores the error. → Log it, rethrow it, or turn it into a typed result.
+- **Unhandled async failure**: a promise or future whose failure path nobody handles. → Handle the failure where it is awaited, or pass it on to the caller.
+- **Bare error message**: an error that carries only a string. → Use a typed error that carries the context a reader needs.
+- **Errors as control flow**: an exception thrown for an expected case. → Check the case up front, or return a result.
+
+## Types and names
+
+- **Untyped boundary**: a public function, exported type or data shape without an explicit type, where the language supports one. → Declare the type.
+- **Escape hatch**: `any`, a non-null assertion or an unchecked cast. → Narrow the type. When it can't be avoided, say why in a comment.
+- **Magic value**: a literal number or string whose meaning the reader must guess. → Give it a named constant.
+- **Unclear boolean**: a boolean whose name doesn't read as a question. → Prefix it with `is`, `has`, `can` or `should`.
+
+## Tests
+
+- **Mixed test**: one test that checks several behaviours. → Split it, so each test checks one behaviour.
+- **Method-named test**: a test named after the method it calls. → Name it after the behaviour, such as `returns 404 when the user is missing`.
+- **Weak assertion**: an assertion that only checks a value exists, or that can't fail. → Assert the actual value or outcome.
+- **Tangled test**: setup, action and checks are mixed together. → Order them as arrange, act, assert.
+- **Internal mock**: a mock of an internal module or a pure function. → Mock only at system boundaries such as network, database, filesystem and clock. Test the rest directly.
+- **Silent skip**: a disabled test with no reason. → Fix it, delete it, or link the issue that tracks it.
+- **Unprotected bug fix**: a fix that no test guards. → Add a regression test that fails without the fix, when practical.
+
+## Leftovers
+
+- **Commented-out code**: code kept alive in a comment. → Delete it. Version control keeps the history.

package/src/skills/cognitive-load/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: cognitive-load
+description: Rules for keeping the cognitive load of code low. Use when writing, refactoring or reviewing code.
+---
+
+# Cognitive load
+
+Cognitive load is how much a reader must hold in mind to understand the code. Working memory holds about
+**four chunks**: a variable's value, a branch taken, a call to chase, a mapping to remember. Past four, the
+reader loses the thread.
+
+_Intrinsic_ load comes from the problem itself and stays. _Extraneous_ load comes from how the code is
+written. The rules below cut extraneous load.
+
+## Rules
+
+- **Named conditions.** Give the parts of a compound condition intermediate variables named after what they
+  mean. The `if` then reads as one chunk:
+  ```java
+  var isFresh = price.timestamp().isAfter(cutoff);
+  var isKnownVendor = vendors.contains(price.vendor());
+  if (isFresh && isKnownVendor) { ... }
+  ```
+- **Early returns.** Handle invalid cases with guard clauses at the top. The happy path then runs
+  unindented. Nesting makes the reader carry every outer condition along.
+- **Composition over inheritance.** Deep inheritance chains make the reader trace behaviour across levels.
+  A change in a parent can silently break a child.
+- **Deep modules.** A module earns its place with a simple interface over substantial behaviour. Many
+  shallow modules whose interface is as complex as their body are tiring to navigate. Merge them.
+- **Important logic can be large.** Keep the crux of a feature in one substantial function. Splitting it
+  into many tiny hops hides it.
+- **One stakeholder per module.** A module answers to one user or one concern. "Does one thing" is too vague
+  to judge.
+- **Plain language subset.** Use constructs any developer of the language reads fluently. A clever feature
+  makes the reader learn the feature before the code.
+- **Self-describing values.** Prefer names, enums and descriptive strings over codes that need a lookup
+  table. Return `"jwt_has_expired"` rather than relying on HTTP status `401` vs `403`. Keep business meaning
+  out of transport details.
+- **Plain terms.** Name things with the plainest accurate words, in the problem's own language. Reuse terms
+  already in the codebase.
+- **Duplication over coupling.** A few copied lines beat a premature shared abstraction that couples
+  unrelated code. Every dependency is code the reader may have to debug.
+- **Framework at the edge.** Core logic uses the framework like a library. It stays readable to someone who
+  doesn't know the framework's magic.
+- **Layers only where they hide something.** Add an abstraction only at a real extension point. A layer that
+  only forwards calls is pure indirection.
+- **Boring over clever.** Pick the straightforward solution. Debugging is twice as hard as writing the code.
+- **Familiar is not simple.** Code feels simple to its author. Judge it as a newcomer would. If a newcomer
+  stays confused for about 40 minutes, the code needs work.
+
+Source: Artem Zakirullin, [Cognitive load is what matters](https://github.com/zakirullin/cognitive-load),
+CC BY 4.0. Condensed and adapted.

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

@@ -0,0 +1,72 @@
+---
+name: configure-agents-md
+description: Writes the workflow rules into AGENTS.md as one marked block, links the repository's own standards, and makes CLAUDE.md include AGENTS.md. Never changes content outside the block. Used during /5:implement CONFIGURE and /5:reconfigure.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+model: sonnet
+user-invocable: false
+---
+
+# Configure AGENTS.md Skill
+
+## Overview
+
+This skill writes the workflow rules into `AGENTS.md` as one block between `<!-- foifi:start` and `<!-- foifi:end -->`. Everything outside that block belongs to the repository. The skill never rewrites, moves, or deletes it, in `AGENTS.md` or in `CLAUDE.md`.
+
+A step executor calls it for the CONFIGURE feature. `/5:reconfigure` calls it in refresh mode. Both modes run the same steps:
+
+- **Full mode (default):** input is the plan at `.5/planning/CONFIGURE.md`.
+- **Refresh mode:** the prompt includes "REFRESH MODE" and points at `.5/reconfigure-manifest.json`.
+
+It generates no architecture, testing, concerns, or conventions docs and no codebase index. Agents explore the code themselves.
+
+## 1. Collect Inputs
+
+- **Build and run commands:** from `.5/config.json`, plus other detected scripts worth running. Skip commands that `AGENTS.md` or `CLAUDE.md` already document outside the block.
+- **Commit message rule:** the repository's own commit convention when one is documented, such as in `CONTRIBUTING.md`. Then write `Follow the commit convention in {path}.` Otherwise use `git.commitMessage.pattern` from `.5/config.json` and write `Write commit messages as \`{pattern}\`. Take {ticket-id} from the branch name when it matches \`ticket.pattern\`; drop it otherwise.` Without a pattern, remove the `## Commit Messages` section.
+- **Repository standards:** the files `.claude/skills/review-style/SKILL.md` step 2 counts as repository standards. Use the list in the CONFIGURE plan or the refresh manifest when it has one. Do not count workflow-generated files.
+- **Existing project docs:** `.5/ARCHITECTURE.md`, `.5/TESTING.md`, `.5/CONCERNS.md`, and `.5/CONVENTIONS.md`, when they exist. Link them; never rewrite or delete them.
+
+## 2. Fill the Template
+
+Use `.claude/templates/AGENTS.md` as the block. Keep its marker comments and static sections exactly as written; `review-style` reads the markers to tell workflow rules apart from repository standards.
+
+- `{BUILD_RUN_COMMANDS}` → the build, test, and other commands. Remove the section when there are none left.
+- `{COMMIT_MESSAGE_RULE}` → the commit message rule.
+- `{REPO_STANDARDS_LINKS}` → one bullet per repository standard, as `- [path](path)`. When there are none, write `- None documented yet. The style skills below set the baseline.`
+- `{PROJECT_DOCUMENTATION_LINKS}` → one link per existing `.5/*.md` doc. When there are none, remove the whole `## Project Documentation` section.
+
+## 3. Write AGENTS.md
+
+- **No `AGENTS.md`:** create it with only the block.
+- **`AGENTS.md` with a foifi block:** replace the text from the `<!-- foifi:start` line through the `<!-- foifi:end -->` line. Keep any `<!-- 5-sync:rules-start -->` … `<!-- 5-sync:rules-end -->` and `<!-- 5-sync:agents-start -->` … `<!-- 5-sync:agents-end -->` sections inside the old block unchanged, just before the new `<!-- foifi:end -->`: `configure-rules` and `/5:synchronize-agents` own them. Leave every other byte unchanged.
+- **`AGENTS.md` without a block:** append a blank line and the block at the end. Leave the existing content unchanged.
+- **Legacy file** (its first line starts with `<!-- Generated from the foifi AGENTS.md template`): an earlier version generated the whole file. Keep only what the user wrote: the content under its `## Custom Documentation` heading, unchanged. Write that content, then a blank line, then the block. Drop the rest; the block replaces it.
+
+## 4. Include AGENTS.md from CLAUDE.md (Claude Code only)
+
+Claude Code reads `CLAUDE.md`, and `@AGENTS.md` pulls in the full `AGENTS.md`.
+
+- **No `CLAUDE.md`:** create it with only `@AGENTS.md`.
+- **`CLAUDE.md` without an `@AGENTS.md` line:** append a blank line and `@AGENTS.md`. Leave the existing content unchanged.
+- **`CLAUDE.md` with an `@AGENTS.md` line:** leave it as it is.
+
+## Output Contract
+
+```
+Component A (AGENTS.md): SUCCESS - Wrote the foifi block in AGENTS.md
+  - AGENTS.md (block replaced | appended | created, 3 repository standards linked)
+  - CLAUDE.md (unchanged | @AGENTS.md appended | created)
+```
+
+Or on failure:
+
+```
+Component A (AGENTS.md): FAILED - Unable to read the AGENTS.md template
+```
+
+## DO NOT
+
+- DO NOT change, move, or delete anything outside the foifi block, in `AGENTS.md` or `CLAUDE.md`.
+- DO NOT generate architecture, testing, concerns, or conventions docs, index files, or rebuild scripts.
+- DO NOT rewrite or delete existing `.5/*.md` docs.
+- DO NOT restate repository standards in the block. Link them.

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).