菜单
Convert acceptance criteria, Jira tickets, Gherkin scenarios, PRDs, or any product requirements into a filled-in spec under specs/ using this repo's templates. Use when translating PM artifacts or informal asks into an add, change, migrate, or remove spec ready for implementation.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Update the okf/ knowledge bundle after a change to the system — the touched concepts, their index entries, the affected diagrams, and the bundle log. Use at the end of any change that alters system shape (an agent, a Kind, a route, a check name, a package, an env var, a port convention), or standalone when the bundle has drifted from reality.
Scaffold a new deterministic, agent-free tooling package on the modern pair, with tests and its knowledge concept. Use when the system needs a new platform capability (an API client, ingress, transport, notifier-style package) rather than a new workflow.
Scaffold a new workflow agent end-to-end on the modern pair — ingest Kind, dispatcher registration, agent package, tests, webhook route, and the knowledge updates. Use when adding an entirely new workflow (a new fixer, digest, or reviewer-style agent) to the system.
Interview the user one question at a time to resolve every unfilled marker in a spec file (`<!-- TODO -->`, raw template placeholder prose, `<YYYY-MM-DD>`-style header stubs, empty plan steps, unconfirmed reverse-spec presumptions). Use on hand-authored specs, stale specs, or when the user says "grill me" or "stress-test this plan". The conversion skills (/ac-to-spec, /reverse-spec) embed this logic inline, so freshly-converted specs don't need a separate pass. Recommends an answer for every question, explores the codebase and okf bundle instead of asking when it can, and writes resolutions back with a Decisions log.
Execute a library, API, or framework swap on a port — mechanical migration that preserves observable behavior, verified against the shipped API. Use when bumping a major SDK version (e.g. the ADK), swapping a library, or moving to a new provider API.
Reverse-engineer a spec from existing code — reconstructs presumed intent, event flow, external contracts, config, and business rules by reading source, tests, prompts, and git history. Use when inheriting undocumented behavior, onboarding onto a workflow agent or platform package, checking modern-pair drift, or capturing a baseline before a change or migration.
| name | ac-to-spec |
| description | Convert acceptance criteria, Jira tickets, Gherkin scenarios, PRDs, or any product requirements into a filled-in spec under specs/ using this repo's templates. Use when translating PM artifacts or informal asks into an add, change, migrate, or remove spec ready for implementation. |
Translate product requirements — in any format — into a filled-in spec from
.agents/templates/, saved under specs/ and grilled clean before handoff.
Parameters: spec kind (optional — inferred from content if omitted)
Usage examples:
/ac-to-spec @ticket.md # infer kind from content
/ac-to-spec add @prd-excerpt.md # explicit: new capability
/ac-to-spec change @gherkin.feature # explicit: change spec
/ac-to-spec migrate # paste inline, explicit kind
/ac-to-spec remove @slack-thread.txt # explicit: removal spec
| Kind | Template | When to use |
|---|---|---|
add | .agents/templates/add.spec.md | Building something that doesn't exist yet |
change | .agents/templates/change.spec.md | Modifying, enhancing, or fixing existing behavior |
migrate | .agents/templates/migrate.spec.md | Swapping providers/libraries, restructuring, moving state |
remove | .agents/templates/remove.spec.md | Deprecating, killing, or cleaning up existing code |
Scaffold with make spec name=<slug> kind=<add|remove|change|migrate> (run from a port
directory, e.g. go/), or write specs/<YYYYMMDD>-<slug>.md directly matching the
template. specs/ is gitignored dev memory — never reference a spec from code,
standards, or the okf bundle; only other specs may reference specs.
Ground technical sections in the bundle — cite concepts, never copy their content in:
okf/orientation/what-this-system-is.md — what the system does; event flow contextokf/standards/language-parity.md — two-pair contract (modern Go/Python, frozen Kotlin/TS)okf/standards/architecture-design.md — language-neutral design; the ingest→root→workflow pathokf/standards/webhooks.md — webhook routes and check names (external contracts, all four ports)okf/orientation/suspend-resume-design.md — durable park/resume designokf/standards/testing.md — coverage floor, no LLM-output assertionsokf/standards/documentation.md — which okf concepts/diagrams must move with a changeokf/modules/agents/*.md — per-agent concepts (fixflow, reviewer, summary, ...)Accepts any of these — no preprocessing required: Gherkin (Given/When/Then),
Jira ticket (title, description, AC checklist), PRD prose, user stories,
bullet lists from Slack/email/notes, free text. Extract structure from whatever
is provided.
The grill step (step 7) runs inline. For specs spanning more than one workflow agent
or both modern ports' internals, dispatch one Explore agent IN PARALLEL with the
grill so the dialog isn't blocked on serial codebase reads:
For a spec touching {agents/packages}, report per unit:
- Current shape from its okf/modules/ concept and the code itself.
- Recent changes in the spec's domain (last 5 commits to that directory).
- Env vars, webhook routes, or check names it owns.
Return findings only — do NOT modify the spec.
For single-agent or single-package specs, direct reads are faster than briefing a subagent.
The user provides requirements via @file or inline paste. Read the full content.
If the user specified a kind, use it. Otherwise infer from content signals:
| Signal | Inferred kind |
|---|---|
| "build", "create", "add new", "introduce", named capability with no existing code | add |
| "change", "update", "enhance", "fix", "modify", references existing behavior | change |
| "migrate", "swap", "upgrade", "replace X with Y", "restructure", "move state" | migrate |
| "remove", "deprecate", "kill", "sunset", "clean up", "delete" | remove |
If ambiguous, ask rather than guess — frame the question with what you detected
(e.g. "this adds a tool AND changes dispatch — one change spec or split?").
Read .agents/templates/<kind>.spec.md for the exact section structure. Keep the
header shape: # <KIND>: <title> and > Kind: <kind> · Status: draft · Date: <date>.
change, migrate, remove)Ground the spec in current state, Go first (the reference port):
change — read the affected package/agent to describe Context accuratelymigrate — read the current shape to fill Context and Target state honestlyremove — enumerate callers, config, and external state for Impact analysisFor add, check whether something similar already exists — if so, confirm with the
user whether this is really add or should be change.
Map extracted information onto the template sections:
Gherkin: Given → Context/preconditions; When → the triggering event or workflow
step; Then → Test plan assertions and Design outcomes. Jira: title → H1;
description → Context/Motivation; AC checklist → preserved verbatim plus mapped;
linked issues → Compatibility / Impact analysis.
<!-- TODO: [what's missing] -->; these are
temporary working state and MUST be resolved in step 7<!-- TODO: no signal in AC — [what the user must decide] -->, never skippedFollow the grill-me skill on the working spec: scan for <!-- TODO --> markers, raw
template placeholder prose, <YYYY-MM-DD>-style header stubs, and empty plan steps;
explore the codebase before asking; one question at a time with a recommended answer
and tradeoff; write each resolution back immediately; append a ## Decisions log.
Always walk the house decision branches, even if unmarked:
okf/standards/language-parity.md)okf/standards/webhooks.md)okf/standards/documentation.md)No <!-- TODO --> markers may survive. Explicit deferrals go under ### Deferred
in the Decisions log with a reason.
At the bottom of the spec:
---
## Original Requirements
> **Source**: [format detected]
> **Converted on**: {date}
> **Spec kind**: {kind} (inferred / explicit)
<details>
<summary>Original acceptance criteria (click to expand)</summary>
{verbatim original input, unmodified}
</details>
Save as specs/<YYYYMMDD>-<slug>.md and tell the user: which kind was used (and why,
if inferred); how many decisions were grilled and how many deferred (call deferred ones
out); and that the spec is implementation-ready — including which ports it covers.
Read-only skill — produces a document, not code changes.