new-surface
Add a surface: render the graph sub-agent and promote Surface + verification Rule + Check into the graph.
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-27
- Stars
- ★ 5
- Forks
- 0
01 前言 Front Matter
- name
- new-surface
- description
- Add a surface: render the graph sub-agent and promote Surface + verification Rule + Check into the graph.
- argument-hint
- surface name and its path
- user-invocable
- true
03 SKILL.md 正文
new-surface
Add a surface: render the graph-mode sub-agent and promote the Surface into the canonical Stable Knowledge Graph — no standards doc and no routing table exist.
Engine root: this skill's base directory is
<engine-root>/skills/new-surface/; engine scripts live two levels up, at<engine-root>/scripts/. Resolve them relative to the base directory your harness reports for this skill.
Procedure
-
Gather inputs — if the user has not provided all four pieces of information, ask for them before proceeding:
- Surface name — short, lowercase, hyphen-separated identifier (e.g.
api,admin-dashboard). - Surface path — workspace-relative path to the surface codebase (e.g.
apps/api). - Specialist agent — semantic agent identifier, defaulting to
<name>-agentonly when the user accepts it. - Test command — the command used to run tests for this surface (e.g.
vitest run,pytest).
- Surface name — short, lowercase, hyphen-separated identifier (e.g.
-
Declare the hub mode. Run
steepy-formula hub-modeand quote itsmode:line —graph,migrate, ornone, each printed with oneevidence:line. The command always exits 0: it is a declaration, not a gate, and this prose never re-implements its detection — the command is the single authority. The declared mode routes the rest of the run:Declared mode Route graphContinue with Steps 3–6 — the graph promotion; never create a standards doc. migrateStop and tell the user to run the graph-migrateskill (invoke it the way your harness invokes skills) before any other workflow.noneNo hub to add a surface to — tell the user to run the initskill (invoke it the way your harness invokes skills) first, and stop. -
Render the specialist agent — create
.claude/agents/<surface-name>-agent.mdfrom the graph-mode agent template<engine-root>/templates/surface-agent-graph.mdby substituting{{name}}and{{path}}agent-side (refuse to overwrite an existing agent file — surface the conflict to the user instead). That template's per-task guidance points the agent at the deterministic surface target —steepy-formula context resolve --target apex:<projectId>:surface:<slug(name)>, with--path {{path}}as the alternative where a topology bridge exists — never at a standards doc, because there is none. Binding is deterministic: surface<name>→ agent file.claude/agents/<name>-agent.md. -
Build the structural promotion scenario (nothing applied). The shipped
promotion createcommand carries only typed knowledge candidates (term/rule/decision/readme) and cannot express a Surface — drive the shipped structural-promotion helper instead; it works on an initialized graph (ADD operations whose target already exists in the stable graph are skipped and reported, so only the genuinely new nodes and edges ride the scenario). Write the surface into.formula/work/new-surface-<surface-name>.json— a local, gitignored work artifact:{ "project": { "id": "<projectId>" }, "surfaces": [ { "name": "<surface-name>", "path": "<surface-path>", "testCommand": "<test-command>" } ] }<projectId>is the project id the Step 2 declaration echoed on itsproject:line (the CLI's fixed resolution chain — in an initialized repo it comes from.formula/config.json); the helper requires the file'sproject.idand its--projectflag to agree.testCommandis the test command the user confirmed in Step 1 — from it the helper derives the surface's verification Rule (APPLIES_TO→ the Surface) and its Check with the command persisted as theext_v1_commandextension property (VERIFIED_BYfrom the Rule). That property is where graph-aware skills read the surface's test command from the resolved context.
Then create the draft scenario:
node <engine-root>/scripts/structural-promotion.mjs \ --project <projectId> --port docker \ --input .formula/work/new-surface-<surface-name>.json new-surface-<surface-name>The helper maps the input into plain ADD operations — the Surface (with
PART_OF→ the Project root, whose own ADD is skipped as already present), the verification Rule withAPPLIES_TO→ the Surface, and the Check withext_v1_commandandVERIFIED_BY— and creates the DRAFT scenario through the core promotion lifecycle. Nothing is applied here; record the scenario id it reports. -
Preview and human gate.
steepy-formula promotion preview new-surface-<surface-name>The typed diff report IS the preview: show it to the user. Approval is explicit, never assumed — one question with a clear yes/change/no choice; never proceed on silence. On yes, commit the transaction:
steepy-formula promotion apply new-surface-<surface-name> --yes [--approver <name>]That yes IS the human gate, and the agent applies directly on it: pass
--yesonly after the human's explicit yes, in an interactive session, for exactly the scenario just previewed. A change re-previews and needs a new yes; a no applies nothing. The CLI refuses (exit 20) an apply whose base revision moved after the preview.--approvernames the human who said yes (default: the OS user). -
Verify — run the graph coherence gate, then a resolver spot-check:
steepy-formula graph validate steepy-formula context resolve --target apex:<projectId>:surface:<slug(name)>graph validatemust come back clean, and the resolved context must return the new Surface, its verification Rule, and its Check carrying the approved test command asext_v1_command. (--path <surface-path>answers only where a topology bridge exists; on a curated-only graph it exits 10 UNRESOLVED — expected, not a failure.) If either gate fails, fix the graph before considering the task complete.
04 同仓库更多 Skills
web-check
Run the web surface checks.
review
Verify implemented work against its spec with real evidence before any "done" claim. Checks the spec's success criteria, runs the surface test command, and runs `steepy-formula graph validate` through the deterministic inline evidence capture.
plan
Turn a local working spec into a step-by-step implementation plan. Each step names the owning surface and specialist agent and the surface test command; the plan is written into .formula/work/plans/ as a gitignored work artifact.
loop-engineer
Validate and authorize a gear-4 goal contract, invoke the packaged deterministic loop controller, report its result, and hand off terminal evidence to review.
init
Graph-first init — gate on a provisioned Stable Knowledge Graph before writing anything, interview the governed structure, scaffold the disk-minimal harness assets, and land the initial graph through a promotion scenario. Never invents Rules from stack detection.
inception
Turn an idea and its starting materials into a minimal, verified, runnable application before the graph binding exists — reconnaissance, architecture decisions, verified versions, one human approval, bootstrap of one representative path, and final verification — then hand off to init and discovery.