agents-init

Synopsis

agents-init [-a | --agents] [-p | --plugins] [-v | --verbose]
            [-q | --quiet] [-s | --silent] [-h | --help]

Description

Scaffolds an AGENTS/ sub-repository inside a project directory. Creates a self-contained git repo for agent specifications, moves any existing agent-related files into it, and replaces them with symlinks so the outer project never tracks agent files directly.

Scaffolding runs only inside a git repository, or in a directory that already has an AGENTS.md, CLAUDE.md, or AGENTS/. Elsewhere it is a no-op, so running an agent CLI in an arbitrary directory does not create a repository there.

File layout after setup: AGENTS/AGENTS.md canonical agent spec (real file) AGENTS/CLAUDE.md real file (if CLAUDE.md existed separately) or symlink → AGENTS.md (single-source case) /AGENTS.md → AGENTS/AGENTS.md /CLAUDE.md → AGENTS/CLAUDE.md AGENTS/plans superpowers plans (real dir, .gitkeep) AGENTS/specs superpowers specs (real dir, .gitkeep) AGENTS/devlogs agent development logs (real dir, .gitkeep) AGENTS/.version MAJOR.MINOR.PATCH structure version (seed 1.0.0) AGENTS/.agents-tools/ committed version-bump script + git hook shims docs/superpowers/plans → ../../AGENTS/plans (always) docs/superpowers/specs → ../../AGENTS/specs (always) docs/plans → ../AGENTS/plans (only if docs/plans existed) docs/specs → ../AGENTS/specs (only if docs/specs existed) docs/devlogs → ../AGENTS/devlogs (only if docs/devlogs existed)

plans/ and specs/ are merged from every legacy location (docs/, docs/superpowers/, and the old AGENTS/plugins/ layout) into the canonical AGENTS/; the AGENTS/plugins/ layer is removed.

Each AGENTS repo carries a self-contained version bumper wired via core.hooksPath: a pre-commit hook bumps AGENTS/.version on every commit (MINOR when the tracked directory set changes, PATCH otherwise; MAJOR is manual-only), and a prepare-commit-msg hook appends “(vX.Y.Z)” to the commit subject. Each shim then chains (execs) to the global/system core.hooksPath hook of the same name, so this local override does not shadow global hooks (e.g. ggshield, Git LFS). The script/hooks are version-managed from scripts/agents-tools/ and refreshed when their marker is stale.

Downstream tooling can read AGENTS/.version directly — a changed MINOR field signals a structure change.

With no flags, runs both --agents and --plugins setup; --agents re-runs only the AGENTS.md / symlink step and --plugins only the plans/specs/ devlogs wiring step. Managed paths are added to .gitignore. At the end of every invocation any uncommitted changes inside the sub-repo are auto-committed so agent-made edits are captured automatically. Fully idempotent: a second run produces no output and no new commits.

The commit is local only. Nothing here fetches or pushes: the wrappers call this synchronously before starting an agent, and a network round trip there blocks the launch until an unreachable remote times out and can prompt for credentials with nobody watching. A sub-repo that has an upstream is pulled by hand, on the user’s own schedule.

Called automatically by the claude and agy wrappers on every invocation.

Arguments


`-a, --agents`	Set up AGENTS/ repo + `AGENTS.md` / `CLAUDE.md` symlinks only
`-p, --plugins`	Set up AGENTS/ repo + plans/specs/devlogs dirs + docs/ symlinks only
`-v, --verbose`	Print all per-step output (default)
`-q, --quiet`	Print one summary line only if changes were made
`-s, --silent`	Suppress all output; errors only (standard UNIX convention)
`-h, --help`	Show this help message and exit

Exit Status


`0`	Setup completed successfully
`1`	Fatal error (git init failed, move failed, the AGENTS/ commit was rejected, or an unresolved rebase blocked it)

Example

agents-init
agents-init --agents
agents-init --plugins
agents-init --quiet

Dependencies: _agents_repo_install_tools, _agents_repo_sync, _agents_init_ensure_gitignore

Classification: self-limiting(rm,mkdir), bypasses-shadow(mv)

Used by: agy, claude