docs(ai): condense AI instruction files, remove duplication

[PierreBrisorgueil]

Summary

• What changed: Removed duplicated content across CLAUDE.md, copilot-instructions.md, AGENTS.md, stack-maintainer.md, and README.md
• Why: ~60% of content was duplicated between files — commands appeared in 3 places, architecture rules in 4. Each file now owns only its tool-specific content.
• Related issues: Closes docs(ai): condense AI instruction files, remove duplication #3164

Scope

• Module(s) impacted: none (docs only)
• Cross-module impact: none
• Risk level: low

Validation

• npm run lint
• npm test
• Manual checks done (if applicable)

Guardrails check

• No secrets or credentials introduced (.env*, secrets/**, keys, tokens)
• No risky rename/move of core stack paths
• Changes remain merge-friendly for downstream projects
• Tests added or updated when behavior changed

Optional: Infra/Stack alignment details

Delete this section if not applicable.

Before vs After (key changes only)

Area	Before	After	Notes
CLAUDE.md	91 lines	~60 lines	Commands → package.json, merge workflow → README
copilot-instructions.md	68 lines	~56 lines	Commands → package.json, stays self-contained
AGENTS.md	35 lines	~22 lines	Preflight + review convention removed (→ CLAUDE.md)
stack-maintainer.md	51 lines	~42 lines	Example review section removed
README.md	196 lines	~182 lines	Skills table condensed, duplicate arch rules removed

Notes for reviewers

• Security considerations: none — docs only
• Mergeability considerations: low risk, all changed files are docs/config for AI tooling
• Follow-up tasks: apply same condensation to Vue repo

Summary by CodeRabbit

• Chores
  • Consolidated documentation by removing example/redundant guidance and simplifying command lists into single-script references.
  • Removed several legacy guidance sections (preflight, review conventions, layered rules) to reduce verbosity.
  • Condensed per-skill listings into a single reference line and added a caution note advising manual conflict resolution during merges.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c54fcca and 6f1c83b.

📒 Files selected for processing (1)

• README.md

🚧 Files skipped from review as they are similar to previous changes (1)

• README.md

---

📝 Walkthrough

Walkthrough

Removed duplicated, example, and explicit command content across AI-instruction docs; replaced command lists with references to package.json/other single sources and removed select guidance sections and an example review block. No functional code changes.

Changes

Cohort / File(s)	Summary
Documentation: command references CLAUDE.md, .github/copilot-instructions.md, README.md	Replaced explicit canonical command lists/tables with single-line references to package.json scripts or .claude/skills/; removed concrete merge/command examples.
Agent & reviewer guidance cleanup AGENTS.md, .claude/agents/stack-maintainer.md	Removed Preflight section, Review output convention, and the Example review code block; trimmed redundant guidance and verbosity.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• chore(claude): rename pr skill to pull-request and fix automation gaps #3160 — touches the same documentation areas (CLAUDE.md, AGENTS.md, copilot instructions) and likely targets the same duplication/condensing effort.

Suggested labels

Refactor

Poem

🐰 I nibbled through docs at dawn,

clipped examples, trimmed the brawn.
One script to rule the scattered land,
neat paths now point with gentle hand.
Hooray — the rabbit’s tidy plan!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: condensing AI instruction files and removing duplication across documentation.
Description check	✅ Passed	The description follows the template structure with all required sections completed: summary, scope, validation, guardrails check, before/after table, and reviewer notes.
Linked Issues check	✅ Passed	All objectives from issue #3164 are met: duplicated content removed from documentation, canonical commands consolidated to package.json, each file contains only tool-specific content, and shared rules consolidated.
Out of Scope Changes check	✅ Passed	All changes are in-scope documentation consolidation targeting duplication removal. The conflict caution note in README aligns with the documented restructuring objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/condense-ai-instruction-files

---

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.86%. Comparing base (762c79a) to head (6f1c83b).
⚠️ Report is 3 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #3165   +/-   ##
=======================================
  Coverage   89.86%   89.86%           
=======================================
  Files          52       52           
  Lines        1164     1164           
  Branches      234      234           
=======================================
  Hits         1046     1046           
  Misses        107      107           
  Partials       11       11           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

Reduces duplication across AI-related documentation by centralizing canonical commands in package.json and consolidating shared guidance, leaving each instruction file focused on tool-specific content.

Changes:

• Replace duplicated “canonical commands” sections with pointers to package.json scripts.
• Condense AI setup docs by removing repeated skills/architecture content and linking to the relevant source files.
• Trim agent-focused docs (AGENTS + stack-maintainer) to avoid repeating preflight/review conventions.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
README.md	Condenses Claude skill listing / removes duplicated architecture rules, points to .claude/skills/.
CLAUDE.md	Removes duplicated command table and merge workflow snippet; points to package.json and README.
AGENTS.md	Removes duplicated preflight + review convention; delegates shared rules to CLAUDE.md.
.github/copilot-instructions.md	Replaces canonical command list with a pointer to package.json scripts.
.claude/agents/stack-maintainer.md	Removes example review block to reduce duplication.

[coderabbitai]

🧹 Nitpick comments (1)

CLAUDE.md (1)

59-61: Consider using a relative Markdown link for the cross-reference.

Plain prose works, but a relative link makes it clickable in rendered Markdown and more explicit for AI tools scanning the file.

🔗 Proposed improvement

-See README — stack merge workflow section.
+See [README — Stack Merge Workflow section](README.md#stack-merge-workflow).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@CLAUDE.md` around lines 59 - 61, Replace the plain cross-reference under the
"## Stack merge workflow" heading with a relative Markdown link to the README
section (e.g., change "See README — stack merge workflow section." to a
clickable relative link like "See README — [stack merge
workflow](README.md#stack-merge-workflow)"); update the link target to match the
README section slug for "Stack merge workflow" so it becomes clickable and
machine-friendly.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@CLAUDE.md`:
- Around line 59-61: Replace the plain cross-reference under the "## Stack merge
workflow" heading with a relative Markdown link to the README section (e.g.,
change "See README — stack merge workflow section." to a clickable relative link
like "See README — [stack merge workflow](README.md#stack-merge-workflow)");
update the link target to match the README section slug for "Stack merge
workflow" so it becomes clickable and machine-friendly.

---

ℹ️ Review info

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 762c79a and c54fcca.

📒 Files selected for processing (5)

• .claude/agents/stack-maintainer.md
• .github/copilot-instructions.md
• AGENTS.md
• CLAUDE.md
• README.md

💤 Files with no reviewable changes (2)

• .claude/agents/stack-maintainer.md
• AGENTS.md