cyber-aced 0.4.0 → 0.4.2

package/skills/improve-skill/references/governances/skill-design.md

@@ -0,0 +1,260 @@
+# Skill Design
+
+Rules for authoring SKILL.md files that agents load on demand. Apply when creating, generalizing, or auditing a skill — before adding scripts or CLI instructions.
+
+## Structure
+
+SKILL.md must be agent-first: dense normative rules the agent executes without opening linked files first.
+
+- Do not include `## Why`, `## Rationale`, `## Background`, or `## Context` sections.
+- Do not include causal explanation ("because…") or rationale prose in the body.
+- One-line scope ("Apply when…") is allowed at the top.
+- Put optional depth in `## References` at the end — `governance show` commands, external HTTPS URLs, sibling files in the same skill folder only.
+
+**SKILL.md structure:**
+
+```markdown
+# Skill Title
+## When to use / Prerequisites   # short scope
+## Workflow                      # numbered steps, decision logic
+## Anti-patterns                 # optional
+## References                    # on-demand standards, external URLs, reference.md — no repo file paths
+```
+
+Do not embed References content or links to sibling files mid-workflow.
+
+## Core principles
+
+### Decisions over documentation
+
+Encode what to decide and how. Do not repeat generic best practices, API docs, or facts the model can derive without the skill.
+
+### Narrow and composable
+
+One workflow per skill. A skill is selected one of three ways — matched against a situation, named by a caller, or fired by an event. Declare that choice in the `description`; never infer it from a visibility flag.
+
+- **Name-only skills** (loaded by name from another skill, never matched to a user situation) set the `description` to exactly `"By name only"` — nothing else. The minimal description is the mechanism, not a label for it: the `description` is the only surface the model matches against, so every word added to it is another handle for a spurious match. Identity — what the skill is, who calls it, what it returns — belongs in the body and README, which the caller reads after loading it by name.
+- **`user-invocable` is a visibility flag only.** It controls whether a skill appears in the user's command list. It never determines how a skill is selected, and must not be read as one: a skill may legitimately be `user-invocable: false` and still situationally triggered.
+- Whether a skill can run standalone is documentation for its README, not a declared kind. A self-contained engine and a fragment of a larger capability are selected the same way and carry the same minimal description.
+- Neither type should be loaded as ambient context.
+
+### No baked-in opinions
+
+Detect the user's setup (package manager, monorepo shape, editor, OS paths) at runtime rather than assuming a specific stack. If the skill only applies to one stack, say so explicitly in the description.
+
+## Placement and scope
+
+Where a skill file lives depends on who consumes it. Whole-repo layout (manifests, CI, archetypes) is covered in **skill-repo-structure** — load from References when scaffolding a library repo.
+
+### Skill placement
+
+Use **placement** for where a skill lives; do not call this axis "type".
+
+| Placement | Location | Use case |
+| --- | --- | --- |
+| **User** | `~/.agents/skills/<name>/` | Personal skills across all projects |
+| **Project private** | `.agents/skills/<name>/` | Contributor tooling scoped to one repo |
+| **Project public** | `skills/<name>/` | Shipped with a package or installed via `npx skills add` |
+
+### Skill patterns
+
+Use **pattern** for the workflow shape; do not overload "kind" or "type" here.
+
+| Pattern | Use case |
+| --- | --- |
+| **Process** | Multi-step workflows where sequence and decision logic matter |
+| **Tool-based** | Workflows centered on consistent use of tools, systems, or connectors |
+| **Standard** | Workflows that enforce tone, structure, formatting, or quality bars |
+| **Persona** | Loads an expert stance, decision style, and working behavior into the session |
+
+Repo-internal skills must include `metadata: internal: true` in frontmatter.
+Persona skills must include `metadata.persona: "true"`.
+
+### Patch and local rules
+
+- Upstream contributions from a local install map to `skills/<name>/…` in the source repo — never `.agents/skills/` upstream.
+- **`SKILL.local.md`** extends a skill locally; never commit or push it upstream.
+- Include every changed file under the skill folder when patching (not only `SKILL.md`).
+
+## Progressive disclosure
+
+Keep SKILL.md concise — essential workflow and decision logic only.
+
+- Put detailed reference material in sibling files (`reference.md`, `examples.md`) in the same skill folder.
+- Link sibling files **only from References**; agent reads them when stuck, not by default.
+- Link references **one level deep** from SKILL.md; avoid chains of nested files.
+- Aim to keep SKILL.md under ~500 lines; split when a skill grows beyond that.
+
+## Extract deterministic logic
+
+When a step produces the same output given the same input and needs no judgment, move it out of prose:
+
+- Prefer an **existing project CLI** or a small **script** in the skill's `scripts/` directory.
+- The skill retains **when** to invoke the tool; the tool retains **how**.
+- Candidates: text manipulation, file I/O, structured data transforms, validation with fixed rules.
+
+Do not re-derive deterministic steps in natural language each run.
+
+### Keep scripts inside the skill folder
+
+The skill folder is the unit an installer copies (`skills add --skill <name>` takes that folder and nothing else).
+
+- Put every script the skill runs in its own `scripts/`, and invoke it as `node <skill-dir>/scripts/<file>`.
+- Never reference a path outside the skill folder: a sibling skill, a plugin's `bin/`, or the package root. Standalone copies and symlinked installs break such paths without an error.
+- Use Node built-ins only, or bundle dependencies into the script. The script itself never depends on `npx`, `tsx`, or a global install; the pinned `npx` fallback below is the skill's, not the script's. For a released CLI the skill depends on but does not ship, follow **cli-resolution**.
+
+### Share logic by bundling it into each skill
+
+When several skills, or a skill and a package CLI, need the same logic:
+
+- Author it once in the package source, typed and tested there.
+- Have the build emit a self-contained bundle into the `scripts/` of each skill that uses it. Start the bundle with a header naming its source file and saying it is generated, then the usage comment an agent reads when stuck. Minify the rest.
+- Do not commit the bundles. Gitignore them, build them in `prepack`, and ship them through the npm package's `files`.
+- Add a CI check that packs the package, unpacks it with no `node_modules`, and runs each bundle from the unpacked skill folder.
+- If the build is cached (for example by Turborepo), list each bundle as a build output by exact path. A glob such as `skills/**` restores cached copies over hand-written scripts.
+- Keep the tests with the source, outside the skill folder, so installs do not copy them.
+- Expose the same commands in the package CLI, and give each such skill a pinned fallback: when `scripts/<file>` is missing or cannot run, call `npx -y <package>@^<version> <command>` with the same arguments. A skill installed from git has no built `scripts/`, and this is how it still works.
+- Distribute the plugin from npm where the harness supports an npm plugin source. Git-sourced installs, including organization-distributed marketplaces that exclude npm sources, use the fallback.
+
+When a skill includes `scripts/` or documents CLI commands agents run, load **agent-tool-output** from References for stdout, JSON, non-interactive, and stderr rules.
+
+## Description and structure
+
+### Frontmatter
+
+- `name` must match the parent directory name exactly.
+- `description` of a situationally triggered skill states what the skill does, then when it applies — the situations, requests, and implicit phrasings that should select it. Lead with the capability, in third person.
+- Do not open the `description` with a fixed lead-in such as `"Use this skill when"` or `"When to use"`. A trigger clause after the capability (`"… Use when …"`) is fine; no particular phrase is required.
+- A **name-only** skill's `description` is exactly `"By name only"` and carries no capability or trigger text at all.
+- Keep `description` ≤1024 characters — the agentskills.io hard limit. Put the capability and the main triggers first; listings may truncate the tail.
+- `compatibility` — optional; declare environment constraints (required tools, network access, OS, runtime version). Include only when the skill has requirements the agent cannot assume.
+
+#### Runtime fields
+
+Support varies by platform; the notes below are Claude Code's documented behavior. Set none of these unless the skill needs them — each one is a deviation the reader must account for.
+
+| Field | Effect |
+| --- | --- |
+| `allowed-tools` | **Pre-approves** the listed tools for the invoking turn. It does not restrict the tool pool — every other tool stays callable. The grant clears on the user's next message. |
+| `disallowed-tools` | Removes tools from the pool while the skill is active. This is the field that restricts. Also clears on the next message. |
+| `model` | Model to use while the skill is active. Applies for the rest of the current turn only; the session model resumes on the next prompt. |
+| `effort` | Effort level while the skill is active: `low`, `medium`, `high`, `xhigh`, `max`. Same turn-scoped lifetime as `model`. |
+| `context: fork` | Runs the skill in a subagent, with the skill body as the task prompt. Pair with `agent:` to choose the subagent type. Only meaningful for a skill that states a task — a reference or stance skill forked this way receives no actionable prompt and returns nothing useful. |
+| `paths` | Glob patterns limiting automatic activation to matching files. |
+
+A skill cannot express a tool **allowlist** — `allowed-tools` grants and `disallowed-tools` denies, but neither says "only these". A hard allowlist, `permissionMode`, `maxTurns`, persistent `memory`, `mcpServers`, and worktree `isolation` remain agent-definition fields. Reach for an agent definition when one of those is the actual requirement, not for `model` or `effort` alone.
+
+### skill.json — install-time metadata
+
+`skill.json` is an optional sidecar file in the same directory as `SKILL.md`. It holds install-time metadata that the `skills add` / `skills update` installer reads. It is **not** loaded into agent context, so it costs zero tokens at runtime.
+
+Do not put install-time metadata in SKILL.md frontmatter — agents load it unnecessarily.
+
+**Supported fields:**
+
+```json
+{
+  "distribution": {
+    "install_via": "package_manager",
+    "package": {
+      "name": "cyber-asana",
+      "bin": "cyber-asana"
+    }
+  }
+}
+```
+
+**`distribution`** — declare the required install channel.
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `install_via` | yes | `"package_manager"` — must be installed via npm, not source control |
+| `package.name` | when `install_via: package_manager` | npm package that ships the skill binary |
+| `package.bin` | no | binary name; defaults to `package.name` |
+
+Use `install_via: package_manager` when the skill depends on a released binary from the same repo. Source-based `skills add org/repo` will skip such skills and print an `npm install` hint.
+
+### Activation
+
+The `activation` field belongs in **SKILL.md frontmatter** as a **top-level field** (not nested under `metadata:`). Agents need this information to know whether a hook is involved; not all agents support hooks, so it must travel with the skill file.
+
+```yaml
+---
+name: my-skill
+activation: per-situation
+description: "<what it does>. Use when <situations>."
+---
+```
+
+| `activation` | Claude Code | Cursor | Codex |
+| --- | --- | --- | --- |
+| `per-situation` | — | — | — |
+| `session-start` | `SessionStart` | `sessionStart` | `SessionStart` |
+| `session-end` | `SessionEnd` | `sessionEnd` | — |
+| `pre-tool-use` | `PreToolUse` | `preToolUse` | — |
+| `post-tool-use` | `PostToolUse` | `postToolUse` | `PostToolUse` |
+| `post-tool-use-failure` | — | `postToolUseFailure` | — |
+| `before-submit-prompt` | `UserPromptSubmit` | `beforeSubmitPrompt` | — |
+| `before-shell-execution` | — | `beforeShellExecution` | — |
+| `after-shell-execution` | — | `afterShellExecution` | — |
+| `before-mcp-execution` | — | `beforeMCPExecution` | — |
+| `after-mcp-execution` | — | `afterMCPExecution` | — |
+| `before-read-file` | — | `beforeReadFile` | — |
+| `after-file-edit` | — | `afterFileEdit` | — |
+| `subagent-start` | — | `subagentStart` | — |
+| `subagent-stop` | — | `subagentStop` | `SubagentStop` |
+| `pre-compact` | `PreCompact` | `preCompact` | — |
+| `stop` | `Stop` | `stop` | `Stop` |
+| `after-agent-response` | — | `afterAgentResponse` | — |
+| `after-agent-thought` | — | `afterAgentThought` | — |
+| `before-tab-file-read` | — | `beforeTabFileRead` | — |
+| `after-tab-file-edit` | — | `afterTabFileEdit` | — |
+
+— = no documented equivalent on that host.
+
+**Default:** omit or set `per-situation` — no hook; load via `description` or explicit invoke.
+
+**Hook-backed skills:** set `activation` to the normalized event, then register with `hook register --event …` (cyberplace CLI maps `session-start` → `SessionStart` / `sessionStart`, `post-tool-use` → `PostToolUse` / `postToolUse`). CLI today supports `SessionStart` and `PostToolUse` only; other values are portable declarations until hosts implement them.
+
+**Defaults by pattern:** persona → `per-situation` (opt-in via `description`); discipline / always-on injection → `session-start`; process / tool-based / standard → `per-situation` or omit.
+
+Deprecated: `metadata.activation` in SKILL.md frontmatter. Use top-level `activation:` instead.
+
+### Body
+
+- Include actionable steps, numbered instructions, or decision logic — not just a restatement of the description.
+- Do not instruct generic behavior the model already follows ("write clean code", "be helpful").
+
+## Anti-patterns
+
+- Rationale or "because…" prose in the body
+- `## Why`, `## Rationale`, `## Background`, or `## Context` sections
+- Links to other repository files mid-workflow
+- Mid-body links to sibling skill files (use References at end)
+
+## Governance lookup order
+
+A skill that reads a governance at run time stops at the first hit:
+
+1. `.agents/governances/<name>.md` — project override.
+2. Only when an installed copy exists: `upx --local-only buddy-agent-harness@^<major> governance show <name> --overrides-only` when `upx` is on PATH; else `buddy-agent-harness governance show <name> --overrides-only` when `command -v buddy-agent-harness` finds it. Exit 127 from `upx`, or any non-zero exit, means no override. Never through `npx`.
+3. `references/governances/<name>.md` inside the skill — the default copy, committed to git.
+
+Copies live at `<skill>/references/governances/<name>.md`, and the files in that folder declare which governances the skill uses. A skill copies every governance a copied governance references, and lists every copy in its SKILL.md References, so each stays one level deep. A pointer inside a copy (`governance show <other>`) is read as "load `references/governances/<other>.md`".
+
+`buddy-agent-harness governance` and the copy step in `universal-plugin plugin build` are planned (tracked in https://github.com/repobuddy/buddy-agent-harness/issues/122). Until they ship, a skill uses step 3 only.
+
+## References
+
+Related governances (load on demand; read stdout as authoritative):
+
+```bash
+npx cyberplace@<version> governance show skill-repo-structure
+npx cyberplace@<version> governance show agent-tool-output
+npx cyberplace@<version> governance show universal-plugin
+```
+
+Runtime field reference (re-verify before relying on a version-gated field):
+
+- <https://code.claude.com/docs/en/skills> — skill frontmatter, invocation control, `context: fork`
+- <https://code.claude.com/docs/en/sub-agents> — agent-definition frontmatter, `skills:` preloading

package/skills/improve-skill/scripts/validate.mts

@@ -675,13 +675,13 @@ export function runChecks(filePath: string, scanRoots?: Set<string>): CheckResul
 		)
 	}
 
-	if (isPartialSkill && fmDesc && !/^Partial Skill:/i.test(fmDesc)) {
+	if (isPartialSkill && fmDesc && !/^(Partial Skill:|By name only$)/i.test(fmDesc.trim())) {
 		warn(
 			'MEDIUM',
 			'Q3',
 			'Partial skill description missing the "Partial Skill:" prefix',
 			`description: ${fmDesc}`,
-			'Lead the description with "Partial Skill: invoke by name only — <identity>. <caller>."',
+			'Set the description to exactly "By name only" (or lead with "Partial Skill:")',
 		)
 	}
 

package/skills/init-aced/SKILL.md

@@ -50,14 +50,14 @@ Do not reorder or reformat other entries.
         "builder-spec": "aced-builder-spec",
         "builder-impl": "aced-builder-impl",
         "architect-spec": null,
-        "architect-impl": null
+        "architect-impl": "aced-architect-impl"
       }
     }
   ]
 }
 ```
 
-ACED serves its four agent-config artifact-types with one squad. `impl-producer: null` — writing the agent config is done by the `define-agent` / `define-command` / `improve` skills or the SDD-default impl-producer (the conductor running `impl-producer-governance` via a spawned builder), not a bound impl-producer agent. `solution-producer: null` uses the SDD default. ACED binds its own `builder-spec` (`aced-builder-spec`) and `builder-impl` (`aced-builder-impl`) bars; each remaining `null` governance uses the SDD default actor-gate bar.
+ACED serves its four agent-config artifact-types with one squad. `impl-producer: null` — writing the agent config is done by the `define-agent` / `define-command` / `improve` skills or the SDD-default impl-producer (the conductor running `impl-producer-governance` via a spawned builder), not a bound impl-producer agent; `aced-impl-producer` is the diagnose-and-refine loop those skills load, not a role binding. `solution-producer: null` uses the SDD default. ACED binds its own `builder-spec` (`aced-builder-spec`), `builder-impl` (`aced-builder-impl`), and `architect-impl` (`aced-architect-impl`) bars; each remaining `null` governance uses the SDD default actor-gate bar.
 
 **Each squad's `governances` block is required.** Every squad must carry a `governances` map (each binding may be `null`, but the block itself must be present). Reject a payload with a squad missing its `governances` block — fail with an error and **do not write** the file.
 

package/skills/list-skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: list-skills
-description: "Partial Skill: invoke by name only — the ACED manage-gateway skill-inventory engine — loaded in-session by the manage gateway, not user-triggered."
+description: "By name only"
 user-invocable: false
 metadata:
   internal: true

package/skills/manage-model-runners/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: manage-model-runners
-description: "Partial Skill: invoke by name only — the ACED manage-model-runners engine — loaded in-session by the ACED manage gateway, not user-triggered."
+description: "By name only"
 user-invocable: false
 metadata:
   internal: true

package/skills/manage-skill-dirs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: manage-skill-dirs
-description: "Partial Skill: invoke by name only — config-authoring/skill-dirs' curation engine for the extra skill-scan locations improve-skill's validate engine uses — loaded by the manage gateway, not triggered by users directly."
+description: "By name only"
 user-invocable: false
 metadata:
   internal: true

package/skills/repair-private-skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: repair-private-skills
-description: "Partial Skill: invoke by name only — the ACED manage-gateway engine that validates and repairs repo-private skill hygiene — loaded in-session by the ACED manage gateway, not user-triggered."
+description: "By name only"
 user-invocable: false
 metadata:
   internal: true

package/skills/report/SKILL.md

@@ -11,8 +11,8 @@ Generate a project-wide health dashboard across all eval suites.
 
 Scan the project spec (`.agents/specs/`) for behavioral-leaf nodes carrying an `eval.md` (subject + run policy) alongside their `<node>.feature`. For each, read:
 - `eval.md` for target path and threshold
-- The most recent file in `results/` (sort by filename descending)
-- The second-most-recent file in `results/` for trend (if it exists)
+- The most recent file in `.agents/aced/results/<target-slug>/` (sort by filename descending)
+- The second-most-recent file there for trend (if it exists)
 
 If no matching directories are found, report that no eval suites are initialized and suggest `sdd:start-mission` (the conductor resolves the ACED roles).
 

package/skills/run/SKILL.md

@@ -76,7 +76,7 @@ itself waiting on its own blind simulator — so it can report before its measur
 correct itself afterwards. Where an agent reports more than once, the **final** report for that agent
 id supersedes the earlier one entirely: never bank the first, never merge them. Do not compute
 results while any judge is still live; a run that ends with cases outstanding reports those cases as
-**unmeasured**, not as passes or failures. A judge that emits `BLOCKER: <reason>` in place of a score
+**unmeasured**, not as passes or failures. A judge that emits `BLOCKER: <reason>` in place of a score <!-- field-mandate-ignore: BLOCKER is aced-case-judge's output, which this skill reads -->
 is likewise unmeasured — surface it rather than folding it into the pass rate.
 
 ## Compute results

package/skills/skillify/SKILL.md

@@ -31,7 +31,7 @@ The tell is the *target artifact*, not the "reuse this" framing: an agent/person
 Load the **skill-design** governance before drafting:
 
 ```bash
-npx cyberplace@0.2.4 governance show skill-design
+npx cyberplace@<version> governance show skill-design   # resolve <version> via: npm view cyberplace version — never @latest
 ```
 
 Read stdout as the authoritative rules for principles, progressive disclosure, and description structure.
@@ -98,9 +98,9 @@ description: Use this skill when <trigger>. <One-line summary.>
 ### 2. <Step title>
 ...
 
-## What NOT to do
+## Pitfalls
 
-- <Common mistake or anti-pattern>
+- <Mistake — the failure it causes and what to do instead>
 ```
 
 Rules: