docs(readme): improve quick start guide and restructure documentation

[flora131]

Summary

Restructured the README to provide a more streamlined and user-friendly onboarding experience. The Quick Start Guide now follows a clear 4-step process with advanced options moved to collapsible sections.

Key Changes

• Reorganized Quick Start Guide: Converted "Set up Atomic" section into a numbered step-by-step guide (Steps 1-4)

  • Step 1: Install Atomic
  • Step 2: Initialize Your Project
  • Step 3: Generate Context Files
  • Step 4: Ship Features

• Simplified installation instructions: Made the default installation path more prominent and moved advanced options (specific versions, custom directories, source control selection) into collapsible <details> sections

• Integrated workflow into Quick Start: Removed redundant "The Workflow" section from TOC and integrated the research → spec → implement → PR workflow directly into Step 4

• Improved readability: Simplified language throughout, made instructions more action-oriented, and reduced cognitive load for new users

• Better information hierarchy: Moved less common options into collapsible sections so users can focus on the happy path first

Impact

New users can now get started with Atomic more quickly without being overwhelmed by edge cases and advanced options upfront.

[claude]

PR Review: Update README to be more user-friendly

Thanks for working on improving the documentation! Here's my review:

✅ What Works Well

1. Cleaner structure - Renaming "Set up Atomic" to "Quick Start Guide" and using numbered steps (Step 1-4) makes the onboarding flow much clearer for new users.

2. Collapsible sections - Using <details> tags for advanced installation options (specific version, custom directory, source control) keeps the main documentation clean while preserving the information for power users.

3. Consolidated workflow - Integrating "The Workflow" content into "Step 4: Ship Features" reduces redundancy and provides a more natural reading flow.

4. Streamlined prerequisites - Removing "Hardware: Minimal requirements" and "Network: Internet connection required" is appropriate - these add little value.

⚠️ Concerns

1. Removed bun installation method - The original README included:

   # Using bun
   bun add -g @bastani/atomic
   
   # Without installation (one-time use)
   bunx @bastani/atomic

   This was completely removed. Given this is a bun-based project (per CLAUDE.md), some users may prefer the bun installation method. Suggestion: Consider adding this back as another collapsible <details> section under "Advanced Installation" titled "Install via bun".

2. Lost context about init behavior - The original README explained:

   atomic init configures source-control-specific skills in your project (GitHub/Git or Sapling), while Atomic's baseline agents/skills are installed globally under ~/.atomic/.claude, ~/.atomic/.opencode, and ~/.atomic/.copilot during install/update

   This useful context about where skills are installed was removed. Consider keeping this explanation somewhere.

3. Unrelated bun.lock change - The PR removes "configVersion": 0, from bun.lock. While harmless, this appears unrelated to the README changes. Was this intentional, or was it picked up accidentally during a bun operation?

4. Empty PR description - Adding a description explaining the motivation and summarizing changes would help reviewers and serve as documentation for future reference.

📝 Minor Suggestions

• In the "Step 4: Ship Features" section, some code blocks use backticks without a language specifier (e.g., the /research-codebase commands). For consistency, consider using bash or leaving them unspecified consistently.

• Consider adding a brief note in Step 2 or 3 explaining that /init is different from atomic init - new users might get confused between the CLI command and the slash command.

Summary

Overall, this is a good improvement to the documentation structure. The main suggestion is to preserve the bun installation option (even if in a collapsible section) since it's a bun-based project and some users may prefer that installation method.

---

This review was generated by an automated code review system.

[Copilot]

Pull request overview

This PR restructures the README to improve the onboarding experience for new users. The Quick Start Guide has been reorganized into a clear 4-step process, with advanced installation options moved to collapsible sections. The previously separate "The Workflow" section has been integrated into Step 4, consolidating the documentation structure.

Changes:

• Reorganized Quick Start Guide into a numbered 4-step process (Install → Initialize → Generate Context → Ship Features)
• Simplified installation instructions by promoting the native installation method and moving advanced options (specific versions, custom directories, source control selection) into collapsible <details> sections
• Integrated the workflow (Research → Spec → Implement → Debug → PR) directly into Step 4, removing redundancy from the Table of Contents

Reviewed changes

Copilot reviewed 1 out of 2 changed files in this pull request and generated 2 comments.

File	Description
bun.lock	Automated lockfile update removing configVersion field
README.md	Complete restructuring of Quick Start Guide with improved information hierarchy and simplified onboarding flow

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The "Advanced Installation" section appears after "Step 4: Ship Features" which creates a confusing document structure. Since this section contains installation-related options (specific versions, custom directories, source control selection), it should be placed immediately after "Step 1: Install Atomic" (before Step 2). This would keep all installation-related content grouped together and prevent users from having to jump back to earlier steps when reading through the Quick Start Guide sequentially.

[Copilot]

In Step 4, the workflow commands (/research-codebase, /create-spec, /ralph, /gh-commit, /gh-create-pr) are shown without clarifying that they should be run inside a chat session. Unlike Step 3 which explicitly states "Start a chat session and run /init", Step 4 doesn't make this clear for subsequent commands. Users might misinterpret these as CLI commands. Consider adding a note at the beginning of Step 4 such as: "The following commands should be run inside your chat session (started with atomic chat -a <agent>)."