diff --git a/CONTEXT.md b/CONTEXT.md index d474996..54b4c69 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -49,7 +49,7 @@ The provider-agnostic always-on instruction entry point. Two files: Contains always-on rules in plain markdown with no provider-specific syntax (no `@import`). Provider-specific files (`CLAUDE.md`) are thin adapters that import the relevant `AGENTS.md` and add only Claude Code-specific syntax. This pattern means a single source of truth can serve multiple providers without duplication. See ADR-0012. ### Skill composition -A skill calling another skill by name to delegate a sub-task. The calling skill focuses on the orchestration decision ("when to do X"); the called skill owns the mechanics ("how to do X"). Established compositions: `grill-me` calls `write-adr` when a decision crystallises; `implement-feature` calls `tdd` as its implementation methodology. +A skill calling another skill by name to delegate a sub-task. The calling skill focuses on the orchestration decision ("when to do X"); the called skill owns the mechanics ("how to do X"). Established compositions: `grill-me` calls `write-adr` when a decision crystallises; `implement-feature` calls `tdd` as its implementation methodology; `forge` calls `grill-with-docs` to refine intent, classifies the target artifact type (skill / agent / plugin / marketplace entry), then routes to the matching `*-author` skill — which owns its own create/improve logic and, where applicable, its own inline audit closeout (`skill-author` runs `/skill-audit`, `agent-author` runs `kyberforge:agent-audit`, both in the same context as the authoring work). `forge` additionally runs its own independent recheck after a skill/agent route finishes: a clean-context subagent (not forked, no inherited context) re-runs the same audit skill against the finished artifact, as a distinct verification layer from the author skill's inline audit — the two can share blind spots since the inline audit runs in the same context as the work it checks. If the clean audit surfaces 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; only then is the route done. `plugin-author` and `marketplace-author` have no audit counterpart and get no recheck; their terminal check is `claude plugin validate`. ### Provider-agnostic issue tracker Skills and workflows reference "linked issue" generically rather than a specific provider. Gitea is the canonical issue tracker for this repo (see ADR-0017). "Issue" is the cross-provider term (GitHub, GitLab, Gitea all use it). diff --git a/plugins/kyberforge/skills/forge/README.md b/plugins/kyberforge/skills/forge/README.md new file mode 100644 index 0000000..4f69bf7 --- /dev/null +++ b/plugins/kyberforge/skills/forge/README.md @@ -0,0 +1,37 @@ +# forge + +Guided entry point for building or improving something in kyberforge 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. `plugin-author` and `marketplace-author` routes get no recheck: they have no audit counterpart, and their real terminal check (`claude plugin validate`) is already part of their own flow. + +## Before you start + +Have a rough idea of what you want to build or change. forge doesn't require you to already know whether it's a skill, agent, plugin, or marketplace entry — that classification is its job. + +## Usage + +``` +/forge +``` + +Skip forge and call the target skill directly (`/skill-author`, `/agent-author`, `/plugin-author`, `/marketplace-author`) when you already know the artifact type. + +## Files + +| File | Purpose | +|------|---------| +| `SKILL.md` | Skill instructions for agents | +| `references/sources.md` | Provenance chain — research sources that informed this skill | + +## Routes to + +| Artifact type | Skill | +|---|---| +| Skill | `kyberforge:skill-author` | +| Agent / subagent definition | `kyberforge:agent-author` | +| Plugin | `kyberforge:plugin-author` | +| Marketplace entry | `kyberforge:marketplace-author` | diff --git a/plugins/kyberforge/skills/forge/SKILL.md b/plugins/kyberforge/skills/forge/SKILL.md new file mode 100644 index 0000000..8d32819 --- /dev/null +++ b/plugins/kyberforge/skills/forge/SKILL.md @@ -0,0 +1,62 @@ +--- +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. +metadata: + category: factory + source_keys: + - claude-code-subagents-docs + - context7-websites-code-claude + - agentskills-spec +--- + +## Gotchas + +- forge is an optional guided entry point, not a gate — the six existing factory skills (`skill-author`, `skill-audit`, `agent-author`, `agent-audit`, `plugin-author`, `marketplace-author`) remain directly invokable and forge does not intercept those calls. +- 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. + +## 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. + +## Step 2 — Classify the artifact type + +Match the grilled intent against exactly one row (or more than one, if the intent genuinely spans several): + +| 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:plugin-author` | +| 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:marketplace-author` | + +If the intent is genuinely ambiguous between rows even after grilling, ask the user directly 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. + +## Step 3 — Announce, then route + +State the classification and which skill(s) will run before invoking anything. + +**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. `plugin-author`'s release step). Judge this from context: if nothing about the routed flow signals a live checkpoint, prefer the fork subagent. + +`plugin-author` and `marketplace-author` routes 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:marketplace-author`), chain the routes in dependency order — an artifact that must exist on disk before another skill can target it goes first (e.g. `plugin-author` creates the plugin directory before `skill-author` scaffolds a skill inside it). diff --git a/plugins/kyberforge/skills/forge/references/sources.md b/plugins/kyberforge/skills/forge/references/sources.md new file mode 100644 index 0000000..5d9aac7 --- /dev/null +++ b/plugins/kyberforge/skills/forge/references/sources.md @@ -0,0 +1,81 @@ +# Sources + +## claude-code-subagents-docs + +- **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 +- **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. +- **Contributing files:** SKILL.md +- **Status:** `extracted` + +## claude-code-plugins-docs + +- **URL:** https://code.claude.com/docs/en/plugins +- **Research doc:** plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md +- **Description:** Official Claude Code plugin authoring guide — plugin structure, manifest fields, loading methods, skill namespacing, agent activation, marketplace submission. Background context for Step 2's plugin/marketplace rows; no forge-specific content drawn directly from it beyond that. +- **Contributing files:** (none) +- **Status:** `extracted` + +## agentskills-spec + +- **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. +- **Contributing files:** SKILL.md +- **Status:** `extracted` + +## agentskills-home + +- **URL:** https://agentskills.io/home.md +- **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md +- **Description:** Agent Skills overview — not drawn on directly for forge; listed for provenance completeness against the agentskillsio research doc. +- **Contributing files:** (none) +- **Status:** `extracted` + +## agentskills-best-practices + +- **URL:** https://agentskills.io/skill-creation/best-practices.md +- **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md +- **Description:** Best practices for skill creators — not drawn on directly for forge; listed for provenance completeness against the agentskillsio research doc. +- **Contributing files:** (none) +- **Status:** `extracted` + +## agentskills-optimizing-descriptions + +- **URL:** https://agentskills.io/skill-creation/optimizing-descriptions.md +- **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md +- **Description:** How to test and improve skill descriptions for triggering accuracy — not drawn on directly for forge; listed for provenance completeness against the agentskillsio research doc. +- **Contributing files:** (none) +- **Status:** `extracted` + +## agentskills-evaluating-skills + +- **URL:** https://agentskills.io/skill-creation/evaluating-skills.md +- **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md +- **Description:** Eval-driven skill quality improvement — not drawn on directly for forge; listed for provenance completeness against the agentskillsio research doc. +- **Contributing files:** (none) +- **Status:** `extracted` + +## agentskills-using-scripts + +- **URL:** https://agentskills.io/skill-creation/using-scripts.md +- **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md +- **Description:** Using scripts in skills — not applicable to forge (no scripts/ directory); listed for provenance completeness against the agentskillsio research doc. +- **Contributing files:** (none) +- **Status:** `extracted` + +## agentskills-quickstart + +- **URL:** https://agentskills.io/skill-creation/quickstart.md +- **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md +- **Description:** Step-by-step first-skill walkthrough — not drawn on directly for forge; listed for provenance completeness against the agentskillsio research doc. +- **Contributing files:** (none) +- **Status:** `extracted`