refactor: restructure AGENTS.md and apply prompting principles

[myakove]

Summary

Restructure the AGENTS.md / CLAUDE.md relationship and rewrite AGENTS.md applying prompting principles for better AI compliance.

Changes

Structural

• AGENTS.md is now the canonical file (was a symlink to CLAUDE.md)
• CLAUDE.md contains only @AGENTS.md (reference to canonical file)
• Heading updated from # CLAUDE.md to # AGENTS.md

Content Rewrite (724 → 220 lines, 70% reduction)

• Merged 6 anti-defensive programming sections into 1 with single ❌/✅ example
• Merged 5 PyGithub blocking sections into 1 with decision checklist
• Removed redundant Summary/Quick Reference (copy of earlier content)
• Removed Type Compatibility Pattern (duplicate PyGithub example)
• Demoted CRITICAL/MANDATORY overuse to factual statements
• One sentence per concept throughout

New Rule

• Added ## Generated Documentation — docs/ is autogenerated by docsfy, never edit manually

[myakove-bot]

Report bugs in Issues

Welcome! 🎉

This pull request will be automatically processed with the following features:

🔄 Automatic Actions

• Reviewer Assignment: Reviewers are automatically assigned based on the OWNERS file in the repository root
• Size Labeling: PR size labels (XS, S, M, L, XL, XXL) are automatically applied based on changes
• Issue Creation: Disabled for this repository
• Pre-commit Checks: pre-commit runs automatically if .pre-commit-config.yaml exists
• Branch Labeling: Branch-specific labels are applied to track the target branch
• Auto-verification: Auto-verified users have their PRs automatically marked as verified
• Labels: All label categories are enabled (default configuration)

📋 Available Commands

PR Status Management

• /wip - Mark PR as work in progress (adds WIP: prefix to title)
• /wip cancel - Remove work in progress status
• /hold - Block PR merging (approvers only)
• /hold cancel - Unblock PR merging
• /verified - Mark PR as verified
• /verified cancel - Remove verification status
• /reprocess - Trigger complete PR workflow reprocessing (useful if webhook failed or configuration changed)
• /regenerate-welcome - Regenerate this welcome message
• /security-override - Set security check runs to pass (maintainers only)
• /security-override cancel - Re-run security checks

Review & Approval

• /lgtm - Approve changes (looks good to me)
• /approve - Approve PR (approvers only)
• /automerge - Enable automatic merging when all requirements are met (maintainers and approvers only)
• /assign-reviewers - Assign reviewers based on OWNERS file
• /assign-reviewer @username - Assign specific reviewer
• /check-can-merge - Check if PR meets merge requirements

Testing & Validation

• /retest tox - Run Python test suite with tox
• /retest build-container - Rebuild and test container image
• /retest python-module-install - Test Python package installation
• /retest pre-commit - Run pre-commit hooks and checks
• /retest conventional-title - Validate commit message format
• /retest all - Run all available tests

Container Operations

• /build-and-push-container - Build and push container image (tagged with PR number)
  • Supports additional build arguments: /build-and-push-container --build-arg KEY=value

Cherry-pick Operations

• /cherry-pick <branch> - Schedule cherry-pick to target branch when PR is merged
  • Multiple branches: /cherry-pick branch1 branch2 branch3
• /cherry-pick-retry <branch> - Retry a failed cherry-pick (merged PRs only)

Branch Management

• /rebase - Rebase this PR branch onto its base branch

Label Management

• /<label-name> - Add a label to the PR
• /<label-name> cancel - Remove a label from the PR

✅ Merge Requirements

This PR will be automatically approved when the following conditions are met:

1. Approval: /approve from at least one approver
2. LGTM Count: Minimum 1 /lgtm from reviewers
3. Status Checks: All required status checks must pass
4. No Blockers: No wip, hold, has-conflicts labels and PR must be mergeable (no conflicts)
5. Verified: PR must be marked as verified

📊 Review Process

Approvers and Reviewers

Approvers:

• myakove
• rnetser

Reviewers:

• myakove
• rnetser

Available Labels

• hold
• verified
• wip
• lgtm
• approve
• automerge

AI Features

• Conventional Title: Mode: fix (claude/claude-opus-4-6-1m)
• Cherry-Pick Conflict Resolution: Enabled (claude/claude-opus-4-6-1m)
• Test Oracle: Triggers: approved (claude/claude-opus-4-6[1m]); /test-oracle can be used anytime

Security Checks

• Suspicious Path Detection: Monitors paths: .claude/, .vscode/, .cursor/, .devcontainer/, .pi/, .github/workflows/, .github/actions/
• Committer Identity Check: Verifies last committer matches PR author
• Mandatory: Security checks block merge (use /security-override to bypass — maintainers only)

💡 Tips

• WIP Status: Use /wip when your PR is not ready for review
• Verification: The verified label is removed on new commits unless the push is detected as a clean rebase
• Cherry-picking: Cherry-pick labels are processed when the PR is merged
• Container Builds: Container images are automatically tagged with the PR number
• Permission Levels: Some commands require approver permissions
• Auto-verified Users: Certain users have automatic verification and merge privileges

For more information, please refer to the project documentation or contact the maintainers.

[qodo-code-review]

PR Summary by Qodo

Docs: Make AGENTS.md canonical and simplify CLAUDE.md reference
📝 Documentation 🕐 20-40 Minutes

Description

• Make AGENTS.md canonical and reduce CLAUDE.md to a single reference.
• Rewrite AGENTS.md for clearer, non-redundant guidance and stronger AI compliance.
• Add rule: docs/ is docsfy-generated; regenerate instead of editing.

Diagram

graph TD
  CLAUDE["CLAUDE.md"] --> AGENTS["AGENTS.md (canonical)"]
  DOCSFY{{"docsfy"}} --> DOCS[/"docs/ (generated)"/]
  AGENTS -. "Do not edit" .-> DOCS
  subgraph Legend
    direction LR
    _file["Markdown file"] ~~~ _ext{{"Generator"}} ~~~ _dir[/"Generated dir"/]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep AGENTS.md as a symlink to CLAUDE.md

• ➕ Keeps one physical source of truth with no duplicated content
• ➕ Works with standard filesystem tooling and editors
• ➖ Less explicit in-repo about which file is canonical
• ➖ Symlinks can be awkward on some platforms and in some code-hosting views

2. Move canonical content into CLAUDE.md and have AGENTS.md reference it

• ➕ Avoids changing the historically larger/primary file name
• ➕ Still achieves single-source content
• ➖ Conflicts with the stated goal that AGENTS.md is canonical
• ➖ Keeps the naming mismatch for tools/users expecting AGENTS.md

3. Split AGENTS.md into smaller topic files and include them from CLAUDE.md/AGENTS.md

• ➕ More modular; easier to maintain discrete sections over time
• ➕ Can reduce merge conflicts for frequent edits
• ➖ More moving parts and navigation overhead
• ➖ Include mechanics may be tool-specific; can confuse contributors

Recommendation: The PR’s approach is the best fit: make AGENTS.md the canonical, human-readable source and reduce CLAUDE.md to a single explicit reference. This removes duplication/sync risk while keeping the entrypoint obvious for both humans and AI tooling. Symlinks were considered but are less portable and less explicit.

Files changed (2) +221 / -719

Documentation (2) +221 / -719

AGENTS.mdAdd canonical AGENTS.md with condensed, principle-driven guidance +220/-0

Add canonical AGENTS.md with condensed, principle-driven guidance

• Introduces AGENTS.md as the canonical agent/development guidance file with a major rewrite focused on concise, non-redundant rules and examples. Consolidates anti-defensive programming and PyGithub non-blocking guidance into single sections and adds a new rule that docs/ is generated by docsfy and must not be edited manually.

AGENTS.md

CLAUDE.mdReplace prior guidance with a single reference to AGENTS.md +1/-719

Replace prior guidance with a single reference to AGENTS.md

• Removes the previous long-form content and replaces it with a single @AGENTS.md reference, establishing AGENTS.md as the source of truth and eliminating duplicated guidance.

CLAUDE.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 30 rules

1. except Exception without re-raise ✓ Resolved 📘 Rule violation ≡ Correctness

Description

AGENTS.md includes an exception-handling example that catches broad Exception and does not
re-raise or log with traceback. This can encourage patterns that swallow programming errors and
violate the requirement to catch specific exception types (or, if broad catch is unavoidable, to
observe and re-raise).

Code

AGENTS.md[R128-133]

+try:
+    await clone_repo()
+    ctx.complete_step("clone_repository", commit_sha="abc123")
+except Exception as ex:
+    ctx.fail_step("clone_repository", exception=ex, traceback_str=traceback.format_exc())
+```

Relevance

⭐⭐⭐ High

Team often requires logging traceback + re-raise; accepted similar “don’t swallow Exception” changes
(PR #1000, #1114).

PR-#1000
PR-#1114

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 181390 requires avoiding broad except Exception in non-boundary code paths unless
it is narrowed or (if unavoidable) logged with traceback and re-raised/terminated. The example in
AGENTS.md catches Exception and only records it in ctx.fail_step(...) without re-raising or
any traceback logging.

Rule 181390: Catch specific exception types instead of broad Exception
AGENTS.md[128-133]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The documentation snippet shows `except Exception as ex:` without re-raising or logging traceback, which conflicts with the compliance rule requiring specific exception types (or, if broad catch is unavoidable, logging with full context and re-raising).

## Issue Context
This is in `AGENTS.md` under the “Structured Webhook Logging” example. Since AGENTS.md is canonical guidance, it should not teach patterns that swallow errors.

## Fix Focus Areas
- AGENTS.md[128-133]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. CodeRabbit guidelines path outdated ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

.coderabbit.yaml is configured to load code-guidelines from CLAUDE.md, but this PR replaces
CLAUDE.md with a one-line @AGENTS.md reference instead of the actual guidelines content. As a
result, CodeRabbit will not ingest the guidance now located in AGENTS.md, reducing/losing rule
enforcement in automated reviews.

Code

CLAUDE.md[1]

+@AGENTS.md

Relevance

⭐⭐⭐ High

.coderabbit.yaml explicitly loads guidelines from CLAUDE.md (added in PR #947); keeping it accurate
is enforced.

PR-#947

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The PR changes CLAUDE.md to only contain an indirection string, while CodeRabbit is still
explicitly configured to load guidelines from CLAUDE.md only, so the guidance in AGENTS.md will
not be picked up by that configuration.

CLAUDE.md[1-1]
.coderabbit.yaml[70-77]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
CodeRabbit is configured to read project code guidelines from `CLAUDE.md`, but `CLAUDE.md` no longer contains the guidelines after this PR (it only contains `@AGENTS.md`). This likely prevents CodeRabbit from ingesting the intended guidelines now stored in `AGENTS.md`.

## Issue Context
- `CLAUDE.md` has been reduced to a single-line indirection (`@AGENTS.md`).
- `.coderabbit.yaml` still declares `CLAUDE.md` as the only `knowledge_base.code_guidelines.filePatterns` entry.

## Fix Focus Areas
- Update CodeRabbit guideline file pattern:
 - .coderabbit.yaml[70-77]
- (Optional) If other tooling depends on `CLAUDE.md`, consider keeping `CLAUDE.md` as a real copy/symlink of `AGENTS.md` instead of indirection:
 - CLAUDE.md[1-1]

## Proposed fix
Change `.coderabbit.yaml` to point to `AGENTS.md` (or include both):
- Replace `filePatterns: ["CLAUDE.md"]` with `filePatterns: ["AGENTS.md"]`, or
- Use `filePatterns: ["AGENTS.md", "CLAUDE.md"]` if you want to support both names.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[myakove]

@qodo-code-review[bot]

The following review comments were reviewed and a decision was made:

AGENTS.md:128 (qodo rule violation) — except Exception without re-raise

Addressed: Fixed — added raise after ctx.fail_step() in the AGENTS.md example so exceptions propagate.

CLAUDE.md:1 (qodo bug) — CodeRabbit guidelines path outdated

Addressed: Fixed — updated .coderabbit.yaml to point filePatterns to AGENTS.md instead of CLAUDE.md.

[qodo-code-review]

code-review[bot]

The following review comments were reviewed and a decision was made:

AGENTS.md:128 (qodo rule violation) — except Exception without re-raise

Addressed: Fixed — added raise after ctx.fail_step() in the AGENTS.md example so exceptions propagate.

CLAUDE.md:1 (qodo bug) — CodeRabbit guidelines path outdated

Addressed: Fixed — updated .coderabbit.yaml to point filePatterns to AGENTS.md instead of CLAUDE.md.

Yes — both items are already addressed:

• finding 1 is implemented: the example now re-raises after ctx.fail_step().
• finding 2 is implemented: .coderabbit.yaml now points code guidelines to AGENTS.md.

So there are no remaining active Qodo findings on this PR.

[qodo-code-review]

Code review by qodo was updated up to the latest commit 34f5397

[myakove-bot]

New container for ghcr.io/myk-org/github-webhook-server:latest published