rubyn-code 0.5.0 → 0.7.0

data/lib/rubyn_code/tools/spawn_agent.rb

@@ -9,8 +9,9 @@ module RubynCode
       TOOL_NAME = 'spawn_agent'
       DESCRIPTION = 'Spawn an isolated sub-agent to handle a task. The sub-agent gets its own ' \
                     "fresh context, works independently, and returns only a summary. Use 'explore' " \
-                    "type for research/reading, 'worker' type for writing code/files. The sub-agent " \
-                    'shares the filesystem but not your conversation.'
+                    "type for research/reading, 'worker' type for writing code/files, or the name " \
+                    'of any custom agent defined in .rubyn-code/agents/. The sub-agent shares the ' \
+                    'filesystem but not your conversation.'
       PARAMETERS = {
         prompt: {
           type: :string,
@@ -19,76 +20,73 @@ module RubynCode
         },
         agent_type: {
           type: :string,
-          description: "Type of agent: 'explore' (read-only) or 'worker' (full write access). Default: explore",
-          required: false,
-          enum: %w[explore worker]
+          description: "Agent type: 'explore' (read-only), 'worker' (full write access), or a " \
+                       'custom agent name from .rubyn-code/agents/. Default: explore',
+          required: false
         }
       }.freeze
       RISK_LEVEL = :execute
 
+      READ_TOOLS = %w[read_file glob grep bash load_skill memory_search].freeze
+      BLOCKED_TOOLS = %w[spawn_agent send_message read_inbox compact memory_write].freeze
+
       # These get injected by the executor or the REPL
       attr_writer :llm_client, :on_status
 
       def execute(prompt:, agent_type: 'explore')
-        type = agent_type.to_sym
+        agent = resolve_agent(agent_type)
         callback = @on_status || method(:default_status)
         @tool_count = 0
 
-        callback.call(:started, "Spawning #{type} agent...")
+        callback.call(:started, "Spawning #{agent.name} agent...")
 
-        tools = tools_for_type(type)
-        result, hit_limit = run_sub_agent(
-          prompt: prompt, tools: tools, type: type, callback: callback
-        )
+        tools = tools_for(agent)
+        result, hit_limit = run_sub_agent(prompt: prompt, tools: tools, agent: agent, callback: callback)
 
         callback.call(:done, "Agent finished (#{@tool_count} tool calls).")
 
         summary = RubynCode::SubAgents::Summarizer.call(result, max_length: 3000)
-        format_agent_result(type, summary, hit_limit)
+        format_agent_result(agent.name, summary, hit_limit)
       end
 
       private
 
-      def format_agent_result(type, summary, hit_limit)
+      # Resolve the requested type via the catalog, falling back to explore
+      # for an unknown name so a typo degrades gracefully instead of erroring.
+      def resolve_agent(agent_type)
+        catalog = RubynCode::SubAgents::Catalog.new(project_root: project_root)
+        catalog.get(agent_type) || catalog.get('explore')
+      end
+
+      def format_agent_result(name, summary, hit_limit)
         if hit_limit
-          "## Sub-Agent Result (#{type}) — INCOMPLETE (reached #{@tool_count} tool calls)\n\n" \
+          "## Sub-Agent Result (#{name}) — INCOMPLETE (reached #{@tool_count} tool calls)\n\n" \
             'The sub-agent ran out of turns before finishing. Here is what it accomplished so far:' \
             "\n\n#{summary}"
         else
-          "## Sub-Agent Result (#{type})\n\n#{summary}"
-        end
-      end
-
-      def max_iterations_for(type)
-        if type == :explore
-          Config::Defaults::MAX_EXPLORE_AGENT_ITERATIONS
-        else
-          Config::Defaults::MAX_SUB_AGENT_ITERATIONS
+          "## Sub-Agent Result (#{name})\n\n#{summary}"
         end
       end
 
       # Returns [result_text, hit_limit] tuple
-      def run_sub_agent(prompt:, tools:, type:, callback:)
+      def run_sub_agent(prompt:, tools:, agent:, callback:)
         conversation = RubynCode::Agent::Conversation.new
         conversation.add_user_message(prompt)
 
-        max_iterations = max_iterations_for(type)
         iteration = 0
         last_text = nil
 
         loop do
-          return finish_at_limit(conversation, type, last_text) if iteration >= max_iterations
+          return finish_at_limit(conversation, agent, last_text) if iteration >= agent.max_iterations
 
-          last_text, done = process_iteration(
-            conversation, tools, type, callback, last_text
-          )
+          last_text, done = process_iteration(conversation, tools, agent, callback, last_text)
           return [last_text || '', false] if done
 
           iteration += 1
         end
       end
 
-      def finish_at_limit(conversation, type, last_text)
+      def finish_at_limit(conversation, agent, last_text)
         conversation.add_user_message(
           'You have reached your turn limit. Summarize everything you found or ' \
           'accomplished so far. Be thorough — this is your last chance to report back.'
@@ -96,17 +94,17 @@ module RubynCode
         response = @llm_client.chat(
           messages: conversation.to_api_format,
           tools: [],
-          system: sub_agent_system_prompt(type)
+          system: agent.system_prompt
         )
         summary = extract_text(response)
         [summary.empty? ? (last_text || '') : summary, true]
       end
 
-      def process_iteration(conversation, tools, type, callback, last_text)
+      def process_iteration(conversation, tools, agent, callback, last_text)
         response = @llm_client.chat(
           messages: conversation.to_api_format,
           tools: tools,
-          system: sub_agent_system_prompt(type)
+          system: agent.system_prompt
         )
 
         content = response_content(response)
@@ -117,22 +115,22 @@ module RubynCode
         conversation.add_assistant_message(content)
         return [last_text, true] if tool_calls.empty?
 
-        execute_sub_agent_tools(tool_calls, conversation, type, callback)
+        execute_sub_agent_tools(tool_calls, conversation, agent, callback)
         [last_text, false]
       end
 
-      def execute_sub_agent_tools(tool_calls, conversation, type, callback)
+      def execute_sub_agent_tools(tool_calls, conversation, agent, callback)
         tool_calls.each do |tc|
           name, input, id = extract_tool_call(tc)
           @tool_count += 1
           callback.call(:tool, name.to_s)
 
-          run_single_tool(name, input, id, conversation, type)
+          run_single_tool(name, input, id, conversation, agent)
         end
       end
 
-      def run_single_tool(name, input, id, conversation, type)
-        if %w[spawn_agent].include?(name)
+      def run_single_tool(name, input, id, conversation, agent)
+        if name == 'spawn_agent'
           conversation.add_tool_result(
             id, name, 'Error: Sub-agents cannot spawn other agents.', is_error: true
           )
@@ -140,9 +138,9 @@ module RubynCode
         end
 
         tool_class = RubynCode::Tools::Registry.get(name)
-        if type == :explore && tool_class.risk_level != :read
+        if agent.read_only? && tool_class.risk_level != :read
           conversation.add_tool_result(
-            id, name, 'Error: Explore agents can only use read-only tools.', is_error: true
+            id, name, "Error: #{agent.name} agents can only use read-only tools.", is_error: true
           )
           return
         end
@@ -154,31 +152,18 @@ module RubynCode
         conversation.add_tool_result(id, name, "Error: #{e.message}", is_error: true)
       end
 
-      def tools_for_type(type)
+      # The tool allowlist: explicit list from a custom agent, else the
+      # access-based default (read-only set or everything-minus-blocked).
+      def tools_for(agent)
         all_tools = RubynCode::Tools::Registry.tool_definitions
-        blocked = %w[spawn_agent send_message read_inbox compact memory_write]
-
-        if type == :explore
-          read_tools = %w[read_file glob grep bash load_skill memory_search]
-          all_tools.select { |t| read_tools.include?(t[:name]) }
-        else
-          all_tools.reject { |t| blocked.include?(t[:name]) }
-        end
-      end
 
-      def sub_agent_system_prompt(type)
-        base = 'You are a Rubyn sub-agent. Complete your task efficiently and ' \
-               'return a clear summary of what you found or did.'
-
-        case type
-        when :explore
-          "#{base}\nYou have read-only access. Search, read files, and analyze. " \
-          'Do NOT attempt to write or modify anything.'
-        when :worker
-          "#{base}\nYou have full read/write access. Make the changes needed, " \
-          'run tests if appropriate, and report what you did.'
+        if agent.tool_names && !agent.tool_names.empty?
+          allowed = agent.tool_names - BLOCKED_TOOLS
+          all_tools.select { |t| allowed.include?(t[:name]) }
+        elsif agent.read_only?
+          all_tools.select { |t| READ_TOOLS.include?(t[:name]) }
         else
-          base
+          all_tools.reject { |t| BLOCKED_TOOLS.include?(t[:name]) }
         end
       end
 

data/lib/rubyn_code/tools/spawn_teammate.rb

@@ -25,13 +25,18 @@ module RubynCode
           type: :string,
           description: 'Initial task or instruction for the teammate',
           required: true
+        },
+        parent_agent_id: {
+          type: :string,
+          description: 'ID of the parent agent spawning this teammate (for lineage tracking)',
+          required: false
         }
       }.freeze
       RISK_LEVEL = :execute
 
       attr_writer :llm_client, :on_status, :db
 
-      def execute(name:, role:, prompt:)
+      def execute(name:, role:, prompt:, parent_agent_id: nil)
         callback = @on_status || method(:default_status)
 
         raise Error, 'LLM client not available' unless @llm_client
@@ -40,7 +45,7 @@ module RubynCode
         mailbox = Teams::Mailbox.new(@db)
         manager = Teams::Manager.new(@db, mailbox: mailbox)
 
-        teammate = manager.spawn(name: name, role: role)
+        teammate = manager.spawn(name: name, role: role, parent_agent_id: parent_agent_id)
         callback.call(:started, "Spawning teammate '#{name}' as #{role}...")
 
         Thread.new do

data/lib/rubyn_code/tools/web_fetch.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'faraday'
 require_relative 'base'
 require_relative 'registry'
 
@@ -76,6 +75,7 @@ module RubynCode
       end
 
       def build_connection
+        require 'faraday'
         Faraday.new do |f|
           f.options.timeout = 30
           f.options.open_timeout = 10

data/lib/rubyn_code/tools/web_search.rb

@@ -3,7 +3,6 @@
 require 'open3'
 require 'cgi'
 require 'json'
-require 'faraday'
 require_relative 'base'
 require_relative 'registry'
 
@@ -112,6 +111,7 @@ module RubynCode
       end
 
       def brave_request(query, num_results)
+        require 'faraday'
         Faraday.get('https://api.search.brave.com/res/v1/web/search') do |req|
           req.params['q'] = query
           req.params['count'] = num_results
@@ -135,6 +135,7 @@ module RubynCode
       end
 
       def tavily_request(query, num_results)
+        require 'faraday'
         Faraday.post('https://api.tavily.com/search') do |req|
           req.headers['Content-Type'] = 'application/json'
           req.body = JSON.generate(
@@ -156,6 +157,7 @@ module RubynCode
       end
 
       def serpapi_request(query, num_results)
+        require 'faraday'
         Faraday.get('https://serpapi.com/search.json') do |req|
           req.params['q'] = query
           req.params['num'] = num_results
@@ -175,6 +177,7 @@ module RubynCode
       end
 
       def google_request(query, num_results)
+        require 'faraday'
         Faraday.get('https://www.googleapis.com/customsearch/v1') do |req|
           req.params['q'] = query
           req.params['num'] = [num_results, 10].min

data/lib/rubyn_code/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubynCode
-  VERSION = '0.5.0'
+  VERSION = '0.7.0'
 end

data/lib/rubyn_code.rb

@@ -16,11 +16,16 @@ module RubynCode
   # rather than a successful tool call returning a string like "denied".
   class UserDeniedError < Error; end
 
-  # Infrastructure
-  autoload :Config, 'rubyn_code/config/settings'
+  # Chisel — opt-in "write the minimum that works" enforcement (off by default)
+  autoload :Chisel, 'rubyn_code/chisel'
 
+  # Infrastructure
   module Config
+    autoload :Settings, 'rubyn_code/config/settings'
+    autoload :Defaults, 'rubyn_code/config/defaults'
+    autoload :ProjectConfig, 'rubyn_code/config/project_config'
     autoload :ProjectProfile, 'rubyn_code/config/project_profile'
+    autoload :Validator, 'rubyn_code/config/validator'
   end
 
   # Database
@@ -49,6 +54,7 @@ module RubynCode
       autoload :Base, 'rubyn_code/llm/adapters/base'
       autoload :JsonParsing, 'rubyn_code/llm/adapters/json_parsing'
       autoload :PromptCaching, 'rubyn_code/llm/adapters/prompt_caching'
+      autoload :TokenCaching, 'rubyn_code/llm/adapters/token_caching'
       autoload :Anthropic, 'rubyn_code/llm/adapters/anthropic'
       autoload :AnthropicCompatible, 'rubyn_code/llm/adapters/anthropic_compatible'
       autoload :AnthropicStreaming, 'rubyn_code/llm/adapters/anthropic_streaming'
@@ -153,6 +159,14 @@ module RubynCode
   module SubAgents
     autoload :Runner, 'rubyn_code/sub_agents/runner'
     autoload :Summarizer, 'rubyn_code/sub_agents/summarizer'
+    autoload :AgentType, 'rubyn_code/sub_agents/agent_type'
+    autoload :Catalog, 'rubyn_code/sub_agents/catalog'
+  end
+
+  # Checkpoints (/rewind)
+  module Checkpoint
+    autoload :Manager, 'rubyn_code/checkpoint/manager'
+    autoload :Hook, 'rubyn_code/checkpoint/hook'
   end
 
   # Layer 7: Tasks
@@ -162,6 +176,13 @@ module RubynCode
     autoload :Models, 'rubyn_code/tasks/models'
   end
 
+  # Layer 7b: Megaplan
+  module Megaplan
+    autoload :PlanProposer, 'rubyn_code/megaplan/plan_proposer'
+    autoload :InterviewSession, 'rubyn_code/megaplan/interview_session'
+    autoload :CiRecovery, 'rubyn_code/megaplan/ci_recovery'
+  end
+
   # Layer 8: Background
   module Background
     autoload :Worker, 'rubyn_code/background/worker'
@@ -174,6 +195,7 @@ module RubynCode
     autoload :Manager, 'rubyn_code/teams/manager'
     autoload :Mailbox, 'rubyn_code/teams/mailbox'
     autoload :Teammate, 'rubyn_code/teams/teammate'
+    autoload :AgentRegistry, 'rubyn_code/teams/agent_registry'
   end
 
   # Layer 10: Protocols
@@ -215,6 +237,17 @@ module RubynCode
     autoload :Runner, 'rubyn_code/hooks/runner'
     autoload :BuiltIn, 'rubyn_code/hooks/built_in'
     autoload :UserHooks, 'rubyn_code/hooks/user_hooks'
+    autoload :GoalHook, 'rubyn_code/hooks/goal_hook'
+    autoload :EventMap, 'rubyn_code/hooks/event_map'
+    autoload :Response, 'rubyn_code/hooks/response'
+    autoload :SettingsJsonLoader, 'rubyn_code/hooks/settings_json_loader'
+    autoload :SubprocessExecutor, 'rubyn_code/hooks/subprocess_executor'
+    autoload :ExternalDispatcher, 'rubyn_code/hooks/external_dispatcher'
+  end
+
+  # Session goals (/goal)
+  module Goal
+    autoload :Evaluator, 'rubyn_code/goal/evaluator'
   end
 
   # Layer 15: MCP
@@ -223,6 +256,7 @@ module RubynCode
     autoload :StdioTransport, 'rubyn_code/mcp/stdio_transport'
     autoload :SSETransport, 'rubyn_code/mcp/sse_transport'
     autoload :ToolBridge, 'rubyn_code/mcp/tool_bridge'
+    autoload :ServerExtrasBridge, 'rubyn_code/mcp/server_extras_bridge'
     autoload :Config, 'rubyn_code/mcp/config'
   end
 
@@ -233,6 +267,7 @@ module RubynCode
     autoload :InstinctMethods, 'rubyn_code/learning/instinct'
     autoload :Injector, 'rubyn_code/learning/injector'
     autoload :Shortcut, 'rubyn_code/learning/shortcut'
+    autoload :Porter, 'rubyn_code/learning/porter'
   end
 
   # IDE (VS Code extension server)
@@ -264,6 +299,8 @@ module RubynCode
     autoload :Setup, 'rubyn_code/cli/setup'
     autoload :FirstRun, 'rubyn_code/cli/first_run'
     autoload :DaemonRunner, 'rubyn_code/cli/daemon_runner'
+    autoload :LoopRunner, 'rubyn_code/cli/loop_runner'
+    autoload :MentionExpander, 'rubyn_code/cli/mention_expander'
     autoload :VersionCheck, 'rubyn_code/cli/version_check'
 
     # Slash Command System
@@ -296,6 +333,20 @@ module RubynCode
       autoload :InstallSkills, 'rubyn_code/cli/commands/install_skills'
       autoload :RemoveSkills, 'rubyn_code/cli/commands/remove_skills'
       autoload :Skills, 'rubyn_code/cli/commands/skills'
+      autoload :Megaplan, 'rubyn_code/cli/commands/megaplan'
+      autoload :Goal, 'rubyn_code/cli/commands/goal'
+      autoload :Loop, 'rubyn_code/cli/commands/loop'
+      autoload :Agents, 'rubyn_code/cli/commands/agents'
+      autoload :CommandTemplate, 'rubyn_code/cli/commands/command_template'
+      autoload :CustomCommand, 'rubyn_code/cli/commands/custom_command'
+      autoload :CustomLoader, 'rubyn_code/cli/commands/custom_loader'
+      autoload :Learning, 'rubyn_code/cli/commands/learning'
+      autoload :Rewind, 'rubyn_code/cli/commands/rewind'
+      autoload :Chisel, 'rubyn_code/cli/commands/chisel'
+      autoload :ChiselReview, 'rubyn_code/cli/commands/chisel_review'
+      autoload :ChiselAudit, 'rubyn_code/cli/commands/chisel_audit'
+      autoload :ChiselDebt, 'rubyn_code/cli/commands/chisel_debt'
+      autoload :ChiselGain, 'rubyn_code/cli/commands/chisel_gain'
     end
   end
 

data/skills/megaplan/megaplan.md

@@ -0,0 +1,156 @@
+---
+name: megaplan
+description: Phased project planning. Interview the user one question at a time, then scaffold numbered phase folders (requirements/design/tasks). Trigger phrases include "megaplan", "mega plan", "plan phases", "phase this out", or any feature spanning 3+ PRs.
+tags:
+  - planning
+  - process
+  - phases
+  - megaplan
+triggers:
+  - megaplan
+  - mega plan
+  - plan phases
+  - phase this out
+---
+
+# Megaplan — Phased Project Planning
+
+Ship in vertical slices. Each phase merges cleanly and leaves the trunk working.
+
+## Don't use for
+
+- Single-PR features — just do them
+- Pure research / exploration — nothing shippable
+- Work where the *shape* (not just the details) will change weekly — plan something smaller first
+
+## Design principles to apply throughout
+
+Hold the work to these when proposing phases and reviewing each `design.md`:
+
+- **Vertical slices, not horizontal.** A phase touches every layer it needs to be end-to-end testable. The classic anti-pattern this skill exists to prevent: "Phase 1: all models. Phase 2: all controllers. Phase 3: all views." Trunk is unshippable until Phase 3 and Phase 2 has nothing to test. Instead: "Phase 1: one feature, full-stack, behind a flag."
+- **SOLID, applied lightly.** Single Responsibility and Dependency Inversion are the two that actually bite at the phase-design level. The others usually take care of themselves if those two are clean.
+- **KISS.** Skip the abstraction until you have two concrete callers. Three similar lines beat a premature framework. Inline before you extract.
+- **Justify abstractions.** Every new module/service/class in `design.md` needs a one-sentence reason it exists separately. If you can't write it, inline the code.
+
+## The workflow
+
+### 1. Interview first
+
+Don't propose phases until you understand the shape. Walk through the agenda below **one question per turn** — never dump the full list in a single message. The point is to let the operator steer at every step.
+
+**How to ask:**
+
+- **One topic per turn.** Pick the next unanswered item from the agenda. Ask only about that.
+- **Number the options.** Whenever the question has 2+ plausible answers, present them as a numbered list so the operator can reply with just the number. Include a **recommended** pick (the one you'd default to given what you know so far) and say *why* it's the recommendation in one short line.
+- **Restate locked-in answers at the top of each follow-up.** A running "Decisions so far:" block of one-line bullets, so the operator can spot drift and you can spot contradictions.
+- **Open-ended questions are fine** when no obvious option set exists (e.g. "What's the end-state in user-facing terms?"). Still ask one at a time.
+- **Stop when you're 95% sure of the shape.** Don't run the whole agenda for its own sake — skip topics that are already obvious from context. The agenda is a checklist *for you*, not a script to read aloud.
+
+**Agenda (interviewer's checklist, not a dump):**
+
+- **Goal** — end state in user-facing terms
+- **Constraints** — deadlines, infra limits, things you can't break
+- **Existing assets** — what's there to build on or rip out
+- **Natural ordering** — dependency sequence (data → API → UI)?
+- **External dependencies** — other teams, third-party APIs, infra access, design review. These reorder phases more than technical concerns do.
+- **Destructive operations** — schema drops, data deletes, deprecations. These need their own phase with an explicit rollback note.
+- **Test strategy** — what coverage is needed?
+- **Done-per-phase** — minimum manual test that proves each phase shipped?
+
+### 2. Propose phases, get agreement
+
+A good phase:
+- Is a vertical slice — testable end-to-end at merge time
+- Ships independently — trunk works at every boundary
+- Has a clear definition of done
+- Is roughly 1–3 days of focused work
+- Has a name that survives the PR title. If it adds *and* removes, capture both (e.g. "TX-Only Checkout + Geofencing Removal").
+
+A good phase list:
+- 3–8 phases for most projects
+- Ordered by dependency, not priority
+- Destructive operations isolated to their own phase
+- Ends with a phase that visibly delivers the goal
+
+Propose as a numbered outline. Let the user reorder, merge, or split before any files exist.
+
+### 3. Scaffold the structure
+
+```
+docs/
+  README.md                # roadmap tracker
+  NN-slug/
+    requirements.md        # user stories + acceptance criteria
+    design.md              # architecture + interfaces + test strategy
+    tasks.md               # numbered checklist
+```
+
+Numbering: zero-padded (`01-`, `02-`). Slugs: kebab-case, ≤4 words.
+
+Default: fully scaffold the *current* phase; future phases stay as one-liners in `README.md` until you start them. Later phases mutate based on what's learned early — don't pre-write what you'll have to rewrite.
+
+### 4. Implement phase-by-phase
+
+For each phase:
+1. **Read the running architecture doc first** (`CLAUDE.md` or equivalent). That's how you don't repeat decisions or miss constraints from earlier phases.
+2. Branch off main: `git checkout -b phase-NN-slug`
+3. Work `tasks.md` top-to-bottom, checking subtasks as you go
+4. Commit at section boundaries: `Phase N (M/X): description` — where `M` is the current section number and `X` is the total number of sections in `tasks.md`
+5. Run full test suite + lint + format at each commit boundary
+6. When `tasks.md` is fully checked, push and open a PR (see PR description shape below)
+7. After merge: check the box in `docs/README.md`, update the running architecture doc if anything moved
+
+## File templates
+
+### requirements.md
+
+Use RFC 2119 SHALL/SHOULD/MAY language for acceptance criteria. They're contracts — write them as something a QA tester could check.
+
+Sections: Overview, Glossary, Requirements (per requirement: user story + numbered SHALL criteria), Out of scope.
+
+### design.md
+
+Sections: Overview, Architecture (each component gets Responsibility, Collaborators, "Why not inline?"), Data model changes, Test strategy, Migration / rollout, Future enhancements.
+
+Every new abstraction needs a justification line. If you can't answer "why not inline this", inline it.
+
+### tasks.md
+
+Sections (`## [ ] N. <name>`) and tasks (`- [ ] N.M ...`) both get checkboxes. A section ticks only when every task under it ticks. Reference requirements by ID (`refs Req 1.1`) so coverage gaps are visible. Always end with a Validation section that includes the manual smoke flow.
+
+## PR description shape
+
+Three bullets. Don't pad them.
+
+```
+## What shipped
+- <user-facing capability or removal>
+
+## What proves it
+- <new tests, smoke flow, manual check>
+
+## What's deferred
+- <link to later phase, or "none">
+```
+
+## Patterns and pitfalls
+
+**Patterns to keep:**
+- **Branch per phase:** `phase-NN-slug` — disposable, one PR per branch
+- **Squash-merge:** one phase = one commit on main, full PR description preserved
+- **Plan before code:** `requirements.md` is finalized and `design.md` is sketched before any task in `tasks.md` gets implemented.
+- **Semantic test anchors** so later phases don't break earlier tests
+- **One running architecture doc** kept current — read it before each phase, update it after
+
+**When to break the rules:**
+- **Phase grew mid-stream?** Split it. Add `NN-a-slug` / `NN-b-slug` or renumber.
+- **Later phase invalidates an earlier requirement?** Update the earlier doc with a "Superseded by Phase N" note.
+- **Phase ships nothing user-visible** (e.g. refactor prep)? Still its own PR — but say so in the description.
+
+**Pitfalls to avoid:**
+- **Horizontal-slice phases** (all models / all controllers / all views). Trunk is unshippable until the last phase merges.
+- **Scaffolding all phases upfront in full detail** — later phases get invalidated by what you learn early.
+- **Phases longer than ~3 days** — the phase should split. Long phases hide scope creep.
+- **Requirements without acceptance criteria** — "Make X work" isn't a requirement; "When <condition>, the system SHALL <observable behavior>" is.
+- **Tasks that don't reference requirements** — if you can't cite which requirement a task serves, the task probably isn't load-bearing.
+- **Destructive operations mixed with feature work** — schema drops, deletes, deprecations belong in their own phase with a rollback note.