diff --git a/README.md b/README.md index 4950aae..db33645 100644 --- a/README.md +++ b/README.md @@ -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. +``` +

Install GitGuardex diff --git a/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/.openspec.yaml b/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/.openspec.yaml new file mode 100644 index 0000000..4b8c565 --- /dev/null +++ b/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-04-21 diff --git a/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/notes.md b/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/notes.md new file mode 100644 index 0000000..19a31c8 --- /dev/null +++ b/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/notes.md @@ -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. diff --git a/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/proposal.md b/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/proposal.md new file mode 100644 index 0000000..950e935 --- /dev/null +++ b/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/proposal.md @@ -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. diff --git a/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/specs/readme-about-description/spec.md b/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/specs/readme-about-description/spec.md new file mode 100644 index 0000000..5fc2e52 --- /dev/null +++ b/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/specs/readme-about-description/spec.md @@ -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. diff --git a/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/tasks.md b/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/tasks.md new file mode 100644 index 0000000..8464451 --- /dev/null +++ b/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/tasks.md @@ -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. diff --git a/package.json b/package.json index 7422cd6..561864e 100644 --- a/package.json +++ b/package.json @@ -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": { diff --git a/test/metadata.test.js b/test/metadata.test.js index 41ea192..85f9117 100644 --- a/test/metadata.test.js +++ b/test/metadata.test.js @@ -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', () => {