@alavida/agentpack 0.1.2 → 0.1.4

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:
@@ -243,6 +253,28 @@ Validate the shipped agent skill:
 npm run intent:validate
 ```
 
+## Releases
+
+This repo now uses Changesets for versioning and publishing.
+
+Normal maintainer flow:
+
+1. Add a changeset in any PR that changes user-facing behavior.
+2. Merge the feature PR to `main`.
+3. Let GitHub open or update the `Version Packages` release PR.
+4. Review and merge that release PR.
+5. The merge publishes to npm automatically.
+
+Useful local commands:
+
+```bash
+npx changeset
+npm run version-packages
+npm run release
+```
+
+Manual git tags are no longer the normal release path.
+
 ## Optional Agent Integration
 
 This package also ships an agent-facing skill under:
@@ -263,10 +295,12 @@ In authoring repos:
 
 - commit `.agentpack/build-state.json`
 - commit `.agentpack/catalog.json`
+- commit `skills/sync-state.json` when maintaining shipped Intent skills
 
 In consumer/runtime repos:
 
 - do not commit `.agentpack/install.json`
+- do not commit `.agentpack/dev-session.json`
 
 ## License
 

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.2",
+  "version": "0.1.4",
   "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,11 @@
     "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"
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "changeset publish",
+    "intent:validate": "npx @tanstack/intent validate",
+    "build:dashboard": "node scripts/build-dashboard.mjs"
   },
   "keywords": [
     "agentpack",
@@ -43,10 +48,15 @@
     "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"
+    "@changesets/cli": "^2.30.0",
+    "@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.3
 sources:
   - README.md
   - docs/introduction.mdx
@@ -56,6 +56,7 @@ 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:
 
@@ -70,10 +71,16 @@ 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`
+- do not commit `.agentpack/dev-session.json`
+- commit `skills/sync-state.json` when maintaining the shipped Intent skills for this package
 
 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
+- `skills dev` records the active session in `.agentpack/dev-session.json` so the next run can clean up stale runtime links after abnormal termination
+- if a stale local dev session blocks startup, use `agentpack skills dev cleanup` and escalate to `agentpack skills dev cleanup --force` only when the recorded pid is a false positive
+- use `agentpack skills unlink <root> --recursive` when you need to remove one active dev root plus its transitive local runtime links
 - 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
 
@@ -106,6 +113,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.
 

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.3"
+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,127 @@
+---
+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.3"
+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/`, records the active dev session in `.agentpack/dev-session.json`, 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
+```
+
+If the previous dev process was killed badly and left stale runtime links behind:
+
+```bash
+agentpack skills dev cleanup
+```
+
+If a wrapper-managed process left a false-positive live pid in `.agentpack/dev-session.json`:
+
+```bash
+agentpack skills dev cleanup --force
+```
+
+If you need to remove the active root plus its recorded transitive links in one shot:
+
+```bash
+agentpack skills unlink value-copywriting --recursive
+```
+
+## 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.3"
+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
+