agent-skillboard 0.1.2 → 0.2.1

package/docs/install.md

@@ -1,34 +1,51 @@
-# Install And Bootstrap
-
-SkillBoard sits one layer above skill installers, plugin marketplaces, harness
-bundles, and local skill repositories.
-
+# Install And Bootstrap
+
+SkillBoard sits one layer above skill installers, plugin marketplaces, harness
+bundles, and local skill repositories.
+
+After install, ask your AI questions like "what skills can you use in this
+project?" or "can you make this reviewed skill available for the current
+workflow?" The AI runs SkillBoard behind the scenes: it reads the current brief,
+uses one current action id only after confirmation when policy would change, and
+runs the guard automatically before actual skill use. For already-allowed
+skills, the AI should tell you which skill it is about to use and which skill it
+used in the result instead of asking for another approval. That disclosure is an
+audit trace, not a permission prompt. You do not need to memorize the SkillBoard
+command loop.
+
 ## Install From npm
 
-Use npx when you want to bootstrap a project without keeping a global
-SkillBoard binary installed:
+Use no-prompt npx package execution when you want to bootstrap a project
+without keeping a global SkillBoard binary installed:
+
+AI/automation/operator details:
 
 ```bash
-npx agent-skillboard init
-npx agent-skillboard brief
-npx agent-skillboard doctor --summary
+npx --yes --package agent-skillboard skillboard init
+npx --yes --package agent-skillboard skillboard doctor --summary
+npx --yes --package agent-skillboard skillboard brief --workflow <workflow-from-init>
 ```
 
 SkillBoard does not make installed skills automatically callable. It imports
 trusted local skills as manual-only and keeps runtime/plugin skills quarantined
-until reviewed.
+until reviewed. When `init` creates or discovers workflows, use one of the
+workflow names it prints for the first brief. If `init` does not print a
+workflow, run the unscoped `brief` command it prints instead. The explicit
+package/binary spelling avoids an extra npx install prompt and keeps the
+executable name clear.
 
-In CI or scripts, use the explicit package/binary spelling:
+The equivalent `npm exec` spelling is also no-prompt and works well in scripts:
 
 ```bash
-npx --yes --package agent-skillboard skillboard init
-npx --yes --package agent-skillboard skillboard doctor --summary
 npm exec --yes --package agent-skillboard -- skillboard init
 npm exec --yes --package agent-skillboard -- skillboard doctor --summary
+npm exec --yes --package agent-skillboard -- skillboard brief --workflow <workflow-from-init>
 ```
 
 For repeated local use, install the CLI globally:
 
+AI/automation/operator details:
+
 ```bash
 npm install -g agent-skillboard
 skillboard init
@@ -43,10 +60,12 @@ The executable remains `skillboard` even though the npm package name is
 Use GitHub npx only when you intentionally want the current repository state
 before the next npm release:
 
+AI/automation/operator details:
+
 ```bash
 npx --yes --package github:NyXXiR/skillboard skillboard init
-npx --yes --package github:NyXXiR/skillboard skillboard brief
 npx --yes --package github:NyXXiR/skillboard skillboard doctor --summary
+npx --yes --package github:NyXXiR/skillboard skillboard brief --workflow <workflow-from-init>
 ```
 
 The equivalent `npm exec` spelling is explicit about the package and binary:
@@ -54,35 +73,38 @@ The equivalent `npm exec` spelling is explicit about the package and binary:
 ```bash
 npm exec --yes --package github:NyXXiR/skillboard -- skillboard init
 npm exec --yes --package github:NyXXiR/skillboard -- skillboard doctor --summary
+npm exec --yes --package github:NyXXiR/skillboard -- skillboard brief --workflow <workflow-from-init>
 ```
 
 ## Install From A Clone
 
 Use a clone when developing SkillBoard itself or testing unreleased changes:
 
+AI/automation/operator details:
+
 ```bash
 git clone https://github.com/NyXXiR/skillboard.git
 cd skillboard
 npm install
 node bin/skillboard.mjs init --dir /path/to/your/project
-node bin/skillboard.mjs brief --dir /path/to/your/project
 node bin/skillboard.mjs doctor --dir /path/to/your/project --summary
+node bin/skillboard.mjs brief --dir /path/to/your/project --workflow <workflow-from-init>
 ```
-
-## What init Does
-
+
+## What init Does
+
 `skillboard init` is the safe mutating step. npm installation itself does not
 modify a project, but init creates the files that let agents discover the control
 plane without a manual prompt and inventories already installed local agent
 skills.
-
-Created project files:
-
-- `skillboard.config.yaml`: desired state for workflows, capabilities, skills,
-  harnesses, and install units.
-- `skills/`: local skill root.
-- `.skillboard/reports/`: generated dashboard and reconcile output location.
-- `.skillboard/profiles/`: project-specific source profile location.
+
+Created project files:
+
+- `skillboard.config.yaml`: desired state for workflows, capabilities, skills,
+  harnesses, and install units.
+- `skills/`: local skill root.
+- `.skillboard/reports/`: generated dashboard and reconcile output location.
+- `.skillboard/profiles/`: project-specific source profile location.
 - `AGENTS.md`: Codex-style project instruction bridge.
 - `CLAUDE.md`: Claude Code project instruction bridge.
 
@@ -120,16 +142,30 @@ CI or automation gate. Use `--json` for an agent-readable health payload, or
 report. `skillboard status` is the same report under a shorter command name.
 
 For AI-mediated use, the generated bridge tells agents to answer availability
-questions from `skillboard brief --json`, not from memory or from raw
-`SKILL.md` bodies. The brief is read-only and organizes the response around
-"What your AI can use now", decisions the user can make once, hard safety
-blocks, inactive installed skills, and suggested action cards. Text briefs show
-action cards by default; JSON keeps them opt-in with `--include-actions`. The
-default text brief is compact for large skill sets: it keeps counts, top
-categories, the next safe action, short section previews, and short action
-summaries. Use `skillboard brief --verbose` when you need the full list or full
-copyable command details. Agents should still run `skillboard guard use ...`
-immediately before an actual skill invocation.
+questions by reading the current brief with `skillboard brief --json`, not from
+memory or from raw `SKILL.md` bodies. The brief is read-only and organizes the
+response around "What your AI can use now", decisions the user can make once,
+hard safety blocks, inactive installed skills, and suggested action cards. Text
+briefs show action cards by default; JSON keeps them opt-in with
+`--include-actions`. The default text brief is compact for large skill sets: it
+keeps counts, top categories, the next safe action, short section previews, and
+short action summaries. Use `skillboard brief --verbose` when an operator needs
+the full list or full copyable command details. Agents should still run
+`skillboard guard use ...` immediately before an actual skill invocation. A
+passing guard is not a user prompt; the agent should disclose the selected skill
+at the start and completion, and ask only if the guard denies use or a
+policy-changing action is needed.
+
+When the user asks which skill fits a task, the bridge tells agents to use
+`skillboard brief --intent <request> --json`, read `assistant_guidance.route`,
+and use `recommended_skill`, `fallback_skills`, `route_candidates`,
+`post_use_policy_suggestion`, and `guard_command` instead of guessing from raw
+skill text. Inspect
+`route_candidates` when several skills match so denied candidates and selected
+fallbacks are clear. If `post_use_policy_suggestion` is present, the agent
+should use the allowed routed skill first, then ask after completion whether to
+remember the suggested policy. If no skill matches, the agent should ask a
+clarifying question before choosing a skill.
 
 Action cards are change suggestions. Before an agent applies one that changes
 policy, trust, hooks, reset state, or skill references, it should request user
@@ -152,20 +188,34 @@ system prompt for the managed project:
 
 ```text
 Use SkillBoard as the source of truth for agent skill availability.
-Before answering what skills can be used, run:
-skillboard brief --json --dir /path/to/your/project
+Use the workflow generated by init, such as `hermes-codex-local-manual`, or a
+workflow you explicitly created for that Hermes profile.
+
+Before answering what skills can be used in that workflow, run:
+skillboard brief --workflow <workflow-name> --json --include-actions --dir /path/to/your/project
+
+When the user asks which skill fits a task, run:
+skillboard brief --workflow <workflow-name> --intent <request> --json --dir /path/to/your/project
+Read assistant_guidance.route. Use recommended_skill, fallback_skills,
+route_candidates, post_use_policy_suggestion, and guard_command. Inspect
+route_candidates when several skills match so denied candidates and selected
+fallbacks are clear. If post_use_policy_suggestion is present, use the allowed
+routed skill first, then ask after completion whether to remember the suggested
+policy. If no skill matches, ask a clarifying question before choosing a skill.
 
 Do not infer availability from installed SKILL.md files. Immediately before
 invoking a skill, run:
 skillboard guard use <skill-id> --workflow <workflow-name> --dir /path/to/your/project
 
-For suggested policy changes, ask the user to approve one current action id,
-then run:
-skillboard apply-action <action-id> --dir /path/to/your/project --yes --json
-```
+If the guard allows an already-approved skill, do not ask the user for another
+approval. Say at the start: "I will use <skill-id> for this request." Say at
+completion: "I used <skill-id> for this request." Treat that disclosure as an
+audit trace, not a permission prompt.
 
-Use the workflow generated by init, such as `hermes-codex-local-manual`, or a
-workflow you explicitly created for that Hermes profile.
+For suggested policy changes, ask the user to approve one current action id from
+the `--include-actions` brief, then run:
+skillboard apply-action <action-id> --workflow <workflow-name> --dir /path/to/your/project --yes --json
+```
 
 After installing a new local agent skill pack, plugin, workflow bundle, or
 harness, rescan before enabling anything:
@@ -275,24 +325,24 @@ may be wired into local agent/runtime configuration. Combine `--reset-config`,
 SkillBoard-owned lifecycle scaffolding while preserving local `skills/`.
 
 ## Upper-Layer Control
-
-After installing skill packs or harness bundles, represent them as install
-units:
-
-```bash
-skillboard import \
-  --profile github.mattpocock.skills \
-  --source-root /path/to/mattpocock-skills \
-  --out .skillboard/reports/mattpocock-import.yaml
-```
-
-The import output is a reviewable YAML fragment. Merge the accepted `skills` and
-`install_units` into `skillboard.config.yaml`; imported skills stay inactive
-until workflows and policies explicitly use them.
-
-For a direct but still safe apply path:
-
-```bash
+
+After installing skill packs or harness bundles, represent them as install
+units:
+
+```bash
+skillboard import \
+  --profile github.mattpocock.skills \
+  --source-root /path/to/mattpocock-skills \
+  --out .skillboard/reports/mattpocock-import.yaml
+```
+
+The import output is a reviewable YAML fragment. Merge the accepted `skills` and
+`install_units` into `skillboard.config.yaml`; imported skills stay inactive
+until workflows and policies explicitly use them.
+
+For a direct but still safe apply path:
+
+```bash
 skillboard import \
   --profile github.mattpocock.skills \
   --source-root /path/to/mattpocock-skills \
@@ -325,45 +375,45 @@ changes.
 
 ```yaml
 install_units:
-  github.mattpocock.skills:
-    kind: marketplace
-    source: npx skills@latest add mattpocock/skills
-    scope: user-global
-    provided_components:
-      - skills
-    components:
-      skills:
-        - matt.tdd
-```
-
-Then link each governed skill back to its owner:
-
-```yaml
-skills:
-  matt.tdd:
-    path: matt/tdd
-    status: active
-    invocation: workflow-auto
-    exposure: exported
-    owner_install_unit: github.mattpocock.skills
-```
-
-Run:
-
-```bash
-skillboard check --config skillboard.config.yaml --skills skills
-skillboard dashboard --config skillboard.config.yaml --skills skills --out .skillboard/reports/skill-map.md
-```
-
-This keeps multiple installed repositories visible as managed units instead of
-turning every skill into a global invocation candidate.
-
-## Adapter Direction
-
-Import support should be profile-driven, not hardcoded. A popular source such as
-`mattpocock/skills` or `oh-my-openagent` may ship with a built-in source profile,
-but that profile should be data that maps repository layout and defaults into the
-same install-unit model. Source-specific code should be limited to detector
-plugins for layouts that cannot be described declaratively.
-
-See [adapters.md](adapters.md).
+  github.mattpocock.skills:
+    kind: marketplace
+    source: npx skills@latest add mattpocock/skills
+    scope: user-global
+    provided_components:
+      - skills
+    components:
+      skills:
+        - matt.tdd
+```
+
+Then link each governed skill back to its owner:
+
+```yaml
+skills:
+  matt.tdd:
+    path: matt/tdd
+    status: active
+    invocation: workflow-auto
+    exposure: exported
+    owner_install_unit: github.mattpocock.skills
+```
+
+Run:
+
+```bash
+skillboard check --config skillboard.config.yaml --skills skills
+skillboard dashboard --config skillboard.config.yaml --skills skills --out .skillboard/reports/skill-map.md
+```
+
+This keeps multiple installed repositories visible as managed units instead of
+turning every skill into a global invocation candidate.
+
+## Adapter Direction
+
+Import support should be profile-driven, not hardcoded. A popular source such as
+`mattpocock/skills` or `oh-my-openagent` may ship with a built-in source profile,
+but that profile should be data that maps repository layout and defaults into the
+same install-unit model. Source-specific code should be limited to detector
+plugins for layouts that cannot be described declaratively.
+
+See [adapters.md](adapters.md).

package/docs/plans/skillboard-variant-lifecycle-handoff.md

@@ -0,0 +1,56 @@
+# SkillBoard Variant Lifecycle Handoff Plan
+
+This document was the handoff point for continuing the SkillBoard variant lifecycle implementation in `/home/nyxxir/skillboard`.
+
+## Status
+
+Completed on 2026-06-29.
+
+The authoritative execution plan was `.omo/plans/skillboard-variant-lifecycle.md`; all Todos 1-8 and final verification wave F1-F4 were completed. Ignored orchestration artifacts under `.omo/` and `.agent-work/` contain the detailed evidence and continuity logs.
+
+## Implemented Scope
+
+The feature adds a manual, auditable lifecycle for cross-agent skill variants:
+
+- `skillboard variant fork`
+- `skillboard variant status`
+- `skillboard variant approve`
+- `skillboard variant reset`
+- nested `skills.<id>.variant` metadata
+- digest-backed raw `SKILL.md` snapshots
+- documentation and tests for manual cross-agent adaptation
+
+## Product Decisions Preserved
+
+- `variant add` remains the existing immediate policy-registration command.
+- New lifecycle commands are additive: `fork`, `status`, `approve`, `reset`.
+- A draft fork is policy-valid but not callable:
+  - top-level `status: candidate`
+  - top-level `invocation: manual-only`
+  - no workflow active/preferred/fallback role until approval
+- `variant.status` is nested lifecycle metadata only. Top-level skill statuses were not expanded with `draft` or `approved`.
+- Snapshot files are raw `SKILL.md` content only.
+- Snapshot paths are config-relative and stay under `.skillboard/variant-snapshots/`.
+- Drift is computed from file digests; `drifted` is not persisted in config.
+- The implementation does not add automatic prompt conversion, LLM calls, new dependencies, or prompt rewriting.
+
+## Verification Summary
+
+Final verification passed:
+
+- `npm run check` → 244/244 tests pass.
+- Focused lifecycle suite → 24/24 tests pass.
+- Manual CLI QA evidence was written under `.omo/evidence/manual-variant-lifecycle/`.
+- F1-F4 evidence files were written under `.omo/evidence/`.
+- Independent final no-edit review passed with no blockers.
+- `git diff --check` and untracked whitespace checks passed.
+
+## Final Commit
+
+Planned commit message:
+
+```text
+feat(control): add variant lifecycle management
+```
+
+Do not push unless the user explicitly asks.