#534 Split README into focused docs

[hubertgajewski]

Summary

Split the giant README into a concise human-first entry point plus focused docs under docs/.

• Added focused docs for configuration, Playwright, test inventory, CI, Bruno, AI assistant workflows, and project management.
• Updated CLAUDE.md, reviewer agents, and project skills so future AI-assisted changes update the focused owner docs instead of pushing detail back into README.
• Kept AI-useful operational details available in the new docs, including MCP servers, CI behavior, test/spec inventory, script summaries, project-board rules, and credential/variable references.

Closes #534

Test plan

• README reduced to a concise overview, quick start, contents, common commands, configuration/test summaries, repository structure, documentation map, and AI notes.
• Focused docs added under docs/ for every owner area requested in the issue.
• Agent-facing guidance updated in CLAUDE.md, .claude/agents/*, and .claude/skills/*.
• Local Markdown link checker: Checked 164 markdown files; all local links resolve.
• Targeted Prettier check for changed Markdown files.
• git diff --check HEAD~1..HEAD.
• deep-review-pro iteration 2: ready, zero blocking findings.
• CI checks pass on the PR.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR splits a 593-line README into focused human and agent reference documentation by creating eight new docs files, updating agent routing rules to recognize docs changes as out-of-scope, and redirecting skill/agent guidance to point to the new documentation homes instead of README.

Changes

Documentation Reorganization & Agent Reference Updates

Layer / File(s)	Summary
Documentation Index and Navigation docs/INDEX.md	New navigation table mapping user tasks to focused docs (configuration, Playwright, test inventory, CI, Bruno, AI assistants, project management) plus ownership rules clarifying which docs own which content areas.
Configuration & Infrastructure Docs docs/CONFIGURATION.md, docs/CI.md, docs/BRUNO.md	New docs for local setup prerequisites (.env/.vars keys, GitHub secrets), CI workflow behavior (triggers, runners, automation scripts, detailed Playwright pipeline, quality metrics, self-healing), and Bruno API collection setup (environments, request sequence, CLI/GitHub Actions integration).
Test Suite & Code Docs docs/PLAYWRIGHT.md, docs/TEST_INVENTORY.md	New docs for Playwright test architecture (setup, commands, tag scheme, directory structure, POM, fixtures, config defaults) and per-spec coverage inventory (smoke, public/authenticated/cross-cutting regression, unit tests, coverage-matrix).
Process & Workflow Docs docs/AI_ASSISTANTS.md, docs/PROJECT_MANAGEMENT.md	New docs for AI assistant workflows (skills location, agent roster, Claude-to-Codex mapping, Git worktree provisioning) and MCP servers (five declared servers with run/build paths, tools, and behavioral notes); project management scales (Fibonacci points, T-shirt sizes), epic/story labeling, and Actual hours semantics.
Agent Out-of-Scope Routing .claude/agents/deep-review-*.md	Six agent prompts (architecture, code, python, typescript, unit-test) updated to include "docs" in out-of-scope categories, broadening ownership from "README / CLAUDE.md" to "README / docs / CLAUDE.md". Deep-review-docs agent updated with new checklist verification rules pointing CI/env/coverage/MCP changes to docs/ owners instead of README.
Project Checklist Verification .claude/agents/deep-review-project-checklist.md	Test-tag, consistency, and CI workflow references updated from README.md to PLAYWRIGHT.md, TEST_INVENTORY.md, and CI_LOCAL.md.
Skill File Reference Updates .claude/skills/create-issue/SKILL.md, .claude/skills/generate-test/SKILL.md, .claude/skills/generate-stubs/SKILL.md, .claude/skills/fix-issue/SKILL.md, .claude/skills/deep-review-lite/SKILL.md, .claude/skills/deep-review-pro/SKILL.md	Skill instructions updated to reference new docs locations: create-issue→PROJECT_MANAGEMENT.md, generate-test→PLAYWRIGHT.md/TEST_INVENTORY.md, fix-issue→docs/ folder recognition + PROJECT_MANAGEMENT.md, generate-stubs/generate-test table formatting adjusted, deep-review-lite checklist references updated.
Behavioral Guidance & Documentation Map CLAUDE.md	Expanded "Keep README.md and docs/ up to date" section to specify which docs/ subfiles own which operational areas (CONFIGURATION, PLAYWRIGHT, TEST_INVENTORY, CI, BRUNO, AI_ASSISTANTS, PROJECT_MANAGEMENT); Project #1 board conventions redirected to PROJECT_MANAGEMENT.md; MCP servers section expanded to reference docs/AI_ASSISTANTS.md; documentation map pointer added to docs/INDEX.md.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• hubertgajewski/orwellstat#531: Updates to deep-review agent prompts (.claude/agents/) align with the same deep-review-docs ownership expansion and reference updates.
• hubertgajewski/orwellstat#511: Changes to .claude/ agent/skill files that reference documentation are affected by the docs reorganization and new reference paths.

Suggested reviewers

• claude

Poem

🐰 A Doc-Focused Harvest

The README grew quite tall and wide,
So focused docs we now provide—
Each agent knows which path to take,
While humans read what matters most.
Skills and checklists now consult
The docs that own each special cult. 📚✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title '#534 Split README into focused docs' accurately summarizes the main objective of creating focused documentation files and restructuring README.
Linked Issues check	✅ Passed	The PR successfully implements all major objectives from issue #534: README reduced to human-first entry point [#534], focused docs created for configuration/Playwright/tests/CI/Bruno/AI/project management [#534], agent guidance updated [#534], and documentation index/links verified [#534].
Out of Scope Changes check	✅ Passed	All changes remain within scope of issue #534: README restructuring, focused doc creation, agent/skill guidance updates, and documentation formatting. No unrelated changes detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/534

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

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

[coderabbitai]

🧹 Nitpick comments (1)

CLAUDE.md (1)

5-5: 💤 Low value

Minor: Consider removing blank line within blockquote.

The Markdownlint warning at line 6 indicates there's a blank line inside the blockquote that violates MD028. While this doesn't affect functionality, removing it would align with Markdown best practices.

📝 Proposed fix

Remove the blank line between the first and second sentences of the blockquote to satisfy MD028.

🤖 Prompt for 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.

In `@CLAUDE.md` at line 5, The blockquote in CLAUDE.md contains an internal blank
line that triggers MD028; remove the empty line inside the quoted paragraph so
the blockquote becomes a single continuous paragraph (update the quoted text
shown between the ">" markers in CLAUDE.md accordingly) to satisfy the
markdownlint rule.

🤖 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.

Nitpick comments:
In `@CLAUDE.md`:
- Line 5: The blockquote in CLAUDE.md contains an internal blank line that
triggers MD028; remove the empty line inside the quoted paragraph so the
blockquote becomes a single continuous paragraph (update the quoted text shown
between the ">" markers in CLAUDE.md accordingly) to satisfy the markdownlint
rule.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a6296e60-f176-41c1-9285-d81ba14f44cb

📥 Commits

Reviewing files that changed from the base of the PR and between ccd8af2 and 3d1bcb3.

📒 Files selected for processing (24)

• .claude/agents/deep-review-architecture.md
• .claude/agents/deep-review-code.md
• .claude/agents/deep-review-docs.md
• .claude/agents/deep-review-project-checklist.md
• .claude/agents/deep-review-python.md
• .claude/agents/deep-review-qa.md
• .claude/agents/deep-review-typescript.md
• .claude/agents/deep-review-unit-test.md
• .claude/skills/create-issue/SKILL.md
• .claude/skills/deep-review-lite/SKILL.md
• .claude/skills/deep-review-pro/SKILL.md
• .claude/skills/fix-issue/SKILL.md
• .claude/skills/generate-stubs/SKILL.md
• .claude/skills/generate-test/SKILL.md
• CLAUDE.md
• README.md
• docs/AI_ASSISTANTS.md
• docs/BRUNO.md
• docs/CI.md
• docs/CONFIGURATION.md
• docs/INDEX.md
• docs/PLAYWRIGHT.md
• docs/PROJECT_MANAGEMENT.md
• docs/TEST_INVENTORY.md