V4.3 addresses the gaps V4.2 surfaces: no data on whether commands are being used, no repeatable way to verify the Forgeflow team is installed correctly, and no compact release path for smoke checks, pilot evidence, and clean-checkout validation. The release ships Observability, Integrity, Cross-Project Memory, plugin packaging, stabilization smoke automation, maintainer pilot scripts, and topology/report hardening. The guiding rule: before adding more surface area, know what’s installed, what’s working, and what’s ready for a maintainer to run.
-
hooks/forgeflow-telemetry.js — PostToolUse event recorder
Records Forgeflow events to ~/.claude/projects/<sanitized-cwd>/memory/forgeflow-metrics.jsonl. Captured events: verdict (APPROVE / REVISE / BLOCK from Arbiter, CONFIRM / CHALLENGE from Compass), auto-fix-applied (per-worker SUCCESS or abort-reason from /review-auto), auto-fix-round (via chore(auto-fix): round N commit detection), fleet-shard-complete (via worktree removal detection), command-invoked for /handoff (.claude/handoff.md writes) and /ui-iterate (ui-iterations report writes). Every event carries ts, session_id, project, cwd. Fail-open on any I/O error — the hook never blocks tool use.
-
/forgeflow-metrics — summarize usage from telemetry
Aggregates across all forgeflow-metrics.jsonl files with period filter (week / month / all) and per-project filter. Produces invocation counts, verdict distribution, /review-auto rounds-to-APPROVE histogram + worker success rates, /fleet shard completion counts, top projects by invocation + REVISE rate. Interprets the numbers in a Signals section: closed-loop effectiveness (percent of REVISEs closed in 1 auto-fix round), command adoption rates, verdict churn signals. --json flag for structured output; absent telemetry shows a clear “nothing to summarize yet” with wiring instructions.
-
/forgeflow-health — installation integrity audit
Checklist-style audit of the 29 canonical agent files, 21+ commands, 3 hooks, 2 project-rules, 4 forgeflow-patterns, templates, settings.json validity, hook wiring, project-local .forgeflow/ state, version drift against upstream SHA, and gh auth active account. --fix auto-repairs safe issues (creates missing dirs, adds .forgeflow/ to .gitignore). Never mutates settings.json — always directs user to manual fix for hook wiring drift. Default output is failure-focused; --verbose includes passing checks.
-
.claude-plugin/plugin.json — plugin manifest
Declares version 4.3.0, author, homepage, keywords, and component directories (agents, commands, hooks, templates, project-rules, forgeflow-patterns). install.destinations map each source directory to its target under ~/.claude/. install.preserve protects custom-* agents from being overwritten. install.post-install documents which hooks need manual wiring into settings.json PostToolUse.
-
.claude-plugin/marketplace.json — marketplace entry
Exposes the repo as ForgeflowAI marketplace with a single plugin entry pointing at github:ForgeflowAI/Forgeflow. Users add via claude plugin add + claude plugin install instead of manual curl + copy.
-
README Installation — Option A (plugin) + Option B (manual)
Plugin install is the recommended path for fresh setups: two commands install the entire Forgeflow. Manual setup remains documented as Option B for users who want per-file control. Both paths converge on the same hook-wiring step (settings.json PostToolUse).
-
New
forgeflow-patterns/ directory (4 seeded files)
Patterns that recur across 2+ projects get promoted from per-project .forgeflow/<project>/agent-notes/ to the global ~/.claude/forgeflow-patterns/ library. Seeded from review data across campaign-management (288 learning lines / 27 rounds), llama.cpp (54 / 243), and SubAgents (173 / 808) projects — total 515 labeled learning lines. Tier A (domain): three classes identified — type safety / schema mismatch, unimplemented-but-promised features, null-safety + error-path gaps — each with citations, severity classification, plan/implement/review-time checks. Tier B (tooling): agent mode-specificity, cold-start edges, output routing gaps, prescriptive-vs-descriptive rule enforcement.
-
verdict-trends.md — distribution patterns by project type
Schema-heavy projects run BLOCK 35% / REVISE 45% / APPROVE 20%; low-level systems projects run BLOCK 25% / REVISE 30% / APPROVE 45%; agent-tooling projects run high REVISE churn with low BLOCK rate. Anomaly patterns included: first-pass APPROVE on schema change is suspicious (reviewer likely missed consumers); REVISE loop that doesn’t converge is design-level, should de-escalate to /consult; BLOCK on agent tooling is rare and load-bearing — avoid /review-auto.
-
auto-fix-patterns.md — classifier decision flow
Defines which finding classes route to NIT (95% worker success — formatting, unused imports, missing returns), MUST-FIX-SAFE (80% success — null guards, missing await, type narrowing), MUST-FIX-RISKY (always surface — Warden-flagged, multi-file, reviewer uncertainty), BLOCKER (always surface with recurring-blocker class reference). Decision flow encoded for /review-auto Step 2. Includes a telemetry-driven refinement plan: success-rate thresholds that promote / demote classes, triggered by /forgeflow-learnings (future) reading accumulated metrics.
-
Atlas agent updates — global pattern awareness
All three Atlas review-cycle files updated.
atlas-early.md (discuss/research/plan): loads context from both .forgeflow/<project>/ AND ~/.claude/forgeflow-patterns/; cites matching patterns by name during planning so issues are preempted. atlas-consult.md: checks recurring-blockers.md and tooling-patterns.md at consult start. atlas-review.md: references matching global patterns in the review output, strengthening the receipt for challenges and teaching the pattern simultaneously.
-
/update-forgeflow extended sync coverage
Adds forgeflow-patterns/*.md to both first-run and incremental sync modes, with destination ~/.claude/forgeflow-patterns/. Includes hooks/forgeflow-telemetry.js in the tracked hook list so the new telemetry hook is pulled on every update. Without these additions, fresh installs would miss the pattern library and the telemetry recorder.
-
/forgeflow-smoke and smoke-check.js — one local stabilization check
Runs health, trends refresh, report refresh, code map, doc links, and release-version guards in one pass. The helper emits Markdown or JSON, reports pass/warn/fail per check, resolves stale latest-insights recommendations when the same run refreshes them, and keeps warnings actionable instead of failing informational fixture/test import gaps.
-
/forgeflow-pilot and render-pilot-script.js — bounded maintainer trial script
Prints a repeatable pilot path for Claude Code or Codex: install verification, baseline smoke, trends, report, code map, one bounded work item, final report, pilot evidence recording, rollup, and a public-safe result template. This lets a maintainer run one real trial without assembling steps from the full wiki.
-
Import-gap hardening for project trends, report, and smoke
Code maps still show every unresolved and skipped dynamic import, but each gap is classified as production or test/fixture scope. Trends, report, and smoke now escalate production-scope gaps while leaving test/fixture-only gaps visible as informational context.
-
Clean-checkout release verification
Verified a fresh checkout at the release commit, disposable Claude and Codex template installs, installed helper health with project-local repair, clean smoke, and the full release-check test list. Generated local state remains under ignored
.forgeflow/ paths.
-
Decision gate: 3+ real
/fleet runs per month triggers the build
Phase 4 — extending /fleet to handle phases spanning multiple workspaces in a monorepo (pnpm workspaces, turbo.json, nx.json, lerna) — was designed but NOT shipped. The decision gate: build only if Phase 1 telemetry shows /fleet used on at least 3 refactors per month. Rationale: /fleet is the most complex existing command and the riskiest to extend; the community pattern (5-30 shards with worktree isolation) is aspirational but may not match actual usage. Reassess in 4–6 weeks once forgeflow-metrics.jsonl has data.
-
Parked items
Explicitly not building in V4.3: cost estimator (waiting for Anthropic stable token-cost API), SDK-backed command rewrites (markdown templates still scaling fine), multi-account Forgeflow variants (complexity without clear payoff).