5-phase-workflow 3.0.0 → 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/dependency-guard.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// Stop hook: when the uncommitted diff adds a dependency, make Claude justify it once
+// before finishing. New dependencies are the most reliable, heuristic-free drift signal.
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+// Each extractor returns the dependency identities a manifest declares. The hook compares
+// those sets with HEAD, so config edits and version bumps of existing packages never count.
+const pep508Name = spec => (spec.trim().match(/^([A-Za-z0-9][A-Za-z0-9._-]*)/) || [])[1];
+const normalizePy = name => name && name.toLowerCase().replace(/[_.]+/g, '-');
+const jsonKeys = sections => text => { const json = JSON.parse(text); return sections.flatMap(s => Object.keys(json[s] || {})); };
+const matchAll = (text, re, pick) => [...text.matchAll(re)].map(pick);
+
+function requirementsDeps(text) {
+  return text.split('\n')
+    .map(l => l.replace(/#.*/, '').trim())
+    .filter(l => l && !l.startsWith('-'))
+    .map(l => normalizePy(pep508Name(l)))
+    .filter(Boolean);
+}
+
+// Minimal TOML walk for Cargo.toml, Pipfile, and pyproject.toml (PEP 621, PEP 735, Poetry).
+function tomlDeps(text) {
+  const deps = [];
+  let section = '';
+  let inArray = false;
+  // Collects quoted specs; returns true once the array closes (a `]` outside quotes, not in "pkg[extra]").
+  const arrayLine = line => {
+    matchAll(line, /"([^"]+)"|'([^']+)'/g, m => normalizePy(pep508Name(m[1] || m[2]))).forEach(d => d && deps.push(d));
+    return line.replace(/"[^"]*"|'[^']*'/g, '').includes(']');
+  };
+
+  for (const raw of text.split('\n')) {
+    const line = raw.replace(/\s#.*$/, '').trim();
+    if (inArray) { inArray = !arrayLine(line); continue; }
+    const header = line.match(/^\[\[?([^\]]+)\]\]?$/);
+    if (header) {
+      section = header[1].trim();
+      const dotted = section.match(/(?:^|\.)(?:dependencies|dev-dependencies|build-dependencies)\.([^.]+)$/);
+      if (dotted) deps.push(dotted[1]); // Cargo: [dependencies.serde]
+      continue;
+    }
+    const key = (line.match(/^"?([A-Za-z0-9_.-]+)"?\s*=/) || [])[1];
+    if (!key) continue;
+    const arrayOfSpecs = (section === 'project' && key === 'dependencies') ||
+      section === 'project.optional-dependencies' || section === 'dependency-groups';
+    if (arrayOfSpecs && line.includes('[')) {
+      inArray = !arrayLine(line.slice(line.indexOf('[') + 1));
+    } else if (/(?:^|\.)(?:dependencies|dev-dependencies|build-dependencies|packages|dev-packages)$/.test(section) && key !== 'python') {
+      deps.push(key);
+    }
+  }
+  return deps;
+}
+
+function goModDeps(text) {
+  const deps = [];
+  let inBlock = false;
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    if (/^require\s*\($/.test(line)) { inBlock = true; continue; }
+    if (inBlock && line === ')') { inBlock = false; continue; }
+    if (line.includes('// indirect')) continue; // pulled in by tooling, not chosen
+    const spec = inBlock ? line : (line.match(/^require\s+(.+)$/) || [])[1];
+    const mod = spec && spec.split(/\s+/)[0];
+    if (mod && !mod.startsWith('//')) deps.push(mod);
+  }
+  return deps;
+}
+
+const EXTRACTORS = [
+  [/^package\.json$/, jsonKeys(['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'])],
+  [/^composer\.json$/, jsonKeys(['require', 'require-dev'])],
+  [/^requirements.*\.txt$/, requirementsDeps],
+  [/^(pyproject\.toml|Pipfile|Cargo\.toml)$/, tomlDeps],
+  [/^go\.mod$/, goModDeps],
+  [/^Gemfile$/, text => matchAll(text, /^\s*gem\s+['"]([^'"]+)['"]/gm, m => m[1])],
+  [/^pom\.xml$/, text => matchAll(text, /<dependency>([\s\S]*?)<\/dependency>/g, m =>
+    [/<groupId>([^<]+)</, /<artifactId>([^<]+)</].map(re => (m[1].match(re) || [])[1] || '?').join(':'))],
+  [/^build\.gradle(\.kts)?$/, text => matchAll(text,
+    /^\s*(?:implementation|api|compileOnly|runtimeOnly|testImplementation|testRuntimeOnly|annotationProcessor|kapt|ksp|classpath)\s*\(?\s*(?:['"]([^'":]+:[^'":]+)|(libs\.[\w.]+))/gm,
+    m => m[1] || m[2])],
+  [/\.csproj$/, text => matchAll(text, /<PackageReference\s+Include="([^"]+)"/gi, m => m[1])]
+];
+
+function git(cwd, args) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+}
+
+function headVersion(root, file) {
+  try { return git(root, ['show', `HEAD:${file}`]); } catch (e) { return null; }
+}
+
+function addedDependencies(root) {
+  const changed = git(root, ['diff', 'HEAD', '--name-only']).split('\n').filter(Boolean);
+  const untracked = git(root, ['ls-files', '--others', '--exclude-standard']).split('\n').filter(Boolean);
+  const found = [];
+
+  for (const file of new Set([...changed, ...untracked])) {
+    const extract = (EXTRACTORS.find(([re]) => re.test(path.basename(file))) || [])[1];
+    const abs = path.join(root, file);
+    if (!extract || !fs.existsSync(abs)) continue;
+    try {
+      const before = headVersion(root, file);
+      const old = new Set(before ? extract(before) : []);
+      extract(fs.readFileSync(abs, 'utf8'))
+        .filter(d => !old.has(d))
+        .forEach(d => found.push(`${d} (${file})`));
+    } catch (e) {
+      // Unparseable manifest (e.g. mid-edit JSON): skip this file, keep checking the others.
+    }
+  }
+  return [...new Set(found)];
+}
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    if (data.stop_hook_active) process.exit(0); // Claude is already continuing because of a Stop hook
+
+    const root = git(data.cwd || process.cwd(), ['rev-parse', '--show-toplevel']).trim(); // git paths are root-relative
+    const deps = addedDependencies(root);
+    if (!deps.length) process.exit(0);
+
+    // Ask once per session and dependency set, so an accepted dependency doesn't nag on every stop.
+    const stateFile = path.join(root, '.5', '.dependency-guard.json');
+    const signature = `${data.session_id || ''}:${deps.slice().sort().join('|')}`;
+    let seen = [];
+    try { seen = JSON.parse(fs.readFileSync(stateFile, 'utf8')).signatures || []; } catch (e) { /* first run */ }
+    if (seen.includes(signature)) process.exit(0);
+    if (fs.existsSync(path.dirname(stateFile))) {
+      fs.writeFileSync(stateFile, JSON.stringify({ signatures: [...seen, signature].slice(-20) })); // concurrent sessions
+    }
+
+    process.stdout.write(JSON.stringify({
+      decision: 'block',
+      reason: `Uncommitted changes add dependencies:\n${deps.map(d => `- ${d}`).join('\n')}\n\n` +
+        'For each one: if the user asked for it or added it themselves, keep it and name it in your reply. ' +
+        'Otherwise remove it with the package manager (never edit a lockfile by hand) and use existing code, ' +
+        'the standard library, a native platform feature, or an installed dependency instead.'
+    }));
+    process.exit(0);
+  } catch (e) {
+    process.exit(0); // Never block on errors (not a git repo, no HEAD, unparseable manifest)
+  }
+});

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,14 +26,13 @@
         ]
       }
     ],
-    "PreToolUse": [
+    "Stop": [
       {
-        "matcher": "Task|Agent",
         "hooks": [
           {
             "type": "command",
-            "command": "node .claude/hooks/config-guard.js",
-            "timeout": 5
+            "command": "node .claude/hooks/dependency-guard.js",
+            "timeout": 10
           }
         ]
       }

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.