ariadna 1.1.4 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b216fcd72bc73121f1c9129c55c7575ddf50d0ff0d14f34e14f34398a3c6aa23
-  data.tar.gz: 04bad2627d8928f2c2a641f67366764f6d5336ef17fae933923633b675cbd41d
+  metadata.gz: a59ce08ab4d7f1165dd59dac034ac04e5725263a3022bebbd2c3c39fdb0a3c23
+  data.tar.gz: 2eb175ba24a25c5114e3b76f83bbfef0275a21dc114f00d7376390508cb54a87
 SHA512:
-  metadata.gz: 20e330e4c9ca1c1b7bb149efbe12446800c00dd80d6cb299cb38fa1f285244ac05f0b577f196dfa658492c71df5cf697df01885f395998c271008c2e48d105ce
-  data.tar.gz: 2c449bfa9ba635500167fac1019c047559938f89cc8adbfb958e88bb2ea6bf9e3e148b54d62a7d208dfbb6b091b9a53d558406651fc733fc5093689386cb7898
+  metadata.gz: 11f2127685615ea902f97bfc9fc813e20e74f354b055672568d39552d3d551d31896ba73b5ad3434d1ac84dc6d593f8d385818e78fc7cae24844f45720558f80
+  data.tar.gz: cec523e574d6182711229ddf5fa7519929f3c9fb9a144a0eb4928cf46a24d4761e9f718cf3678cf2dde812f9cd655647ca2c12776fcf29aa526831ad9df017a9

data/data/agents/ariadna-planner.md

@@ -17,6 +17,7 @@ Your job: Produce PLAN.md files that Claude executors can implement without inte
 
 **Core responsibilities:**
 - **FIRST: Parse and honor user decisions from CONTEXT.md** (locked decisions are NON-NEGOTIABLE)
+- Use Rails conventions (from `rails-conventions.md`) for standard task decomposition
 - Decompose phases into parallel-optimized plans with 2-3 tasks each
 - Build dependency graphs and assign execution waves
 - Derive must-haves using goal-backward methodology
@@ -25,6 +26,33 @@ Your job: Produce PLAN.md files that Claude executors can implement without inte
 - Return structured results to orchestrator
 </role>
 
+<rails_awareness>
+## Rails-Aware Planning
+
+Load Rails conventions from your required reading for standard task decomposition patterns.
+
+@~/.claude/ariadna/references/rails-conventions.md
+
+**Use domain templates** for common Rails work:
+- "Add model" → migration + model + tests + fixtures
+- "Add controller" → routes + controller + views + tests
+- "Add authentication" → auth scaffold + user model + session controller + tests
+- "Add background job" → job class + model method + tests
+- "Add mailer" → mailer + views + tests
+- "Add Turbo/Hotwire feature" → Turbo Frame + controller response + Stimulus (if needed) + system test
+
+**Known domains (skip discovery):** Models, Controllers, Views, Auth, Jobs, Email, File Uploads, Real-time, Testing, API Mode, Caching. See `rails-conventions.md` `<known_domains>` for the full list.
+
+**Discovery only for:** External API integrations, novel gems, payment systems, or anything not in the known domains list.
+
+**Pitfall prevention:** Apply common Rails pitfalls from `rails-conventions.md` proactively:
+- Include `includes()` for associations in controller queries (N+1)
+- Add database indexes in migration tasks
+- Use strong_parameters in controller tasks
+- Keep controllers thin, models rich
+- Use background jobs for external calls
+</rails_awareness>
+
 <context_fidelity>
 ## CRITICAL: User Decision Fidelity
 

data/data/ariadna/references/rails-conventions.md

@@ -0,0 +1,384 @@
+<rails_conventions>
+
+Pre-baked Rails knowledge for Ariadna planning and execution agents. This document replaces generic research for standard Rails projects, encoding well-known conventions, patterns, and pitfalls so agents don't need to web-search for common Rails patterns.
+
+<standard_stack>
+
+## Standard Rails Stack (2025)
+
+| Layer | Technology | Notes |
+|-------|-----------|-------|
+| Framework | Rails 8+ | Defaults to SQLite in dev, includes Solid Queue/Cache/Cable |
+| Database | PostgreSQL (production) | SQLite for dev/test is fine for most projects |
+| Background Jobs | Solid Queue | Rails 8 default, replaces Sidekiq for most cases |
+| Caching | Solid Cache | Rails 8 default, database-backed cache |
+| WebSockets | Action Cable + Solid Cable | Rails 8 default |
+| Real-time UI | Turbo (Hotwire) | Turbo Drive, Frames, Streams |
+| JS Sprinkles | Stimulus (Hotwire) | Controllers for interactive behavior |
+| CSS | Tailwind CSS or Propshaft | Rails 8 defaults to Propshaft asset pipeline |
+| Auth | Rails built-in `has_secure_password` or Devise | Rails 8 includes auth generator |
+| Email | Action Mailer | Built-in |
+| File Upload | Active Storage | Built-in |
+| API | Rails API mode or Jbuilder | Built-in |
+| Testing | Minitest | Rails default, use fixtures not factories |
+| Linting | RuboCop + rubocop-rails | Standard community linting |
+
+**What NOT to use (and why):**
+- Factories (FactoryBot) when fixtures suffice — fixtures are faster, declarative, and Rails-native
+- RSpec unless the project already uses it — Minitest is simpler and Rails-native
+- Webpacker/Shakapacker — replaced by importmap-rails or jsbundling-rails
+- Sprockets — replaced by Propshaft in Rails 8
+- Redis for jobs/cache — Solid Queue/Cache use the database, simpler ops
+
+</standard_stack>
+
+<architecture_patterns>
+
+## Rails Architecture Patterns
+
+### MVC Foundation
+- **Models:** Business logic lives here. Validations, scopes, callbacks, associations.
+- **Controllers:** Thin. Receive request, call model, render response. 7 RESTful actions max.
+- **Views:** ERB templates. Logic delegated to presenters or helpers.
+
+### Concern-Driven Architecture
+```
+app/models/concerns/
+  shared/           # Cross-model concerns (Trackable, Searchable)
+  model_name/       # Model-specific concerns (User::Authenticatable)
+```
+
+**When to extract a concern:**
+- Behavior reused across 2+ models → shared concern
+- Model file exceeds ~100 lines → model-specific concern
+- Logical grouping of related methods → named concern
+
+### Service Objects (When Needed)
+Use plain Ruby objects in `app/services/` for:
+- Multi-model operations (CreateOrderWithPayment)
+- External API integrations (StripeChargeService)
+- Complex business processes spanning multiple steps
+
+**Don't use for:** Simple CRUD, single-model operations, or anything a model method handles.
+
+### Presenter Pattern
+Plain Ruby classes for complex view logic:
+```ruby
+# app/models/dashboard_presenter.rb (NOT app/presenters/)
+class DashboardPresenter
+  include ActionView::Helpers::TagHelper
+
+  def initialize(user)
+    @user = user
+  end
+
+  def greeting
+    "Welcome, #{@user.name}"
+  end
+end
+```
+
+### RESTful Resource Design
+- Prefer creating new controllers over adding custom actions
+- `POST /messages/:id/archive` → `ArchivesController#create`
+- Nest resources max 1 level: `/posts/:post_id/comments`
+- Use `concerns` in routes for shared resource patterns
+
+### Current Attributes
+```ruby
+# app/models/current.rb
+class Current < ActiveSupport::CurrentAttributes
+  attribute :user, :session, :account
+end
+```
+Set in `ApplicationController`, access everywhere. No parameter passing for auth context.
+
+</architecture_patterns>
+
+<common_pitfalls>
+
+## Common Rails Pitfalls (with Prevention)
+
+### 1. N+1 Queries
+**Problem:** Loading associated records in a loop.
+**Prevention:** Use `includes`, `preload`, or `eager_load` in controllers. Add `strict_loading` to models in development.
+```ruby
+# Bad
+@posts = Post.all  # then post.comments in view
+
+# Good
+@posts = Post.includes(:comments, :author).all
+```
+
+### 2. Missing Database Indexes
+**Prevention:** Always add indexes for:
+- Foreign keys (`add_index :posts, :user_id`)
+- Columns used in `where` clauses
+- Columns used in `order` clauses
+- Unique constraints (`add_index :users, :email, unique: true`)
+
+### 3. Mass Assignment Vulnerabilities
+**Prevention:** Always use `strong_parameters` in controllers.
+```ruby
+def post_params
+  params.require(:post).permit(:title, :body, :published)
+end
+```
+
+### 4. Callback Hell
+**Prevention:** Limit callbacks to:
+- `before_validation` for normalization (strip whitespace, downcase email)
+- `after_create_commit` for async side effects (send email, broadcast)
+- Avoid `after_save` chains that trigger cascading updates
+
+### 5. Fat Controllers
+**Prevention:** Controllers should only:
+1. Authenticate/authorize
+2. Load/build the resource
+3. Call save/update/destroy
+4. Respond with redirect or render
+
+### 6. Missing Validations
+**Prevention:** Validate at model level, not just in forms:
+- Presence on required fields
+- Uniqueness with database-level constraint
+- Format for emails, URLs, phone numbers
+- Numericality for quantities, prices
+
+### 7. Unscoped Queries (Multi-tenancy)
+**Prevention:** Always scope queries to current user/account:
+```ruby
+# Bad
+Post.find(params[:id])
+
+# Good
+Current.user.posts.find(params[:id])
+```
+
+### 8. Missing Error Handling
+**Prevention:** Add `rescue_from` in `ApplicationController`:
+```ruby
+rescue_from ActiveRecord::RecordNotFound, with: :not_found
+rescue_from ActionController::ParameterMissing, with: :bad_request
+```
+
+### 9. Synchronous External Calls
+**Prevention:** Always use background jobs for:
+- Sending emails
+- Calling external APIs
+- Processing uploads
+- Generating reports
+
+### 10. Missing CSRF Protection
+**Prevention:** Rails enables CSRF by default. Don't disable `protect_from_forgery`. For API endpoints, use token auth instead.
+
+</common_pitfalls>
+
+<testing_patterns>
+
+## Rails Testing Patterns (Minitest)
+
+### Test Organization
+```
+test/
+  models/           # Unit tests for models
+  controllers/      # Integration tests for request/response
+  system/           # Browser-based end-to-end tests
+  helpers/          # Helper method tests
+  jobs/             # Background job tests
+  mailers/          # Mailer tests
+  fixtures/         # YAML test data
+  test_helper.rb    # Shared setup
+```
+
+### Fixtures Over Factories
+```yaml
+# test/fixtures/users.yml
+alice:
+  name: Alice
+  email: alice@example.com
+  password_digest: <%= BCrypt::Password.create('password') %>
+
+bob:
+  name: Bob
+  email: bob@example.com
+  password_digest: <%= BCrypt::Password.create('password') %>
+```
+
+**Why fixtures:** Faster (loaded once per test suite), declarative, Rails-native, no external gem needed.
+
+### Model Test Pattern
+```ruby
+class UserTest < ActiveSupport::TestCase
+  setup do
+    Current.session = sessions(:alice_session) # Always set Current context
+  end
+
+  test "validates email presence" do
+    user = User.new(name: "Test")
+    assert_not user.valid?
+    assert_includes user.errors[:email], "can't be blank"
+  end
+
+  test "creates user with valid attributes" do
+    assert_difference "User.count", 1 do
+      User.create!(name: "New", email: "new@example.com", password: "password")
+    end
+  end
+end
+```
+
+### Controller Test Pattern (Integration)
+```ruby
+class PostsControllerTest < ActionDispatch::IntegrationTest
+  setup do
+    @user = users(:alice)
+    sign_in @user  # Helper method
+  end
+
+  test "index returns posts" do
+    get posts_url
+    assert_response :success
+    assert_select "h2", posts(:first).title
+  end
+
+  test "create redirects on success" do
+    assert_difference "Post.count", 1 do
+      post posts_url, params: { post: { title: "New", body: "Content" } }
+    end
+    assert_redirected_to post_url(Post.last)
+  end
+end
+```
+
+### System Test Pattern
+```ruby
+class UserFlowsTest < ApplicationSystemTestCase
+  test "user can sign up and create a post" do
+    visit new_registration_url
+    fill_in "Name", with: "Test User"
+    fill_in "Email", with: "test@example.com"
+    fill_in "Password", with: "password123"
+    click_on "Sign up"
+
+    assert_text "Welcome, Test User"
+
+    click_on "New Post"
+    fill_in "Title", with: "My First Post"
+    fill_in "Body", with: "Hello world"
+    click_on "Create Post"
+
+    assert_text "My First Post"
+  end
+end
+```
+
+### Key Testing Conventions
+- Use `assert_difference` for state changes, not just boolean checks
+- Set `Current.session` in setup blocks for multi-tenancy
+- Test happy path and one key failure path per method
+- Use `assert_select` for HTML assertions in controller tests
+- Run `bin/rails test` (not `rspec`) for the full suite
+
+</testing_patterns>
+
+<domain_templates>
+
+## Rails Task Templates for Planning
+
+These templates help the planner agent decompose common Rails work into well-structured tasks.
+
+### Add Model
+```
+Tasks:
+1. Create migration + model with validations, associations, and concerns
+   Files: db/migrate/xxx_create_[model].rb, app/models/[model].rb
+2. Add model tests + fixtures
+   Files: test/models/[model]_test.rb, test/fixtures/[model].yml
+```
+
+### Add Controller (with views)
+```
+Tasks:
+1. Add routes + controller with RESTful actions
+   Files: config/routes.rb, app/controllers/[model]_controller.rb
+2. Add views (index, show, new, edit, _form partial)
+   Files: app/views/[model]/*.html.erb
+3. Add controller tests
+   Files: test/controllers/[model]_controller_test.rb
+```
+
+### Add Authentication
+```
+Tasks:
+1. Generate auth scaffold (Rails 8: bin/rails generate authentication)
+   or: Add User model with has_secure_password, Session model, SessionsController
+   Files: app/models/user.rb, app/models/session.rb, app/controllers/sessions_controller.rb
+2. Add auth views (login, registration)
+   Files: app/views/sessions/*.html.erb, app/views/registrations/*.html.erb
+3. Add auth tests
+   Files: test/controllers/sessions_controller_test.rb, test/models/user_test.rb
+```
+
+### Add Background Job
+```
+Tasks:
+1. Create job class + model method it delegates to
+   Files: app/jobs/[name]_job.rb, app/models/[model].rb
+2. Add job tests
+   Files: test/jobs/[name]_job_test.rb
+```
+
+### Add Mailer
+```
+Tasks:
+1. Create mailer + views
+   Files: app/mailers/[name]_mailer.rb, app/views/[name]_mailer/*.html.erb
+2. Add mailer tests
+   Files: test/mailers/[name]_mailer_test.rb
+```
+
+### Add Turbo/Hotwire Feature
+```
+Tasks:
+1. Add Turbo Frame wrapping + controller turbo_stream response
+   Files: app/views/[model]/*.html.erb, app/controllers/[model]_controller.rb
+2. Add Stimulus controller (if interactive behavior needed)
+   Files: app/javascript/controllers/[name]_controller.js
+3. Add system test for real-time behavior
+   Files: test/system/[feature]_test.rb
+```
+
+</domain_templates>
+
+<known_domains>
+
+## Known Rails Domains (Skip Research)
+
+These domains are well-understood in Rails and don't need web research:
+
+| Domain | Key Patterns | Research Needed? |
+|--------|-------------|-----------------|
+| Models & Migrations | ActiveRecord, validations, associations, concerns | No |
+| Controllers & Routes | RESTful resources, before_action, strong params | No |
+| Views & Templates | ERB, partials, layouts, content_for | No |
+| Authentication | has_secure_password, Devise, Rails 8 auth generator | No |
+| Authorization | Pundit, CanCanCan, or hand-rolled | No |
+| Background Jobs | Solid Queue, ActiveJob | No |
+| Email | Action Mailer, letter_opener | No |
+| File Uploads | Active Storage | No |
+| Real-time | Action Cable, Turbo Streams | No |
+| Testing | Minitest, fixtures, system tests | No |
+| API Mode | Jbuilder, API-only controllers, token auth | No |
+| Caching | Fragment caching, Russian doll, Solid Cache | No |
+| Search | pg_search, Ransack | Maybe (depends on complexity) |
+| Payments | Stripe, Pay gem | Yes (API details change) |
+| External APIs | Third-party integrations | Yes (API-specific) |
+| Novel Gems | Unfamiliar libraries | Yes |
+| Infrastructure | Docker, Kamal, deployment | Maybe |
+
+**Heuristic:** If all phase requirements map to "No" domains, skip research automatically. If any requirement maps to "Yes", consider `--research` flag.
+
+</known_domains>
+
+</rails_conventions>

data/data/ariadna/workflows/new-project.md

@@ -14,9 +14,9 @@ Check if `--auto` flag is present in $ARGUMENTS.
 **If auto mode:**
 - Skip brownfield mapping offer (assume greenfield)
 - Skip deep questioning (extract context from provided document)
-- Config questions still required (Step 5)
+- Skip config questions — use opinionated defaults (Step 5)
 - After config: run Steps 6-9 automatically with smart defaults:
-  - Research: Always yes
+  - Research: No (Rails conventions pre-loaded). Use `--auto --research` to force research.
   - Requirements: Include all table stakes + features from provided document
   - Requirements approval: Auto-approve
   - Roadmap approval: Auto-approve
@@ -215,129 +215,45 @@ mkdir -p .planning
 ariadna-tools commit "docs: initialize project" --files .planning/PROJECT.md
 ```
 
-## 5. Workflow Preferences
+## 5. Workflow Configuration
 
-**Round 1 — Core workflow settings (4 questions):**
+**Use opinionated defaults. Only ask if user wants to customize.**
 
-```
-questions: [
-  {
-    header: "Mode",
-    question: "How do you want to work?",
-    multiSelect: false,
-    options: [
-      { label: "YOLO (Recommended)", description: "Auto-approve, just execute" },
-      { label: "Interactive", description: "Confirm at each step" }
-    ]
-  },
-  {
-    header: "Depth",
-    question: "How thorough should planning be?",
-    multiSelect: false,
-    options: [
-      { label: "Quick", description: "Ship fast (3-5 phases, 1-3 plans each)" },
-      { label: "Standard", description: "Balanced scope and speed (5-8 phases, 3-5 plans each)" },
-      { label: "Comprehensive", description: "Thorough coverage (8-12 phases, 5-10 plans each)" }
-    ]
-  },
-  {
-    header: "Execution",
-    question: "Run plans in parallel?",
-    multiSelect: false,
-    options: [
-      { label: "Parallel (Recommended)", description: "Independent plans run simultaneously" },
-      { label: "Sequential", description: "One plan at a time" }
-    ]
-  },
-  {
-    header: "Git Tracking",
-    question: "Commit planning docs to git?",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Planning docs tracked in version control" },
-      { label: "No", description: "Keep .planning/ local-only (add to .gitignore)" }
-    ]
+Apply these defaults directly to `.planning/config.json`:
+
+```json
+{
+  "mode": "interactive",
+  "depth": "standard",
+  "parallelization": true,
+  "commit_docs": true,
+  "model_profile": "balanced",
+  "workflow": {
+    "research": false,
+    "plan_check": true,
+    "verifier": true
   }
-]
+}
 ```
 
-**Round 2 — Workflow agents:**
-
-These spawn additional agents during planning/execution. They add tokens and time but improve quality.
-
-| Agent | When it runs | What it does |
-|-------|--------------|--------------|
-| **Researcher** | Before planning each phase | Investigates domain, finds patterns, surfaces gotchas |
-| **Plan Checker** | After plan is created | Verifies plan actually achieves the phase goal |
-| **Verifier** | After phase execution | Confirms must-haves were delivered |
-
-All recommended for important projects. Skip for quick experiments.
+**Ask ONE question — only the non-obvious setting:**
 
 ```
 questions: [
   {
-    header: "Research",
-    question: "Research before planning each phase? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Investigate domain, find patterns, surface gotchas" },
-      { label: "No", description: "Plan directly from requirements" }
-    ]
-  },
-  {
-    header: "Plan Check",
-    question: "Verify plans will achieve their goals? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Catch gaps before execution starts" },
-      { label: "No", description: "Execute plans without verification" }
-    ]
-  },
-  {
-    header: "Verifier",
-    question: "Verify work satisfies requirements after each phase? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Confirm deliverables match phase goals" },
-      { label: "No", description: "Trust execution, skip verification" }
-    ]
-  },
-  {
-    header: "Model Profile",
-    question: "Which AI models for planning agents?",
+    header: "Depth",
+    question: "How thorough should planning be?",
     multiSelect: false,
     options: [
-      { label: "Balanced (Recommended)", description: "Sonnet for most agents — good quality/cost ratio" },
-      { label: "Quality", description: "Opus for research/roadmap — higher cost, deeper analysis" },
-      { label: "Budget", description: "Haiku where possible — fastest, lowest cost" }
+      { label: "Standard (Recommended)", description: "Balanced scope and speed (5-8 phases, 3-5 plans each)" },
+      { label: "Quick", description: "Ship fast (3-5 phases, 1-3 plans each)" },
+      { label: "Comprehensive", description: "Thorough coverage (8-12 phases, 5-10 plans each)" }
     ]
   }
 ]
 ```
 
-Create `.planning/config.json` with all settings:
-
-```json
-{
-  "mode": "yolo|interactive",
-  "depth": "quick|standard|comprehensive",
-  "parallelization": true|false,
-  "commit_docs": true|false,
-  "model_profile": "quality|balanced|budget",
-  "workflow": {
-    "research": true|false,
-    "plan_check": true|false,
-    "verifier": true|false
-  }
-}
-```
-
-**If commit_docs = No:**
-- Set `commit_docs: false` in config.json
-- Add `.planning/` to `.gitignore` (create if needed)
-
-**If commit_docs = Yes:**
-- No additional gitignore entries needed
+Create `.planning/config.json` with the defaults above, applying the user's depth selection.
 
 **Commit config.json:**
 
@@ -345,24 +261,26 @@ Create `.planning/config.json` with all settings:
 ariadna-tools commit "chore: add project config" --files .planning/config.json
 ```
 
-**Note:** Run `/ariadna:settings` anytime to update these preferences.
+**Note:** Run `/ariadna:settings` anytime to update these preferences (research, model profile, parallelization, etc.).
 
 ## 5.5. Resolve Model Profile
 
-Use models from init: `researcher_model`, `synthesizer_model`, `roadmapper_model`.
+Use models from init: `roadmapper_model`.
 
 ## 6. Research Decision
 
-**If auto mode:** Default to "Research first" without asking.
+**Default: Skip research.** Rails conventions are pre-loaded via `rails-conventions.md` reference document, which provides standard stack, architecture patterns, common pitfalls, and testing patterns.
 
-Use AskUserQuestion:
-- header: "Research"
-- question: "Research the domain ecosystem before defining requirements?"
-- options:
-  - "Research first (Recommended)" — Discover standard stacks, expected features, architecture patterns
-  - "Skip research" — I know this domain well, go straight to requirements
+**If `--research` flag was passed or auto mode:** Run full research (see below).
 
-**If "Research first":**
+**Otherwise:** Display skip notice and continue to Step 7:
+
+```
+Using pre-loaded Rails conventions (stack, architecture, patterns, pitfalls).
+To research instead: /ariadna:new-project --research
+```
+
+**If research requested (`--research` flag or auto mode):**
 
 Display stage banner:
 ```
@@ -596,7 +514,7 @@ Display research complete banner and key findings:
 Files: `.planning/research/`
 ```
 
-**If "Skip research":** Continue to Step 7.
+**If research not requested:** Continue to Step 7.
 
 ## 7. Define Requirements
 
@@ -769,6 +687,9 @@ Task(prompt="
 **Research (if exists):**
 @.planning/research/SUMMARY.md
 
+**Rails Conventions (pre-loaded domain knowledge):**
+@~/.claude/ariadna/references/rails-conventions.md
+
 **Config:**
 @.planning/config.json
 
@@ -780,8 +701,9 @@ Create roadmap:
 2. Map every v1 requirement to exactly one phase
 3. Derive 2-5 success criteria per phase (observable user behaviors)
 4. Validate 100% coverage
-5. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
-6. Return ROADMAP CREATED with summary
+5. Use Rails conventions reference for standard patterns and build order
+6. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
+7. Return ROADMAP CREATED with summary
 
 Write files first, then return. This ensures artifacts persist even if context is lost.
 </instructions>
@@ -903,14 +825,15 @@ Present completion with next steps:
 
 **Phase 1: [Phase Name]** — [Goal from ROADMAP.md]
 
-/ariadna:discuss-phase 1 — gather context and clarify approach
+/ariadna:plan-phase 1
 
 <sub>/clear first → fresh context window</sub>
 
 ---
 
 **Also available:**
-- /ariadna:plan-phase 1 — skip discussion, plan directly
+- /ariadna:discuss-phase 1 — gather detailed context before planning (optional)
+- /ariadna:plan-phase 1 --research — research before planning (for non-standard integrations)
 
 ───────────────────────────────────────────────────────────────
 ```
@@ -940,18 +863,18 @@ Present completion with next steps:
 - [ ] Brownfield detection completed
 - [ ] Deep questioning completed (threads followed, not rushed)
 - [ ] PROJECT.md captures full context → **committed**
-- [ ] config.json has workflow mode, depth, parallelization → **committed**
-- [ ] Research completed (if selected) — 4 parallel agents spawned → **committed**
-- [ ] Requirements gathered (from research or conversation)
+- [ ] config.json has opinionated defaults → **committed**
+- [ ] Research completed (only if `--research` flag) — 4 parallel agents spawned → **committed**
+- [ ] Requirements gathered (from research or conversation, with Rails conventions as context)
 - [ ] User scoped each category (v1/v2/out of scope)
 - [ ] REQUIREMENTS.md created with REQ-IDs → **committed**
-- [ ] ariadna-roadmapper spawned with context
+- [ ] ariadna-roadmapper spawned with context (including rails-conventions.md)
 - [ ] Roadmap files written immediately (not draft)
 - [ ] User feedback incorporated (if any)
 - [ ] ROADMAP.md created with phases, requirement mappings, success criteria
 - [ ] STATE.md initialized
 - [ ] REQUIREMENTS.md traceability updated
-- [ ] User knows next step is `/ariadna:discuss-phase 1`
+- [ ] User knows next step is `/ariadna:plan-phase 1`
 
 **Atomic commits:** Each phase commits its artifacts immediately. If context is lost, artifacts persist.
 

data/data/ariadna/workflows/plan-phase.md

@@ -1,11 +1,12 @@
 <purpose>
-Create executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification. Default flow: Research (if needed) -> Plan -> Verify -> Done. Orchestrates ariadna-phase-researcher, ariadna-planner, and ariadna-plan-checker agents with a revision loop (max 3 iterations).
+Create executable phase prompts (PLAN.md files) for a roadmap phase. Default flow: Context (inline if needed) -> Plan -> Verify -> Done. Orchestrates ariadna-planner and ariadna-plan-checker agents. Research skipped by default (Rails conventions pre-loaded); use --research to force research for non-standard integrations.
 </purpose>
 
 <required_reading>
 Read all files referenced by the invoking prompt's execution_context before starting.
 
 @~/.claude/ariadna/references/ui-brand.md
+@~/.claude/ariadna/references/rails-conventions.md
 </required_reading>
 
 <process>
@@ -26,7 +27,7 @@ Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_
 
 ## 2. Parse and Normalize Arguments
 
-Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--gaps`, `--skip-verify`).
+Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--gaps`, `--skip-verify`, `--skip-context`).
 
 **If no phase number:** Detect next unplanned phase from roadmap.
 
@@ -45,21 +46,55 @@ PHASE_INFO=$(ariadna-tools roadmap get-phase "${PHASE}")
 
 **If `found` is false:** Error with available phases. **If `found` is true:** Extract `phase_number`, `phase_name`, `goal` from JSON.
 
-## 4. Load CONTEXT.md
+## 4. Inline Context Gathering (Replaces discuss-phase)
 
 Use `context_content` from init JSON (already loaded via `--include context`).
 
-**CRITICAL:** Use `context_content` from INIT — pass to researcher, planner, checker, and revision agents.
+**If `context_content` is not null:** Display: `Using phase context from: ${PHASE_DIR}/*-CONTEXT.md` and skip to step 5.
 
-If `context_content` is not null, display: `Using phase context from: ${PHASE_DIR}/*-CONTEXT.md`
+**If `context_content` is null AND no `--skip-context` flag:**
+
+Analyze the phase goal from `roadmap_content` and determine if there are implementation decisions the user should weigh in on.
+
+**Quick assessment — does this phase need context?**
+
+- Pure infrastructure / setup / configuration → No context needed, skip
+- Standard CRUD (models, controllers, views) → No context needed, skip
+- User-facing features with UI/UX decisions → Context helpful
+- Features with multiple valid approaches → Context helpful
+
+**If context would be helpful:** Offer inline clarification with a single AskUserQuestion:
+
+```
+questions: [
+  {
+    header: "Context",
+    question: "Phase {X}: {Name} has some implementation choices. Want to discuss them before planning?",
+    multiSelect: false,
+    options: [
+      { label: "Plan directly (Recommended)", description: "Planner will make reasonable choices, you review the plan" },
+      { label: "Quick discussion", description: "Clarify 2-3 key decisions inline" },
+      { label: "Full discussion", description: "Run /ariadna:discuss-phase for detailed context gathering" }
+    ]
+  }
+]
+```
+
+- **"Plan directly":** Continue to step 5. Planner will use its judgment for ambiguous areas.
+- **"Quick discussion":** Identify 2-3 key gray areas and ask focused AskUserQuestion for each. Write a lightweight CONTEXT.md to the phase directory. Then continue to step 5.
+- **"Full discussion":** Exit and tell user to run `/ariadna:discuss-phase {X}` first, then return.
+
+**CRITICAL:** Use `context_content` from INIT — pass to planner and checker agents.
 
 ## 5. Handle Research
 
-**Skip if:** `--gaps` flag, `--skip-research` flag, or `research_enabled` is false (from init) without `--research` override.
+**Default: Skip research.** Rails conventions are pre-loaded via `rails-conventions.md`.
+
+**Skip if:** `--gaps` flag, or `research_enabled` is false (default) without `--research` override.
 
 **If `has_research` is true (from init) AND no `--research` flag:** Use existing, skip to step 6.
 
-**If RESEARCH.md missing OR `--research` flag:**
+**If `--research` flag explicitly passed:**
 
 Display banner:
 ```
@@ -179,6 +214,14 @@ IMPORTANT: If context exists below, it contains USER DECISIONS from /ariadna:dis
 **Gap Closure (if --gaps):** {verification_content} {uat_content}
 </planning_context>
 
+<rails_context>
+Use Rails conventions from your required reading (rails-conventions.md) for:
+- Standard task decomposition patterns (model → migration+model+tests, controller → routes+controller+views+tests)
+- Known domain detection (skip discovery for standard Rails work)
+- Architecture patterns (MVC, concerns, service objects)
+- Common pitfall prevention (N+1, mass assignment, fat controllers)
+</rails_context>
+
 <downstream_consumer>
 Output consumed by /ariadna:execute-phase. Plans need:
 - Frontmatter (wave, depends_on, files_modified, autonomous)
@@ -248,7 +291,7 @@ IMPORTANT: Plans MUST honor user decisions. Flag as issue if plans contradict.
 
 <expected_output>
 - ## VERIFICATION PASSED — all checks pass
-- ## ISSUES FOUND — structured issue list
+- ## ISSUES FOUND — structured issue list with severity (minor/major/blocker)
 </expected_output>
 ```
 
@@ -264,58 +307,65 @@ Task(
 ## 11. Handle Checker Return
 
 - **`## VERIFICATION PASSED`:** Display confirmation, proceed to step 13.
-- **`## ISSUES FOUND`:** Display issues, check iteration count, proceed to step 12.
-
-## 12. Revision Loop (Max 3 Iterations)
+- **`## ISSUES FOUND`:** Classify issues and proceed to step 12.
 
-Track `iteration_count` (starts at 1 after initial plan + check).
+## 12. Handle Checker Issues (Inline Fix, No Revision Loop)
 
-**If iteration_count < 3:**
+**Classify each issue by severity:**
 
-Display: `Sending back to planner for revision... (iteration {N}/3)`
+### Minor Issues (orchestrator fixes inline)
+Issues the orchestrator can fix directly with the Edit tool — no agent re-spawn needed:
+- Missing requirement mapping in frontmatter
+- Dependency ordering errors (wrong wave number)
+- Missing `<verify>` or `<done>` elements in tasks
+- Frontmatter field corrections
+- must_haves adjustments
 
-```bash
-PLANS_CONTENT=$(cat "${PHASE_DIR}"/*-PLAN.md 2>/dev/null)
+**For minor issues:** Fix the PLAN.md files directly using the Edit tool:
+```
+Read the PLAN.md file, apply the fix, write it back.
 ```
 
-Revision prompt:
-
-```markdown
-<revision_context>
-**Phase:** {phase_number}
-**Mode:** revision
-
-**Existing plans:** {plans_content}
-**Checker issues:** {structured_issues_from_checker}
+Display: `Fixed {N} minor issue(s) inline.`
 
-**Phase Context:**
-Revisions MUST still honor user decisions.
-{context_content}
-</revision_context>
+### Major Issues (present to user)
+Issues that require architectural decisions or significant plan restructuring:
+- Missing requirements with no clear task mapping
+- Incorrect decomposition (tasks too large or wrong scope)
+- Contradictions with user decisions from CONTEXT.md
+- Scope creep (tasks implementing deferred ideas)
 
-<instructions>
-Make targeted updates to address checker issues.
-Do NOT replan from scratch unless issues are fundamental.
-Return what changed.
-</instructions>
+**For major issues:** Present to user with AskUserQuestion:
+```
+questions: [
+  {
+    header: "Plan Issues",
+    question: "The plan checker found {N} issue(s) that need your input. How to proceed?",
+    multiSelect: false,
+    options: [
+      { label: "Accept as-is", description: "Proceed despite issues" },
+      { label: "Re-plan", description: "Spawn planner again with issue context" },
+      { label: "Fix manually", description: "I'll edit the PLAN.md files myself" }
+    ]
+  }
+]
 ```
 
+- **"Accept as-is":** Proceed to step 13.
+- **"Re-plan":** Spawn planner in revision mode (single attempt, not a loop):
+
 ```
 Task(
-  prompt="First, read ~/.claude/agents/ariadna-planner.md for your role and instructions.\n\n" + revision_prompt,
+  prompt="First, read ~/.claude/agents/ariadna-planner.md for your role and instructions.\n\n" + revision_prompt_with_issues,
   subagent_type="general-purpose",
   model="{planner_model}",
   description="Revise Phase {phase} plans"
 )
 ```
 
-After planner returns -> spawn checker again (step 10), increment iteration_count.
-
-**If iteration_count >= 3:**
-
-Display: `Max iterations reached. {N} issues remain:` + issue list
+After planner returns, proceed to step 13 (no re-check loop).
 
-Offer: 1) Force proceed, 2) Provide guidance and retry, 3) Abandon
+- **"Fix manually":** Display file paths and exit.
 
 ## 13. Present Final Status
 
@@ -337,8 +387,9 @@ Output this markdown directly (not as a code block):
 | 1    | 01, 02 | [objectives] |
 | 2    | 03     | [objective]  |
 
-Research: {Completed | Used existing | Skipped}
-Verification: {Passed | Passed with override | Skipped}
+Context: {Gathered inline | Used existing | Skipped}
+Research: {Completed | Used existing | Skipped (Rails conventions loaded)}
+Verification: {Passed | Passed with fixes | Skipped}
 
 ───────────────────────────────────────────────────────────────
 
@@ -363,14 +414,14 @@ Verification: {Passed | Passed with override | Skipped}
 - [ ] .planning/ directory validated
 - [ ] Phase validated against roadmap
 - [ ] Phase directory created if needed
-- [ ] CONTEXT.md loaded early (step 4) and passed to ALL agents
-- [ ] Research completed (unless --skip-research or --gaps or exists)
-- [ ] ariadna-phase-researcher spawned with CONTEXT.md
+- [ ] Context handled: existing CONTEXT.md used, inline gathering offered, or skipped
+- [ ] Research skipped by default (Rails conventions in context), or completed if --research flag
 - [ ] Existing plans checked
-- [ ] ariadna-planner spawned with CONTEXT.md + RESEARCH.md
+- [ ] ariadna-planner spawned with rails-conventions + any CONTEXT.md + RESEARCH.md
 - [ ] Plans created (PLANNING COMPLETE or CHECKPOINT handled)
-- [ ] ariadna-plan-checker spawned with CONTEXT.md
-- [ ] Verification passed OR user override OR max iterations with user decision
+- [ ] ariadna-plan-checker spawned (unless --skip-verify)
+- [ ] Minor checker issues fixed inline by orchestrator (no revision loop)
+- [ ] Major checker issues presented to user for decision
 - [ ] User sees status between agent spawns
 - [ ] User knows next steps
 </success_criteria>

data/data/commands/ariadna/new-project.md

@@ -1,7 +1,7 @@
 ---
 name: ariadna:new-project
 description: Initialize a new project with deep context gathering and PROJECT.md
-argument-hint: "[--auto]"
+argument-hint: "[--auto] [--research]"
 allowed-tools:
   - Read
   - Bash
@@ -11,27 +11,29 @@ allowed-tools:
 ---
 <context>
 **Flags:**
-- `--auto` — Automatic mode. After config questions, runs research → requirements → roadmap without further interaction. Expects idea document via @ reference.
+- `--auto` — Automatic mode. Skips config questions, runs requirements → roadmap without further interaction. Expects idea document via @ reference.
+- `--research` — Force domain research (4 parallel researchers + synthesizer). By default, research is skipped and Rails conventions are pre-loaded.
 </context>
 
 <objective>
-Initialize a new project through unified flow: questioning → research (optional) → requirements → roadmap.
+Initialize a new project through streamlined flow: questioning → requirements → roadmap. Research skipped by default (Rails conventions pre-loaded); use --research for non-standard domains.
 
 **Creates:**
 - `.planning/PROJECT.md` — project context
-- `.planning/config.json` — workflow preferences
-- `.planning/research/` — domain research (optional)
+- `.planning/config.json` — workflow preferences (opinionated defaults)
+- `.planning/research/` — domain research (only with --research flag)
 - `.planning/REQUIREMENTS.md` — scoped requirements
 - `.planning/ROADMAP.md` — phase structure
 - `.planning/STATE.md` — project memory
 
-**After this command:** Run `/ariadna:plan-phase 1` to start execution.
+**After this command:** Run `/ariadna:plan-phase 1` to start planning.
 </objective>
 
 <execution_context>
 @~/.claude/ariadna/workflows/new-project.md
 @~/.claude/ariadna/references/questioning.md
 @~/.claude/ariadna/references/ui-brand.md
+@~/.claude/ariadna/references/rails-conventions.md
 @~/.claude/ariadna/templates/project.md
 @~/.claude/ariadna/templates/requirements.md
 </execution_context>

data/data/commands/ariadna/plan-phase.md

@@ -1,7 +1,7 @@
 ---
 name: ariadna:plan-phase
 description: Create detailed execution plan for a phase (PLAN.md) with verification loop
-argument-hint: "[phase] [--research] [--skip-research] [--gaps] [--skip-verify]"
+argument-hint: "[phase] [--research] [--skip-research] [--gaps] [--skip-verify] [--skip-context]"
 agent: ariadna-planner
 allowed-tools:
   - Read
@@ -14,26 +14,28 @@ allowed-tools:
   - mcp__context7__*
 ---
 <objective>
-Create executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification.
+Create executable phase prompts (PLAN.md files) for a roadmap phase. Research skipped by default (Rails conventions pre-loaded). Includes optional inline context gathering (replaces separate discuss-phase step).
 
-**Default flow:** Research (if needed) → Plan → Verify → Done
+**Default flow:** Context (inline if needed) → Plan → Verify → Done
 
-**Orchestrator role:** Parse arguments, validate phase, research domain (unless skipped), spawn ariadna-planner, verify with ariadna-plan-checker, iterate until pass or max iterations, present results.
+**Orchestrator role:** Parse arguments, validate phase, offer inline context gathering, spawn ariadna-planner (with Rails conventions), verify with ariadna-plan-checker (single pass, inline fixes for minor issues), present results.
 </objective>
 
 <execution_context>
 @~/.claude/ariadna/workflows/plan-phase.md
 @~/.claude/ariadna/references/ui-brand.md
+@~/.claude/ariadna/references/rails-conventions.md
 </execution_context>
 
 <context>
 Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omitted)
 
 **Flags:**
-- `--research` — Force re-research even if RESEARCH.md exists
-- `--skip-research` — Skip research, go straight to planning
+- `--research` — Force research even if not enabled in config (for non-standard integrations)
+- `--skip-research` — Skip research, go straight to planning (default behavior)
 - `--gaps` — Gap closure mode (reads VERIFICATION.md, skips research)
-- `--skip-verify` — Skip verification loop
+- `--skip-verify` — Skip plan verification
+- `--skip-context` — Skip inline context gathering, plan directly
 
 Normalize phase input in step 2 before any directory lookups.
 </context>

data/lib/ariadna/tools/config_manager.rb

@@ -12,7 +12,7 @@ module Ariadna
         "branching_strategy" => "none",
         "phase_branch_template" => "ariadna/phase-{phase}-{slug}",
         "milestone_branch_template" => "ariadna/{milestone}-{slug}",
-        "research" => true,
+        "research" => false,
         "plan_checker" => true,
         "verifier" => true,
         "parallelization" => true,
@@ -89,7 +89,7 @@ module Ariadna
           phase_branch_template: "ariadna/phase-{phase}-{slug}",
           milestone_branch_template: "ariadna/{milestone}-{slug}",
           workflow: {
-            research: true,
+            research: false,
             plan_check: true,
             verifier: true
           },

data/lib/ariadna/tools/frontmatter.rb

@@ -210,6 +210,8 @@ module Ariadna
             key = key_match[2]
             value = key_match[3].strip
 
+            next unless current[:obj].is_a?(Hash)
+
             if value.empty? || value == "["
               current[:obj][key] = value == "[" ? [] : {}
               stack.push({ obj: current[:obj][key], key: nil, indent: indent })

data/lib/ariadna/version.rb

@@ -1,3 +1,3 @@
 module Ariadna
-  VERSION = "1.1.4"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ariadna
 version: !ruby/object:Gem::Version
-  version: 1.1.4
+  version: 1.2.0
 platform: ruby
 authors:
 - Jorge Alvarez
@@ -45,6 +45,7 @@ files:
 - data/ariadna/references/phase-argument-parsing.md
 - data/ariadna/references/planning-config.md
 - data/ariadna/references/questioning.md
+- data/ariadna/references/rails-conventions.md
 - data/ariadna/references/tdd.md
 - data/ariadna/references/ui-brand.md
 - data/ariadna/references/verification-patterns.md