refactor(kyberforge): move audit guidance out of the per-run rubric load

skill-audit loaded roughly 4,268 words of rubric on every run, most of it
criteria for findings a clean skill never triggers. The auditing guidance moves
into finding-criteria.md, read only when a finding is actually raised, cutting
a clean audit to about 999 words. The named-skill exemption is replaced with
properties, so the rubric stops carrying a list that ages the moment a skill
is renamed.

apm-workflow's `type:` trap sat in one flow while biting several, so it is
promoted to a common gate reachable from all of them; its claim to be
self-contained was untrue once it started routing to apm-install. skill-author's
contract had drifted from body-discipline.md and is realigned, and agent-audit's
field inventory is brought in line with the same split.
This commit is contained in:
2026-08-31 08:02:19 +00:00
parent e869912374
commit dac9cad912
42 changed files with 540 additions and 342 deletions

View File

@@ -4,7 +4,7 @@ Guided entry point for building or improving something in any plugin of this rep
## What it does
Grills the user's intent via `bin:grill-with-docs` (inline, interactive) against this repo's `CONTEXT.md` and `docs/adr/`, classifies the target artifact type (skill, agent/subagent definition, plugin, or marketplace entry), announces the classification, then routes to the matching author skill — chaining more than one, in dependency order, if the intent spans multiple artifact types.
Grills the user's intent via `grill-with-docs` (inline, interactive) against this repo's `CONTEXT.md` and `docs/adr/`, classifies the target artifact type (skill, agent/subagent definition, plugin, or marketplace entry), announces the classification, then routes to the matching author skill — chaining more than one, in dependency order, if the intent spans multiple artifact types.
Author-skill invocation defaults to a fork subagent (inherits the grilled-intent context) and falls back to inline when forking isn't possible or the routed flow needs live user interaction (clarifying questions, a HITL gate). After a `skill-author` or `agent-author` route finishes — each already closes out with its own inline audit — forge spins up a separate clean-context subagent to independently re-run the matching audit skill (`skill-audit` / `agent-audit`) as a distinct check on the finished artifact, not a duplicate of the inline one. If that clean audit turns up any unresolved finding, forge loops — re-invoke the author skill to resolve it, re-run the clean audit — until the clean audit comes back with nothing unresolved. `apm-workflow` routes (plugin, marketplace entry) get no recheck: they have no audit counterpart, and no automatic terminal check either — `apm audit` is a separate `apm-workflow` action, not a closing step of the configure or marketplace flow — so forge verifies those routes by reading the written manifest back against the grilled intent.

View File

@@ -1,12 +1,11 @@
---
name: forge
description: >
Use when the user wants to build, add, or improve something but has not yet
named the artifact type — skill, agent, plugin, or marketplace entry; "a
skill for the gitea plugin, or an agent?". Grills the intent, classifies the
artifact, then routes to the matching author skill. Do not use when the type
is already named — invoke `skill-author`, `agent-author` or `apm-workflow`
directly.
Use when the user wants to build or improve something but has not yet named
the artifact type — skill, agent, plugin, or marketplace entry; "a skill for
the gitea plugin, or an agent?". Routes to the matching author skill. Do not
use when the type is already named — invoke `skill-author`, `agent-author`
or `apm-workflow` directly.
metadata:
category: factory
source_keys:
@@ -18,11 +17,11 @@ metadata:
## Gotchas
- forge is an optional guided entry point, not a gate — `skill-author`, `skill-audit`, `agent-author`, `agent-audit` and `apm-workflow` all stay directly invokable, and forge never intercepts a direct call to one.
- Claude Code's skill-level `context: fork` frontmatter field and the `/fork` subagent command are opposites despite the shared word: `context: fork` isolates (fresh context, no parent access), while `/fork` inherits the full conversation. Every routing branch below turns on that distinction.
- Claude Code's skill-level `context: fork` frontmatter field and the `/fork` subagent command are opposites despite the shared word: `context: fork` isolates (fresh context, no parent access), while `/fork` inherits the full conversation. The route reference each classification loads spends that distinction: `references/author-routes.md` chooses between the two, `references/apm-routes.md` rules the fork out.
## Step 1 — Grill the intent
Call `bin:grill-with-docs` unless a grill session has already run and is available in the context.
Call `grill-with-docs` unless a grill session has already run and is available in the context.
Grilling regularly overturns the artifact type assumed at the start, or splits one idea into several artifacts, so it runs before classification rather than confirming it. Run it inline in the current conversation — grilling is interactive and a subagent cannot hold the back-and-forth.
@@ -48,4 +47,4 @@ When the intent spans several rows, chain the routes in dependency order — an
## Step 3 — Closing gates, common to every route
- **Resolve before closing.** A route is finished only when its verification reports nothing unresolved. An actionable finding reopens the route; it is never reported onward as a caveat.
- **Bump the package version.** If the finished route's completion message carries no evidence of a package version bump, read `references/version-bump.md`.
- **Bump the package version.** A skill route always lands here: `skill-author` moves only a skill's own `metadata.version`, which is not the package `apm.yml`'s number — so read `references/version-bump.md` after one. `agent-author` and the apm routes bump the package themselves at plugin scope; after those, read it only when their output does not say they did.

View File

@@ -5,9 +5,12 @@ source_keys:
# Bumping the package version after a route
Reached from `SKILL.md` Step 3 when a route has finished and its completion message carries no
evidence that the package version was bumped. The author skills bump it themselves in some flows,
so check their output before doing anything here — a second bump for one artifact is wrong.
Reached from `SKILL.md` Step 3 after a route has finished. A skill route always lands here:
`skill-author` moves only a skill's own `metadata.version`, which is not the package manifest's
number, so the package version is still behind when it reports done. `agent-author` bumps the
resolved package's `apm.yml` itself at plugin/APM scope, and `apm-workflow`'s configure flow
carries the same policy — read those routes' output before acting here, because a second bump for
one change is wrong.
## Find the owning package
@@ -33,5 +36,5 @@ brief:
Clean context rather than a fork is the point: the bump decision is made independently, without
anchoring on the authoring conversation that just argued for the artifact's significance.
Then report to the user: "Updated `<package-name>` version from X.Y.Z to X.Y.Z to reflect the new
`<artifact-name>`."
Then report to the user: "Updated `<package-name>` version from `<old>` to `<new>` to reflect the
new `<artifact-name>`."