getff — rules as tests

getff compiles your conventions into native toolchain gates (ESLint/husky for npm, clippy for cargo — cargo-deny dependency bans are on the roadmap). Its own AGENTS.md is executable — every claim carries a live-fired enforcement status; the gate fails when a claim drifts from reality. Docs lie; tests don't.

Honest framing: today the executable AGENTS.md is this repo's own — open it, every statement has an enforcement line. getff init (via ./setup, see Installation) installs the enforcement layer (ESLint/husky/CI gates) into your TypeScript project; generating your executable AGENTS.md is the next milestone, not shipped yet.

What you get today

After install, your project has:

1. A skill (.claude/skills/getff/) — auto-activates in Claude Code on questions about lint, tests, CI, mutation testing, contracts, AI-driven code drift.
2. Sub-agents (.claude/agents/) — 11 shipped by default: review-sidecar, living-docs-auditor, compliance-verifier, memory-codification-auditor, aif-init, rule-researcher, capability-reuse-auditor, docplan-auditor, claims-conformance-auditor, fidelity-auditor, rule-test-author (setup.d/20-agents.sh skips seven authoring-only tools and gates two more behind --profile factory):
   • review-sidecar — two-AI tautology review of tests (our differentiator; no earlier deterministic channel — its cousin Stryker is CI-only).
   • living-docs-auditor — runs audit-ai-docs.sh and interprets results (backward Living-Documentation drift).
   • the remaining 6 cover §1.7 PR-review substance (compliance-verifier), memory-to-repo codification audits (memory-codification-auditor), AIF onboarding scaffolds (aif-init), live-documentation rule research (rule-researcher), build-vs-reuse capability audits (capability-reuse-auditor), and DocPlan semantic-grouping judgment for the composition gate (docplan-auditor) — see agents/ for each agent's own description.
   • 2 more agents ship only under --with-aif-suite / --all (they presuppose the aif-handoff operator runtime, same gate as the operator-suite skills — F7 split): orchestrator-worker-discipline + reviewer-discipline, with their aif-orchestrator-discipline skill-context.
   • R1–R20 code-rule validation is enforced earlier (edit-time custom ESLint + pre-push) and via AI Factory's own rules-sidecar (which reads your .ai-factory/RULES.md) — so we no longer ship a competing best-practices-sidecar (C-1 KEEP-AIF, 2026-05-20).
   • skill-context overrides (.ai-factory/skill-context/) ride AIF's own pipeline instead of colliding agent slots (C-1 follow-up, SSOT #50): aif-review/SKILL.md injects our anti-tautology test-review into AIF's review-sidecar; aif-rules-check/SKILL.md injects the R10-naming + test-existence residue into AIF's rules-sidecar.
3. AI Factory templates (.ai-factory/) — DESCRIPTION, ARCHITECTURE, RULES (R1–R11 + R12–R20 for UI + IR1–IR6 for microservices).
4. An audit script (scripts/audit-ai-docs.sh) — drift detection + code-vs-docs probes. ~10 sec run. Each probe has a paired negative test (must fail when introduced bug).
5. Stack configs:
   • ESLint 9 flat config (typescript-eslint strictTypeChecked + Prettier; for React, also react-hooks + jsx-a11y/strict + @next/next) — setup.d/70-deps.sh pins eslint@^9, the verified peer matrix.
   • Vitest 4.x with .unit.ts / .integration.ts / .audit.ts naming and per-module coverage thresholds (90% domain, 85% application).
   • Stryker mutation testing (incremental on PR diff).
   • dependency-cruiser layered architecture rules.
   • Husky pre-commit (lint-staged) + pre-push. The pre-push hook runs getff's own rule checks — rule-glob liveness, lint-staged binary resolution, generated-rule firing, link-check on changed Markdown, un-pinned tool installs — not your typecheck or test suite, which stay yours to wire.
   • GitHub Actions CI with required ci-success job.
   • For React/Next: also Playwright (component testing + e2e) and Storybook test-runner.

Why this exists

Authoritative for: project goal, methodology, design invariants. Other docs (docs/meta-factory/EXECUTION-PLAN.md, docs/meta-factory/PROPOSAL.md, CLAUDE.md) subordinate to this section for these definitions. They remain authoritative for their own scope (operational plan, design history, AI-tooling conventions) but cannot redefine the project's goal.

Goal (user-facing)

AI agents (Claude, Cursor, Copilot, Aider) write plausible-looking code that reliably violates undocumented conventions. Without enforced rules:

• as any and ! non-null assertions multiply.
• Tests pass because they're tautological (expect(x).toBeDefined() for typed values).
• Layer boundaries leak.
• Conventions in CLAUDE.md are forgotten within 3 sessions.

This package operationalizes the principle: every rule that governs your codebase is an executable artifact — an ESLint rule, a pre-push check, a principle test, a mutation gate, a drift probe, or a Living Documentation assertion — that fails when violated, at the earliest reachable channel:

edit-time → pre-commit → pre-push → CI → production audit

CI is the last-resort gate, not the primary one. AI cannot silently bypass what fails at any of these channels.

Practice note: a small number of rules are currently Class C (prose-only, mechanism deferred). See research-patches/2026-05-16-readme-absolutism-vs-class-c-practice.md. These are tracked and audited; rule files self-describe class via a > **Class:** A | B | C line in their header per .claude/rules/doc-authority-hierarchy.md §3.

Methodology

Generate enforcement rules from principles, not from copy-pasted presets. Presets become stale as stacks evolve (Next 14 → 15 → 16 in 18 months); principles age more slowly.

The framework validates itself with its own logic — recursive self-application. Same precedent as GCC three-stage bootstrap or rustc compiling itself: a quality signal that the framework's own claims hold up under its own scrutiny. Quality signal, not the goal.

What must not break (invariants)

• Build-vs-reuse discipline — prior-art consult before any capability commit. SSOT: docs/meta-factory/prior-art-evaluations.md. Macro-level operating philosophy: .claude/rules/build-first-reuse-default.md (default = adopt upstream when problem-class matches; build only when structurally missing). Enforcement: Prior-art: commit trailer + pre-push hook.
• Recursive self-application — make self-audit green = the framework's own conventions don't drift.
• Search-coverage discipline — negative-existence claims («no production analog») fail the §1 6-item checklist before shipping as load-bearing. Rule: .claude/rules/phase-research-coverage.md.
• No paid LLM in CI — no API-billed LLM calls in CI/GH Actions beyond the operator's existing Claude Code subscription. Semantic LLM checks ship as AI-agnostic sub-agent prompts (under agents/) read by active AI sessions, not as automated gates with metered API calls. Rationale + escape hatch: .claude/rules/no-paid-llm-in-ci.md.
• Multi-channel enforcement — every rule fails at the earliest reachable channel: edit-time (ESLint) → pre-commit (lint-staged) → pre-push (husky + audit-ai-docs + §1.7) → CI (discipline-self-check) → production (Living Documentation drift). CI is the last-resort gate.

If recursive self-application breaks, the framework becomes documentation that lies about itself — exactly the failure mode it claims to prevent.

What this project is and isn't

Is: universal satellite for Living Documentation enforcement — neutrally compatible with any companion stack (workflow frameworks, task orchestrators, methodology discipline tools). Focused on R1-R20 rules-as-tests, audit-ai-docs.sh drift detection, mutation testing, principle tests, 5-layer framework. One-button install of pre-configured opinionated discipline.

Isn't: workflow framework (multiple companions exist — see companion-target comparison and SSOT #56-#83); task orchestration / swarm coordination (see same SSOT); standalone CI tool. Not the IDE/CLI runtime our framework deploys into — Claude Code, Cursor, Codex are deployment surfaces, not companions; the framework installs into their workspace via standard project install.

Reuse stance: see .claude/rules/build-first-reuse-default.md. Default = adopt upstream when problem-class matches. Build ourselves only what is structurally missing — currently: Living Documentation, 5-layer framework, methodology discipline, AST-based hooks (shipped Wave 10 / N3 ✅).

Roadmap signals: companion-target comparison shipped 2026-05-16 — see research-patch §3-§4. Verdicts: Superpowers = 3rd named companion (rules-as-tests alignment confirmed via TDD-for-Skills discipline). OhMyOpencode = ADOPT VOCABULARY (SSOT #83) for orchestrator dispatch + verification loop terminology (Atlas + Prometheus naming convention; no runtime dependency). microsoft/agent-framework = REFERENCE-only (different lifecycle / problem class). Cursor / Codex = framework-consumers (different architectural layer — runtimes we install into, not companions at our framework layer). Future widening pending only if new discipline-framework candidates appear.

The 5-layer framework

Layer	What	Tools
1	Architecture / fitness functions	ESLint, dependency-cruiser, ArchUnit
2	Meta-tests (tests about test suite)	AST scans, eslint-plugin-vitest
3	Specification by Example	Vitest it.each, fast-check property tests
4	Mutation testing	Stryker incremental
5	Living documentation	OpenAPI from Zod, ADRs as ArchUnit because(...)

Plus extensions:

• Pre-PR: AIF /aif-verify with sub-agents.
• Production: SLO-as-code (OpenSLO + Pyrra), error budgets, observability 2.0.
• Between services: Pact contract testing with can-i-deploy --to production.
• Between code and AI docs: audit-ai-docs.sh with drift detection + code-vs-docs probes.

For details, see skills/getff/references/:

• checks-map.md — map of all 8 enforcement levels (edit-time → production)
• overview.md — 5 layers with patterns and anti-patterns
• ai-traps.md — what AI violates most + Lessons learned (real grabli)
• self-testing-docs.md — the audit-ai-docs.sh pattern with negative tests
• doc-organization.md — hot/cold split for AGENTS.md, token economy

What's in the repo (operator contour)

What you get today lists what getff init installs into your project. This section maps what the framework repo itself runs — the machinery that keeps the five layers above honest while the framework is being built. Most of it is not shipped to consumers: what ships, and at which tier, is a per-artifact fact, and the authoritative per-artifact list is generated rather than kept by hand (see the closing note).

Family	Where	What it is
Enforcement machinery	packages/core/principles/	Meta-tests about the rules themselves — every rule must carry an executable check and a paired negative test. make self-audit runs them; this is recursive self-application in code.
Discipline rules	.claude/rules/, digest 00-rule-index.md	Prose statutes, each declaring the channel it fires on (edit-time inject, hook, pre-push section, cold agent). The index is generated from the rule files, never hand-edited.
Session hooks	.claude/hooks/	Context injected at the moment of work: the rule matching the edited path, the session bootstrap and goal digest, the output language, kickoff traps, sub-agent context. Plus session continuity — a pre-compaction residue snapshot, a handoff-currency gate, and a plain-words session recap.
Seats (skills)	.claude/skills/	Named roles a session takes: /pipeline (what to work on next — priority scoring over a deterministic feed with completion detection), /arch (design dialogue), /orchestrator and /dispatcher (waves, routing, in-flight probing), /reviewer, /night-mode (autonomous runs), /harvest (finished agent branches into PRs), /story (plain-words recap), /rule-research and /rule-tests (a new rule, and the test that proves it fires), /ai-doc, /self-reflection.
Cold agents

The per-artifact list is generated, not written here. A hand-kept roster of this size drifts on the first pull request that adds a skill — the failure mode .claude/rules/attention-is-not-a-mechanism.md exists to forbid. The reference generator — one card per artifact across installer layers, skills, agents, hooks, templates, rules, scripts, packages, bridge CLI and plugin, with a test asserting population and cards match one-to-one in both directions — is designed and lands with the documentation site. Until it does, the directories above are the source of truth.

Installation

Quick start — one command (recommended)

git clone https://github.com/artyhoo/getff /tmp/rt
cd /your/project
bash /tmp/rt/setup ts-server                 # or react-next; omit to get a stack picker

./setup is the one-click orchestrator (framework + companions + runtime-bridge). Flags:

• --yes — non-interactive consumer default: skip the prompts, install missing project-scope companions, install the dev-dependencies, run the bridge step; ships the curated consumer set only. Machine-global companions (user-scope plugins/MCP, npm -g) are skipped with a «NOT wired» notice — they need --global.
• --global — allow machine-global companion installs under --yes (user-scope plugins/MCP servers, npm -g).
• --all — everything: --yes --global PLUS the AIF operator suite (6 skills + 2 agents + their skill-context — presupposes the aif-handoff runtime; operator machines).
• --dry-run — print the full plan, write nothing.

It runs four steps:

1. Preflight — probes for bash, git, python3, curl; reports anything missing.
2. Framework — runs install.sh (file deploy only: skill, sub-agents, AI Factory templates, stack configs, husky hook files, audit script).
3. Companions — manifest-driven, detect-first, consent per companion — see below.
4. Runtime-bridge — optional guided aif-handoff setup ([y/N], default N) — see docs/runtime-bridge-setup.md.

Interactive ./setup deploys files and asks before touching your dependencies. It merges the canonical package.json scripts itself (non-destructively) and activates the shipped .husky/pre-commit + pre-push hooks itself — unless you already set your own core.hooksPath, which it leaves alone (do not run npx husky init, it would clobber the shipped hooks). It never hands you a step to do by hand: when it finishes, a «NOT wired» list names each piece it could not wire and why, and a Checked by the install: block reports what it verified — git hooks active (core.hooksPath is .husky, or .husky/_ once husky 9's prepare script has run), the result of getff's scripts/audit-ai-docs.sh (a copy the project already had is its own code, and the install does not run it), and whether dependencies were installed. A companion ./setup could not install gets a «NOT wired» line of its own at the end of the run. The non-interactive flags do not ask: -y / --yes / --full / --all run the dev-dependency install for you (setup:53 sets --full; setup.d/70-deps.sh:335 takes the install arm on it), so on a reviewed or offline machine pass no flag and answer the prompt.

The previous end-to-end wrapper setup.sh (ai-factory init + npm install + husky init + npm scripts via jq) has been retired (2026-07-10) — ./setup supersedes it. It also ran an unpinned npm install -g ai-factory; companions now install detect-first via the manifest below. If older instructions point you at bash setup.sh, use ./setup instead.

On Windows

Same command, one prerequisite: Git for Windows — it supplies the bash, git and curl the preflight above probes for. WSL is neither required nor used: the getff entry point is a Node program that finds Git Bash itself and deliberately ignores the bash on PATH, because on a WSL machine that is C:\WINDOWS\system32\bash.exe, which cannot open C:\-style paths. Set GETFF_BASH to override the search. Full prerequisites, the search order and what has and has not been measured: INSTALL.md § Windows.

As a Claude Code plugin (per-harness)

The soft layer (skills, sub-agents, session hooks) also ships as a Claude Code plugin from an in-repo marketplace:

/plugin marketplace add artyhoo/getff
/plugin install getff@getff

One install and the skills auto-trigger (a SessionStart hook injects a using-getff bootstrap — no manual Skill call), the consumer-facing sub-agents resolve, and the path-scoped rule-injector fires on edits.

The honest boundary (soft vs hard). A plugin never silently mutates your git/CI, so the plugin delivers only the soft layer. The hard layer — .husky pre-commit/pre-push hooks + the CI workflow that actually fail the build — is opt-in via one command:

/getff:install-enforcement

It previews the changes (dry-run, writes nothing), asks for [y/N], then fetches the project's own official install.sh and wires .husky + CI into the current repo. Same installer, reached honestly.

• OpenCode (and other non-CC harnesses): the same skills are portable — see .opencode/INSTALL.md. The one accepted off-CC degradation: SessionStart auto-injection does not fire, so the bootstrap skill is read on demand (a documented degradation, not a portability gap).
• Plugin vs ./setup: the plugin is the soft-layer-first path (great for "just give me the skills"); ./setup / install.sh is the full file deploy + hard layer in one shot. Both reach the same install.sh for enforcement.

As a ZCode plugin (per-harness)

ZCode installs the same plugin payload from the same GitHub marketplace — one artifact serves both harnesses:

In ZCode: Settings → Plugin Management → Discover → + (Add marketplace) → enter artyhoo/getff → install Getff from the getff marketplace section. ZCode has no plugin CLI/slash command for this (verified live, ZCode 3.11.2); the + dialog accepts the GitHub owner/repo, a git URL, or a local directory, and the Discover card's Get/Install/Update button installs or refreshes the payload.

What the plugin delivers on ZCode, and the honest boundary:

• Skills — the plugin's skills load into ZCode sessions from the installed payload; the SessionStart hook injects the using-getff bootstrap so they auto-trigger (same mechanism as CC).
• Session hooks — ZCode runs the plugin's PostToolUse gate hooks advisory-only (its schema consumes additionalContext for PostToolUse, not permissionDecision) — declared loudly by the harness renderer, not silently dropped.
• The soft/hard boundary is the same as CC — a plugin never mutates your git/CI. The hard layer (.husky + CI enforcement) is opt-in via the installer (./setup / install.sh), which is harness-independent; on CC a /getff:install-enforcement command is the convenience path to the same installer.
• Agents — ZCode's plugin system records the plugin's sub-agents but does not execute them (known harness limitation, per ZCode's own bundled plugin documentation); their markdown stays readable by any session.
• Per-hook parity detail — what works, what degrades, and why: the ZCode parity doctrine §2 census is the SSOT.
• Language (human-facing output) — ZCode has no env-block mechanism for plugin hooks and a GUI-launched app does not inherit your shell profile, so AIF_HOOK_LANG never reaches hooks there (CC reads it from ~/.claude/settings.json env). The plugin's hook wrapper falls back to a file: put one line (e.g. ru) in ~/.config/getff/hook-lang and hook messages + the output-language directive follow it on both harnesses; an explicit env var always wins (incident 2026-09-13: Russian explanations silently degraded to English on ZCode).

Optional companion install (K-1)

Companion installs run as ./setup step 3, driven by a manifest (setup.d/companions.manifest) — one row per companion (detect command, install command, kind), looped by setup.d/engine.sh:

• Detect-first: a companion that is already present is skipped.
• Consent per companion (interactive): Install <name>? [y/N] — default is N; no companion is mandatory. When stdin is not a tty (piped / CI), prompts fall through to N automatically.
• Headless: --yes / --all install missing manifest companions without prompting — project-scope companions under both; --yes alone skips machine-global companions with a «NOT wired» notice, while --all (= --yes --global) allows them and additionally ships the AIF operator suite — see Installation flags above; --dry-run prints what would be installed.
• Official installers only, no version pin — currently Superpowers via claude plugin install superpowers@claude-plugins-official, and ast-grep (structural code search: CLI via npm install -g @ast-grep/cli, then the official ast-grep/agent-skill plugin).
• External services (manifest kind external-service — the aif-handoff runtime-bridge) are not plain installs; they route to the guided-detect bridge step (./setup step 4) instead.

Each cc-plugin companion is installed via claude plugin install — this is administrative file-management (file copy + manifest registration into ~/.claude/), not an API-billed LLM call. Verified VERIFIED-FREE per Stage 2 v3 §4.8.

TaskMaster is no longer an offered companion — its marketplace plugin slug does not resolve, and the install offer was withdrawn in the one-click rework. The COMPANIONS=... env var belonged to the retired setup.sh wrapper and is gone — use the manifest + flags above.

What gets installed automatically

After the framework deploy (./setup step 2 — or bash install.sh <stack> directly), your project has:

Path	Source	Edit needed?
.claude/skills/getff/	skill + 5 references, on-demand	No — auto-activates in Claude Code
.claude/agents/ — 11 files (review-sidecar, living-docs-auditor, compliance-verifier, memory-codification-auditor, aif-init, rule-researcher, capability-reuse-auditor, docplan-auditor, claims-conformance-auditor, fidelity-auditor, rule-test-author)	sub-agents for /aif-verify (R1–R20 validation is earlier-channel: ESLint + pre-push + AIF rules-sidecar)	No
.ai-factory/skill-context/aif-review/SKILL.md, aif-rules-check/SKILL.md	overrides injected into AIF's own sidecars (anti-tautology review + R10/test-existence residue); getff owns only its fenced block, so rules /aif-evolve writes into the same file survive install and --refresh	No
.ai-factory/RULES.md	R1-R11 (or +R12-R20 for react-next)	Yes — review and trim per project
.ai-factory/DESCRIPTION.template.md + .ai-factory/DESCRIPTION.md	template with <PLACEHOLDERS>; the installer already materializes DESCRIPTION.md from it (setup.d/30-templates.sh:77, never clobbering an edited one)	Yes — fill in DESCRIPTION.md (no rename needed)
.ai-factory/ARCHITECTURE.ts-server.md	drop-in for canonical hexagonal layout	Maybe — rename to ARCHITECTURE.md if your layout matches
AGENTS.md (root)	from packages/core/templates/shared/AGENTS.md.template	Yes — review
eslint.config.mjs, vitest.config.ts, tsconfig.json, stryker.config.json, .lintstagedrc.json, .nvmrc	stack-specific configs	No — work out of the box
.husky/pre-commit,

† Layout-honesty caveat. The shipped audits (scripts/audit-ai-docs.sh / .react-next.sh, and the ci.yml that runs them) assume the canonical src/ + DDD layout. Several layout-specific probes are hardcoded to that layout, so on a non-src/ project (app/, lib/, apps/*/src/, or a flat tree) they currently report PASS while checking zero files — green that means "the rule could not run on your layout", not "the rule ran and found nothing wrong". Two concrete examples at current HEAD: R4 (packages/core/audit-self/audit-ai-docs.ts:191, probeR4) returns warn with (skipped: no src/domain — probe could not run) when src/domain is absent; R17 (audit-ai-docs.react-next.sh:86) collects no roots when src/shared/ui / src/features/*/ui don't exist and emits warn "… (skipped: no src/shared/ui or src/features/*/ui — probe could not run)" instead of scanning. So "works as-is" is accurate on the canonical layout, but a consumer on another layout must not read green from these audits as a real pass — extend or repoint the probes to your own paths first.

Manual work after install: the three project-specific items above (DESCRIPTION placeholders, RULES.md trimming, AGENTS.md review). The wiring itself — dev-dependencies, package.json scripts, git hooks — is done by the installer or, when it cannot be, listed under «NOT wired» with the reason (npx depcruise --init is not needed: .dependency-cruiser.cjs ships with the install). Typically 5-10 minutes — or zero, if you delegate it to an AI (next section).

For AI agents — let Claude/Cursor do the install

Paste the prompt from INSTALL-FOR-AI.md into Claude Code, Cursor, or any AI agent with file access in your project's directory. It is the one step list: the agent previews the install, asks you one question (where it may install), then walks every step — install, project passport draft, rule research, the project's own checks — and ends with its own report, where each step reads «done» or «not done» with the reason.

Full guide for AI-driven install: see INSTALL-FOR-AI.md.

Alternative paths

If you already have ai-factory set up or want partial install:

# Path B — only the overlay (you handle ai-factory init + npm yourself):
bash /tmp/rt/install.sh ts-server     # or react-next; --force to overwrite

# Path A — AIF extension (forward-compat, schema landing soon):
ai-factory extension add ./getff

# Path C — cherry-pick configs only (no skill, no sub-agents, no audit):
cp /tmp/rt/templates/ts-server/eslint.config.mjs .
cp /tmp/rt/packages/core/templates/shared/tsconfig.json .
# ... see INSTALL.md §C

What stack does it support?

• ts-server — Node.js 22.23+ server-only (Fastify, Hono, Express, plain HTTP).
• react-next — React 19 + Next.js 15 (App Router) + TypeScript.
• react-spa — React 19 + Vite SPA (Feature-Sliced Design). Early — ships the require-error-boundary rule; the rule-pack is still growing.
• react-native — React Native / Expo (Expo or bare-RN baseline). Experimental baseline — stack scaffold + templates; a dedicated rule-pack is not yet shipped.

Pass the stack to ./setup (or install.sh) as a positional argument — ts-server / react-next / react-spa / react-native — or omit it to get an interactive picker. All share base configs (tsconfig, husky, lint-staged, RULES R1-R11); the React stacks add R12-R20 + Storybook/Playwright where applicable.

Multi-toolchain roadmap

The stacks above are all inside the npm toolchain. The framework is being generalized one level up — from {stack} to {toolchain: npm | cargo | go | maven, …, stack} — via the Convention Compiler: a narrow-core intermediate representation plus a per-backend capability matrix (deliberately not a union "one IR fits all"). Rust/cargo is the first non-npm backend.

The Convention-Compiler rule-pack for Rust is a roadmap, not shipped — no Rust rule-pack exists yet. The cargo lane itself does ship: install.sh cargo (install.sh:166) routes to setup.d/46-cargo.sh, alongside the python and go lanes. What is in place today: the design + kickoff (docs/superpowers/specs/2026-07-03-multi-toolchain-convention-compiler-design.md), and the trust-tier system's first non-JS provenance adapter (cargo, deriving trusted doc-research hosts from Cargo.toml metadata — SSOT #197). Live cargo rule-firing needs a Rust toolchain and is not yet verified end-to-end.

Forward compatibility note on AIF extensions

The AIF extension.json schema is in active development as of May 2026 (PR #34 in lee-to/ai-factory, Draft state). This package ships:

• extension.json — best-effort manifest matching what's visible in AIF code today
• install.sh — guaranteed fallback that does not depend on AIF extension support

When the schema finalizes, extension.json may need updates. install.sh will continue to work regardless.

Compatibility

The framework is AI-agnostic by design — any harness with a CC-compatible hook system works. Per-hook coverage and dogfood depth vary; the doctrine lives at .claude/rules/zcode-parity-doctrine.md.

Supported today:

• Claude Code — primary dogfood harness; deepest coverage (hook-by-hook census: doctrine §2).
• ZCode — full parity via plugin channel + _zcode-emit helper; consumers install from the same GitHub marketplace (see «As a ZCode plugin» above). Four CC-only events (SubagentStart, SubagentStop, WorktreeCreate, PreCompact) have documented fallbacks or accepted CC-only rationale per the doctrine §4.
• Codex CLI — bounded native hook adapter: consumer installs deliver project-local .codex/hooks.json plus the shared adapter, its entry-point dependency and language resolver; definitions derive only from the registered, delivered framework checks, activation requires project and exact-definition trust via Codex /hooks (never granted by the install), and missing Node or customized definitions produce an explicit not-wired notice (docs/codex-contributor.md).
• Cursor — high CC-overlap (native SubagentStart/Stop, lifecycle hooks). Listed based on docs-verification in the S8 agnosticism survey; live end-to-end testing is a follow-up.

Roadmap (FEASIBLE-WITH-WORK — adapter needed):

• Windsurf — Cascade Hooks present; taxonomy adapter needed.

Out-of-scope:

• Aider — no hook system (upstream issues aider#2045, aider#2557).

Wave B rollout status: Stages 5 (warn-subagent-report ZCode variant), 6 (9-twin migration + generator), 7B (inject-subagent-context extension for full SubagentStart payload parity), 9C (end-of-turn-reminder ZCode multi-turn arm) are merged (#1043/#1044/#1046/#1047). Live per-stage status lives in the doctrine §3 — cited here rather than restated, so this line cannot drift from the census.

Verified versions (May 6, 2026)

All versions in INSTALL.md §4 were verified via npm view <pkg> version on installation date. Re-verify before deploying to your project — versions move.

What's enforced

The complete rule list (R1–R20):

Base (R1–R11) — server TS:

• R1 TypeScript hygiene (no any, no !, no enum)
• R2 Validation at boundaries (Zod)
• R3 Architectural boundaries (layered)
• R4 Tests for new public code (real assertions only)
• R5 Async correctness (no floating promises)
• R6 Errors (Error subclasses, no string throw)
• R7 Time/randomness/IO injection
• R8 Observability (OTel spans)
• R9 Imports (banned: lodash, moment, axios)
• R10 Naming conventions
• R11 CI integrity

React/Next addition (R12–R20):

• R12 Server vs Client components
• R13 Data fetching (RSC / Server Actions / TanStack Query)
• R14 Forms (Server Actions with Zod)
• R15 Accessibility (jsx-a11y/strict)
• R16 Performance (next/image, next/link)
• R17 Component tests (Storybook + Vitest + a11y)
• R18 TanStack Query / SWR (typed responses)
• R19 Styles (Tailwind, no CSS-in-JS)
• R20 Server Actions ('use server', return type pattern)

Microservices (IR1–IR6):

• IR1 API contracts (OpenAPI from Zod)
• IR2 Consumer-driven contracts (Pact + can-i-deploy)
• IR3 Event schemas (Zod-validated)
• IR4 Service-to-service auth (mTLS / signed JWT)
• IR5 Distributed tracing (W3C Trace Context)
• IR6 Resilience (timeouts, retries, circuit breakers)

Lessons learned included

references/ai-traps.md ends with 23 real-world lessons from running AI-driven projects, among them:

1. Dual-remote projects — .claude/ in .gitignore of work-repo (drift symptom)
2. Skills declared early, never created (skill-fantoms)
3. _comment_TODO in JSON outlives everything
4. Stale orchestrator-prompts pile up indefinitely
5. AGENTS.md tables drift faster than the body
6. AI silently demotes "MUST" to "should"
7. Trigger overlap between two skills
8. Rules without measurable check decay

Each lesson includes the rule that came from it — typically a specific check in audit-ai-docs.sh.

Updating

ai-factory extension update getff                   # Path A
./install.sh <stack> --force                        # Path B (overwrites configs)
# Path C: cherry-pick changes manually

License

Source-available, not permissively licensed — said here first, not left for someone else to point out. Licensed under the Functional Source License, Version 1.1, Apache 2.0 Future License (FSL-1.1-ALv2). Use, copy, modification, and redistribution are permitted for any Permitted Purpose — internal use, non-commercial education, and non-commercial research — but Competing Use (offering a product or service that substitutes for or provides substantially the same functionality as this software) is not.

Why FSL instead of MIT/Apache from day one: a single-maintainer project competing against well-funded forks of its own code has no recourse under a permissive license. FSL keeps the Competing-Use restriction only while the project needs it — read source, self-host, use internally, all permitted from day one.

Each version automatically converts to Apache License 2.0 on the second anniversary of its release — so this restriction has a hard expiry, not an open-ended one. See LICENSE.md for full terms.

Inspirations & sources

This package synthesizes:

• "Rules as Tests" framework — five-layer principle
• Senko Rašić's two-AI review pattern (review-sidecar)
• Charity Majors' observability 2.0 (production-side rules)
• Gojko Adzic's Specification by Example (Layer 3)
• Cyrille Martraire's Living Documentation (Layer 5)
• Ian Robinson's Consumer-Driven Contracts (Pact, integration rules)
• Larry Smith's shift-left testing (2001)
• AI documentation drift practices from ai-docs skill (real-project applied wisdom)
• Negative test pair pattern as lightweight mutation testing

Full citations in each references/*.md file.