cyber-aced 0.3.0

package/skills/define-agent/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: define-agent
+description: 'Use this skill when the user wants to create or improve an agent definition — a named, reusable role that can be delegated to as a subagent, loaded in-context as a persona, or both. Trigger on "create an agent", "write a conductor", "make an agent definition", "define a persona", "build a dual-mode agent", or "add an invokable agent".'
+---
+
+# Define Agent
+
+Create or improve an agent definition — a named role encoded in a single file.
+
+When the conductor dispatches this skill as a generic builder (`produced-by sdd:automaton`) for the ACED **impl-producer** role (implement mode, against a frozen `.feature`), it builds the **agent definition** to pass the frozen suite. The **verification is the frozen `.feature` itself** — its inline `@rubric` scenarios and `@trigger` `Examples`, authored by `aced-scenario-writer` at explore — so no separate eval suite is authored here; `eval.md` carries only the `subject` binding and run policy. As impl-producer it self-aligns to `sdd:ownership-governance` plus the resolved **builder-impl + architect-impl** bars (the ACED builder-impl is `aced:aced-builder-impl`). (Invoked standalone — no frozen `.feature` — only the agent definition is produced.) If the impl-judge reports scenario failures, load `aced-impl-producer` to run the diagnose-and-refine loop rather than re-deriving it here.
+
+## First: confirm an agent definition is the right artifact
+
+A skill can set `model`, `effort`, `allowed-tools`, `disallowed-tools`, `paths`, and can run itself in
+a subagent via `context: fork` + `agent:`. Wanting a specific model or effort level is **not** a
+reason to author an agent definition.
+
+Author an agent definition when the requirement is one of these, which no skill can express:
+
+| Requirement | Field |
+| --- | --- |
+| A closed tool allowlist — "only these, nothing else" | `tools` |
+| A permission mode for the whole run | `permissionMode` |
+| A turn ceiling | `maxTurns` |
+| Memory that survives across conversations | `memory` |
+| Agent-scoped MCP servers | `mcpServers` |
+| An isolated git worktree | `isolation: worktree` |
+
+Note that a skill's `allowed-tools` **pre-approves** and `disallowed-tools` **denies** — neither
+closes the set, which is why a real allowlist needs the agent definition.
+
+If none of the rows apply and the target is a stance, a voice, or a convention set rather than a
+worker, route to `define-skill` and stop here.
+
+## Keep the content in a skill when more than one caller needs it
+
+Content written into an agent body is reachable two ways only: spawn that agent, or read its file by
+path. Path-reading is brittle and breaks under plugin distribution.
+
+When the same content must serve both a spawned agent and an in-session load, write it as a skill and
+name it in the agent's `skills:` frontmatter. That field injects the skill's full content into the
+agent at startup — one body of text, two entry points, no duplication:
+
+```yaml
+---
+name: <agent-name>
+description: <when to delegate to this agent>
+model: opus
+tools: Read, Write, Edit, Grep, Glob
+skills:
+  - <shared-content-skill>
+---
+```
+
+`skills:` is a preload list, not an access list — it does not restrict what the agent may load later.
+A skill named there must stay model-invocable: `disable-model-invocation: true` blocks preloading.
+
+The inverse direction — `context: fork` on the skill — is for when the **skill** carries the task and
+the agent only supplies tools and system prompt. Do not fork a skill that is pure reference: it
+arrives as guidelines with no actionable prompt and returns nothing useful.
+
+## Agent definition modes
+
+Present these three modes to the user and ask which fits their use case:
+
+| Mode | What it does | When to pick it |
+|------|-------------|-----------------|
+| **Delegated** | Runs as a subagent in its own context; returns a result to the caller | Autonomous workers, fan-out tasks, long-running jobs where interruption isn't needed |
+| **Invokable (dual-mode)** | Can be spawned as a subagent AND reached by a thin companion command, so the user can steer it interactively either way. The command takes one of **two shapes** — see below; picking the wrong one is what makes an agent bleed | Conductors, reviewers, personas — and workers that produce an artifact, which stay just as steerable through a gateway |
+| **In-context only** | Loaded via command only; not intended as a subagent | One-off role activations where no other caller needs the content |
+
+**In-context only is rarely the right answer now.** If the content is a stance the user loads into a
+session — a voice, a register, a review standard — it is a skill, not an agent definition, and
+`define-skill` owns it. Pick this mode only when the file genuinely must stay an agent definition.
+
+For **Invokable**, a companion command file is scaffolded alongside the agent definition. Prefer
+putting the shared body in a skill (see above) and having both the command and the agent's `skills:`
+field name it. Falling back to a command that reads the agent file by path is acceptable only when no
+skill placement is available to the user.
+
+## Determine placement
+
+If the target scope is not clear from context, ask:
+
+> Where should this agent definition live?
+> 1. **User-global** (`~/.agents/agents/<name>.md`) — available across all projects
+> 2. **Project** (`.agents/agents/<name>.md`) — scoped to this repo
+> 3. **Inside a plugin** (`plugins/<plugin-name>/agents/<name>.md`) — distributed with the plugin
+
+After the user selects, derive the canonical path.
+
+Then ask which runtimes to target (select all that apply):
+
+| Runtime | Symlink target |
+|---------|---------------|
+| Claude Code | `.claude/agents/<name>.md` |
+| Cursor | `.cursor/rules/<name>.mdc` |
+| Codex | `.codex/agents/<name>.md` |
+
+The canonical file lives at the canonical path. All runtime locations are symlinks to it.
+
+## Gather requirements
+
+Ask the user:
+
+1. **Name** — kebab-case slug (e.g. `conductor`, `code-reviewer`). If the agent's role is to **score or verify a specific gate or case**, name it by that gate/scope, not a bare action verb: `<domain>-<gate>-judge` for a gate scorer (e.g. `sdd-impl-judge`, `aced-impl-judge`), `<domain>-case-judge` for a case scorer (e.g. `aces-case-judge`). Flag any gate/case scorer whose name is not in that form — bare verdict verbs (`implementer`, `judge`, `validator`, `reviewer`, `checker`) and non-verdict action names (`eval-runner`, `grader`) alike. A producer/worker agent (e.g. `scenario-writer`, `doc-writer`) keeps its action-oriented name — this convention only applies to gate/case scorers.
+2. **Role** — one sentence: "You are a [seniority] [role] focused on [bounded concern]."
+3. **Responsibilities** — what does this agent do? (3–6 bounded concerns)
+4. **Output format** — what does it produce? (file, report, JSON, confirmation, etc.)
+5. **Human-in-the-loop rules** — which actions require user confirmation before proceeding?
+6. **Out of scope** — what should it explicitly refuse or defer?
+7. **Tools** (Claude Code / Codex) — comma-separated tool names, or `*` for all
+
+If improving an existing file, read it first. Ask only about gaps or issues found.
+
+## Draft the agent definition
+
+Write the file at the canonical path using this structure:
+
+```markdown
+---
+name: <name>
+description: >
+  Use this agent when <primary trigger>. Trigger on <phrase 1>, <phrase 2>, or
+  when the user <implicit signal> — even if they don't say "<domain word>"
+  explicitly.
+tools: <tool list or *>
+model: <optional: opus | sonnet | haiku>
+---
+
+# <Title>
+
+You are a <seniority> <role> focused on <bounded concern>.
+
+## Responsibilities
+
+- <one bounded concern per bullet>
+
+## Output format
+
+<Concrete: file path, JSON shape, Markdown section structure, etc.>
+
+## Human-in-the-loop rules
+
+- <Action requiring confirmation before execution>
+
+## Out of scope
+
+- <Explicit refusal or deferral>
+```
+
+Omit `model:` unless the user specifies one. Omit `tools:` for in-context-only agents.
+
+## For Invokable mode: scaffold the companion command
+
+Write a second file at `.agents/commands/<name>.md` (or the plugin-scoped equivalent). **Ask one
+question first, because the two shapes are not interchangeable:**
+
+> **Where does this agent's output go — into the session, or into something it produces?**
+
+| Its output is… | Command shape | Why |
+|---|---|---|
+| **the session itself** — replies, review remarks, decisions the user reacts to | **Adoption** | The instruction governs the session's own output, so loading it into the session is the point |
+| **a produced artifact** — a document, a file, a draft it hands back | **Gateway** | The instruction governs the artifact. Loading it into the session applies it to output it was never written for |
+
+**Getting this wrong is not a style slip — it is the bleed.** An adoption command is a scope statement
+made once; every reply after it accumulates as an unlabeled example, and the voice or stance drifts
+into output it does not govern.
+
+**When both fit, gateway.** A reviewer that also writes `review.md` matches both rows — its remarks
+are what the user reacts to *and* it produces a file. Gateway is the fail-safe direction: a wrongly
+gatewayed agent costs a round trip, while a wrongly adopted one bleeds.
+
+**Gateway costs no steering.** The command runs in the session, so the user converses with it,
+redirects it, asks for a different angle, and asks for revisions — it brokers each run. What a
+gateway leaves out is the agent's *instructions*, not the user's control. Only a single dispatch is
+uninterruptible once it starts, which is why the command settles what it can before dispatching and
+why a revision is another dispatch rather than an in-session edit.
+
+### Adoption — for an agent whose output is the session
+
+```markdown
+---
+description: Load <name> as your operating role for this session.
+allowed-tools: Read
+---
+
+Read `<canonical-path-to-agent-file>` in full and adopt it as your operating
+instructions for the rest of this session.
+
+Confirm in one line that the <name> role is active. Do not take any action until
+the user gives you a task.
+
+$ARGUMENTS
+```
+
+### Gateway — for an agent that produces an artifact
+
+The command exists because a subagent is not slash-invokable. It must **not** load the agent's
+instructions into the session — it collects what the subagent cannot ask for, dispatches, and relays.
+
+Bind a **bounded** tool set, as the adoption template does. This is the one session that must not do
+the work itself, so leaving tools open is leaving the failure available: name the runtime's
+subagent-dispatch tool plus whatever read-only tools the command needs to settle the brief, and
+nothing that writes. The dispatch tool's name is runtime-specific — use the name the target runtime
+actually exposes rather than copying one from another runtime's docs.
+
+```markdown
+---
+description: <what the user gets> — briefs the <name> subagent and returns its result.
+allowed-tools: <dispatch-tool>, Read, Glob, Grep
+---
+
+Gateway to the `<name>` subagent. Take the request, brief the subagent, return what it produces.
+
+**Do not load <name>'s instructions into this session.** They govern what it produces, not this
+conversation. The subagent holds them in its own context, which is where they belong.
+
+## The request
+
+$ARGUMENTS
+
+## What to do
+
+1. **Read the request.** If it carries enough to act on, go to step 3.
+2. **Ask only what would change the result.** The subagent cannot ask anything once it starts, so
+   settle what is genuinely undecided here — at most two things, in one message, and only what you
+   cannot settle yourself.
+3. **Brief the subagent.** It starts blank and inherits nothing from this conversation: state the
+   task, name the **source files** (do not paste or summarize their contents), mark what the user
+   settled explicitly so it is not re-derived, and name what is out of scope.
+4. **Return what came back**, and relay the assumptions it declared rather than burying them. A wrong
+   inference is cheapest to catch before the next round.
+
+For a revision, dispatch again with the same completeness — the new subagent has not seen the
+previous result. Do not do the work in this session to save a round trip; that does it without the
+agent's instructions, which is the drift the gateway exists to prevent.
+```
+
+Symlink `.claude/commands/<name>.md` → `.agents/commands/<name>.md` (and other runtime equivalents the user selected).
+
+## Create symlinks
+
+After writing the canonical file(s), create symlinks for each selected runtime. Use relative paths from the symlink location to the canonical file.
+
+Example for a project-scoped agent targeting Claude Code:
+```bash
+ln -sf ../../.agents/agents/<name>.md .claude/agents/<name>.md
+```
+
+Verify each symlink resolves correctly.
+
+## Run quality checks
+
+After writing, evaluate the agent definition against these checks:
+
+| # | Check | Severity |
+|---|-------|----------|
+| F1 | `name` and `description` fields present | CRITICAL |
+| F2 | `name` is kebab-case and matches file stem | HIGH |
+| F3 | `description` starts with "Use this agent when…" | HIGH |
+| F4 | `description` ≤ 1024 characters | HIGH |
+| F9 | `description` includes implicit trigger phrasing | MEDIUM |
+| B1 | Body opens with "You are a [seniority] [role]…" | HIGH |
+| B5 | Irreversible actions have confirmation rules | HIGH |
+| B8 | Body under 200 lines | MEDIUM |
+| B9 | A gate- or case-scorer agent is named in `<domain>-<gate>-judge` or `<domain>-case-judge` form; flags any gate/case scorer whose name is not in that form (`implementer`, `judge`, `validator`, `reviewer`, `checker`, and non-verdict action names like `eval-runner`); does not fire for a non-scorer producer agent | HIGH |
+
+Report results. Fix any CRITICAL or HIGH failures before presenting the final file to the user.
+
+## Report
+
+Summarize:
+
+- Canonical file path
+- Runtime symlinks created
+- Companion command path (Invokable mode only)
+- Quality check outcome
+- Suggested next step: run `sdd:start-mission` (the conductor resolves the ACED roles) to spec and eval for this agent definition

package/skills/define-command/README.md

@@ -0,0 +1,36 @@
+# define-command
+
+Create or improve a command — a user-invoked-only slash workflow (`/name`) that never auto-triggers from the model — then hand it to the ACED eval loop to spec and score.
+
+## When to use
+
+Use this skill when you want to author a new command or formalize an existing user-only workflow into one.
+
+Good triggers include:
+
+- "Create a command that does X" / "add a `/deploy` command"
+- Suppressing a skill's auto-invocation because accidental firing would be disruptive
+- Converting an existing workflow skill into a `/name`-only command
+- Deciding between the `commands/` folder and `disable-model-invocation: true` mechanisms
+
+Defer to a sibling when the request is really about a companion command that loads an agent definition into context (`define-agent`), a workflow that should keep auto-triggering (`define-skill`), a reference-only rule set (`define-governance`), or scoring / diagnosing an existing config (`run` / `add-scenario` / `improve`).
+
+## What it does
+
+The skill walks you through the shape before writing anything:
+
+1. **Route** — confirm this is a standalone command, not an agent companion, an auto-triggered skill, or governance
+2. **Mechanism** — `commands/` folder (widest cross-harness support) or `disable-model-invocation: true` (modern, Claude Code / Windsurf only)
+3. **Placement** — user-global, project, or inside a plugin's `commands/` subfolder
+
+It then drafts the command file for the chosen mechanism, creates runtime symlinks (`disable-model-invocation` mechanism only), audits it, and points you at the ACED eval loop (`start-mission` / `add-scenario` / `run`) to spec and score it.
+
+## `command` is a registered ACED artifact-type
+
+ACED already serves `command` as one of its four agent-config artifact-types (alongside `skill`, `subagent`, `agents-section`) — see `init-aced`. Before `define-command`, authoring one fell to `define-agent` (for the agent-companion case) or ad hoc editing; this skill gives standalone commands their own dedicated producer.
+
+## Install
+
+```bash
+npx skills add cyberuni/cyberplace --skill aced/define-command
+```

package/skills/define-command/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: define-command
+description: 'Use this skill when the user wants to create or improve a command — a user-invoked-only slash workflow (`/name`) that never auto-triggers from the model. Trigger on "create a command", "add a slash command", "make a /deploy command", "add a user-only workflow", "convert this skill to a command", or "stop this skill from auto-triggering", even if they do not say "command" explicitly. Not for a companion command scaffolded alongside an agent definition — whether it adopts that agent in-session or gateways to it as a subagent (define-agent) — an auto-triggered workflow skill (define-skill), or a reference-only rule set (define-governance).'
+---
+
+# Define Command
+
+Create or improve a **command** — a workflow the user invokes explicitly via `/name`, never
+triggered automatically by the model.
+
+When the conductor dispatches this skill as a generic builder (`produced-by sdd:automaton`) for the
+ACED **impl-producer** role (implement mode, against a frozen `.feature`), it builds the **command
+file** to pass the frozen suite. The **verification is the frozen `.feature` itself** — its inline
+`@rubric` scenarios and `@trigger` `Examples`, authored by `aced-scenario-writer` at explore — so no
+separate eval suite is authored here; `eval.md` carries only the `subject` binding and run policy. As
+impl-producer it self-aligns to `sdd:ownership-governance` plus the resolved **builder-impl +
+architect-impl** bars (the ACED builder-impl is `aced:aced-builder-impl`). If the impl-judge reports
+scenario failures, load `aced-impl-producer` to run the diagnose-and-refine loop rather than
+re-deriving it here.
+
+There are two other entry points, both with **no frozen `.feature`** and **only the command file**
+produced:
+
+- **Standalone** — the user invokes this skill directly, outside any CR. Scaffold, then offer the
+  ACED eval loop (see "Report and hand off" below) rather than assuming it.
+- **Escaped** — the gateway or `start-mission` invokes this skill directly after resolving the
+  request `non-durable` (the escape hatch, before any CR opens). There is no mission to hand off
+  within: scaffold, audit, report, and **stop** — do not mention the ACED eval loop.
+
+## Route the request first
+
+`define-command` owns **standalone user-invoked workflows**. Defer when the intent belongs to a
+sibling that carries the same config vocabulary:
+
+| The request is really about… | Defer to |
+|---|---|
+| a thin command that loads an **agent definition** into context (the Invokable-mode companion) | `define-agent` |
+| a workflow that should **auto-trigger** from the model's own judgment | `define-skill` |
+| a **reference-only rule set / governance** other skills load but never execute as steps | `define-governance` |
+| **scoring** an existing config, or **adding** an eval case | `run` / `add-scenario` |
+| **diagnosing** why an existing command's evals fail | `improve` |
+
+A request that turns out to want an agent loaded into context (not a self-contained workflow) is
+handed to `define-agent` — do not scaffold a companion-command shape here.
+
+## Choose the mechanism
+
+Two mechanisms suppress model auto-invocation; pick one based on target harnesses (ask the user which
+harnesses to target if not stated):
+
+| Mechanism | File | Portability | When to pick it |
+|---|---|---|---|
+| **`commands/` folder** (legacy) | A standalone markdown file, not a `SKILL.md` | Widest support — Claude Code, and GitHub Copilot CLI (reads `.claude/commands/`); the only option for cross-harness plugin commands targeting Cursor too | Default choice; use for anything shipped in a plugin or targeting more than Claude Code |
+| **`disable-model-invocation: true`** (modern) | A `SKILL.md` with the frontmatter flag | Claude Code, Windsurf; **not** Copilot CLI, Codex CLI, or Gemini CLI; has a known Cursor bug hiding plugin-delivered skills from the `/` menu (Mar 2026) | Only when targeting Claude Code / Windsurf exclusively and the command benefits from full `SKILL.md` progressive disclosure (a `references/` or `scripts/` dir) |
+
+If improving an existing file, read it first and keep its current mechanism unless the user asks to
+migrate.
+
+## Determine placement
+
+If the target scope is not clear from context, ask:
+
+> Where should this command live?
+> 1. **User-global** (`~/.claude/commands/<name>.md`) — available across all your projects
+> 2. **Project** (`.claude/commands/<name>.md`) — scoped to this repo
+> 3. **Inside a plugin** (`plugins/<plugin-name>/commands/<name>.md`) — distributed with the plugin, native in Claude Code and Cursor
+
+For the `disable-model-invocation` mechanism, placement instead follows the skill convention — write
+the canonical `SKILL.md` at `~/.agents/skills/<name>/`, `.agents/skills/<name>/`, or
+`plugins/<plugin-name>/skills/<name>/`, then symlink `.claude/skills/<name>` (and other targeted
+runtime locations) to it.
+
+## Gather requirements
+
+Ask the user:
+
+1. **Name** — kebab-case slug, becomes `/name`
+2. **Purpose** — one sentence: what does invoking this command do?
+3. **Arguments** — does it accept free text after the command (`$ARGUMENTS`)? What does the caller
+   pass?
+4. **Pre-approved tools** — which tools should run without a permission prompt during this
+   command's turn? (`allowed-tools:` frontmatter). This grants; it does not fence. Every other tool
+   stays callable under normal permission settings. If the requirement is "this command must never
+   touch X", that is `disallowed-tools:`, not `allowed-tools:`.
+5. **Steps** — the actual workflow body, numbered
+
+If improving an existing file, read it first. Ask only about gaps or issues found.
+
+## Draft the command file
+
+**`commands/` folder mechanism:**
+
+```markdown
+---
+description: <one sentence — shown in the `/` menu, keep it scannable, no token-budget pressure since it never enters trigger matching>
+allowed-tools: <tools to pre-approve, comma-separated — omit if nothing needs pre-approval>
+---
+
+<Body — the workflow itself, written as if the user just typed `/name`.>
+
+$ARGUMENTS
+```
+
+**`disable-model-invocation` mechanism:**
+
+```markdown
+---
+name: <name>
+description: <capability the command performs — never matched for auto-trigger, but still keep it accurate for the `/` menu>
+disable-model-invocation: true
+---
+
+# <Title>
+
+## Instructions
+1. <step>
+2. <step>
+```
+
+## Create symlinks (`disable-model-invocation` mechanism only)
+
+After writing the canonical `SKILL.md`, create symlinks for each selected runtime, same as any skill:
+
+```bash
+ln -sf <relative-path-to-canonical> <runtime-location> && ls <runtime-location>   # verify it resolves
+```
+
+The `commands/` folder mechanism has no canonical+symlink step — the file at its placement path is
+the whole artifact, unless distributed via a plugin's `commands/` subfolder (already native, no
+symlink needed).
+
+## Audit before handing back
+
+For the `disable-model-invocation` mechanism, run the structural audit and fix any CRITICAL or HIGH
+finding before presenting the skill:
+
+```bash
+npx cyberplace@0.2.4 audit validate --path <placement-dir>/<name>   # resolve <version> via: npm view cyberplace version — never @latest
+```
+
+The `commands/` folder mechanism is not a `SKILL.md` — the audit tool does not apply; check by hand
+that `description` is present and the body reads correctly as a `/name` invocation.
+
+## Run quality checks
+
+After writing, evaluate the command against these checks:
+
+| # | Check | Severity |
+|---|-------|----------|
+| C1 | `description` field present | CRITICAL |
+| C2 | Body reads correctly as a standalone `/name` invocation, not dependent on prior conversational context | HIGH |
+| C3 | Irreversible or destructive steps are called out explicitly, not buried mid-body | HIGH |
+| C4 | `$ARGUMENTS` used only if the command actually accepts caller input | MEDIUM |
+| C5 | `disable-model-invocation` mechanism: `name` matches the file's directory stem | HIGH |
+| C6 | `commands/` folder mechanism: no stray `disable-model-invocation` field (meaningless outside a `SKILL.md`) | MEDIUM |
+
+Report results. Fix any CRITICAL or HIGH failures before presenting the final file to the user.
+
+## Report and hand off to the ACED eval loop
+
+Summarize:
+
+- Canonical file path (and runtime symlinks, `disable-model-invocation` mechanism only)
+- Mechanism chosen and why
+- Audit outcome (or the by-hand check result for the `commands/` folder mechanism)
+
+**Escaped** entry: stop here — the artifact resolved `non-durable`, so there is no mission to hand
+off to.
+
+**Standalone or impl-producer** entry: point the user at the **ACED eval loop** to spec and score
+the command — run `sdd:start-mission` (the conductor resolves the ACED roles for the `command`
+artifact-type) to author its frozen `.feature` (with inline `@trigger` Examples exercising `/name`
+invocation), or `add-scenario` / `run` to grow and score it. Do **not** embed a legacy trigger-query
+eval file as the test step — scoring is the ACED loop's job.

package/skills/define-governance/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: define-governance
+description: 'Create or revise a governance file — reference-only criteria or rules that other skills and agents load on demand. Use when the target is the criteria file itself, even if the user just says "write standards for" or "improve this governance".'
+---
+
+# Define Governance
+
+Create or improve a governance file — a reference-only skill that encodes criteria,
+standards, or workflow rules. Governance files are loaded on demand by other skills
+or agents; they never auto-trigger from user input.
+
+## Governance vs. skill
+
+| | Governance | Workflow skill |
+|---|---|---|
+| **Purpose** | Criteria, standards, rules the agent enforces | Steps the agent executes |
+| **Triggered by** | Explicit load (`/<name>` or `## References`) | User situation matching `description:` |
+| **Auto-trigger** | Never | Yes, when description matches |
+| **Body style** | Normative rules, checklists, rubrics | Numbered steps, decision logic |
+
+If the content describes *what to enforce* (a rubric, a quality bar, a constraint set),
+it is a governance file. If it describes *how to do something* (a workflow), it is a
+workflow skill.
+
+## Determine placement
+
+If the target scope is not clear from context, ask:
+
+> Where should this governance file live?
+> 1. **User-global** (`~/.agents/skills/<name>/SKILL.md`) — available across all projects
+> 2. **Project** (`.agents/skills/<name>/SKILL.md`) — scoped to this repo
+> 3. **Inside a plugin** (`plugins/<plugin-name>/skills/<name>/SKILL.md`) — distributed with the plugin
+
+After the user selects, derive the canonical path.
+
+## Gather requirements
+
+Ask the user:
+
+1. **Name** — kebab-case slug (e.g. `commit-discipline`, `skill-design`, `review-rubric`)
+2. **Topic** — one sentence: what domain does this governance cover?
+3. **Consumers** — which skills or agents will load this? (informs the structure and depth)
+4. **Content type** — select the primary content shape:
+   - **Rubric** — scored criteria for evaluation: named dimensions, each with its own `max`, plus one `threshold`
+   - **Constraint set** — rules that must not be violated
+   - **Checklist** — ordered or unordered items to verify
+   - **Decision table** — conditions → outcomes
+   - **Mixed** — more than one of the above
+5. **Rules or criteria** — the actual content; collect from the user or from an existing document
+
+Draft no file until the name, the content type, and the rules are gathered.
+
+If improving an existing file, read it first. Ask only about gaps or issues found.
+
+## Draft the governance file
+
+Write the file at the canonical path using this structure:
+
+```markdown
+---
+name: <name>
+description: "Partial Skill: invoke by name only — <one sentence: what domain this governs and who loads it>"
+user-invocable: false
+metadata:
+  type: governance
+---
+
+# <Title>
+
+Apply when: <one-line scope — the situation or artifact type this governs>
+
+## <Section per content type>
+
+<Normative rules, rubric rows, checklist items, or decision rows>
+
+## Validate
+
+<One assertion per binding rule above, phrased as an observable, falsifiable claim about the
+resulting artifact — a diff, a file's presence/absence, a structural shape — never a claim about
+the agent's intent ("I checked X"). Prefer a mechanical check (a script, grep pattern, or diff)
+wherever the rule permits one. Reserve prose assertions for genuine judgment calls, and phrase even
+those as something a second, cold reader re-derives from the artifact, not something read off the
+first agent's own account. Skip this section only for a pure Rubric governance, where the scored
+dimensions already are the verification.>
+
+## References
+
+<on-demand standards, sibling files, external HTTPS URLs — no repo file paths>
+```
+
+Rules for the body:
+- Set `user-invocable: false` — the classifier for a partial skill (a governance is loaded by name, never user-triggered)
+- Lead `description` with the `"Partial Skill:"` prefix (recommended form `"Partial Skill: invoke by name only — …"`) — a self-declaration for the reader; keep it minimal and non-trigger-shaped so the harness (which still sees the description) does not auto-match it
+- Do not include `## Why`, `## Rationale`, or causal prose — put that in ADRs
+- Encode decisions and criteria, not facts the model already knows
+- For a **Constraint set**, **Checklist**, or **Decision table** governance, write a `## Validate`
+  section — one checkable assertion per rule, run twice: once by the agent that just followed the
+  rule, as its own pre-handoff self-check, and once by a cold reader re-checking the same artifact
+  later. A `## Validate` section that just says "confirm you followed the rules above" does not
+  count — it restates the instruction instead of asserting something about the result. A pure
+  **Rubric** governance does not need one: its scored dimensions already serve this purpose.
+- Keep each rule atomic and independently falsifiable. To decide whether a multi-clause rule splits,
+  ask what each clause has left to check when the other clause is false:
+  - **Split it** when each clause states its own demand — something still checkable when the other
+    clause fails. *"Every skill has a README and its description names a trigger"* splits: a skill can
+    have a README whose description names no trigger, and a trigger-naming description with no README.
+  - **Keep it as one rule** when a clause *qualifies* another — it constrains how the other clause is
+    satisfied rather than adding a demand of its own, so it has nothing left to check once that clause
+    fails. *"the description names when to trigger, and does so in the user's own phrasing"* stays one
+    rule: if the description names no trigger, there is no naming whose phrasing could be wrong.
+  The joining word does not decide this — `and` appears in both examples. Test the clause, not the seam.
+
+## Create symlinks
+
+Governance files follow the same symlink convention as skills. After writing the canonical
+file, create symlinks for each runtime the user targets:
+
+| Runtime | Symlink target |
+|---------|---------------|
+| Claude Code | `.claude/skills/<name>/SKILL.md` → canonical path |
+| Cursor | `.cursor/rules/<name>.mdc` → canonical path |
+
+Use relative paths from the symlink location.
+
+## Run quality checks
+
+After writing, evaluate the governance file against these checks:
+
+| # | Check | Severity |
+|---|-------|----------|
+| G1 | `description` starts with `"Partial Skill:"` | CRITICAL |
+| G2 | `user-invocable: false` present | HIGH |
+| G3 | `metadata.type: governance` present | HIGH |
+| G4 | No `## Why` or `## Rationale` section | HIGH |
+| G5 | Body opens with `Apply when:` scope line | MEDIUM |
+| G6 | All rules are atomic and independently falsifiable | MEDIUM |
+| G7 | No workflow steps (numbered action sequences) | MEDIUM |
+| G8 | `name` is kebab-case and matches file stem | HIGH |
+| G9 | Constraint set / checklist / decision table content has a paired `## Validate` section with checkable, artifact-state assertions (not restated rules) | MEDIUM |
+
+Report results. Fix any CRITICAL or HIGH failures before presenting the final file.
+
+## Report
+
+Summarize:
+
+- Canonical file path
+- Runtime symlinks created
+- Content type(s) encoded
+- Quality check outcome — name every check that failed, including failures below the fix bar left unfixed
+- Suggested next step: run `sdd:start-mission` (the conductor resolves the ACED roles) to spec and eval for this governance file