refactor!: delegate skill workflows to plugin-scoped subagents #4

Merged

claudiomaradonna merged 5 commits from refactor/subagent-architecture into main 2026-05-13 11:34:58 +02:00

Conversation 0 Commits 5 Files changed 8 +698 -330

claudiomaradonna commented 2026-05-13 11:34:29 +02:00

Owner

Copy link

The three skill SKILL.md files (~17 KB total) used to load into the main
session on every invocation and persist in the conversation history until
compaction. This PR moves each workflow body into a plugin-scoped subagent
(agents/commit-worker.md, agents/push-worker.md, agents/pr-worker.md)
and rewrites each SKILL.md as a thin orchestrator (~9 KB total, -49%) that
drives a two-pass exchange: mode=propose returns a structured plan, the
orchestrator surfaces it via AskUserQuestion in main, mode=execute
carries out the approval. The heavy workflow body now lives inside the
subagent's isolated context and is discarded when the subagent terminates,
so main only ever holds the thin router plus the short summary artifacts.
Frontmatter descriptions are tightened too (-25% off the pre-refactor
baseline) to cut the persistent system-reminder cost. Requires a Claude
Code runtime that supports plugin-scoped agents at
<plugin-root>/agents/<name>.md — documented in a new README Architecture
section

The three skill SKILL.md files (~17 KB total) used to load into the main session on every invocation and persist in the conversation history until compaction. This PR moves each workflow body into a plugin-scoped subagent (`agents/commit-worker.md`, `agents/push-worker.md`, `agents/pr-worker.md`) and rewrites each SKILL.md as a thin orchestrator (~9 KB total, -49%) that drives a two-pass exchange: `mode=propose` returns a structured plan, the orchestrator surfaces it via `AskUserQuestion` in main, `mode=execute` carries out the approval. The heavy workflow body now lives inside the subagent's isolated context and is discarded when the subagent terminates, so main only ever holds the thin router plus the short summary artifacts. Frontmatter descriptions are tightened too (-25% off the pre-refactor baseline) to cut the persistent system-reminder cost. Requires a Claude Code runtime that supports plugin-scoped agents at `<plugin-root>/agents/<name>.md` — documented in a new README Architecture section

claudiomaradonna added 5 commits 2026-05-13 11:34:30 +02:00

refactor(commit)!: delegate /commit workflow to commit-worker subagent ... 0309cc4323

Move the full /commit workflow out of the SKILL.md body and into a
plugin-scoped subagent at `agents/commit-worker.md`. The skill now
acts as a thin orchestrator that drives a two-pass exchange with the
subagent:

  pass 1 (mode=propose) — pre-flight, signing pre-flight, branch and
  atomic-commit grouping analysis, returning a human summary plus an
  opaque YAML plan;
  user checkpoint — `AskUserQuestion` in the main session to
  approve / edit / cancel the proposal;
  pass 2 (mode=execute) — branch setup, hunk-level or whole-file
  staging, signed commits as approved.

Motivation: when invoked, the previous monolithic SKILL.md (~7,200
char after the recent signing pre-flight expansion) loaded into the
main session context in full and persisted there for every subsequent
turn. With the subagent split, the main session only ever holds the
~3,400-char thin router plus the two short summaries; the heavy
workflow body lives inside the subagent's isolated context and is
discarded when the subagent terminates.

The two-pass design (rather than letting the subagent call
AskUserQuestion itself mid-run) keeps the user-approval checkpoint in
the main session where AskUserQuestion is known to work, and avoids
depending on subagent capabilities that aren't documented.

BREAKING CHANGE: requires a Claude Code runtime that supports
plugin-scoped agents under `<plugin-root>/agents/<name>.md`. Users on
older runtimes won't see the subagent and the skill will fail; this
is the only path the maintainer is willing to ship — see the
companion `/push` and `/pr` refactors in this branch.

refactor(push)!: delegate /push workflow to push-worker subagent ... dfd3e13c53

Mirror the commit-worker pattern from 0309cc4: move the full /push
workflow out of the SKILL.md body and into a plugin-scoped subagent
at `agents/push-worker.md`. The skill becomes a thin orchestrator
that drives a two-pass exchange:

  pass 1 (mode=resolve) — pre-flight, remote resolution, list of
  commits to publish, and the courtesy compare-URL hint, returned as
  a human summary plus an opaque YAML plan;
  user checkpoint — `AskUserQuestion` in the main session to
  confirm push / cancel;
  pass 2 (mode=push) — actual `git push` (with `-u` if no upstream),
  returning the result.

Motivation: keep the workflow body out of the main session context so
it doesn't persist in the conversation history after invocation. The
push variant of the savings is smaller in absolute terms (the
original SKILL.md was only ~3,100 char) but the architectural
consistency with /commit and the upcoming /pr refactor is what
matters: every workflow body lives in its dedicated subagent, main
only ever sees thin orchestration.

BREAKING CHANGE: requires a Claude Code runtime that supports
plugin-scoped agents under `<plugin-root>/agents/<name>.md`.

refactor(pr)!: delegate /pr workflow to pr-worker subagent ... eec0e8274e

Mirror the commit-worker and push-worker pattern: move the full /pr
workflow out of the SKILL.md body and into a plugin-scoped subagent
at `agents/pr-worker.md`. The skill becomes a thin orchestrator that
drives a two-pass exchange:

  pass 1 (mode=compose) — pre-flight, provider detection (host
  patterns, existing CLI logins, env-var bootstrap), check for an
  existing open PR/MR, compose a Conventional-Commits-aligned title
  and motivation-focused body. Returns a human summary plus an opaque
  YAML plan;
  user checkpoint — `AskUserQuestion` in the main session to
  approve / edit / cancel;
  pass 2 (mode=open) — opens the PR/MR via `gh`/`glab`/`tea`, or
  emits the compare URL fallback with title and body to paste.

This is the largest body win of the three refactors: the previous
SKILL.md (~7,500 char including the §5 prose examples and §2b/2c
self-hosted bootstrap procedure) drops to a ~3,500-char thin router
in main. All the rare-path detail — env-var bootstrap, full body
examples, sectioned-body criterion — lives in the subagent context
and is only paid when /pr actually fires.

BREAKING CHANGE: requires a Claude Code runtime that supports
plugin-scoped agents under `<plugin-root>/agents/<name>.md`.
Completes the subagent-delegation chain across all three skills
(/commit → /push → /pr).

perf(skills): tighten frontmatter descriptions across the three skills ... 0b5525e661

The refactor commits 0309cc4 / dfd3e13 / eec0e82 inflated each
skill's frontmatter `description` by adding internal-implementation
prose ("delegates execution to the X subagent so the full workflow
never enters the main session context"). The description field is
loaded into the Claude Code skills system reminder at session start
and pays a persistent context cost on every session — implementation
detail belongs in the body, not the description.

Drop the subagent-delegation prose and tighten the user-facing
signal. Aggregate length goes from 1,280 char (post-refactor
inflation) to 692 char — a ~46% trim of the persistent layer, and
~26% smaller than the pre-refactor baseline of 929 char.

Auto-match signal preserved: each description still leads with
"Invoke to <verb>", names the workflow's core constraint, and points
to the next skill in the chain.

chore(release): bump to 0.7.0 and document subagent architecture ... dd828093fe

The 0.7.0 line wraps the subagent-delegation refactor across the
three skills (0309cc4, dfd3e13, eec0e82) and the description-tightening
pass (0b5525e). The architectural change is significant enough to
warrant a minor version bump rather than a patch — and to require a
note in the README so users understand why each skill now goes
through a worker subagent and what runtime support that assumes.

Add an "Architecture" section to the README describing the two-pass
pattern (propose → user checkpoint → execute), the motivation
(keeping the workflow body out of the main session context), and the
runtime requirement (plugin-scoped agents under
`<plugin-root>/agents/<name>.md`).

claudiomaradonna merged commit dd828093fe into main 2026-05-13 11:34:58 +02:00

claudiomaradonna deleted branch refactor/subagent-architecture 2026-05-13 11:35:01 +02:00

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

claudiomaradonna/claude-plugin-conventional-commit!4

No description provided.