feat(agents): AGENTS/ structure versioning + plans/specs/devlogs consolidation #57

2026-06-18T01:55:07Z

rootiest commented

2026-06-18 01:55:07 +00:00

Summary

Two related AGENTS/-structure improvements to agents-init.

1. Structure versioning (new)

Every AGENTS/ sub-repo now carries a self-contained, commit-time version bumper:

AGENTS/.version — MAJOR.MINOR.PATCH (seeded 1.0.0).
- MAJOR — manual only.
- MINOR — auto-bumped (PATCH reset to 0) when the tracked directory set changes between HEAD and the staged index (dot-dirs like .agents-tools excluded; .gitkeep keeps empty dirs visible).
- PATCH — auto-bumped on every other commit.
AGENTS/.agents-tools/ — committed version-bump script + pre-commit / prepare-commit-msg hook shims, wired via local core.hooksPath. The prepare-commit-msg hook appends (vX.Y.Z) to the commit subject.
Hooks never block a commit (guarded [ -x ], always exit 0).
agents-init seeds .version, installs/refreshes the tooling (marker-versioned), sets core.hooksPath, and now pulls before auto-commit when an upstream exists (no-op for local-only repos).

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

2. plans/specs/devlogs consolidation

Dropped the AGENTS/plugins/ layer; plans/ and specs/ now live directly under AGENTS/ alongside the new devlogs/.
Merges content from every legacy location (docs/<tgt>, docs/superpowers/<tgt>, old AGENTS/plugins/...) into the canonical AGENTS/<tgt>.
Always creates docs/superpowers/{plans,specs} symlinks (where superpowers skills write); docs/{plans,specs} symlinks only when they had existed as real dirs.

Design & plan

Captured in the AGENTS sub-repo: specs/2026-06-17-agents-version-tracking-design.md, plans/2026-06-17-agents-version-tracking.md.

Tests

scripts/agents-tools/test-version-bump.sh — 5 hermetic blocks (precommit baseline/PATCH/MINOR, prepmsg suffix+idempotency, real-hook e2e, corrupt-.version recovery, hook-resilience-when-bumper-missing). All green.
Two independent review passes; findings fixed (incl. a real hook-blocking bug in the first hook approach).

Notes

Docs synced: docs/fish-config.md + docs/fish-config.index (offline SSOT). README unchanged (overview-only; defers function/agent-tooling detail to offline docs).
The AGENTS/ sub-repo is gitignored by this repo; its own commits are separate and local.

Manual Verification

Fresh repo: cd (mktemp -d); and agents-init → creates AGENTS/.version = 1.0.0, AGENTS/.agents-tools/{version-bump,hooks/*} (executable), and core.hooksPath = .agents-tools/hooks.
In that AGENTS repo, mkdir newdir; touch newdir/.gitkeep; git add -A; git commit -m "add dir" → .version bumps to 1.1.0 and the commit subject ends with (v1.1.0).
A content-only commit (edit an existing file) bumps PATCH only (e.g. 1.1.1), not MINOR.
Manually set MAJOR (echo 2.0.0 > AGENTS/.version) → next structure commit → 2.1.0; MAJOR is never auto-changed.
Second agents-init run on an unchanged repo is a strict no-op (no output, no new commit).
bash scripts/agents-tools/test-version-bump.sh prints precommit OK / prepmsg OK / e2e OK / corrupt-recovery OK / hook-resilience OK.
Existing behavior intact: agents-init still scaffolds plans/, specs/, devlogs/ and the docs/superpowers/{plans,specs} symlinks; no AGENTS/plugins/ remains.
config-help agents-init (or browse docs/fish-config.md) reflects the versioning behavior.

## Summary Two related AGENTS/-structure improvements to `agents-init`. ### 1. Structure versioning (new) Every `AGENTS/` sub-repo now carries a self-contained, commit-time version bumper: - **`AGENTS/.version`** — `MAJOR.MINOR.PATCH` (seeded `1.0.0`). - **MAJOR** — manual only. - **MINOR** — auto-bumped (PATCH reset to 0) when the tracked **directory set** changes between `HEAD` and the staged index (dot-dirs like `.agents-tools` excluded; `.gitkeep` keeps empty dirs visible). - **PATCH** — auto-bumped on every other commit. - **`AGENTS/.agents-tools/`** — committed `version-bump` script + `pre-commit` / `prepare-commit-msg` hook shims, wired via local `core.hooksPath`. The `prepare-commit-msg` hook appends `(vX.Y.Z)` to the commit subject. - Hooks **never block a commit** (guarded `[ -x ]`, always `exit 0`). - `agents-init` seeds `.version`, installs/refreshes the tooling (marker-versioned), sets `core.hooksPath`, and now **pulls before auto-commit when an upstream exists** (no-op for local-only repos). Downstream tooling can read `AGENTS/.version` — a changed **MINOR** field signals a directory-structure change. ### 2. plans/specs/devlogs consolidation - Dropped the `AGENTS/plugins/` layer; `plans/` and `specs/` now live directly under `AGENTS/` alongside the new `devlogs/`. - Merges content from every legacy location (`docs/<tgt>`, `docs/superpowers/<tgt>`, old `AGENTS/plugins/...`) into the canonical `AGENTS/<tgt>`. - Always creates `docs/superpowers/{plans,specs}` symlinks (where superpowers skills write); `docs/{plans,specs}` symlinks only when they had existed as real dirs. ### Design & plan Captured in the AGENTS sub-repo: `specs/2026-06-17-agents-version-tracking-design.md`, `plans/2026-06-17-agents-version-tracking.md`. ## Tests - `scripts/agents-tools/test-version-bump.sh` — 5 hermetic blocks (precommit baseline/PATCH/MINOR, prepmsg suffix+idempotency, real-hook e2e, corrupt-`.version` recovery, hook-resilience-when-bumper-missing). All green. - Two independent review passes; findings fixed (incl. a real hook-blocking bug in the first hook approach). ## Notes - Docs synced: `docs/fish-config.md` + `docs/fish-config.index` (offline SSOT). README unchanged (overview-only; defers function/agent-tooling detail to offline docs). - The `AGENTS/` sub-repo is gitignored by this repo; its own commits are separate and local. ## Manual Verification - [x] Fresh repo: `cd (mktemp -d); and agents-init` → creates `AGENTS/.version` = `1.0.0`, `AGENTS/.agents-tools/{version-bump,hooks/*}` (executable), and `core.hooksPath` = `.agents-tools/hooks`. - [x] In that AGENTS repo, `mkdir newdir; touch newdir/.gitkeep; git add -A; git commit -m "add dir"` → `.version` bumps to `1.1.0` and the commit subject ends with `(v1.1.0)`. - [x] A content-only commit (edit an existing file) bumps **PATCH** only (e.g. `1.1.1`), not MINOR. - [x] Manually set `MAJOR` (`echo 2.0.0 > AGENTS/.version`) → next structure commit → `2.1.0`; MAJOR is never auto-changed. - [x] Second `agents-init` run on an unchanged repo is a strict no-op (no output, no new commit). - [x] `bash scripts/agents-tools/test-version-bump.sh` prints `precommit OK / prepmsg OK / e2e OK / corrupt-recovery OK / hook-resilience OK`. - [x] Existing behavior intact: `agents-init` still scaffolds `plans/`, `specs/`, `devlogs/` and the `docs/superpowers/{plans,specs}` symlinks; no `AGENTS/plugins/` remains. - [x] `config-help agents-init` (or browse `docs/fish-config.md`) reflects the versioning behavior.

rootiest added 7 commits 2026-06-18 01:55:08 +00:00

feat(agents-tools): add version-bump precommit logic dda63a05ff

test(agents-tools): cover version-bump prepmsg suffix 7d277e52bd

fix(agents-tools): harden version-bump test (CDPATH + hooks isolation), drop LFS band-aid 5cbb01497c

fix(agents-tools): never block commits on missing bumper; robust .version parse 58e21eba95

feat(agents-init): scaffold .version + commit-time version hooks, pull before commit 46dd6cd3a9

docs: document AGENTS/ structure versioning and current layout 70f1ec2eeb

fix(agents-init): guard install helper against silent failures 7474760525

rootiest merged commit b81cbd3b02 into main

2026-06-18 02:10:09 +00:00

rootiest deleted branch feat/agents-version-tracking

2026-06-18 02:10:10 +00:00