@alavida/agentpack 0.1.4 → 0.1.6

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@alavida/agentpack",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Package-backed skills lifecycle CLI for agent skills and plugins",
   "type": "module",
+  "workspaces": [
+    "packages/*"
+  ],
   "bin": {
     "agentpack": "bin/agentpack.js",
     "intent": "bin/intent.js"

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.3
+library_version: 0.1.4
 sources:
   - README.md
   - docs/introduction.mdx
@@ -20,7 +20,8 @@ Use this skill when the user is working with `@alavida/agentpack` and needs the
 
 Agentpack is a lifecycle toolchain for agent artifacts:
 
-- a packaged skill is a reusable capability artifact
+- a package is the distribution unit
+- an exported skill is the runtime module unit
 - a plugin package is a deployable runtime shell
 - source docs are the truth
 - `SKILL.md` is the compiled agent-facing artifact
@@ -49,19 +50,20 @@ If a skill points at `domains/.../knowledge/*.md`, run `skills validate`, `skill
 
 ### 1. Authored packaged skill
 
-Use when the user is creating or editing one reusable skill package.
+Use when the user is creating or editing one packaged skill module or a package that exports several skill modules.
 
 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
+- `agentpack skills inspect <target>`
+- `agentpack skills validate <target>`
+- `agentpack skills dev <target>` if local runtime testing is needed
+- `agentpack skills dev --no-dashboard <target>` 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
+- `package.json.agentpack.skills` declares exported skill modules
+- `SKILL.md.requires` is the source of truth for skill-to-skill edges
+- `package.json.dependencies` is the managed cross-package 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
@@ -77,7 +79,7 @@ Persistence rule:
 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` starts a localhost workbench by default for one selected exported skill, with provenance edges, internal module edges, cross-package dependency edges, 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
@@ -92,7 +94,7 @@ Use when the skill is already published and the user wants it available in anoth
 
 Default flow:
 
-- `agentpack skills install <package-name>`
+- `agentpack skills install <package-name-or-local-package-path>`
 - `agentpack skills env`
 
 Do not prescribe `skills dev` here unless the user is authoring locally.
@@ -124,8 +126,8 @@ Use when the source docs changed and the user needs to know whether the packaged
 Default flow:
 
 - `agentpack skills stale`
-- `agentpack skills stale <skill>`
-- `agentpack skills validate <skill>`
+- `agentpack skills stale <target>`
+- `agentpack skills validate <target>`
 
 Key idea:
 
@@ -138,7 +140,8 @@ 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
+- `package.json` is the package manifest and export table
+- canonical skill ids look like `@scope/package:skill-name`
 - install and materialization are the runtime-resolution step
 - staleness means the source changed after the last known compiled state
 

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

@@ -7,10 +7,11 @@ Use this reference when the user needs the methodology behind packaged skills, n
 A packaged skill is a reusable capability artifact.
 
 - source docs or knowledge files are the truth
-- `SKILL.md` is the authored agent artifact
+- `SKILL.md` is the authored agent artifact for one exported skill module
 - `package.json` is the package and distribution artifact
-- `requires` expresses direct skill dependencies
-- `package.json.dependencies` is the compiled mirror of `requires`
+- `package.json.agentpack.skills` declares exported skill modules
+- `requires` expresses direct skill dependencies using canonical ids like `@scope/package:skill-name`
+- `package.json.dependencies` is the managed cross-package mirror of `requires`
 
 This is closer to a compiler pipeline than a prompt file:
 
@@ -22,27 +23,28 @@ This is closer to a compiler pipeline than a prompt file:
 
 ## Single Source Of Truth
 
-`SKILL.md.requires` is the dependency truth.
+`SKILL.md.requires` is the dependency truth for skill-to-skill edges.
 
-Do not tell the user to hand-maintain `package.json.dependencies` as the primary dependency source. Agentpack treats those dependencies as a compiled mirror.
+Do not tell the user to hand-maintain `package.json.dependencies` as the primary dependency source. Agentpack treats those dependencies as a compiled package-level mirror for cross-package references.
 
 Practical consequence:
 
 - if `requires` changes, run `skills validate` or `skills dev`
-- those commands sync the package dependencies automatically
+- those commands sync cross-package package dependencies automatically
+- same-package module references do not create package dependency entries
 
 ## 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
+1. `agentpack skills inspect <target>`
+2. `agentpack skills validate <target>`
+3. `agentpack skills dev <target>` if the user wants agent runtime discovery during iteration
 
 What each step means:
 
 - `inspect` explains what the skill currently is
-- `validate` checks package readiness, source existence, and records the validated source snapshot in `.agentpack/build-state.json`
+- `validate` checks package readiness, exported skill declarations, source existence, canonical dependency resolution, 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:
@@ -76,7 +78,7 @@ Authoring stage:
 
 Consumption stage:
 
-- package name
+- package name or local package path
 - installed from registry or tarball
 - `skills install`
 - `skills env`

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

@@ -3,7 +3,7 @@ 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"
+library_version: "0.1.4"
 sources:
   - "alavida-ai/agentpack:docs/commands.mdx"
   - "alavida-ai/agentpack:docs/architecture.mdx"
@@ -22,14 +22,22 @@ metadata:
   sources:
     - domains/value/knowledge/selling-points.md
 requires:
-  - @alavida-ai/methodology-gary-provost
+  - "@alavida/methodology:gary-provost"
 ---
 ```
 
 ```json
 {
-  "name": "@alavida-ai/value-copywriting",
+  "name": "@alavida/value-copywriting",
   "version": "1.0.0",
+  "files": ["skills"],
+  "agentpack": {
+    "skills": {
+      "value-copywriting": {
+        "path": "skills/value-copywriting/SKILL.md"
+      }
+    }
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/alavida-ai/knowledge-base.git"
@@ -37,9 +45,8 @@ requires:
   "publishConfig": {
     "registry": "https://npm.pkg.github.com"
   },
-  "files": ["SKILL.md"],
   "dependencies": {
-    "@alavida-ai/methodology-gary-provost": "^1.0.0"
+    "@alavida/methodology": "^1.0.0"
   }
 }
 ```
@@ -50,20 +57,20 @@ requires:
 
 ```yaml
 requires:
-  - @alavida-ai/methodology-gary-provost
+  - "@alavida/methodology:gary-provost"
 ```
 
 ### Validate to sync and record provenance
 
 ```bash
-agentpack skills validate domains/value/skills/copywriting
+agentpack skills validate domains/value/skills/value-copywriting
 ```
 
 ### Inspect by path or package name
 
 ```bash
-agentpack skills inspect domains/value/skills/copywriting
-agentpack skills inspect @alavida-ai/value-copywriting
+agentpack skills inspect domains/value/skills/value-copywriting
+agentpack skills inspect @alavida/value-copywriting:value-copywriting
 ```
 
 ## Common Mistakes
@@ -75,7 +82,7 @@ Wrong:
 ```json
 {
   "dependencies": {
-    "@alavida-ai/methodology-gary-provost": "^1.0.0"
+    "@alavida/methodology": "^1.0.0"
   }
 }
 ```
@@ -84,10 +91,10 @@ Correct:
 
 ```yaml
 requires:
-  - @alavida-ai/methodology-gary-provost
+  - "@alavida/methodology:gary-provost"
 ```
 
-`requires` is the authored dependency truth; `package.json.dependencies` is the compiled mirror.
+`requires` is the authored dependency truth; `package.json.dependencies` is the managed cross-package mirror.
 
 Source: skills/agentpack-cli/SKILL.md
 
@@ -105,11 +112,18 @@ Correct:
 
 ```json
 {
-  "files": ["SKILL.md"]
+  "files": ["skills"],
+  "agentpack": {
+    "skills": {
+      "value-copywriting": {
+        "path": "skills/value-copywriting/SKILL.md"
+      }
+    }
+  }
 }
 ```
 
-A package that excludes `SKILL.md` is structurally invalid even if the authored source exists locally.
+A package that excludes its exported skill files is structurally invalid even if the authored source exists locally.
 
 Source: docs/commands.mdx
 
@@ -119,7 +133,7 @@ Wrong:
 
 ```json
 {
-  "name": "@alavida-ai/value-copywriting"
+  "name": "@alavida/value-copywriting"
 }
 ```
 
@@ -127,8 +141,15 @@ Correct:
 
 ```json
 {
-  "name": "@alavida-ai/value-copywriting",
+  "name": "@alavida/value-copywriting",
   "version": "1.0.0",
+  "agentpack": {
+    "skills": {
+      "value-copywriting": {
+        "path": "skills/value-copywriting/SKILL.md"
+      }
+    }
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/alavida-ai/knowledge-base.git"

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

@@ -1,6 +1,7 @@
 # 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.json.agentpack.skills` owns the exported skill map and each exported skill path
+- `package.json` owns package-level distribution metadata such as package name, version, publish config, and repository
+- `requires` uses canonical ids like `@scope/package:skill-name`
+- `skills validate` syncs managed cross-package dependencies from `requires` and refreshes `.agentpack/build-state.json`

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

@@ -3,7 +3,7 @@ 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"
+library_version: "0.1.4"
 sources:
   - "alavida-ai/agentpack:docs/introduction.mdx"
   - "alavida-ai/agentpack:docs/commands.mdx"
@@ -46,7 +46,7 @@ agentpack skills dev domains/value/skills/copywriting
 
 ```bash
 cd consumer-repo
-agentpack skills install @alavida-ai/value-copywriting
+agentpack skills install @alavida/value-copywriting
 agentpack skills env
 ```
 
@@ -77,7 +77,7 @@ Source: docs/introduction.mdx
 Wrong:
 
 ```bash
-agentpack skills install @alavida-ai/value-copywriting
+agentpack skills install @alavida/value-copywriting
 ```
 
 Correct:

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

@@ -1,9 +1,9 @@
 ---
 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.
+description: Use when turning maintained skills into deployable bundled plugins or publishable skill packages with explicit dependency closure, hooks, MCP tools, and production checks in agentpack.
 type: core
 library: agentpack
-library_version: "0.1.3"
+library_version: "0.1.4"
 sources:
   - "alavida-ai/agentpack:docs/commands.mdx"
   - "alavida-ai/agentpack:docs/architecture.mdx"
@@ -26,13 +26,21 @@ agentpack plugin build plugins/website-dev
 
 ## Core Patterns
 
-### Ship a standalone package for one reusable capability
+### Ship one package for one reusable skill module
 
 ```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.
+Use this when one package should export one reusable skill module and does not need to ship bundled with hooks, MCP tools, or other runtime pieces.
+
+### Ship one package that exports several related skill modules
+
+```bash
+agentpack skills validate domains/value/skills/pm-foundations
+```
+
+Use this when several skills belong together as one package but still need to remain separate runtime modules through `package.json.agentpack.skills`.
 
 ### Bundle a production plugin when shipping several skills together
 
@@ -56,7 +64,7 @@ Wrong:
 
 ```yaml
 requires:
-  - @alavida-ai/value-copywriting
+  - "@alavida/value-copywriting:value-copywriting"
 ```
 
 ```json
@@ -70,7 +78,7 @@ Correct:
 ```json
 {
   "devDependencies": {
-    "@alavida-ai/value-copywriting": "^1.0.0"
+    "@alavida/value-copywriting": "^1.0.0"
   }
 }
 ```
@@ -110,11 +118,11 @@ Publish one packaged skill and assume hooks, MCP tools, and related skills ship
 Correct:
 
 ```text
-Use a standalone package for one reusable capability
+Use a skill package for one or many reusable skill modules
 Use a bundled plugin when several skills, hooks, or MCP tools must ship together
 ```
 
-Packaged skills are reusable units; plugins are deployable runtime shells.
+Skill packages are reusable distribution units; exported skills are runtime modules; plugins are deployable runtime shells.
 
 Source: README.md
 

package/src/application/auth/get-auth-status.js

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readUserConfig } from '../../infrastructure/fs/user-config-repository.js';
+import { readUserCredentials } from '../../infrastructure/fs/user-credentials-repository.js';
+import { getUserNpmrcPath, parseNpmrc, readUserNpmrc } from '../../infrastructure/fs/user-npmrc-repository.js';
+import { resolveRegistryConfig } from '../../domain/auth/registry-resolution.js';
+import { verifyAuth } from './verify-auth.js';
+
+function findRepoNpmrc(cwd) {
+  let current = cwd;
+
+  while (true) {
+    const npmrcPath = join(current, '.npmrc');
+    if (existsSync(npmrcPath)) {
+      return {
+        path: npmrcPath,
+        config: parseNpmrc(readFileSync(npmrcPath, 'utf-8')),
+      };
+    }
+
+    const gitPath = join(current, '.git');
+    if (existsSync(gitPath)) break;
+
+    const parent = join(current, '..');
+    if (parent === current) break;
+    current = parent;
+  }
+
+  return {
+    path: null,
+    config: {},
+  };
+}
+
+export async function getAuthStatus({
+  cwd = process.cwd(),
+  env = process.env,
+  verify = false,
+} = {}) {
+  const config = readUserConfig({ env });
+  const credentials = readUserCredentials({ env });
+  const userNpmrc = readUserNpmrc({ env });
+  const repoNpmrc = findRepoNpmrc(cwd);
+
+  const resolved = resolveRegistryConfig({
+    scope: config.scope,
+    defaults: {
+      registry: config.registry,
+      verificationPackage: config.verificationPackage,
+    },
+    userNpmrc,
+    repoNpmrc: repoNpmrc.config,
+  });
+
+  const userNpmrcPath = getUserNpmrcPath({ env });
+  const requiredRegistryKey = `${config.scope}:registry`;
+  const requiredTokenKey = resolved.registry
+    ? `//${new URL(resolved.registry).host}/:_authToken`
+    : null;
+
+  const npmWired = Boolean(
+    userNpmrc[requiredRegistryKey]
+      && requiredTokenKey
+      && userNpmrc[requiredTokenKey]
+  );
+
+  const result = {
+    provider: config.provider,
+    configured: Boolean(credentials?.token && npmWired),
+    scope: config.scope,
+    registry: resolved.registry,
+    storage: {
+      mode: credentials?.token ? 'file' : 'missing',
+    },
+    npmConfig: {
+      path: userNpmrcPath,
+      wired: npmWired,
+      source: resolved.source,
+      repoOverridePath: repoNpmrc.path,
+    },
+    verification: {
+      status: 'not_checked',
+    },
+  };
+
+  if (!verify) {
+    return result;
+  }
+
+  result.verification = await verifyAuth({
+    registry: resolved.registry,
+    authToken: credentials?.token || null,
+    verificationPackage: resolved.verificationPackage,
+  });
+
+  return result;
+}

package/src/application/auth/login.js

@@ -0,0 +1,110 @@
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { readUserConfig, writeUserConfig } from '../../infrastructure/fs/user-config-repository.js';
+import { writeUserCredentials } from '../../infrastructure/fs/user-credentials-repository.js';
+import { writeManagedNpmrcEntries } from '../../infrastructure/fs/user-npmrc-repository.js';
+import { openBrowser } from '../../infrastructure/runtime/open-browser.js';
+import { verifyAuth } from './verify-auth.js';
+import { AgentpackError, EXIT_CODES } from '../../utils/errors.js';
+
+const GITHUB_TOKEN_URL = 'https://github.com/settings/tokens';
+
+function buildVerificationFailure(verification) {
+  if (verification.status === 'invalid') {
+    return new AgentpackError('The GitHub personal access token was rejected by GitHub Packages', {
+      code: 'auth_verification_failed',
+      exitCode: EXIT_CODES.GENERAL,
+    });
+  }
+
+  if (verification.status === 'insufficient_permissions') {
+    return new AgentpackError('The GitHub personal access token does not have package read access', {
+      code: 'auth_verification_failed',
+      exitCode: EXIT_CODES.GENERAL,
+    });
+  }
+
+  if (verification.status === 'unreachable') {
+    return new AgentpackError('GitHub Packages could not be reached during verification', {
+      code: 'auth_verification_failed',
+      exitCode: EXIT_CODES.GENERAL,
+    });
+  }
+
+  if (verification.status === 'not_configured') {
+    return new AgentpackError('Authentication verification is not configured for this machine', {
+      code: 'auth_verification_not_configured',
+      exitCode: EXIT_CODES.GENERAL,
+    });
+  }
+
+  return new AgentpackError('The saved credential was rejected by the configured registry', {
+    code: 'auth_verification_failed',
+    exitCode: EXIT_CODES.GENERAL,
+  });
+}
+
+export async function login({
+  env = process.env,
+  scope = null,
+  registry = null,
+  verificationPackage = null,
+} = {}) {
+  const current = readUserConfig({ env });
+  const nextConfig = {
+    ...current,
+    scope: scope || current.scope,
+    registry: registry || current.registry,
+    verificationPackage: verificationPackage || current.verificationPackage,
+  };
+
+  openBrowser(GITHUB_TOKEN_URL);
+  output.write(`Configuring GitHub Packages auth for ${nextConfig.scope}`);
+  output.write('Use a GitHub personal access token with package read access.');
+
+  const rl = readline.createInterface({ input, output });
+  try {
+    const token = (await rl.question('Token: ')).trim();
+    if (!token) {
+      throw new AgentpackError('A GitHub credential is required to continue', {
+        code: 'auth_token_missing',
+        exitCode: EXIT_CODES.GENERAL,
+      });
+    }
+
+    const verification = await verifyAuth({
+      registry: nextConfig.registry,
+      authToken: token,
+      verificationPackage: nextConfig.verificationPackage,
+    });
+
+    if (verification.status !== 'valid') {
+      throw buildVerificationFailure(verification);
+    }
+
+    const managedEntries = {
+      [`${nextConfig.scope}:registry`]: nextConfig.registry,
+      [`//${new URL(nextConfig.registry).host}/:_authToken`]: token,
+    };
+
+    writeManagedNpmrcEntries({ entries: managedEntries, env });
+    writeUserCredentials({ token }, { env });
+    writeUserConfig({
+      ...nextConfig,
+      managedNpmKeys: Object.keys(managedEntries),
+    }, { env });
+
+    return {
+      configured: true,
+      provider: nextConfig.provider,
+      scope: nextConfig.scope,
+      registry: nextConfig.registry,
+      verificationPackage: nextConfig.verificationPackage,
+      storage: {
+        mode: 'file',
+      },
+    };
+  } finally {
+    rl.close();
+  }
+}

package/src/application/auth/logout.js

@@ -0,0 +1,16 @@
+import { deleteUserCredentials } from '../../infrastructure/fs/user-credentials-repository.js';
+import { removeManagedNpmrcEntries } from '../../infrastructure/fs/user-npmrc-repository.js';
+import { readUserConfig } from '../../infrastructure/fs/user-config-repository.js';
+
+export function logout({ env = process.env } = {}) {
+  const config = readUserConfig({ env });
+  const keys = config.managedNpmKeys || [];
+
+  deleteUserCredentials({ env });
+  removeManagedNpmrcEntries({ keys, env });
+
+  return {
+    removedCredentials: true,
+    removedNpmKeys: keys.length,
+  };
+}

package/src/application/auth/verify-auth.js

@@ -0,0 +1,37 @@
+export async function verifyAuth({
+  registry,
+  authToken,
+  verificationPackage,
+} = {}) {
+  if (!registry || !authToken || !verificationPackage) {
+    return { status: 'not_configured' };
+  }
+
+  const url = `${registry.replace(/\/+$/, '')}/${encodeURIComponent(verificationPackage)}`;
+
+  let response;
+  try {
+    response = await fetch(url, {
+      headers: {
+        accept: 'application/json',
+        authorization: `Bearer ${authToken}`,
+      },
+    });
+  } catch {
+    return { status: 'unreachable' };
+  }
+
+  if (response.ok) {
+    return { status: 'valid' };
+  }
+
+  if (response.status === 401) {
+    return { status: 'invalid' };
+  }
+
+  if (response.status === 403) {
+    return { status: 'insufficient_permissions' };
+  }
+
+  return { status: 'unreachable' };
+}

package/src/cli.js

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 import { createRequire } from 'node:module';
 import { formatError, AgentpackError, EXIT_CODES } from './utils/errors.js';
 import { output } from './utils/output.js';
+import { authCommand } from './commands/auth.js';
 import { skillsCommand } from './commands/skills.js';
 import { pluginCommand } from './commands/plugin.js';
 
@@ -21,6 +22,7 @@ export function createProgram() {
     .option('--workbench <path>', 'Override workbench context (name or path)');
 
   program.addCommand(skillsCommand());
+  program.addCommand(authCommand());
   program.addCommand(pluginCommand());
 
   program.addHelpText('after', `