From 4aab9d327c4457bed53b24144483473aacd068da Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sun, 30 Aug 2026 16:31:23 +0000 Subject: [PATCH] refactor(kyberforge): retrofit forge to the ADR-0020 contract Description 648 -> 387 chars, body 1093 -> 541 words. This was the last body FAIL in the 39-skill corpus. The body was not trimmed to fit. forge routes four artifact types that a single invocation classifies between, so the contract requires a dispatch table plus the gates common to every route, with each route self-contained in references/. Adds references/author-routes.md (skill and agent), references/apm-routes.md (plugin and marketplace entry) and references/version-bump.md. Skill and agent share one file: they differ on one axis only, which audit skill verifies the result. Fixes three defects the first pass introduced or relocated: - references/apm-routes.md claimed `apm audit` "already runs inside apm-workflow's own flow" and told the agent to confirm it ran clean. apm-workflow dispatches audit as its own row; the configure and marketplace rows never reach it. That was the only completion check these routes had, and it could never be satisfied. Replaced with a manual read-back the agent performs itself. - "Read only the reference file" forbade the multi-artifact case the same body documents two lines later, and ADR-0011 records eight artifacts authored in one pass. - The announce gate became a closing gate, reachable only after the invocation it was meant to precede. Moved to the end of Step 2. Also restores the artifact enumeration to the plugin row, normalises to bare unnamespaced skill names per AGENTS.md, adds a dispatch fallback for artifacts matching no row, and corrects three provenance entries -- one asserted a contribution that did not happen. Refs #99 Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01MWb5RQgCL1ye7cGp2RPb2u --- .../kyberforge/.apm/skills/forge/README.md | 23 +++--- plugins/kyberforge/.apm/skills/forge/SKILL.md | 81 ++++++------------- .../skills/forge/references/apm-routes.md | 42 ++++++++++ .../skills/forge/references/author-routes.md | 44 ++++++++++ .../.apm/skills/forge/references/sources.md | 8 +- .../skills/forge/references/version-bump.md | 37 +++++++++ plugins/kyberforge/skills/forge/README.md | 23 +++--- plugins/kyberforge/skills/forge/SKILL.md | 81 ++++++------------- .../skills/forge/references/apm-routes.md | 42 ++++++++++ .../skills/forge/references/author-routes.md | 44 ++++++++++ .../skills/forge/references/sources.md | 8 +- .../skills/forge/references/version-bump.md | 37 +++++++++ 12 files changed, 330 insertions(+), 140 deletions(-) create mode 100644 plugins/kyberforge/.apm/skills/forge/references/apm-routes.md create mode 100644 plugins/kyberforge/.apm/skills/forge/references/author-routes.md create mode 100644 plugins/kyberforge/.apm/skills/forge/references/version-bump.md create mode 100644 plugins/kyberforge/skills/forge/references/apm-routes.md create mode 100644 plugins/kyberforge/skills/forge/references/author-routes.md create mode 100644 plugins/kyberforge/skills/forge/references/version-bump.md diff --git a/plugins/kyberforge/.apm/skills/forge/README.md b/plugins/kyberforge/.apm/skills/forge/README.md index b8f4857..aaa8bb8 100644 --- a/plugins/kyberforge/.apm/skills/forge/README.md +++ b/plugins/kyberforge/.apm/skills/forge/README.md @@ -1,12 +1,12 @@ # forge -Guided entry point for building or improving something in kyberforge when the target artifact type isn't decided yet. +Guided entry point for building or improving something in any plugin of this repo when the target artifact type isn't decided yet. ## 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. -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 their real terminal check (`apm audit`) is already part of their own flow. +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. ## Before you start @@ -22,16 +22,19 @@ Skip forge and call the target skill directly (`/skill-author`, `/agent-author`, ## Files -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/sources.md` | Provenance chain — research sources that informed this skill | +| File | Loaded when | +|------|-------------| +| `SKILL.md` | Always — Gotchas, the grill step, the classification dispatch table, and the gates common to every route | +| `references/author-routes.md` | The intent classifies as a skill or an agent/subagent definition — fork-vs-inline judgment and the two-tier verification loop | +| `references/apm-routes.md` | The intent classifies as a plugin or a marketplace entry — always-inline invocation, why these routes get no clean-context recheck, and the manual read-back that stands in for one | +| `references/version-bump.md` | A finished route left the owning package's version unbumped — walk-up rule and the clean-context bump brief | +| `references/sources.md` | Never loaded at runtime — provenance chain for the research sources that informed this skill | ## Routes to | Artifact type | Skill | |---|---| -| Skill | `kyberforge:skill-author` | -| Agent / subagent definition | `kyberforge:agent-author` | -| Plugin | `kyberforge:apm-workflow` (configure) | -| Marketplace entry | `kyberforge:apm-workflow` (marketplace) | +| Skill | `skill-author` | +| Agent / subagent definition | `agent-author` | +| Plugin | `apm-workflow` (configure) | +| Marketplace entry | `apm-workflow` (marketplace) | diff --git a/plugins/kyberforge/.apm/skills/forge/SKILL.md b/plugins/kyberforge/.apm/skills/forge/SKILL.md index b0318e0..99de5bd 100644 --- a/plugins/kyberforge/.apm/skills/forge/SKILL.md +++ b/plugins/kyberforge/.apm/skills/forge/SKILL.md @@ -1,16 +1,12 @@ --- name: forge description: > - Use when the user wants to build, add, or improve something - but hasn't yet named which of it (skill, agent, plugin, or marketplace - entry) they need — "I want to add something to kyberforge", "not sure if - this should be a skill or a plugin", "help me figure out what to build", - "I have an idea but don't know where it belongs". Grills the intent first, - classifies the target artifact type, then routes to the matching author - skill. Do not use when the user already names the target artifact type or - skill/agent explicitly (e.g. "run /skill-author on my-skill", "create an - agent for X") — route directly to that author skill instead, bypassing - forge. + 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. metadata: category: factory source_keys: @@ -21,62 +17,35 @@ metadata: ## Gotchas -- forge is an optional guided entry point, not a gate — the four existing factory skills (`skill-author`, `skill-audit`, `agent-author`, `agent-audit`) plus `apm-workflow` (for plugin/marketplace-entry artifacts) remain directly invokable and forge does not intercept those calls. `plugin-author` and `marketplace-author` were removed per ADR-0015 once issue #90 landed — `apm-workflow` is their sole successor. -- Claude Code's skill-level `context: fork` frontmatter field and the `/fork` subagent command are opposites despite sharing a name — `context: fork` isolates (fresh context, no parent access), while `/fork` inherits the full conversation. Keep this straight when deciding how to invoke a subagent in Step 3. +- 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. ## Step 1 — Grill the intent -Call `bin:grill-with-docs` unless a grill session was already performed and is available in the context. -Grilling may surface that the artifact type assumed at the start is wrong, or that the idea splits into more than one artifact. -This step always runs inline, in the current conversation — grilling is interactive and a subagent cannot hold the back-and-forth. +Call `bin:grill-with-docs` unless a grill session has already run and is available in the context. -## Step 2 — Classify the artifact type +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. -Match the grilled intent against exactly one row (or more than one, if the intent genuinely spans several): +## Step 2 — Classify and dispatch -| Intent | Artifact type | Route to | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -----------------------------| ---------------------------------| -| A reusable capability or workflow the agent should load inline in the main conversation — triggered automatically by description-matching, not a fresh context, and free to bundle its own `references/`, `scripts/`, or `assets/` | Skill | `kyberforge:skill-author` | -| A recurring task needs its own reusable agent/subagent definition — dedicated system prompt, tools, and description, invokable by name across sessions | Agent / subagent definition | `kyberforge:agent-author` | -| A new distributable unit is needed — no existing plugin is the right home for the skill/agent/hook/MCP server being built, or the bundle needs its own manifest, versioning, and install lifecycle separate from what already exists | Plugin | `kyberforge:apm-workflow` (configure — `apm plugin init`) | -| The plugin itself already exists (or was just created) and only its marketplace-facing metadata needs to change — listing it for the first time, or updating its version/description entry — never the plugin's contents | Marketplace entry | `kyberforge:apm-workflow` (marketplace — `apm marketplace package add`) | +Match the grilled intent against exactly one row — or more than one, if the intent genuinely spans several artifacts. -If the intent is genuinely ambiguous between rows even after grilling, ask the user directly rather than guessing. +| Intent | Artifact type | Route to | Read | +|---|---|---|---| +| A reusable capability the agent loads inline in the main conversation, triggered by description-matching, free to bundle its own `references/`, `scripts/` or `assets/` | Skill | `skill-author` | `references/author-routes.md` | +| A recurring task needs its own reusable definition — dedicated system prompt, tools and description, invokable by name across sessions | Agent / subagent | `agent-author` | `references/author-routes.md` | +| A new distributable unit — no existing plugin is the right home for the skill, agent, hook or MCP server being built, or the bundle needs its own manifest, versioning and install lifecycle | Plugin | `apm-workflow` (`apm plugin init`) | `references/apm-routes.md` | +| The plugin already exists and only its marketplace-facing metadata changes — a first listing, or a version/description update, never the plugin's contents | Marketplace entry | `apm-workflow` (`apm marketplace package add`) | `references/apm-routes.md` | -Note: plugin and marketplace-entry artifacts route through `kyberforge:apm-workflow` per ADR-0015 — the former `plugin-author` and `marketplace-author` skills were removed once issue #90 landed. +The table classifies what to build, not how to run it: a one-off task that merely needs an isolated or context-inheriting run is not an artifact and has no row here. If the intent stays genuinely ambiguous between rows after grilling, ask the user rather than guessing. -This table classifies what to build, not how to run it — a one-off task that merely needs an isolated vs. context-inheriting run (rather than a new, reusable definition) isn't an artifact at all; there's nothing here to route it to. +A real artifact that matches no row — a hook, an MCP server, an AGENTS.md, a research doc — has no route here. Say so, hand the user the skill that does own it, and never bend it into a row to make the table fit. -## Step 3 — Announce, then route +When the intent spans several rows, chain the routes in dependency order — an artifact that must exist on disk before another skill can target it goes first, so `apm-workflow` scaffolds the plugin directory before `skill-author` scaffolds a skill inside it. -State the classification and which skill(s) will run before invoking anything. +**Announce, then invoke.** State the classification and which skill(s) will run. Then read the reference file for each classified artifact type — only those — and follow it. -**Invoking the author skill(s).** Default to a fork subagent — it inherits the full grilled-intent conversation, so the author skill doesn't need to be re-briefed. Fall back to an inline invocation (same conversation, no subagent) when either is true: -- **Fork is technically unavailable** — already running inside a fork (a fork cannot spawn another fork), a nesting-depth cap is reached, or the environment doesn't support forking. -- **The routed flow needs live user interaction mid-run** that a backgrounded fork can't surface in real time — clarifying questions, confirmation checkpoints, or a HITL gate (e.g. `apm-workflow`'s publish/release steps, or its conversational confirmation before removing a marketplace entry). Judge this from context: if nothing about the routed flow signals a live checkpoint, prefer the fork subagent. +## Step 3 — Closing gates, common to every route -`apm-workflow` routes for plugin/marketplace-entry artifacts always run inline — their flows are short, prompt-heavy, or gated, and get no follow-up audit-recheck step to justify running detached (see below). - -**After a skill or agent route finishes.** `skill-author` and `agent-author` already close out with their own inline audit (`skill-author` runs `/skill-audit`, `agent-author` invokes `kyberforge:agent-audit` directly) in the same context as the authoring work — that's unchanged. Once that author skill's run has finished, spin up a separate **clean-context subagent** (fresh, not forked, no inherited context) to independently re-run the same audit skill against the finished artifact. This is a distinct verification layer, not a duplicate: the inline audit shares context with the work it's checking and can share its blind spots, while the clean rerun has no stake in the result. - -If the clean audit surfaces any unresolved finding — not only a disagreement with the inline pass, any actionable finding on its own — loop: re-invoke the author skill (same fork-vs-inline judgment as the initial invocation) to resolve it, then re-run the clean audit again. Repeat until the clean audit comes back with nothing unresolved. Only then is the route done — the same resolve-before-close discipline `skill-author`/`agent-author` already apply to their own inline audit. - -When the intent spans multiple artifact types (e.g. a new skill inside a new plugin, then registering that plugin via `kyberforge:apm-workflow` marketplace), chain the routes in dependency order — an artifact that must exist on disk before another skill can target it goes first (e.g. `apm-workflow` scaffolds the plugin directory via `apm plugin init` before `skill-author` scaffolds a skill inside it). - -## Step 4 — Bump plugin version (if applicable) - -After the routed skill finishes, check if the artifact was created or updated inside a package by walking up from the artifact's path to the nearest ancestor `apm.yml` that declares a top-level `type:` field (`instructions`/`skill`/`hybrid`/`prompts`). An `apm.yml` with no `type:` field is a marketplace-only manifest (see `plugins/kyberforge/docs/research/docs/microsoft-apm/monorepo-and-repo-shapes.md`) — it does not count as a match; skip it and keep walking up. - -**Skip this step if:** -- No ancestor `apm.yml` with a `type:` field is found (the artifact is standalone or scoped to user agent directories) -- The author skill already bumped the package version (check the skill's audit output or completion message for version bump evidence) - -**If a typed `apm.yml` is found and no version bump was done:** - -Invoke `kyberforge:apm-workflow` as a **clean-context subagent** (fresh, not forked) with this brief: - -> "The package at `` gained a new `` (``). Bump the `version` field in that package's `apm.yml`. Determine whether to bump minor (0.1.0) or patch (0.0.1) based on whether this is a new capability (minor) or a fix/refactor (patch). Do not release or tag — just update `apm.yml` and commit." - -Use a clean-context subagent (not forked) so the version bump decision is made independently without anchoring to the earlier authoring context. This gives apm-workflow a clear, isolated directive. - -Report completion to the user: "Updated `` version from X.Y.Z to X.Y.Z to reflect the new ``." +- **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`. diff --git a/plugins/kyberforge/.apm/skills/forge/references/apm-routes.md b/plugins/kyberforge/.apm/skills/forge/references/apm-routes.md new file mode 100644 index 0000000..3e04823 --- /dev/null +++ b/plugins/kyberforge/.apm/skills/forge/references/apm-routes.md @@ -0,0 +1,42 @@ +--- +source_keys: + - claude-code-subagents-docs +--- + +# Routing a plugin or marketplace entry to apm-workflow + +Reached from `SKILL.md` Step 2 when the classified artifact is a plugin or a marketplace entry. +Both route to `apm-workflow` — a plugin to its configure flow (`apm plugin init`), a marketplace +entry to its marketplace flow (`apm marketplace package add`). + +No other skill is a candidate for these two rows: `plugin-author` and `marketplace-author` were +removed per ADR-0015 once issue #90 landed, and `apm-workflow` is their sole successor. + +## Always inline, never forked + +Run these routes inline, in the current conversation. Their flows are short, prompt-heavy or +gated — `apm-workflow`'s publish and release steps take a HITL gate, and removing a marketplace +entry takes a conversational confirmation — and a backgrounded fork cannot surface those +checkpoints to the user in real time. + +## No clean-context recheck, and no automatic audit + +Skill and agent routes close with a clean-context audit rerun; these two do not, and the omission +is deliberate rather than an oversight. Neither artifact type has an audit skill counterpart to +re-run, so detaching the route to earn a recheck it would never get buys nothing. + +These routes get no automated terminal check either. `apm audit` is a separate action on +`apm-workflow`'s own dispatch table, not a closing step of the configure or marketplace flow a +forge route lands in, so a completion message from either says nothing about it. Do not wait for +one and do not report one you did not see. + +Verify by hand instead. Read back what the route wrote against what the grill settled: + +- **Plugin** — the package directory exists where the intent said it should, and its `apm.yml` + carries the intended `name`, a top-level `type:` field, and a `version`. +- **Marketplace entry** — the entry names that package, points at the source the intent settled + on, and carries the version the package actually declares. + +If the change warrants the full integrity and policy check rather than a read-back, invoke +`apm-workflow` again for its audit action and run `apm audit` deliberately. Then return to +`SKILL.md` Step 3 for the closing gates common to every route. diff --git a/plugins/kyberforge/.apm/skills/forge/references/author-routes.md b/plugins/kyberforge/.apm/skills/forge/references/author-routes.md new file mode 100644 index 0000000..237debc --- /dev/null +++ b/plugins/kyberforge/.apm/skills/forge/references/author-routes.md @@ -0,0 +1,44 @@ +--- +source_keys: + - claude-code-subagents-docs +--- + +# Routing a skill or agent to its author skill + +Reached from `SKILL.md` Step 2 when the classified artifact is a skill or an agent/subagent +definition. Route a skill to `skill-author` and an agent to `agent-author`. The two branches +differ on one axis only — which audit skill verifies the result — and everything below applies to +both. + +## Choose fork or inline + +Default to a **fork subagent**. It inherits the full grilled-intent conversation, so the author +skill does not need re-briefing on what the user asked for or what the grill settled. + +Fall back to an **inline invocation** — same conversation, no subagent — when either holds: + +- **Fork is technically unavailable.** You are already running inside a fork (a fork cannot spawn + another fork), a nesting-depth cap is reached, or the environment does not support forking. +- **The routed flow needs live user interaction mid-run** that a backgrounded fork cannot surface + in real time: clarifying questions, confirmation checkpoints, or a HITL gate. Judge this from + context — if nothing about the flow signals a live checkpoint, prefer the fork. + +## Two-tier verification + +Both author skills already close out with their own inline audit, in the same context as the +authoring work: `skill-author` runs `/skill-audit`, `agent-author` invokes +`agent-audit`. That is tier one, and forge does not change it. + +Tier two belongs to forge. Once the author skill's run has finished, spin up a separate +**clean-context subagent** — fresh, not forked, no inherited context — to independently re-run the +same audit skill against the finished artifact. This is a distinct verification layer, not a +duplicate: the inline audit shares context with the work it is checking and can share its blind +spots, while the clean rerun has no stake in the result. + +If the clean audit surfaces any unresolved finding — not only a disagreement with the inline pass, +any actionable finding on its own — loop: re-invoke the author skill (same fork-versus-inline +judgment as the first invocation) to resolve it, then re-run the clean audit. Repeat until the +clean audit comes back with nothing unresolved. Only then is the route done. This is the same +resolve-before-close discipline the author skills already apply to their own inline audit. + +Return to `SKILL.md` Step 3 for the closing gates common to every route once the loop closes. diff --git a/plugins/kyberforge/.apm/skills/forge/references/sources.md b/plugins/kyberforge/.apm/skills/forge/references/sources.md index 5d9aac7..4f065b3 100644 --- a/plugins/kyberforge/.apm/skills/forge/references/sources.md +++ b/plugins/kyberforge/.apm/skills/forge/references/sources.md @@ -4,15 +4,15 @@ - **URL:** https://code.claude.com/docs/en/sub-agents - **Research doc:** plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md -- **Description:** Official Claude Code subagent reference — definition format, all frontmatter fields, scope priority, built-in agents, CLI flags, environment variables, known limitations. Grounds Step 3's fork-vs-inline invocation logic: fork inherits full conversation history via `/fork` or `subagent_type: "fork"`, is not a declarable frontmatter field on any agent definition, cannot be nested (a fork cannot spawn another fork), and is a caller-side invocation choice rather than a property of the artifact being routed to. -- **Contributing files:** SKILL.md +- **Description:** Official Claude Code subagent reference — definition format, all frontmatter fields, scope priority, built-in agents, CLI flags, environment variables, known limitations. Grounds the fork-vs-inline invocation logic in `references/author-routes.md`, the always-inline decision for the apm routes in `references/apm-routes.md`, and the clean-context bump subagent in `references/version-bump.md`: fork inherits full conversation history via `/fork` or `subagent_type: "fork"`, is not a declarable frontmatter field on any agent definition, cannot be nested (a fork cannot spawn another fork), and is a caller-side invocation choice rather than a property of the artifact being routed to. +- **Contributing files:** SKILL.md, references/author-routes.md, references/apm-routes.md, references/version-bump.md - **Status:** `extracted` ## context7-websites-code-claude - **URL:** context7:/websites/code_claude - **Research doc:** plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md -- **Description:** Official Claude Code documentation site indexed by Context7 — confirms the `context: fork` skill-level frontmatter field means isolated/fresh execution, the opposite of what the `/fork` subagent command does (inherits conversation). Informs the Gotchas entry warning against conflating the two. +- **Description:** Official Claude Code documentation site indexed by Context7 — confirms the `context: fork` skill-level frontmatter field means isolated/fresh execution, the opposite of what the `/fork` subagent command does (inherits conversation). Informs the Gotchas entry in `SKILL.md` warning against conflating the two; nothing else in this skill draws on it, and no `references/` file mentions the `context: fork` field. - **Contributing files:** SKILL.md - **Status:** `extracted` @@ -28,7 +28,7 @@ - **URL:** https://agentskills.io/specification.md - **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md -- **Description:** Complete SKILL.md format specification — confirms `assets/`, `references/`, and `scripts/` are warranted only by the bulk/reusability of supporting content (large reference material, executable code, templates), not by a skill's category. forge has none of that bulk, so a lean SKILL.md-plus-provenance-file shape is spec-legitimate; the `references/sources.md` in this directory exists for this repo's own provenance-chain convention (see `CONTEXT.md`), not because the spec requires it. +- **Description:** Complete SKILL.md format specification — confirms `assets/`, `references/`, and `scripts/` are warranted only by the bulk/reusability of supporting content (large reference material, executable code, templates), not by a skill's category, and forge's per-route procedures are that kind of supporting content — so the spec permits the `references/` split here but does not require it. The warrant is a house decision: ADR-0020's rule that dispatch is mandatory at two or more mutually exclusive flows, which forge's four-row table is. `references/sources.md` likewise exists for this repo's own provenance-chain convention (see `CONTEXT.md`), not because the spec requires it. - **Contributing files:** SKILL.md - **Status:** `extracted` diff --git a/plugins/kyberforge/.apm/skills/forge/references/version-bump.md b/plugins/kyberforge/.apm/skills/forge/references/version-bump.md new file mode 100644 index 0000000..8a9662a --- /dev/null +++ b/plugins/kyberforge/.apm/skills/forge/references/version-bump.md @@ -0,0 +1,37 @@ +--- +source_keys: + - claude-code-subagents-docs +--- + +# 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. + +## Find the owning package + +Walk up from the artifact's path to the nearest ancestor `apm.yml` that declares a top-level +`type:` field (`instructions`, `skill`, `hybrid` or `prompts`). + +An `apm.yml` with **no** `type:` field is a marketplace-only manifest: it lists packages rather +than declaring one, so it does not count as a match. Skip it and keep walking up. + +Skip this step entirely if no ancestor `apm.yml` carries a `type:` field: the artifact is then +standalone or scoped to a user agent directory, and there is no package to version. + +## Delegate the bump + +Invoke `apm-workflow` as a **clean-context subagent** — fresh, not forked — with this +brief: + +> "The package at `` gained a new `` (``). Bump the +> `version` field in that package's `apm.yml`. Determine whether to bump minor (0.1.0) or patch +> (0.0.1) based on whether this is a new capability (minor) or a fix/refactor (patch). Do not +> release or tag — just update `apm.yml` and commit." + +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 `` version from X.Y.Z to X.Y.Z to reflect the new +``." diff --git a/plugins/kyberforge/skills/forge/README.md b/plugins/kyberforge/skills/forge/README.md index b8f4857..aaa8bb8 100644 --- a/plugins/kyberforge/skills/forge/README.md +++ b/plugins/kyberforge/skills/forge/README.md @@ -1,12 +1,12 @@ # forge -Guided entry point for building or improving something in kyberforge when the target artifact type isn't decided yet. +Guided entry point for building or improving something in any plugin of this repo when the target artifact type isn't decided yet. ## 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. -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 their real terminal check (`apm audit`) is already part of their own flow. +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. ## Before you start @@ -22,16 +22,19 @@ Skip forge and call the target skill directly (`/skill-author`, `/agent-author`, ## Files -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/sources.md` | Provenance chain — research sources that informed this skill | +| File | Loaded when | +|------|-------------| +| `SKILL.md` | Always — Gotchas, the grill step, the classification dispatch table, and the gates common to every route | +| `references/author-routes.md` | The intent classifies as a skill or an agent/subagent definition — fork-vs-inline judgment and the two-tier verification loop | +| `references/apm-routes.md` | The intent classifies as a plugin or a marketplace entry — always-inline invocation, why these routes get no clean-context recheck, and the manual read-back that stands in for one | +| `references/version-bump.md` | A finished route left the owning package's version unbumped — walk-up rule and the clean-context bump brief | +| `references/sources.md` | Never loaded at runtime — provenance chain for the research sources that informed this skill | ## Routes to | Artifact type | Skill | |---|---| -| Skill | `kyberforge:skill-author` | -| Agent / subagent definition | `kyberforge:agent-author` | -| Plugin | `kyberforge:apm-workflow` (configure) | -| Marketplace entry | `kyberforge:apm-workflow` (marketplace) | +| Skill | `skill-author` | +| Agent / subagent definition | `agent-author` | +| Plugin | `apm-workflow` (configure) | +| Marketplace entry | `apm-workflow` (marketplace) | diff --git a/plugins/kyberforge/skills/forge/SKILL.md b/plugins/kyberforge/skills/forge/SKILL.md index b0318e0..99de5bd 100644 --- a/plugins/kyberforge/skills/forge/SKILL.md +++ b/plugins/kyberforge/skills/forge/SKILL.md @@ -1,16 +1,12 @@ --- name: forge description: > - Use when the user wants to build, add, or improve something - but hasn't yet named which of it (skill, agent, plugin, or marketplace - entry) they need — "I want to add something to kyberforge", "not sure if - this should be a skill or a plugin", "help me figure out what to build", - "I have an idea but don't know where it belongs". Grills the intent first, - classifies the target artifact type, then routes to the matching author - skill. Do not use when the user already names the target artifact type or - skill/agent explicitly (e.g. "run /skill-author on my-skill", "create an - agent for X") — route directly to that author skill instead, bypassing - forge. + 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. metadata: category: factory source_keys: @@ -21,62 +17,35 @@ metadata: ## Gotchas -- forge is an optional guided entry point, not a gate — the four existing factory skills (`skill-author`, `skill-audit`, `agent-author`, `agent-audit`) plus `apm-workflow` (for plugin/marketplace-entry artifacts) remain directly invokable and forge does not intercept those calls. `plugin-author` and `marketplace-author` were removed per ADR-0015 once issue #90 landed — `apm-workflow` is their sole successor. -- Claude Code's skill-level `context: fork` frontmatter field and the `/fork` subagent command are opposites despite sharing a name — `context: fork` isolates (fresh context, no parent access), while `/fork` inherits the full conversation. Keep this straight when deciding how to invoke a subagent in Step 3. +- 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. ## Step 1 — Grill the intent -Call `bin:grill-with-docs` unless a grill session was already performed and is available in the context. -Grilling may surface that the artifact type assumed at the start is wrong, or that the idea splits into more than one artifact. -This step always runs inline, in the current conversation — grilling is interactive and a subagent cannot hold the back-and-forth. +Call `bin:grill-with-docs` unless a grill session has already run and is available in the context. -## Step 2 — Classify the artifact type +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. -Match the grilled intent against exactly one row (or more than one, if the intent genuinely spans several): +## Step 2 — Classify and dispatch -| Intent | Artifact type | Route to | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -----------------------------| ---------------------------------| -| A reusable capability or workflow the agent should load inline in the main conversation — triggered automatically by description-matching, not a fresh context, and free to bundle its own `references/`, `scripts/`, or `assets/` | Skill | `kyberforge:skill-author` | -| A recurring task needs its own reusable agent/subagent definition — dedicated system prompt, tools, and description, invokable by name across sessions | Agent / subagent definition | `kyberforge:agent-author` | -| A new distributable unit is needed — no existing plugin is the right home for the skill/agent/hook/MCP server being built, or the bundle needs its own manifest, versioning, and install lifecycle separate from what already exists | Plugin | `kyberforge:apm-workflow` (configure — `apm plugin init`) | -| The plugin itself already exists (or was just created) and only its marketplace-facing metadata needs to change — listing it for the first time, or updating its version/description entry — never the plugin's contents | Marketplace entry | `kyberforge:apm-workflow` (marketplace — `apm marketplace package add`) | +Match the grilled intent against exactly one row — or more than one, if the intent genuinely spans several artifacts. -If the intent is genuinely ambiguous between rows even after grilling, ask the user directly rather than guessing. +| Intent | Artifact type | Route to | Read | +|---|---|---|---| +| A reusable capability the agent loads inline in the main conversation, triggered by description-matching, free to bundle its own `references/`, `scripts/` or `assets/` | Skill | `skill-author` | `references/author-routes.md` | +| A recurring task needs its own reusable definition — dedicated system prompt, tools and description, invokable by name across sessions | Agent / subagent | `agent-author` | `references/author-routes.md` | +| A new distributable unit — no existing plugin is the right home for the skill, agent, hook or MCP server being built, or the bundle needs its own manifest, versioning and install lifecycle | Plugin | `apm-workflow` (`apm plugin init`) | `references/apm-routes.md` | +| The plugin already exists and only its marketplace-facing metadata changes — a first listing, or a version/description update, never the plugin's contents | Marketplace entry | `apm-workflow` (`apm marketplace package add`) | `references/apm-routes.md` | -Note: plugin and marketplace-entry artifacts route through `kyberforge:apm-workflow` per ADR-0015 — the former `plugin-author` and `marketplace-author` skills were removed once issue #90 landed. +The table classifies what to build, not how to run it: a one-off task that merely needs an isolated or context-inheriting run is not an artifact and has no row here. If the intent stays genuinely ambiguous between rows after grilling, ask the user rather than guessing. -This table classifies what to build, not how to run it — a one-off task that merely needs an isolated vs. context-inheriting run (rather than a new, reusable definition) isn't an artifact at all; there's nothing here to route it to. +A real artifact that matches no row — a hook, an MCP server, an AGENTS.md, a research doc — has no route here. Say so, hand the user the skill that does own it, and never bend it into a row to make the table fit. -## Step 3 — Announce, then route +When the intent spans several rows, chain the routes in dependency order — an artifact that must exist on disk before another skill can target it goes first, so `apm-workflow` scaffolds the plugin directory before `skill-author` scaffolds a skill inside it. -State the classification and which skill(s) will run before invoking anything. +**Announce, then invoke.** State the classification and which skill(s) will run. Then read the reference file for each classified artifact type — only those — and follow it. -**Invoking the author skill(s).** Default to a fork subagent — it inherits the full grilled-intent conversation, so the author skill doesn't need to be re-briefed. Fall back to an inline invocation (same conversation, no subagent) when either is true: -- **Fork is technically unavailable** — already running inside a fork (a fork cannot spawn another fork), a nesting-depth cap is reached, or the environment doesn't support forking. -- **The routed flow needs live user interaction mid-run** that a backgrounded fork can't surface in real time — clarifying questions, confirmation checkpoints, or a HITL gate (e.g. `apm-workflow`'s publish/release steps, or its conversational confirmation before removing a marketplace entry). Judge this from context: if nothing about the routed flow signals a live checkpoint, prefer the fork subagent. +## Step 3 — Closing gates, common to every route -`apm-workflow` routes for plugin/marketplace-entry artifacts always run inline — their flows are short, prompt-heavy, or gated, and get no follow-up audit-recheck step to justify running detached (see below). - -**After a skill or agent route finishes.** `skill-author` and `agent-author` already close out with their own inline audit (`skill-author` runs `/skill-audit`, `agent-author` invokes `kyberforge:agent-audit` directly) in the same context as the authoring work — that's unchanged. Once that author skill's run has finished, spin up a separate **clean-context subagent** (fresh, not forked, no inherited context) to independently re-run the same audit skill against the finished artifact. This is a distinct verification layer, not a duplicate: the inline audit shares context with the work it's checking and can share its blind spots, while the clean rerun has no stake in the result. - -If the clean audit surfaces any unresolved finding — not only a disagreement with the inline pass, any actionable finding on its own — loop: re-invoke the author skill (same fork-vs-inline judgment as the initial invocation) to resolve it, then re-run the clean audit again. Repeat until the clean audit comes back with nothing unresolved. Only then is the route done — the same resolve-before-close discipline `skill-author`/`agent-author` already apply to their own inline audit. - -When the intent spans multiple artifact types (e.g. a new skill inside a new plugin, then registering that plugin via `kyberforge:apm-workflow` marketplace), chain the routes in dependency order — an artifact that must exist on disk before another skill can target it goes first (e.g. `apm-workflow` scaffolds the plugin directory via `apm plugin init` before `skill-author` scaffolds a skill inside it). - -## Step 4 — Bump plugin version (if applicable) - -After the routed skill finishes, check if the artifact was created or updated inside a package by walking up from the artifact's path to the nearest ancestor `apm.yml` that declares a top-level `type:` field (`instructions`/`skill`/`hybrid`/`prompts`). An `apm.yml` with no `type:` field is a marketplace-only manifest (see `plugins/kyberforge/docs/research/docs/microsoft-apm/monorepo-and-repo-shapes.md`) — it does not count as a match; skip it and keep walking up. - -**Skip this step if:** -- No ancestor `apm.yml` with a `type:` field is found (the artifact is standalone or scoped to user agent directories) -- The author skill already bumped the package version (check the skill's audit output or completion message for version bump evidence) - -**If a typed `apm.yml` is found and no version bump was done:** - -Invoke `kyberforge:apm-workflow` as a **clean-context subagent** (fresh, not forked) with this brief: - -> "The package at `` gained a new `` (``). Bump the `version` field in that package's `apm.yml`. Determine whether to bump minor (0.1.0) or patch (0.0.1) based on whether this is a new capability (minor) or a fix/refactor (patch). Do not release or tag — just update `apm.yml` and commit." - -Use a clean-context subagent (not forked) so the version bump decision is made independently without anchoring to the earlier authoring context. This gives apm-workflow a clear, isolated directive. - -Report completion to the user: "Updated `` version from X.Y.Z to X.Y.Z to reflect the new ``." +- **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`. diff --git a/plugins/kyberforge/skills/forge/references/apm-routes.md b/plugins/kyberforge/skills/forge/references/apm-routes.md new file mode 100644 index 0000000..3e04823 --- /dev/null +++ b/plugins/kyberforge/skills/forge/references/apm-routes.md @@ -0,0 +1,42 @@ +--- +source_keys: + - claude-code-subagents-docs +--- + +# Routing a plugin or marketplace entry to apm-workflow + +Reached from `SKILL.md` Step 2 when the classified artifact is a plugin or a marketplace entry. +Both route to `apm-workflow` — a plugin to its configure flow (`apm plugin init`), a marketplace +entry to its marketplace flow (`apm marketplace package add`). + +No other skill is a candidate for these two rows: `plugin-author` and `marketplace-author` were +removed per ADR-0015 once issue #90 landed, and `apm-workflow` is their sole successor. + +## Always inline, never forked + +Run these routes inline, in the current conversation. Their flows are short, prompt-heavy or +gated — `apm-workflow`'s publish and release steps take a HITL gate, and removing a marketplace +entry takes a conversational confirmation — and a backgrounded fork cannot surface those +checkpoints to the user in real time. + +## No clean-context recheck, and no automatic audit + +Skill and agent routes close with a clean-context audit rerun; these two do not, and the omission +is deliberate rather than an oversight. Neither artifact type has an audit skill counterpart to +re-run, so detaching the route to earn a recheck it would never get buys nothing. + +These routes get no automated terminal check either. `apm audit` is a separate action on +`apm-workflow`'s own dispatch table, not a closing step of the configure or marketplace flow a +forge route lands in, so a completion message from either says nothing about it. Do not wait for +one and do not report one you did not see. + +Verify by hand instead. Read back what the route wrote against what the grill settled: + +- **Plugin** — the package directory exists where the intent said it should, and its `apm.yml` + carries the intended `name`, a top-level `type:` field, and a `version`. +- **Marketplace entry** — the entry names that package, points at the source the intent settled + on, and carries the version the package actually declares. + +If the change warrants the full integrity and policy check rather than a read-back, invoke +`apm-workflow` again for its audit action and run `apm audit` deliberately. Then return to +`SKILL.md` Step 3 for the closing gates common to every route. diff --git a/plugins/kyberforge/skills/forge/references/author-routes.md b/plugins/kyberforge/skills/forge/references/author-routes.md new file mode 100644 index 0000000..237debc --- /dev/null +++ b/plugins/kyberforge/skills/forge/references/author-routes.md @@ -0,0 +1,44 @@ +--- +source_keys: + - claude-code-subagents-docs +--- + +# Routing a skill or agent to its author skill + +Reached from `SKILL.md` Step 2 when the classified artifact is a skill or an agent/subagent +definition. Route a skill to `skill-author` and an agent to `agent-author`. The two branches +differ on one axis only — which audit skill verifies the result — and everything below applies to +both. + +## Choose fork or inline + +Default to a **fork subagent**. It inherits the full grilled-intent conversation, so the author +skill does not need re-briefing on what the user asked for or what the grill settled. + +Fall back to an **inline invocation** — same conversation, no subagent — when either holds: + +- **Fork is technically unavailable.** You are already running inside a fork (a fork cannot spawn + another fork), a nesting-depth cap is reached, or the environment does not support forking. +- **The routed flow needs live user interaction mid-run** that a backgrounded fork cannot surface + in real time: clarifying questions, confirmation checkpoints, or a HITL gate. Judge this from + context — if nothing about the flow signals a live checkpoint, prefer the fork. + +## Two-tier verification + +Both author skills already close out with their own inline audit, in the same context as the +authoring work: `skill-author` runs `/skill-audit`, `agent-author` invokes +`agent-audit`. That is tier one, and forge does not change it. + +Tier two belongs to forge. Once the author skill's run has finished, spin up a separate +**clean-context subagent** — fresh, not forked, no inherited context — to independently re-run the +same audit skill against the finished artifact. This is a distinct verification layer, not a +duplicate: the inline audit shares context with the work it is checking and can share its blind +spots, while the clean rerun has no stake in the result. + +If the clean audit surfaces any unresolved finding — not only a disagreement with the inline pass, +any actionable finding on its own — loop: re-invoke the author skill (same fork-versus-inline +judgment as the first invocation) to resolve it, then re-run the clean audit. Repeat until the +clean audit comes back with nothing unresolved. Only then is the route done. This is the same +resolve-before-close discipline the author skills already apply to their own inline audit. + +Return to `SKILL.md` Step 3 for the closing gates common to every route once the loop closes. diff --git a/plugins/kyberforge/skills/forge/references/sources.md b/plugins/kyberforge/skills/forge/references/sources.md index 5d9aac7..4f065b3 100644 --- a/plugins/kyberforge/skills/forge/references/sources.md +++ b/plugins/kyberforge/skills/forge/references/sources.md @@ -4,15 +4,15 @@ - **URL:** https://code.claude.com/docs/en/sub-agents - **Research doc:** plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md -- **Description:** Official Claude Code subagent reference — definition format, all frontmatter fields, scope priority, built-in agents, CLI flags, environment variables, known limitations. Grounds Step 3's fork-vs-inline invocation logic: fork inherits full conversation history via `/fork` or `subagent_type: "fork"`, is not a declarable frontmatter field on any agent definition, cannot be nested (a fork cannot spawn another fork), and is a caller-side invocation choice rather than a property of the artifact being routed to. -- **Contributing files:** SKILL.md +- **Description:** Official Claude Code subagent reference — definition format, all frontmatter fields, scope priority, built-in agents, CLI flags, environment variables, known limitations. Grounds the fork-vs-inline invocation logic in `references/author-routes.md`, the always-inline decision for the apm routes in `references/apm-routes.md`, and the clean-context bump subagent in `references/version-bump.md`: fork inherits full conversation history via `/fork` or `subagent_type: "fork"`, is not a declarable frontmatter field on any agent definition, cannot be nested (a fork cannot spawn another fork), and is a caller-side invocation choice rather than a property of the artifact being routed to. +- **Contributing files:** SKILL.md, references/author-routes.md, references/apm-routes.md, references/version-bump.md - **Status:** `extracted` ## context7-websites-code-claude - **URL:** context7:/websites/code_claude - **Research doc:** plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md -- **Description:** Official Claude Code documentation site indexed by Context7 — confirms the `context: fork` skill-level frontmatter field means isolated/fresh execution, the opposite of what the `/fork` subagent command does (inherits conversation). Informs the Gotchas entry warning against conflating the two. +- **Description:** Official Claude Code documentation site indexed by Context7 — confirms the `context: fork` skill-level frontmatter field means isolated/fresh execution, the opposite of what the `/fork` subagent command does (inherits conversation). Informs the Gotchas entry in `SKILL.md` warning against conflating the two; nothing else in this skill draws on it, and no `references/` file mentions the `context: fork` field. - **Contributing files:** SKILL.md - **Status:** `extracted` @@ -28,7 +28,7 @@ - **URL:** https://agentskills.io/specification.md - **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md -- **Description:** Complete SKILL.md format specification — confirms `assets/`, `references/`, and `scripts/` are warranted only by the bulk/reusability of supporting content (large reference material, executable code, templates), not by a skill's category. forge has none of that bulk, so a lean SKILL.md-plus-provenance-file shape is spec-legitimate; the `references/sources.md` in this directory exists for this repo's own provenance-chain convention (see `CONTEXT.md`), not because the spec requires it. +- **Description:** Complete SKILL.md format specification — confirms `assets/`, `references/`, and `scripts/` are warranted only by the bulk/reusability of supporting content (large reference material, executable code, templates), not by a skill's category, and forge's per-route procedures are that kind of supporting content — so the spec permits the `references/` split here but does not require it. The warrant is a house decision: ADR-0020's rule that dispatch is mandatory at two or more mutually exclusive flows, which forge's four-row table is. `references/sources.md` likewise exists for this repo's own provenance-chain convention (see `CONTEXT.md`), not because the spec requires it. - **Contributing files:** SKILL.md - **Status:** `extracted` diff --git a/plugins/kyberforge/skills/forge/references/version-bump.md b/plugins/kyberforge/skills/forge/references/version-bump.md new file mode 100644 index 0000000..8a9662a --- /dev/null +++ b/plugins/kyberforge/skills/forge/references/version-bump.md @@ -0,0 +1,37 @@ +--- +source_keys: + - claude-code-subagents-docs +--- + +# 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. + +## Find the owning package + +Walk up from the artifact's path to the nearest ancestor `apm.yml` that declares a top-level +`type:` field (`instructions`, `skill`, `hybrid` or `prompts`). + +An `apm.yml` with **no** `type:` field is a marketplace-only manifest: it lists packages rather +than declaring one, so it does not count as a match. Skip it and keep walking up. + +Skip this step entirely if no ancestor `apm.yml` carries a `type:` field: the artifact is then +standalone or scoped to a user agent directory, and there is no package to version. + +## Delegate the bump + +Invoke `apm-workflow` as a **clean-context subagent** — fresh, not forked — with this +brief: + +> "The package at `` gained a new `` (``). Bump the +> `version` field in that package's `apm.yml`. Determine whether to bump minor (0.1.0) or patch +> (0.0.1) based on whether this is a new capability (minor) or a fix/refactor (patch). Do not +> release or tag — just update `apm.yml` and commit." + +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 `` version from X.Y.Z to X.Y.Z to reflect the new +``."