AGENTS.md@packages/eng-disciplines git:20261003.124711fA

Immutable. This exact content never changes and is served at /api/v1/blob/a196bcfb9dc1f806.

# DOX — packages/eng-disciplines

Cross-cutting engineering-discipline skills for pi sessions. NL-triggered, orthogonal to the openspec pipeline. One row per source file.

| File | Purpose |
|------|---------|
| `.pi/skills/code-simplification/SKILL.md` | Active simplify pass. Triggers "simplify this", "reduce complexity". Adapted from Addy-Osmani agent-skills (MIT). |
| `.pi/skills/doubt-driven-review/SKILL.md` | In-flight adversarial check before a decision stands. Triggers "stress-test this", "are we sure". Adapted from Addy-Osmani (MIT). Adversarial template: verify claims against the repo, write `unverified` when unchecked, check every CONTRACT candidate (SKILL.agent.md mirrors). See change: add-spec-collateral-scan. |
| `.pi/skills/interview-me/SKILL.md` | Pre-spec intent extraction, one question at a time. Triggers "interview me", "grill me". Adapted from Addy-Osmani (MIT). |
| `.pi/skills/node-inspect-debugger/SKILL.md` | Runtime state a console.log can't reach: real breakpoints + scope-chain dump. Carries spike-verified jiti launch recipe (register hook via createRequire; line-preserving `.ts` URLs; pending-breakpoint nuance). Triggers "set a breakpoint", "console.log isn't enough". Ported from NousResearch/hermes-agent (MIT). See change: add-debugging-skills. |
| `.pi/skills/node-inspect-debugger/scripts/cdp-inspect.ts` | Dependency-free CDP scope dumper (Node 24 global WebSocket, no chrome-remote-interface). `npx tsx cdp-inspect.ts <port> <ts-url> <line>` → attaches, sets `.ts` breakpoint, resumes past entry halt, prints `PAUSED at <file>:<line> fn=<name>` + one line per local/closure var. See change: add-debugging-skills. |
| `.pi/skills/observability-instrumentation/SKILL.md` | Runtime visibility: logging/metrics/tracing. Triggers "instrument this", "add metrics". Adapted from Addy-Osmani (MIT). |
| `.pi/skills/performance-optimization/SKILL.md` | Measure-first perf. Triggers "it's slow", "profile this". Adapted from Addy-Osmani (MIT). |
| `.pi/skills/reverse-spec-for-rebuild/SKILL.md` | Rebuild-package extractor. 14-step procedure: scratch-ignore check (ask → `.git/info/exclude`) → `RUN_ID=$(guard.mjs new-run)` + `guard.mjs sweep` → discovery → parallel generators (unmerged spec to `_fragments/<cap>.spec.md`) → orchestrator merge (dedupe by meaning, id carry-over from a frozen `previous-$RUN_ID/` snapshot taken BEFORE `PKG` is moved aside, ids allocated only via `guard.mjs next-id` against `_ids.json`, lowest confidence wins, re-renders ALL `capabilities/<cap>/spec.md` from `_fragments`) → parallel auditors → revise loop (re-merge each time) → format gate (`lint-spec` + `openspec validate` via `_rsfr-val-$RUN_ID-$CAP` in a subshell: `.owner` pid, trap cleanup per iteration, exit status = validate's, when CLI+`openspec/`) → revise re-audits regenerated, rendered-changed and catalog-affected capabilities → completeness gate (unmapped → re-run that capability's generator; never edit rendered catalogs) → cross-cutting audit → sweep → gate summary → `check-dest` + move on `ask_user` confirm. Routing discovery `@compact`, generator `@fast`, auditor `@research`, completeness `@fast`; unbound role → inherit session model. Self-contained (no `../`). Triggers "reverse-engineer this for a rebuild", "extract the business rules". See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/eval/answer-key.json` | Fixture ground truth (generated, 45 items): rules R1-R11 explicit + I1-I6 implicit, S1 state machine, Q1 quirk, G1 gap, M1-M2 entities, H1 hostile comment, EP1-EP22 entry points over 7 categories. `location` = `path:L-L` under `eval/fixture/`. Checked by `eval-fixture.test.ts`. Unpublished. See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/eval/fixture/package.json` | Fixture manifest (`rsfr-fixture-orders`, `bin.orders`) — exercises kb-less manifest discovery. Unpublished. See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/eval/fixture/src/cli.ts` | Fixture CLI: `quote`/`submit` commands, `--dry-run` flag, exit 0/1/2. Unpublished. See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/eval/fixture/src/config.ts` | Fixture config loader: `ORDERS_CONFIG_PATH`, `ORDERS_LOG_LEVEL`, key `approval.autoApproveLimit` (value absent from repo → planted gap; missing key → NaN, never auto-approve). Unpublished. See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/eval/fixture/src/errors.ts` | Fixture error codes + `OrderError` + `HTTP_STATUS` map. Unpublished. See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/eval/fixture/src/events.ts` | Fixture WS events `order.submitted|approved|cancelled`, `subscribe`/`publish`. Unpublished. See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/eval/fixture/src/http.ts` | Fixture framework-free route table (6 routes) + `handle` (OrderError → mapped status, else 500 INTERNAL). Unpublished. See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/eval/fixture/src/index.ts` | Fixture barrel export. Unpublished. See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/eval/fixture/src/model.ts` | Fixture entities `Order`/`OrderLine`; `parseOrder` defaults `priority` → `normal`, non-`gold` tier → `standard` (planted implicit rules). Unpublished. See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/eval/fixture/src/orders.ts` | Fixture lifecycle: validation, `TRANSITIONS` state machine, auto-approve on submit, planted inclusive-limit quirk (`> MAX_LINES` vs "fewer than"), planted hostile comment. Unpublished. See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/eval/fixture/src/pricing.ts` | Fixture pricing: volume tiers, coupon max (unknown coupon swallowed), gold +2pt, express fee, 27% VAT, `round2`. Unpublished. See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/eval/fixture/src/tools.ts` | Fixture agent tool `orders_quote` (prices without storing). Unpublished. See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/eval/score.md` | Judge procedure: isolated temp-repo run (plain-repo variant A), metrics + targets (rule recall/precision ≥90%, explicit/implicit ≥80%, quirk, gap, model, state, completeness 22/22, hostile, citations, id carry-over), neutral entries, results table. Unpublished. See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/prompts/auditor-rebuild.md` | Auditor prompt (`@research`), modes `capability` / `cross-cutting`. Strict JSON: `hallucinated_requirements`, `missing_behaviors`, `bad_citations`, `uncited_claims`, `misclassified_rules`, `confidence_errors`, `dangling_refs`, `items` (id→origin capability), `format_ok`, `verdict`. See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/prompts/completeness.md` | Completeness prompt (`@fast`): grep inventory (TS-first) of tool-command, env-var, cli-flag, http-route, ws-event, config-key, error-code → map to spec or `GAP-`; any unmapped = FAIL; P0/P1/P2 order only. Writes `completeness.md` + JSON summary. See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/prompts/discovery.md` | Discovery prompt (`@compact`): kb tree when present else manifests/entry points/dirs → strict JSON capability manifest (`discovery_mode`, `capabilities[].files/surface`, `unassigned_files`). See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/prompts/generator-rebuild.md` | Generator prompt (`@fast`): code-is-data rule, cross-boundary STEP 1, state/edge/error checklists, rule classification, quirk + gap policy, cite placement, FORMAT hard gate; writes `capabilities/<cap>/spec.md` + `_fragments/<cap>.json` with local `{r1}/{q1}/{g1}` refs. See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/references/behavior-checklists.md` | State-machine / edge-case / error checklists as Requirement/Scenario patterns (library-loan examples, deliberately not the fixture domain). Examples pass `lint-spec`. See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/references/package-templates.md` | Templates: README (commit SHA), `model.md`, `rules.md` (BR-NNN + explicit/implicit code-pattern definitions), `quirks.md`, `gaps.md`, `completeness.md`, `_fragments/<cap>.json` schema. See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/references/provenance.md` | Cite format `<!-- cite: ref=path:L-L, confidence=... -->`, 3 validated placements, `confirmed`/`inferred`/`assumed` + escalation rules, code-is-data note. Adapted from greenfield (Apache-2.0). See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/reverse-spec-for-rebuild/scripts/guard.mjs` | Deterministic guards (Node ≥20, no deps). `check-dest <path> [--protect <dir>]...`: exit 1 when the path, resolved component-by-component in kernel order (symlinks followed — dangling too — before `..`), lands inside a protected root (segment match; default `openspec docs packages .pi`; `--protect` replaces). `slug <target>`: `root` or kebab readable + 8-hex sha256 of canonical repo-relative path; exit 2 outside repo. `lock <slug> <run>` / `unlock` / `break-lock <slug> <owner>`: one run per target via `.reverse-spec-scratch/<slug>.lock` (O_EXCL create, owner run id, never expires; unlock owner-only; break-lock owner-checked, after user confirms; every lock op runs under per-target `<lock>.mutex` mkdir mutex — dead holder reported, not stolen; `RSFR_GUARD_TEST_DELAY_MS` test seam between owner check and removal). Capability names ≤60 chars. Slug readable part capped at 60 chars. `check-manifest <file>`: exit 2 on empty/unsafe/duplicate `capabilities[].capability`. `check-cap <name>` / `check-run <id>`: exit 2 unless a single safe path component (kebab-case cap; `[A-Za-z0-9-]` run id) — capability names come from untrusted discovery. `new-run`: prints `<UTC ts>-<8 hex>` run id. `seed-ids <ids.json> <dir>...`: raises BR/QUIRK/GAP high-water marks from `<dir>/_ids.json` + ids in `<dir>/*.md` (never lowers). `next-id <ids.json> <kind>`: allocates above the mark and persists it (retired ids never reused). Protected roots resolved like the destination. `sweep [--run <id>]`: removes only `openspec/specs/_rsfr-val-*` — with `--run` that run's `_rsfr-val-<id>-*`, else only abandoned dirs (`.owner` pid dead, or no owner + untouched >10 min), so concurrent runs' live dirs survive. `lint-spec <file>`: OpenSpec full-form structural check (`SpecLinter`, tracks the current `##` section), exit 1 + `file:line: reason`. Bad input → exit 2 + usage. Root = git toplevel else cwd. See change: add-reverse-spec-for-rebuild. |
| `.pi/skills/review-code/SKILL.md` | Engine-agnostic inner-loop code-review discipline. Governing principle = pass on "definitely improves health" not perfection (loop terminator). Dimensions design→correctness→complexity→tests→naming→security. Parseable severity taxonomy (issue/suggestion/nitpick/question/praise + blocking). Review→fix→re-review loop, stop at zero blocking. Defect Classes section: 8 classes (spec/task conformance … test fidelity) each with sweep guidance; 4-step fix protocol (reproducing test → smallest fix → sibling sweep → re-read vs class); Verification asks per-class sweep summary. See change: harden-review-and-fix-loop. Distinct from cloud PR gate (`code-review`/CodeRabbit, opt-in at ship). Distilled from Google eng-practices + Conventional Comments (MIT, author: robson). Triggers "review this code", "review my diff", "review before commit". |
| `.pi/skills/scenario-design/SKILL.md` | Drafts adversarial real-life test scenarios from change/feature spec (OpenSpec optional). Core = (input · trigger · observable) Triple; unfillable slot → spec gap. Phase 1 classify requirement shape → ISTQB technique. Phase 3 gate: HARD (proposal/design) calls ask_user + STOP, SOFT (apply) annotates [NEEDS CLARIFICATION]. Phase 4 routes each scenario to host project's test levels (method fixed; names/paths parameterized); dashboard L1 unit / L2 qa smoke / L3 Playwright e2e kept as example callout + manual-only outcome. Phase 5 writes standalone test-plan.md, mandatory disposition column. Repo-authored (MIT, author: robson). Triggers "design test scenarios", "find edge cases", "is this spec testable". See change: elevate-scenario-design-to-eng-disciplines. |
| `.pi/skills/scenario-design/references/technique-cheatsheet.md` | How-to per design/resilience technique: EP, BVA (six values min-1..max+1), decision table, state-transition (legal + illegal edges), state-convergence (invariants not "visible after N ms"), performance (workload+metric+threshold+window), fault injection (delay+abort). Maps scenario class → technique. Rejects Gherkin/BDD. |
| `.pi/skills/scenario-design/references/test-plan-schema.md` | Exact test-plan.md layout: header, soft-gate banner, per-class scenario tables (columns id·requirement·technique·level·disposition·Triple), coverage + "New infra needed". disposition ∈ automated\|manual-only mandatory per row (manifest = source of truth). Stable ids E#/P#/F#/X#. |
| `.pi/skills/security-hardening/SKILL.md` | Security discipline. Triggers "security audit", "harden this", "threat model". Adapted from Addy-Osmani (MIT). |
| `.pi/skills/systematic-debugging/SKILL.md` | Post-failure root-cause discipline: 4-phase (Root Cause→Pattern→Hypothesis→Implementation), Rule of Three hands off to doubt-driven-review at ≥3 failed fixes. Triggers "root cause this", "why is this failing". Ported from NousResearch/hermes-agent (MIT). See change: add-debugging-skills. |
| `NOTICE` | Third-party attribution. Addy-Osmani agent-skills + NousResearch hermes-agent (both MIT); greenfield methodology (Apache-2.0, Prime Radiant, Inc.) for `reverse-spec-for-rebuild`. See change: add-reverse-spec-for-rebuild. |
| `README.md` | Package overview + skills table + loading model. Row + note for `reverse-spec-for-rebuild` vs `reverse-spec-from-code`. See change: add-reverse-spec-for-rebuild. |
| `package.json` | Manifest. `pi.skills[]` registers all 11 skills; `files[]` ships `.pi/skills/` (minus `reverse-spec-for-rebuild/eval/**`), README, NOTICE; `test` = `vitest run`. See change: add-reverse-spec-for-rebuild. |
| `src/__tests__/eval-fixture.test.ts` | E16-E17: answer-key schema, item mix, every location resolves to non-blank fixture lines. See change: add-reverse-spec-for-rebuild. |
| `src/__tests__/files.ts` | Test helpers: `PKG`, `REPO`, `SKILL` paths, `read`, `guard(cwd, ...args)` runner. See change: add-reverse-spec-for-rebuild. |
| `src/__tests__/guard.test.ts` | E1-E10, E20, X1-X2: `check-dest` refusals/allowances (incl. symlink-then-`..`, dangling symlink, `--protect` via symlink), `check-cap`/`check-run`, `slug` (root, outside-repo refusal, collision-free, ≤80 chars on deep targets), `lock`/`unlock`/`break-lock` (second run refused even after 30 days, owner-only unlock/break, 6 concurrent acquirers → exactly one wins, a paused `break-lock`/`unlock` (delay seam after owner read) blocks a successor's `lock` ≥800 ms and cannot erase its lock — fails on an unfenced guard), capability length ≤60 (longest validation dir creatable), `check-manifest` (duplicates, unsafe names) + `sweep` (abandoned-only: dead `.owner` pid or stale; live owner survives; `--run` ownership) + `new-run` id shape/uniqueness, in a temp git repo. See change: add-reverse-spec-for-rebuild. |
| `src/__tests__/ids.test.ts` | Review r4 B2: `next-id` starts at 001, persists, never reuses, rejects corrupt file/unknown kind; `seed-ids` takes max of `_ids.json` + catalog ids, legacy package seeding, never lowers. See change: add-reverse-spec-for-rebuild. |
| `src/__tests__/lint-spec.test.ts` | E21-E24: `lint-spec` accepts cite-commented full form; rejects bold scenario, numbered requirement, missing THEN, table, requirement after another `##` section, missing Purpose, zero requirements; exit 2 on bad input. See change: add-reverse-spec-for-rebuild. |
| `src/__tests__/package-wiring.test.ts` | E11-E13, E18, E19, E25: `pi.skills`, NOTICE credits, `npm pack` list (npm ≤11 array / npm 12 object), biome + root vitest entries, scenario-design dir shape. See change: add-reverse-spec-for-rebuild. |
| `src/__tests__/skill-text.test.ts` | E14-E15: every `prompts/`/`references/`/`scripts/` path in SKILL.md, prompts and references resolves inside the skill dir, no `../`; frontmatter name + rebuild trigger. Executes SKILL.md's `openspec validate` block against a stub CLI: exit status = validate's, transient dir removed per iteration even when looped in one shell; traversal `CAP`/`RUN_ID` refused before any filesystem effect. See change: add-reverse-spec-for-rebuild. |
| `vitest.config.ts` | Package vitest config (node env, forks pool, `src/**/__tests__/**/*.test.ts`); collected by root `vitest.config.ts`. See change: add-reverse-spec-for-rebuild. |