From 70f1ec2eebaed9963c5c60ca15af4b84f4084e0a Mon Sep 17 00:00:00 2001
From: rootiest <chris@rootiest.com>
Date: Wed, 17 Jun 2026 21:42:36 -0400
Subject: [PATCH] docs: document AGENTS/ structure versioning and current
 layout

---
 docs/fish-config.index     |  8 ++++++++
 docs/fish-config.md        | 35 ++++++++++++++++++++++++-----------
 functions/agents-init.fish |  9 +++++++++
 3 files changed, 41 insertions(+), 11 deletions(-)

diff --git a/docs/fish-config.index b/docs/fish-config.index
index 32ee3fa..9660d6e 100644
--- a/docs/fish-config.index
+++ b/docs/fish-config.index
@@ -135,6 +135,14 @@ smart-exit=### smart_exit
 ai=## 5.12 AI and Developer Tools
 antigravity-ide=### antigravity-ide
 agy=### agy
+agents-init=### agents-init
+agents=### agents-init
+agents-tools=### agents-init
+version-bump=### agents-init
+.version=### agents-init
+structure-version=### agents-init
+core.hooksPath=### agents-init
+devlogs=### agents-init
 claude-cli=### claude
 claude-docs=### claude-docs
 claude-pr=### claude-pr
diff --git a/docs/fish-config.md b/docs/fish-config.md
index 630ba2d..232c735 100644
--- a/docs/fish-config.md
+++ b/docs/fish-config.md
@@ -1127,17 +1127,30 @@ Add -i (interactive confirmation) to destructive commands:
 ### agents-init
 
     Synopsis:  agents-init [--agents | --plugins]
-    Scaffold an AGENTS/ sub-repository for tracking agent specs and plugin
-    directories. Creates AGENTS/ as a standalone git repo, initializes
-    standard plugin subdirectories (superpowers/, plans/, specs/), moves any
-    existing AGENTS.md and docs/plugin dirs into the sub-repo, and replaces
-    them with relative symlinks. Also adds CLAUDE.md -> AGENTS/AGENTS.md so
-    Claude Code picks up the shared agent instructions. Adds all managed
-    paths to .gitignore and auto-commits every change inside the AGENTS/
-    sub-repo. Fully idempotent: a second run produces no output and no new
-    commits. Flags: --agents re-runs only the AGENTS.md / symlink step;
-    --plugins re-runs only the plugin-directory wiring step. Called
-    automatically by the claude and agy wrappers on every invocation.
+    Scaffold an AGENTS/ sub-repository for tracking agent specs, plans, specs,
+    and dev logs. Creates AGENTS/ as a standalone git repo, moves any existing
+    AGENTS.md into it, and replaces it with a relative symlink (plus
+    CLAUDE.md -> AGENTS/AGENTS.md so Claude Code picks up the shared agent
+    instructions). Consolidates plans/ and specs/ directly under AGENTS/
+    (merging any legacy docs/plans, docs/superpowers/plans, or old
+    AGENTS/plugins/ locations into the canonical AGENTS/<tgt>), creates
+    AGENTS/devlogs/, and wires docs/superpowers/{plans,specs} symlinks back to
+    them. Adds managed paths to .gitignore and auto-commits every change inside
+    the AGENTS/ sub-repo; pulls first when the sub-repo has an upstream.
+    Fully idempotent: a second run produces no output and no new commits.
+    Flags: --agents re-runs only the AGENTS.md / symlink step; --plugins
+    re-runs only the plans/specs/devlogs wiring step. Called automatically by
+    the claude and agy wrappers on every invocation.
+
+    Structure versioning: each AGENTS/ repo carries a self-contained version
+    bumper. AGENTS/.version holds MAJOR.MINOR.PATCH (seeded 1.0.0). Committed
+    git hooks under AGENTS/.agents-tools/ (wired via core.hooksPath) bump it on
+    every commit: MINOR (resetting PATCH) when the tracked directory set
+    changes, PATCH otherwise; MAJOR is manual-only. A prepare-commit-msg hook
+    appends "(vX.Y.Z)" to the commit subject. Downstream tooling can read
+    AGENTS/.version - a changed MINOR field signals a structure change. The
+    script and hooks are shipped from scripts/agents-tools/ and refreshed when
+    their version marker is stale.
 
     agents-init
     agents-init --agents
diff --git a/functions/agents-init.fish b/functions/agents-init.fish
index 74b35d1..bca1ba4 100644
--- a/functions/agents-init.fish
+++ b/functions/agents-init.fish
@@ -20,6 +20,8 @@
 #     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)
@@ -30,6 +32,13 @@
 #   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. The script/hooks are version-managed from
+#   scripts/agents-tools/ and refreshed when their marker is stale.
+#
 #   With no flags, runs both --agents and --plugins setup. At the end of
 #   every invocation, commits any uncommitted changes in the AGENTS/ sub-repo
 #   so that agent-made edits are captured automatically.