@alavida/agentpack 0.1.1

package/README.md

@@ -0,0 +1,269 @@
+# agentpack
+
+You already know the feeling:
+
+- the skill worked in one repo, but now it is copied into three places
+- a plugin depends on a skill, but nobody knows where that dependency truth lives
+- the source knowledge changed, but the shipped skill never got updated
+- the runtime still has a skill on disk, but nobody can tell whether it is current, stale, local, bundled, or installed transitively
+- the agent "knows" something, but you no longer trust where that knowledge came from
+
+That is the problem `agentpack` is for.
+
+The core failure mode is lifecycle collapse. Most teams flatten four different artifact types into one fuzzy thing called "a skill":
+
+- source knowledge
+- compiled skill artifact
+- runtime plugin
+- installed environment state
+
+Once those boundaries blur, everything gets worse:
+
+- authors do not know what to update
+- consumers do not know what to install
+- plugins become hidden dependency containers
+- agents end up running stale knowledge with no visible trust chain
+
+`agentpack` gives those artifacts their own lifecycle again:
+
+- source docs and knowledge files stay authoritative
+- `SKILL.md` becomes the agent-facing artifact
+- `package.json` becomes the distribution contract
+- npm handles package resolution and versioning
+- `agentpack` handles validation, staleness, local linking, install flow, and plugin bundling
+
+This is for teams who want agent behavior to be packaged, inspectable, and updateable like software instead of copy-pasted prompt debris.
+
+Docs: https://docs.alavida.ai
+
+## Install
+
+```bash
+npm install -g @alavida/agentpack
+```
+
+Or without a global install:
+
+```bash
+npx @alavida/agentpack --help
+```
+
+## Why It Exists
+
+Most agent workflows still look like this:
+
+- write source knowledge in one place
+- hand-copy some of it into a skill
+- hand-copy that skill into a plugin or repo
+- lose track of what depends on what
+- discover drift only when the agent produces the wrong output
+
+`agentpack` gives you a real lifecycle instead:
+
+1. Write and maintain source knowledge where your team already works.
+2. Derive a skill artifact from that knowledge.
+3. Validate it before release.
+4. Link it locally for testing.
+5. Publish it as a package.
+6. Install or bundle it wherever it needs to run.
+
+## What It Does
+
+`agentpack` covers four practical workflows:
+
+1. Author a packaged skill from source docs or knowledge files.
+2. Validate that skill before release.
+3. Link it locally into `.claude/skills/` and `.agents/skills/` for testing.
+4. Bundle packaged skills into self-contained plugin artifacts.
+
+## Quick Start
+
+### Author and test a packaged skill
+
+Run these commands from the repo that owns the source files referenced by `metadata.sources`:
+
+```bash
+agentpack skills inspect domains/operations/skills/agonda-prioritisation
+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.
+
+If your agent session was already running, start a fresh session after linking so the runtime can pick up the newly materialized skill.
+
+### Install a published skill in another repo
+
+```bash
+agentpack skills install @scope/skill-package
+agentpack skills env
+```
+
+### Build a plugin artifact
+
+```bash
+agentpack plugin inspect path/to/plugin
+agentpack plugin validate path/to/plugin
+agentpack plugin build path/to/plugin
+```
+
+For watch mode during development:
+
+```bash
+agentpack plugin dev path/to/plugin
+```
+
+## The Model
+
+The most important distinction in `agentpack` is lifecycle stage.
+
+### Packaged skills
+
+A packaged skill is a reusable capability artifact.
+
+- `metadata.sources` track provenance
+- `requires` define authored skill dependencies
+- `package.json.dependencies` are the compiled mirror of `requires`
+- it is self-contained at runtime, not a pointer back to source files
+
+Typical local flow:
+
+- `skills inspect`
+- `skills validate`
+- `skills dev`
+
+### Consumer installs
+
+Consumer repos do not author the skill. They install the published package and materialize it into agent-visible directories.
+
+Typical consumer flow:
+
+- `skills install`
+- `skills env`
+
+### Plugins
+
+A plugin is a deployable runtime shell, not just another skill package.
+
+Plugin-local skills can declare `requires` on packaged skills. `agentpack` can then build a self-contained plugin artifact that vendors those packaged dependencies.
+
+Typical plugin flow:
+
+- `plugin inspect`
+- `plugin validate`
+- `plugin build`
+- `plugin dev`
+
+## What Agentpack Refuses To Blur
+
+These are deliberate boundaries:
+
+- Knowledge is the source of truth.
+- Skills are derived artifacts.
+- Plugins are runtime shells.
+- Installed state is repo-local runtime state.
+
+If you blur those together, you get the exact problems this tool exists to stop:
+
+- skills that silently depend on files they do not ship
+- plugins that hide reusable capability dependencies
+- repos that cannot explain why a skill is present
+- updates that change behavior without an explicit review step
+
+## Knowledge As A Package
+
+`agentpack` works best when you treat knowledge like software:
+
+- the source files explain the methodology or domain truth
+- the skill is the compiled agent-facing artifact
+- package metadata defines how the capability is distributed
+- validation and stale checks stop the artifact drifting from its sources
+
+That lets you manage agent behavior with the same discipline you already apply to code.
+
+## Source-Backed Skills
+
+For source-backed skills, run authoring commands from the repo that owns the source files.
+
+If a skill points at `domains/.../knowledge/*.md`, run:
+
+- `agentpack skills validate`
+- `agentpack skills dev`
+- `agentpack skills stale`
+
+from that knowledge-base repo root, not from the `agentpack` repo.
+
+## Commands
+
+Implemented today:
+
+- `agentpack skills inspect`
+- `agentpack skills validate`
+- `agentpack skills dev`
+- `agentpack skills unlink`
+- `agentpack skills stale`
+- `agentpack skills install`
+- `agentpack skills env`
+- `agentpack skills uninstall`
+- `agentpack skills outdated`
+- `agentpack skills dependencies`
+- `agentpack skills registry`
+- `agentpack skills status`
+- `agentpack skills missing`
+- `agentpack plugin inspect`
+- `agentpack plugin validate`
+- `agentpack plugin build`
+- `agentpack plugin dev`
+
+## Docs
+
+Hosted docs: https://docs.alavida.ai
+
+Docs source: [`docs/`](./docs)
+
+For local docs preview as a contributor:
+
+```bash
+npm i -g mint
+cd docs
+mint dev
+```
+
+## Development
+
+Run the full test suite:
+
+```bash
+npm test
+```
+
+Validate the shipped agent skill:
+
+```bash
+npm run intent:validate
+```
+
+## Optional Agent Integration
+
+This package also ships an agent-facing skill under:
+
+```text
+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.
+
+## Metadata Policy
+
+In authoring repos:
+
+- commit `.agentpack/build-state.json`
+- commit `.agentpack/catalog.json`
+
+In consumer/runtime repos:
+
+- do not commit `.agentpack/install.json`
+
+## License
+
+MIT

package/bin/agentpack.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from '../src/cli.js';
+
+run(process.argv);

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@alavida/agentpack",
+  "version": "0.1.1",
+  "description": "Package-backed skills lifecycle CLI for agent skills and plugins",
+  "type": "module",
+  "bin": {
+    "agentpack": "bin/agentpack.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "!skills/_artifacts",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "find test -name '*.test.js' -print0 | xargs -0 node --test",
+    "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"
+  },
+  "keywords": [
+    "agentpack",
+    "skills",
+    "cli",
+    "alavida"
+  ],
+  "author": "Alavida AI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alavida-ai/agentpack.git"
+  },
+  "homepage": "https://docs.alavida.ai",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "intent": {
+    "version": 1,
+    "repo": "alavida-ai/agentpack",
+    "docs": "https://github.com/alavida-ai/agentpack/tree/main/docs"
+  },
+  "dependencies": {
+    "commander": "^13.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/intent": "^0.0.14"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/skills/agentpack-cli/SKILL.md

@@ -0,0 +1,136 @@
+---
+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
+sources:
+  - README.md
+  - docs/introduction.mdx
+  - docs/overview.mdx
+  - docs/architecture.mdx
+  - docs/build-lifecycle.mdx
+  - docs/commands.mdx
+  - docs/current-state.mdx
+  - docs/distribution.mdx
+  - docs/end-to-end-test-plan.md
+---
+
+# Agentpack CLI
+
+Use this skill when the user is working with `@alavida/agentpack` and needs the right lifecycle framing, not just a command snippet.
+
+Agentpack is a lifecycle toolchain for agent artifacts:
+
+- a packaged skill is a reusable capability artifact
+- a plugin package is a deployable runtime shell
+- source docs are the truth
+- `SKILL.md` is the compiled agent-facing artifact
+- `package.json` is the distributable package artifact
+
+## Core Methodology
+
+Do not answer with isolated commands until you identify which lifecycle stage the user is in:
+
+- authoring a packaged skill
+- testing a packaged skill locally
+- installing a published skill in a consumer repo
+- wiring a plugin-local skill to packaged dependencies
+- building a self-contained plugin artifact
+- checking staleness after source docs change
+
+If the user is confused, explain the stage boundary first.
+
+## Repo-Root Rule
+
+For source-backed packaged skills, run authoring commands from the repo that owns the files referenced in `metadata.sources`.
+
+If a skill points at `domains/.../knowledge/*.md`, run `skills validate`, `skills dev`, and `skills stale` from that knowledge-base repo root, not from the `agentpack` repo.
+
+## Lifecycle Routing
+
+### 1. Authored packaged skill
+
+Use when the user is creating or editing one reusable skill package.
+
+Default flow:
+
+- `agentpack skills inspect <skill-dir>`
+- `agentpack skills validate <skill-dir>`
+- `agentpack skills dev <skill-dir>` if local runtime testing is needed
+
+Key idea:
+
+- `SKILL.md.requires` is the source of truth
+- `package.json.dependencies` is the compiled mirror
+- `validate` and `dev` sync dependencies automatically
+- `skills dev` materializes the compiled skill artifact for runtime use
+
+Runtime notes:
+
+- after `skills dev` writes to `.claude/skills/` or `.agents/skills/`, start a fresh agent session if the current one was already running
+- 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
+
+Read [skill-lifecycle.md](references/skill-lifecycle.md) when the user needs the full methodology.
+
+### 2. Consumer install
+
+Use when the skill is already published and the user wants it available in another repo.
+
+Default flow:
+
+- `agentpack skills install <package-name>`
+- `agentpack skills env`
+
+Do not prescribe `skills dev` here unless the user is authoring locally.
+
+### 3. Plugin-local dependency and artifact build
+
+Use when a plugin-local skill declares `requires` on packaged skills and the user wants a self-contained plugin artifact.
+
+Default flow:
+
+- `agentpack plugin inspect <plugin-dir>`
+- `agentpack plugin validate <plugin-dir>`
+- `agentpack plugin build <plugin-dir>`
+- `agentpack plugin dev <plugin-dir>` for watch mode
+
+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
+
+Read [plugin-lifecycle.md](references/plugin-lifecycle.md) when the user needs the full artifact flow.
+
+### 4. Stale source-backed skill
+
+Use when the source docs changed and the user needs to know whether the packaged skill must be rebuilt or revalidated.
+
+Default flow:
+
+- `agentpack skills stale`
+- `agentpack skills stale <skill>`
+- `agentpack skills validate <skill>`
+
+## Conceptual Frame
+
+When the user is reasoning about the model itself, explain agentpack this way:
+
+- docs or knowledge files are source files
+- `SKILL.md` is the compiled artifact
+- `package.json` is the distribution manifest
+- install and materialization are the runtime-resolution step
+- staleness means the source changed after the last known compiled state
+
+Read [knowledge-as-package.md](references/knowledge-as-package.md) when the user needs this framing.
+
+## Response Requirements
+
+Be explicit about:
+
+- which repo the command must run from
+- whether the target is a local path or a published package name
+- whether the user is in authoring, consumer-install, or plugin-build mode
+- what the next irreversible step is
+
+Do not collapse authored skill lifecycle and consumer install lifecycle into one answer.

package/skills/agentpack-cli/references/knowledge-as-package.md

@@ -0,0 +1,48 @@
+# Knowledge As Package
+
+Use this reference when the user is reasoning about why `agentpack` exists, or how docs and knowledge files become runtime agent capabilities.
+
+## The Core Idea
+
+Agentpack treats knowledge the way a software toolchain treats source code.
+
+Mapping:
+
+- knowledge docs = source files
+- `SKILL.md` = compiled artifact for agents
+- `package.json` = distribution manifest
+- npm package = versioned published artifact
+- `.claude/skills/` or `.agents/skills/` = runtime resolution surface
+
+This is why a skill is not just a prompt file. It is a package-backed artifact with provenance, dependencies, and lifecycle checks.
+
+## Why Source Tracking Matters
+
+Without source tracking, a skill drifts silently away from the docs or knowledge it was supposed to encode.
+
+With `metadata.sources`:
+
+- the skill points at the files it was derived from
+- validation checks that those files exist
+- stale detection can report when source truth changed
+
+This is the main reason to keep docs as sources and skills as derived artifacts.
+
+## Why Installation Is Separate From Authoring
+
+Published package consumption is not the same as local skill authoring.
+
+Authoring cares about:
+
+- source truth
+- validation
+- dependency sync
+- local discovery via `skills dev`
+
+Consumption cares about:
+
+- versioned package installation
+- transitive dependency resolution
+- runtime materialization into agent-visible directories
+
+Keep those stages separate in explanations.

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

@@ -0,0 +1,58 @@
+# Plugin Lifecycle
+
+Use this reference when the user is working with plugin-local skills, bundled skill dependencies, or plugin artifact testing.
+
+## Two Artifact Types
+
+Keep this boundary clear:
+
+- packaged skills are libraries
+- plugins are deployable runtime shells
+
+A packaged skill can be reused across repos. A plugin artifact is built for execution and can vendor packaged skills into a self-contained output.
+
+## Dependency Truth
+
+For plugins, local plugin skill `requires` are the authored dependency truth.
+
+That means:
+
+- local plugin skills declare which packaged skills they need
+- plugin `package.json.devDependencies` must contain those packaged skills
+- `plugin validate` checks that the declared package dependencies are actually present
+
+Do not move that dependency truth into `plugin.json`.
+
+## Build Flow
+
+Use this flow when the user wants a runnable plugin artifact:
+
+1. `agentpack plugin inspect <plugin-dir>`
+2. `agentpack plugin validate <plugin-dir>`
+3. `agentpack plugin build <plugin-dir>`
+
+Use `agentpack plugin dev <plugin-dir>` when the user wants rebuild-on-change behavior.
+
+## What Build Produces
+
+The plugin source tree is not the final runtime artifact.
+
+`plugin build`:
+
+- syncs local skill dependencies
+- resolves direct and transitive packaged skill closure
+- vendors those packaged skills into the output
+- writes bundled provenance
+- produces a self-contained artifact under `.agentpack/dist/plugins/<plugin-name>/`
+
+That built artifact is what should be tested with `claude --plugin-dir`.
+
+## Consumer Boundary
+
+For plugin consumers, the built plugin artifact should behave the same way whether it came from:
+
+- `plugin dev`
+- `plugin build`
+- or a published plugin package
+
+When the user is testing “what will the consumer get”, push them toward the built artifact, not the plugin source tree.

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

@@ -0,0 +1,78 @@
+# Skill Lifecycle
+
+Use this reference when the user needs the methodology behind packaged skills, not just the command names.
+
+## Model
+
+A packaged skill is a reusable capability artifact.
+
+- source docs or knowledge files are the truth
+- `SKILL.md` is the authored agent artifact
+- `package.json` is the package and distribution artifact
+- `requires` expresses direct skill dependencies
+- `package.json.dependencies` is the compiled mirror of `requires`
+
+This is closer to a compiler pipeline than a prompt file:
+
+- source files change
+- the skill artifact is updated
+- dependency metadata is synced
+- validation checks release readiness
+- stale detection tells you when the source truth moved
+
+## Single Source Of Truth
+
+`SKILL.md.requires` is the dependency truth.
+
+Do not tell the user to hand-maintain `package.json.dependencies` as the primary dependency source. Agentpack treats those dependencies as a compiled mirror.
+
+Practical consequence:
+
+- if `requires` changes, run `skills validate` or `skills dev`
+- those commands sync the package dependencies automatically
+
+## Local Authoring Flow
+
+Use this when the user is creating or changing a packaged skill in the same repo as its source docs.
+
+1. `agentpack skills inspect <skill-dir>`
+2. `agentpack skills validate <skill-dir>`
+3. `agentpack skills dev <skill-dir>` if the user wants agent runtime discovery during iteration
+
+What each step means:
+
+- `inspect` explains what the skill currently is
+- `validate` checks package readiness and source existence
+- `dev` links the skill into `.claude/skills/` and `.agents/skills/` for local testing
+
+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
+- the linked skill is the compiled artifact the runtime should use; do not separately load the source files unless you are editing the skill itself
+- once linked and picked up by the runtime, trigger the skill through the runtime's skill invocation path rather than reading `SKILL.md` manually
+
+## Repo-Root Constraint
+
+Source-backed validation is relative to the current repo root.
+
+If `metadata.sources` points at files in a knowledge-base repo, run authoring commands from that repo root. A `missing_source` error often means the user is in the wrong repo, not that the skill is wrong.
+
+## Publish Boundary
+
+Local authoring and published consumption are different stages.
+
+Authoring stage:
+
+- skill directory path
+- local source docs
+- `skills validate`
+- `skills dev`
+
+Consumption stage:
+
+- package name
+- installed from registry or tarball
+- `skills install`
+- `skills env`
+
+Do not substitute one for the other.