Revamp README: re-frame intro, simplify sections, add visual polish

README.md

@@ -1,47 +1,71 @@
 # Claude-Driven Development (CDD)
 
+![Claude-Driven Development — a dark charcoal banner with a faint grid: the large "Claude-Driven Development." wordmark in green with an orange period, above the tagline "A human-in-the-loop workflow for building software with Claude Code."](doc/assets/social-preview.png)
+
 [![template-smoke](https://github.com/drabaioli/cdd/actions/workflows/template-smoke.yml/badge.svg)](https://github.com/drabaioli/cdd/actions/workflows/template-smoke.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-orange.svg)](LICENSE)
+[![Built with Claude Code](https://img.shields.io/badge/Built%20with-Claude%20Code-d97757.svg)](https://claude.com/claude-code)
+[![Issues welcome](https://img.shields.io/badge/Issues-welcome-brightgreen.svg)](https://github.com/drabaioli/cdd/issues)
+[![Status: active development](https://img.shields.io/badge/status-active%20development-blue.svg)](doc/knowledge_base/roadmap.md)
 
-Build real software with Claude Code without handing over the wheel. CDD is a human-in-the-loop workflow: the agent carries the implementation, verification, and documentation across git worktrees, and every decision that matters passes through an explicit human gate. The docs, the roadmap, and the agent's context stay current as the project grows instead of rotting behind it.
+CDD (Claude-Driven Development) is a human-in-the-loop workflow for building software with Claude Code. The idea is simple: let AI agents do as much of the work as possible, and automate everything you can, but keep a developer around for the decisions that matter. You're not watching an agent free-run. You're steering it through a disciplined lifecycle where you get to approve things before anything consequential happens.
 
-## How it works
+A big part of what makes it work is being careful with context. When a single conversation tries to cover planning, implementation, review, and everything in between, all that mixed-together detail becomes a distraction and the quality of the results starts to suffer. So instead, every step gets its own fresh session with a single job and just the context it needs. The session doing the implementation isn't carrying the baggage of the planning discussion, and the one opening a PR isn't cluttered with half-finished exploration. It turns out that a handful of small, focused sessions tend to go a lot further than one giant one.
+
+The other half is checking in often. One-shotting a whole task is a bit utopian: today's models don't handle it all that gracefully yet, and no agent can read your mind and know exactly what you want. Frequent, low-stakes check-ins fix that. Each time you approve a plan or review a change, you get a chance to nudge things back on course before they drift too far, so the end result lands much closer to what you actually wanted.
 
-Every task moves through the same cycle. Each step is a fresh Claude Code session doing exactly one job, handing off to the next through files (a handoff file, the roadmap, the docs) rather than a shared chat window. A session loads only the context it needs to start, then follows links to the rest (the process doc, the architecture and feature docs) when a step actually calls for them, so context stays lean and never bloats with material the current job doesn't use. The locks across the top of the diagram are the human gates: the agent never crosses one without your explicit approval, and approving the plan is the load-bearing one.
+It also tries to bake in good engineering habits rather than hoping you'll remember them. The workflow reviews its own code and writes specs before it builds, and it looks after the hygiene that usually slips first when you're moving at AI speed: running tests, keeping documentation in sync, linting, formatting. The discipline is built into the lifecycle instead of taped on at the end.
 
-![CDD task cycle: start a session and run /cdd-next-step to queue a task, spin up an isolated worktree, build in plan mode, optionally /cdd-merge-base, run /cdd-pre-pr to self-review and open the PR, review on GitHub, optionally /cdd-process-pr for review feedback, merge, then clean up and repeat, with locked human gates across the top.](doc/assets/task-cycle.png)
+Documentation gets the same care, and not just for your benefit. A structured knowledge base keeps the project's memory durable across all these throwaway sessions, and it's exactly what a coding agent needs to understand how things work and what to do next. It all comes back to the same goal: giving each session exactly the context it needs, and keeping you in control at every gate.
+
+## How it works
+
+![CDD task cycle: start a session and run /cdd-next-step to queue a task, spin up an isolated worktree, build in plan mode, optionally /cdd-merge-base, run /cdd-pre-pr to self-review and open the PR, review on GitHub, optionally /cdd-process-pr for review feedback, merge, then clean up and repeat, with locked human gates down the left.](doc/assets/task-cycle.png)
 
 One full turn around the cycle:
 
-1. **Pick the next task.** Start a session with `claude`, then run `/cdd-next-step`. It proposes what to work on: the next roadmap item, an off-roadmap prompt you type, or a GitHub issue (`#NN`).
-2. **Confirm the intent.** You confirm the task is what you actually want and settle any roadmap-related decisions it raises. Once that's clear, it writes a handoff file for the implementation session.
-3. **Spin up an isolated worktree.** Run `cdd-worktree <branch>` to create a dedicated git worktree and branch. It automatically launches the implementation session, which opens in plan mode.
-4. **Review and approve the plan.** The session rebuilds its context from the handoff and the docs, then presents a plan. You approve it (this is the key gate), and it implements the task, updates the architecture/feature docs and the roadmap, and commits the work locally (no push yet).
-5. **Integrate the base branch if it moved.** If the base branch advanced while you were working, run `/cdd-merge-base`. It does more than resolve textual conflicts: it performs a *logical* merge, adopting newer base-branch features where the task should now use them.
-6. **Self-review and open the PR.** In a fresh session, run `/cdd-pre-pr`. It runs the CI gates, code-reviews the diff, reconciles the docs and roadmap, and ends by offering to open the PR, the point at which the branch is first pushed.
-7. **Review on GitHub.** You read the diff on GitHub and leave review comments, exactly as you would on any PR.
-8. **Address the feedback.** Run `/cdd-process-pr` on the branch. It triages the review comments, makes the requested changes, replies in each thread, and commits and pushes back to the PR.
-9. **Merge.** You squash-merge the branch on GitHub.
-10. **Clean up and repeat.** Back in your terminal, run `cdd-worktree-done` to remove the feature worktree and fast-forward your base branch to the freshly merged state. Then go again.
+1. **Select a task** — one, or several to run in parallel.
+2. **Write the handoff and create a git worktree** for the task, isolated from your main checkout.
+3. **Launch an implementation session.** It opens in plan mode; you approve the plan, then let it implement. You know what to expect, because you approved the plan.
+4. **Merge from the base branch if it moved** while you were working, approving the merge plan.
+5. **Let an agent review the code before the PR opens** — this is also where tests run and the docs are checked, linted, and formatted. It opens the PR at the end.
+6. **Review the PR** and ask the agent to address your feedback.
+7. **Merge the PR, delete the worktree, pull the changes into your main worktree — and start over.**
 
 The [process document](doc/knowledge_base/claude-driven-development.md) describes the full lifecycle, the artifacts, the edit rules, and the reasoning behind every gate. Read it first if you want to understand what CDD is and why.
 
-## Three objectives
+## Quick start
 
-CDD is built around three goals, in tension and balanced on purpose:
+CDD's front door is its guided commands. Here's the shortest path from zero to your first task:
 
-- **Automate everything except the decisions that matter.** The agent handles implementation, verification, and documentation. You keep control through explicit human gates: picking the task, approving the plan, approving any base-branch merge, merging the PR. Everything between the gates is automated; the gates never are.
-- **Bake in engineering best practices.** Tests, linting, formatting, CI, and living documentation aren't bolted on at the end. The workflow expects them at every step and reconciles docs and roadmap with each change, so quality and context don't erode as the project grows.
-- **Improve the workflow as you use it.** CDD is meant to be turned on itself. Friction surfaced in a session folds back into the process and the template, so the workflow gets sharper over time.
+```bash
+git clone https://github.com/drabaioli/cdd.git && cd cdd
+claude
+```
 
-## Quick start
+Then, from inside that Claude Code session:
+
+1. Run **`/cdd-bootstrap`** and start a new project. It walks you through defining the project and drafting a real roadmap through conversation, then scaffolds everything in one go — overview, `CLAUDE.md`, and roadmap already filled in.
+2. **`cd`** into your freshly created project and launch `claude` there.
+3. Run **`/cdd-next-step`** to scope your first task.
+4. Lift off — you're now running the task cycle above.
+
+Other entry points, run the same way from a session inside this repo:
+
+- **Bring CDD to a project you already have:** run **`/cdd-retrofit`**. It installs CDD into an existing codebase, or upgrades a project already running CDD, preserving your local customizations along the way.
+- **Produce a one-off deliverable** that doesn't warrant a whole project (a single script plus a README, no roadmap or project substrate): run **`/cdd-quick-create`**.
+
+Prefer to script it? The non-interactive `tools/bootstrap-cdd-project.sh` does the same scaffolding without the guided conversation.
+
+## Three objectives
 
-CDD's front door is its guided commands. Run them from a Claude Code session inside a clone of this repo (`git clone https://github.com/drabaioli/cdd.git && cd cdd && claude`).
+CDD is built around three goals, in tension and balanced on purpose.
 
-**Start a brand-new project:** run `/cdd-bootstrap`. It walks you through defining the project and drafting a real roadmap through conversation, then scaffolds everything in one go (overview, `CLAUDE.md`, and roadmap already filled in), leaving you ready to run the task cycle above.
+**Automate everything except the decisions that matter.** Everything between the human gates is automated; the gates, picking the task, approving the plan, approving any base-branch merge, merging the PR, never are.
 
-**Bring CDD to a project you already have:** run `/cdd-retrofit`. It installs CDD into an existing codebase, or upgrades a project already running CDD, preserving your local customizations along the way.
+**Bake in engineering best practices.** Tests, linting, formatting, CI, and living documentation aren't bolted on at the end. The workflow expects them at every step, so quality and context don't erode as the project grows.
 
-**Produce a one-off deliverable** that doesn't warrant a whole project (a single script plus a README, no roadmap or project substrate): run `/cdd-quick-create`.
+**Improve the workflow as you use it.** CDD is meant to be turned on itself. Friction surfaced in a session folds back into the process and the template, so the workflow gets sharper over time.
 
 ## Command reference
 
@@ -76,15 +100,15 @@ Either form wires `~/.bashrc` and `~/.zshrc` (idempotent); open a new shell afte
 
 ## Questions?
 
-The fastest way to understand how CDD works is to ask it directly: open your local clone with `claude` and ask Claude Code questions about the project. The process doc, the template, and these docs are all right there for it to read: "why the human gates?", "what does `/cdd-merge-base` actually do?", and so on.
+The fastest way to understand CDD is to ask it directly: launch `claude` on your local clone of this repo and ask away. The process doc, the template, and these docs are all right there for it to read.
 
 ## Contributing
 
 At this stage CDD accepts **GitHub issues only; pull requests aren't open yet**. Bug reports, suggestions, and questions about the workflow are very welcome: please [open an issue](https://github.com/drabaioli/cdd/issues). Have a change in mind? Raise it as an issue first and we can discuss it there. Direct PRs aren't being accepted for now. That will change as the project opens up.
 
 ## Status
 
-In active use, and dogfooded on itself. CDD has driven full task cycles end to end (real merges and PR reviews) on a downstream demo project (see [`demo/`](demo/)) and been retrofitted onto existing real-world codebases, with the friction found along the way folded back into the template. See [`doc/knowledge_base/roadmap.md`](doc/knowledge_base/roadmap.md) for what's done and what's next.
+Currently in active development and working quite well. See [`doc/knowledge_base/roadmap.md`](doc/knowledge_base/roadmap.md) for what's done and what's next.
 
 ## License
 

doc/knowledge_base/roadmap.md

@@ -160,6 +160,7 @@ Prepare CDD to be open-sourced publicly: license it, rewrite the README to expla
 
 - [x] Add a standard MIT `LICENSE` at the repo root (holder: Diego Andres Rabaioli; year 2026). Repo-root only — not added to `template/` or wired into `bootstrap-cdd-project.sh`, since the template is copied verbatim into downstream projects without dragging a license along.
 - [x] Rewrite the README from scratch: what CDD is and how to use it; guided entry points (`/cdd-bootstrap`, `/cdd-retrofit`, `/cdd-quick-create`) lead the quick start with the manual `bootstrap-cdd-project.sh` recipe below; a complete reference of all 7 slash commands; the task-cycle image (`doc/assets/task-cycle.png`); a short issues-only Contributing section. Kept the two-big-ideas framing, the six-checkpoint concept, the `template-smoke` badge, and the Status section.
+- [x] README re-framing + visual-polish pass (follow-up to the rewrite above, not a reopen): re-ordered the intro emphasis (AI agents / automation / human-in-the-loop first, context economy next, documentation de-emphasized to a closing mention) and folded in engineering-best-practices framing; simplified How it works (10 steps → 7), Quick start (guided flow leads), Questions, and Status; added a hero banner (`doc/assets/social-preview.png`), an expanded badge row (License, Built with Claude Code, Issues welcome, status — alongside the existing `template-smoke` CI badge), and tasteful heading emojis. README-only; no process-doc/template counterpart.
 - [ ] `CONTRIBUTING.md` (full version, once PRs are accepted).
 - [x] `CODE_OF_CONDUCT.md`. — Contributor Covenant 2.1 at the repo root; enforcement contact `drabaioli@gmail.com`. Repo-root only, not added to `template/`.
 - [x] `.github/` issue templates: `bug_report.yml` and `idea.yml` forms plus `config.yml` (blank issues enabled). PR template deferred until PRs open.