@alavida/agentpack 0.1.1 → 0.1.3

package/skills/identifying-skill-opportunities/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: identifying-skill-opportunities
+description: Use when deciding what raw knowledge should become a packaged skill, a reusable capability boundary, a requires edge, or a plugin-local wrapper in an agentpack skillgraph.
+type: core
+library: agentpack
+library_version: "0.1.2"
+sources:
+  - "alavida-ai/agentpack:docs/architecture.mdx"
+  - "alavida-ai/agentpack:docs/overview.mdx"
+  - "alavida-ai/agentpack:skills/agentpack-cli/SKILL.md"
+---
+
+# Agentpack - Identifying Skill Opportunities
+
+## Setup
+
+```md
+Source knowledge:
+- domains/design/knowledge/brand-guidelines.md
+- domains/frontend/knowledge/component-heuristics.md
+
+Reusable skills:
+- domains/design/skills/brand-guidelines
+- domains/frontend/skills/frontend-skill
+
+Composed task skill:
+- domains/design/skills/agonda-brand-frontend
+  requires:
+    - @scope/brand-guidelines
+    - @scope/frontend-skill
+```
+
+## Core Patterns
+
+### Split by reusable capability
+
+If a knowledge area should be reused compositionally in work, give it its own packaged skill.
+
+### Compose task-specific skills with `requires`
+
+Use a task skill when the work needs several reusable capabilities together.
+
+### Keep plugin-local skills as delivery wrappers
+
+Use plugin-local skills to expose packaged capabilities inside a runtime shell, not to hide the capability graph.
+
+## Common Mistakes
+
+### HIGH Copying knowledge into one giant skill
+
+Wrong:
+
+```md
+One SKILL.md contains branding, frontend heuristics, research notes, and delivery instructions.
+```
+
+Correct:
+
+```md
+Create packaged skills for reusable capabilities, then compose them with requires.
+```
+
+Flattening multiple capabilities into one skill destroys explicit dependency edges and makes maintenance coarse.
+
+Source: maintainer interview
+
+### CRITICAL Using plugin boundaries as the dependency model
+
+Wrong:
+
+```text
+plugins/website-dev/skills/copywriting/SKILL.md
+plugins/website-dev/skills/research/SKILL.md
+```
+
+Correct:
+
+```text
+domains/brand/skills/copywriting/SKILL.md
+domains/research/skills/interview-research/SKILL.md
+plugins/website-dev/skills/copywriting/SKILL.md # requires packaged skills
+```
+
+Plugins are a delivery surface, not the architectural place to hide reusable capability boundaries.
+
+Source: docs/architecture.mdx
+
+### CRITICAL Omitting provenance sources for knowledge-backed skills
+
+Wrong:
+
+```yaml
+---
+name: value-copywriting
+description: Copy.
+requires: []
+---
+```
+
+Correct:
+
+```yaml
+---
+name: value-copywriting
+description: Copy.
+metadata:
+  sources:
+    - domains/value/knowledge/tone-of-voice.md
+requires: []
+---
+```
+
+Without `metadata.sources`, the skillgraph cannot explain stale state against source truth.
+
+Source: docs/architecture.mdx
+
+## References
+
+- [Capability boundaries](references/capability-boundaries.md)

package/skills/identifying-skill-opportunities/references/capability-boundaries.md

@@ -0,0 +1,6 @@
+# Capability Boundaries
+
+- Split when the knowledge should be reused as an independent capability in real work
+- Compose task-specific skills with `requires` instead of flattening them
+- Keep plugins for delivery concerns such as hooks, MCP tools, and grouped shipment of several skills
+

package/skills/maintaining-skillgraph-freshness/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: maintaining-skillgraph-freshness
+description: Use when validating authored skills, checking stale state, and keeping build-state and catalog metadata aligned with changing knowledge in an agentpack skillgraph.
+type: lifecycle
+library: agentpack
+library_version: "0.1.2"
+sources:
+  - "alavida-ai/agentpack:docs/commands.mdx"
+  - "alavida-ai/agentpack:docs/current-state.mdx"
+  - "alavida-ai/agentpack:README.md"
+---
+
+# Agentpack - Maintaining Skillgraph Freshness
+
+## Setup
+
+```bash
+cd knowledge-base
+agentpack skills validate domains/value/skills/copywriting
+agentpack skills stale
+git add .agentpack/build-state.json .agentpack/catalog.json
+```
+
+## Core Patterns
+
+### Use stale before and after source changes
+
+```bash
+agentpack skills stale
+edit domains/value/knowledge/tone-of-voice.md
+agentpack skills stale
+```
+
+### Revalidate to refresh the baseline
+
+```bash
+agentpack skills validate domains/value/skills/copywriting
+```
+
+### Commit authored metadata
+
+```bash
+git add .agentpack/build-state.json .agentpack/catalog.json
+git commit -m "chore: refresh skill metadata"
+```
+
+## Common Mistakes
+
+### CRITICAL Treating stale detection as automatic without validate
+
+Wrong:
+
+```bash
+edit domains/value/knowledge/tone-of-voice.md
+agentpack skills stale
+```
+
+Correct:
+
+```bash
+edit domains/value/knowledge/tone-of-voice.md
+agentpack skills stale
+agentpack skills validate domains/value/skills/copywriting
+```
+
+The stale baseline only updates on successful validation.
+
+Source: docs/commands.mdx
+
+### HIGH Not committing build-state and catalog in authoring repos
+
+Wrong:
+
+```bash
+git add domains/value/skills/copywriting
+git commit -m "feat: update copywriting"
+```
+
+Correct:
+
+```bash
+git add domains/value/skills/copywriting .agentpack/build-state.json .agentpack/catalog.json
+git commit -m "feat: update copywriting"
+```
+
+Uncommitted authored metadata breaks stale visibility across clones, CI, and teammates.
+
+Source: README.md
+
+### MEDIUM Using install-state as authored provenance
+
+Wrong:
+
+```text
+.agentpack/install.json is treated as the authored source of truth
+```
+
+Correct:
+
+```text
+.agentpack/build-state.json and .agentpack/catalog.json are the authored metadata files
+```
+
+Install-state describes runtime materialization, not authored source freshness.
+
+Source: docs/current-state.mdx
+
+## References
+
+- [Authored metadata](references/authored-metadata.md)

package/skills/repairing-broken-skill-or-plugin-state/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: repairing-broken-skill-or-plugin-state
+description: Use when auditing or repairing stale skills, unresolved requires, missing runtime dependencies, affected dependents, or malformed plugin definition files in agentpack.
+type: lifecycle
+library: agentpack
+library_version: "0.1.2"
+sources:
+  - "alavida-ai/agentpack:docs/current-state.mdx"
+  - "alavida-ai/agentpack:docs/commands.mdx"
+  - "alavida-ai/agentpack:src/domain/plugins/load-plugin-definition.js"
+requires:
+  - maintaining-skillgraph-freshness
+  - developing-and-testing-skills
+---
+
+# Agentpack - Repairing Broken Skill Or Plugin State
+
+## Setup
+
+```bash
+agentpack skills status
+agentpack skills missing
+agentpack skills dependencies @alavida-ai/value-copywriting
+agentpack plugin inspect plugins/website-dev
+```
+
+## Core Patterns
+
+### Start with visibility commands
+
+```bash
+agentpack skills status
+agentpack skills missing
+agentpack skills env
+```
+
+### Inspect plugin definition failures before build
+
+```bash
+agentpack plugin inspect plugins/website-dev
+agentpack plugin validate plugins/website-dev
+```
+
+### Trace stale or affected dependents explicitly
+
+```bash
+agentpack skills stale
+agentpack skills dependencies @alavida-ai/value-copywriting
+```
+
+## Common Mistakes
+
+### HIGH Debugging plugin bundle failures without inspect
+
+Wrong:
+
+```bash
+agentpack plugin build plugins/website-dev
+```
+
+Correct:
+
+```bash
+agentpack plugin inspect plugins/website-dev
+agentpack plugin validate plugins/website-dev
+```
+
+`plugin inspect` and `plugin validate` now surface actionable diagnostics for missing plugin files and metadata.
+
+Source: docs/commands.mdx
+
+### HIGH Treating affected dependents as healthy because they still resolve
+
+Wrong:
+
+```bash
+agentpack skills env
+```
+
+Correct:
+
+```bash
+agentpack skills stale
+agentpack skills dependencies @alavida-ai/value-copywriting
+```
+
+A dependent can still resolve while being affected by an upstream stale dependency.
+
+Source: docs/current-state.mdx
+
+### MEDIUM Repairing runtime state by hand-editing local materializations
+
+Wrong:
+
+```bash
+rm -rf .claude/skills/value-copywriting
+```
+
+Correct:
+
+```bash
+agentpack skills unlink value-copywriting
+agentpack skills install @alavida-ai/value-copywriting
+```
+
+Runtime state should be repaired through agentpack lifecycle commands, not direct edits under `.claude/skills` or `.agents/skills`.
+
+Source: docs/architecture.mdx
+
+## References
+
+- [Diagnostic flows](references/diagnostic-flows.md)

package/skills/repairing-broken-skill-or-plugin-state/references/diagnostic-flows.md

@@ -0,0 +1,6 @@
+# Diagnostic Flows
+
+- Stale authored skill: `skills stale` -> `skills dependencies <package>` -> `skills validate <path>`
+- Missing runtime dependency: `skills missing` -> `skills install <package>` -> `skills env`
+- Malformed plugin shell: `plugin inspect <dir>` -> follow `path` and `nextSteps` -> `plugin validate <dir>`
+

package/skills/shipping-production-plugins-and-packages/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: shipping-production-plugins-and-packages
+description: Use when turning maintained skills into deployable bundled plugins or publishable standalone packages with explicit dependency closure, hooks, MCP tools, and production checks 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:README.md"
+requires:
+  - identifying-skill-opportunities
+  - authoring-skillgraphs-from-knowledge
+  - repairing-broken-skill-or-plugin-state
+---
+
+# Agentpack - Shipping Production Plugins And Packages
+
+## Setup
+
+```bash
+agentpack plugin inspect plugins/website-dev
+agentpack plugin validate plugins/website-dev
+agentpack plugin build plugins/website-dev
+```
+
+## Core Patterns
+
+### Ship a standalone package for one reusable capability
+
+```bash
+agentpack skills validate domains/value/skills/copywriting
+```
+
+Use this when the capability stands on its own and does not need to ship bundled with hooks, MCP tools, or other skills.
+
+### Bundle a production plugin when shipping several skills together
+
+```bash
+agentpack plugin inspect plugins/website-dev
+agentpack plugin validate plugins/website-dev
+agentpack plugin build plugins/website-dev
+```
+
+### Use plugin dev during iteration on the delivery shell
+
+```bash
+agentpack plugin dev plugins/website-dev
+```
+
+## Common Mistakes
+
+### CRITICAL Declaring plugin-local skill requires without matching devDependencies
+
+Wrong:
+
+```yaml
+requires:
+  - @alavida-ai/value-copywriting
+```
+
+```json
+{
+  "devDependencies": {}
+}
+```
+
+Correct:
+
+```json
+{
+  "devDependencies": {
+    "@alavida-ai/value-copywriting": "^1.0.0"
+  }
+}
+```
+
+Plugin bundle closure depends on direct required skill packages being present in `package.json.devDependencies`.
+
+Source: docs/commands.mdx
+
+### HIGH Forgetting the plugin manifest and expecting validate to infer it
+
+Wrong:
+
+```text
+plugins/website-dev/package.json
+# no .claude-plugin/plugin.json
+```
+
+Correct:
+
+```text
+plugins/website-dev/package.json
+plugins/website-dev/.claude-plugin/plugin.json
+```
+
+Plugin commands require an explicit runtime manifest and now return structured diagnostics when it is missing.
+
+Source: docs/commands.mdx
+
+### HIGH Assuming a packaged skill and a bundled plugin are the same release unit
+
+Wrong:
+
+```text
+Publish one packaged skill and assume hooks, MCP tools, and related skills ship with it automatically
+```
+
+Correct:
+
+```text
+Use a standalone package for one reusable capability
+Use a bundled plugin when several skills, hooks, or MCP tools must ship together
+```
+
+Packaged skills are reusable units; plugins are deployable runtime shells.
+
+Source: README.md
+
+## References
+
+- [Plugin delivery](references/plugin-delivery.md)

package/skills/shipping-production-plugins-and-packages/references/plugin-delivery.md

@@ -0,0 +1,6 @@
+# Plugin Delivery
+
+- Favor standalone packages for one reusable capability
+- Favor bundled plugins when several skills need to ship together
+- Use bundled plugins when delivery also needs hooks or MCP tools
+- Run `plugin inspect` and `plugin validate` before `plugin build`

package/src/application/plugins/build-plugin.js

@@ -0,0 +1,5 @@
+import { buildPlugin } from '../../lib/plugins.js';
+
+export function buildPluginUseCase(target, options) {
+  return buildPlugin(target, options);
+}

package/src/application/plugins/inspect-plugin-bundle.js

@@ -0,0 +1,5 @@
+import { inspectPluginBundle } from '../../lib/plugins.js';
+
+export function inspectPluginBundleUseCase(target, options) {
+  return inspectPluginBundle(target, options);
+}

package/src/application/plugins/validate-plugin-bundle.js

@@ -0,0 +1,5 @@
+import { validatePluginBundle } from '../../lib/plugins.js';
+
+export function validatePluginBundleUseCase(target, options) {
+  return validatePluginBundle(target, options);
+}

package/src/application/skills/build-skill-workbench-model.js

@@ -0,0 +1,194 @@
+function explainNodeStatus(status) {
+  if (status === 'affected') return 'Affected by upstream authored state changes';
+  if (status === 'changed') return 'Changed since recorded build-state';
+  if (status === 'stale') return 'Stale against recorded build-state';
+  return 'No current lifecycle issue detected';
+}
+
+export function buildSkillWorkbenchModel({
+  repoRoot,
+  selectedSkill,
+  dependencyRecords = [],
+  sourceStatuses = new Map(),
+  selectedStatus = 'unknown',
+}) {
+  const selectedNode = {
+    id: selectedSkill.packageName,
+    type: 'skill',
+    repoRoot,
+    packageName: selectedSkill.packageName,
+    name: selectedSkill.name,
+    skillFile: selectedSkill.skillFile,
+    status: selectedStatus,
+    explanation: selectedStatus === 'stale'
+      ? `Stale because one or more recorded sources changed: ${selectedSkill.sources.join(', ')}`
+      : 'Current against recorded build-state',
+  };
+
+  const sourceNodes = selectedSkill.sources.map((source) => ({
+    id: `source:${source}`,
+    type: 'source',
+    path: source,
+    status: sourceStatuses.get(source) || 'unknown',
+    explanation: explainNodeStatus(sourceStatuses.get(source) || 'unknown'),
+  }));
+
+  const dependencyNodes = dependencyRecords.map((dependency) => ({
+    id: dependency.packageName,
+    type: 'dependency',
+    packageName: dependency.packageName,
+    status: dependency.status || 'unknown',
+    explanation: explainNodeStatus(dependency.status || 'unknown'),
+  }));
+
+  return {
+    selected: selectedNode,
+    nodes: [selectedNode, ...sourceNodes, ...dependencyNodes],
+    edges: [
+      ...sourceNodes.map((node) => ({
+        source: node.id,
+        target: selectedNode.id,
+        kind: 'provenance',
+      })),
+      ...dependencyNodes.map((node) => ({
+        source: selectedNode.id,
+        target: node.id,
+        kind: 'requires',
+      })),
+    ],
+  };
+}
+
+export function buildTransitiveSkillWorkbenchModel({
+  repoRoot,
+  targetPackageName,
+  skillGraph,
+  statusMap,
+  changedSources = new Set(),
+  resolveSkillSources,
+  resolveSkillRequires,
+}) {
+  const targetGraphNode = skillGraph.get(targetPackageName);
+  if (!targetGraphNode) return null;
+
+  const depthMap = new Map();
+  const parentMap = new Map();
+  const bfsOrder = [];
+  const queue = [{ name: targetPackageName, depth: 0, parent: null }];
+
+  while (queue.length > 0) {
+    const { name, depth, parent } = queue.shift();
+    if (depthMap.has(name)) continue;
+
+    depthMap.set(name, depth);
+    if (parent !== null) parentMap.set(name, parent);
+    bfsOrder.push(name);
+
+    const graphNode = skillGraph.get(name);
+
+    // Use graph dependencies if available, fall back to declared requires
+    const deps = graphNode
+      ? graphNode.dependencies
+      : [];
+
+    // Also include declared requires that aren't in graph dependencies
+    const declared = resolveSkillRequires ? resolveSkillRequires(name) : [];
+    const allDeps = [...new Set([...deps, ...declared])];
+
+    for (const dep of allDeps) {
+      if (!depthMap.has(dep)) {
+        queue.push({ name: dep, depth: depth + 1, parent: name });
+      }
+    }
+  }
+
+  const nodes = [];
+  const edges = [];
+  const sourceTracker = new Map();
+
+  for (const packageName of bfsOrder) {
+    const graphNode = skillGraph.get(packageName);
+    if (!graphNode) {
+      nodes.push({
+        id: packageName,
+        type: 'dependency',
+        packageName,
+        name: packageName.split('/').pop(),
+        description: null,
+        version: null,
+        status: 'unknown',
+        explanation: 'Package not found in skill graph',
+        depth: depthMap.get(packageName),
+      });
+      continue;
+    }
+
+    const isTarget = packageName === targetPackageName;
+    const status = statusMap?.get(packageName) || 'unknown';
+
+    nodes.push({
+      id: packageName,
+      type: isTarget ? 'skill' : 'dependency',
+      packageName,
+      name: graphNode.name,
+      description: graphNode.description || null,
+      version: graphNode.packageVersion || null,
+      status,
+      explanation: explainNodeStatus(status),
+      depth: depthMap.get(packageName),
+    });
+
+    const sources = resolveSkillSources(packageName);
+    for (const sourcePath of sources) {
+      const sourceId = `source:${sourcePath}`;
+      if (!sourceTracker.has(sourceId)) {
+        sourceTracker.set(sourceId, { path: sourcePath, usedBy: [] });
+      }
+      sourceTracker.get(sourceId).usedBy.push(packageName);
+    }
+
+    const deps = graphNode ? graphNode.dependencies : [];
+    const declared = resolveSkillRequires ? resolveSkillRequires(packageName) : [];
+    const allDeps = [...new Set([...deps, ...declared])];
+
+    for (const dep of allDeps) {
+      if (depthMap.has(dep)) {
+        edges.push({
+          source: packageName,
+          target: dep,
+          kind: 'requires',
+        });
+      }
+    }
+  }
+
+  const sourceNodes = [];
+  for (const [sourceId, sourceData] of sourceTracker) {
+    const isChanged = changedSources.has(sourceData.path);
+    sourceNodes.push({
+      id: sourceId,
+      type: 'source',
+      path: sourceData.path,
+      status: isChanged ? 'changed' : 'current',
+      explanation: isChanged ? 'Changed since recorded build-state' : 'No current lifecycle issue detected',
+      depth: 0,
+      usedBy: sourceData.usedBy,
+    });
+
+    for (const skillPackageName of sourceData.usedBy) {
+      edges.push({
+        source: sourceId,
+        target: skillPackageName,
+        kind: 'provenance',
+      });
+    }
+  }
+
+  const selectedNode = nodes.find((n) => n.id === targetPackageName);
+
+  return {
+    selected: selectedNode,
+    nodes: [...sourceNodes, ...nodes],
+    edges,
+  };
+}

package/src/application/skills/inspect-skill.js

@@ -0,0 +1,5 @@
+import { inspectSkill } from '../../lib/skills.js';
+
+export function inspectSkillUseCase(target, options) {
+  return inspectSkill(target, options);
+}