From dc953b105e00a04ee9274d67df23dac445cf92ef Mon Sep 17 00:00:00 2001 From: NagyVikt Date: Tue, 21 Apr 2026 16:38:21 +0200 Subject: [PATCH] Bring the README docs in line with current Guardex behavior 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) --- README.md | 100 ++++++++++------- docs/images/workflow-gx-terminal-status.svg | 103 ++++++++++++------ .../.openspec.yaml | 2 + .../notes.md | 5 + 4 files changed, 138 insertions(+), 72 deletions(-) create mode 100644 openspec/changes/agent-codex-refresh-gx-status-svg-2026-04-21-16-31/.openspec.yaml create mode 100644 openspec/changes/agent-codex-refresh-gx-status-svg-2026-04-21-16-31/notes.md diff --git a/README.md b/README.md index 42e5a8c..94886ea 100644 --- a/README.md +++ b/README.md @@ -74,60 +74,84 @@ That's it. Setup installs hooks, scripts, templates, and scaffolds OpenSpec/cave --- -## AGENTS.md and CLAUDE.md behavior +## How `AGENTS.md` and `CLAUDE.md` are handled -GitGuardex does **not** clear repo-owned guidance just because it needs to install its own contract. +> [!IMPORTANT] +> **GitGuardex never overwrites your guidance.** Only the content between these markers is managed: +> +> ```text +> +> ... managed content ... +> +> ``` +> +> Everything outside that block is preserved byte-for-byte. -- `AGENTS.md` is managed by marker block. `gx setup` and `gx doctor` only refresh the ` ... ` section. -- Text before or after that marker block stays yours. -- If `AGENTS.md` exists but has no Guardex markers yet, GitGuardex appends its contract to the end instead of replacing the file. -- If `AGENTS.md` does not exist, GitGuardex creates it. -- 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. +### Behavior at a glance -```mermaid -flowchart TD - A[Existing AGENTS.md] --> B{Guardex markers already present?} - B -->|Yes| C[Refresh only the managed block] - B -->|No| D[Append managed block to the end] - E[No AGENTS.md yet] --> F[Create AGENTS.md with managed block] - C --> G[Keep repo-owned text before and after] - D --> G -``` +
-Before / after: +| Your repo has… | `gx setup` / `gx doctor` does… | +| :--- | :--- | +| `AGENTS.md` **with** markers | Refreshes **only** the managed block | +| `AGENTS.md` **without** markers | Appends the managed block to the end | +| No `AGENTS.md` | Creates it with the managed block | +| A root `CLAUDE.md` | Leaves it alone | -```md -# AGENTS +
-Project-specific guidance before managed block. +> [!NOTE] +> 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`. - -- old managed contract - +### Decision flow -Trailing repo notes after managed block. -``` - -```md -# AGENTS +```mermaid +flowchart TD + Start([gx setup / gx doctor]) + Check{AGENTS.md
exists?} + Markers{Markers
present?} + Create[Create AGENTS.md
with managed block] + Refresh[Refresh the
managed block] + Append[Append managed block
to end of file] + Done([Repo-owned text preserved]) -Project-specific guidance before managed block. + Start --> Check + Check -- No --> Create + Check -- Yes --> Markers + Markers -- Yes --> Refresh + Markers -- No --> Append + Create --> Done + Refresh --> Done + Append --> Done - -- current GitGuardex-managed contract - + classDef entry fill:#0b76c5,stroke:#60a5fa,stroke-width:2px,color:#fff + classDef decide fill:#78350f,stroke:#fbbf24,stroke-width:2px,color:#fff + classDef action fill:#374151,stroke:#94a3b8,stroke-width:1.5px,color:#f1f5f9 + classDef finish fill:#064e3b,stroke:#34d399,stroke-width:2px,color:#fff -Trailing repo notes after managed block. + class Start entry + class Check,Markers decide + class Create,Refresh,Append action + class Done finish ``` -Visual model: +### What actually changes -```text -CLAUDE.md -> AGENTS.md - ├─ repo-owned text stays - └─ Guardex refreshes only the marker block +```diff + # AGENTS + + Project-specific guidance before managed block. + + +- - old managed contract ++ - current GitGuardex-managed contract + + + Trailing repo notes after managed block. ``` +Only lines **inside** the marker block change. Everything above and below is preserved exactly. + --- ## What `gx` shows first diff --git a/docs/images/workflow-gx-terminal-status.svg b/docs/images/workflow-gx-terminal-status.svg index f1a0e3f..b49eac7 100644 --- a/docs/images/workflow-gx-terminal-status.svg +++ b/docs/images/workflow-gx-terminal-status.svg @@ -1,45 +1,80 @@ - + GitGuardex terminal status output - A terminal screenshot style illustration showing the gx status help screen with active services, repo path, branch, commands, and doctor hint. + A terminal screenshot style illustration showing the updated gx help screen with active services, repo path, branch, merge and release commands, agent bot controls, repo toggle guidance, and the doctor hint. - - + + - - - deadpool@recodee:~/Documents/recodee$ gx - + + deadpool@recodee:~/ + Documents/recodee + $ gx - - [gitguardex] CLI: @imdeadpool/guardex/7.0.10 linux-x64 node-v22.22.0 - [gitguardex] Global services: - - ● oh-my-codex: active - - ● oh-my-claude-sisyphus: active - - ● @fission-ai/openspec: active - - ● cavemem: active - - ● @imdeadpool/codex-account-switcher: active - - ● GitHub (gh): active - [gitguardex] Repo safety service: ● active. - [gitguardex] Repo: /home/deadpool/Documents/recodee - [gitguardex] Branch: dev - gitguardex-tools logs: - - └─ USAGE - $ gx <command> [options] - └─ COMMANDS - status Show GitGuardex CLI + service health without modifying files - setup Install, repair, and verify guardrails (flags: --repair, --install-only, --target) - doctor Repair drift + verify (auto-sandboxes on protected main) - protect Manage protected branches (list/add/remove/set/reset) - sync Sync agent branches with origin/<base> - finish Commit + PR + merge completed agent branches (--all, --branch) - cleanup Prune merged/stale agent branches and worktrees - prompt Print AI setup checklist (--exec, --snippet) - Try 'gitguardex doctor' for one-step repair + verification. + + [gitguardex] CLI: @imdeadpool/guardex/7.0.16 linux-x64 node-v22.22.0 + [gitguardex] Global services: + + - + + oh-my-codex: active + - + + oh-my-claudecode: active + - + + @fission-ai/openspec: active + - + + cavemem: active + - + + @imdeadpool/codex-account-switcher: active + - + + cavekit: active + - + + caveman: active + - + + GitHub (gh): active + + [gitguardex] Repo safety service: + + active. + [gitguardex] Repo: /home/deadpool/Documents/recodee + [gitguardex] Branch: dev + gitguardex-tools logs: + + └─ USAGE + $ gx <command> [options] + + └─ COMMANDS + status Show GitGuardex CLI + service health without modifying files + setup Install, repair, and verify guardrails (flags: --repair, --install-only, --target) + doctor Repair drift + verify (auto-sandboxes on protected main) + protect Manage protected branches (list/add/remove/set/reset) + merge Create/reuse an integration lane and merge overlapping agent branches + sync Sync agent branches with origin/<base> + finish Commit + PR + merge completed agent branches (--all, --branch) + cleanup Prune merged/stale agent branches and worktrees + release Create or update the current GitHub release with README-generated notes + agents Start/stop repo-scoped review + cleanup bots + prompt Print AI setup checklist (--exec, --snippet) + report Security/safety reports (e.g. OpenSSF scorecard) + help Show this help output + version Print Guardex version + + └─ AGENT BOT + agents Start/stop review + cleanup bots for this repo + + └─ REPO TOGGLE + Set repo-root .env: GUARDEX_ON=0 disables Guardex, GUARDEX_ON=1 enables it again + └─ Try 'gitguardex doctor' for one-step repair + verification. diff --git a/openspec/changes/agent-codex-refresh-gx-status-svg-2026-04-21-16-31/.openspec.yaml b/openspec/changes/agent-codex-refresh-gx-status-svg-2026-04-21-16-31/.openspec.yaml new file mode 100644 index 0000000..4b8c565 --- /dev/null +++ b/openspec/changes/agent-codex-refresh-gx-status-svg-2026-04-21-16-31/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-04-21 diff --git a/openspec/changes/agent-codex-refresh-gx-status-svg-2026-04-21-16-31/notes.md b/openspec/changes/agent-codex-refresh-gx-status-svg-2026-04-21-16-31/notes.md new file mode 100644 index 0000000..714049d --- /dev/null +++ b/openspec/changes/agent-codex-refresh-gx-status-svg-2026-04-21-16-31/notes.md @@ -0,0 +1,5 @@ +# T1 Notes + +- Refresh `docs/images/workflow-gx-terminal-status.svg` so the README terminal snapshot matches the current `gx` output. +- Replace the README `AGENTS.md` / `CLAUDE.md` handling section with the fuller marker-preservation table, note, flowchart, and diff. +- Keep the docs change scoped to the SVG, README section, and matching T1 note only.