animus-setup

name	animus-setup
description	Set up Animus in the current project - initialize config, connect MCP, install required plugins, create a first workflow, and start the daemon. Use when bootstrapping Animus in a repo or fixing an incomplete Animus setup.
user_invocable	true
auto_invoke	false
animus_version	0.7.0-rc.18

You are setting up Animus in the current project.

Do not preload the entire ~/animus-skills/skills/ directory. Start with targeted reads:

• Read getting-started first for the core Animus mental model.
• Read mcp-setup only when creating or fixing .mcp.json.
• Read workflow-authoring only when editing .animus/workflows.yaml or .animus/workflows/*.yaml.
• Read daemon-operations only when starting, checking, or debugging the daemon.
• Read troubleshooting only if setup fails.
• Use configuration, task-management, queue-management, and mcp-tools as lookup references, not mandatory preload.

Setup flow

Repo already has a committed animus.toml? Then setup is animus install (resolves the manifest into .animus/plugins.lock and installs the declared plugins + packs; --locked in CI), then continue at step 4.

1. Run animus init --walkthrough in the project root. It scaffolds animus.toml, .env.example, a merge-safe .gitignore, and .animus/. (animus setup was removed in v0.4.4 — use animus init.) The interactive walkthrough also installs the recommended workflow packs (default yes), offers a flavor picker when multiple flavors are discoverable, and suggests migrating env-var API keys to the keychain (animus secret set <KEY> — preferred over env vars).
2. Install required plugins with animus plugin install-defaults (bare — it installs the flavor's full required set: provider, task + requirement subject backends, config_source, transport-http, workflow-runner, queue; every daemon-preflight role in one command). --include-recommended adds extras. As plugins are added later, prefer animus add <spec> so the manifest + lock stay the record.
3. Run animus daemon preflight and resolve any missing role. When multiple roles are missing it prints the composed fix — animus install for manifest projects, else animus plugin install-defaults --flavor default --yes.
4. Create or verify .mcp.json pointing to the animus binary.
5. Create or validate a minimal workflow file.
6. Start the daemon with conservative defaults.
7. Create one small task subject, enqueue it, and verify end-to-end execution. Dispatch is event-driven — the enqueue wakes the daemon immediately.

Use animus init --walkthrough --non-interactive --no-install when automation should avoid prompts and plugin installs are already handled elsewhere; add --install-packs to install the recommended packs non-interactively, or --no-packs to skip them.

For team repos, commit animus.toml + .animus/plugins.lock — the lock is the source of truth for everyone (git clone && animus install). Binaries land in <project>/.animus/plugins/ (gitignored); .animus/plugins.yaml is a derived projection of the lock, never the authority.

Minimal workflow

Start with a small workflow instead of a full production pipeline:

agents:
  default:
    model: claude-sonnet-4-6
    tool: claude

phases:
  implementation:
    mode: agent
    agent: default
    idempotency: idempotent
    directive: Implement the task and report what changed.

workflows:
  - id: standard
    name: Standard
    phases: [implementation]

Expand it only after the daemon, MCP, and subject dispatch loop work.

Daemon startup

Start with:

animus daemon preflight
animus daemon start --pool-size 5
animus daemon health

animus daemon start always detaches (prints pid + log path; idempotent if already running). Use animus daemon run for a foreground dev/debug daemon and animus daemon restart to bounce it. The legacy --autonomous flag was removed — daemon start now errors on it (it always detaches). --interval-secs is only a fallback heartbeat now — dispatch itself is event-driven.

If preflight reports missing defaults on a dev machine:

animus daemon start --auto-install

Use --skip-preflight only when intentionally debugging without required plugins.

Verification

• Run animus daemon status or the MCP equivalent.
• Create a small task subject with animus subject create --kind task --title "Verify setup".
• Enqueue it with animus queue enqueue --subject-id task:<id>. The enqueue nudges the daemon, so pickup is immediate — no tick interval to wait for. The enqueue (or a cron schedules: entry) is the dispatch trigger; the daemon is queue-only and never scans the backend for Ready subjects.
• Confirm the daemon picks it up before adding more workflows or schedules.
• If a run stalls, check animus agent interactions list — agents can park mid-run on a pending question or approval; answer with animus agent interactions answer <ID>.

If something fails, read only the skill that matches the blocker instead of sweeping the whole repo.