ariadna 1.1.3 → 1.2.0

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/data/guides/backend.md

@@ -18,7 +18,6 @@ We stand on the shoulders of giants.
 - [Part 1: Foundation & Architecture](#part-1-foundation--architecture)
   - [1.0 The Vanilla Rails Philosophy](#10-the-vanilla-rails-philosophy)
   - [1.1 Understanding Architecture](#11-understanding-fizzys-architecture)
-  - [1.2 UUID Primary Keys & Fixtures](#12-uuid-primary-keys--fixtures)
 - [Part 2: Model Layer Patterns](#part-2-model-layer-patterns)
   - [2.1 Concern Architecture](#21-concern-architecture)
   - [2.2 Intention-Revealing APIs](#22-intention-revealing-apis)
@@ -204,52 +203,6 @@ setup do
 end
 ```
 
-### UUID Primary Keys
-
-It uses UUIDs (UUIDv7, base36-encoded to 25 characters) instead of auto-incrementing integers:
-
-**Why UUIDs:**
-- **Security**: No ID enumeration across tenants
-- **Distributed systems**: Can generate IDs client-side
-- **Merging**: No ID conflicts when combining data
-
-**The Card exception**: Cards use `number` (integer) for user-facing IDs:
-```ruby
-# Card ID: "abc123def456..." (UUID, internal)
-# Card number: 1234 (integer, user-facing)
-
-# In routes and URLs
-card_path(@card)  # => /cards/1234 (uses number, not ID)
-
-# In controllers
-@card = Current.user.accessible_cards.find_by!(number: params[:id])
-```
-
-**Fixture behavior:**
-- Fixture UUIDs are deterministic and always "older" than test-created records
-- `.first` and `.last` work predictably in tests
-
-## 1.2 UUID Primary Keys & Fixtures
-
-### Practical Implications
-
-```ruby
-# ✓ Good: Find cards by number
-def set_card
-  @card = Current.user.accessible_cards.find_by!(number: params[:id])
-end
-
-# ✗ Bad: Don't use regular find for cards
-def set_card
-  @card = Card.find(params[:id])  # Wrong! Cards use number for params
-end
-
-# ✓ Good: Everything else uses UUID find
-def set_board
-  @board = Current.user.boards.find(params[:board_id])
-end
-```
-
 ---
 
 # Part 2: Model Layer Patterns
@@ -2642,10 +2595,10 @@ end
 ```ruby
 class CreateCardArchives < ActiveRecord::Migration[7.1]
   def change
-    create_table :card_archives, id: :uuid do |t|
-      t.references :card, null: false, foreign_key: true, type: :uuid
-      t.references :user, null: false, foreign_key: true, type: :uuid
-      t.references :account, null: false, foreign_key: true, type: :uuid
+    create_table :card_archives do |t|
+      t.references :card, null: false, foreign_key: true
+      t.references :user, null: false, foreign_key: true
+      t.references :account, null: false, foreign_key: true
       t.timestamps
     end
   end
@@ -3094,7 +3047,7 @@ Wrap related operations in transactions.
 
 This documentation covers the core backend patterns and practices used throughout the Rails application:
 
-- **Foundation**: Multi-tenancy via Current context, UUID primary keys
+- **Foundation**: Multi-tenancy via Current context
 - **Models**: Concern-driven architecture, intention-revealing APIs, smart defaults
 - **Controllers**: Thin controllers that delegate to rich models
 - **Jobs**: Ultra-thin jobs following _now/_later pattern

data/data/templates.md

@@ -57,7 +57,7 @@ Launch **6 parallel agents** (one per file), each tasked with rewriting a single
   - **Languages**: Ruby (version from `.ruby-version`), JavaScript/CSS for assets
   - **Runtime**: Ruby + Bundler, `.ruby-version`
   - **Frameworks**: Rails (version), Minitest (recommended)/RSpec, Hotwire/Turbo/Stimulus
-  - **Key Dependencies**: Key gems (solid_queue, solid_cache, pundit, etc.)
+  - **Key Dependencies**: Key gems (solid_queue, solid_cache, etc.)
   - **Configuration**: `database.yml`, `credentials.yml.enc`, `config/environments/`
   - **Build**: Asset pipeline (Propshaft/Sprockets), importmap/esbuild/vite
   - **Platform**: Kamal, Docker, Heroku, etc.
@@ -79,7 +79,7 @@ Launch **6 parallel agents** (one per file), each tasked with rewriting a single
   - **Organization**: `test/` mirroring `app/`, fixtures in `test/fixtures/`
   - **Structure**: `ActiveSupport::TestCase`, `setup` blocks, `test "description"` blocks
   - **Mocking**: `Minitest::Mock`, `stub`, `travel_to` for time
-  - **Fixtures**: YAML fixtures (Rails default), deterministic UUIDs, fixture accessor methods
+  - **Fixtures**: YAML fixtures (Rails default), fixture accessor methods
   - **Test Types**: Model tests, controller tests, integration tests, system tests (Capybara)
   - **Patterns**: `assert_difference`, `assert_changes`, `assert_no_difference`, Current context setup
   - **Coverage**: SimpleCov

data/lib/ariadna/tools/config_manager.rb

@@ -1,3 +1,4 @@
+require "fileutils"
 require "json"
 require_relative "output"
 
@@ -11,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,
@@ -88,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/tools/phase_manager.rb

@@ -1,6 +1,7 @@
 require "json"
 require "fileutils"
 require_relative "output"
+require_relative "frontmatter"
 
 module Ariadna
   module Tools

data/lib/ariadna/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ariadna
 version: !ruby/object:Gem::Version
-  version: 1.1.3
+  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