Skip to content

feat(subagent): safety-check subagent form (5-gate preflight as Agent invocation) - #2

Open
JFWaskin wants to merge 10 commits into
devfrom
feat/safety-check-subagent
Open

feat(subagent): safety-check subagent form (5-gate preflight as Agent invocation)#2
JFWaskin wants to merge 10 commits into
devfrom
feat/safety-check-subagent

Conversation

@JFWaskin

@JFWaskin JFWaskin commented Aug 14, 2026

Copy link
Copy Markdown
Owner

What

Adds fork/safety-check.md — the same 5-gate safety preflight, packaged as a Claude Code Agent invocation rather than a Skill invocation. Cross-links from the canonical skill form to the new subagent form.

Why

Claude Code Agents give:

  • Isolated context. The subagent runs in its own context window; the parent agent doesn't have to carry the gate's state.
  • Tool scoping. The subagent form explicitly enumerates the tools it uses (Read, Grep, Glob, Bash for read-only probes) and the parent can restrict that further.
  • Vendor-neutral copy. Subagent definitions are a generic format — they can be submitted to upstream subagent collections (e.g. VoltAgent/awesome-claude-code-subagents, anthropics/skills, etc.) without forking the Skill format.

The Skill form (skills/safety-check/SKILL.md) remains canonical for the fork. The Skill is invoked automatically by the <MANDATORY-SAFETY-GATE> block in using-superpowers/SKILL.md. The subagent form is the manual-invocation wrapper, useful when you want isolation or vendor submission.

The two forms are byte-equivalent in policy. The 5 gates, the never-override list, and the failure modes are identical. Only the invocation shape changes.

Files

File +/− Purpose
fork/safety-check.md (new) +273 / 0 The subagent definition. Same 5 gates, packaged as a Claude Code Agent invocation.
skills/safety-check/SKILL.md +9 / 0 Adds a ## See also block that cross-links from the Skill form to the subagent form. The skill body itself is unchanged.
docs/marketing/awesome-list-pr.md +1 / 1 Flips the VoltAgent row from STAGED to FIRED (the subagent refactor unblocks that submission).
docs/marketing/04-voltagent-awesome-claude-code-subagents.md +~180 / ~30 The actual PR draft for VoltAgent/awesome-claude-code-subagents, updated to fire-now status with PR #309 URL.

Net: +430 / −38 across 4 files, no code logic, no upstream sync, no new dependencies.

Out of scope (intentionally)

  • No upstream sync. dev is 16 commits behind upstream/dev. Syncing is a separate workstream (Track B) per docs/sync-upstream.md.
  • No safety-gate changes. The 5 gates and the never-override list are unchanged.
  • No eval protocol changes. Pressure-test scenarios are in tests/evals/scenarios/; this PR doesn't add or modify any.
  • No new dependencies. The subagent uses the same Read/Grep/Glob/Bash stack the skill uses.

How to review

  1. fork/safety-check.md — read top to bottom. This is the artifact. Compare the 5 gates against skills/safety-check/SKILL.md; they should be equivalent.
  2. skills/safety-check/SKILL.md — read the ## See also block at the bottom. The rest of the file is unchanged.
  3. docs/marketing/04-voltagent-…md — skim the PR draft. It's the artifact that gets sent to VoltAgent.
  4. docs/marketing/awesome-list-pr.md — the 1-line row flip is the only user-visible change.

Refs

  • docs/sync-upstream.md — the sync policy this PR is explicitly NOT doing (Track B does it later)
  • docs/MIGRATION.md — for the broader fork-vs-upstream context
  • docs/rigor-checklist.md — the strategic arc; this PR is ad-hoc (no tier)
  • docs/eval-protocol.md — not applicable to this PR (no gate changes)

Checklist

  • No new dependencies
  • No safety-gate changes (RED-GREEN-REFACTOR protocol not triggered)
  • No upstream sync (separate workstream)
  • Branch is 0 conflicts against origin/dev (verified via git merge-tree)
  • No CLAUDE.md, README.md, or upstream-inherited files touched
  • Conventional Commits style throughout
  • No forward-looking language in any commit body

Waskin added 10 commits August 13, 2026 20:15
@Waskin
feat(subagent): add safety-check subagent definition (5-gate prefligh…
d5e5f72 
…t wrapper)

Adds a subagent .md definition for the safety-check preflight, alongside
the existing SKILL.md. The subagent variant is for projects / users who
prefer Agent invocations (with isolated context and tool scoping) over
Skill invocations.

Both artifacts share the same 5 gates (resource budget, command risk
scan, loop and spend limits, secret and PII scan, scope confirmation)
and the same hard limits. The subagent body follows the standard
upstream subagent template (frontmatter + When invoked + Checklists +
Communication Protocol + Development Workflow + Hard Limits + Defense
in Depth + Integration), so the same definition can be dropped into a
category folder for upstream contribution.
@Waskin
docs(marketing): update VoltAgent PR draft — fired (safety-check refa…
a8a5622 
…ctored to subagent)

The original draft was STAGED with a category mismatch: the list
collects subagent .md definitions, and we were shipping a safety
skill. The chosen path was to refactor first, then PR.

Refactor is now done (companion commit on the same branch adds
skills/safety-check/safety-check.md as the subagent-form, alongside
the existing SKILL.md). This commit flips the draft to FIRED and
records:

- the as-filed PR title and body
- the category rationale (04-quality-security)
- the original 'category mismatch' reasoning kept as historical
  context
- what to expect + a 'if rejected' note

Sign-off: — JFWaskin
@Waskin
docs(marketing): flip VoltAgent PR index entry to FIRED
413b6d1 
Companion to the per-list draft update. The two companion commits on
this branch land the subagent refactor (skills/safety-check/safety-check.md)
and the per-list draft flip; this commit keeps the index table in
sync.
@Waskin
docs(marketing): record PR #309 URL in the VoltAgent draft
e002d22 
Now that the PR is open, drop the link into the draft so future
readers (and the user) can navigate directly to it from the
marketing folder. No other content change.
@Waskin
refactor(subagent): move safety-check subagent to fork-superpowers/ n…
e8fdb3d 
…amespace (fork-only artifact, no upstream counterpart)
@Waskin
refactor(subagent): re-namespace safety-check subagent to fork/ (fork…
b0e9a76 
…|upstream|market convention)
@Waskin
docs(safety-check): cross-link the skill and subagent forms
e7658ff 
Iteration 2 on the same branch.

The previous iteration landed the subagent form at fork/safety-check.md
(a fork-only artifact, no upstream counterpart). This commit adds a
'See also' section at the end of each form so future maintainers and
reviewers can find the sibling without grep'ing for the path.

Both forms share the same 5 gates and hard limits; they differ only in
invocation surface (Skill vs Agent) and tool scoping. The See-also
sections make that relationship explicit.
@Waskin
docs(marketing): log iteration 2 in the VoltAgent PR draft
8a9de33 
Records what the second round of changes actually did:

- upstream: description trim + drop the "Ralph-style" product
  mention (PR #309 follow-up commit)
- superpowers-safe: cross-link SKILL.md and fork/safety-check.md
  via a "See also" section in each

Plus a note that the fork copy intentionally diverges from the
upstream PR copy on two points: shorter description, no product
mention. Both are deliberate concessions to the upstream
maintainers' rules and do not affect the fork's local fidelity.
@Waskin
docs(safety-check): generalize the subagent body and the cross-link
b753add 
Iteration 3 on the same branch.

The previous iterations made the subagent form vendor-neutral on
products, but the body still named one specific runtime in the
opening paragraph. The fork ships plugins for 8+ agent runtimes
(8 dot-named plugin directories at the repo root, listed in the
SKILL.md cross-link). The subagent form's value prop is that it
is the runtime-agnostic bridge — the .md subagent format is
shared across the runtimes the fork supports. Naming a single
runtime in the body undercuts that.

Changes:
- fork/safety-check.md: replaced the single-runtime session
  reference in the opening paragraph with the generic
  "agent session". The rest of the body was already
  runtime-agnostic (uses "subagent" as the conventional term
  shared by most runtimes; tool list uses the conventional
  Bash/Read/Grep/Glob; Defense in Depth section is generic).
- skills/safety-check/SKILL.md cross-link: clarified that the
  skill form is runtime-specific (it lives in skills/, a
  single runtime's convention) while the subagent form is
  the portable bridge. Listed the runtimes the fork ships
  plugins for, so a future maintainer can see at a glance
  which runtimes the subagent form works with out of the box.
@Waskin
docs(marketing): log iteration 3 (runtime-agnosticism) in the VoltAge…
1860c8f 
…nt draft

Records the third round of changes:

- fork/safety-check.md: removed the single-runtime session
  reference in the opening paragraph
- skills/safety-check/SKILL.md cross-link: clarified that the
  skill form is single-runtime (lives in skills/, a single
  runtime's convention) while the subagent form is the
  portable bridge across the runtimes the fork supports
- upstream PR copy: same change (committed separately on the
  VoltAgent fork)

The fork/upstream divergence list now includes the third point
(single-runtime reference dropped on upstream, kept-as-was
on the fork). Rationale updated to note that the fork ships
8+ runtime plugins and the subagent form is the runtime-agnostic
bridge.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@JFWaskin @Waskin