docs: update README

[Hurblat]

• Add problem/solution table upfront (why use this?)
• Reduce from 538 to 200 lines by removing redundancy
• Add 3-command quick start (marketplace standard)
• Add ASCII workflow diagram with human checkpoints
• Replace prose with scannable tables for commands, agents, issue tracking
• Remove duplicate file structure sections
• Remove stale command references (/security-review, /code-review)
• Fix JSON examples that had invalid # comments
• Separate user install from local development paths

Summary by CodeRabbit

• Documentation
  • Rewrote README into a plugin-centered Quick Start and modular workflow emphasizing marketplace integration and plugin structure
  • Added clear sections for Commands, Internal Commands, Agents, and public-facing command mappings
  • Introduced Issue Tracking integration, human approval checkpoints, and lifecycle visualization
  • Simplified prerequisites and local development guidance with concise local settings and onboarding for plugin authors
  • Documented generated artifacts, directory overview, and contribution/testing guidance

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

The README is fully rewritten to center the repository on a plugin-driven workflow, reorganizing into Quick Start, The Workflow, Commands, Internal Commands, Agents, Issue Tracking Integration, Plugin Structure, Generated Files, and Local Development with simplified configuration and onboarding.

Changes

Cohort / File(s)	Summary
Documentation restructure README.md	Complete rewrite reframing the repository around a plugin-centric workflow: new Quick Start, The Workflow visualization, Commands/Internal Commands, Agents table, Issue Tracking Integration, Plugin Structure, Generated Files, local development guidance, and simplified configuration examples.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 I nibble at lines and polish the thread,
I hop through plugins where bright ideas spread,
Diagrams and commands in tidy array,
Agents and issues now easy to play,
A README refreshed — hooray for the spread!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The PR title 'docs: update README' is vague and generic, failing to capture the substantial modernization effort described in the PR objectives.	Use a more specific title that reflects the key change, such as 'docs: modernize README to match 2025 plugin conventions' as mentioned in the PR summary, or 'docs: restructure README for plugin-centric workflow'.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
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 docstrings

---

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: 3

🤖 Fix all issues with AI agents

In `@README.md`:
- Around line 186-196: The markdown code block showing the plugin directory tree
in README.md triggers markdownlint MD040; update that fenced block to include a
language tag (for example "text") after the opening ``` so the tree is ```text
... ```; locate the tree block under the plugins/claude-constructor/ example in
README.md and add the language tag to the opening fence to satisfy MD040.
- Around line 121-130: The fenced code block in README.md (the generated-files
tree containing state_management/, specifications/, code_reviews/) lacks a
language tag which triggers markdownlint MD040; update the opening fence from
``` to ```text so the block becomes a text code block (keep the existing closing
fence), ensuring the tree block is explicitly marked as plain text.
- Around line 32-52: The fenced ASCII workflow block that begins with "PLANNING"
is missing a language tag and triggers markdownlint MD040; update the opening
fence for that code block (the triple backticks surrounding the box containing
"PLANNING" → "IMPLEMENTATION" → "REVIEW") to include a language tag such as text
(i.e., change ``` to ```text) so the block is properly annotated.