Trim AGENTS.md to align with best practices (369 → 122 lines)

[adalton]

Summary

• Reduced AGENTS.md from 369 to 122 lines (68% reduction) to align with the wg-agentic-sdlc repo-scaffolding best practice recommending context files stay under 150 lines
• Removed sections that duplicated content already in each workflow's guidelines.md and skills/*.md (the AI execution chain)
• Relocated Claude Code installation internals to CONTRIBUTING.md (the only unique content that needed a new home)

Motivation

Cross-pollination analysis between wg-agentic-sdlc and this repo identified that our AGENTS.md exceeded the recommended 150-line limit (hard cap 300). ETH Zurich research shows agent adherence drops with context file length. Duplication analysis confirmed that Workflow-Specific Notes, Prerequisites, Artifact Management, and Common Commands were already documented in each workflow's own guidelines.md and skills/*.md files — the files AI agents actually read during execution.

What changed

Deleted (duplicated in workflow docs):

• Workflow-Specific Notes (~108 lines) — every note verified present in the relevant workflow's guidelines.md/skills/*.md
• Prerequisites per workflow (~17 lines) — each workflow's guidelines.md covers its dependencies
• Artifact Management per-workflow listing (~14 lines) — each workflow documents its own artifacts; convention kept as one-liner in Key Constraints
• Common Commands (~40 lines) — generic git/gh/jira/vale commands agents already know
• Verbose Shared Resources explanation (~31 lines) — replaced with tree + one-liners + recipe concept sentence

Relocated:

• Claude Code installation internals → new "Installation Internals" section in CONTRIBUTING.md

Added:

• One-sentence recipe concept explanation after the _shared/ tree
• Alphabetized workflow list
• README.md annotation in workflow structure tree: (prerequisites, artifacts, usage)

Validation

• Fresh-session test: an agent with only the trimmed AGENTS.md correctly navigated the repo, understood the recipe system, identified Jira-ingesting workflows, and followed path conventions
• Code review (2 iterations): reviewer verified no information loss by spot-checking 7 workflow READMEs against removed content

Test plan

• Run a workflow (e.g., bugfix /assess or code-review /start) against a target project to confirm the agent can still orient itself
• Run skill-reviewer /review against a workflow in this repo to confirm it can discover the architecture
• Verify CONTRIBUTING.md installation internals are findable by an agent modifying the installer

🤖 Generated with Claude Code

[coderabbitai]

Warning

Rate limit exceeded

@adalton has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 50 minutes and 23 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: dd23558b-4998-46fa-83e9-47e8b88d791a

📥 Commits

Reviewing files that changed from the base of the PR and between a7f19b2 and 1ef5ee0.

📒 Files selected for processing (3)

• .github/scripts/validate-structure.sh
• CONTRIBUTING.md
• ai-ready/README.md

Walkthrough

This PR updates workflow documentation standards and installation guidance. AGENTS.md is reorganized with reordered workflows, clarified directory structures, consolidated constraints, and refined production checklists. CONTRIBUTING.md adds installation internals explaining how install.sh discovers and wires workflows.

Changes

Workflow Documentation and Installation Guidance

Layer / File(s)	Summary
Workflow Structure and Inventory AGENTS.md	Current workflows list reordered with additions (design, e2e); directory structure clarified to show README.md as canonical component alongside SKILL.md and _shared/.
Key Constraints and Rules AGENTS.md	New consolidated "Key Constraints" section documents plain markdown-only content, relative-path requirements, SKILL.md disclosure limits, attended-mode behavior, artifact persistence location, and read-only review rules.
Shared Resources Definition AGENTS.md	"Shared Resources" section condensed with explicit pointers to _shared/review-protocol.md and self-review recipe via relative paths.
Production Path Confirmation AGENTS.md	"Path to Production" checklist refined with explicit PR/MR creation confirmation, restricted Jira writes to specific phases with approval requirement, and Vale validation for documentation changes.
Installation and Wiring Mechanics CONTRIBUTING.md	New "Installation Internals" section documents workflow discovery via */SKILL.md, CLAUDE.md reference appending/cleaning, symlink creation into ~/.claude/skills/, and uninstall behavior.

---

🎯 2 (Simple) | ⏱️ ~8 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: trimming AGENTS.md from 369 to 122 lines to align with best practices, which is the primary objective of the changeset.
Description check	✅ Passed	The description provides detailed explanation of the changes, motivation, what was deleted/relocated/added, validation performed, and test plan—all directly related to the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@AGENTS.md`:
- Around line 77-84: The CI’s AGENTS structure validator is failing because
AGENTS.md no longer includes the workflow-specific notes/artifact sections the
validator expects; update the validator (or reintroduce a minimal compatible
section) so it accepts the trimmed AGENTS contract — locate the validator script
(the AGENTS/lint step in your CI workflow) that enforces headings like "##
Installation" and "## Development" and change its rules to allow the new format
(or add a minimal "Workflows/Artifacts" compatibility block to AGENTS.md at the
same semantic location as the removed sections) so entries around the "##
Installation" and "## Development" headings pass CI.

In `@CONTRIBUTING.md`:
- Around line 90-92: Replace the home-absolute path "~/.claude/skills/" in the
second list item with a path-agnostic phrase (e.g., "global Claude skills
directory") and ensure the alternate project-level reference remains a relative
path (".claude/skills/"); update the sentence so it reads something like
"Symlinks workflows into the global Claude skills directory (or .claude/skills/
for project-level) for slash command discovery" and remove any other
home-absolute references to comply with the relative-path rule.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 53fd0541-8b01-467f-9a75-7bd424a0bb74

📥 Commits

Reviewing files that changed from the base of the PR and between a0c7166 and a7f19b2.

📒 Files selected for processing (2)

• AGENTS.md
• CONTRIBUTING.md

[amir-yogev-gh]

LGTM