plan_driven 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49e95b18ac3191d34d9d526ba2fea2428ea662fab966da32c15239ba39573e5d
-  data.tar.gz: '099d0a1fae1854e186a894e95354118b086722ecb6b13c72e90e28dfa2a2bc13'
+  metadata.gz: 2cad74cf1d61e2bc83cc71e30037048a81a0042a25a355695e97f1ec5ebdd823
+  data.tar.gz: f9b7139fbc8cac5475fd0b1429ebf90d8f06884c71d49c122b48c310c180c442
 SHA512:
-  metadata.gz: 2bd6c949e802f2f2e7ccc1b98052ebc3c744b5e4bb381666cddbe79f7849e7ff1cf4205bde8a8f00b560bbce70f85ebac584c2ddd76f12156a8adf3f06843520
-  data.tar.gz: c6605b055a96b9f2779038c2915ae2bf2585dfa28b66cd289a6b9a2dcbf295ed1ebda16d2df4476ea0d71b6dfd26ea05e9da39b596c905bbe18aeda6c6aa98a8
+  metadata.gz: 4b1de072864c1a701b49cff10ff0fa25cbe1c8c111c354884dcaaec308637ed1b62f2a12db0dac5be768f77706d9a03cbd24498cfdc93cd10d07611250ee266b
+  data.tar.gz: 65eb69253b06990105156e72f2a61a9b8b77e7b39b444414ce4516d065ae5a1eabcd0b2a671e1fd33a2929d86031688d8967f3a4d3a97246bac5ca97b3741641

data/CHANGELOG.md

@@ -6,6 +6,59 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-30
+
+### Added
+
+- The browser wizard: a Rails engine the install generator mounts at `/plan_driven`, in
+  development only. It walks a plan through the interview, plan, approval, tickets, agents
+  and evidence with Back and Next, and every button runs the matching `plan-driven` command in
+  the background, with the command and its live output shown beside the form. Only a fixed
+  list of commands can run, for local requests only (`config.wizard_enabled`).
+- The wizard's Configuration page: Connections shows which services the app uses and whether
+  each has a key, and connects one from a pasted key; Interview questions changes, adds and
+  removes the questions `new` asks.
+- `plan-driven connect SERVICE` (`cursor`, `openai`, `anthropic`, `github`) checks a key with
+  the service before storing it, and stores nothing when the service refuses it. The key is
+  read from stdin, never from the command line.
+- `plan-driven questions` and `plan-driven question KEY` (`--title`, `--ask`, `--group`,
+  `--required`, `--optional`, `--remove`). The changes live in the app, in
+  `config/plan_driven/interview.yml`, so the team shares one interview; an added question is
+  a section of the plan like the others.
+- `plan-driven edit PLAN SECTION --from FILE` replaces a section with a file's contents.
+- Tokens and cost. Every model call (drafting, redrafts, tickets) and every agent run is
+  recorded with its tokens and duration. `plan-driven usage PLAN` prints them, and the delivery
+  report has a Tokens and cost table. `config.token_prices` turns tokens into dollars.
+- Local coding agents: `config.agent_provider = :local` runs `config.agent_command` (Claude
+  Code, Codex, the Cursor CLI...) in its own git worktree per ticket, then commits, pushes and
+  opens the pull request. Feedback runs in the same worktree; the worktree is removed after
+  the merge. `{prompt_file}` in the command passes the prompt as a file instead of stdin.
+- `GitHub#create_pull`, and Cursor agent runs carry `duration_ms`.
+
+### Changed
+
+- MigrationGuard judges each removal or rename on its own sentence, or migration code line,
+  and the step it sits under. Before, the word "expand" or "contract" anywhere in Database
+  changes excused every destructive change in the section. Headings, negated sentences,
+  rollback notes and tables the plan creates are no longer read as removals.
+- Terminal tables fit the terminal width, cutting the last column short instead of wrapping.
+- When answers are piped into `plan-driven new`, the interview prints each answer after its
+  question, so the transcript reads like the terminal session.
+
+### Fixed
+
+- Optional questions no longer read "(optional) (optional)" in the New plan form: the
+  interview adds "(optional)" itself, in the terminal and in the wizard alike.
+- `plan-driven version` exits with status 0 instead of a TypeError after printing the version.
+- `evidence` always runs Cucumber with `RAILS_ENV=test`. Started from a development server,
+  as the wizard does, it inherited `RAILS_ENV=development` and ran the scenarios against the
+  development database. The wizard also no longer passes the server's `RAILS_ENV` to commands.
+- `remove_check_constraint` and other `remove_*` methods that drop no data are no longer
+  destructive changes; `remove_column(s)`, `remove_reference`, `remove_timestamps`,
+  `drop_table`, `rename_*` and `change_column` still are.
+- Ticket coverage asks for tickets only for tables the plan creates or changes. Tables the
+  plan names in prose, or that already exist in the schema, no longer need their own ticket.
+
 ## [0.1.0] - 2026-09-30
 
 First public release.
@@ -72,5 +125,6 @@ First public release.
 - `plan-driven doctor` checks keys, the repository, the PDF browser, the Cursor API, the agent
   model, and Node and the SDK for `:cursor`.
 
-[Unreleased]: https://github.com/blaz1988/plan-driven/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/blaz1988/plan-driven/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/blaz1988/plan-driven/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/blaz1988/plan-driven/releases/tag/v0.1.0

data/README.md

@@ -24,10 +24,50 @@ Zagreb. [Need Rails engineers?](#about-rubycode)
 
 ## Watch it deliver a feature
 
-[![Watch the plan_driven demo (25 min)](docs/images/demo.png)](https://github.com/blaz1988/plan-driven/releases/download/v0.1.0/plan-driven-demo.mp4)
+[![Watch the plan_driven wizard demo (12 min)](docs/images/wizard-demo.png)](https://github.com/blaz1988/plan-driven/releases/download/v0.1.0/plan-driven-wizard.mp4)
+
+**[▶ Watch the wizard demo](https://github.com/blaz1988/plan-driven/releases/download/v0.1.0/plan-driven-wizard.mp4)**
+(12 minutes, narrated, with captions). One feature, comments on events, is delivered from
+the [browser wizard](#the-browser-wizard) in [Gather](https://github.com/blaz1988/gather):
+the plan drafted and one section redrafted, six tickets as issues
+([#34](https://github.com/blaz1988/gather/issues/34) to
+[#39](https://github.com/blaz1988/gather/issues/39)), six agents and six pull requests
+([#40](https://github.com/blaz1988/gather/pull/40) to
+[#45](https://github.com/blaz1988/gather/pull/45)), one round of feedback, and 42 of 42
+acceptance criteria proven by a passing scenario. After every click the video zooms into the
+wizard's terminal panel, which shows the `plan-driven` command that ran and its output. The
+wizard ships with 0.2.0.
 
-**[▶ Watch the demo](https://github.com/blaz1988/plan-driven/releases/download/v0.1.0/plan-driven-demo.mp4)**
-(25 minutes, narrated, with captions). One feature, RSVPs with a waitlist, goes from an
+<details>
+<summary>Chapters</summary>
+
+| Time | Chapter |
+| ---: | --- |
+| 0:00 | What plan_driven is |
+| 0:24 | Installing it, and how the wizard works |
+| 1:13 | `doctor`, from the wizard |
+| 1:48 | The interview as a form, and the draft |
+| 2:43 | Reading the plan, redrafting a section, submitting and approving |
+| 3:51 | Tickets drafted and approved, as GitHub issues |
+| 4:37 | Starting the agents |
+| 5:18 | Refreshing, and `review` |
+| 6:01 | Reading the first pull request |
+| 6:46 | Approving and merging, and the next agent starts |
+| 7:43 | Feedback to the agent on T3 |
+| 8:24 | Every ticket merged |
+| 8:53 | Evidence (42 of 42), tokens, and the delivery report |
+| 9:47 | Reading the delivery report |
+| 10:11 | The feature in the app |
+| 10:46 | The same commands in a terminal |
+| 11:22 | Recap |
+
+</details>
+
+### The CLI deep dive
+
+**[▶ Watch the CLI demo](https://github.com/blaz1988/plan-driven/releases/download/v0.1.0/plan-driven-demo.mp4)**
+(28 minutes, narrated, with captions), for everything the wizard runs, typed in a terminal.
+One feature, RSVPs with a waitlist, goes from an
 idea to production code in a new Rails 8 app,
 [Gather](https://github.com/blaz1988/gather). Nothing in it is staged: the plan, the five
 tickets, the five pull requests ([#8](https://github.com/blaz1988/gather/pull/8) to
@@ -44,18 +84,20 @@ repository. The planner and the five agents ran on Claude Opus 5.5 through Curso
 | 2:49 | `doctor`: keys, repository and the Cursor connection |
 | 3:15 | The interview |
 | 4:14 | Reading the implementation plan |
-| 6:05 | Deciding the open questions, then approving |
-| 7:20 | Tickets: drafted, steered to five, read and approved |
-| 9:42 | The tickets as GitHub issues |
-| 10:12 | What the agent is told, and starting the first agent |
-| 11:08 | Reading the first pull request, `review`, `approve-pr` and `merge` |
-| 13:18 | The model and its rules (T2) |
-| 15:22 | The RSVP card, tried on the branch before merging (T3) |
-| 17:41 | Feedback: a behind-main warning and a refactor (T5) |
-| 20:12 | The organizer's attendee list (T4) |
-| 21:47 | Evidence: 33 of 33 acceptance criteria, and the delivery report |
-| 23:01 | The finished feature in the app |
-| 24:12 | Recap |
+| 6:05 | Deciding the open questions with `redraft` |
+| 6:50 | Every section can be changed: Database changes redrafted and edited in vim (PD-2) |
+| 9:51 | Submitting and approving the plan |
+| 10:23 | Tickets: drafted, steered to five, read and approved |
+| 12:44 | The tickets as GitHub issues |
+| 13:15 | What the agent is told, and starting the first agent |
+| 14:10 | Reading the first pull request, `review`, `approve-pr` and `merge` |
+| 16:21 | The model and its rules (T2) |
+| 18:25 | The RSVP card, tried on the branch before merging (T3) |
+| 20:44 | Feedback: a behind-main warning and a refactor (T5) |
+| 23:15 | The organizer's attendee list (T4) |
+| 24:50 | Evidence: 33 of 33 acceptance criteria, and the delivery report |
+| 26:04 | The finished feature in the app |
+| 27:15 | Recap |
 
 </details>
 
@@ -65,11 +107,15 @@ repository. The planner and the five agents ran on Claude Opus 5.5 through Curso
 - [Requirements](#requirements)
 - [Installation](#installation)
 - [Getting your app ready](#getting-your-app-ready)
+- [The browser wizard](#the-browser-wizard)
 - [Walkthrough: one feature from idea to merged](#walkthrough-one-feature-from-idea-to-merged)
 - [Guards](#guards)
 - [What the agent is told](#what-the-agent-is-told)
 - [Commands](#commands)
 - [Configuration](#configuration)
+- [Choosing the coding agents](#choosing-the-coding-agents)
+- [Tokens and cost](#tokens-and-cost)
+- [How it compares](#how-it-compares)
 - [Keys](#keys)
 - [Working as a team](#working-as-a-team)
 - [Troubleshooting](#troubleshooting)
@@ -93,7 +139,7 @@ repository. The planner and the five agents ran on Claude Opus 5.5 through Curso
  plan-driven approve-tickets  ─▶ tickets approved     GitHub issues created
         │
         ▼
- plan-driven develop      one Cursor cloud agent per ready ticket, one PR each
+ plan-driven develop      one agent per ready ticket (Cursor cloud, or a local CLI), one PR each
  plan-driven status       agent finished ─▶ PR open
  plan-driven review       PrGuard: scope, specs, Cucumber scenarios, CI, up to date
  plan-driven feedback     the same agent pushes a fix to the same PR
@@ -102,7 +148,7 @@ repository. The planner and the five agents ran on Claude Opus 5.5 through Curso
         │
         ▼
  plan-driven evidence     Cucumber results mapped to acceptance criteria
- plan-driven report       docs/plans/pd-1-…/delivery-report.pdf
+ plan-driven report       docs/plans/pd-1-…/delivery-report.pdf, with tokens and cost
 ```
 
 Phases are stored in your application's database, so a plan can't skip a step. Tickets can't
@@ -119,9 +165,12 @@ model as a list to fix, and a plan that still fails isn't accepted.
 
 - Ruby 3.1+ and Rails 7.0+ (see [support](#rails-and-ruby-support)).
 - The application on GitHub, with CI running on pull requests.
-- A [Cursor](https://cursor.com) account with the GitHub integration connected to that
-  repository, and a Cursor API key (Cursor dashboard, Integrations). The agents run as
-  Cursor cloud agents.
+- Coding agents, one of (see [Choosing the coding agents](#choosing-the-coding-agents)):
+  - **Cursor cloud agents** (the default): a [Cursor](https://cursor.com) account with the
+    GitHub integration connected to that repository, and a Cursor API key (Cursor dashboard,
+    Integrations).
+  - **A local agent CLI** (`agent_provider :local`): Claude Code, Codex, the Cursor CLI or any
+    command that edits files in its working directory, plus `git` push access to the repository.
 - A model for drafting plans and tickets, one of:
   - **Cursor** (`llm_provider :cursor`): any model on your Cursor account, Claude Opus 5.5 by
     default. Needs Node 22.13+ and the Cursor SDK. No other LLM key.
@@ -204,7 +253,7 @@ into your application. See [Keys](#keys).
 ```
 $ bin/plan-driven doctor
 
-plan-driven 0.1.0
+plan-driven 0.2.0
 ✓ Rails application: plan_driven tables present
 LLM: cursor/claude-opus-5-5
 ✓ Cursor SDK: Node v24.21.0, @cursor/sdk found
@@ -263,6 +312,81 @@ config.extra_context = "Gather lists community events. An event has an organizer
 **Who approves.** `plan_approvals` and `ticket_approvals` list the roles that must sign off,
 for example `%w[review qa devops director]`. One person can hold every role on a small team.
 
+## The browser wizard
+
+Not everyone wants to drive a delivery from the terminal. The install generator mounts a
+wizard in your app, in development only:
+
+```ruby
+# config/routes.rb
+mount PlanDriven::Wizard::Engine, at: "/plan_driven" if Rails.env.development?
+```
+
+Start the app and open `http://localhost:3000/plan_driven`. It walks a plan through the same
+five steps, with Back and Next: **Plan** (the interview, then read, edit or redraft any section
+and submit), **Approve**, **Tickets**, **Agents & PRs** and **Proof & report**. A step opens
+once the plan has reached it.
+
+The wizard is a front end for the CLI, not a second implementation. Every button runs one
+`plan-driven` command in the background, and the panel on the right shows that command and its
+output as it runs, exactly as you'd see it in a terminal:
+
+![The wizard's Approve step, with the command it ran and its output](docs/images/18-wizard.png)
+
+```
+$ bin/plan-driven edit PD-3 database_changes --from tmp/plan_driven/wizard/sections/PD-3-database_changes-1f2e.md --yes
+✓ Database changes updated; PD-3 is now revision 2 (draft)
+✓ All checks passed
+```
+
+So anything done in the browser can be repeated, scripted or reviewed from the terminal, and
+the audit trail is the same either way. A few things to know:
+
+- Only a fixed list of commands can run, built from the form fields as an argument list, never
+  through a shell. A key pasted on the Configuration page goes to `plan-driven connect` on
+  stdin, so it's never in the command line, the panel or the logs.
+- It answers local requests only, and only in development. `config.wizard_enabled = true`
+  turns it on in another environment, still for local requests only.
+- "Acting as" at the top sets `PLAN_DRIVEN_ACTOR` for the commands it runs, so approvals are
+  recorded under the name you give; it defaults to your git identity.
+- Each run is kept in `tmp/plan_driven/wizard/`: the command, its output and its exit status.
+
+### Configuration: connections and the interview
+
+**Configuration**, at the top of every page, has two parts.
+
+**Connections** shows which services this app's configuration uses (Cursor for cloud agents
+or drafting, OpenAI or Anthropic for drafting, GitHub for issues and pull requests), whether
+each one has a key, and where the key comes from. Paste a key and click Connect:
+`plan-driven connect cursor` checks it with the service first (for Cursor, the account it
+belongs to) and only then stores it in `~/.plan_driven/config`. A refused key is never stored.
+**Check every connection** runs `doctor`. The same works in the terminal:
+
+```
+$ bin/plan-driven connect cursor
+Cursor key:
+Checking the key with Cursor...
+✓ Cursor: connected as ana@example.com
+  stored in ~/.plan_driven/config (0600), never in the app
+```
+
+Which model drafts and which agents write the code are still set in the initializer (see
+[Choosing the coding agents](#choosing-the-coding-agents)); the page shows the current choice.
+
+**Interview questions** lists what `plan-driven new` and the New plan form ask. Change a
+question's title or wording, make it required or optional, add your own questions, or put one
+back to the default. Each Save runs `plan-driven question`:
+
+```
+$ bin/plan-driven question success_metric --title "Success metric" --ask "How will we know it worked?" --optional
+✓ Question success_metric added
+```
+
+The changes are written to `config/plan_driven/interview.yml` in your app. Commit it, and the
+whole team gets the same interview, in the wizard and in the terminal. An added question goes
+to the model with the other answers, and it's a section of the plan under the group you pick.
+Drafted sections (Database changes, Risks...) belong to the model and can't be changed here.
+
 ## Walkthrough: one feature from idea to merged
 
 This is the run from the demo video, in [Gather](https://github.com/blaz1988/gather), with the
@@ -319,8 +443,22 @@ column it cites exists.
 
 ![The plan, grounded in the real schema](docs/images/03-plan.png)
 
-Change what isn't right. `edit` opens a section in `$EDITOR`. `redraft` has the model rewrite
-one section from an instruction, which is the quickest way to record decisions:
+**Every section of the plan can be changed**, not only Outstanding questions: What, Why,
+Database changes, Application changes, Risks, Testing, any of them (the keys are listed under
+[Commands](#commands)). The draft is the model's proposal, and your team has the final say.
+There are two ways to change a section:
+
+- `edit PLAN SECTION` opens the section in `$VISUAL` or `$EDITOR` as Markdown. Use it for exact
+  changes: a column, a name, a step, a test case.
+- `redraft PLAN SECTION "instruction"` has the model rewrite only that section, following your
+  instruction. It reads the rest of the plan and the code while it does.
+
+Either way the change becomes a new revision, the plan goes back to draft, the guards run again
+and the Markdown, HTML and PDF are written again. `plan-driven log PLAN` lists every change.
+Change the plan through these commands, not by editing `plan.md`: the database is the source,
+and the files are rendered from it.
+
+`redraft` is also the quickest way to record decisions:
 
 ```
 $ bin/plan-driven redraft PD-1 outstanding_questions "Record my answers under Decided and keep only
@@ -337,6 +475,80 @@ Redrafting outstanding_questions...
 
 ![The decisions, recorded in the plan](docs/images/04-plan-decided.png)
 
+#### Example: changing the database design
+
+The agent's draft is a starting point, and the database design is where teams most often
+disagree with it. In Gather's second plan, PD-2 (event categories), the model suggested a string
+column on `events`:
+
+```
+$ bin/plan-driven show PD-2 --section database_changes
+### Step 1: Expand (migration `AddCategoryToEvents`)
+
+On table `events`:
+- Add column `category`: type `string`, **nullable**, default `'meetup'`.
+- Add composite index `index_events_on_category_and_starts_at` on `[:category, :starts_at]`. ...
+```
+
+The team wanted a table instead. `redraft` rewrites the section to that design, keeping the
+expand and contract steps:
+
+```
+$ bin/plan-driven redraft PD-2 database_changes "Use a categories table instead of a string column:
+  name and slug, seeded with meetup, workshop, talk and conference, and a category_id reference on events."
+Redrafting database_changes...
+Categories live in their own `categories` table, and each event points to one of them through
+`events.category_id`. ...
+### Step 1: Expand
+#### Migration `CreateCategories`
+New table `categories`:
+- `name` string, **not null**, no default. ...
+- `slug` string, **not null**, no default. ...
+...
+### Step 5: Contract (migration `EnforceCategoryOnEvents`)
+- `change_column_null :events, :category_id, false`.
+✓ All checks passed
+```
+
+A small change doesn't need the model. `edit` opens the section in your editor. Here, a `color`
+column is added to the new table, in the column list, the migration and the resulting schema:
+
+```
+$ EDITOR=vim bin/plan-driven edit PD-2 database_changes
+✓ Database changes updated; PD-2 is now revision 3 (draft)
+✓ All checks passed
+```
+
+![Adding a column to the plan in vim](docs/images/04b-edit-section.png)
+
+The guards check your edit the same way they check the model's draft (see [Guards](#guards)),
+and anything that fails is listed right after you save. `submit` refuses a plan with errors.
+
+Other sections that depend on the change follow the same way. The model reads the whole plan,
+so it picks up the new table and the `color` column:
+
+```
+$ bin/plan-driven redraft PD-2 application_changes "Follow the new Database changes: a Category model,
+  events.category_id instead of an enum, and the category colour on the card badge."
+...
+✓ All checks passed
+
+$ bin/plan-driven submit PD-2
+✓ PD-2 revision 4 is in review
+
+$ bin/plan-driven log PD-2
+When              Event         Ticket  By                         Details
+2026-09-30 10:07  plan.drafted          Ivan Blažević <ivan...>    model=cursor/claude-opus-5-5 ...
+2026-09-30 10:10  plan.revised          Ivan Blažević <ivan...>    sections=database_changes
+2026-09-30 10:16  plan.revised          Ivan Blažević <ivan...>    sections=database_changes
+...
+```
+
+You can change a plan in draft, in review and after it's approved. An approval belongs to a
+revision, so a changed plan must be approved again. Once its tickets are drafted, the plan is
+locked, because the tickets and pull requests were built from it. Changes after that go into a
+follow-up plan.
+
 ### 3. Submit and approve
 
 ```
@@ -530,8 +742,12 @@ An error blocks the next step and a warning is shown and recorded.
 
 **MigrationGuard** reads the database changes:
 
-- removing or renaming a column or table in one step is an error, unless the plan stages it
-  with `ignored_columns`, expand and contract, or a later release;
+- removing or renaming a column or table in one step is an error. Each change is judged on its
+  own, sentence by sentence and line by line in migration code: it's accepted only when that
+  sentence stages it (`ignored_columns`, a later release, after the backfill) or when it sits
+  under a contract, cleanup or later step. Mentioning "expand" somewhere else in the section
+  doesn't excuse it. Headings, negated sentences ("No column is removed"), rollback notes and
+  tables the plan itself creates don't count as removals;
 - NOT NULL on an existing table without a default or backfill is a warning;
 - on PostgreSQL, an index that isn't built concurrently is a warning.
 
@@ -623,14 +839,18 @@ key such as `PD-1`, and `PLAN/TICKET` is a ticket such as `PD-1/T3`.
 | `evidence PLAN [--from FILE]` | Run or import Cucumber results |
 | `report PLAN` | Write the delivery report |
 | `log PLAN` | The audit trail |
+| `usage PLAN` | Tokens, time and cost per step and per agent run |
+| `questions` | The interview's questions, and which ones the team changed or added |
+| `question KEY [--title T] [--ask Q] [--group G] [--required \| --optional] [--remove]` | Change or add an interview question, or put it back |
 | `configure` | Store keys in `~/.plan_driven/config` |
-| `doctor` | Check keys, repository, PDF browser and the Cursor connection |
+| `connect SERVICE` | Check a key with `cursor`, `openai`, `anthropic` or `github`, then store it |
+| `doctor` | Check keys, repository, PDF browser, and the Cursor connection or local agent command |
 
 Section keys for `show --section`, `edit` and `redraft`: `what`, `why`, `where`, `who`,
 `when`, `background`, `existing_data_structure`, `architecture`, `database_changes`,
 `application_changes`, `infrastructure_changes`, `out_of_scope`, `risks`, `performance`,
-`security`, `monitoring`, `outstanding_questions` and `testing`. `edit PLAN` without a section
-lists them.
+`security`, `monitoring`, `outstanding_questions` and `testing`, plus any question the team
+added. `edit PLAN` without a section lists them.
 
 `--yes` skips confirmations, for scripts. `merge` still needs the ticket key typed unless
 `--yes` is given.
@@ -657,11 +877,17 @@ PlanDriven.configure do |config|
   config.plan_approvals = %w[review]            # e.g. %w[review qa devops director]
   config.ticket_approvals = %w[review]
 
-  # Cursor cloud agents
-  config.agent_model = nil                      # nil uses your Cursor default
+  # Coding agents
+  config.agent_provider = :cursor               # or :local, see "Choosing the coding agents"
+  config.agent_command = nil                    # :local only, e.g. "claude -p --permission-mode acceptEdits --output-format json"
+  config.agent_timeout = 3600                   # :local only; seconds before a run is stopped
+  config.agent_model = nil                      # :cursor; nil uses your Cursor default
   config.base_branch = "main"
   config.max_parallel_agents = 3
-  config.skip_reviewer_request = false          # true: the agent doesn't request you as reviewer
+  config.skip_reviewer_request = false          # :cursor; true: the agent doesn't request you as reviewer
+
+  # Tokens and cost: dollars per million tokens, by model id. None ship with the gem.
+  config.token_prices = {}                      # { "model-id" => { input: 3.0, output: 15.0, cache_write: 3.75, cache_read: 0.3 } }
 
   # GitHub
   config.github_repository = nil                # "owner/name"; read from the origin remote when nil
@@ -695,6 +921,88 @@ plan and can't change a file.
 
 `config.template` replaces the plan's sections if your template differs.
 
+## Choosing the coding agents
+
+Every ticket goes to one agent, which works on its own branch and opens one pull request. The
+rest of the workflow is the same whichever agents you use: `review`, `feedback`, `approve-pr`
+and `merge` see only the pull request.
+
+**Cursor cloud agents** (`agent_provider :cursor`, the default) run on Cursor-hosted machines
+against a fresh clone of the repository, so nothing runs on your laptop and several tickets
+can run at once. `config.agent_model` picks the model.
+
+**A local agent CLI** (`agent_provider :local`) runs a command on your machine. Each ticket
+gets its own git worktree and branch under `tmp/plan_driven/agents`, so tickets don't touch
+your working copy or each other. The command gets the same prompt a cloud agent gets, on stdin,
+or wherever the command says `{prompt_file}`. When it exits cleanly, plan_driven commits what
+it left, pushes the branch and opens the pull request, using the description the agent wrote
+to `PR_DESCRIPTION.md`. Feedback runs the command again in the same worktree and pushes to the
+same pull request. After the merge, the worktree and the local branch are removed.
+
+```ruby
+config.agent_provider = :local
+
+# Claude Code
+config.agent_command = "claude -p --permission-mode acceptEdits --output-format json"
+# Codex
+config.agent_command = "codex exec --full-auto -"
+# The Cursor CLI
+config.agent_command = 'cursor-agent -p --force --output-format json "$(cat {prompt_file})"'
+```
+
+A local agent runs with your permissions and your shell, so give it only the tools it needs to
+edit and to run the test suite, and read the pull request as carefully as a cloud agent's.
+Runs longer than `config.agent_timeout` (an hour by default) are stopped. The Cursor CLI setup
+is the one tested end to end; flags change between CLI versions, so check your CLI's `--help`.
+`plan-driven doctor` checks that the command is on the `PATH`.
+
+## Tokens and cost
+
+Every model call and every agent run is recorded with the tokens it used: drafting the plan,
+each `redraft`, drafting the tickets, and each agent run and follow-up, with its duration.
+`plan-driven usage PD-1` prints them, and the delivery report has a Tokens and cost table.
+
+Prices change and differ per account, so the gem ships none: put what your provider charges in
+`config.token_prices` (dollars per million tokens, with separate cache prices), and the report
+shows dollars next to the tokens. Without a price you still get the tokens and the time.
+
+Cursor reports tokens for every cloud agent run. A local CLI's tokens are recorded when it
+prints them the way Claude Code's `--output-format json` does; otherwise only the time is.
+
+For scale, these are the five cloud agents from the demo, read back from Cursor's usage API
+(T4 and T5 include their feedback runs):
+
+| Ticket | Runs | Output tokens | Cache reads | Total tokens |
+| --- | ---: | ---: | ---: | ---: |
+| T1 migration | 1 | 13,861 | 738,595 | 791,861 |
+| T2 model rules | 1 | 21,037 | 1,519,826 | 1,596,409 |
+| T3 RSVP card | 1 | 16,611 | 1,161,514 | 1,242,945 |
+| T4 attendee list | 2 | 10,957 | 1,083,671 | 1,149,274 |
+| T5 seats on the index | 2 | 12,725 | 1,154,333 | 1,248,462 |
+| **Total** | 7 | **75,191** | **5,657,939** | **6,028,951** |
+
+94% of the tokens are cache reads, which cost a fraction of fresh input, and only 75 thousand
+are code and text the agents wrote. Most of an agent's tokens go into reading the codebase, so
+a small, conventional one is cheaper to work on.
+
+## How it compares
+
+plan_driven sits next to spec-driven tools such as GitHub's Spec Kit and Kiro, which also start
+from a written spec before an agent writes code. As we understand them, those are
+language-agnostic and focus on producing the spec, the design and the task list for an agent to
+follow. plan_driven is narrower and goes further on the Rails side:
+
+- the plan is drafted from your Rails schema, models and routes, and Existing Data Structure is
+  checked against them;
+- the rules are Ruby code that blocks the next step (expand and contract, ticket size and
+  order, pull request scope, CI), rather than guidance in a prompt;
+- phases and approvals are stored in your database, per revision, with an audit trail;
+- each acceptance criterion is mapped to a Cucumber scenario, and the delivery report shows
+  the proof, the approvals and the cost.
+
+If your stack isn't Rails, or you only want a spec for a single agent session, a general tool
+is the better fit.
+
 ## Keys
 
 | Key | Used for | Environment |

data/app/controllers/plan_driven/wizard/application_controller.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  module Wizard
+    # The wizard runs commands on this machine, so it only answers local requests in development
+    # (or wherever config.wizard_enabled says).
+    class ApplicationController < ActionController::Base
+      protect_from_forgery with: :exception
+      layout "plan_driven/wizard/application"
+      before_action :local_only!
+      helper_method :acting_as, :current_job
+
+      helper do
+        # A button that runs one command for the plan on the page, e.g. run_button("Submit", "submit").
+        def run_button(label, action, fields = {}, primary: false, disabled: false)
+          button_to label, run_plan_path(@plan.key),
+                    params: fields.merge(do: action, step: @step), disabled: disabled,
+                    class: primary ? "primary" : nil, form: { style: "display:inline" }
+        end
+
+        def markdown(text)
+          PlanDriven::Renderer::HTML.convert(text).html_safe
+        end
+
+        def guard_list(report)
+          safe_join([
+            (tag.ul(safe_join(report.errors.map { |e| tag.li(e) }), class: "errors") if report.errors.any?),
+            (tag.ul(safe_join(report.warnings.map { |w| tag.li(w) }), class: "warnings") if report.warnings.any?),
+            (tag.p("#{report.passes.size} checks passed.", class: "muted") if report.passes.any?)
+          ].compact)
+        end
+      end
+
+      private
+
+      def local_only!
+        enabled = PlanDriven.configuration.wizard_enabled
+        enabled = Rails.env.development? if enabled.nil?
+        head :forbidden unless enabled && request.local?
+      end
+
+      def acting_as
+        session[:plan_driven_actor].presence || PlanDriven.actor
+      end
+
+      def current_job
+        return @current_job if defined?(@current_job)
+
+        @current_job = params[:job].present? ? Job.find(params[:job]) : nil
+      rescue ArgumentError
+        @current_job = nil
+      end
+
+      def start(argv, stdin: nil)
+        Job.start(argv, stdin: stdin, actor: session[:plan_driven_actor])
+      end
+    end
+  end
+end