@alavida/agentpack 0.1.1 → 0.1.3

package/README.md

@@ -88,7 +88,9 @@ agentpack skills validate domains/operations/skills/agonda-prioritisation
 agentpack skills dev domains/operations/skills/agonda-prioritisation
 ```
 
-Use `skills dev` when you want the skill linked into `.claude/skills/` and `.agents/skills/` for local runtime testing.
+Use `skills dev` when you want the skill linked into `.claude/skills/` and `.agents/skills/` for local runtime testing. It now also starts a localhost development workbench by default for one selected skill, showing immediate provenance sources, direct required skills, lifecycle state, and workbench actions such as validation and stale checks.
+
+Pass `--no-dashboard` if you want the original CLI-only linking workflow without the local dashboard.
 
 If your agent session was already running, start a fresh session after linking so the runtime can pick up the newly materialized skill.
 
@@ -107,6 +109,8 @@ agentpack plugin validate path/to/plugin
 agentpack plugin build path/to/plugin
 ```
 
+`plugin inspect` and `plugin validate` now emit actionable structured diagnostics when a plugin target is missing required files such as `package.json` or `.claude-plugin/plugin.json`.
+
 For watch mode during development:
 
 ```bash
@@ -219,6 +223,12 @@ Implemented today:
 
 Hosted docs: https://docs.alavida.ai
 
+For a repo-local demo and manual testing target, initialize submodules and use [`sandbox/acme-demo/`](./sandbox/acme-demo).
+
+```bash
+git submodule update --init --recursive
+```
+
 Docs source: [`docs/`](./docs)
 
 For local docs preview as a contributor:
@@ -251,7 +261,11 @@ This package also ships an agent-facing skill under:
 node_modules/@alavida/agentpack/skills/agentpack-cli/SKILL.md
 ```
 
-If your repo uses TanStack Intent, you can map that shipped skill into your agent workflow so the agent knows how to use `agentpack` correctly inside downstream repos. This is optional. It is not required to use the CLI.
+Consumers can use TanStack Intent in their repos to map that shipped skill into their agent workflow so the agent knows how to use `agentpack` correctly.
+
+This is recommended if you want downstream coding agents to follow the right `agentpack` lifecycle automatically.
+
+It is still optional. You do not need Intent to install or run the CLI itself.
 
 ## Metadata Policy
 

package/bin/intent.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Auto-generated by @tanstack/intent setup
+// Exposes the intent end-user CLI for consumers of this library.
+// Commit this file, then add to your package.json:
+//   "bin": { "intent": "./bin/intent.js" }
+try {
+  await import('@tanstack/intent/intent-library')
+} catch (e) {
+  if (e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND') {
+    console.error('@tanstack/intent is not installed.')
+    console.error('')
+    console.error('Install it as a dev dependency:')
+    console.error('  npm add -D @tanstack/intent')
+    console.error('')
+    console.error('Or run directly:')
+    console.error('  npx @tanstack/intent@latest list')
+    process.exit(1)
+  }
+  throw e
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@alavida/agentpack",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Package-backed skills lifecycle CLI for agent skills and plugins",
   "type": "module",
   "bin": {
-    "agentpack": "bin/agentpack.js"
+    "agentpack": "bin/agentpack.js",
+    "intent": "./bin/intent.js"
   },
   "files": [
     "bin",
@@ -18,7 +19,8 @@
     "validate:live": "node scripts/live-validation.mjs",
     "smoke:monorepo": "node scripts/smoke-monorepo.mjs",
     "docs:dev": "cd docs && mint dev",
-    "intent:validate": "npx @tanstack/intent validate"
+    "intent:validate": "npx @tanstack/intent validate",
+    "build:dashboard": "node scripts/build-dashboard.mjs"
   },
   "keywords": [
     "agentpack",
@@ -43,10 +45,14 @@
     "docs": "https://github.com/alavida-ai/agentpack/tree/main/docs"
   },
   "dependencies": {
-    "commander": "^13.0.0"
+    "commander": "^13.0.0",
+    "d3": "^7.9.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1"
   },
   "devDependencies": {
-    "@tanstack/intent": "^0.0.14"
+    "@tanstack/intent": "^0.0.14",
+    "esbuild": "^0.25.10"
   },
   "engines": {
     "node": ">=20.0.0"

package/skills/agentpack-cli/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agentpack-cli
 description: Use the agentpack CLI correctly when treating knowledge as a package. Apply the authored skill lifecycle, plugin lifecycle, source-backed validation, install flow, and bundled plugin artifact flow without mixing those stages together.
-library_version: 0.1.1
+library_version: 0.1.2
 sources:
   - README.md
   - docs/introduction.mdx
@@ -56,17 +56,26 @@ Default flow:
 - `agentpack skills inspect <skill-dir>`
 - `agentpack skills validate <skill-dir>`
 - `agentpack skills dev <skill-dir>` if local runtime testing is needed
+- `agentpack skills dev --no-dashboard <skill-dir>` if the user wants to skip the local workbench
 
 Key idea:
 
 - `SKILL.md.requires` is the source of truth
 - `package.json.dependencies` is the compiled mirror
 - `validate` and `dev` sync dependencies automatically
+- `skills validate` records the current source-hash snapshot in `.agentpack/build-state.json`
 - `skills dev` materializes the compiled skill artifact for runtime use
 
+Persistence rule:
+
+- commit `.agentpack/build-state.json` so stale detection works across GitHub, CI, and teammate machines
+- commit `.agentpack/catalog.json` in authoring repos
+- do not commit `.agentpack/install.json`
+
 Runtime notes:
 
 - after `skills dev` writes to `.claude/skills/` or `.agents/skills/`, start a fresh agent session if the current one was already running
+- `skills dev` starts a localhost workbench by default for one selected skill, with provenance edges, direct required skills, and actions like validate or stale checks
 - do not reload `metadata.sources` manually once the dev-linked skill exists; trust the compiled `SKILL.md` artifact unless you are explicitly updating the skill
 - invoke the resulting skill through the runtime's skill mechanism, not by opening the file and reading it as plain text
 
@@ -99,6 +108,7 @@ Key idea:
 - plugin-local `requires` remain the dependency truth
 - packaged skills are vendored into the built artifact
 - the plugin artifact is the thing consumers run
+- `plugin inspect` and `plugin validate` can return structured diagnostics with `path`, `nextSteps`, and example fixes when plugin definition files are missing or malformed
 
 Read [plugin-lifecycle.md](references/plugin-lifecycle.md) when the user needs the full artifact flow.
 
@@ -112,6 +122,11 @@ Default flow:
 - `agentpack skills stale <skill>`
 - `agentpack skills validate <skill>`
 
+Key idea:
+
+- `skills stale` compares current source hashes to the last validated snapshot in `.agentpack/build-state.json`
+- if that file is not committed, stale detection will not persist across clones or CI runs
+
 ## Conceptual Frame
 
 When the user is reasoning about the model itself, explain agentpack this way:

package/skills/agentpack-cli/references/skill-lifecycle.md

@@ -42,9 +42,15 @@ Use this when the user is creating or changing a packaged skill in the same repo
 What each step means:
 
 - `inspect` explains what the skill currently is
-- `validate` checks package readiness and source existence
+- `validate` checks package readiness, source existence, and records the validated source snapshot in `.agentpack/build-state.json`
 - `dev` links the skill into `.claude/skills/` and `.agents/skills/` for local testing
 
+Important persistence behavior:
+
+- commit `.agentpack/build-state.json` if you want `skills stale` to work across GitHub, CI, and teammate machines
+- commit `.agentpack/catalog.json` in authoring repos
+- do not commit `.agentpack/install.json`
+
 Important runtime behavior:
 
 - if the agent session was already running before `skills dev`, start a fresh session so the runtime can rescan the linked skill
@@ -76,3 +82,17 @@ Consumption stage:
 - `skills env`
 
 Do not substitute one for the other.
+
+## Stale Detection Contract
+
+`skills stale` is not comparing against memory or local runtime state.
+
+It compares current source hashes against the last validated snapshot recorded in `.agentpack/build-state.json`.
+
+That means:
+
+1. run `agentpack skills validate <skill-dir>`
+2. commit the updated `.agentpack/build-state.json`
+3. later source changes can be detected by `agentpack skills stale`
+
+If the build-state file is not committed, stale detection will only work on the machine where validation was last run.

package/skills/authoring-skillgraphs-from-knowledge/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: authoring-skillgraphs-from-knowledge
+description: Use when authoring packaged skills from source knowledge with valid SKILL.md metadata, package.json release fields, provenance sources, and requires edges in agentpack.
+type: core
+library: agentpack
+library_version: "0.1.2"
+sources:
+  - "alavida-ai/agentpack:docs/commands.mdx"
+  - "alavida-ai/agentpack:docs/architecture.mdx"
+  - "alavida-ai/agentpack:skills/agentpack-cli/SKILL.md"
+---
+
+# Agentpack - Authoring Skillgraphs From Knowledge
+
+## Setup
+
+```yaml
+---
+name: value-copywriting
+description: Messaging and copywriting guidance.
+metadata:
+  sources:
+    - domains/value/knowledge/selling-points.md
+requires:
+  - @alavida-ai/methodology-gary-provost
+---
+```
+
+```json
+{
+  "name": "@alavida-ai/value-copywriting",
+  "version": "1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alavida-ai/knowledge-base.git"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  },
+  "files": ["SKILL.md"],
+  "dependencies": {
+    "@alavida-ai/methodology-gary-provost": "^1.0.0"
+  }
+}
+```
+
+## Core Patterns
+
+### Author `requires` in `SKILL.md`
+
+```yaml
+requires:
+  - @alavida-ai/methodology-gary-provost
+```
+
+### Validate to sync and record provenance
+
+```bash
+agentpack skills validate domains/value/skills/copywriting
+```
+
+### Inspect by path or package name
+
+```bash
+agentpack skills inspect domains/value/skills/copywriting
+agentpack skills inspect @alavida-ai/value-copywriting
+```
+
+## Common Mistakes
+
+### CRITICAL Editing package dependencies instead of requires
+
+Wrong:
+
+```json
+{
+  "dependencies": {
+    "@alavida-ai/methodology-gary-provost": "^1.0.0"
+  }
+}
+```
+
+Correct:
+
+```yaml
+requires:
+  - @alavida-ai/methodology-gary-provost
+```
+
+`requires` is the authored dependency truth; `package.json.dependencies` is the compiled mirror.
+
+Source: skills/agentpack-cli/SKILL.md
+
+### HIGH Shipping a skill package without SKILL.md in files
+
+Wrong:
+
+```json
+{
+  "files": ["README.md"]
+}
+```
+
+Correct:
+
+```json
+{
+  "files": ["SKILL.md"]
+}
+```
+
+A package that excludes `SKILL.md` is structurally invalid even if the authored source exists locally.
+
+Source: docs/commands.mdx
+
+### HIGH Using missing or invalid package metadata
+
+Wrong:
+
+```json
+{
+  "name": "@alavida-ai/value-copywriting"
+}
+```
+
+Correct:
+
+```json
+{
+  "name": "@alavida-ai/value-copywriting",
+  "version": "1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alavida-ai/knowledge-base.git"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  }
+}
+```
+
+Release-readiness checks enforce package identity and distribution metadata during `skills validate`.
+
+Source: docs/commands.mdx
+
+## References
+
+- [Authored metadata](references/authored-metadata.md)

package/skills/authoring-skillgraphs-from-knowledge/references/authored-metadata.md

@@ -0,0 +1,6 @@
+# Authored Metadata
+
+- `SKILL.md` owns `name`, `description`, `metadata.sources`, and `requires`
+- `package.json` owns distribution metadata such as package name, version, publish config, and repository
+- `skills validate` syncs managed dependencies from `requires` and refreshes `.agentpack/build-state.json`
+

package/skills/developing-and-testing-skills/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: developing-and-testing-skills
+description: Use when iterating locally on a packaged skill with agentpack skills dev, the localhost workbench, repo-local materialization, and runtime testing feedback loops.
+type: core
+library: agentpack
+library_version: "0.1.2"
+sources:
+  - "alavida-ai/agentpack:docs/commands.mdx"
+  - "alavida-ai/agentpack:docs/introduction.mdx"
+  - "alavida-ai/agentpack:README.md"
+requires:
+  - authoring-skillgraphs-from-knowledge
+  - maintaining-skillgraph-freshness
+---
+
+# Agentpack - Developing And Testing Skills
+
+## Setup
+
+```bash
+cd knowledge-base
+agentpack skills dev domains/value/skills/copywriting
+```
+
+## Core Patterns
+
+### Start local dev with the workbench
+
+```bash
+agentpack skills dev domains/value/skills/copywriting
+```
+
+This links the selected skill into `.claude/skills/` and `.agents/skills/` and starts a localhost workbench by default.
+
+### Use CLI-only mode when you explicitly do not want the dashboard
+
+```bash
+agentpack skills dev --no-dashboard domains/value/skills/copywriting
+```
+
+### Stop and clean up local links
+
+```bash
+agentpack skills unlink value-copywriting
+```
+
+## Common Mistakes
+
+### HIGH Expecting the current agent session to pick up new links
+
+Wrong:
+
+```bash
+agentpack skills dev domains/value/skills/copywriting
+```
+
+Correct:
+
+```bash
+agentpack skills dev domains/value/skills/copywriting
+# start a fresh agent session if one was already running
+```
+
+Already-running agent sessions may not rescan newly materialized skills.
+
+Source: README.md
+
+### MEDIUM Assuming unresolved requires block local dev links
+
+Wrong:
+
+```bash
+agentpack skills dev domains/value/skills/copywriting
+# ignore the unresolved warning because linking succeeded
+```
+
+Correct:
+
+```bash
+agentpack skills dev domains/value/skills/copywriting
+agentpack skills dependencies @alavida-ai/value-copywriting
+agentpack skills missing
+```
+
+`skills dev` can still link the selected skill while warning about unresolved packaged requirements.
+
+Source: docs/commands.mdx
+
+### MEDIUM Using no-dashboard mode and expecting workbench actions
+
+Wrong:
+
+```bash
+agentpack skills dev --no-dashboard domains/value/skills/copywriting
+```
+
+Correct:
+
+```bash
+agentpack skills dev domains/value/skills/copywriting
+```
+
+`--no-dashboard` suppresses the localhost workbench entirely.
+
+Source: docs/introduction.mdx
+
+## References
+
+- [Local workbench](references/local-workbench.md)

package/skills/developing-and-testing-skills/references/local-workbench.md

@@ -0,0 +1,7 @@
+# Local Workbench
+
+- Default `skills dev` starts a localhost workbench for one selected skill
+- The workbench shows provenance sources, direct required skills, lifecycle state, and actions such as validate or stale checks
+- `--no-dashboard` keeps the old CLI-only flow
+- Editing `SKILL.md`, `package.json`, or tracked source files refreshes the model during the dev session
+

package/skills/getting-started-skillgraphs/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: getting-started-skillgraphs
+description: Use when starting from an empty repo or empty skillgraph and needing the first correct authoring loop, lifecycle framing, repo-root routing, and inspect/validate/dev command flow in agentpack.
+type: lifecycle
+library: agentpack
+library_version: "0.1.2"
+sources:
+  - "alavida-ai/agentpack:docs/introduction.mdx"
+  - "alavida-ai/agentpack:docs/commands.mdx"
+  - "alavida-ai/agentpack:README.md"
+---
+
+# Agentpack - Getting Started Skillgraphs
+
+## Setup
+
+```bash
+npm install -g @alavida/agentpack
+cd knowledge-base
+agentpack skills inspect domains/value/skills/copywriting
+agentpack skills validate domains/value/skills/copywriting
+agentpack skills dev domains/value/skills/copywriting
+```
+
+## Core Patterns
+
+### Start in the authoring repo
+
+```bash
+cd knowledge-base
+agentpack skills validate domains/value/skills/copywriting
+agentpack skills stale
+```
+
+Run source-backed commands from the repo that owns the files in `metadata.sources`.
+
+### Use the authored workflow first
+
+```bash
+agentpack skills inspect domains/value/skills/copywriting
+agentpack skills validate domains/value/skills/copywriting
+agentpack skills dev domains/value/skills/copywriting
+```
+
+### Switch to consumer install only after publishing
+
+```bash
+cd consumer-repo
+agentpack skills install @alavida-ai/value-copywriting
+agentpack skills env
+```
+
+## Common Mistakes
+
+### CRITICAL Wrong repo root for source-backed commands
+
+Wrong:
+
+```bash
+cd tooling/agentpack
+agentpack skills validate ../knowledge-base/domains/value/skills/copywriting
+```
+
+Correct:
+
+```bash
+cd knowledge-base
+agentpack skills validate domains/value/skills/copywriting
+```
+
+`metadata.sources` resolve relative to the current repo root, so validating from the wrong repo breaks provenance checks.
+
+Source: docs/introduction.mdx
+
+### HIGH Starting with install instead of authoring validation
+
+Wrong:
+
+```bash
+agentpack skills install @alavida-ai/value-copywriting
+```
+
+Correct:
+
+```bash
+agentpack skills inspect domains/value/skills/copywriting
+agentpack skills validate domains/value/skills/copywriting
+```
+
+`install` is the consumer lifecycle; authored skills need inspect and validate first.
+
+Source: skills/agentpack-cli/SKILL.md
+
+### MEDIUM Treating the dashboard as the authoring surface
+
+Wrong:
+
+```bash
+agentpack skills dev domains/value/skills/copywriting
+```
+
+Correct:
+
+```bash
+edit domains/value/skills/copywriting/SKILL.md
+agentpack skills dev domains/value/skills/copywriting
+```
+
+The localhost workbench is for visibility during `skills dev`, not the source of truth for authored behavior.
+
+Source: docs/commands.mdx
+
+## References
+
+- [Command routing](references/command-routing.md)

package/skills/getting-started-skillgraphs/references/command-routing.md

@@ -0,0 +1,7 @@
+# Command Routing
+
+- Authoring repo: `skills inspect`, `skills validate`, `skills dev`, `skills stale`
+- Consumer repo: `skills install`, `skills env`, `skills status`, `skills missing`
+- Plugin shell: `plugin inspect`, `plugin validate`, `plugin build`, `plugin dev`
+- If sources live under `domains/.../knowledge/*.md`, run authored commands from that repo root
+