agent-skillboard 0.2.18 → 0.3.1

package/docs/adapters.md

@@ -1,127 +1,51 @@
 # Adapter Model
 
-SkillBoard should not hardcode one adapter per popular repository.
-
-The core should stay generic, and repository-specific behavior should live in
-data-driven source profiles wherever possible.
+Adapters discover skills and runtime components. They do not decide whether a
+skill is available.
 
 ## Layers
 
-1. Core scanners
-
-   Generic code that understands common primitives:
-
-   - `SKILL.md` folders with YAML frontmatter;
-   - plugin or marketplace manifests;
-   - package manager metadata;
-   - known user/project install scopes;
-   - command, hook, MCP, agent, and LSP component lists.
-
-2. Source profiles
-
-   Declarative profiles that describe how to interpret a source:
-
-   ```yaml
-   id: github.mattpocock.skills
-   source: mattpocock/skills
-   kind: marketplace
-   namespace: matt
-   target_path_prefix: matt
-   default_status: vendor
-   default_invocation: manual-only
-   default_exposure: exported
-   skill_paths:
-     - "skills/**/SKILL.md"
-     - "*/SKILL.md"
-   category_path_segment: 1
-   path_rules:
-     - pattern: "skills/deprecated/**/SKILL.md"
-       status: deprecated
-       invocation: deprecated
-       category: deprecated
-   ```
-
-   A profile can set namespace, default policy, component mapping, known manifest
-   paths, category extraction, lifecycle overrides, and risk hints without
-   requiring code changes.
-
-   `category_path_segment` reads a slash-separated path segment from the matched
-   `SKILL.md` path. For example, `skills/engineering/tdd/SKILL.md` with segment
-   `1` becomes category `engineering`. `path_rules` apply first-match overrides
-   for repository conventions such as `deprecated` or `in-progress` folders.
-
-3. Detector plugins
-
-   Code adapters are only for sources whose layout cannot be described
-   declaratively, such as installers that mutate multiple config files or require
-   command output parsing. These should be small detector modules that produce the
-   same install-unit data model as profiles.
-
-## Built-In Profiles Are Not Hardcoding
-
-SkillBoard can ship built-in profiles for popular ecosystems, but they should be
-treated as bundled data, not product logic. Users and communities should be able
-to add or override profiles without forking the CLI.
-
-Good built-ins:
-
-- `mattpocock/skills`: skill pack profile.
-- `code-yeongyu/oh-my-openagent`: harness/plugin bundle profile.
-- `anthropics/skills`: standard Agent Skills profile.
-- `wshobson/agents`: marketplace/plugin profile.
-- `VoltAgent/awesome-agent-skills`: catalog profile.
-
-Bad design:
-
-- `if repo === "mattpocock/skills"` branches in the import logic;
-- repo-specific policy decisions embedded in TypeScript;
-- automatic global activation because a known repository was installed.
-
-## Import Output Contract
-
-Every profile or detector should output the same normalized shape:
-
-- install units;
-- declared skills;
-- owner links via `owner_install_unit`;
-- component lists;
-- guessed capabilities;
-- default invocation and exposure;
-- warnings and decisions requiring user approval.
-
-Current CLI surface:
-
-```bash
-skillboard import \
-  --profile github.mattpocock.skills \
-  --source-root /path/to/source \
-  --out .skillboard/reports/import-fragment.yaml
+1. Core scanners read common `SKILL.md`, manifest, package, and component shapes.
+2. Source profiles describe repository paths and stable id mapping as data.
+3. Detector plugins handle installers whose layout cannot be expressed by a
+   profile.
+
+Every layer produces deterministic generated inventory. Source, provenance,
+path, digest, aliases, install-unit, and runtime-component observations are
+optional audit metadata and never determine availability.
+
+## Profile example
+
+```yaml
+id: example-pack
+source: example/skills
+namespace: example
+skill_paths:
+  - "skills/**/SKILL.md"
+path_rules:
+  - pattern: "skills/deprecated/**/SKILL.md"
+    category: deprecated
 ```
 
-The command emits a config fragment rather than mutating policy automatically.
-This keeps the control plane reviewable while still avoiding hardcoded adapter
-branches.
+Profiles may classify paths and describe components. They cannot enable,
+disable, share, or unshare skills.
 
-When the fragment is acceptable, the same importer can merge it:
+## Import contract
 
 ```bash
-skillboard import \
-  --profile github.mattpocock.skills \
-  --source-root /path/to/source \
-  --config skillboard.config.yaml \
-  --merge \
-  --dry-run
+skillboard import --profile <id-or-path> --source-root <dir> --out <fragment>
+skillboard import --profile <id-or-path> --source-root <dir> --config <path> --merge --dry-run
 ```
 
-Merge is append-only by default and refuses duplicate skill or install-unit ids.
-`--replace` is the explicit overwrite escape hatch. Drop `--dry-run` after
-reviewing the change plan.
-
-The reconciler then applies the same policy rules regardless of source.
+Import and inventory refresh create a missing valid v2 entry as
+`enabled: true`, `shared: false`, while preserving existing policy. Runtime and
+action permission remains with the agent or
+harness.
 
-## Default Safety
+This is a trust-neutral import: import does not review or approve a source and
+does not authorize any runtime component. Audit observations remain
+informational regardless of whether the fragment is only emitted or merged.
 
-New external skills should default to `vendor` or `candidate`, with
-`manual-only` or `router-only` invocation. Personal control skills can become
-`global-meta`, but external repositories should not gain `global-auto` through an
-adapter.
+Historical profile fields that encoded status, mode, exposure, or source review
+belong only to the v1 migration reader. New profiles must not emit them as
+availability policy.

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

@@ -1,124 +1,57 @@
 # 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.
+`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.
 
-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.
+`setup` is a repeatable user-level convergence operation. It observes agents
+and Hermes profiles added after installation, refreshes managed guidance and
+inventory, and materializes missing copies only for skills already marked
+`shared: true`. Custom agent roots are remembered outside policy as operational
+discovery state. They must not introduce project scope, source trust gates, or
+another authorization layer.
 
 ## 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.