agent-skillboard 0.2.18 → 0.3.0

package/docs/ai-skill-routing-goal.md

@@ -1,124 +1,50 @@
 # AI Skill Routing Goal
 
-SkillBoard's product goal is to be a **permissive AI skill routing layer**. It keeps installed skills broadly available by default, then gives the AI a deterministic route when multiple skills could steer the same task. It should help an AI decide which skills and workflow policies apply to the current task without turning normal work into a settings session.
+SkillBoard is a user-level, non-blocking control plane for skill availability,
+cross-agent sharing, and overlap routing. It asks only two policy questions:
 
-This document is the goal reference for product work, routing changes, AI-facing brief changes, bridge updates, policy UX, and workflow UX.
+1. Is the skill enabled or disabled?
+2. Should SkillBoard share this skill with other supported agents?
 
-## Core principle
+Installed, valid skills default to enabled and agent-local. A user may disable
+a skill or opt that individual skill into sharing. An optional preference ranks
+enabled candidates that are actually installed for the current agent;
+preference never changes availability or copies files.
 
-SkillBoard should keep the user's work moving by default. Broadly available
-skills are normal; deterministic overlap resolution is the value.
+## Product loop
 
-The preferred loop is:
+Preserve `observe → route → work → explain briefly → ask after → remember`.
+Ordinary work must not stop for source review or pre-task configuration. Read
+the current brief when skills overlap, run the guard before use, and ask
+once only before a persistent policy change.
 
-```text
-observe → route → work → explain briefly → ask after → remember policy
-```
+## Boundaries
 
-That means:
+Source, provenance, digest, aliases, install-unit details, and risk are optional
+audit metadata and never determine availability. They belong in generated
+inventory and audit output, not user policy.
 
-1. **Observe** the user's request and current workflow context.
-2. **Route** to the most appropriate allowed skill or workflow policy without asking first when the risk is low, especially when several similar skills match.
-3. **Work** normally so SkillBoard does not become a pre-task settings checklist.
-4. **Explain briefly** which skill was used or skipped, only at the level needed for trust.
-5. **Ask after** the task when the routing choice was ambiguous, recurring, or likely to become a useful preference.
-6. **Remember policy** as usage guidance for future turns.
+Runtime and action authorization are outside SkillBoard's scope. The active
+agent or harness remains responsible for hooks, MCP servers, commands, network
+access, external writes, destructive actions, and secrets.
 
-## Non-goals
+SkillBoard does not rewrite `SKILL.md` bodies. It records enablement, explicit
+sharing, and optional routing preference. Agent presence (`installed_on`) is
+generated inventory, not user-managed policy.
 
-SkillBoard does not rewrite `SKILL.md` bodies as the primary way to improve outcomes.
-
-SkillBoard should not:
-
-- ask users to choose from a large skill inventory before ordinary work can begin;
-- require users to memorize the SkillBoard command loop;
-- infer permission from raw installed `SKILL.md` files;
-- silently let overlapping skills contaminate an answer;
-- make the default model feel deny-first when the user's skill set is already allowed;
-- mutate skill body content when a usage policy would solve the problem;
-- turn every allowed skill invocation into a permission prompt.
-
-## Simplification rule
-
-Do not simplify by deleting concepts blindly. Keep a concept only when it
-justifies itself against SkillBoard's routing identity: routing, overlap
-resolution, policy memory, or a less interruptive user flow. Concepts that do
-not pass that test should be removed, merged, or renamed into the smaller
-surface that does.
-
-## What SkillBoard controls
-
-SkillBoard controls **when and how a skill may influence an AI workflow**.
-
-The control object is a usage policy, not the skill body itself:
-
-- task or intent triggers;
-- workflow scope;
-- user, project, or team scope;
-- preferred and fallback skills;
-- exclusion rules;
-- overlap resolution summaries;
-- confidence or ambiguity thresholds;
-- disclosure and guard behavior;
-- pending policy suggestions to review later.
-
-## Skill usage modes
-
-Use these terms when designing routing, docs, brief output, or policy UX:
-
-- **Always use** — apply the skill automatically for a clearly scoped situation.
-- **Prefer** — choose this skill first when several skills match.
-- **Reference only** — read the skill as background guidance, but do not let its format or workflow dominate the final answer.
-- **Ask after use** — use the skill for low-risk ambiguous work, then ask whether to remember that choice.
-- **Ask before use** — ask first only when the action is risky, policy-changing, expensive, destructive, or externally visible.
-- **Avoid** — do not use the skill in a scoped situation unless the user explicitly asks.
-- **Block** — never use the skill while the policy remains in force.
-
-## User-facing flow
-
-A normal user should be able to talk to their AI naturally:
-
-```text
-User: "Help me refine this UX flow."
-AI: works using the routed skills.
-AI: "I used command-flow-ux-audit as the primary reference and left TDD skills out because this was not a code-editing task. Should I treat that as the default for UX-flow requests?"
-```
-
-The confirmation is intentionally small and late. It records a policy preference without interrupting the work that caused the user to ask for help.
-
-## AI-facing behavior
-
-AI integrations should:
-
-- read the current SkillBoard brief before making skill availability claims;
-- route from the current request and workflow instead of searching raw skill bodies;
-- run the guard automatically immediately before invoking an allowed skill;
-- disclose allowed skill use at the start and completion;
-- ask the user before applying policy-changing action cards;
-- reread the post-apply brief before making another availability claim;
-- propose remembered policy only when the user has seen enough context to judge the result.
+`shared: false` means SkillBoard does not propagate the skill. It does not
+remove or quarantine copies that the user or another tool installed. With
+`shared: true`, SkillBoard materializes a managed shared source and compatible
+managed copies for supported agents, while preserving every agent-owned
+original.
 
 ## Development rule
 
-Read `docs/ai-skill-routing-goal.md` before changing routing, brief, bridge, policy, or workflow UX.
-
-Any implementation that affects AI-mediated skill selection should preserve the non-blocking loop:
-
-```text
-observe → route → work → explain briefly → ask after → remember policy
-```
-
-When in doubt, prefer a small usage-policy change over skill-body mutation or a larger pre-task setup flow.
-
-## MVP acceptance criteria
-
-A change moves SkillBoard toward this goal when:
+Every route, brief, guard, dashboard, generated bridge, and policy mutation must
+project the same v2 meaning. Normal commands use one home control plane from any
+working directory; project initialization is not part of the v2 flow. Never
+reintroduce source reputation, workflow scope, or legacy state fields as hidden
+authorization checks.
 
-- ordinary allowed-skill work proceeds without a pre-task skill-selection prompt;
-- ambiguous but low-risk choices can be handled with ask-after-use policy suggestions;
-- multiple allowed matching skills stay available while the routed skill is deterministic;
-- risky or policy-changing actions still require explicit confirmation before apply;
-- `brief --json` gives AI integrations a stable way to discover the goal document and routing guidance;
-- text output stays compact by default and reserves verbose detail for explicit requests;
-- users can understand why a skill was used, skipped, or blocked;
-- SkillBoard records usage policy separately from skill body content.
+Version 1 is migration input only. It has a one-release read-only window in the
+v0.3 release and is removed in v0.4.0.

package/docs/capabilities.md

@@ -1,113 +1,26 @@
-# Capabilities
+# Capabilities and Preferences
 
-SkillBoard uses **capabilities** as a contract layer between a workflow and the skills that satisfy it. A capability is an abstract need, such as "requirement-clarification" or "test-first-implementation". Skills claim to provide it; workflows declare they require it.
+Policy schema v2 does not use capabilities for authorization. Availability is
+an enabled policy entry plus observed installation on the current agent.
 
-There are two places where capabilities appear:
-
-1. **Global capability catalog** in `skillboard.config.yaml` (`capabilities`)
-2. **Workflow-scoped requirements** under each workflow (`required_capabilities`)
-
-## Global Capability Catalog
-
-The global catalog defines a capability once for the whole project.
-
-```yaml
-capabilities:
-  requirement-clarification:
-    canonical: meerkat.requirement-intake
-    alternatives:
-      - matt.grill-me
-      - matt.grill-with-docs
-    default_policy: router-only
-```
-
-- `canonical`: the preferred skill for this capability.
-- `alternatives`: other skills that may satisfy the same capability.
-- `default_policy`: the suggested invocation policy when a workflow requires the capability but does not override it.
-
-The catalog is used for project-wide policy checks, such as:
-
-- Is the canonical skill declared?
-- Does a skill that claims `canonical_for` actually match the catalog?
-- Are fallback or alternative skill references valid?
-
-## Workflow-Scoped Requirements
-
-A workflow can require a capability and pin how it should be resolved.
-
-```yaml
-workflows:
-  requirement-review:
-    required_capabilities:
-      requirement-clarification:
-        preferred: meerkat.requirement-intake
-        fallback:
-          - matt.grill-with-docs
-        policy: router-only
-```
-
-- `preferred`: the skill to use first for this workflow.
-- `fallback`: ordered alternatives if the preferred skill is unavailable or blocked.
-- `policy`: invocation mode that applies when the capability is resolved in this workflow.
-
-## Resolution Flow
-
-When a workflow is selected, SkillBoard resolves each required capability like this:
-
-```
-workflow.required_capabilities
-        │
-        ▼
-  capability name
-        │
-        ▼
-  lookup global catalog (capabilities.<name>)
-        │
-        ▼
-  preferred in workflow? ──yes──► use workflow.preferred with workflow.policy
-        │
-       no
-        ▼
-  use catalog.canonical with workflow.policy
-        │
-        ▼
-  fallback order: workflow.fallback, then catalog.alternatives
-```
-
-If no preferred skill is set in the workflow, the global catalog's canonical skill is used. Fallbacks are checked in order: first the workflow's own fallback list, then the global alternatives.
-
-## Explicit Skill Variants
-
-Use `skillboard variant add claude.a --from a --capability task-review --workflow claude-workflow --path claude/a ...` to record a user-approved `a -> claude.a` variant. SkillBoard adds the variant to the capability alternatives, makes it preferred for the named workflow, and keeps the base skill available as fallback.
-
-This is policy registration, not prompt migration. For a reviewed manual adaptation lifecycle, run `skillboard variant fork <variant-id>` to create a draft and raw snapshot, edit the variant body by hand, inspect `skillboard variant status <variant-id>` for `variant.status` and computed drift, then use `skillboard variant approve <variant-id>` or `skillboard variant reset <variant-id>`. SkillBoard records user-approved variants and consistent workflow policy across agents; it does not convert skill bodies, does not rewrite skill bodies, and does not guarantee semantic equivalence of skill bodies.
-
-## Global vs Workflow: When to Use Each
-
-| Use case | Use global catalog | Use workflow requirement |
-|----------|-------------------|--------------------------|
-| Define a canonical skill for a capability | ✅ | |
-| List known alternatives project-wide | ✅ | |
-| Provide a default invocation policy | ✅ | |
-| Pin a different skill for one workflow | | ✅ |
-| Add workflow-specific fallbacks | | ✅ |
-| Override invocation policy for a workflow | | ✅ |
-
-## Skill Declaration
-
-A skill declares that it satisfies a capability through `canonical_for`:
+Use optional `preference` when one matching skill should rank ahead of another:
 
 ```yaml
 skills:
-  meerkat.requirement-intake:
-    canonical_for:
-      - requirement-clarification
+  test-first:
+    enabled: true
+    shared: false
+    preference:
+      intents: [implementation, testing]
+      priority: 100
 ```
 
-If `canonical_for` references a capability, the global catalog must list the same skill as its `canonical`. Otherwise the policy check reports a mismatch.
+Preference ranks only and never changes availability. Explicit user selection
+wins among guard-allowed candidates.
 
-## Safety Notes
+Version 1 capability catalogs and workflow requirements are migration input
+only. Migration may convert names to intent terms and priorities, reports
+discarded policy fields, and never carries capability policy into the v2 guard.
 
-- A workflow requirement can only reference capabilities defined in the global catalog.
-- `policy` in a workflow requirement must be a valid invocation value.
-- Prefer `workflow-auto` or `router-only` for workflow requirements; reserve `global-auto` for explicitly global-meta skills.
+Manual skill variants are content-management records, not authorization.
+Runtime and action permission checks stay with the agent or harness.