agents-init

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

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.

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)
`<root>/AGENTS.md`	→ AGENTS/AGENTS.md
`<root>/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/<tgt>,
docs/superpowers/<tgt>, and the old AGENTS/plugins/ layout) into the
canonical AGENTS/<tgt>; 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. The sub-repo is pulled first when it has an upstream, and at the end of every invocation any uncommitted changes inside it are auto-committed so agent-made edits are captured automatically. Fully idempotent: a second run produces no output and no new commits.

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

Returns:


`0`	Setup completed successfully
`1`	Fatal error (git init failed, move failed, etc.)

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

Used by: agy, claude