Skip to content

Refactor to native routing: skill-owned dispatch, consolidated meta-skills, openspec removal - #19

Open
cpliakas wants to merge 4 commits into
mainfrom
refactor/native-routing
Open

Refactor to native routing: skill-owned dispatch, consolidated meta-skills, openspec removal#19
cpliakas wants to merge 4 commits into
mainfrom
refactor/native-routing

Conversation

@cpliakas

Copy link
Copy Markdown
Owner

Summary

Restructures the plugin around Claude Code's native mechanisms, removing the hand-rolled orchestration machinery while keeping the advisory-agent premise intact. Net effect excluding the openspec removal: 35 files, +1,214/−1,935.

1. Plugin hook infrastructure + explicit tool grants (1227592)

  • Adds .claude-plugin/plugin.json and hooks/hooks.json so the markdownlint PostToolUse hook actually registers and fires (the script existed but was never wired).
  • Hardens the hook script: lint findings (exit 1) are distinguished from tool failures (exit ≥ 2, now surfaced instead of silently disabling linting), output is jq-escaped, truncation is marked.
  • Every agent now declares an explicit tools grant: advisory agents get Read, Glob, Grep, Skill (the skills: frontmatter only preloads content — the Skill tool is what allows invocation); Bash only where the body runs commands. Codified in CLAUDE.md.

2. Routing inversion (010da7d) — breaking

  • /plan-implementation now owns all mechanical routing: it reads the Tech Lead's registry directly, matches specialists semantically, classifies the tier via the Signals Catalog, and dispatches all five target types itself (subagent/external-agent spawned in parallel, skills invoked, docs read, human questions surfaced as open items).
  • The Tech Lead is invoked once, for judgment only: escalation flags (tier-3 one-way doors must name chief-architect), conflict resolution between specialists, constraints, and the recommended approach. tech-lead.md drops from 782 to ~440 lines.
  • The hand-parsed markdown contract ("Parseable Phase 1/2 Output Contracts") and every parse-failure path built around it are deleted.
  • Routing-outcome capture is removed outright rather than closed into a feedback loop: an auto-tuning registry would violate the plugin's advise-never-mandate stance, and the write-only log had no feedback path. /audit-routing-quality is deleted with it.

3. Consolidation + openspec removal (fc6b95b) — breaking

  • /re-onboard merges into /onboard --check-drift (same diff pass, same confirm-before-write flow, optional agent-name scoping).
  • /audit-routing-table's structural checks fold into /audit-agent-memory as a tech-lead-only section; the legacy-format MIGRATION.md moves alongside.
  • openspec/ is removed along with every live reference — proposals no longer flow through openspec.
  • Version bumps to 0.14.0.

4. Review-gate fixes (d17877b)

Cross-cutting fixes from the final adversarial review, dominated by one theme: the target-type registry format wasn't understood by every consumer. The drift check and the audit checks are now target-type aware (previously the drift check could batch-delete valid human/skill/external-agent registrations), agent-file resolution falls back to .claude/agents/ for consuming projects, unknown target types warn-and-exclude instead of coercing to subagent, write-convention spawns the domain owner directly, and agent bodies search with Glob/Grep instead of delegating to a subagent they cannot spawn.

Breaking changes

  • tech-lead no longer emits consultation-request output; callers that drove the two-phase protocol manually must use /plan-implementation.
  • Removed skills: /audit-routing-quality, /re-onboard (→ /onboard --check-drift), /audit-routing-table (→ /audit-agent-memory tech-lead).

Review process

Each batch ran through an explore → implement → review → fix → test workflow (Opus adversarial review of the staged diff) followed by an independent /code-review high gate; all findings from both layers were addressed before each commit.

After merge

  • Tag v0.14.0 per the repo's versioning convention.
  • Reinstall/update the locally installed plugin (currently pinned at 0.13.0) so the new skill set takes effect.

🤖 Generated with Claude Code

https://claude.ai/code/session_016myji5spWpb6qwqUQesXCr

cpliakas and others added 4 commits August 21, 2026 08:26
… grants

Add .claude-plugin/plugin.json and hooks/hooks.json so the markdownlint
PostToolUse hook actually registers and fires (previously the script existed
but was never wired). Harden the hook script: discriminate lint findings
(exit 1) from tool failures, escape output via jq, and mark truncation.

Give every agent an explicit tools grant: advisory agents are read-only
(Read, Glob, Grep) plus Skill so they can invoke the skills their bodies
reference; Bash only where the body runs commands (engineering-manager).
Codify the convention in CLAUDE.md and document the hook wiring in README.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AcZDonkHbahjy1SYuGHVye
…h-lead to judgment

Invert routing ownership: /plan-implementation now reads the routing model
from the Tech Lead's memory directly, matches specialists semantically,
classifies the tier via the Signals Catalog, and dispatches all five target
types itself (subagent/external-agent spawned in parallel, skills invoked,
docs read, human questions surfaced). The Tech Lead is invoked exactly once,
for judgment only: escalation flags, conflict resolution between specialists,
constraints, and the recommended approach.

This deletes the hand-parsed markdown contract between the two (the
"Parseable Phase 1/2 Output Contracts") and every parse-failure path built
around it. tech-lead.md drops from 782 to ~440 lines. Incident-analysis and
retrospective consultation move to the same single-invocation pattern, and
conduct-postmortem/facilitate-retrospective/onboard gain the Agent, Write,
and Skill grants their bodies already required.

Remove routing-outcome capture outright rather than closing the loop: an
auto-tuning registry would violate the plugin's advise-never-mandate stance,
and the write-only log had no feedback path. Deletes the Routing Value
grading rubric, the Routing Outcomes memory log, and /audit-routing-quality.

BREAKING CHANGE: tech-lead no longer emits consultation-request output;
callers that drove the two-phase protocol manually must use
/plan-implementation. /audit-routing-quality is removed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016myji5spWpb6qwqUQesXCr
Merge /re-onboard into /onboard as a --check-drift mode (same diff pass,
same confirm-before-write flow; an optional agent name scopes the check).
Fold /audit-routing-table's structural checks into /audit-agent-memory as a
tech-lead-only section, with the legacy-format MIGRATION.md ported alongside.
Remove the openspec/ directory and every live reference to it — proposals no
longer flow through openspec.

BREAKING CHANGE: /re-onboard and /audit-routing-table are removed; use
/onboard --check-drift and /audit-agent-memory tech-lead.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016myji5spWpb6qwqUQesXCr
…view findings

The target-type registry format introduced by the routing refactor was not
understood by every consumer: the onboard drift check could flag valid
human/skill/external-agent registrations as drifted and batch-delete them,
and audit-agent-memory's routing checks reported permanent false broken
pointers for them. Both now parse the target-type suffix and scope file
checks to subagent and doc entries.

Also: plan-implementation falls back to .claude/agents/ for agent files (the
default path only matched this plugin's own repo) and no longer claims an
unreadable file makes a specialist undispatchable; unknown target types are
excluded with a loud warning instead of coerced to subagent; add-specialist
discovers agents in both directories; write-convention spawns the domain
owner directly instead of emitting a consultation request nothing consumes;
agent bodies search with Glob/Grep directly instead of delegating to the
Explore subagent (subagents cannot nest); the markdownlint hook surfaces
tool failures (exit >= 2) instead of silently disabling linting; drift-check
messages never name onboarding skills that do not ship; dispatch semantics
are documented once in plan-implementation Step 4 with README and
add-specialist summarizing it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016myji5spWpb6qwqUQesXCr
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant