recodeee · NagyVikt · Apr 21, 2026 · Apr 21, 2026
@@ -28,8 +28,18 @@ I was running ~30 Codex agents in parallel and hit a wall: they kept working on
 
 ### Solution
 
+![Agent branch/worktree start protocol](https://raw.githubusercontent.com/recodeee/gitguardex/main/docs/images/workflow-branch-start.svg)
+
 GitGuardex exists to stop that loop. Every agent gets its own worktree, claims the files it's touching, and can't clobber files another agent has claimed. Your local branch stays clean; agents stay in their lanes.
 
+## GitHub About description
+
+The canonical GitHub About copy lives in [about_description.txt](./about_description.txt):
+
+```text
+Guardian T-Rex for your multi-agent repo. Isolated worktrees, file locks, and PR-only merges stop parallel Codex & Claude agents from overwriting each other's work. Auto-wires Oh My Codex, Oh My Claude, OpenSpec, and Caveman.
+```
+
 
 <p align="center">
   <img alt="Install GitGuardex" src="https://raw.githubusercontent.com/recodeee/gitguardex/main/docs/images/install-hero.svg" width="680">

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-21
@@ -0,0 +1,7 @@
+# T1 Notes
+
+- Handoff: change=`agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46`; scope=`package.json`; action=`align the npm package description with the existing Guardian T-Rex README/About copy`.
+- Replace the generic package description with the approved Guardian T-Rex positioning so npm metadata matches README and `about_description.txt`.
+- Restore the README GitHub About section so the canonical copy is linked and mirrored from the documented source.
+- Restore the README solution image required by the existing metadata/spec regression so the copy-alignment suite stays green after the metadata update.
+- Keep the change narrowly scoped to package metadata, one README parity fix, and the matching regression coverage; no version bump or runtime behavior change.
@@ -0,0 +1,16 @@
+## Why
+
+- `about_description.txt` and the README already use the approved Guardian T-Rex positioning, but `package.json` still exposes the older generic package description.
+- That drift makes the npm package metadata tell a different story than the canonical About copy.
+
+## What Changes
+
+- Align `package.json` `description` with the canonical text in `about_description.txt`.
+- Restore the README GitHub About section so the canonical copy is visible and linked from the documented source file.
+- Restore the missing README solution visual required by the current `readme-about-description` regression.
+- Add an OpenSpec delta that requires package metadata to stay aligned with the canonical About description source.
+
+## Impact
+
+- Affected surfaces: `package.json`, `README.md`, one metadata regression test, and the matching OpenSpec change record.
+- Risk is low and limited to package metadata / product copy consistency.
@@ -0,0 +1,14 @@
+## MODIFIED Requirements
+
+### Requirement: README points to one canonical GitHub About description source
+The repo SHALL keep one canonical GitHub About description in `about_description.txt`, and the README plus package metadata SHALL mirror that same copy instead of drifting across product surfaces.
+
+#### Scenario: package metadata matches the canonical About copy
+- **WHEN** a maintainer inspects `package.json` and `about_description.txt`
+- **THEN** `package.json` `description` matches the full canonical text in `about_description.txt`
+- **AND** the README continues to reference that same canonical source.
+
+#### Scenario: solution visual remains under the solution heading
+- **WHEN** a reader opens the top-level README
+- **THEN** the `### Solution` heading is followed by the workflow image
+- **AND** the Guardex solution copy appears below that image.
@@ -0,0 +1,25 @@
+## 1. Metadata
+
+- [x] 1.1 Update `package.json` so the npm description matches the canonical Guardian T-Rex copy.
+- [x] 1.2 Restore the README GitHub About section so it links to `about_description.txt` and mirrors the canonical copy.
+- [x] 1.3 Restore the README solution visual expected by the existing metadata/about regression.
+
+## 2. OpenSpec
+
+- [x] 2.1 Record the scope and handoff in the change notes.
+- [x] 2.2 Add a spec delta covering package metadata alignment with `about_description.txt`.
+
+## 3. Verification
+
+- [x] 3.1 Validate `package.json` parses as JSON.
+- [x] 3.2 Run `git diff --check`.
+- [x] 3.3 Update/add regression coverage for canonical About copy alignment.
+- [x] 3.4 Run `npm test`.
+- [x] 3.5 Run `openspec validate agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46 --type change --strict`.
+- [x] 3.6 Run `openspec validate --specs`.
+
+## 4. Cleanup
+
+- [ ] 4.1 Run `bash scripts/agent-branch-finish.sh --branch "agent/codex/align-guardian-t-rex-package-description-2026-04-21-18-46" --base main --via-pr --wait-for-merge --cleanup`.
+- [ ] 4.2 Record PR URL + final `MERGED` state in the completion handoff.
+- [ ] 4.3 Confirm sandbox cleanup (`git worktree list`, `git branch -a`) or capture a `BLOCKED:` handoff if merge/cleanup is pending.
@@ -1,7 +1,7 @@
 {
   "name": "@imdeadpool/guardex",
   "version": "7.0.16",
-  "description": "GitGuardex: hardened multi-agent git guardrails for parallel agent work.",
+  "description": "Guardian T-Rex for your multi-agent repo. Isolated worktrees, file locks, and PR-only merges stop parallel Codex & Claude agents from overwriting each other's work. Auto-wires Oh My Codex, Oh My Claude, OpenSpec, and Caveman.",
   "license": "MIT",
   "preferGlobal": true,
   "bin": {

@@ -72,6 +72,7 @@ test('README documents gx release as README-driven GitHub release writer', () =>
 test('README keeps canonical About copy and problem-solution visuals aligned', () => {
   const readme = fs.readFileSync(readmePath, 'utf8');
   const aboutDescription = fs.readFileSync(aboutDescriptionPath, 'utf8').trim();
+  const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
 
   assert.match(
     readme,
@@ -83,6 +84,7 @@ test('README keeps canonical About copy and problem-solution visuals aligned', (
   );
   assert.match(readme, /\[about_description\.txt\]\(\.\/about_description\.txt\)/);
   assert.match(readme, new RegExp(escapeRegexLiteral(aboutDescription)));
+  assert.equal(pkg.description, aboutDescription);
 });
 
 test('security workflows are present and use pinned GitHub Actions SHAs', () => {