agentpacks

agentpacks

Website: https://github.com/lssm-tech/contractspec/tree/main/packages/tools/agentpacks

Composable AI agent configuration manager that merges packs into target-specific tool configuration, rules, hooks, skills, and AGENTS output.

What It Provides

• Loads, merges, and resolves agent packs into Cursor, Claude Code, Codex, Copilot, Gemini, OpenCode, registry, and AGENTS targets.
• Publishes a CLI plus a broad programmatic API for pack loading, sources, targets, importers, and exporters.
• Compiles canonical filesystem-authored agent applications from agent/{instructions.md,agent.ts,tools,skills,connections,sandbox,channels,subagents,schedules} and evals/ into deterministic AgentSpec/WorkflowSpec configuration.
• Recently expanded around AI-native flows, model guidance, Cursor plugin output, and compatibility hardening.
• Related ContractSpec packages include @lssm-tech/tool.bun, @lssm-tech/tool.typescript.

Installation

npm install agentpacks

or

bun add agentpacks

Usage

npx agentpacks --help
# or
bunx agentpacks --help

Generate and RTK refresh

After a successful non-dry-run agentpacks generate writes files, the CLI runs rtk init and then rtk init --codex to refresh Claude Code and Codex RTK guidance. Dry runs, diff-only runs, no-op generations, and partial generations with target errors skip the RTK refresh. RTK command failures are reported as warnings after generation output is written.

agentpacks generate --diff uses a non-writing filesystem overlay. It reports added, modified, and deleted generated artifacts without changing files or directories, and exits non-zero when drift is present so it can be used as a CI check.

Complete skill bundles

Skills may include nested references/, scripts/, assets/, and agents/openai.yaml beside SKILL.md. Claude, Codex, Cursor, OpenCode, Copilot, Gemini, and Mistral targets preserve these files byte-for-byte, including executable permissions. Gemini writes .gemini/skills/<name>/. Existing skill importers and Cursor plugin export preserve the same bundles. Resource files receive no generated header and are never executed during generation. Keep relative links within the skill directory.

Generation validates bundles before target cleanup and rejects symlinks, non-regular files, and unsafe paths. --diff detects binary and permission changes without printing binary contents or modifying files. Existing single-file skills retain their output format.

Custom GenerationFileSystem adapters may implement the optional readBytes, writeBytes (with a mode option), and statMode methods. Resource-bearing generation requires all three and fails before mutation when they are absent; the text-only API remains compatible. GenerateResult.artifactSources maps each skill output path to its exact source paths for generation evidence. Resource digests hash raw bytes; existing UTF-8 text digests remain unchanged.

For repository authoring, use maintain-agentpacks and edit canonical pack sources. Keep descriptions specific, route conditional details to references, and update feature-units.json when adding or removing resources. Verify generated links and behavior as well as schema validity.

Governed generation evidence

Production generation can emit a canonical AgentpackGenerationTraceManifestV1. Evidence mode is fail closed: the exact Connect decision and replay artifacts plus SOURCE_DATE_EPOCH are required, and preview modes never write a manifest.

SOURCE_DATE_EPOCH=1700000000 agentpacks generate \
  --targets codexcli \
  --trace-manifest .agentpacks/traces/generation.json \
  --connect-decision .contractspec/connect/decision.json \
  --connect-replay .contractspec/connect/replay.json

Each trace binds normalized source paths, source digests, target capability, output action and digest, deterministic time, and Connect evidence. Evidence contains references and digests—not source contents, credentials, prompts, or secret values. RTK refresh completes before output digests are recorded.

Create and independently verify an AgentpackAiAuditReceiptV1 against an exact commit SHA and exact changed-path scope:

agentpacks ai-audit create \
  --output .agentpacks/audit.json \
  --trace-manifests .agentpacks/traces/generation.json \
  --baseline 0123456789abcdef0123456789abcdef01234567

agentpacks ai-audit verify \
  --receipt .agentpacks/audit.json \
  --expected-sha 89abcdef0123456789abcdef0123456789abcdef \
  --baseline 0123456789abcdef0123456789abcdef01234567

Verification re-hashes active AGENTS.md rules, manifests, their source and Connect references, and generated artifacts. A stale SHA, changed path scope, missing evidence, invalid schema, or digest mismatch fails verification.

Root Claude and Codex context is maintained inside explicit agentpacks-managed Markdown blocks in CLAUDE.md and AGENTS.md. Content outside those blocks, including repository boundaries, package guidance, and RTK instructions, is preserved across regeneration.

Generated Markdown keeps YAML frontmatter on the first line; the Generated by agentpacks header follows the frontmatter so hosts can parse skill, agent, command, and rule metadata. Claude Code agents receive name, description, and a Claude-compatible model: an explicit claudecode.model (including inherit) wins, the models.json profile model applies only when the agent sets none, and non-Anthropic profile models fall back to the session model. Claude Code detail rules with globs (or claudecode.paths) emit paths: and load only for matching files; rules with no globs or **/* stay always loaded. pack validate warns about a rule with no globs, no claudecode.paths, and Cursor alwaysApply: false; set claudecode.paths: ['**/*'] to keep such a rule always loaded on purpose. Model guidance (model-config) loads only for **/models.json and agentpacks.jsonc in Claude Code and Cursor.

Platform compatibility and canonical packs

Agentpacks is migrating from file-only pack prose toward typed all-content feature units that can render or transform platform-native artifacts without semantic drift or silent loss. The public contract is:

• canonical production guidance lives in three pack families: ContractSpec-specific, software best practices, and monorepo-specific ContractSpec mission/goals/constraints;
• each canonical pack includes feature-units.json as the typed all-content migration baseline;
• every meaningful prose feature unit must keep a shared invariant and explicit Claude plus Codex/GPT variants;
• OpenCode selects the Codex/GPT operational variant by default;
• Codex CLI generation treats root AGENTS.md as the primary operational guidance surface and may also emit .codex/* artifacts;
• structural feature units such as hooks, MCP, model profiles, plugins, ignore files, assets, manifests, and exported docs require target capability status, transform/loss policy, diagnostics, and trace evidence;
• generated files must preserve traceability back to feature-unit ids and Connect parity evidence;
• agentpacks:all is the selected core-target smoke run, while agentpacks:compat:all-targets is the exhaustive registered-target compatibility run.

See docs/agentpacks-platform-compatibility.md and packs/README.md in the ContractSpec repository for the canonical taxonomy, legacy-pack disposition, and release gates.

Architecture

src/application/ is a data-only compiler. It rejects executable expressions, computed keys, methods, spread, template literals, unsafe sandbox policy, secret literals, and unresolved references instead of evaluating authored source. Successful output is passed through the canonical defineAgent() and defineWorkflow() entry points before it is returned.

Protocol V1 applications may declare the existing AgentSpec.protocol and communicationProfileRef fields in agent/agent.ts. Their compiler caller must supply an explicit compiledAt evidence timestamp. The compiler then emits a canonical application manifest and permission summary that bind the source, tools, connections, communication profiles, automations, subagents, evaluations, and protocol policy references by SHA-256. Legacy applications remain unchanged and do not receive Protocol V1 evidence implicitly.

Filesystem applications may declare a stable applicationId distinct from their legacy meta.key. This is opt-in for Protocol V1 and lets an existing public agent key remain compatible while lifecycle and qualification bind the canonical installed application identity.

Protocol V1 schedules may opt into a governance block with timezone, objective, policy and evidence refs, risk and approval requirements, bounded run count and active days, and delivery requirements. Agentpacks compiles those sources into immutable AgentAutomationDefinitionV1 artifacts bound to the exact application manifest. Legacy schedules without governance compile as before and do not become materializable automation definitions implicitly. Compiler output never deploys a schedule or grants effect authority; Agent Host and the selected policy owner must separately preview, authorize, materialize, persist, and qualify it.

• src/cli/ contains command implementations for init, generate, install, publish, search, and pack subcommands.
• src/core/ handles config loading, dependency resolution, pack loading, typed feature-unit coverage validation, lockfiles, and feature merging.
• src/features/, src.sources/, src.targets/, src.importers/, and src.exporters/ implement the pack pipeline.
• src.utils/ contains credentials, diffing, markdown, registry, and model-helper utilities.
• src/index.ts is the root public barrel and package entrypoint.

Public Entry Points

• Exports the CLI binary plus API, core, features, targets, sources, importers, exporters, and utility subpaths.
• Binary agentpacks points to ./dist/index.js.
• Export . resolves through ./src/index.ts.
• Export ./api resolves through ./src/api.ts.
• Export ./cli/export-cmd resolves through ./src/cli/export-cmd.ts.
• Export ./cli/generate resolves through ./src/cli/generate.ts.
• Export ./cli/ai-audit resolves through ./src/cli/ai-audit.ts.
• Export ./evidence exposes generation trace and AI-audit APIs.
• Export ./cli/import-cmd resolves through ./src/cli/import-cmd.ts.
• Export ./cli/info resolves through ./src/cli/info.ts.
• Export ./cli/init resolves through ./src/cli/init.ts.
• Export ./cli/install resolves through ./src/cli/install.ts.
• Export ./cli/login resolves through ./src/cli/login.ts.
• Export ./cli/models-explain resolves through ./src/cli/models-explain.ts.

Local Commands

• bun run dev — contractspec-bun-build dev
• bun run build — contractspec-bun-build build
• bun run test — bun test --pass-with-no-tests
• bun run lint — bun lint:fix
• bun run lint:check — biome check .
• bun run lint:fix — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
• bun run typecheck — tsgo --noEmit
• bun run publish:pkg — bun publish --tolerate-republish --ignore-scripts --verbose
• bun run publish:pkg:canary — bun publish:pkg --tag canary
• bun run clean — rimraf dist .turbo
• bun run build:bundle — contractspec-bun-build transpile
• bun run build:types — contractspec-bun-build types
• bun run prebuild — contractspec-bun-build prebuild

Recent Updates

• Use the Biome-only lint and formatting workflow in pack guidance and generated targets.
• Vnext ai-native.
• Add latest models and align defaults.
• Harden AgentSkills compatibility in agentpacks.
• Add first-class mistral provider support.
• Align cursor plugin export and hooks output.

Notes

• Do not modify target output formats without updating the corresponding target writer, capability matrix, trace/loss diagnostics, and release evidence.
• Pack schema changes must stay backward-compatible (see schema.json) unless the release capsule explicitly declares the public compatibility-surface migration and migration evidence.
• Never hard-code model names; use utils/model-allowlist and utils/model-guidance.