feat(agents-init): scaffold AGENTS/ sub-repo with symlinks, plugin dirs, and AI wrapper integration #52

2026-06-13T02:16:07Z

rootiest commented

2026-06-13 02:16:07 +00:00

Summary

Adds agents-init fish function that scaffolds a self-contained AGENTS/ git sub-repo inside any project, moves existing agent files into it, and replaces them with symlinks so the outer project never tracks agent files directly
Adds _agents_init_ensure_gitignore private helper that checks (via git check-ignore with correct path normalization) and appends missing patterns as a labeled comment block
Adds agy.fish wrapper — runs agents-init (full setup) before launching the Antigravity CLI, mirroring the claude wrapper
Removes antigravity.fish — the filtered warning no longer exists; agy is used directly
Updates ag/ag. abbreviations to expand to agy instead of antigravity
Refactors claude.fish to call agents-init (full setup, both modes) before launch
Adds doc blocks to save_antigravity_session.fish and save_claude_session.fish

What `agents-init` does

Flag	Effect
(none)	Runs both `--agents` and `--plugins`
`--agents`	Initializes `AGENTS/` git repo; moves/creates `AGENTS/AGENTS.md` and `AGENTS/CLAUDE.md`; symlinks root `AGENTS.md → AGENTS/AGENTS.md` and `CLAUDE.md → AGENTS/CLAUDE.md`
`--plugins`	Creates `AGENTS/plugins/{superpowers,plans,specs}/`; migrates any existing `docs/<dir>` content into them; symlinks `docs/<dir> → ../AGENTS/plugins/<dir>`

File layout after full setup

<project-root>/
├── AGENTS/                        # standalone git sub-repo (gitignored)
│   ├── AGENTS.md                  # canonical agent spec (real file)
│   ├── CLAUDE.md                  # real file (if both existed) or → AGENTS.md
│   └── plugins/
│       ├── superpowers/
│       ├── plans/
│       └── specs/
├── AGENTS.md  →  AGENTS/AGENTS.md          # root symlink (gitignored)
├── CLAUDE.md  →  AGENTS/CLAUDE.md          # root symlink (gitignored)
└── docs/
    ├── superpowers  →  ../AGENTS/plugins/superpowers
    ├── plans        →  ../AGENTS/plugins/plans
    └── specs        →  ../AGENTS/plugins/specs

CLAUDE.md handling — four cases, no data loss

Initial state	Result
Neither exists	`AGENTS/AGENTS.md` created with agent directive; `AGENTS/CLAUDE.md → AGENTS.md`
Only `AGENTS.md`	Moved to `AGENTS/AGENTS.md`; `AGENTS/CLAUDE.md → AGENTS.md`
Only `CLAUDE.md`	Moved to `AGENTS/AGENTS.md`; `AGENTS/CLAUDE.md → AGENTS.md`
Both exist	Each moved to its own file in `AGENTS/`; root symlinks point to respective files

Root CLAUDE.md always points to AGENTS/CLAUDE.md, giving a consistent two-level chain: CLAUDE.md → AGENTS/CLAUDE.md → AGENTS/AGENTS.md. Existing symlinks with wrong targets are auto-corrected on the next run via readlink check.

Auto-commit

On every invocation, any changes inside AGENTS/ are staged and committed automatically — chore: initialize AGENTS repository on first run, chore: sync AGENTS repository thereafter. This means every claude or agy launch captures agent-made edits from the previous session without manual intervention.

Manual Verification

Run agents-init in a fresh project — verify AGENTS/ dir is created with its own .git repo
Confirm AGENTS.md → AGENTS/AGENTS.md and CLAUDE.md → AGENTS/CLAUDE.md symlinks exist in the root
Confirm docs/superpowers, docs/plans, docs/specs are symlinks into AGENTS/plugins/
Run agents-init a second time — verify it is fully idempotent (no output, no new commits)
In a project with existing docs/superpowers content, run agents-init — verify content is migrated and symlink created
Modify AGENTS/AGENTS.md, then run agents-init again — verify a new commit appears capturing the change
Run agents-init --help — verify usage message prints and exits 0
In a project with both real AGENTS.md and CLAUDE.md, run agents-init — verify both are preserved as separate files in AGENTS/
In a project with a real CLAUDE.md only, run agents-init — verify it becomes AGENTS/AGENTS.md
Run claude in a project — verify agents-init fires, AGENTS sub-repo is committed, then claude launches
Run agy in a project — same verification as above
Confirm ag abbreviation expands to agy

## Summary - Adds `agents-init` fish function that scaffolds a self-contained `AGENTS/` git sub-repo inside any project, moves existing agent files into it, and replaces them with symlinks so the outer project never tracks agent files directly - Adds `_agents_init_ensure_gitignore` private helper that checks (via `git check-ignore` with correct path normalization) and appends missing patterns as a labeled comment block - Adds `agy.fish` wrapper — runs `agents-init` (full setup) before launching the Antigravity CLI, mirroring the `claude` wrapper - Removes `antigravity.fish` — the filtered warning no longer exists; `agy` is used directly - Updates `ag`/`ag.` abbreviations to expand to `agy` instead of `antigravity` - Refactors `claude.fish` to call `agents-init` (full setup, both modes) before launch - Adds doc blocks to `save_antigravity_session.fish` and `save_claude_session.fish` ## What `agents-init` does | Flag | Effect | |------|--------| | _(none)_ | Runs both `--agents` and `--plugins` | | `--agents` | Initializes `AGENTS/` git repo; moves/creates `AGENTS/AGENTS.md` and `AGENTS/CLAUDE.md`; symlinks root `AGENTS.md → AGENTS/AGENTS.md` and `CLAUDE.md → AGENTS/CLAUDE.md` | | `--plugins` | Creates `AGENTS/plugins/{superpowers,plans,specs}/`; migrates any existing `docs/<dir>` content into them; symlinks `docs/<dir> → ../AGENTS/plugins/<dir>` | ### File layout after full setup ``` <project-root>/ ├── AGENTS/ # standalone git sub-repo (gitignored) │ ├── AGENTS.md # canonical agent spec (real file) │ ├── CLAUDE.md # real file (if both existed) or → AGENTS.md │ └── plugins/ │ ├── superpowers/ │ ├── plans/ │ └── specs/ ├── AGENTS.md → AGENTS/AGENTS.md # root symlink (gitignored) ├── CLAUDE.md → AGENTS/CLAUDE.md # root symlink (gitignored) └── docs/ ├── superpowers → ../AGENTS/plugins/superpowers ├── plans → ../AGENTS/plugins/plans └── specs → ../AGENTS/plugins/specs ``` ### CLAUDE.md handling — four cases, no data loss | Initial state | Result | |---|---| | Neither exists | `AGENTS/AGENTS.md` created with agent directive; `AGENTS/CLAUDE.md → AGENTS.md` | | Only `AGENTS.md` | Moved to `AGENTS/AGENTS.md`; `AGENTS/CLAUDE.md → AGENTS.md` | | Only `CLAUDE.md` | Moved to `AGENTS/AGENTS.md`; `AGENTS/CLAUDE.md → AGENTS.md` | | Both exist | Each moved to its own file in `AGENTS/`; root symlinks point to respective files | Root `CLAUDE.md` always points to `AGENTS/CLAUDE.md`, giving a consistent two-level chain: `CLAUDE.md → AGENTS/CLAUDE.md → AGENTS/AGENTS.md`. Existing symlinks with wrong targets are auto-corrected on the next run via `readlink` check. ### Auto-commit On every invocation, any changes inside `AGENTS/` are staged and committed automatically — `chore: initialize AGENTS repository` on first run, `chore: sync AGENTS repository` thereafter. This means every `claude` or `agy` launch captures agent-made edits from the previous session without manual intervention. ## Manual Verification - [x] Run `agents-init` in a fresh project — verify `AGENTS/` dir is created with its own `.git` repo - [x] Confirm `AGENTS.md → AGENTS/AGENTS.md` and `CLAUDE.md → AGENTS/CLAUDE.md` symlinks exist in the root - [x] Confirm `docs/superpowers`, `docs/plans`, `docs/specs` are symlinks into `AGENTS/plugins/` - [x] Run `agents-init` a second time — verify it is fully idempotent (no output, no new commits) - [x] In a project with existing `docs/superpowers` content, run `agents-init` — verify content is migrated and symlink created - [x] Modify `AGENTS/AGENTS.md`, then run `agents-init` again — verify a new commit appears capturing the change - [x] Run `agents-init --help` — verify usage message prints and exits 0 - [x] In a project with both real `AGENTS.md` and `CLAUDE.md`, run `agents-init` — verify both are preserved as separate files in `AGENTS/` - [x] In a project with a real `CLAUDE.md` only, run `agents-init` — verify it becomes `AGENTS/AGENTS.md` - [x] Run `claude` in a project — verify `agents-init` fires, AGENTS sub-repo is committed, then claude launches - [x] Run `agy` in a project — same verification as above - [x] Confirm `ag` abbreviation expands to `agy`

rootiest added 14 commits 2026-06-13 02:16:08 +00:00

feat(agents-init): add gitignore helper function 522fd03c12

fix(agents-init): add write-error check and arg validation to gitignore helper b6ed77d8f9

fix(agents-init): move argv assignments after guard in gitignore helper e6de825fb1

feat(agents-init): scaffold function with argparse, help, and sub-repo init 1e1c2003f3

fix(agents-init): address code quality issues in skeleton 7463d894f2

feat(agents-init): add --agents mode (AGENTS.md move + symlinks + gitignore) d1949953df

fix(agents-init): add error checks and CLAUDE.md move to --agents mode 2a9a7ed2ff

feat(agents-init): add --plugins mode (docs/ move + symlinks + gitignore) 3befc07887

fix(agents-init): use fish-idiomatic command substitution in --plugins mode a483c30c05

feat(agents-init): add auto-commit step for AGENTS/ sub-repo 8d0f425b10

refactor(claude): delegate symlink logic to agents-init --agents 0167370823

docs: add agents-init entry and update claude description in fish-config.md 11dc584104

fix(agents-init): address final review issues (CLAUDE.md safety, rm-rf guard, gitignore anchoring, worktree detection) 45cba3a15b

docs: add SYNOPSIS/DESCRIPTION doc blocks to session hook scripts and index entries 178214c812

rootiest added 1 commit 2026-06-13 02:25:54 +00:00

feat(agy): wrap agy with agents-init --agents, same as claude wrapper e96f874469

rootiest added 2 commits 2026-06-13 02:27:39 +00:00

chore: remove antigravity wrapper (filtered error no longer exists, use agy directly) d68bedef95

chore: update ag/ag. abbreviations and docs to point to agy instead of antigravity 015daec928

rootiest added 1 commit 2026-06-13 03:05:47 +00:00

fix(agents-init): migrate plugin dirs, smarter CLAUDE.md handling, wrappers run full init 3a054021cf

- Move plugin dir creation into --plugins mode (not 'Always') so --agents
  alone no longer creates empty AGENTS/plugins/ dirs
- Wrappers (claude, agy) now call plain agents-init (both modes) so plugin
  dirs in docs/ are migrated on the first AI launch, not just --agents
- Rewrite --agents CLAUDE.md logic: detect which root files are real vs
  symlinks and handle all four cases (both/agents-only/claude-only/neither)
  without ever losing content
- AGENTS/CLAUDE.md is now its own file in AGENTS/ (real file when both
  existed, symlink → AGENTS.md for single-source cases)
- Root CLAUDE.md now points to AGENTS/CLAUDE.md instead of AGENTS/AGENTS.md;
  readlink checks auto-fix existing symlinks with the wrong target
- New empty setups get AGENTS/AGENTS.md pre-populated with the agent
  directive warning editors not to write through the root symlinks

rootiest added 1 commit 2026-06-13 03:30:20 +00:00

fix(agents-init): fix gitignore duplicate entries, add block comment style 9f9248deb1

- Strip leading / from pattern before git check-ignore so root-anchored
  patterns like /AGENTS.md are checked as repo-relative paths (AGENTS.md)
  and correctly match existing rules — fixes duplicates on every run
- Rework helper to accept multiple patterns and write them as a single
  labeled block with project-style header/footer comment rather than
  appending bare patterns one at a time
- Move gitignore calls out of per-plug loop in --plugins mode so all
  three docs/ patterns are checked and written in one block
- Remove 5 duplicate bare entries left in .gitignore by the broken runs

rootiest changed title from ~~feat(agents-init): scaffold AGENTS/ sub-repo with symlinks and plugin dirs~~ to feat(agents-init): scaffold AGENTS/ sub-repo with symlinks, plugin dirs, and AI wrapper integration

2026-06-13 03:36:15 +00:00

rootiest added 1 commit 2026-06-13 03:51:33 +00:00

fix(agents-init): use command cp -rn to bypass interactive wrapper and skip existing files 69384f6427

rootiest added 1 commit 2026-06-13 04:03:15 +00:00

feat(agents-init): add --quiet and --silent flags; wrappers use --quiet 8f845f7cf2

rootiest added 1 commit 2026-06-13 04:05:34 +00:00

feat(agents-init): add -a/--agents and -p/--plugins short flags 2a7cb0f5cb

rootiest added 1 commit 2026-06-13 04:19:18 +00:00

fix(agents-init): quiet only on change, add -v/--verbose flag 976f46757c

- quiet mode now outputs one summary line only when something actually changed;
  idempotent re-runs produce no output
- add -v/--verbose flag as an explicit alias for the default verbose behavior
- gitignore helper output captured to detect changes without printing in quiet mode
- drop eager "Initializing…" header in favour of end-of-run conditional summary

rootiest added 1 commit 2026-06-13 04:24:23 +00:00

chore(agents-init): fix formatting and alignment a5966fd982

rootiest merged commit 50e4d92249 into main

2026-06-13 04:26:25 +00:00

rootiest deleted branch feat/agents-init

2026-06-13 04:26:26 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: rootiest/fish-config#52