Changelog

Added

• Native Cursor and Codex packaging — sync .cursor-plugin/plugin.json to Claude version/counts and wire skills / agents / commands / hooks (hooks/hooks-cursor.json) / MCP; add .codex-plugin/plugin.json plus root .agents/plugins/marketplace.json so Codex can install from this repo without the Bun CLI. Native Codex surface is skills + MCP + safety hooks (agents/commands stay on Bun --to codex).
• Cross-platform hook contracts — Cursor safety hooks now fail closed, and the Slack credential guard understands Codex's canonical apply_patch payload while scanning only newly added lines in non-documentation files.
• Cross-harness safety hook adapters — hooks/hooks-cursor.json (Cursor beforeShellExecution + Write preToolUse) and hooks/hooks.json (Codex ${PLUGIN_ROOT}) ship block-no-verify, prevent-main-commit, block-slack-webhook, and block-db-push. Shared scripts/hook_payload.py normalizes Cursor payloads into the Claude shape. Nudge / SDD-cache / TodoWrite / Stop tracker hooks remain Claude-primary (documented in scripts/HOOKS.md harness matrix).
• Manifest parity CI — tests/plugin-consistency.test.ts asserts Claude / Cursor / Codex plugin versions match and required packaging + hook config files exist, with script-path existence checks for Cursor/Codex hook entries.

Added

• Sub-issue status is now a first-class, stakeholder-readable track. Sub-issues decompose a parent and roll up into the *parent's* PR, so they never earn their own in_review/shipped board stage — which left them with only open/closed as visible state, too coarse for a business stakeholder to read "what is happening right now." The lifecycle engine gains a --sub-status <N> <in_progress|in_review|blocked|done> verb that drives a mutually-exclusive status:* label (status:in-progress / status:in-review / status:blocked; done strips every status:* label and closes the issue as completed — an orchestrator close, not a PR auto-close). Labels are repo-scoped, so the verb needs no board and runs in github mode too, self-creating its labels with colors that mirror the stage palette. The invariant — at most one status:* label per issue — is enforced by the verb (a swap, not an add) and covered by seven new cases in tests/lifecycle_board_test.py. Defined in the lifecycle skill (new *Sub-issue status* section + one-writer table row) with the concrete gh calls in references/gh-recipes.md.
• Seam gate + drift flag against status snowballing. Because agents don't deterministically do the right thing, the lifecycle now *verifies a predecessor step finished before allowing the next transition*, at the one seam where a mistake gets buried: --set-status <N> in_review refuses (error_code: open_sub_issues) when the parent still has open sub-issues — enforcing in the engine what /workflows:work Phase 4 only stated in prose, so an agent that skips the checklist can't mark a parent ready-for-review and let the merge → shipped automation quietly ship unfinished decomposed work. The reconciler and deliberate operator/CI moves pass through with --force; a new report-only reconciler flag in_review_with_open_subissues catches parents that reached that state via a forced/out-of-band path (rule-5 reality-sync, a human drag). Both use data already fetched (no extra queries) and are covered by six new tests. Deliberately scoped to this one high-value seam — sub-issue label-residue scans and board-wide audits were assessed as overkill.
• /lifecycle-doctor now verifies the one native automation the lifecycle depends on — the built-in "Item closed" Projects workflow is the sole writer of → shipped (no engine verb owns it), so a human silently disabling it means merged PRs close issues but Status never advances to shipped. The doctor gains an item_closed_workflow check (via a new project_workflows API reader) that FAILs if it is off — bootstrap only checked it once at setup; the doctor now re-checks every run. GitHub's Projects API exposes only a workflow's name/enabled (never its action config) and no enable/create mutation, so enabled is the one bit that can be verified.

Added

• documentation-health gains first-class GitHub Actions support. A new example workflow (assets/doc-health.yml) ships two independent tiers: a deterministic scan gate that fetches the zero-dependency scanner at a pinned ref, and an opt-in audit job that runs the skill inside anthropics/claude-code-action for the agent-in-the-loop judgment pass (duplication, Diátaxis mode-mixing, stale commands, README↔CLAUDE.md drift). The audit posts its review *as Claude* (the Claude GitHub App identity) and is propose-only yet blocking: it never pushes to a protected branch, but emits a --json-schema structured output and fails the check on a judgment-confirmed must-fix, so a real problem blocks merge while scanner false positives don't. The skill is dogfooded on this very marketplace via live repo workflows (.github/workflows/doc-health.yml).
• Manifest-version-triggered release automation (.github/workflows/release.yml): on push to main, reads the plugin version and cuts an immutable v<version> tag + GitHub Release (notes from the CHANGELOG) when it's new. Chosen over release-please/conventional-commits because the repo already hand-bumps the manifest and maintains the changelog under test — those tags are what the doc-health workflow and external consumers pin to.
• One-click adoption via /setup. The setup skill gains a "Docs CI" step that installs .github/workflows/doc-health.yml into the target repo and walks through enabling the agent tier — generate a CLAUDE_CODE_OAUTH_TOKEN (Pro/Max subscription, via claude setup-token) or ANTHROPIC_API_KEY secret, install the Claude GitHub App, and mark the checks Required. The scan gate needs no secret; the audit tier accepts a subscription token (pass exactly one credential — an empty second one breaks auth). Reciprocal pointers in the skill and README make the path obvious from either entry point, and both READMEs now route install → /setup with a "Configure" step so the capability surfaces through the marketplace's config flow rather than sitting behind a skill users must already know to invoke.

Added

• New block-db-push.py PreToolUse hook — blocks prisma db push (and its npx/pnpm/dotenv wrapper forms plus pnpm --filter <pkg> push script aliases) before it runs. db push mutates the live database to match schema.prisma *without* writing a migration, silently drifting the schema from the migration history; that breaks tests which apply migrations from scratch and means CI/CD and production (which deploy by running migrations) never receive the change. This is the DB-safety sibling of the existing prevent-main-commit / block-no-verify git guards, and it is inert unless a project actually runs prisma db push, so non-Prisma repos pay nothing. Precision-guarded (quote-stripped so prose/grep/echo mentions and legitimate migrate dev / migrate deploy / generate commands are never blocked) and covered by tests/block_db_push_test.py. Documented in scripts/HOOKS.md. Adapted from the first-party agent-leverage / bluestar-intel repos. Component counts (agents/commands/skills) unchanged — hooks are not counted.

Added

• New acceptance-criteria-reviewer agent — a focused reviewer whose sole job is to hold a change against the documented Acceptance Criteria and Validation steps of its tracker issue, criterion by criterion, and emit a PASS / FAIL / INCOMPLETE verdict with file:line evidence. It deliberately ignores code style, security, performance, and architecture (other agents own those) — the narrow scope and separate context window are the point: an independent verifier, not the author, decides whether "done" is actually done. A criterion is met only when the diff demonstrably makes it true; "can't tell" and "CI is green but no test covers the criterion" both count as *not met*. Review agent count 16 → 17; total agents 30 → 31.

Added

• Canonical issue and sub-issue body templates for the eng workflow — scripts/templates/issue-template.md (parent) and scripts/templates/sub-issue-template.md (task unit) codify best-practice structure with standard sections: Overview, Problem Statement / Context, Proposed Solution / Implementation Notes, Scope, System-Wide Impact, External System Wiring, Task Breakdown, Acceptance Criteria, Validation (how a reviewer proves it *behaves*, not merely compiles — exact commands + expected result, plus manual and rollback steps), and Dependencies & Risks. /workflows:plan Step 7 now copies the sub-issue template for every <task_body_file> it creates under a parent, so decomposed tasks share one standard shape instead of an undefined ad-hoc body.

Added

• New /workflows:groom command — the grooming segment of the pipeline as a first-class flow, supporting the standard bifurcated workflow (intake → groomed work; groomed work → implemented work). It drives an idea, bug report, or stub issue through brainstorm → plan and stops once the work is groomed: Status planned on the board, a join-keyed plan doc, and sub-issues with dependencies — exactly the bar /workflows:work's entry gate enforces before a claim. Autonomous by default with a decision log (--steer for an interactive grooming session), idempotent on already-groomed items (re-runs report and stop; later stages are never re-groomed or regressed), provenance-gated for outsider-authored issues, and hard-stopped: it never claims, never branches, never writes product code, never opens a PR. It owns no lifecycle transition of its own — it sequences the existing /workflows:brainstorm and /workflows:plan writers and reads state through the orchestrate gate (a pure state read), so the one-writer-per-transition table is unchanged. Bug reports get grooming-specific handling: optional reproduction validation via bug-reproduction-validator when cheap and side-effect-free, with "can't reproduce" treated as a legitimate grooming outcome rather than a failure. Command count 27 → 28.

Added

• New documentation-health skill — audits and repairs the informational health of a repository's documentation across all six layers (root & nested CLAUDE.md, root & nested README.md, internal-facing docs, external-facing docs). It encodes cited best practices — Anthropic's CLAUDE.md memory guidance (~200-line ceiling, no drifting counts, @import vs on-demand loading), the Standard-Readme required-section spec, Diátaxis mode-separation, docs-as-code hygiene, and GitHub community-health/ADR/CODEOWNERS conventions — as a concrete rule set anchored by one principle: *any fact that lives elsewhere (a count, version, date, command) must be referenced or generated, never hand-copied.* Ships a Discover → Audit → Report → Repair → Codify workflow (SKILL.md), a full cited per-layer checklist (reference.md), and a zero-dependency Python scanner (scripts/doc_health_check.py) that runs on any repo and shells out to lychee/doctoc/markdownlint when present. Skill count 34 → 35.

Added

• doubt-driven-development skill — in-flight adversarial review of non-trivial decisions, adopted and adapted from addyosmani/agent-skills. Where verification-loop and /workflows:review are post-hoc gates on a finished artifact, doubt-driven is an in-flight posture: it materializes a fresh-context reviewer — biased to disprove, not approve — before any non-trivial decision stands. The loop is CLAIM → EXTRACT → DOUBT → RECONCILE → STOP: name the decision and why it matters, extract the smallest reviewable artifact + contract, hand the reviewer ARTIFACT + CONTRACT but never the CLAIM (passing the conclusion biases toward agreement), then classify every finding in strict precedence (contract-misread / valid-actionable / valid-trade-off / noise) and stop on trivial findings, a hard 3-cycle bound, or user override. Includes a "doubt theater" checkable signal (two+ cycles of substantive findings with zero classified actionable = validating, not doubting), rationalization/red-flag tables, and a heavily-gated cross-model escalation protocol (read-only sandbox, prompt piped via stdin not argv, explicit per-invocation user authorization, announced skips in non-interactive contexts). Retargeted to local components: the fresh-context reviewer roster points at the agentic-engineering review agents (security-sentinel, architecture-strategist, code-simplicity-reviewer, integration-boundary-reviewer, pattern-recognition-specialist, the kieran-* reviewers) spawned per orchestrating-swarms; docs-fact verification points at the context7 MCP; the post-hoc counterpart is /workflows:review + verification-loop; TDD's RED step (test-driven-development) is doubt made concrete for behavioral claims, with test-strategy-reviewer covering coverage quality at review time; reviewer-surfaced failure modes hand off to debugging-and-error-recovery. Provenance pinned in docs/upstream-sources.md. Skills 33 → 34.

Added

• api-and-interface-design skill — design-time contract authoring for REST/GraphQL endpoints, module boundaries, component props, and type contracts (adopted from addyosmani/agent-skills, skills/api-and-interface-design/SKILL.md@4e8bd9fd, adapted). Fills a genuine gap: the plugin's architecture-strategist and integration-boundary-reviewer agents both inspect an interface *after* the code is written, and nothing local covered shaping a contract *before* it exists. The skill carries the upstream's Hyrum's Law framing (every observable behavior — error text, timing, ordering — becomes a de facto contract once someone depends on it), the One-Version Rule, branded types for IDs (type TaskId = string & { readonly __brand: 'TaskId' }), discriminated-union status modeling, input/output type separation, the HTTP status-code and naming-convention tables, and a rationalizations table. Adaptations: a Positioning section stating the design-time-vs-review-time split against the two review agents; the upstream's deprecation-and-migration sibling reference (not adopted here) retargeted to the local data-migration-expert agent for the data-layer-migration facet; frontmatter description and voice conformed to house style (imperative, what + when). Supply-chain review: single prose SKILL.md, no scripts/network/dependencies — clean. Skills 32 → 33.

Added

• debugging-and-error-recovery skill — the root-cause debugging methodology that sits above the plugin's existing reproduce-and-file tools. Adopted and adapted from addyosmani/agent-skills (skills/debugging-and-error-recovery/SKILL.md@4e8bd9fd, MIT, supply-chain reviewed). Codifies stop-the-line on any unexpected failure, then a six-step triage checklist — reproduce, localize, reduce, fix the root cause, guard, verify. Its high-value content is preserved intact: the non-reproducible-bug decision tree (branch on timing / environment / state / randomness, with tactics like artificial delays to widen race windows and load to raise collision probability), the symptom-vs-root-cause worked example (fix the JOIN, not [...new Set(users)] in the UI), a git bisect run regression recipe, the calibrated "you might be right 70% of the time; the other 30% costs hours — reproduce first" rationalization, and a "Treating Error Output as Untrusted Data" section (never execute commands or URLs embedded in stack traces or CI logs) that mirrors this repo's own untrusted-input posture. Positioned explicitly as the broader triage *methodology*: it points to the /reproduce-bug and /report-bug commands and the bug-reproduction-validator agent for the concrete reproduce-and-file workflow so their triggers stay distinct, and hands off to the verification-loop skill for the pre-PR quality pass. Generic per-error triage trees (TypeError, CORS, white screen) tightened; stack-specific commands marked illustrative to keep the methodology language-agnostic. Skill count 31 → 32.

Added

• sdd-cache — an opt-in, revalidating WebFetch doc cache (adopted from addyosmani/agent-skills, ported bash→python3). A PreToolUse/PostToolUse (WebFetch) hook pair that caches fetched documentation on disk so an agent consulting the same official docs across sessions stops re-downloading identical pages — without weakening the "verify against current docs" guarantee. The load-bearing property is that there is no TTL: the pre hook looks up the cached entry by sha256(url) (32 hex chars) under .claude/sdd-cache/, and if it carries an ETag/Last-Modified validator, sends a conditional HEAD (If-None-Match/If-Modified-Since, 5s timeout, follows redirects) to that same URL; it serves the cached body and blocks the fetch (exit 2, the same deny signal block-no-verify.py uses) only on a real 304 Not Modified — a live re-verification, not a memory read. Any other outcome (200 = changed, error, timeout, or an entry with no validator) lets the real WebFetch proceed. The post hook HEADs the URL to capture validators from the final redirect hop and writes {url, prompt, etag, last_modified, content, fetched_at} atomically; a response with no validator is never cached (it could never be revalidated) and any stale entry is removed. Opt-in posture (a condition of the adoption): both hooks are inert unless AGENTIC_SDD_CACHE=1 is set — following the v3.7.0 opt-in precedent (off by default, explicit signal) but via an environment variable rather than a committed frontmatter flag, since caching is a per-machine choice that shouldn't ride a PR and flip on for every clone (and so it stays off the agentic-engineering.local.md config surface). Both fail-open on any error, so a broken cache can never block a legitimate fetch. The two upstream bash scripts were ported to python3 (stdlib urllib/hashlib/json — curl→urllib.request, jq→json, shasum→hashlib) to match every other hook in scripts/; .claude/sdd-cache/ is gitignored. Supply-chain reviewed line-by-line (the only network egress is a conditional HEAD to the same URL the agent already intends to fetch — no exfiltration; writes confined to the cache dir; no eval of fetched content). Pinned by sdd_cache_pre_test.py / sdd_cache_post_test.py (offline: the revalidation call is mocked, including the safety-critical "200 ⇒ never serve stale" path and the cross-hook shared-key invariant). Documented in README.md (Hooks) and scripts/HOOKS.md. Provenance: addyosmani/agent-skills@4e8bd9fde4a38cd009053e649f4cdc7cd36b568b. No component count changes — hook addition only.

Added

• test-driven-development skill — the test-*authoring* discipline, adopted (adapted) from addyosmani/agent-skills. Fills the gap on the write side of testing: RED-GREEN-REFACTOR, the Prove-It pattern (every bug fix starts with a failing reproduction test), the test pyramid plus a Google-style test-size resource model (Small = no I/O, ms / Medium = localhost, s / Large = external, min), the test-double preference order (real > fake > stub > mock, mock only at boundaries), state-not-interactions assertions, DAMP-over-DRY, the Beyonce Rule, and the efficiency rule "after a clean run, don't re-run the same command unless code changed." Explicitly positioned as the authoring complement to the review-time test-strategy-reviewer (audits existing tests) and the verification-loop gate (runs the suite before done), so the three skills' triggers don't collide. Co-locates an adapted references/testing-patterns.md (framework-generic Arrange-Act-Assert, naming, assertions, mocking-at-boundaries, component/API/E2E examples). The upstream browser-testing section is retargeted from Chrome DevTools MCP to the local agent-browser skill and /test-browser command, and the "sibling reference" pointers now name only components that exist here. Skills 30 → 31. Provenance pinned in docs/upstream-sources.md.

Added

• security-and-hardening skill — the build-time security playbook that complements the audit-time security-sentinel agent. Adopted (adapted) from addyosmani/agent-skills via the /upstream-scan triage pipeline. Where security-sentinel reviews finished code ("did they build it safely"), this skill guides hardening *during* implementation ("how to build it safely") — the two are stated as complementary in the skill so their triggers don't collide. Substance preserved in full: a five-minute threat-model-first process running STRIDE over each trust boundary (with mitigations) and writing abuse cases next to use cases; a three-tier Always / Ask-First / Never boundary system; OWASP Top 10 prevention patterns including an SSRF allowlist built on ipaddr.js range() !== 'unicast' that names its own residual TOCTOU / DNS-rebinding gap and the pinned-IP mitigation; a reachability-keyed npm audit triage decision tree ("is the vulnerable function actually called in your code path?") plus supply-chain hygiene (lockfile + npm ci, postinstall wariness, typosquat watch); and a full OWASP LLM Top 10 section treating model output as untrusted data (no eval/SQL/innerHTML/shell), with prompt-injection, excessive-agency, and unbounded-consumption guidance. Co-locates the upstream security checklist as a skill reference (security-checklist.md), linked from SKILL.md. Provenance pinned to addyosmani/agent-skills@4e8bd9fde4a38cd009053e649f4cdc7cd36b568b; both source files passed supply-chain review (pure documentation — no scripts, network calls, or embedded instructions). Skills 29 → 30.

Added

• observability-and-instrumentation skill — instrument-as-you-build discipline so a feature ships with the telemetry to operate it, not archaeology after the first incident. Adopted and adapted from addyosmani/agent-skills (skill + its repo-root observability checklist, co-located here as references/observability-checklist.md). Codifies the parts most teams get wrong: a signal-selection table (structured log vs metric vs trace, each with a cost profile — "metrics tell you *that*, traces *where*, logs *why*"), RED for endpoints / USE for resources, a hard cardinality denylist (user_id, email, request_id, full URL, and error text are never metric labels), "percentiles always, averages never", symptom-vs-cause alerting (error rate > 1% for 5 min pages; CPU at 85% does not), a log-level → on-call-action table, and a verify-the-telemetry step (force an error in staging, find it by requestId). Complements the audit-time security-sentinel agent (secret-in-logs) and the performance-oracle agent (measured slowness); illustrative OpenTelemetry/Prometheus snippets are examples only. Skills 28 → 29.

Added

• interview-me skill — confidence-gated intent extraction that runs upstream of brainstorming. Adopted and adapted from addyosmani/agent-skills (skills/interview-me/SKILL.md). What the user asks for and what they actually want are different things ("build me a dashboard" is a convention, not a solved problem); this skill closes that gap before any spec, plan, or code exists, when switching costs are still zero. The mechanic is a mandated HYPOTHESIS / CONFIDENCE ~N% — missing: opener, then one question at a time each carrying a falsifiable GUESS: (the user reacts to a wrong guess faster than they generate an answer, which also surfaces the interviewer's own assumptions), a "want vs. should-want" detector for buzzword goals ("scalable", "clean", "modern") whose probe is *"If you didn't have to justify this to anyone, what would you actually want?"*, an anti-sycophancy rule, rejection of false confirmations ("Whatever you think is best" → re-ask with two concrete options), a checkable stop condition (*"Can I predict the user's reaction to the next three questions?"*), and a restate template with a non-negotiable Out-of-scope line. It explicitly refuses non-interactive contexts (CI, /loop, autonomous loops), flagging underspecification as a blocker instead of guessing. Positioned deliberately relative to brainstorming — interview-me extracts what the user wants (intent); brainstorming explores how to build it (approaches) — so their adjacent triggers order rather than collide, then it hands off to brainstorming and /workflows:plan. Optional user-confirmed persistence to docs/intent/YYYY-MM-DD-<topic>-intent.md, mirroring where brainstorming saves its design docs. Supply-chain review: clean (pure-prose skill, no remote fetches, scripts, or exfiltration). Skills 27 → 28. Provenance pinned in docs/upstream-sources.md.

Added

• /config-flags — discoverable config surface for every opt-in flag the plugin offers. scripts/config_registry.py is the single declared inventory of per-repo configuration flags read from agentic-engineering.local.md (and, for board identity, the committed agentic-engineering.md): a ConfigFlag dataclass (key/kind/default/description/owner/file/choices/toggleable) per flag, with --inventory/--get/--set verbs sharing lifecycle_board.py's existing atomic-write, tracked-file-guard, and {ok, error_code, error, fix} error contract — writes are refused outright if agentic-engineering.local.md is tracked in git, never silently overwritten. Retrofits the four flags that previously shipped with zero central discoverability (issue_tracker, review_agents, plan_review_agents, nudge_todowrite from v3.7.0) plus the two board-identity keys (github_project_owner/github_project_number, inventoried but never toggleable). /config-flags (named to avoid colliding with the built-in /config) browses the full inventory and flips a flag via AskUserQuestion; /lifecycle-doctor gains a read-only Configuration section (SET/UNSET vocabulary, distinct from its PASS/WARN/FAIL/SKIP health checks) over the same inventory; the setup skill now delegates its flag writes to the shared writer instead of hand-templating frontmatter (and, as a side effect, no longer risks silently overwriting a tracked local config — the writer refuses first). A new lint test (tests/config-registry.test.ts, mirroring tests/flagless-gh.test.ts) fails CI if a script reads a frontmatter key with no matching registry entry, so a flag can never ship invisibly again the way nudge_todowrite did. Command count 26 → 27. See docs/plans/2026-07-10-feat-discoverable-config-surface-plan.md (#91) for the full design, including the deliberately-deferred Phase 2 (build-time aggregation of config flags across every plugin in this marketplace, once a second plugin ships one).

Added

• land-docs skill — the autonomous "data lane" that ships compounded knowledge as its own docs-only PR and merges it on green, so a session closes out without a second user turn. Before this, the seam between land-pr (merges the code PR) and /workflows:compound (writes docs/solutions/ markdown) had a gap: compound never touched git — it wrote the knowledge into the post-merge default branch's working tree, stamped the board compounded, and stopped on a blocking "What's next?" menu. The knowledge was left uncommitted and the agent turned back to ask the user what to do — another cycle before the session could end. land-docs closes that seam: it opens a docs/<N>-knowledge PR, follows its GitHub Actions checks (CI owns review — the skill runs no in-agent review pass), and merges on green with no user turn; fixes a simple check failure; or pauses only when a failure genuinely warrants user input. Its one safety property is a docs-only scope gate — every changed path must match *.md / docs/; any non-doc path aborts the auto-merge and escalates — which is what licenses the unattended merge. Wired into /workflows:compound (new Phase 3) and /workflows:orchestrate (new Compound sub-row + suppressed the blocking compound-docs decision menu on the pipeline path), and referenced from the land-pr skill as the counterpart knowledge-PR lander. Skills 26 → 27.

Added

• nudge-todowrite-to-tracker.py — optional, non-blocking PreToolUse (TodoWrite) hook nudging toward the repo's durable issue tracker. TodoWrite is ephemeral, in-session scratch; a repo that has committed to a durable tracker (GitHub Issues / GitHub Project board) wants cross-session work filed there instead, without fighting TodoWrite's legitimate ephemeral role with a hard block. The hook is silent (exit 0, no output) unless the repo opts in with nudge_todowrite: true in agentic-engineering.local.md frontmatter (same tracked-file security invariant as issue_tracker: — a committed copy is ignored) *and* a tracker actually resolves to something other than none. Tracker resolution reuses workflow-repo-preflight.py's resolve_issue_tracker() chain verbatim (local override > committed board config -> github-project -> gh auth -> github -> none), so the reminder always names the same tracker the rest of the lifecycle tooling agrees on; beads is intentionally not a nudge target since the unified lifecycle already demotes it to a non-authoritative scratchpad (plan-tracker-guard.py). Pinned by nudge_todowrite_to_tracker_test.py. Addresses #89. No component count changes — hook addition only.

Added

• setup skill now offers an opt-in up-front Headroom install (Step 3.8). Previously the headroom skill only installed the CLI lazily on its first invocation; the plugin's setup flow did not manage it. Setup now detects install state (command -v headroom) and the available installer (uv preferred, pip fallback), and — only when Headroom is absent and an installer exists — offers uv tool install "headroom-ai[all]" behind an AskUserQuestion gate, then verifies with headroom doctor. Consistent with the plugin's norm of never installing a binary without consent: it skips silently when already installed, declines to offer when neither uv nor pip is present (pointing at the skill instead), never auto-installs on non-interactive runs (prints the command for later), and notes the AVX2/ONNX [all]-extra caveat with the base-package fallback. Step 5's confirmation summary gains a Headroom: line; the skill description is updated to match. Skill enhancement only — no component count changes.

Added

• headroom skill — AI context compression via the Headroom CLI. Headroom compresses everything an agent reads (tool outputs, logs, RAG chunks, files, conversation history) before it reaches the LLM, cutting 60-95% of tokens with the same answers via reversible compression that caches and restores originals on demand. The skill follows the same shape as the rclone skill: a setup check that installs the tool as a global CLI with uv tool install "headroom-ai[all]" (pip fallback, plus AVX2/ONNX requirement notes and headroom doctor routing verification), a command reference (wrap, proxy, perf, dashboard, learn), and worked workflows for the three integration modes — wrapping a coding agent (headroom wrap claude), running the drop-in proxy (headroom proxy --port 8787), and library use (from headroom import compress). headroom learn (mine failed sessions into local markdown corrections) ties into the compounding-engineering loop. Skill count 25 → 26.

Added

• git-worktree skill gains a non-interactive gc subcommand for safe, unattended reaping of merged worktrees (adapted from the bluestar-intel repo's post-merge gc-worktrees.sh hook). The skill previously only offered cleanup, which is interactive (read -r prompt — unusable in an agentic loop or hook) and force-removes EVERY inactive worktree regardless of merge state, so it can silently discard unmerged parallel work and leaves orphaned local branches behind. This is a real hazard for the plugin's core parallel/swarm workflows (/resolve_parallel, orchestrating-swarms), where several worktrees hold live in-progress work at once. worktree-manager.sh gc [base-branch] reaps a worktree only when ALL hold: it lives under .worktrees/, is not the current worktree, has a clean tree, is fully merged into the base (git cherry shows zero + commits and ≥1 - — patch-equivalence catches GitHub's default squash/rebase merges where SHAs differ, while a brand-new empty branch is left alone), and has been idle for the grace window (default 30 min, WORKTREE_GC_GRACE_MIN); it also deletes the now-orphaned local branch. WORKTREE_GC=0 skips, WORKTREE_GC_BASE sets the default base (origin/main → local main fallback), and it always exits 0 so it can be wired into a git post-merge hook without ever failing the surrounding operation. cleanup is unchanged but now documents its force-remove hazard and points at gc for unattended use. Verified end-to-end in scratch repos: squash-merged worktree + branch reaped; genuinely-unmerged, dirty, and current worktrees all preserved. No component count changes — skill enhancement only.

Added

• docs/pages/changelog.html is now generated from this file (issue #78). The published docs-site changelog had silently diverged from CHANGELOG.md: hand-maintained from v1.0.0 → v2.6.0, it received two more hand-written entries at v2.32.1/v2.32.2 and was then untouched while ~30 releases (3.0.0 → 3.5.4) shipped — and nothing caught the drift, since scripts/generate-docs.ts deliberately left it as hand-written chrome. scripts/generate-docs.ts now parses this file (Keep a Changelog format: ## [x.y.z] - date headers, ### Category sections, single/nested bullet lists, inline bold/code/link spans, one summary table) with a small hand-rolled renderer — no new dependency; a markdown library was surveyed and rejected because the target page's per-category HTML/CSS wrapping (.changelog-category.added/.changed/.fixed/…, FA icons, version badges) needs bespoke mapping a generic renderer wouldn't produce anyway — and splices the result into docs/pages/changelog.html between the standard <!-- GENERATED --> markers, wired into the existing bun run docs:build / docs:check pipeline (tests/docs-generated.test.ts now covers the changelog page too, so drift is caught in CI like every other reference page).
• Backfilled v1.0.0 → v2.6.0 into CHANGELOG.md — this file previously started at v2.15.0; those 13 earlier releases existed only in the hand-written HTML. Transcribed verbatim (all agents/commands/skills, the v2.0.0 summary table, nested Puppeteer→Playwright migration list) so the generated changelog page loses no history switching to CHANGELOG.md as its sole source of truth.
• Root CLAUDE.md "Keeping Docs Up-to-Date" section corrected — no longer claims changelog.html "mirrors CHANGELOG.md" as a manual step; documents the generator relationship and warns against hand-editing the generated entries.

Added

• tests/setup-recipe.test.ts — the setup skill's Step 4.5 gitignore recipe is now executed in CI, not just published (todo 004 from the PR #72 review synthesis; the durability follow-up that PR deferred). The recipe's flags are load-bearing and lived only in markdown, unguarded by the count/frontmatter tests — the exact false-confidence shape docs/solutions/testing-patterns/recorded-fixtures-must-be-load-bearing.md warns about. The test extracts the first fenced bash block after the ## Step 4.5 heading verbatim (failing if the heading or block is missing, so doc and test cannot drift — a "simplified" recipe runs as simplified and fails on behavior) and executes it via bash in hermetic temp git repos (isolated GIT_CONFIG_GLOBAL/GIT_CONFIG_NOSYSTEM/GIT_CEILING_DIRECTORIES, so a developer's own excludes can't fake a pass) across the six core scenarios: fresh repo run from a subdirectory (entry lands in the root .gitignore; file ignored and untracked), legacy tracked copy (tracked=1 detected, entry appended exactly once across a re-run — pinning --no-index, without which a tracked path is never reported ignored and every re-run would re-append; the test also asserts plain check-ignore fails where --no-index passes), pre-existing broader *.local.md pattern (byte-identical .gitignore, nothing appended), .gitignore without a trailing newline (the tail -c1 repair keeps the last existing pattern intact), non-git directory (silent skip, root=none, no .gitignore created), and symlinked .gitignore (append refused — the PR #72 review guard — link target byte-identical across two runs). The echoed root=/gitignore=/tracked= status line is asserted exactly: the SKILL declares it the recipe's only observable output, consumed by the untrack consent gate and Step 5. Mutation-verified before landing: dropping --no-index, disabling the symlink guard, or renaming the heading each fails the suite. Also commits todos/004 (pending → complete). No component changes — counts unchanged.

Added

• block-slack-webhook secret-hygiene guard hook, ported from agent-leverage (PreToolUse — Bash + Write/Edit/MultiEdit, wired in plugin.json, with a unit test). Completes the agent-leverage guard cluster: the prior ports (block-no-verify, prevent-main-commit, block-beads-jsonl-stage) cover git and env hygiene, but the plugin had no guard against committing a live secret. A Slack incoming-webhook URL (hooks.slack.com/services/...) is a credential; hardcoding one into code, CI config, or a curl leaks it into git history and build logs. The hook blocks that on the unambiguous host+path — so the Slack *app* (api.slack.com / chat.postMessage / MCP tooling) is never blocked — and exempts prose (.md/.mdx/.txt/…) and files under hooks//scripts/ that merely *describe* the anti-pattern. The block message points to the correct alternative: read the webhook from an env var / secret manager, or send through a connected Slack app. Generalized from agent-leverage's repo-specific version (removed references to that repo's internal notification code paths). No new agents/commands/skills — counts unchanged.

Added

• Bootstrap scaffolds the actions/add-to-project workflow when forward binding is auto-add (issue #63) — the mechanism that makes #64's auto-add choice functional and flips /lifecycle-doctor's board_forward_binding check from WARN to PASS. The built-in Projects v2 auto-add workflow has no create/enable API (ProjectV2Workflow is delete-only); the official actions/add-to-project Action reproduces it. When (and only when) the operator chooses auto-add, bootstrap_lifecycle_board.py writes .github/workflows/add-to-project.yml — idempotent (never clobbers an existing file) and non-fatal (a write failure degrades to a summary warning), mirroring the link_repo step. The scaffolded workflow is hardened per a security + framework-docs deepening pass: SHA-pinned actions/add-to-project (resolved live at scaffold time via gh api repos/actions/add-to-project/commits/v2, falling back to a known-good constant — a moving @v2 tag would run with the ADD_TO_PROJECT_PAT secret in scope, the tj-actions/changed-files compromise class, amplified across every scaffolded repo; first-party actions/* is no exemption), permissions: {} at top and job level (the PAT does the Projects write, so GITHUB_TOKEN needs nothing — stricter than contents: read), on: issues: [opened] with no untrusted checkout and no run: steps, plus an inline comment forbidding future run: steps that interpolate github.event.issue.* (script-injection guardrail). Bootstrap also scaffolds .github/dependabot.yml (github-actions ecosystem) so the pin stays current — created only when absent; an existing dependabot config is never parsed/merged (a warning points the operator to add the ecosystem). The correct users/ vs orgs/ project-url segment is resolved via gh api users/<owner> --jq .type. The one remaining manual step — the ADD_TO_PROJECT_PAT secret — is documented least-privilege-first (fine-grained PAT with org Projects:R/W + repo Issues/PRs:read → GitHub App token → classic PAT fallback). No new agents/commands/skills — counts unchanged.

Added

• The repo→board binding is now an explicit, recorded decision (issue #64). Bootstrap used to leave "configure auto-add" as an orphaned manual UI step with no explanation and a doctor check that could only say "verify by hand." Projects v2 boards are *materialized collections, not live queries* — creating an issue does not put it on any board, and GitHub's auto-add is forward-only (never backfills). Setup now records two orthogonal decisions, treated independently (backfill is offered under *any* forward choice, never gated behind auto-add):
  • (A) Forward binding — how NEW issues reach the board. bootstrap_lifecycle_board.py gained --forward-binding {workflow-only,auto-add,none} (default workflow-only), written into committed agentic-engineering.md as github_project_forward_binding in the same write as board identity (a crash can never leave identity without policy). Omitting the flag preserves a prior choice on re-run rather than resetting it. /lifecycle-doctor replaces its uncheckable "verify by hand" line with a concrete per-branch board_forward_binding check: workflow-only PASSes when no orphaned auto-add workflow exists; auto-add verifies .github/workflows/add-to-project.yml is present and the board is repo-linked (its token secret is write-only, so that one bit is explicitly called out as unverifiable); none is informational; an unrecognized/unrecorded value WARNs. (The auto-add workflow *scaffolding* itself remains issue #63's mechanism — this change records and verifies the decision.)
  • (B) Backfill — put EXISTING issues on the board now. New lifecycle_board.py --backfill verb: a one-time, idempotent add of every open origin-repo issue not already on the board, recording a github_project_backfilled_through high-water mark so a re-run adds only what a partial run missed. Enumerates repo issues via paginated gh issue list — deliberately *not* the 50-capped ready-work path, which would have silently dropped issues 51+ — excludes PRs and closed issues, dedupes against board membership with one read (not N+1), tolerates partial failure (one failed add never aborts the loop), and advances an advisory high-water marker only over a failure-free prefix (the marker gates whether setup re-offers the backfill; a re-run always recomputes the full open-vs-board difference). Never run by bootstrap, so setup never mutates issues onto the board unattended (CI-safe by construction).
  • Internals: the committed-config writer (upsert_frontmatter_keys / write_config_keys) moved to lifecycle_board.py as the single write path shared by bootstrap and the backfill marker; the forward-binding doctor verdict is a pure, unit-tested helper (evaluate_forward_binding_check). No new agents/commands/skills — counts unchanged.

Added

• Uniform run-level no-progress stop. Replaced the scattered per-stage "~2 attempts" prose with one stagnation mechanism at the orchestrate loop level: a pass makes *progress* only if the board stage advanced or one of {open sub-issues, unresolved review threads, failing required CI checks, open P1 findings} strictly decreased; two consecutive no-progress passes at a stage enters a new stalled terminal state and escalates with evidence. Evidence-based, not a clock/iteration/token cap. The existing land-pr and /workflows:work retries are now documented as instances of this one rule (a retry that shrinks nothing counts toward the bound).

Added

• verification-loop skill — a systematic verify-before-done pass. Runs build → types → lint → tests → security → diff review as sequential gates and ends with a single ready / not-ready verdict. Adopted from affaan-m/ECC as the first upstream adoption executed through the /upstream-scan triage pipeline (landed via PR #35, issue #60). Counts: 24→25 skills.
• block-beads-jsonl-stage operational guard hook ported from agent-leverage (PreToolUse/Bash, wired in plugin.json, with a unit test): blocks staging the passive .beads/*.jsonl Beads export so the local scratchpad never lands in git (PR #38, issue #57).
• Test coverage + a hook catalog for the existing safety hooks. Added unit tests for block-no-verify and prevent-main-commit (ported in a prior release without tests) and a scripts/HOOKS.md index documenting every plugin hook (PR #37, issue #59).
• Bootstrap now links the lifecycle board to its origin repo. Projects v2 boards are owned by a user/org and can only be _linked_ to a repo — there is no repo-owned board — and linking is what surfaces the board on the repo's Projects tab and enables auto-add-from-repo. bootstrap_lifecycle_board.py gained a link_repo step (after workflow config, before the committed-config write) that is idempotent (queries current links via a shared lifecycle_board.project_linked_repos helper and skips the mutation when already linked) and non-fatal (a link failure degrades to a summary warning, never an abort — board resolution only needs owner+number). /lifecycle-doctor gained a matching board_repo_link check under Board schema: PASS when linked, WARN with the exact gh project link … fix when not, SKIP when unreadable. This closes the gap where a freshly bootstrapped board was invisible on the repo's Projects tab, which read as "no board" in the multi-repo/multi-customer model. Related footgun this surfaces: the committed agentic-engineering.md records one board's owner/number, so a fork/clone under a different owner must re-run bootstrap to point at _its own_ board.

Added

• operating-principles skill — how to operate, distilled from Claude Fable 5 for executor models. The general operating approach for engineering work, captured as explicit procedure so Opus-tier executors (the implementation tier in delegate-mode orchestration) can follow a frontier model's policy mechanically. Depth is self-calibrating: a Step-0 gate sends easy tasks down a light path (do, verify once, report) and multi-step / ambiguous / expensive ones through the full procedure — ground-truth-before-planning (goal restated as an observable acceptance check, real code read before decomposition, load-bearing assumptions verified cheapest-first), risk-first decomposition where every subtask has an independently checkable exit condition, an explicit goal → evidence → gap → action execution loop with a two-strike backtrack rule (two failed fixes at one point = wrong mental model, go instrument) and a blocked-state taxonomy (self-serve facts; escalate only genuine decisions), independent-channel verification (execute > trace > hostile diff read > sibling sweep, plus the make-it-fail-once and green-is-real anti-theater disciplines), and calibrated reporting (every claim labeled Verified / Checked / Assumed; "should work" never rounds up to "works"). Progressive disclosure in four layers: an always-on CLAUDE.md snippet (assets/claude-md-snippet.md — the ten compressed rules plus a trigger line pointing at the skill, paste-ready for consumer repos), the SKILL.md spine, and three depth references — decomposition-patterns.md (load-bearing-question-first, vertical slice, interface-first, spike-then-implement, checkpoint-before-irreversible, scope ledger + five anti-patterns), verification-playbook.md (per-artifact checklists for bug fix / feature / refactor / migration / config), and failure-modes.md (14 characteristic agent failure modes — success theater, patch spiral, imagined codebase, scope drift, premature done, stopping-at-a-plan, … — each with a detection signal and countermeasure). Wired into the delegation path so it is used constantly, not on request: /workflows:work loads it at entry and its subagent brief template instructs every implementation sub-agent to follow it; /workflows:orchestrate inherits both via that template and applies the same discipline to its own review-and-steering loop; and the setup skill gains Step 3.7, which offers to install the snippet into the consuming repo's existing CLAUDE.md and/or AGENTS.md — a marker-guarded append (operating-principles always-on layer) that is idempotent across re-runs and symlink-safe, with an offer to create CLAUDE.md when neither file exists. Counts: 23→24 skills.
• Unified work-item lifecycle on a GitHub Projects v2 board (part 2 of the unified-lifecycle work, issue #39). Replaces the three-tracker dispatch model with a single lifecycle — stub → brainstormed → planned → in_progress → in_review → shipped, with order-independent terminal refinements deployed / compounded and the abandoned off-ramp — whose source of truth is a GitHub Projects v2 board readable and writable by both humans (browser) and agents (gh CLI). New scripts/lifecycle_board.py (importable, stdlib-only, pure decision core + injected run_gh) exposes the verbs --gate / --claim / --set-status / --ready-work / --reconcile / --doctor with a uniform {ok, error_code, error, fix} error contract; its reconciler applies a closed set of five repairs (merged_close_missed, not_planned_close, pr_closed_unmerged, abandoned_cascade, pr_reopened) plus three report-only flags (merged_to_non_default_branch, stale_join_key, truncated_ready_work), never widening past five. Every workflow command gains an idempotent entry gate (--gate) that reads lifecycle state and routes on a closed verdict enum, plus a one-line writer contract naming the single transition it owns. A new skills/lifecycle/SKILL.md holds the shared vocabulary (9 stages, writer table, claim semantics, security invariants) with a references/gh-recipes.md for the concrete gh invocations, deploy adapter, and git-flow issue-closer workflow. A bootstrap script (hosted by the setup skill) creates and configures the board via ID-preserving updateProjectV2Field — a fresh-project guard refuses to adopt a customized project, and the "Item reopened" workflow is disabled if present (new projects typically don't ship it; /lifecycle-doctor re-checks) so that where present, reopening never re-stamps stub. Board identity moves to committed config (github_project_owner: / github_project_number: in agentic-engineering.md) resolved from the git common dir so worktree-isolated subagents behave identically; only the session TTL cache stays local. New /lifecycle-doctor command (wrapping --doctor) is the setup verification front door: a PASS/WARN/FAIL/SKIP checklist over toolchain, repo shape, board schema, and delivery topology, ending with "Ready for first work item: yes/no" (--live runs the end-to-end scratch-issue probe). The fork-trap hook (block-upstream-pr.sh) is extended to cover gh project writes, ProjectV2-mutation GraphQL, GH_REPO= prefixes, and REST writes to upstream paths, backed by a committed tests/flagless-gh.test.ts. gh ≥ 2.94.0 with the project scope is now a hard prerequisite (--parent, --blocked-by, dependency JSON fields), pinned in CI. Counts: 27→28 commands, 22→23 skills (new lifecycle-doctor command; new lifecycle skill offsets the deleted linear-sync).

Added

• /analyze-source command — one-off evaluation of any external resource. Given an X post, a blog, a GitHub repo, a marketplace, or an installable tool, the command resolves the resource (x.com via an api.fxtwitter.com → cdn.syndication.twimg.com → WebSearch fallback chain, following links to the canonical repo before classifying), triages it as a technique / artifact repo / installable tool, spends analysis depth proportional to that type (idea-vs-existing-components for a technique; a full gh api fact sheet — license/stars/dates/archived, trees-API structure, 2–3 credential-free component samples, overlap/gap vs the plugin inventory, and registry decision memory — for a repo; duplicate-vs-complement plus install security surface for a tool), and returns exactly one verdict: author locally, track as an upstream source (emitting a ready-to-paste docs/upstream-sources.md block + top cherry-pick candidates — the intake exit), spin up a new domain plugin, reference/install-alongside, or skip. Read-only by design (disable-model-invocation, scoped allowed-tools with no Write/Edit/gh issue/gh pr; all fetched content is untrusted data read in credential-free subagents) and explicitly delegation-friendly for background agents. Reframed from the originally-planned /upstream-intake: the general act is analysis, and registry intake is just one of five exits — validated by two real runs before implementation, the ECC analysis (verdict: track upstream) and the codex-plugin-cc X-post analysis (verdict: reference/install-alongside). From the 2026-07-03 plan (issue #31).
• /upstream-scan invariant — fork-parent reads must not share a command line with a gh issue/gh label write. The repo's fork-trap hook literal-matches the EveryInc parent slug anywhere in a command that also contains a write subcommand, so a compound line (gh api repos/EveryInc/… && gh issue edit …) is denied even though both halves are individually safe. Documented in the command's invariants as its own Bash-invocation rule (maiden-run finding from PR #33).
• /upstream-scan command + upstream-source registry — recurring adoption from external repos. A new registry (docs/upstream-sources.md, repo-level) records each upstream source (ECC, the EveryInc fork parent, agent-leverage) with its license, visibility, and per-component provenance (adopted:/deferred: entries carrying upstream: path@sha refs, reviewer, and date). The /upstream-scan command compares each source's current component inventory (GitHub trees API) against {local components, adopted, deferred}, evaluates candidates with a curated lens, checks adopted components for upstream drift, and reports to one long-lived, fully-regenerated GitHub issue per source — heartbeat line, evidence columns, and a ready-to-paste registry block for the triage PR. Fully parameterized via registry frontmatter (report_repo, report_label): zero repo names in the command. Safety: disable-model-invocation, scoped allowed-tools (no Edit, no gh pr), explicit --repo on every gh call, untrusted-content rules with credential-free evaluation subagents, and private-source redaction. Enforced by a new merge-time lint (tests/upstream-registry.test.ts): registry schema, entry grammar, and a flagless-gh regression guard. The repo's fork-trap hook (block-upstream-pr.sh) now also covers gh issue subcommands. From the 2026-07-02 upstream-adoption plan (issue #28); prior art: Renovate's dependency dashboard, cargo-vet audits, Chromium third-party metadata.
• /workflows:merge command — a thin entry point to the land-pr skill. Gives the pipeline a command-named merge step (/workflows:merge [PR] [--auto]) that delegates entirely to land-pr — no merge logic is reimplemented. Preserves the /workflows:merge ergonomics some workflows rely on while routing through the single landability/merge-gate implementation (CI wait, review-thread resolution via resolve-pr-parallel, independent-review gate, branch cleanup, idempotent tracker-item close across beads/Linear/GitHub).
• land-pr skill — the completion-and-merge tail the pipeline was missing. The plugin modeled plan → work → (PR opened) → review → resolve comments but had no single component that drives a PR the rest of the way: wait on CI, resolve every review thread (delegating to resolve-pr-parallel), confirm approval and mergeability, then merge and clean up (delete branch, fast-forward the local default branch, idempotently close the tracker item). It defines explicit landability conditions (CI green + threads resolved + approved/mergeable) and a merge gate: pause-and-ask by default, auto-merge only in autonomous contexts (--auto, or when called from /lfg / /slfg / /workflows:orchestrate --auto) and only once all three conditions hold. Ships a scripts/pr-landable-status helper that emits the gating signals as JSON. Wired into the workflow surface: /lfg and /slfg gain a land-and-merge step before DONE; /workflows:orchestrate gains a land stage in its pipeline diagram, decision table (the merge is a 🧍 CHECKPOINT in steer mode, AUTO in --auto), state-detection, and final summary; /workflows:work Phase 4 and /workflows:review now point to land-pr as the next step after PR creation / findings resolution.

• Deterministic docs-site generator (scripts/generate-docs.ts, bun run docs:build / docs:check), gated in CI. Replaces the manual /release-docs skill with a script that regenerates the reference pages (docs/pages/agents|commands|skills|mcp-servers.html) and the landing-page stat numbers directly from the plugin's components — card sections (between <!-- GENERATED --> markers) and each page's "On This Page" sidebar — preserving all hand-written page chrome. A new tests/docs-generated.test.ts (run by bun test) fails if the committed pages drift from the components, so the docs site can no longer fall out of sync. Regenerated all four reference pages, which had drifted badly (7 agents, 14 commands, 8 skills missing; stale counts; a removed Playwright MCP server still listed). /release-docs is now a thin wrapper around bun run docs:build.
• Plugin consistency test (tests/plugin-consistency.test.ts), enforced in CI via bun test. Asserts the filesystem truth (counts of agents/commands/skills, MCP servers) against every place those numbers and lists are declared — plugin.json, marketplace.json, both READMEs, and the docs/index.html landing-page stats — plus version parity between plugin.json and marketplace.json, README completeness (every command by frontmatter name, every agent, every skill must be documented), and frontmatter hygiene (every command/agent declares name + description; every skill's name matches its directory). This closes the "added a component but forgot to update X" gap that previously had to be caught by hand. Failure messages name the exact file/component out of sync.

Added

• FLOWS.md — visual reference for every workflow. A plugin-root document with mermaid diagrams for each flow (orchestrate, brainstorm, plan, deepen-plan, work, review, compound, and the autonomous lfg/slfg), a shared shape legend (human checkpoints vs automatic steps), and a "big picture" composition diagram. Linked from README.md.
• /workflows:orchestrate — a steering orchestrator over the full pipeline. Drives brainstorm → plan → [deepen-plan] → work → review → compound autonomously, sitting between the user and the raw workflow commands like /goal//loop sit over a task. It auto-handles every menial transition (branch setup, "proceed?" prompts, detail-level choices, tracker bookkeeping, running the next stage) and pauses only at meaningful decision gates: approach selection (during brainstorm), a non-negotiable Plan-Approval gate before any code is written, and findings triage after review (P1s are auto-fixed; the user decides on P2/P3). Includes an autonomy dial (--auto minimizes gates to plan-approval + blockers; default "steer"; --careful confirms at every stage boundary), artifact-driven state detection so re-running resumes in place, a sub-command auto-answer cheatsheet, and blocker-batching (one AskUserQuestion, not drip-fed). Has full operation parity with /lfg: the same finalization steps run automatically when applicable — /resolve_todo_parallel for approved findings, /test-browser for web/iOS E2E verification, and /feature-video to attach a walkthrough to the PR — plus the optional ralph-wiggum continuation loop (used only in --auto mode, and it never overrides a human gate). Contrast with /lfg (fully autonomous, no human in the loop): orchestrate runs the same operations but keeps the human at the steering wheel for the few decisions that shape the outcome.
• /workflows:work — Orchestrated Execution style for the beads tracker. A third execution style (alongside inline and Swarm) where the agent acts as orchestrator: it owns the bead state machine and delegates implementation to one focused subagent per bead, looping each bead to a terminal state (resolved or a verified blocker) before returning to the user. Works for a single bead or a whole set. Adds terminal-condition definitions, a wave-based dispatch procedure, a subagent brief template, parallelism/worktree rules, and discovered-work-as-follow-on handling — all aligned with the existing parent-vs-child close convention (child beads close in the loop; the parent/standalone bead closes in Phase 4 after the PR). Picked via an execution-style note in the Phase 2 beads block; contrasted with Swarm mode for when to use each.

Added

• Stop hook safety net (scripts/plan-tracker-guard.py, registered via .claude-plugin/plugin.json hooks.Stop) blocks turn termination when any plan file under docs/plans/ modified in the current session lacks a tracker ID in its frontmatter. Respects issue_tracker: none carve-out and stop_hook_active re-entry protection. Catches any agent that bypasses or forks the /workflows:plan workflow.

Added

• reflect-for-skill-updates skill — the meta-improvement loop for compounding engineering. Where /workflows:compound captures the *solution* to a technical problem, this skill captures *what was missing from the tooling or documentation that let the problem occur in the first place*. It provides a structured gap-analysis process: identify root cause → categorize (missing automation, incomplete skill, workflow gap, undocumented dependency) → implement the fix in the right place (SKILL.md, CLAUDE.md, hook, script) → verify the fix would have prevented the issue. Adapted from agent-leverage's operational toolchain; linked as a natural follow-on to compound-docs. Increases skill count to 23.

• /ci-resolve-workflow-issues command — guided CI diagnostic workflow. The plugin's land-pr skill waits for CI to be green before merging, but there was no guided workflow for _fixing_ a failing build. The new command walks through identifying the PR, fetching failure logs (via gh or GitHub MCP tools), classifying the failure type (lint, types, tests, build, E2E, lockfile, migration, environment), reproducing locally, applying the fix, verifying, and pushing — with a flaky-failure re-run shortcut and a reference table of gh run commands. Links to land-pr as the natural next step once checks pass.

• block-no-verify PreToolUse hook (scripts/block-no-verify.py). Registers via plugin.json hooks.PreToolUse. Blocks git commit --no-verify / -n and git push --no-verify in any project that installs this plugin. Uses segment-aware regex to avoid false positives on grep/echo commands that merely mention the flag. Pre-commit and pre-push hooks are the last local quality gate before CI — bypassing them breaks the compounding-quality chain the plugin is built on.

• prevent-main-commit PreToolUse hook (scripts/prevent-main-commit.py). Registers alongside block-no-verify. Blocks git commit while on main/master and any explicit git push that targets those branches. Enforces the plugin's PR-based workflow (plan → work → PR → review → merge) for all projects that install the plugin, preventing accidental direct pushes that bypass code review and CI.

Added

• Beads (bd) as a first-class issue tracker alongside Linear and GitHub. Workflow commands now resolve an issue_tracker value (beads | linear | github | none) at start and dispatch accordingly.
• agentic-engineering.local.md schema extended with issue_tracker: frontmatter field. Explicit override always wins over auto-detection.
• Preflight script (scripts/workflow-repo-preflight.py) now reports beads_installed, beads_initialized, github_cli_authed, issue_tracker_resolved, issue_tracker_source, issue_tracker_ambiguous, and beads_remember_available.
• /workflows:plan writes bead_id: into plan frontmatter when tracker is beads; otherwise still writes linear_issue: or creates a GitHub issue unchanged.
• /workflows:work uses bd ready/bd update/bd close instead of TodoWrite when tracker is beads. For linear/github/none, TodoWrite is preserved (no regression).
• /workflows:review creates findings as beads (bd create … --tags=code-review) instead of todos/*.md files when tracker is beads. The Linear push step (Step 2b) is now gated to run only when tracker is linear.
• /workflows:compound appends bd remember "<insight>" --link "<solution-doc>" whenever bd is on PATH, regardless of tracker. Complements (does not replace) the solution doc.
• /workflows:brainstorm offers an optional "Capture as bead" handoff step when tracker is beads, pre-seeding the parent bead for the eventual plan.
• setup skill writes the auto-detected issue_tracker: into the generated config and surfaces ambiguous detections via AskUserQuestion.

Added

• scripts/workflow-repo-preflight.py — Deterministic repo/work-start preflight for /workflows:work that emits JSON with current/default branch, dirty state, optional PR metadata, Linear availability, and a recommended next action/prompt.

Added

• integration-boundary-reviewer agent — New always-on review agent that identifies untested integration boundaries where application code calls external libraries, APIs, or services. Flags cases where tests validate shapes but not behavior (e.g., constructor arguments that the library doesn't accept, transport type mismatches, tests that fail at auth before reaching integration code). Runs automatically during /workflows:review.
• test-strategy-reviewer skill — Analyze test files for coverage gaps, mock depth issues, and untested integration boundaries. Reports which functions have no tests, which tests mock at the wrong level, and which external library calls are never exercised with real objects.

Added

• Linear integration — Bidirectional sync between file-based todos and Linear project management
  • linear-sync skill — Documents the integration pattern, status/priority mappings, configuration, and workflow integration
  • /linear:sync command — Full bidirectional sync (push local changes + pull Linear changes)
  • /linear:status command — Show sync dashboard comparing file state with Linear state
  • /linear:import command — Import a specific Linear issue as a local todo file
  • /linear:pull command — Pull Linear changes (state, priority, comments, new issues) into files
  • CLI subcommand agentic-plugin linear — 8 subcommands: sync, push, pull, status, import, create, cancel, config
  • Graceful degradation — All Linear operations silently skip when LINEAR_API_KEY is not set
  • Last-write-wins conflict resolution — Compares Linear updatedAt vs file mtime; conflicts logged, never silently dropped
  • Parent/sub-issue hierarchy — Plans map to parent Linear issues, spawned todos become sub-issues

Added

• Gemini CLI target — New converter target for Gemini CLI. Install with --to gemini to convert agents to .gemini/skills/*/SKILL.md, commands to .gemini/commands/*.toml (TOML format with description + prompt), and MCP servers to .gemini/settings.json. Skills pass through unchanged (identical SKILL.md standard). Namespaced commands create directory structure (workflows:plan → commands/workflows/plan.toml). 29 new tests. (#190)

Added

• setup skill — Interactive configurator for review agents
  • Auto-detects project type (Rails, Python, TypeScript, etc.)
  • Two paths: "Auto-configure" (one click) or "Customize" (pick stack, focus areas, depth)
  • Writes agentic-engineering.local.md in project root (tool-agnostic — works for Claude, Codex, OpenCode)
  • Invoked automatically by /workflows:review when no settings file exists
• learnings-researcher in /workflows:review — Always-run agent that searches docs/solutions/ for past issues related to the PR
• schema-drift-detector wired into /workflows:review — Conditional agent for PRs with migrations

Added

• Factory Droid target — New converter target for Factory Droid. Install with --to droid to output agents, commands, and skills to ~/.factory/. Includes tool name mapping (Claude → Factory), namespace prefix stripping, Task syntax conversion, and agent reference rewriting. 13 new tests (9 converter + 4 writer). (#174)

Added

• document-review skill — Brainstorm and plan refinement through structured review (@Trevin Chow)
• /sync command — Sync Claude Code personal config across machines (@Terry Li)

Added

• orchestrating-swarms skill - Comprehensive guide to multi-agent orchestration
  • Covers primitives: Agent, Team, Teammate, Leader, Task, Inbox, Message, Backend
  • Documents two spawning methods: subagents vs teammates
  • Explains all 13 TeammateTool operations
  • Includes orchestration patterns: Parallel Specialists, Pipeline, Self-Organizing Swarm
  • Details spawn backends: in-process, tmux, iterm2
  • Provides complete workflow examples
• /slfg command - Swarm-enabled variant of /lfg that uses swarm mode for parallel execution

Added

• schema-drift-detector agent - Detects unrelated schema.rb changes in PRs
  • Compares schema.rb diff against migrations in the PR
  • Catches columns, indexes, and tables from other branches
  • Prevents accidental inclusion of local database state
  • Provides clear fix instructions (checkout + migrate)
  • Essential pre-merge check for any PR with database changes

Added

• /workflows:brainstorm command - Guided ideation flow to expand options quickly (#101)

Added

• /workflows:plan command - Interactive Q&A refinement phase (#88)
  • After generating initial plan, now offers to refine with targeted questions
  • Asks up to 5 questions about ambiguous requirements, edge cases, or technical decisions
  • Incorporates answers to strengthen the plan before finalization

Added

• /lfg command - Full autonomous engineering workflow
  • Orchestrates complete feature development from plan to PR
  • Runs: plan → deepen-plan → work → review → resolve todos → test-browser → feature-video
  • Uses ralph-loop for autonomous completion
  • Migrated from local command, updated to use /test-browser instead of /playwright-test

Added

• agent-browser skill - Browser automation using Vercel's agent-browser CLI
  • Navigate, click, fill forms, take screenshots
  • Uses ref-based element selection (simpler than Playwright)
  • Works in headed or headless mode

Added

• /agent-native-audit command - Comprehensive agent-native architecture review
  • Launches 8 parallel sub-agents, one per core principle
  • Principles: Action Parity, Tools as Primitives, Context Injection, Shared Workspace, CRUD Completeness, UI Integration, Capability Discovery, Prompt-Native Features
  • Each agent produces specific score (X/Y format with percentage)
  • Generates summary report with overall score and top 10 recommendations
  • Supports single principle audit via argument

Added

• rclone skill - Upload files to S3, Cloudflare R2, Backblaze B2, and other cloud storage providers

Added

• /feature-video command - Record video walkthroughs of features using Playwright

Added

• /deepen-plan command - Power enhancement for plans. Takes an existing plan and runs parallel research sub-agents for each major section to add:
  • Best practices and industry patterns
  • Performance optimizations
  • UI/UX improvements (if applicable)
  • Quality enhancements and edge cases
  • Real-world implementation examples

The result is a deeply grounded, production-ready plan with concrete implementation details.

Added

• agent-native-architecture skill - Added Dynamic Capability Discovery pattern and Architecture Review Checklist:

New Patterns in mcp-tool-design.md:

• Dynamic Capability Discovery - For external APIs (HealthKit, HomeKit, GraphQL), build a discovery tool (list_*) that returns available capabilities at runtime, plus a generic access tool that takes strings (not enums). The API validates, not your code. This means agents can use new API capabilities without code changes.
• CRUD Completeness - Every entity the agent can create must also be readable, updatable, and deletable. Incomplete CRUD = broken action parity.

New in SKILL.md:

• Architecture Review Checklist - Pushes reviewer findings earlier into the design phase. Covers tool design (dynamic vs static, CRUD completeness), action parity (capability map, edit/delete), UI integration (agent → UI communication), and context injection.
• Option 11: API Integration - New intake option for connecting to external APIs like HealthKit, HomeKit, GraphQL
• New anti-patterns: Static Tool Mapping (building individual tools for each API endpoint), Incomplete CRUD (create-only tools)
• Tool Design Criteria section added to success criteria checklist

New in shared-workspace-architecture.md:

• iCloud File Storage for Multi-Device Sync - Use iCloud Documents for your shared workspace to get free, automatic multi-device sync without building a sync layer. Includes implementation pattern, conflict handling, entitlements, and when NOT to use it.

Added

• CLAUDE.md - Added Skill Compliance Checklist with validation commands for ensuring new skills meet spec requirements

Added

• /xcode-test command - Build and test iOS apps on simulator using XcodeBuildMCP. Automatically detects Xcode project, builds app, launches simulator, and runs test suite. Includes retries for flaky tests.

• /playwright-test command - Run Playwright browser tests on pages affected by current PR or branch. Detects changed files, maps to affected routes, generates/runs targeted tests, and reports results with screenshots.

Added

• /report-bug command — New slash command for reporting bugs in the agentic-engineering plugin. Provides a structured workflow that gathers bug information through guided questions, collects environment details automatically, and creates a GitHub issue in the aagnone3/agentic-engineering repository.

Added

• Context7 MCP Server — Bundled Context7 for instant framework documentation lookup. Provides up-to-date docs for Rails, React, Next.js, and more than 100 other frameworks.

Added

• Playwright MCP Server — Bundled @playwright/mcp for browser automation across all projects. Provides screenshot, navigation, click, fill, and evaluate tools.

Added

• CLAUDE.md — Project instructions with versioning requirements.
• docs/solutions/plugin-versioning-requirements.md — Workflow documentation.

Added

New Agents (seven):

• design-iterator - Iteratively refine UI components through systematic design iterations
• design-implementation-reviewer - Verify UI implementations match Figma design specifications
• figma-design-sync - Synchronize web implementations with Figma designs
• bug-reproduction-validator - Systematically reproduce and validate bug reports
• spec-flow-analyzer - Analyze user flows and identify gaps in specifications
• lint - Run linting and code quality checks on Ruby and ERB files
• ankane-readme-writer - Create READMEs following Ankane-style template for Ruby gems

New Commands (nine):

• /changelog - Create engaging changelogs for recent merges
• /plan_review - Multi-agent plan review in parallel
• /resolve_parallel - Resolve TODO comments in parallel
• /resolve_pr_parallel - Resolve PR comments in parallel
• /reproduce-bug - Reproduce bugs using logs and console
• /prime - Prime/setup command
• /create-agent-skill - Create or edit Claude Code skills
• /heal-skill - Fix skill documentation issues
• /codify - Document solved problems for knowledge base

New Skills (10):

• andrew-kane-gem-writer - Write Ruby gems following Andrew Kane's patterns
• codify-docs - Capture solved problems as categorized documentation
• create-agent-skills - Expert guidance for creating Claude Code skills
• dhh-ruby-style - Write Ruby/Rails code in DHH's 37signals style
• dspy-ruby - Build type-safe LLM applications with DSPy.rb
• every-style-editor - Review copy for Every's style guide compliance
• file-todos - File-based todo tracking system
• frontend-design - Create production-grade frontend interfaces
• git-worktree - Manage Git worktrees for parallel development
• skill-creator - Guide for creating effective Claude Code skills

Added

• gemini-imagegen skill
  • Text-to-image generation with Google's Gemini API
  • Image editing and manipulation
  • Multi-turn refinement via chat interface
  • Multiple reference image composition (up to 14 images)
  • Model support: gemini-2.5-flash-image and gemini-3-pro-image-preview

Added

17 Specialized Agents

Code Review (five):

• kieran-rails-reviewer - Rails code review with strict conventions
• kieran-python-reviewer - Python code review with quality standards
• kieran-typescript-reviewer - TypeScript code review
• dhh-rails-reviewer - Rails review from DHH's perspective
• code-simplicity-reviewer - Final pass for simplicity and minimalism

Analysis & Architecture (four):

• architecture-strategist - Architectural decisions and compliance
• pattern-recognition-specialist - Design pattern analysis
• security-sentinel - Security audits and vulnerability assessments
• performance-oracle - Performance analysis and optimization

Research (four):

• framework-docs-researcher - Framework documentation research
• best-practices-researcher - External best practices gathering
• git-history-analyzer - Git history and code evolution analysis
• repo-research-analyst - Repository structure and conventions

Workflow (three):

• every-style-editor - Every's style guide compliance
• pr-comment-resolver - PR comment resolution
• feedback-codifier - Feedback pattern codification

Six Slash Commands:

• /plan - Create implementation plans
• /review - Comprehensive code reviews
• /work - Execute work items systematically
• /triage - Triage and prioritize issues
• /resolve_todo_parallel - Resolve TODOs in parallel
• /generate_command - Generate new slash commands

Infrastructure:

• MIT license
• Plugin manifest (plugin.json)
• Pre-configured permissions for Rails development