Skip to content

AGENT.md

Latest commit

 

History

History
121 lines (89 loc) · 4.55 KB

AGENT.md

File metadata and controls

121 lines (89 loc) · 4.55 KB
Raw

Agentwheel For AI Agents

Agentwheel is the control plane for installing OpenPack resources into agent runtimes. Use it when a user wants to discover, add, install, update, remove, or publish skills, instructions, rules, commands, subagents, MCP, hooks, settings, plugins, or fragments.

Operating Model

  • add records desired packages in .agentwheel/config.json.
  • plan previews what would change.
  • install makes the declared state true.
  • update refreshes tracking packages, then installs; a configured package name preserves other roots, while update --dependency <name-or-source> advances one tracking dependency and keeps unrelated graph nodes locked.
  • uninstall removes managed runtime output and config entries.

Runtime output directories are generated. Do not hand-edit generated skills, runtime config, or plugin directories to complete an Agentwheel change.

Standard Flow

agentwheel add github:owner/agent-pack --adapter codex --local --mode tracking
agentwheel plan
agentwheel install
agentwheel status

To add and install in one step:

agentwheel install github:owner/agent-pack --adapter codex --local

Use explicit scope when the target matters:

agentwheel install github:owner/agent-pack --adapter claude --user
agentwheel install github:owner/agent-pack --adapter codex --local
agentwheel install --fleet example-fleet --profile daily --dry-run

--user, --local, and --fleet <fleet-id> select separate desired-state scopes. Named fleets are optional. Do not merge scopes or assume a fleet has priority over user or local state.

Register and inspect a fleet using schema v3 or newer only after its canonical root, matching fleetId, and required packages exist:

agentwheel fleet register example-fleet --root /srv/agentwheel/fleets/example-fleet --required-package core-agent-pack
agentwheel fleet list
agentwheel fleet show example-fleet

If a configured runtime path is owned by another scope, stop and use the separate plan-first normalization workflow. Review its digest before apply; matching content is not permission to take ownership.

agentwheel fleet normalize example-fleet --from user --package core-agent-pack --json
agentwheel fleet normalize example-fleet --from user --package core-agent-pack --plan-digest <reviewed-sha256> --apply
agentwheel fleet normalize example-fleet --from user --recover

Named fleets require a CLI that supports schema v3 or newer. Upgrade Agentwheel first and verify agentwheel fleet --help before creating, registering, reading, or planning fleet state. Do not downgrade the config, strip fleet fields, or run a planning/mutation command with the old CLI.

Companion Skills

Install the Agentwheel companion skill when the user wants Agentwheel guidance inside the runtime:

agentwheel doctor --adapter codex --local
agentwheel install github:NestDevLab/agentwheel --adapter codex --local --skill agentwheel

In Syncwheel-managed repositories, doctor can also check for the Syncwheel skill:

agentwheel doctor --adapter codex --local --skill syncwheel --source github:NestDevLab/syncwheel
agentwheel install github:NestDevLab/syncwheel --adapter codex --local --skill syncwheel

Sources And Catalogue

Use direct sources when known:

agentwheel install github:owner/repo --adapter codex --local
agentwheel install skillkit:owner/skill-name --adapter claude --user
agentwheel install vercel:owner/skill-name --adapter codex --user
agentwheel install mcp-registry:publisher/server-name --adapter claude --local
agentwheel install clawhub:@openclaw/package-name --adapter openclaw --local

Use the catalogue for browsing and copy-ready commands:

https://www.nestdev.it/agentwheel/catalogue.html

Draft a public catalogue submission without editing the registry by hand:

npx agentwheel@latest registry publish https://github.com/owner/repo

Safety

  • Prefer agentwheel plan or agentwheel install --dry-run before broad or fleet changes.
  • Stop on drift or conflict unless the user explicitly approves the exact scope.
  • Use --adapter-module only with --allow-adapter-code after the user approves local code execution.
  • Use --execute-plugins only after the user approves plugin execution.
  • Treat registry publishing, Git commits, pushes, and runtime restarts as separate side effects.

Key References

  • Install handoff: install.md
  • Package spec: docs/spec/openpack.md
  • Compatibility matrix: docs/design/artifact-harness-compatibility.md
  • Fleet config: docs/fleet-config.md
  • Catalogue: docs/catalogue.html