recodeee · NagyVikt · Apr 21, 2026 · Apr 21, 2026
@@ -22,53 +22,23 @@
 
 ## The problem
 
-I was running ~30 Codex agents in parallel and hit a wall: they kept working on the same files at the same time — especially tests — and started overwriting or deleting each other's changes. More agents meant *less* forward progress, not more. Classic de-progressive loop.
+![Parallel agents colliding in the same files](https://raw.githubusercontent.com/recodeee/gitguardex/main/docs/images/problem-agent-collision.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.
+I was running ~30 Codex agents in parallel and hit a wall: they kept working on the same files at the same time — especially tests — and started overwriting or deleting each other's changes. More agents meant *less* forward progress, not more. Classic de-progressive loop.
 
 ### Solution
 
-```mermaid
-flowchart LR
-    A[Agent A adds assertions in a shared test] --> S[Several agents touch the same files]
-    B[Agent B rewrites the same test flow] --> S
-    C[Agent C updates the shared helper] --> S
-    D[Agent D deletes lines Agent A just added] --> S
-    E[Agent E saves an older snapshot of the file] --> S
-    S --> F[One agent overwrites another agent's edits]
-    F --> G[Another agent deletes code the others just added]
-    G --> H[Lost work, rework, and review confusion]
-    H --> I[Regression risk and flaky fixes grow]
-    I --> S
-```
+![Agent branch/worktree start protocol](https://raw.githubusercontent.com/recodeee/gitguardex/main/docs/images/workflow-branch-start.svg)
 
-<!-- ===================================================================== -->
-<!-- 1) GITHUB ABOUT SIDEBAR DESCRIPTION                                   -->
-<!-- ===================================================================== -->
-<!--                                                                       -->
-<!-- Paste one of these into:                                              -->
-<!--   Repo → Settings → General → Description                             -->
-<!--                                                                       -->
-<!-- The install command is removed — About is plain text, so there's no   -->
-<!-- way to make it copyable. The install lives in the README where the    -->
-<!-- code block gets GitHub's auto copy button on hover.                   -->
-<!-- ===================================================================== -->
+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
 
-Option A — leads with the tagline (matches README h1):
-    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.
-
-Option B — leads with the benefit:
-    Run many Codex & Claude agents in parallel without them overwriting each
-    other. Isolated worktrees, file locks, PR-only merges. Auto-wires Oh My
-    Codex, Oh My Claude, OpenSpec, and Caveman in every worktree.
-
-Option C — punchiest, under 200 chars:
-    Safety layer for parallel Codex & Claude agents. Isolated worktrees +
-    file locks + PR-only merges. Auto-wires Oh My Codex, Oh My Claude,
-    OpenSpec, and Caveman.
+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.
+```
 
 
 <!-- ===================================================================== -->

@@ -0,0 +1 @@
+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.
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-21
@@ -0,0 +1,5 @@
+# T1 Notes
+
+- Handoff: own `README.md`, `about_description.txt`, `docs/images/problem-agent-collision.svg`, and this change note.
+- Replace the README About-options dump with one canonical `about_description.txt` source and a short README section that points to it.
+- Move the collision visual under `## The problem`, move the solution copy under `### Solution`, and add the existing branch-start visual under the solution heading.
@@ -0,0 +1,15 @@
+## Why
+
+- The README currently mixes three alternative GitHub About descriptions into the product narrative, which adds noise near the top of the page.
+- The user requested a single canonical `about_description` source and a clearer visual split between the problem statement and the solution.
+
+## What Changes
+
+- Add a root `about_description.txt` file with the canonical GitHub About copy and point the README at it.
+- Move the collision visual under `## The problem` and place the existing branch-start workflow image under `### Solution`.
+- Replace the README option dump with a short "GitHub About description" section that mirrors the canonical copy.
+
+## Impact
+
+- Affected surfaces: top-level `README.md`, one new docs image, one new root copy file, and the matching OpenSpec change record.
+- Risk is low and limited to docs/rendered README structure.
@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: README problem and solution sections use separate visuals
+The README SHALL place the multi-agent collision visual directly under `## The problem` and SHALL place a Guardex solution visual directly under `### Solution`.
+
+#### Scenario: problem visual appears before the collision narrative
+- **WHEN** a reader opens the top-level README
+- **THEN** the `## The problem` heading is followed by the collision visual
+- **AND** the narrative about parallel agents overwriting each other appears below that visual.
+
+#### Scenario: solution visual appears under the solution heading
+- **WHEN** a reader reaches the `### Solution` section
+- **THEN** the README shows a Guardex workflow image directly under that heading
+- **AND** the solution copy appears below the image.
+
+### 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 SHALL reference that file instead of listing multiple About-copy options.
+
+#### Scenario: canonical About copy is linked from the README
+- **WHEN** a reader opens the `## GitHub About description` section
+- **THEN** the README links to `about_description.txt`
+- **AND** the section mirrors the same canonical copy in a copyable text block.
@@ -0,0 +1,19 @@
+## 1. Specification
+
+- [x] 1.1 Capture the README/about-copy scope in proposal + spec artifacts.
+
+## 2. Implementation
+
+- [x] 2.1 Add the canonical `about_description.txt` source file.
+- [x] 2.2 Update `README.md` so `The problem` and `Solution` each have the intended visual placement.
+- [x] 2.3 Add the static collision visual used by `The problem`.
+
+## 3. Verification
+
+- [x] 3.1 Run `git diff --check`.
+- [x] 3.2 Run `openspec validate agent-codex-readme-about-description-2026-04-21-18-05 --type change --strict`.
+- [x] 3.3 Run `openspec validate --specs`.
+
+## 4. Cleanup
+
+- [ ] 4.1 Branch is ready for `agent-branch-finish --via-pr --wait-for-merge --cleanup` with PR URL + `MERGED` evidence recorded.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		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.