Skip to content

Commit 495c867

Browse files
NagyViktNagyVikt
NagyVikt
and
NagyVikt
authored
Bring the README docs in line with current Guardex behavior (#246)
The docs still showed the older AGENTS marker explanation and an outdated gx status illustration, so the README was refreshed to match the current CLI surface and the managed-block guidance the user asked to add. This keeps the changes confined to documentation: one richer README section, one updated terminal SVG, and the matching T1 note for the branch. Constraint: Keep the change docs-only and preserve the user-provided README wording for the AGENTS.md/CLAUDE.md section Rejected: Add the new AGENTS guidance as a second duplicate section | would leave conflicting docs in the same README Confidence: high Scope-risk: narrow Reversibility: clean Directive: Update the terminal-status SVG whenever gx command/service output materially changes so README screenshots do not drift Tested: git diff --check; rendered docs/images/workflow-gx-terminal-status.svg to /tmp/workflow-gx-terminal-status.png for visual review Not-tested: npm test (skipped because this is a docs/SVG-only change and the suite previously hung in test/install.test.js) Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>
1 parent 75aae91 commit 495c867

4 files changed

Lines changed: 138 additions & 72 deletions

File tree

‎README.md‎

Lines changed: 62 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -74,60 +74,84 @@ That's it. Setup installs hooks, scripts, templates, and scaffolds OpenSpec/cave
7474

7575
---
7676

77-
## AGENTS.md and CLAUDE.md behavior
77+
## How `AGENTS.md` and `CLAUDE.md` are handled
7878

79-
GitGuardex does **not** clear repo-owned guidance just because it needs to install its own contract.
79+
> [!IMPORTANT]
80+
> **GitGuardex never overwrites your guidance.** Only the content between these markers is managed:
81+
>
82+
> ```text
83+
> <!-- multiagent-safety:START -->
84+
> ... managed content ...
85+
> <!-- multiagent-safety:END -->
86+
> ```
87+
>
88+
> Everything outside that block is preserved byte-for-byte.
8089
81-
- `AGENTS.md` is managed by marker block. `gx setup` and `gx doctor` only refresh the `<!-- multiagent-safety:START --> ... <!-- multiagent-safety:END -->` section.
82-
- Text before or after that marker block stays yours.
83-
- If `AGENTS.md` exists but has no Guardex markers yet, GitGuardex appends its contract to the end instead of replacing the file.
84-
- If `AGENTS.md` does not exist, GitGuardex creates it.
85-
- Root `CLAUDE.md` is **not** separately rewritten by setup/doctor. If your repo keeps a separate `CLAUDE.md`, GitGuardex leaves it alone. In this repo `CLAUDE.md` is a symlink to `AGENTS.md`, so Claude reads the same contract. GitGuardex also installs `.claude/commands/gitguardex.md` for Claude command guidance.
90+
### Behavior at a glance
8691
87-
```mermaid
88-
flowchart TD
89-
A[Existing AGENTS.md] --> B{Guardex markers already present?}
90-
B -->|Yes| C[Refresh only the managed block]
91-
B -->|No| D[Append managed block to the end]
92-
E[No AGENTS.md yet] --> F[Create AGENTS.md with managed block]
93-
C --> G[Keep repo-owned text before and after]
94-
D --> G
95-
```
92+
<div align="center">
9693
97-
Before / after:
94+
| Your repo has&hellip; | `gx setup` / `gx doctor` does&hellip; |
95+
| :--- | :--- |
96+
| `AGENTS.md` **with** markers | Refreshes **only** the managed block |
97+
| `AGENTS.md` **without** markers | Appends the managed block to the end |
98+
| No `AGENTS.md` | Creates it with the managed block |
99+
| A root `CLAUDE.md` | Leaves it alone |
98100
99-
```md
100-
# AGENTS
101+
</div>
101102
102-
Project-specific guidance before managed block.
103+
> [!NOTE]
104+
> In this repo, `CLAUDE.md` is a symlink to `AGENTS.md`, so Claude reads the same contract. Claude-specific command guidance is installed separately at `.claude/commands/gitguardex.md`.
103105
104-
<!-- multiagent-safety:START -->
105-
- old managed contract
106-
<!-- multiagent-safety:END -->
106+
### Decision flow
107107
108-
Trailing repo notes after managed block.
109-
```
110-
111-
```md
112-
# AGENTS
108+
```mermaid
109+
flowchart TD
110+
Start([gx setup / gx doctor])
111+
Check{AGENTS.md<br/>exists?}
112+
Markers{Markers<br/>present?}
113+
Create[Create AGENTS.md<br/>with managed block]
114+
Refresh[Refresh the<br/>managed block]
115+
Append[Append managed block<br/>to end of file]
116+
Done([Repo-owned text preserved])
113117
114-
Project-specific guidance before managed block.
118+
Start --> Check
119+
Check -- No --> Create
120+
Check -- Yes --> Markers
121+
Markers -- Yes --> Refresh
122+
Markers -- No --> Append
123+
Create --> Done
124+
Refresh --> Done
125+
Append --> Done
115126
116-
<!-- multiagent-safety:START -->
117-
- current GitGuardex-managed contract
118-
<!-- multiagent-safety:END -->
127+
classDef entry fill:#0b76c5,stroke:#60a5fa,stroke-width:2px,color:#fff
128+
classDef decide fill:#78350f,stroke:#fbbf24,stroke-width:2px,color:#fff
129+
classDef action fill:#374151,stroke:#94a3b8,stroke-width:1.5px,color:#f1f5f9
130+
classDef finish fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#fff
119131
120-
Trailing repo notes after managed block.
132+
class Start entry
133+
class Check,Markers decide
134+
class Create,Refresh,Append action
135+
class Done finish
121136
```
122137
123-
Visual model:
138+
### What actually changes
124139

125-
```text
126-
CLAUDE.md -> AGENTS.md
127-
├─ repo-owned text stays
128-
└─ Guardex refreshes only the marker block
140+
```diff
141+
# AGENTS
142+
143+
Project-specific guidance before managed block.
144+
145+
<!-- multiagent-safety:START -->
146+
- - old managed contract
147+
+ - current GitGuardex-managed contract
148+
<!-- multiagent-safety:END -->
149+
150+
Trailing repo notes after managed block.
129151
```
130152

153+
Only lines **inside** the marker block change. Everything above and below is preserved exactly.
154+
131155
---
132156

133157
## What `gx` shows first

‎docs/images/workflow-gx-terminal-status.svg‎

Lines changed: 69 additions & 34 deletions
Loading

‎openspec/changes/agent-codex-refresh-gx-status-svg-2026-04-21-16-31/.openspec.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
schema: spec-driven
2+
created: 2026-04-21

‎openspec/changes/agent-codex-refresh-gx-status-svg-2026-04-21-16-31/notes.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# T1 Notes
2+
3+
- Refresh `docs/images/workflow-gx-terminal-status.svg` so the README terminal snapshot matches the current `gx` output.
4+
- Replace the README `AGENTS.md` / `CLAUDE.md` handling section with the fuller marker-preservation table, note, flowchart, and diff.
5+
- Keep the docs change scoped to the SVG, README section, and matching T1 note only.

0 commit comments

Comments
 (0)