agent-skillboard 0.1.2 → 0.2.1

package/docs/user-flow.md

@@ -1,10 +1,30 @@
 # First-Time Skill Control Flow
 
-This flow assumes a user installed SkillBoard because they want to see and
-control which agent skills can affect a workflow.
+This flow assumes a user installed SkillBoard because they want to ask their AI
+which skills are safe to use and approve changes without learning the control
+plane internals.
+
+When you ask your AI "what skills can you use here?" or "make this reviewed
+skill available for this workflow," the AI should read the current brief, show
+the relevant choice, ask only before applying one current action id when policy
+would change, and run the final guard automatically before invocation. For an
+already-allowed skill, the AI should state which skill it is about to use and
+which skill it used when reporting the result, not ask for another approval.
+That disclosure is an audit trace, not a permission prompt. You do not need to
+memorize the SkillBoard command loop. The command examples below are
+AI/automation/operator details for the agent, scripts, or people maintaining the
+setup.
+
+Before changing this routing or workflow UX, read
+[`docs/ai-skill-routing-goal.md`](ai-skill-routing-goal.md). The goal is to keep
+SkillBoard non-blocking: observe the request, route to the current best skill,
+work normally, explain briefly, ask after use only when a policy preference would
+help, and remember that usage policy without rewriting skill bodies.
 
 ## 1. Bootstrap The Control Plane
 
+AI/automation/operator details:
+
 ```bash
 skillboard init
 skillboard doctor
@@ -25,23 +45,49 @@ safety". Use
 `skillboard doctor --strict` when review-needed safe-mode warnings should fail
 automation.
 
-When the user asks the agent what it can use, the agent should run
-`skillboard brief --json` first and answer from the brief rather than reading
-skill files directly. The user-facing text output uses sections such as "What
-your AI can use now", "Needs your decision", and "Blocked for safety"; text
-briefs include previewable action cards by default, while the JSON form keeps
-action cards opt-in. For large skill sets, the default text brief stays compact:
-counts, top categories, next safe action, short previews per section, and short
-action summaries. Use `skillboard brief --verbose` when you need every skill and
-full copyable command details. Those action cards are suggestions only: the
-agent should pick one current action id from the brief, request confirmation
-before applying risk-bearing changes, then run
+When the user asks the agent what it can use, the agent should read the current
+brief with `skillboard brief --json` first and answer from the brief rather than
+reading skill files directly. The user-facing text output uses sections such as
+"What your AI can use now", "Needs your decision", and "Blocked for safety";
+text briefs include previewable action cards by default, while the JSON form
+keeps action cards opt-in. For large skill sets, the default text brief stays
+compact: counts, top categories, next safe action, short previews per section,
+and short action summaries. Use `skillboard brief --verbose` when an operator
+needs every skill and full copyable command details. Those action cards are
+suggestions only: the agent should pick one current action id from the brief,
+request confirmation before applying risk-bearing changes, then run
 `skillboard apply-action <action-id> --config skillboard.config.yaml --skills skills --yes --json`
 with `--workflow <name>` when a workflow is selected. The agent should read the
 returned post-apply brief before making the next availability claim.
 `apply-action` re-resolves the current brief and refuses stale action ids instead
 of replaying cached action-card shell text.
 
+When the user asks which skill fits a task, the agent can keep the same brief
+flow and include the user request as intent:
+
+```bash
+skillboard brief --intent "write tests before implementation" --workflow daily-workflow --config skillboard.config.yaml --skills skills --json
+```
+
+The returned `assistant_guidance.route` maps the request to a declared workflow
+capability or a workflow-bound skill metadata match, returns the recommended
+skill and fallbacks, and includes `match_source`, `matched_terms`,
+`recommendation_reason`, `route_candidates`, `post_use_policy_suggestion`, and the
+`skillboard guard use ...` command that still needs to pass immediately before
+invocation. `route_candidates` is the per-skill decision trace: it shows which
+matching skill was selected, which candidates were denied, and the guard reason
+when a preferred skill was skipped for an allowed fallback.
+`post_use_policy_suggestion` is the ask-after-use hook: if it is present, the
+agent should use the allowed routed skill first, then ask after completion
+whether to remember the suggested preference. Metadata matching can
+use declared skill id, path, category, and `SKILL.md` frontmatter
+name/description; it does not semantically rank raw skill bodies. If a
+recommended skill is already allowed, the agent should disclose it at the start
+and completion rather than ask for another approval. If no capability or
+workflow-bound skill matches, the agent should ask a clarifying question instead
+of guessing from raw `SKILL.md` text. Operators can still call
+`skillboard route ...` directly when they only need the recommendation payload.
+
 Run this again after installing agent packages, plugins, workflow bundles, or
 harnesses:
 
@@ -52,6 +98,8 @@ skillboard inventory refresh
 
 ## 2. Add A User-Owned Skill
 
+AI/automation/operator details:
+
 Create the skill under the project `skills/` directory:
 
 ```bash
@@ -97,6 +145,8 @@ does not grant automatic model invocation.
 
 ## 3. Inspect Influence Before Use
 
+AI/automation/operator details:
+
 ```bash
 skillboard explain user.helper \
   --config skillboard.config.yaml \
@@ -119,8 +169,11 @@ shows which workflows and required outputs would be affected before disabling or
 removing a skill.
 
 For an actual invocation, `brief` is not the final permission check. Agents
-should run `skillboard guard use ...` immediately before calling a skill so
-state changes made after the brief cannot slip through.
+should run `skillboard guard use ...` automatically immediately before calling a
+skill so state changes made after the brief cannot slip through. A passing guard
+does not require another user prompt; the agent should disclose the skill use at
+the start and in the final result. That disclosure is an audit trace, not a
+permission prompt.
 
 When wiring a guard hook from an action card, keep `apply-action` as the
 action-card primary flow:
@@ -130,7 +183,7 @@ skillboard apply-action <action-id> --workflow daily-workflow --config skillboar
 ```
 
 The raw hook commands are underlying manual operator detail for previewing and
-materializing an executable guard hook outside the action-card approval loop:
+materializing an executable guard hook outside the action-card control loop:
 
 ```bash
 skillboard hook install --workflow daily-workflow --config skillboard.config.yaml --skills skills --out .skillboard/hooks/daily-workflow-guard.sh --dry-run --json
@@ -142,6 +195,8 @@ before an operator materializes the matching non-dry-run hook command.
 
 ## 4. Enable, Disable, Or Prefer
 
+AI/automation/operator details:
+
 Enable the skill only for the workflow that should see it:
 
 ```bash
@@ -176,6 +231,8 @@ skillboard prefer user.helper \
 
 ## 5. Remove Governance Without Deleting User Files
 
+AI/automation/operator details:
+
 First try the safe remove:
 
 ```bash
@@ -206,6 +263,8 @@ This removes SkillBoard policy references only. It does not delete
 
 ## 6. Stop Using SkillBoard Safely
 
+AI/automation/operator details:
+
 ```bash
 skillboard uninstall --dry-run
 skillboard uninstall

package/docs/value-proof.md

@@ -0,0 +1,190 @@
+# SkillBoard Value Proof
+
+This is the README-facing proof that SkillBoard gives a user more useful control
+than manually inspecting `/skills` or a raw workflow skill list.
+
+The proof is executable:
+
+```bash
+node --test test/readme-value-proof.test.mjs
+```
+
+The test uses repository fixtures, not a mocked string. It drives the same CLI
+surfaces a user or agent would use.
+
+## GitHub-reader takeaway
+
+The raw list answers inventory questions: which skill declarations are connected
+to this workflow?
+
+SkillBoard answers operational safety questions: which skills can actually run
+now, why are others blocked, which skill fits the user's current request, and
+what approved action changes the next state?
+
+In the tested fixture, the raw list can make the workflow look ready because it
+shows `matt.tdd active workflow-auto`. SkillBoard refuses that unsafe claim and
+reports 0 usable skills, 8 blocked skills, 2 policy errors, and 1 policy warning
+before invocation.
+
+## Case 1: Raw skill list vs SkillBoard brief
+
+Fixture:
+
+```bash
+examples/skillboard.config.yaml
+examples/skills
+```
+
+Workflow:
+
+```bash
+codex-night-workflow
+```
+
+Raw skill list command:
+
+```bash
+node bin/skillboard.mjs list skills \
+  --config examples/skillboard.config.yaml \
+  --skills examples/skills \
+  --workflow codex-night-workflow
+```
+
+Observed raw-list result:
+
+- Raw skill list: 4 workflow-linked rows.
+- It includes `matt.tdd active workflow-auto`.
+- It does not include policy health.
+
+SkillBoard brief command:
+
+```bash
+node bin/skillboard.mjs brief \
+  --config examples/skillboard.config.yaml \
+  --skills examples/skills \
+  --workflow codex-night-workflow
+```
+
+Observed brief result:
+
+- SkillBoard brief: 0 usable skills.
+- 8 blocked skills.
+- Policy errors: 2.
+- Policy warnings: 1.
+- The policy diagnostics identify `matt.grill-with-docs` as a non-callable
+  fallback in `requirement-review`.
+
+What this proves:
+
+- The raw list can make a workflow look usable because it reports declared
+  state such as `active` and `workflow-auto`.
+- The SkillBoard brief checks policy health before use and refuses the unsafe
+  availability claim.
+
+## Case 2: Approved action-card flow
+
+Fixture:
+
+```bash
+examples/multi-source.config.yaml
+examples/multi-source-skills
+```
+
+The test copies this fixture to a temporary project, including `AGENTS.md` and
+`CLAUDE.md`, then runs:
+
+```bash
+node bin/skillboard.mjs brief ... --include-actions --json
+node bin/skillboard.mjs apply-action activate-skill:anthropic.docx ... --yes --json
+node bin/skillboard.mjs brief ... --json
+```
+
+Observed action-card flow result:
+
+- Before apply, usable skills: 2.
+- The current action list includes `activate-skill:anthropic.docx`.
+- Applying that one approved action returns `changed: true`.
+- After apply, usable skills: 2 -> 3.
+- `anthropic.docx` appears in `manual_allowed`.
+- The final brief has 0 policy errors.
+
+What this proves:
+
+- SkillBoard is not just a catalog. It gives a current action id, applies one
+  approved change, then re-resolves the next availability state.
+- The user does not need to hand-edit YAML or infer enable/disable impact from
+  raw `SKILL.md` files.
+
+## Case 3: AI-mediated approved action proof
+
+The test also simulates the product path without calling an external LLM:
+
+```bash
+node bin/skillboard.mjs brief ... --include-actions --json
+node bin/skillboard.mjs apply-action <current-action-id> ... --yes --json
+node bin/skillboard.mjs guard use anthropic.docx ... --json
+node bin/skillboard.mjs guard use matt.grill-me ... --json
+```
+
+Observed AI-mediated result:
+
+- The simulated user asks for `anthropic.docx` to be made available.
+- The AI reads `assistant_guidance.choices` from the current brief.
+- The chosen confirmation maps to the current
+  `activate-skill:anthropic.docx` action id.
+- `apply-action --yes --json` returns a post-apply brief.
+- The returned brief no longer offers the stale activate action and now offers
+  the matching disable action.
+- `guard use anthropic.docx --workflow codex-night-workflow` fails before the
+  approved action and succeeds after it.
+- `guard use matt.grill-me --workflow codex-night-workflow` stays denied
+  because the workflow blocks that skill.
+
+What this proves:
+
+- The proof uses the current `assistant_guidance` action id instead of cached
+  output.
+- SkillBoard keeps the guard as the final boundary before invocation.
+- Blocked skills still produce a non-zero, machine-readable denial.
+
+## Case 4: AI route picks the right allowed skill
+
+The same fixture also proves that SkillBoard can help the AI choose the right
+skill before invocation:
+
+```bash
+node bin/skillboard.mjs route "write tests before implementation" \
+  --config examples/multi-source.config.yaml \
+  --skills examples/multi-source-skills \
+  --workflow codex-night-workflow \
+  --json
+```
+
+Observed route result:
+
+- Matched capability: `test-first-implementation`.
+- Match source: `capability`.
+- Confidence: `high`.
+- Recommended skill: `matt.tdd`.
+- Fallback skill: `private.tdd-work-continuity`.
+- Guard command: `skillboard guard use matt.tdd ...`.
+- Guard result for `matt.tdd`: allowed.
+- Start disclosure: `I will use matt.tdd for this request.`
+- Finish disclosure: `I used matt.tdd for this request.`
+
+The proof also checks `brief --intent "write tests before implementation"` so
+the recommendation appears inside `assistant_guidance.route`, not only through
+the standalone `route` command.
+
+For a request outside the workflow's declared capability, such as "ship a
+powerpoint deck", SkillBoard returns no recommended skill and tells the AI to:
+Ask a clarifying question before choosing a skill.
+
+What this proves:
+
+- The AI can ask SkillBoard which skill fits a normal user request instead of
+  guessing from raw `SKILL.md` text.
+- Allowed skill use stays low-friction: the AI discloses use at start and
+  finish instead of asking for redundant approval.
+- No-match results are explicit, so the AI can ask a clarifying question rather
+  than forcing a poor skill choice.

package/docs/variant-lifecycle.md

@@ -0,0 +1,86 @@
+# Skill Variant Lifecycle
+
+SkillBoard treats a skill variant as a reviewed policy relationship plus a file snapshot trail. This is a manual adaptation lifecycle for cases such as `a -> claude.a`, where a human adapts a base skill for a specific agent or workflow and then asks SkillBoard to record, review, approve, or reset that relationship.
+
+Variant lifecycle is policy registration. SkillBoard records metadata, snapshots, digests, and workflow preference changes; it does not convert skill bodies, does not rewrite skill bodies, and does not guarantee semantic equivalence of skill bodies.
+
+## Lifecycle commands
+
+All examples use the global `skillboard` command. From a clone, replace `skillboard ` with `node bin/skillboard.mjs `.
+
+```bash
+skillboard variant add <variant-id> --from <base-id> --capability <name> --workflow <name> --config <path> --skills <dir> [--path <relative-skill-path>] [--mode manual-only|router-only|workflow-auto] [--category <name>] [--owner-install-unit <unit-id>] [--dry-run] [--json]
+skillboard variant fork <variant-id> --from <base-id> --capability <name> --workflow <name> --path <relative-skill-path> --config <path> --skills <dir> [--adapted-for <label>] [--category <name>] [--owner-install-unit <unit-id>] [--dry-run] [--json]
+skillboard variant status <variant-id> --config <path> --skills <dir> [--json]
+skillboard variant approve <variant-id> --config <path> --skills <dir> [--mode manual-only|router-only|workflow-auto] [--dry-run] [--json]
+skillboard variant reset <variant-id> --to-base|--to-approved --config <path> --skills <dir> [--yes] [--dry-run] [--mode manual-only|router-only|workflow-auto] [--json]
+```
+
+Use `--json` in scripts. Success payloads return the command-specific lifecycle fields such as `message`, `dryRun`, `changed`, `plan`, `filePlan`, `skill`, `variant`, and `warnings`. Errors include `ok: false` with a stable `error.code` and `error.message`. Usage errors exit with code `2` in both plain and JSON modes.
+
+## Recommended review flow
+
+1. Register or fork the variant from a known base:
+
+   ```bash
+   skillboard variant fork claude.a --from a --capability task-review --workflow claude-workflow --path claude/a --config skillboard.config.yaml --skills skills --json
+   ```
+
+   Fork creates a draft relationship and raw snapshot records without promoting the variant for automatic workflow use.
+
+2. Edit the variant `SKILL.md` by hand. This is where the actual adaptation happens.
+
+3. Inspect computed drift before approval:
+
+   ```bash
+   skillboard variant status claude.a --config skillboard.config.yaml --skills skills --json
+   ```
+
+   `variant.status` is the stored lifecycle state. `computedStatus` is derived from the live digest, the base digest, and the approved digest. A changed live file that differs from the base snapshot and has no matching approved snapshot is a draft candidate.
+
+4. Approve the reviewed variant:
+
+   ```bash
+   skillboard variant approve claude.a --config skillboard.config.yaml --skills skills --mode router-only --json
+   ```
+
+   Approval writes an approved snapshot, records the live digest, updates the skill metadata, and promotes the workflow preference/fallback policy for the chosen capability.
+
+5. Reset deliberately when needed:
+
+   ```bash
+   skillboard variant reset claude.a --to-base --config skillboard.config.yaml --skills skills --yes --json
+   skillboard variant reset claude.a --to-approved --config skillboard.config.yaml --skills skills --yes --json
+   ```
+
+   `--to-base` restores the base draft file and demotes workflow preference back to the base skill. `--to-approved` restores the approved snapshot and policy. Without `--yes`, mutating reset is rejected; use `--dry-run --json` to inspect the plan first.
+
+## Metadata and snapshots
+
+Variant metadata lives with the skill declaration in `skillboard.config.yaml`:
+
+```yaml
+skills:
+  claude.a:
+    variant:
+      of: a
+      capability: task-review
+      workflow: claude-workflow
+      status: approved
+      adapted_for: claude
+      base:
+        content_digest: sha256:...
+        snapshot: .skillboard/variant-snapshots/claude.a/base.md
+      approved:
+        content_digest: sha256:...
+        snapshot: .skillboard/variant-snapshots/claude.a/approved.md
+```
+
+Snapshots are raw file records under `.skillboard/variant-snapshots/<encoded-skill-id>/`. That directory is created lazily by lifecycle commands such as `variant fork` and `variant approve`; `skillboard init` does not need to pre-create snapshot directories. A reset can restore the base or approved content safely from those records. The lifecycle helpers verify that snapshot and live paths stay inside the configured workspace before writing files.
+
+## Safety boundaries
+
+- `variant fork` and `variant add` create policy metadata; they do not make a newly edited skill equivalent to the base.
+- `variant approve` should happen only after human review of the live `SKILL.md` body and the `variant status` digest output.
+- `variant reset` writes files only through the safe replacement helper and refuses ambiguous reset targets.
+- A variant is still governed by normal capability, workflow, exposure, install-unit, and invocation checks.