forbee-dev · forbee-dev · Aug 11, 2026 · Aug 11, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -9,7 +9,7 @@
       "name": "forgebee",
       "source": "./forgebee",
       "description": "Full-stack agent framework for Claude Code, Codex, Cursor, Gemini — 37 slash commands, 44 specialist agents, 33 skills, 25 hooks. Karpathy principles (trace test, YAGNI, orphan rule, anti-stop) on every code agent. Adversarial debate triads, two-stage review (spec compliance + code quality), forensic /investigate, /elicit (18 reasoning methods), checkpoint-preview, budget circuit breaker, adversarial input hardening, continuous learning with auto-nudge, Growth OS marketing pipeline, automated PM, /audit-self regression detection.",
-      "version": "5.3.1"
+      "version": "5.4.0"
     }
   ]
 }
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "forgebee",
-  "version": "5.3.1",
+  "version": "5.4.0",
   "description": "Full-stack agent framework — 37 slash commands, 44 specialist agents, 33 skills, 25 hooks. Karpathy principles on every code agent, adversarial debate triads, two-stage review, /investigate, /elicit (18 methods), checkpoint-preview, budget circuit breaker, continuous learning, Growth OS, /audit-self.",
   "author": {
     "name": "Forbee Dev",

diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json
@@ -2,7 +2,7 @@
   "name": "forgebee",
   "displayName": "ForgeBee",
   "description": "Full-stack agent framework — 37 commands, 44 specialist agents, 33 skills, 25 hooks. Karpathy principles, adversarial debate, two-stage review, /investigate, /elicit, checkpoint-preview, budget circuit breaker, continuous learning, Growth OS, /audit-self.",
-  "version": "5.3.1",
+  "version": "5.4.0",
   "author": {
     "name": "Forbee Dev",
     "url": "https://github.com/forbee-dev"

diff --git a/.version-bump.json b/.version-bump.json
@@ -11,6 +11,11 @@
       "path": "README.md",
       "regex": "version-([0-9]+\\.[0-9]+\\.[0-9]+)-blue",
       "replacement": "version-{VERSION}-blue"
+    },
+    {
+      "path": "forgebee/README.md",
+      "regex": "## Key Features \\(v([0-9]+\\.[0-9]+\\.[0-9]+)\\)",
+      "replacement": "## Key Features (v{VERSION})"
     }
   ],
   "audit": {

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -21,9 +21,9 @@ see [`CONTRIBUTING.md`](./CONTRIBUTING.md).
 
 | Surface | Location | Loaded |
 |---------|----------|--------|
-| Agents (44) | `forgebee/agents/*.md` | dispatched via `Task` by orchestrators |
-| Skills (33) | `forgebee/skills/*/SKILL.md` | activated by name / `skill-activator` |
-| Commands (37) | `forgebee/commands/*.md` | `/name` slash invocation |
+| Agents (45) | `forgebee/agents/*.md` | dispatched via `Task` by orchestrators |
+| Skills (34) | `forgebee/skills/*/SKILL.md` | activated by name / `skill-activator` |
+| Commands (38) | `forgebee/commands/*.md` | `/name` slash invocation |
 | Shared contracts | `forgebee/skills/_review-finding-contract.md`, `_debate-protocol.md` | imported by review/debate skills |
 
 ## Hooks (Claude Code only)

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,40 @@ The format roughly follows [Keep a Changelog](https://keepachangelog.com/) and t
 
 ---
 
+## [5.4.0] — 2026-08-11
+
+**Minor: routing actually fires, and a design-system trio arrives.** ForgeBee shipped 114 surfaces that were effectively unreachable. Five defects, each verified by direct hook test, explain why a WordPress task never reached a `wordpress-*` agent.
+
+### Fixed — the routing path
+
+- **`load-index.js` emitted the entire 20,599-byte `INDEX.md` as `additionalContext`.** The harness rejects an oversized payload, persists it to a file, and injects only a ~2KB preview. Every section past that point — including the whole WordPress agent roster, which starts at byte 7335 — never reached the session. It now emits a digest: the Quick Triage table plus the stack section matching `project-triage.json`, 1.2KB on a node repo and 2.1KB on a WordPress repo, with a hard 3.5KB ceiling and a pointer to read the full file.
+- **`skill-activator.js` emitted a top-level `additionalContext`.** `UserPromptSubmit` requires `hookSpecificOutput.additionalContext`. The hook exited 0 with valid JSON and correct content, and the harness discarded all of it — a silent failure with no error surface. This is why skill recommendations never appeared.
+- **The activator scanned only skills.** All 45 agents and all 38 commands were invisible to it, so no agent or slash command could ever be recommended. It now builds one manifest across skills, agents, and commands.
+- **Matching had a 5-character floor on description words**, which silently excluded every high-signal acronym in the domain — ACF, SCF, SEO, API, RLS, CPT, TDD. Floor lowered to 4, plus a dedicated acronym pass that reads capitalisation from the source description before lowercasing, weighted higher than an ordinary word.
+- **Recommendations were unranked and unbounded** — 13 undifferentiated "Consider…" lines per prompt. Now scored (name tokens 3, acronyms 2, description overlap 1, explicit triggers 6, plus a stack boost from detected project type), floored at 3, deduped so a command does not repeat its same-named skill, and capped at 5.
+
+Also fixed: frontmatter values kept their surrounding quotes, which leaked into output as `\"…\"`, and the payload flattened every newline into a space.
+
+### Added
+
+- **`figma-code-sync` skill** — code-first reconciliation of a Figma design system against the code that ships. Carries THE ONE LAW (code is the source of truth; Figma is derived, never approximated from a screenshot), a three-tier free-check pass that needs no source access, 12 defect priors each paired with the counter-case that makes blind application dangerous, ~18 Figma Plugin API traps (including Figma's counter-clockwise-positive `rotation` against CSS's clockwise, and `mainComponent.name` returning the variant while the set name is `mainComponent.parent.name`), absence/census hygiene, and record-keeping rules — one audit file per writer, never shared between concurrent writers.
+- **`wp-design-system` agent** — WordPress block design systems. Resolves layer ownership first: core blocks take `theme.json` presets, custom blocks take their own stylesheet, and the two collide by name with different values. Covers the token pipeline in both directions, a cost-ordered choice between pattern / synced pattern / style variation / custom block / Block Bindings, and saved-content safety via deprecations.
+- **`/design-system` command** — `audit`, `onboard`, or `tokens`, with a documented context load order that stops when a project-level design-system skill is missing rather than improvising a file key. Audits parallelise across pages, never across writers of one file.
+- **Routing Discipline R1–R4** in `CLAUDE.md` — name the route in one line before the first edit, prefer the stack-specific surface over the generic one, read `INDEX.md` rather than guess, and treat hook candidates as input rather than orders.
+- **`findAgentsDirs()`** in `hooks/scripts/_common.js`, mirroring `findSkillsDirs()` for flat `<name>.md` agent files.
+
+### Changed
+
+- **`wordpress-backend` is now an ACF/SCF field-architecture specialist.** It previously held retrieval patterns only. Adds field-group registration (`acf_add_local_field_group` versus JSON sync), immutable field keys and why changing one orphans every value, the real meta storage shape — one field is two rows, and a Repeater flattens to `name_<i>_<sub>` so it **cannot** be `meta_query`'d — `update_field` versus `update_post_meta`, meta-cache priming for the archive N+1, validation hooks, REST exposure with schema, and an ACF-PRO-to-SCF migration risk table. Plus 6 new failure modes and 3 new escalation triggers.
+- `forgebee/README.md` is now tracked in `.version-bump.json`; its `## Key Features (vX.Y.Z)` heading was drifting outside the declared set.
+- Documentation counts corrected across `README.md`, `forgebee/README.md`, and `ARCHITECTURE.md`. The inline/fork skill split in `forgebee/README.md` was already wrong before this release (`11 + 22` against an actual 21 fork skills) and now reads `13 inline + 21 context:fork`.
+
+### Known limitation
+
+The activator's stack boost depends on `project-triage.json`. On a repo triaged as something other than WordPress, a WordPress-flavoured prompt still routes correctly but ranks below generic name-token matches such as `/audit`.
+
+---
+
 ## [5.3.1] — 2026-06-12
 
 **Patch: the `checkpoint` hook is revived and wired.** Follow-up to 5.3.0.

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -46,6 +46,18 @@ Apply to every search / discovery / Bash call by any agent or orchestrator. Unbo
 
 **T5 — Background or cancel after 60s.** If a discovery command hasn't returned in ~60 seconds, it's almost certainly stuck on a vendored subtree — background it (`ctrl+b`) or cancel and re-scope. Never silently wait past 2 minutes for what should be sub-second work.
 
+## Routing Discipline (always apply)
+
+ForgeBee ships 117 surfaces. They are worthless if nothing consults them. Apply before the first Edit, Write, or Bash call of any task.
+
+**R1 — Name the route first.** Open non-trivial work with one line: `Route: <surface> — <reason>`. If no surface fits, write `Route: direct — no matching surface`. One line, no ceremony. Skip it only for pure conversation and one-line mechanical edits.
+
+**R2 — Prefer the stack-specific surface.** `wordpress-backend` beats `backend-engineer` on a WP plugin. `nextjs-frontend` beats `frontend-specialist` in a Next.js app. `supabase-specialist` beats `database-specialist` on Postgres + RLS. The generic agent is the fallback, not the default.
+
+**R3 — Read the index, do not guess.** `forgebee/INDEX.md` is the full directory of skills, agents, and commands. SessionStart injects only a digest — the Quick Triage table plus this project's stack section. When routing is unclear, `Read` the full file. Never assert that a surface does not exist without checking.
+
+**R4 — Hook candidates are input, not orders.** `skill-activator.js` scores candidates on every prompt and lists the top 5. Its top hit can be wrong. Choose or reject it explicitly in the R1 line.
+
 ## Agent Output Modes
 
 **Orchestrator mode (terse):** When a specialist agent is dispatched by `/workflow` or `/team`, the handoff contract carries `responseStyle: "orchestrator"`. In this mode, agents emit telegraphic reports — drop articles/filler, preserve code/citations/paths exact, prefer bullet lists. See `forgebee/skills/terse-report/SKILL.md`. Cuts ~65% of report tokens.
@@ -143,6 +155,7 @@ npm run deploy:production # Deploy to production
 - `/deploy` — Deployment with pre-flight checks, rollback plan + anti-rationalization gate
 - `/browser-debug` — Client-side debugging (console, network, rendering)
 - `/codemaps` — Token-lean architecture documentation for AI context consumption
+- `/design-system` — Design system operations: `audit` a Figma page against code, `onboard` a new component, or audit `tokens`. Loads `figma-code-sync` (code-first law + Figma API traps); dispatches `wp-design-system` for theme.json/SCSS layer ownership
 
 **Stress-test & Quality:**
 - `/elicit [method-name]` — 18 named reasoning methods (`pre-mortem`, `red-team`, `inversion`, `stakeholder-round-table`, `tree-of-thoughts`, …) applied to the most recent plan/design/decision
@@ -183,7 +196,7 @@ npm run deploy:production # Deploy to production
 
 *Growth OS:* brand-strategist, market-intel, audience-architect, content-strategist, hook-engineer, engagement-strategist, content-creator, growth-engineer, marketing-analyst, email-strategist
 
-*WordPress:* wordpress-backend, wordpress-frontend, wordpress-content, wordpress-security, wordpress-seo, phpunit-engineer, woocommerce-cro
+*WordPress:* wordpress-backend, wordpress-frontend, wordpress-content, wordpress-security, wordpress-seo, phpunit-engineer, woocommerce-cro, wp-design-system
 
 *Next.js:* nextjs-frontend, nextjs-content, nextjs-seo
 
@@ -195,7 +208,7 @@ npm run deploy:production # Deploy to production
 
 *Discipline skills (5.1.0):* brainstorming (opt-in hard-gate), elicitation (18 methods), surface-ambiguity (silent-pick guard), terse-report (sub-agent token compression), checkpoint-preview (diff-by-concern), investigate (forensic case file), audit-self (regression detection)
 
-**Routing index:** `forgebee/INDEX.md` is auto-generated by `scripts/build-index.js` and loaded on SessionStart. It maps user intent → the right skill/agent/command. Regenerate after any skill/agent/command add or remove.
+**Routing index:** `forgebee/INDEX.md` is auto-generated by `scripts/build-index.js`. SessionStart injects a digest of it (Quick Triage + the detected stack's agents) — the full 20KB file exceeds the `additionalContext` size limit and would be dropped, so `Read` it directly when the digest is not enough. It maps user intent → the right skill/agent/command. Regenerate after any skill/agent/command add or remove.
 
 **Quality Pipeline:** All commands have Objective + Never rules. All code-producing agents self-review against review-all criteria before reporting `DONE`. Agents report status: `DONE`, `DONE_WITH_CONCERNS`, `BLOCKED`, or `NEEDS_CONTEXT`. `/workflow` runs Spec Compliance Check → Checkpoint Preview → Code Debate → Deliver. review-all is the final validation gate — only Critical/High issues block the push.