plan_driven 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ffc191c08d6787d03cfccdcb13fb559e2fb48f5d042fbe5597335544f36339f
-  data.tar.gz: f32edb2f3c5cd3fd1eed677bc834d6a60527c59d15d49a89065083dc07ee18b8
+  metadata.gz: 1aa0eca4bbed9a924624eda3f8d7bc0708d0e39e379131ef0f440394e7492de5
+  data.tar.gz: ae73e611b52ebd21c3ec55f58706358c5335d3e92b3af7172823ca5c8362a638
 SHA512:
-  metadata.gz: 8a9a83308065071c48d13c575f06966a99fd517a3f6e2fbcacb5d804f937e433395305aef7578332fc171929c8e234923f5abc537ba21e5c6100cbb9e7ee7279
-  data.tar.gz: 79a273ff6f7d84e371445047646f9ea799a374ca0f2a838863b76eb3e9cf3a3a3ded7054235e68c3d500ef02f31e744bf2aa9e255364d071afc0112ed1c9af20
+  metadata.gz: 254283d951789508706067cc257a5ceb839467abe07953eb3457a2553a2eb21eb9698199b158efbbc4db22fef417e2e32a7f1430fe86fa7ea3a7cc1ca63cf31b
+  data.tar.gz: f69bdd8456fa7cda4e6e00b8767a1d4d3876e25b06c683e7c9909b5a941ca89261ea26ac25a3c0ba772bd9543f8e96e6e4dd57ac95a9c92a1c18e88698ed66ec

data/CHANGELOG.md

@@ -6,6 +6,20 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-05
+
+### Added
+
+- Settings on the wizard's Configuration page, and `plan-driven settings` / `plan-driven setting`:
+  how finely tickets are split (`ticket_split`, `max_tickets`, `max_estimate`), whether schema
+  changes get their own pull requests (`separate_migrations`), pull request size, specs and
+  Cucumber proof, whether agents run only the specs they need while working (`targeted_tests`),
+  and how many agents work at once. Each starts at the recommended practice and explains its
+  trade-off. The choices are written to `config/plan_driven/settings.yml`, which wins over the
+  initializer.
+
+## [0.3.0] - 2026-10-01
+
 ### Added
 
 - Statistics, computed from the audit trail: how long planning, tickets, development and proof
@@ -24,6 +38,8 @@ All notable changes to this project are documented here. The format follows
 - The delivery report has colour: every acceptance criterion's result is a green, red, amber
   or grey pill with a matching edge on its row, failed rows are tinted red, merged tickets are
   marked green, and the Markdown shows ✅, ❌, ⏸️ or ⚠️ before each result.
+- The README and the gem description say up front that the whole process runs from the
+  browser wizard or the terminal, whichever you prefer.
 
 ## [0.2.0] - 2026-09-30
 
@@ -144,6 +160,7 @@ 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.2.0...HEAD
+[Unreleased]: https://github.com/blaz1988/plan-driven/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/blaz1988/plan-driven/compare/v0.2.0...v0.3.0
 [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

@@ -29,44 +29,9 @@ Zagreb. [Need Rails engineers?](#about-rubycode)
 
 ## Watch it deliver a feature
 
-[![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.
 
-<details>
-<summary>Chapters</summary>
+https://github.com/user-attachments/assets/4f3c26e1-437b-4bb5-92c2-31e693859e99
 
-| 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
 
@@ -359,7 +324,7 @@ the audit trail is the same either way. A few things to know:
 
 ### Configuration: connections and the interview
 
-**Configuration**, at the top of every page, has two parts.
+**Configuration**, at the top of every page, has three 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
@@ -393,6 +358,39 @@ whole team gets the same interview, in the wizard and in the terminal. An added
 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.
 
+**Tickets and pull requests** holds the choices that change how work is split and checked. Every
+option starts at the recommended Rails practice, and each one explains what changing it trades
+off, mostly fewer pull requests and tokens against bigger reviews:
+
+| Setting | Recommended | What it decides |
+| --- | --- | --- |
+| `ticket_split` | `small` | One user-visible behaviour per ticket, or related behaviours together (`larger`) |
+| `max_tickets` | no limit | At most this many tickets per plan |
+| `max_estimate` | `5` | The largest ticket, in story points |
+| `separate_migrations` | on | Schema changes in their own pull requests, deployed before the code |
+| `max_pr_changed_lines` | `800` | The largest pull request the guard accepts |
+| `require_specs_in_pr` | on | Every code pull request changes specs or features |
+| `cucumber` | on | Every acceptance criterion is proved by a scenario |
+| `targeted_tests` | on | Agents run only the specs they need while working, the whole suite once at the end |
+| `max_parallel_agents` | `3` | Agents working at the same time |
+
+With `separate_migrations` off, an additive migration goes in the pull request of the first code
+that needs it; removing or renaming a column still gets its own cleanup ticket. Each Save runs
+`plan-driven setting`:
+
+```
+$ bin/plan-driven setting separate_migrations off
+✓ separate_migrations: off
+  Off saves a pull request and an agent run for each migration, but the code and the schema
+  change ship together, so a rollback undoes both.
+$ bin/plan-driven setting separate_migrations --default
+✓ separate_migrations is back to on
+```
+
+The choices are written to `config/plan_driven/settings.yml`, which wins over the initializer.
+Commit it so the whole team plans and reviews the same way. `plan-driven settings` lists every
+option, its value, and where the value comes from.
+
 ## Walkthrough: one feature from idea to merged
 
 This is the run from the demo video, in [Gather](https://github.com/blaz1988/gather), with the
@@ -850,6 +848,8 @@ key such as `PD-1`, and `PLAN/TICKET` is a ticket such as `PD-1/T3`.
 | `stats PLAN` | Where the time went: phases, agents and people, each ticket |
 | `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 |
+| `settings` | How tickets and pull requests are split and checked, and where each value comes from |
+| `setting KEY VALUE [--default]` | Change a setting, or put it back |
 | `configure` | Store keys in `~/.plan_driven/config` |
 | `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 |
@@ -911,6 +911,10 @@ PlanDriven.configure do |config|
   config.spec_paths = %w[spec/ test/ features/]
   config.cucumber = true
   config.features_path = "features"
+  config.ticket_split = "small"                 # or "larger"
+  config.max_tickets = nil                      # nil: no limit
+  config.separate_migrations = true
+  config.targeted_tests = true
 
   # What the model and the agents should know
   config.team_rules = ["Authorization goes through Pundit policies, never in controllers."]
@@ -927,6 +931,10 @@ end
 read-only tools (read, grep, glob, ls), so it reads the application's code while it writes the
 plan and can't change a file.
 
+The settings on the Configuration page (`ticket_split` to `max_parallel_agents`, see
+[Configuration: connections and the interview](#configuration-connections-and-the-interview))
+can be set here too; `config/plan_driven/settings.yml` wins over the initializer.
+
 `config.template` replaces the plan's sections if your template differs.
 
 ## Choosing the coding agents

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

@@ -19,6 +19,13 @@ module PlanDriven
         redirect_to configuration_path(anchor: "questions"), alert: e.message
       end
 
+      def setting
+        job = start(Commands.argv("setting", params.permit(:key, :value, :default).to_h))
+        redirect_to configuration_path(job: job.id, anchor: "setting_#{params[:key]}")
+      rescue ArgumentError => e
+        redirect_to configuration_path(anchor: "settings"), alert: e.message
+      end
+
       def connect
         service = Connections.find(params[:service])
         key = params[:api_key].to_s.strip
@@ -30,9 +37,12 @@ module PlanDriven
         redirect_to configuration_path(anchor: "connections"), alert: e.message
       end
 
+      CHECKS = { "questions" => "questions", "settings" => "settings" }.freeze
+
       def check
-        job = start(Commands.argv(params[:do] == "questions" ? "questions" : "doctor", {}))
-        redirect_to configuration_path(job: job.id, anchor: params[:do] == "questions" ? "questions" : "connections")
+        command = CHECKS.fetch(params[:do].to_s, "doctor")
+        job = start(Commands.argv(command, {}))
+        redirect_to configuration_path(job: job.id, anchor: command == "doctor" ? "connections" : command)
       end
 
       private

data/app/views/plan_driven/wizard/configuration/show.html.erb

@@ -47,6 +47,53 @@
   the panel or the logs. A key in the environment always wins.</p>
 <%= button_to "Check every connection", configuration_check_path(do: "doctor"), form: { style: "display:inline" } %>
 
+<h2 id="settings">Tickets and pull requests</h2>
+<p class="muted">How the plan is split into tickets, and what every pull request has to pass. Each default is the
+  practice we recommend; change one when the trade-off suits your team. Changes are written to
+  <code><%= PlanDriven::Settings::PATH %></code> and win over the initializer; commit it so the whole team works the same way.</p>
+
+<% PlanDriven::Settings::OPTIONS.group_by(&:group).each do |group, options| %>
+  <h3><%= group %></h3>
+  <% options.each do |option| %>
+    <% value = config.public_send(option.key) %>
+    <% origin = PlanDriven::Settings.origin(option.key, config: config) %>
+    <% recommended = PlanDriven::Settings.recommended(option.key) %>
+    <div class="card setting" id="setting_<%= option.key %>">
+      <%= form_with url: configuration_setting_path, method: :post do %>
+        <%= hidden_field_tag :key, option.key, id: nil %>
+        <div class="row" style="justify-content:space-between">
+          <span><strong><%= option.title %></strong> <code><%= option.key %></code>
+            <span class="pill <%= value == recommended ? "good" : "wait" %>">
+              <%= value == recommended ? "recommended" : "recommended: #{PlanDriven::Settings.label(recommended)}" %></span>
+            <% unless origin == "default" %><span class="pill"><%= origin %></span><% end %></span>
+          <span class="row">
+            <% case option.type %>
+            <% when :boolean %>
+              <%= select_tag :value, options_for_select([%w[on on], %w[off off]], PlanDriven::Settings.label(value)),
+                             id: "value_#{option.key}", "aria-label": option.title %>
+            <% when :choice %>
+              <%= select_tag :value, options_for_select(option.choices, value), id: "value_#{option.key}",
+                             "aria-label": option.title %>
+            <% else %>
+              <%= number_field_tag :value, value, min: option.minimum, id: "value_#{option.key}", style: "width:110px",
+                                   placeholder: (option.blank ? "no limit" : nil), "aria-label": option.title %>
+            <% end %>
+            <button type="submit">Save</button>
+            <% if origin == "settings" %>
+              <% initial = config.initializer_value(option.key) %>
+              <button type="submit" name="default" value="1">Back to
+                <%= initial == recommended ? "recommended" : "the initializer's #{PlanDriven::Settings.label(initial)}" %></button>
+            <% end %>
+          </span>
+        </div>
+        <p style="margin:8px 0 4px"><%= option.explanation %></p>
+        <p class="muted" style="margin:0;font-size:13px"><strong>Trade-off:</strong> <%= option.tradeoff %></p>
+      <% end %>
+    </div>
+  <% end %>
+<% end %>
+<%= button_to "List the settings", configuration_check_path(do: "settings"), form: { style: "display:inline" } %>
+
 <h2 id="questions">Interview questions</h2>
 <p class="muted">What <code>plan-driven new</code> and the New plan form ask. Changes are written to
   <code><%= PlanDriven::Interview::PATH %></code>; commit it so the whole team gets the same interview. A new required question

data/config/routes.rb

@@ -11,6 +11,7 @@ PlanDriven::Wizard::Engine.routes.draw do
   post "actor", to: "plans#actor", as: :actor
   get "configuration", to: "configuration#show", as: :configuration
   post "configuration/question", to: "configuration#question", as: :configuration_question
+  post "configuration/setting", to: "configuration#setting", as: :configuration_setting
   post "configuration/connect", to: "configuration#connect", as: :configuration_connect
   post "configuration/check", to: "configuration#check", as: :configuration_check
   get "jobs/:id", to: "jobs#show", as: :job

data/lib/generators/plan_driven/templates/plan_driven.rb

@@ -30,7 +30,10 @@ if defined?(PlanDriven.configure)
     # config.sync_issues = true
     # config.merge_method = "squash"
 
-    # Guards.
+    # Guards. How tickets are split and checked can also be chosen on the wizard's Configuration
+    # page; those choices go to config/plan_driven/settings.yml and win over these.
+    # config.ticket_split = "small"          # or "larger": fewer, bigger tickets
+    # config.separate_migrations = true      # false: additive migrations ship with their code
     # config.estimate_scale = [1, 2, 3, 5, 8]
     # config.max_estimate = 5
     # config.max_pr_changed_lines = 800

data/lib/plan_driven/agent_prompt.rb

@@ -52,6 +52,10 @@ module PlanDriven
     def done_block
       lines = ["# Definition of done"]
       lines << "- Specs cover the change (#{@config.spec_paths.join(", ")}), and the existing suite still passes."
+      if @config.targeted_tests
+        lines << "- While you work, run only the specs and features for the files you change. Run the whole " \
+                 "suite once, before you open the pull request."
+      end
       if @config.cucumber && @ticket.kind != "docs"
         lines << "- Every acceptance criterion has a Cucumber scenario in " \
                  "`#{@config.features_path}/#{@plan.slug}/#{@ticket.key.downcase}.feature`. Tag the feature " \
@@ -65,13 +69,21 @@ module PlanDriven
 
     def rules_block
       rules = ["Follow the conventions already used in this codebase.",
-               "Schema changes only in migration tickets; this ticket is a #{@ticket.kind} ticket.",
+               migration_rule,
                "Migrations are additive and reversible. Never remove or rename a column that code still reads.",
                "Don't edit files under #{@config.docs_path}; they are the approved plan.",
                *@config.team_rules]
       "# Rules\n#{rules.map { |rule| "- #{rule}" }.join("\n")}"
     end
 
+    def migration_rule
+      if @config.separate_migrations || %w[migration backfill].include?(@ticket.kind)
+        "Schema changes only in migration tickets; this ticket is a #{@ticket.kind} ticket."
+      else
+        "If this ticket needs a schema change, add it as a migration in this pull request, with db/schema.rb."
+      end
+    end
+
     def pr_block
       closes = @ticket.issue_number ? "\n- a line `Closes ##{@ticket.issue_number}`" : ""
       <<~TEXT.strip

data/lib/plan_driven/cli/config_commands.rb

@@ -26,6 +26,32 @@ module PlanDriven
         cmd_questions
       end
 
+      def cmd_settings
+        config = PlanDriven.configuration
+        ui.table(%w[Setting Value Source Recommended], Settings::OPTIONS.map do |option|
+          [option.key, Settings.label(config.public_send(option.key)), Settings.origin(option.key, config: config),
+           Settings.label(Settings.recommended(option.key))]
+        end)
+        ui.muted "Changes are in #{Settings::PATH}; commit it so the team works the same way. " \
+                 "`plan-driven setting KEY VALUE` changes one."
+      end
+
+      def cmd_setting(key = nil, value = nil)
+        raise ArgumentError, "Which setting? Pass its key, for example separate_migrations." if key.to_s.empty?
+
+        option = Settings.find(key)
+        if @options[:default]
+          Settings.reset(option.key)
+          ui.success "#{option.key} is back to #{Settings.label(PlanDriven.configuration.public_send(option.key))}"
+        else
+          raise ArgumentError, "Pass a value for #{option.key}, or --default." if value.nil?
+
+          ui.success "#{option.key}: #{Settings.label(Settings.change(option.key, value))}"
+        end
+        ui.muted "  #{option.tradeoff}"
+        cmd_settings
+      end
+
       def cmd_connect(name = nil)
         service = Connections.find(name)
         ui.muted "#{service.title}: #{service.purpose}. Get a key at #{service.url}"

data/lib/plan_driven/cli.rb

@@ -44,6 +44,8 @@ module PlanDriven
       "stats" => ["PLAN", "Where the time went: phases, agents and people, each ticket"],
       "questions" => ["", "The interview's questions, with the team's changes"],
       "question" => ["KEY", "Change or add a question (--title, --ask, --group, --required, --optional, --remove)"],
+      "settings" => ["", "How tickets are split and checked, and what each option trades off"],
+      "setting" => ["KEY VALUE", "Change a setting, or put it back with --default"],
       "configure" => ["", "Store API keys in ~/.plan_driven/config"],
       "connect" => ["SERVICE", "Check a key with cursor, openai, anthropic or github, then store it"],
       "doctor" => ["", "Check keys, repository and connections"]
@@ -128,6 +130,7 @@ module PlanDriven
       parser.on("--required") { options[:required] = true }
       parser.on("--optional") { options[:required] = false }
       parser.on("--remove") { options[:remove] = true }
+      parser.on("--default") { options[:default] = true }
     end
 
     def boot_application

data/lib/plan_driven/configuration.rb

@@ -28,8 +28,8 @@ module PlanDriven
 
     # Coding agents: :cursor (Cursor cloud agents), or :local to run a command such as Claude Code
     # or Codex on this machine, one git worktree per ticket (see LocalAgents).
-    attr_accessor :agent_provider, :agent_command, :agent_model, :base_branch, :max_parallel_agents,
-                  :skip_reviewer_request, :agent_timeout
+    attr_accessor :agent_provider, :agent_command, :agent_model, :base_branch, :skip_reviewer_request,
+                  :agent_timeout
 
     # Dollars per million tokens, by model id, for the cost in the delivery report (see Usage).
     attr_accessor :token_prices
@@ -38,8 +38,18 @@ module PlanDriven
     attr_accessor :github_repository, :sync_issues, :merge_method, :issue_labels
 
     # Guards.
-    attr_accessor :estimate_scale, :max_estimate, :max_pr_changed_lines, :require_specs_in_pr,
-                  :spec_paths, :cucumber, :features_path
+    attr_accessor :estimate_scale, :spec_paths, :features_path
+
+    # How the work is split and checked: ticket_split, max_tickets, max_estimate,
+    # separate_migrations, max_pr_changed_lines, require_specs_in_pr, cucumber, targeted_tests and
+    # max_parallel_agents (see Settings). The team's choices in config/plan_driven/settings.yml
+    # win over what the initializer sets.
+    attr_writer(*Settings.keys)
+
+    Settings::OPTIONS.each do |option|
+      name = option.key
+      define_method(name) { settings.fetch(name) { instance_variable_get("@#{name}") } }
+    end
 
     # Extra rules appended to every agent prompt: your team's conventions, in plain English.
     attr_accessor :team_rules
@@ -68,6 +78,22 @@ module PlanDriven
       @interview_template
     end
 
+    # The values in config/plan_driven/settings.yml, read again when the file changes.
+    def settings
+      file = Settings.path(root_path)
+      stamp = [file.to_s, file.exist? && file.mtime]
+      unless @settings_stamp == stamp
+        @settings = Settings.read(root_path)
+        @settings_stamp = stamp
+      end
+      @settings
+    end
+
+    # What the initializer (or the gem's default) sets, without the settings file.
+    def initializer_value(name)
+      instance_variable_get("@#{Settings.find(name).key}")
+    end
+
     # The template as the initializer set it, before the interview changes.
     def base_template
       return @template if @template
@@ -106,12 +132,17 @@ module PlanDriven
       @issue_labels = %w[plan-driven]
 
       @estimate_scale = [1, 2, 3, 5, 8]
+      @spec_paths = %w[spec/ test/ features/]
+      @features_path = "features"
+
+      @ticket_split = "small"
+      @max_tickets = nil
       @max_estimate = 5
+      @separate_migrations = true
       @max_pr_changed_lines = 800
       @require_specs_in_pr = true
-      @spec_paths = %w[spec/ test/ features/]
       @cucumber = true
-      @features_path = "features"
+      @targeted_tests = true
 
       @team_rules = []
       @pdf_renderer = nil

data/lib/plan_driven/guards/pr_guard.rb

@@ -67,19 +67,28 @@ module PlanDriven
 
       def check_migrations(report)
         added = @files.select { |file| file["filename"].start_with?("db/migrate/") && file["status"] == "added" }
-        if added.any? && !%w[migration backfill].include?(@ticket.kind)
-          report.error("A #{@ticket.kind} ticket adds a migration (#{added.first["filename"]}); " \
-                       "schema changes belong in their own migration ticket")
-        end
+        check_migration_ticket(report, added)
         check_migration_scope(report)
-        if added.empty? && @ticket.kind != "migration"
-          report.pass("No migrations, so the schema stays with the migration tickets")
-        end
         return if added.empty? || paths.any? { |path| path.match?(%r{\Adb/(schema\.rb|structure\.sql)\z}) }
 
         report.warning("A migration was added but db/schema.rb didn't change")
       end
 
+      def check_migration_ticket(report, added)
+        return if %w[migration backfill].include?(@ticket.kind) && added.any?
+
+        if added.empty?
+          return unless @config.separate_migrations && @ticket.kind != "migration"
+
+          report.pass("No migrations, so the schema stays with the migration tickets")
+        elsif @config.separate_migrations
+          report.error("A #{@ticket.kind} ticket adds a migration (#{added.first["filename"]}); " \
+                       "schema changes belong in their own migration ticket")
+        else
+          report.pass("Adds #{added.size} migration(s) with the code that needs them (separate_migrations is off)")
+        end
+      end
+
       def check_migration_scope(report)
         return unless @ticket.kind == "migration"
 

data/lib/plan_driven/guards/ticket_guard.rb

@@ -23,6 +23,7 @@ module PlanDriven
           return report
         end
 
+        check_count(report)
         @tickets.each { |ticket| check_ticket(ticket, report) }
         check_slicing(report)
         check_dependencies(report)
@@ -33,6 +34,14 @@ module PlanDriven
 
       private
 
+      def check_count(report)
+        limit = @config.max_tickets
+        return unless limit && @tickets.size > limit
+
+        report.error("There are #{@tickets.size} tickets, above the limit of #{limit} (max_tickets); " \
+                     "combine related tickets")
+      end
+
       # A model ticket, then a controller ticket, then a view ticket: none of them does anything
       # a user can see, so no scenario can prove its criteria.
       def check_slicing(report)
@@ -70,12 +79,18 @@ module PlanDriven
         report.warning("#{label} has #{criteria.size} acceptance criteria; consider splitting it")
       end
 
+      # With ticket_split larger the limit is the top of the scale. Under max_tickets the breakdown
+      # can't always split a big ticket, so going over the limit is only a warning.
       def check_estimate(ticket, label, report)
         estimate = ticket["estimate"]
+        limit = @config.ticket_split == "larger" ? @config.estimate_scale.max : @config.max_estimate
         if estimate.nil?
           report.error("#{label} has no estimate")
-        elsif estimate > @config.max_estimate
-          report.error("#{label} is estimated at #{estimate}, above the limit of #{@config.max_estimate}; split it")
+        elsif estimate > limit && @config.max_tickets
+          report.warning("#{label} is estimated at #{estimate}, above #{limit}; kept whole to stay within " \
+                         "#{@config.max_tickets} tickets")
+        elsif estimate > limit
+          report.error("#{label} is estimated at #{estimate}, above the limit of #{limit}; split it")
         end
       end
 

data/lib/plan_driven/settings.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+
+module PlanDriven
+  # How the work is split into tickets and checked, as the team chose it with
+  # `plan-driven setting` or the wizard's Configuration page. It lives in the application, in
+  # config/plan_driven/settings.yml, so it is committed and the whole team works the same way:
+  #
+  #     settings:
+  #       separate_migrations: false
+  #       max_tickets: 4
+  #
+  # A value here wins over the initializer. Every default is the practice we recommend; each
+  # option says what changing it gains and what it costs.
+  module Settings
+    PATH = "config/plan_driven/settings.yml"
+    HEADER = "# plan_driven settings, as changed with `plan-driven setting` or the wizard.\n" \
+             "# Commit it: everyone on the team splits and checks the work the same way.\n"
+    ON = %w[true on yes 1].freeze
+    OFF = %w[false off no 0].freeze
+    NONE = %w[none no-limit unlimited].freeze
+
+    Option = Struct.new(:key, :type, :choices, :minimum, :blank, :group, :title, :explanation, :tradeoff,
+                        keyword_init: true)
+
+    OPTIONS = [
+      Option.new(
+        key: "ticket_split", type: :choice, choices: %w[small larger], group: "Tickets",
+        title: "How finely the plan is split",
+        explanation: "small: one thing a user can do per ticket, at most max_estimate points, so every pull " \
+                     "request is small and quick to review. larger: related behaviours share a ticket, up to " \
+                     "the top of the estimate scale.",
+        tradeoff: "larger means fewer pull requests and agent runs, so fewer tokens, but each review is bigger " \
+                  "and a problem in one part holds back the whole ticket."
+      ),
+      Option.new(
+        key: "max_tickets", type: :integer, minimum: 1, blank: true, group: "Tickets",
+        title: "At most this many tickets per plan",
+        explanation: "Blank means no limit, and the plan decides. With a limit, the breakdown must fit in it, " \
+                     "and a ticket above max_estimate is a warning instead of an error.",
+        tradeoff: "A low limit gives fewer, larger pull requests and fewer agent runs; reviews get bigger."
+      ),
+      Option.new(
+        key: "max_estimate", type: :integer, minimum: 1, group: "Tickets",
+        title: "Largest ticket, in story points",
+        explanation: "A ticket estimated above this must be split (with ticket_split small).",
+        tradeoff: "Higher means fewer, bigger tickets."
+      ),
+      Option.new(
+        key: "separate_migrations", type: :boolean, group: "Pull requests",
+        title: "Schema changes in their own pull requests",
+        explanation: "On: every schema change is a migration ticket of its own, merged and deployed before the " \
+                     "code that uses it. That is the zero-downtime practice: each migration is reviewed on its " \
+                     "own, and can be rolled out and rolled back separately. Off: an additive migration goes in " \
+                     "the same pull request as the first code that needs it. Removing or renaming a column " \
+                     "always keeps its own cleanup ticket.",
+        tradeoff: "Off saves a pull request and an agent run for each migration, but the code and the schema " \
+                  "change ship together, so a rollback undoes both."
+      ),
+      Option.new(
+        key: "max_pr_changed_lines", type: :integer, minimum: 50, group: "Pull requests",
+        title: "Largest pull request, in changed lines",
+        explanation: "The pull request guard blocks a pull request that adds and removes more lines than this.",
+        tradeoff: "Higher allows bigger tickets; past a few hundred lines, reviews get less careful."
+      ),
+      Option.new(
+        key: "require_specs_in_pr", type: :boolean, group: "Quality",
+        title: "Every pull request changes specs",
+        explanation: "The pull request guard blocks a code pull request that doesn't add or change a spec or " \
+                     "feature file.",
+        tradeoff: "Off lets untested changes reach review; the reviewer has to catch them."
+      ),
+      Option.new(
+        key: "cucumber", type: :boolean, group: "Quality",
+        title: "Prove every acceptance criterion with a Cucumber scenario",
+        explanation: "Each criterion needs a scenario tagged with it, the proof step runs them on the merged " \
+                     "code, and the delivery report shows the result of every criterion.",
+        tradeoff: "Off saves the agents writing scenarios, but nothing proves the criteria automatically and " \
+                  "the delivery report has no proof."
+      ),
+      Option.new(
+        key: "targeted_tests", type: :boolean, group: "Agents",
+        title: "Agents run the specs they need while they work",
+        explanation: "While working, an agent runs only the specs for the files it changes, then the whole suite " \
+                     "once before it opens the pull request. CI and the guards still check everything.",
+        tradeoff: "The biggest token saving: the output of every full-suite run stays in the agent's context. " \
+                  "Off: agents run the whole suite as often as they like."
+      ),
+      Option.new(
+        key: "max_parallel_agents", type: :integer, minimum: 1, group: "Agents",
+        title: "Agents working at the same time",
+        explanation: "How many tickets are handed to agents at once. Tickets still wait for the ones they " \
+                     "depend on.",
+        tradeoff: "More is faster, but more pull requests wait for review at the same time."
+      )
+    ].freeze
+
+    module_function
+
+    def keys
+      OPTIONS.map(&:key)
+    end
+
+    def find(key)
+      OPTIONS.find { |option| option.key == key.to_s } or
+        raise ArgumentError, "Unknown setting #{key.inspect}. One of: #{keys.join(", ")}"
+    end
+
+    def path(root = PlanDriven.configuration.root_path)
+      Pathname(root).join(PATH)
+    end
+
+    def read(root = PlanDriven.configuration.root_path)
+      file = path(root)
+      return {} unless file.exist?
+
+      data = YAML.safe_load(file.read) || {}
+      values = data.is_a?(Hash) ? data["settings"] : nil
+      return {} unless values.is_a?(Hash)
+
+      values.to_h { |key, value| [key.to_s, cast(find(key), value)] }
+    rescue Psych::Exception => e
+      raise ConfigurationError, "#{PATH} isn't valid YAML: #{e.message}"
+    rescue ArgumentError => e
+      raise ConfigurationError, "#{PATH}: #{e.message}"
+    end
+
+    # Sets one option from what was typed ("off", "4", "none"...). Returns the stored value.
+    def change(key, value, root: PlanDriven.configuration.root_path)
+      option = find(key)
+      values = read(root)
+      values[option.key] = cast(option, value)
+      write(values, root)
+      values[option.key]
+    end
+
+    # Back to what the initializer (or the gem) sets.
+    def reset(key, root: PlanDriven.configuration.root_path)
+      option = find(key)
+      values = read(root)
+      raise ArgumentError, "#{option.key} isn't changed in #{PATH}" unless values.key?(option.key)
+
+      values.delete(option.key)
+      write(values, root)
+    end
+
+    def origin(key, config: PlanDriven.configuration)
+      return "settings" if config.settings.key?(key.to_s)
+
+      config.initializer_value(key) == recommended(key) ? "default" : "initializer"
+    end
+
+    def recommended(key)
+      Configuration.new.initializer_value(key)
+    end
+
+    def label(value)
+      case value
+      when true then "on"
+      when false then "off"
+      when nil then "no limit"
+      else value.to_s
+      end
+    end
+
+    def cast(option, value)
+      text = value.to_s.strip.downcase
+      case option.type
+      when :boolean then boolean(option, value, text)
+      when :choice
+        option.choices.include?(text) or
+          raise ArgumentError, "#{option.key} is one of #{option.choices.join(", ")}, not #{value.inspect}"
+        text
+      else integer(option, value, text)
+      end
+    end
+
+    def boolean(option, value, text)
+      return value if [true, false].include?(value)
+      return true if ON.include?(text)
+      return false if OFF.include?(text)
+
+      raise ArgumentError, "#{option.key} is on or off, not #{value.inspect}"
+    end
+
+    def integer(option, value, text)
+      return if option.blank && (value.nil? || text.empty? || NONE.include?(text))
+
+      number = Integer(text, exception: false)
+      unless number && number >= option.minimum
+        raise ArgumentError, "#{option.key} is a whole number of at least #{option.minimum}" \
+                             "#{" (or none)" if option.blank}, not #{value.inspect}"
+      end
+      number
+    end
+
+    def write(values, root)
+      file = path(root)
+      return file.tap { FileUtils.rm_f(file) } if values.empty?
+
+      FileUtils.mkdir_p(file.dirname)
+      file.write(HEADER + YAML.dump("settings" => values).delete_prefix("---\n"))
+      file
+    end
+  end
+end

data/lib/plan_driven/ticket_generator.rb

@@ -65,11 +65,10 @@ module PlanDriven
 
         Order the work the way zero-downtime Rails changes ship: migrations that add, dual
         writes, backfills, switching reads, then cleanup that removes. A ticket may only depend
-        on tickets before it. Keep tickets small: at most #{@config.max_estimate} points on the
-        scale #{@config.estimate_scale.join(", ")}. Schema changes get their own migration tickets.
-        Split code by behaviour, not by layer: each code ticket delivers one thing a user can do,
-        with its model, service, controller, view and specs together, so its acceptance criteria
-        can be proven by Cucumber scenarios.
+        on tickets before it. #{size_rule} #{migration_rule}
+        Split code by behaviour, not by layer: each code ticket delivers #{behaviour_rule}, with its
+        model, service, controller, view and specs together, so its acceptance criteria can be
+        proven by Cucumber scenarios.#{count_rule}
 
         Reply with one JSON object: {"tickets": [ ... ]}. Each ticket has:
         #{FIELDS}
@@ -78,6 +77,35 @@ module PlanDriven
 
     private
 
+    def size_rule
+      scale = @config.estimate_scale
+      return "Keep tickets small: at most #{@config.max_estimate} points on the scale #{scale.join(", ")}." if small?
+
+      "Group related behaviours into one ticket, up to #{scale.max} points on the scale #{scale.join(", ")}, " \
+        "so the plan needs as few pull requests as it can."
+    end
+
+    def migration_rule
+      return "Schema changes get their own migration tickets." if @config.separate_migrations
+
+      "Put each additive schema change in the same ticket as the first code that needs it, as a migration in " \
+        "that pull request. Removing or renaming a column still gets its own cleanup ticket, after everything " \
+        "that stops using it."
+    end
+
+    def behaviour_rule
+      small? ? "one thing a user can do" : "a group of related things a user can do"
+    end
+
+    def count_rule
+      limit = @config.max_tickets
+      limit ? "\nUse at most #{limit} ticket#{"s" unless limit == 1} for the whole plan." : ""
+    end
+
+    def small?
+      @config.ticket_split != "larger"
+    end
+
     def request(plan)
       sections = plan.sections.map { |key, value| "## #{@config.template[key]&.title || key}\n#{value}" }
       "Plan #{plan.key}: #{plan.title}\n\n#{sections.join("\n\n")}"

data/lib/plan_driven/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PlanDriven
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/plan_driven/wizard.rb

@@ -32,6 +32,8 @@ module PlanDriven
         "feedback" => ->(p) { [ticket(p), required(p, "feedback")] },
         "questions" => ->(_p) { [] },
         "question" => ->(p) { [question_key(p), *question_flags(p)] },
+        "settings" => ->(_p) { [] },
+        "setting" => ->(p) { setting_args(p) },
         # The key itself goes on stdin, so it's never in the command line or the panel.
         "connect" => ->(p) { [Connections.find(required(p, "service")).name] }
       }.merge(PLAN_ONLY.to_h { |name| [name, ->(p) { [plan(p)] }] }).freeze
@@ -91,6 +93,14 @@ module PlanDriven
         end
       end
 
+      def setting_args(params)
+        key = Settings.find(required(params, "key")).key
+        return [key, "--default"] if params["default"].to_s == "1"
+
+        value = params["value"].to_s.strip
+        [key, value.empty? ? "none" : value]
+      end
+
       def question_flags(params)
         return ["--remove"] if params["remove"].to_s == "1"
 

data/lib/plan_driven.rb

@@ -10,6 +10,7 @@ require "set"
 require_relative "plan_driven/version"
 require_relative "plan_driven/errors"
 require_relative "plan_driven/credentials"
+require_relative "plan_driven/settings"
 require_relative "plan_driven/configuration"
 require_relative "plan_driven/template"
 require_relative "plan_driven/interview"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: plan_driven
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Ivan Blažević
 bindir: exe
 cert_chain: []
-date: 2026-10-01 00:00:00.000000000 Z
+date: 2026-10-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -134,6 +134,7 @@ files:
 - lib/plan_driven/renderer/style.css
 - lib/plan_driven/repository.rb
 - lib/plan_driven/schema_context.rb
+- lib/plan_driven/settings.rb
 - lib/plan_driven/statistics.rb
 - lib/plan_driven/template.rb
 - lib/plan_driven/ticket_generator.rb
@@ -167,6 +168,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.4
 specification_version: 4
-summary: From implementation plan to merged, tested pull requests, driven from the
-  browser or the terminal.
+summary: 'From implementation plan to merged, tested pull requests: AI agents write
+  the code, developers review, guardrails and tests protect quality. Browser wizard
+  or CLI.'
 test_files: []