docs(readme): add detailed explanations to quickstart section

[austinloveless-liatrio]

Why?

The TL/DR quickstart section lacked sufficient detail for new users to understand what the uvx command does and what the workflow files are at a high level. This made it difficult for readers to quickly grasp the purpose and mechanics of the spec-driven workflow.

What Changed?

• Added "What is this?" section explaining that prompts are structured Markdown playbooks
• Restructured installation options into clear Option A (slash commands) and Option B (manual)
• Added detailed breakdown of what the uvx command does (explains uvx is like npx for Python, details each command component)
• Expanded the 4-step workflow section with three subsections per step:
  • What it does - High-level purpose
  • Output - Specific files created with descriptions
  • Why - The value/reason for this step
• Made the quickstart more beginner-friendly with context about both mechanics and purpose

Additional Notes

This improves onboarding experience for new users who were confused by the original quickstart format.

• Linked relevant spec/task IDs (e.g., tasks/0002-spec-open-source-ready.md) - N/A, documentation improvement
• Ran tests: uv run pytest
• Ran linters/hooks: uv run pre-commit run --all-files
• Updated docs or prompts if behavior changed

Summary by CodeRabbit

• Documentation
  • Redesigned README with expanded introduction and multi-option installation flow
  • Added detailed 4-Stage workflow guide with explicit steps, tasks, and expected artifacts
  • Introduced security-focused section and enhanced usage guidance for clarity

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

[coderabbitai]

Walkthrough

The README.md file is comprehensively restructured to shift from a brief TLDR to a detailed workflow guide. It now includes expanded installation options (Slash Commands and Manual Copy-Paste), a new 4-Step Workflow section with explicit stages, detailed prompts and expected artifacts, and security-focused content.

Changes

Cohort / File(s)	Summary
Documentation restructure README.md	Replaces abbreviated quickstart with comprehensive introduction; adds multi-option installation flow (Option A: Slash Commands, Option B: Manual Copy-Paste); introduces structured 4-Step Workflow with Stages 1–4, including prompts, outputs, artifact paths, and verification criteria; adds security section and expanded usage notes; maintains core references and licensing.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

• Single file scope — only README.md is modified, reducing fragmentation
• Homogeneous changes — consistent pattern of reorganization and expansion across the document
• Documentation focus — requires understanding of workflow logic but no code logic review
• Verification points: Ensure artifact paths and stage names are consistent with any related code or prompt files; confirm the 4-Step Workflow accurately reflects the intended process; validate that installation instructions are clear and complete.

Possibly related PRs

• docs: enhance README structure and add workflow improvements #16 — Related README.md restructure that similarly converts the intro and workflow documentation to a prompt/workflow-focused format
• refactor(prompts): improve spec generation workflow and task list formatting #30 — Implements the prompt refactor (generate-spec, task-list, validate-spec) and spec directory conventions that directly align with the updated artifact paths and terminology in this README rewrite

Suggested reviewers

• RobertKelly

Poem

🐰 A README once brief, now grows with grace,
Four workflow stages find their place,
With prompts and paths and proofs so clear,
The workflow's vision now appears!
Hopping forward with structure and care. ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change—adding detailed explanations to the quickstart section of the README, matching the file modifications and PR objectives.
Description check	✅ Passed	The description covers all required sections (Why, What Changed) with clear details, though test/lint checkboxes remain unchecked and some optional items are marked N/A.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch onboarding-readme-details

Tip

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
4. 📊 Contributor Summary — Include a Markdown table showing contributions:
   | Contributor | Lines Added | Lines Removed | Files Changed |
5. ✔️ Additional Notes — Add any extra reviewer context.
   Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

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

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

README.md (2)

274-274: Create the missing docs/mcp-prompt-support.md file or update the broken link reference on line 274.

Line 274 in README.md references ./docs/mcp-prompt-support.md, but this file does not exist in the repository. This will result in a broken link for users trying to access MCP prompt support details. Either:

• Create the missing docs/mcp-prompt-support.md documentation file, or
• Update the link on line 274 to point to an existing resource

The GitHub Pages documentation links on lines 109–116 are properly formatted and accessible.

---

278-280: Path inconsistency confirmed: line 278 contradicts documented spec artifact location

Line 278 directs users to output specs to tasks/, but lines 56, 129, 234, and 244 consistently document the actual spec artifact location as docs/specs/[NN]-spec-[feature-name]/. This inconsistency will misdirect users during their first workflow run.

Apply this diff to align line 278 with the documented spec artifact directory:

-1. Open `prompts/generate-spec.md` inside your AI assistant and follow the instructions to produce a new spec in `tasks/`.
+1. Open `prompts/generate-spec.md` inside your AI assistant and follow the instructions to produce a new spec in `docs/specs/[NN]-spec-[feature-name]/`.

🧹 Nitpick comments (1)

README.md (1)

122-159: Recommended: Consider consolidating overlapping workflow guidance

The Quickstart section (lines 54–73) and the detailed "Workflow Overview" section (lines 122–159) cover similar ground. While the Overview provides valuable depth for power users, newer users might benefit from a cross-reference ("For more details, see Workflow Overview below") to reduce cognitive load and signpost the progressive disclosure pattern you've intentionally created.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9ead128 and f5b0e8e.

📒 Files selected for processing (1)

• README.md (2 hunks)

🔇 Additional comments (3)

README.md (3)

19-48: Well-structured expansion of installation guidance

The addition of the "What is this?" section and bifurcated installation options (Slash Commands vs. Manual Copy-Paste) significantly improves onboarding clarity. The comparison of uvx to npx is a helpful mental model for Python-unfamiliar users, and the step-by-step breakdown of what the command does (lines 37–44) removes guesswork.

---

50-73: Clear workflow structure with consistent artifact documentation

The 4-Step Workflow section is well-organized, each stage now includes explicit "What it does," "Output," and "Why" subsections. File paths use the [NN] and [TT] placeholder convention consistently with downstream sections. The progression from Spec → Task List → Manage Tasks → Validate Implementation is logical and easy to follow.

---

282-293: Strong addition: Security best practices for proof artifacts

The new Security Best Practices section is well-timed and practical. Recommending gitleaks and similar tooling as preventive guards is sound, and the emphasis on developer responsibility before commits sets the right tone.

[RobertKelly]

I would like the "feature idea" to be external in a feature/story etc. and this to be the next level down. Maybe that's in the details....

[austinloveless-liatrio]

updated