Add Agent Playbook section for automated updates

[stefanvacareanu7]

Summary

• Adds a "Agent Playbook: Updating This Repository End-to-End" section to README.md, documenting how an AI agent (or human) should perform a version bump / update of this repo end-to-end: what this repo is, where versions are pinned (.tool_version, Dockerfile OPENGREP_VERSION ARG, opengrep-rules commit pin in internal/docgen/parsing.go), the step-by-step update/test/CI-verification procedure, common failure modes, and a definition-of-done checklist.
• Documentation only — no functional changes. Only README.md was touched.

Test plan

• Verified section renders correctly as Markdown (table pipes escaped).
• N/A for code/build since this is a README-only change.

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

AI Reviewer: first review requested successfully. AI can make mistakes. Always validate suggestions.

_{TIP This summary will be updated as you push new changes.}

[codacy-production]

Pull Request Overview

The PR introduces a comprehensive 'Agent Playbook' to the README.md, successfully covering the required versioning locations, procedures, and failure modes. However, there are critical inconsistencies in the documented build commands that will likely lead to incorrect container builds. Specifically, the build argument used in the examples does not match the argument name or format required by the Dockerfile as specified in the playbook's own reference table.

Additionally, while the playbook provides a useful end-to-end guide, it creates significant redundancy by duplicating existing 'Usage' and 'Test' sections. These should be consolidated to maintain a single source of truth and prevent future documentation rot.

About this PR

• The addition of the 'Agent Playbook' creates multiple sources of truth for core procedures like building, testing, and generating documentation. To ensure long-term maintainability, these should be unified rather than duplicated across the README.

Test suggestions

• Instructions for bumping .tool_version (no leading 'v') are present.
• Instructions for bumping Dockerfile OPENGREP_VERSION (leading 'v') are present.
• Instructions for updating the opengrep-rules commit pin in internal/docgen/parsing.go are present.
• Verification that docgen (go run ./cmd/docgen) and unit tests are included in the procedure.
• Inclusion of the 'Definition of Done' checklist.
• Verification that pipes within Markdown table cells are escaped (e.g., in unit test command).

_{TIP Improve review quality by adding custom instructions
TIP How was this review? Give us feedback}

[codacy-production]

_{🔴 HIGH RISK}

Critical inconsistency in build commands: The build command uses the argument TOOL_VERSION, but the versioning table (line 59) and failure mode documentation (line 81/87) specify that the Dockerfile requires OPENGREP_VERSION. Furthermore, the table states the version requires a leading v (e.g., v1.24.0), which $(cat .tool_version) lacks. This will likely cause the image build to fail or use a stale binary.

Try running the following prompt in your coding agent:

Verify if the Dockerfile uses TOOL_VERSION or OPENGREP_VERSION. Update the build commands in README.md (lines 13, 70, and 91) to use the correct argument name and ensure the v prefix is included if required (e.g., --build-arg OPENGREP_VERSION=v$(cat .tool_version)).

[codacy-production]

_{🟡 MEDIUM RISK}

Suggestion: This new playbook section largely duplicates instructions found in the existing 'Usage', 'Generate Docs', and 'Test' sections (lines 8-36). To prevent documentation rot, consider consolidating these into the playbook or removing the redundant top-level headings.

Try running the following prompt:

Consolidate the 'Usage', 'Generate Docs', and 'Test' sections into the new 'Agent Playbook' to provide a single, comprehensive guide and remove the redundant headings.