ariadna 1.2.1 → 1.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d45bf8e96c2f2d1d07d2c3236cfaa5e3f6c6fa43cf5f4b785be66fc5160c9ee6
-  data.tar.gz: 69364ceaebbf8755a887e9a994dee5e6490d5144a9f681447d9a0946c3c1f095
+  metadata.gz: 3937059c39a236024b08eb67fea88f5ec4ac193e13c9a99a5a34b365a7f9d53e
+  data.tar.gz: 7b4b5a4dbc80527bfbe6202336dbe85bee931ac323a976a0207f0e3ccb3cd3e8
 SHA512:
-  metadata.gz: 175abad4e06b132ae2f3489fbf7e7db92a0aaa2758d42fc8bb374b2b6151d891cf963a9e592757fd7e872443da3a46c871f8f66ad83ca48c6299a42a4782cb93
-  data.tar.gz: 0c011641fa6e541200d0e0bcbb1c83066ede0c65296c285a0e7d51970b4e626fb916c4798f7e59618bab07b867bcfc997efdd898677c917ce1e56e40b05a9f4c
+  metadata.gz: bf468ce4109266ccc1e8c42191a45977e3f5ef15aaeaca7d98e60490fc46fb7022511563bfd5a24cebb5ec20ab480142cdff6b9f8b5776e6b1a99b8bbad805b2
+  data.tar.gz: d1bc65ed4561f7f842d60276fa1362447fcbf1fe5e152a96c038d38c7e4fa8bf1324285a9032c2be9cb3519205e20136e0de757a7e869adbe691e2c01e29c3ab

data/ariadna.gemspec

@@ -4,9 +4,9 @@ Gem::Specification.new do |s|
   s.name        = "ariadna"
   s.version     = Ariadna::VERSION
   s.summary     = "A meta-prompting and context engineering system for Claude Code"
-  s.description = "Ariadna ports the GSD (Get Shit Done) system to Ruby, providing structured " \
-                  "planning, multi-agent orchestration, and verification workflows via Claude Code " \
-                  "slash commands."
+  s.description = "Ariadna helps you to create ruby on rails applications (or new features in existing ones)" \
+                  "providing structured planning, multi-agent orchestration, and verification workflows " \
+                  "via Claude Code slash commands."
   s.authors     = ["Jorge Alvarez"]
   s.email       = "jorge@alvareznavarro.es"
   s.homepage    = "https://github.com/jorgegorka/ariadna"

data/data/agents/ariadna-backend-executor.md

@@ -47,11 +47,11 @@ Extract from init JSON: `executor_model`, `commit_docs`, `phase_dir`, `plans`, `
 
 Also read STATE.md for position, decisions, blockers:
 ```bash
-cat .planning/STATE.md 2>/dev/null
+cat .ariadna_planning/STATE.md 2>/dev/null
 ```
 
-If STATE.md missing but .planning/ exists: offer to reconstruct or continue without.
-If .planning/ missing: Error — project not initialized.
+If STATE.md missing but .ariadna_planning/ exists: offer to reconstruct or continue without.
+If .ariadna_planning/ missing: Error — project not initialized.
 </step>
 
 <step name="load_plan">
@@ -168,7 +168,7 @@ git commit -m "{type}({phase}-{plan}): {concise task description}
 </task_commit_protocol>
 
 <summary_creation>
-After all tasks complete, create `{phase}-{plan}-SUMMARY.md` at `.planning/phases/XX-name/`.
+After all tasks complete, create `{phase}-{plan}-SUMMARY.md` at `.ariadna_planning/phases/XX-name/`.
 
 **Use template:** @~/.claude/ariadna/templates/summary.md
 
@@ -207,7 +207,7 @@ ariadna-tools state record-metric \
 
 <final_commit>
 ```bash
-ariadna-tools commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md
+ariadna-tools commit "docs({phase}-{plan}): complete [plan-name] plan" --files .ariadna_planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .ariadna_planning/STATE.md
 ```
 </final_commit>
 

data/data/agents/ariadna-codebase-mapper.md

@@ -6,7 +6,7 @@ color: cyan
 ---
 
 <role>
-You are an Ariadna codebase mapper. You explore a codebase for a specific focus area and write analysis documents directly to `.planning/codebase/`.
+You are an Ariadna codebase mapper. You explore a codebase for a specific focus area and write analysis documents directly to `.ariadna_planning/codebase/`.
 
 You are spawned by `/ariadna:map-codebase` with one of four focus areas:
 - **tech**: Analyze technology stack and external integrations → write STACK.md and INTEGRATIONS.md
@@ -135,7 +135,7 @@ Read key files identified during exploration. Use Glob and Grep liberally.
 </step>
 
 <step name="write_documents">
-Write document(s) to `.planning/codebase/` using the templates below.
+Write document(s) to `.ariadna_planning/codebase/` using the templates below.
 
 **Document naming:** UPPERCASE.md (e.g., STACK.md, ARCHITECTURE.md)
 
@@ -157,8 +157,8 @@ Format:
 
 **Focus:** {focus}
 **Documents written:**
-- `.planning/codebase/{DOC1}.md` ({N} lines)
-- `.planning/codebase/{DOC2}.md` ({N} lines)
+- `.ariadna_planning/codebase/{DOC1}.md` ({N} lines)
+- `.ariadna_planning/codebase/{DOC2}.md` ({N} lines)
 
 Ready for orchestrator summary.
 ```
@@ -754,7 +754,7 @@ Ready for orchestrator summary.
 <success_criteria>
 - [ ] Focus area parsed correctly
 - [ ] Codebase explored thoroughly for focus area
-- [ ] All documents for focus area written to `.planning/codebase/`
+- [ ] All documents for focus area written to `.ariadna_planning/codebase/`
 - [ ] Documents follow template structure
 - [ ] File paths included throughout documents
 - [ ] Confirmation returned (not document contents)

data/data/agents/ariadna-debugger.md

@@ -736,8 +736,8 @@ Can I observe the behavior directly?
 ## File Location
 
 ```
-DEBUG_DIR=.planning/debug
-DEBUG_RESOLVED_DIR=.planning/debug/resolved
+DEBUG_DIR=.ariadna_planning/debug
+DEBUG_RESOLVED_DIR=.ariadna_planning/debug/resolved
 ```
 
 ## File Structure
@@ -833,7 +833,7 @@ The file IS the debugging brain.
 **First:** Check for active debug sessions.
 
 ```bash
-ls .planning/debug/*.md 2>/dev/null | grep -v resolved
+ls .ariadna_planning/debug/*.md 2>/dev/null | grep -v resolved
 ```
 
 **If active sessions exist AND no $ARGUMENTS:**
@@ -854,7 +854,7 @@ ls .planning/debug/*.md 2>/dev/null | grep -v resolved
 **Create debug file IMMEDIATELY.**
 
 1. Generate slug from user input (lowercase, hyphens, max 30 chars)
-2. `mkdir -p .planning/debug`
+2. `mkdir -p .ariadna_planning/debug`
 3. Create file with initial state:
    - status: gathering
    - trigger: verbatim $ARGUMENTS
@@ -926,7 +926,7 @@ Return structured diagnosis:
 ```markdown
 ## ROOT CAUSE FOUND
 
-**Debug Session:** .planning/debug/{slug}.md
+**Debug Session:** .ariadna_planning/debug/{slug}.md
 
 **Root Cause:** {from Resolution.root_cause}
 
@@ -945,7 +945,7 @@ If inconclusive:
 ```markdown
 ## INVESTIGATION INCONCLUSIVE
 
-**Debug Session:** .planning/debug/{slug}.md
+**Debug Session:** .ariadna_planning/debug/{slug}.md
 
 **What Was Checked:**
 - {area}: {finding}
@@ -982,8 +982,8 @@ Update status to "fixing".
 Update status to "resolved".
 
 ```bash
-mkdir -p .planning/debug/resolved
-mv .planning/debug/{slug}.md .planning/debug/resolved/
+mkdir -p .ariadna_planning/debug/resolved
+mv .ariadna_planning/debug/{slug}.md .ariadna_planning/debug/resolved/
 ```
 
 **Check planning config using state load (commit_docs is available from the output):**
@@ -1006,7 +1006,7 @@ Root cause: {root_cause}"
 
 Then commit planning docs via CLI (respects `commit_docs` config automatically):
 ```bash
-ariadna-tools commit "docs: resolve debug {slug}" --files .planning/debug/resolved/{slug}.md
+ariadna-tools commit "docs: resolve debug {slug}" --files .ariadna_planning/debug/resolved/{slug}.md
 ```
 
 Report completion and offer next steps.
@@ -1029,7 +1029,7 @@ Return a checkpoint when:
 ## CHECKPOINT REACHED
 
 **Type:** [human-verify | human-action | decision]
-**Debug Session:** .planning/debug/{slug}.md
+**Debug Session:** .ariadna_planning/debug/{slug}.md
 **Progress:** {evidence_count} evidence entries, {eliminated_count} hypotheses eliminated
 
 ### Investigation State
@@ -1100,7 +1100,7 @@ Orchestrator presents checkpoint to user, gets response, spawns fresh continuati
 ```markdown
 ## ROOT CAUSE FOUND
 
-**Debug Session:** .planning/debug/{slug}.md
+**Debug Session:** .ariadna_planning/debug/{slug}.md
 
 **Root Cause:** {specific cause with evidence}
 
@@ -1121,7 +1121,7 @@ Orchestrator presents checkpoint to user, gets response, spawns fresh continuati
 ```markdown
 ## DEBUG COMPLETE
 
-**Debug Session:** .planning/debug/resolved/{slug}.md
+**Debug Session:** .ariadna_planning/debug/resolved/{slug}.md
 
 **Root Cause:** {what was wrong}
 **Fix Applied:** {what was changed}
@@ -1139,7 +1139,7 @@ Orchestrator presents checkpoint to user, gets response, spawns fresh continuati
 ```markdown
 ## INVESTIGATION INCONCLUSIVE
 
-**Debug Session:** .planning/debug/{slug}.md
+**Debug Session:** .ariadna_planning/debug/{slug}.md
 
 **What Was Checked:**
 - {area 1}: {finding}

data/data/agents/ariadna-executor.md

@@ -26,11 +26,11 @@ Extract from init JSON: `executor_model`, `commit_docs`, `phase_dir`, `plans`, `
 
 Also read STATE.md for position, decisions, blockers:
 ```bash
-cat .planning/STATE.md 2>/dev/null
+cat .ariadna_planning/STATE.md 2>/dev/null
 ```
 
-If STATE.md missing but .planning/ exists: offer to reconstruct or continue without.
-If .planning/ missing: Error — project not initialized.
+If STATE.md missing but .ariadna_planning/ exists: offer to reconstruct or continue without.
+If .ariadna_planning/ missing: Error — project not initialized.
 </step>
 
 <step name="load_plan">
@@ -272,7 +272,7 @@ git commit -m "{type}({phase}-{plan}): {concise task description}
 </task_commit_protocol>
 
 <summary_creation>
-After all tasks complete, create `{phase}-{plan}-SUMMARY.md` at `.planning/phases/XX-name/`.
+After all tasks complete, create `{phase}-{plan}-SUMMARY.md` at `.ariadna_planning/phases/XX-name/`.
 
 **Use template:** @~/.claude/ariadna/templates/summary.md
 
@@ -365,7 +365,7 @@ ariadna-tools state add-blocker "Blocker description"
 
 <final_commit>
 ```bash
-ariadna-tools commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md
+ariadna-tools commit "docs({phase}-{plan}): complete [plan-name] plan" --files .ariadna_planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .ariadna_planning/STATE.md
 ```
 
 Separate from per-task commits — captures execution results only.

data/data/agents/ariadna-frontend-executor.md

@@ -46,11 +46,11 @@ Extract from init JSON: `executor_model`, `commit_docs`, `phase_dir`, `plans`, `
 
 Also read STATE.md for position, decisions, blockers:
 ```bash
-cat .planning/STATE.md 2>/dev/null
+cat .ariadna_planning/STATE.md 2>/dev/null
 ```
 
-If STATE.md missing but .planning/ exists: offer to reconstruct or continue without.
-If .planning/ missing: Error — project not initialized.
+If STATE.md missing but .ariadna_planning/ exists: offer to reconstruct or continue without.
+If .ariadna_planning/ missing: Error — project not initialized.
 </step>
 
 <step name="load_plan">
@@ -166,7 +166,7 @@ git commit -m "{type}({phase}-{plan}): {concise task description}
 </task_commit_protocol>
 
 <summary_creation>
-After all tasks complete, create `{phase}-{plan}-SUMMARY.md` at `.planning/phases/XX-name/`.
+After all tasks complete, create `{phase}-{plan}-SUMMARY.md` at `.ariadna_planning/phases/XX-name/`.
 
 **Use template:** @~/.claude/ariadna/templates/summary.md
 
@@ -205,7 +205,7 @@ ariadna-tools state record-metric \
 
 <final_commit>
 ```bash
-ariadna-tools commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md
+ariadna-tools commit "docs({phase}-{plan}): complete [plan-name] plan" --files .ariadna_planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .ariadna_planning/STATE.md
 ```
 </final_commit>
 

data/data/agents/ariadna-integration-checker.md

@@ -57,7 +57,7 @@ For each phase, extract what it provides and what it should consume.
 
 ```bash
 # Key modules and classes from each phase
-for summary in .planning/phases/*/*-SUMMARY.md; do
+for summary in .ariadna_planning/phases/*/*-SUMMARY.md; do
   echo "=== $summary ==="
   grep -A 10 "Key Files\|Exports\|Provides" "$summary" 2>/dev/null
 done

data/data/agents/ariadna-phase-researcher.md

@@ -177,7 +177,7 @@ Priority: Context7 > Official Docs > Official GitHub > Verified WebSearch > Unve
 
 ## RESEARCH.md Structure
 
-**Location:** `.planning/phases/XX-name/{phase}-RESEARCH.md`
+**Location:** `.ariadna_planning/phases/XX-name/{phase}-RESEARCH.md`
 
 ```markdown
 # Phase [X]: [Name] - Research

data/data/agents/ariadna-planner.md

@@ -471,9 +471,9 @@ Output: [Artifacts created]
 </execution_context>
 
 <context>
-@.planning/PROJECT.md
-@.planning/ROADMAP.md
-@.planning/STATE.md
+@.ariadna_planning/PROJECT.md
+@.ariadna_planning/ROADMAP.md
+@.ariadna_planning/STATE.md
 
 # Only reference prior plan SUMMARYs if genuinely needed
 @path/to/relevant/source.rb
@@ -500,7 +500,7 @@ Output: [Artifacts created]
 </success_criteria>
 
 <output>
-After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
+After completion, create `.ariadna_planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
 </output>
 ```
 
@@ -562,6 +562,10 @@ Take phase goal from ROADMAP.md. Must be outcome-shaped, not task-shaped.
 - Good: "Working chat interface" (outcome)
 - Bad: "Build chat components" (task)
 
+Also read the "Why this matters" line from ROADMAP.md for this phase. This tells you the PURPOSE behind the goal. Use it to prioritize truths: truths that directly serve the stated purpose are more critical than nice-to-haves.
+
+Example: If "Why this matters" = "Users need identity before they can own content", then "User can create account" is more critical than "Password has strength indicator."
+
 **Step 2: Derive Observable Truths**
 "What must be TRUE for this goal to be achieved?" List 3-7 truths from USER's perspective.
 
@@ -853,7 +857,7 @@ Triggered when orchestrator provides `<revision_context>` with checker issues. N
 ### Step 1: Load Existing Plans
 
 ```bash
-cat .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
+cat .ariadna_planning/phases/$PHASE-*/$PHASE-*-PLAN.md
 ```
 
 Build mental model of current plan structure, existing tasks, must_haves.
@@ -901,7 +905,7 @@ Group by plan, dimension, severity.
 ### Step 6: Commit
 
 ```bash
-ariadna-tools commit "fix($PHASE): revise plans based on checker feedback" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
+ariadna-tools commit "fix($PHASE): revise plans based on checker feedback" --files .ariadna_planning/phases/$PHASE-*/$PHASE-*-PLAN.md
 ```
 
 ### Step 7: Return Revision Summary
@@ -920,8 +924,8 @@ ariadna-tools commit "fix($PHASE): revise plans based on checker feedback" --fil
 
 ### Files Updated
 
-- .planning/phases/16-xxx/16-01-PLAN.md
-- .planning/phases/16-xxx/16-02-PLAN.md
+- .ariadna_planning/phases/16-xxx/16-01-PLAN.md
+- .ariadna_planning/phases/16-xxx/16-02-PLAN.md
 
 {If any issues NOT addressed:}
 
@@ -947,17 +951,17 @@ Extract from init JSON: `planner_model`, `researcher_model`, `checker_model`, `c
 
 Also read STATE.md for position, decisions, blockers:
 ```bash
-cat .planning/STATE.md 2>/dev/null
+cat .ariadna_planning/STATE.md 2>/dev/null
 ```
 
-If STATE.md missing but .planning/ exists, offer to reconstruct or continue without.
+If STATE.md missing but .ariadna_planning/ exists, offer to reconstruct or continue without.
 </step>
 
 <step name="load_codebase_context">
 Check for codebase map:
 
 ```bash
-ls .planning/codebase/*.md 2>/dev/null
+ls .ariadna_planning/codebase/*.md 2>/dev/null
 ```
 
 If exists, load relevant documents by phase type:
@@ -976,8 +980,8 @@ If exists, load relevant documents by phase type:
 
 <step name="identify_phase">
 ```bash
-cat .planning/ROADMAP.md
-ls .planning/phases/
+cat .ariadna_planning/ROADMAP.md
+ls .ariadna_planning/phases/
 ```
 
 If multiple phases available, ask which to plan. If obvious (first incomplete), proceed.
@@ -1011,7 +1015,7 @@ Select top 2-4 phases. Skip phases with no relevance signal.
 
 **Step 3 — Read full SUMMARYs for selected phases:**
 ```bash
-cat .planning/phases/{selected-phase}/*-SUMMARY.md
+cat .ariadna_planning/phases/{selected-phase}/*-SUMMARY.md
 ```
 
 From full SUMMARYs extract:
@@ -1103,7 +1107,7 @@ Present breakdown with wave structure. Wait for confirmation in interactive mode
 <step name="write_phase_prompt">
 Use template structure for each PLAN.md.
 
-Write to `.planning/phases/XX-name/{phase}-{NN}-PLAN.md`
+Write to `.ariadna_planning/phases/XX-name/{phase}-{NN}-PLAN.md`
 
 Include all frontmatter fields.
 </step>
@@ -1139,7 +1143,7 @@ Returns JSON: `{ valid, errors, warnings, task_count, tasks }`
 <step name="update_roadmap">
 Update ROADMAP.md to finalize phase placeholders:
 
-1. Read `.planning/ROADMAP.md`
+1. Read `.ariadna_planning/ROADMAP.md`
 2. Find phase entry (`### Phase {N}:`)
 3. Update placeholders:
 
@@ -1162,7 +1166,7 @@ Plans:
 
 <step name="git_commit">
 ```bash
-ariadna-tools commit "docs($PHASE): create phase plan" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md .planning/ROADMAP.md
+ariadna-tools commit "docs($PHASE): create phase plan" --files .ariadna_planning/phases/$PHASE-*/$PHASE-*-PLAN.md .ariadna_planning/ROADMAP.md
 ```
 </step>
 

data/data/agents/ariadna-project-researcher.md

@@ -1,6 +1,6 @@
 ---
 name: ariadna-project-researcher
-description: Researches domain ecosystem before roadmap creation. Produces files in .planning/research/ consumed during roadmap creation. Spawned by /ariadna:new-project or /ariadna:new-milestone orchestrators.
+description: Researches domain ecosystem before roadmap creation. Produces files in .ariadna_planning/research/ consumed during roadmap creation. Spawned by /ariadna:new-project or /ariadna:new-milestone orchestrators.
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
 color: cyan
 ---
@@ -8,7 +8,7 @@ color: cyan
 <role>
 You are an Ariadna project researcher spawned by `/ariadna:new-project` or `/ariadna:new-milestone` (Phase 6: Research).
 
-Answer "What does this domain ecosystem look like?" Write research files in `.planning/research/` that inform roadmap creation.
+Answer "What does this domain ecosystem look like?" Write research files in `.ariadna_planning/research/` that inform roadmap creation.
 
 Your files feed the roadmap:
 
@@ -167,7 +167,7 @@ Never present LOW confidence findings as authoritative.
 
 <output_formats>
 
-All files → `.planning/research/`
+All files → `.ariadna_planning/research/`
 
 ## SUMMARY.md
 
@@ -515,7 +515,7 @@ Run pre-submission checklist (see verification_protocol).
 
 ## Step 5: Write Output Files
 
-In `.planning/research/`:
+In `.ariadna_planning/research/`:
 1. **SUMMARY.md** — Always
 2. **STACK.md** — Always
 3. **FEATURES.md** — Always
@@ -549,11 +549,11 @@ In `.planning/research/`:
 
 | File | Purpose |
 |------|---------|
-| .planning/research/SUMMARY.md | Executive summary with roadmap implications |
-| .planning/research/STACK.md | Technology recommendations |
-| .planning/research/FEATURES.md | Feature landscape |
-| .planning/research/ARCHITECTURE.md | Architecture patterns |
-| .planning/research/PITFALLS.md | Domain pitfalls |
+| .ariadna_planning/research/SUMMARY.md | Executive summary with roadmap implications |
+| .ariadna_planning/research/STACK.md | Technology recommendations |
+| .ariadna_planning/research/FEATURES.md | Feature landscape |
+| .ariadna_planning/research/ARCHITECTURE.md | Architecture patterns |
+| .ariadna_planning/research/PITFALLS.md | Domain pitfalls |
 
 ### Confidence Assessment
 
@@ -608,7 +608,7 @@ Research is complete when:
 - [ ] Domain pitfalls catalogued
 - [ ] Source hierarchy followed (Context7 → Official → WebSearch)
 - [ ] All findings have confidence levels
-- [ ] Output files created in `.planning/research/`
+- [ ] Output files created in `.ariadna_planning/research/`
 - [ ] SUMMARY.md includes roadmap implications
 - [ ] Files written (DO NOT commit — orchestrator handles this)
 - [ ] Structured return provided to orchestrator

data/data/agents/ariadna-research-synthesizer.md

@@ -44,10 +44,10 @@ Your SUMMARY.md is consumed by the ariadna-roadmapper agent which uses it to:
 Read all 4 research files:
 
 ```bash
-cat .planning/research/STACK.md
-cat .planning/research/FEATURES.md
-cat .planning/research/ARCHITECTURE.md
-cat .planning/research/PITFALLS.md
+cat .ariadna_planning/research/STACK.md
+cat .ariadna_planning/research/FEATURES.md
+cat .ariadna_planning/research/ARCHITECTURE.md
+cat .ariadna_planning/research/PITFALLS.md
 
 # Planning config loaded via ariadna-tools in commit step
 ```
@@ -121,14 +121,14 @@ Identify gaps that couldn't be resolved and need attention during planning.
 
 Use template: ~/.claude/ariadna/templates/research-project/SUMMARY.md
 
-Write to `.planning/research/SUMMARY.md`
+Write to `.ariadna_planning/research/SUMMARY.md`
 
 ## Step 7: Commit All Research
 
 The 4 parallel researcher agents write files but do NOT commit. You commit everything together.
 
 ```bash
-ariadna-tools commit "docs: complete project research" --files .planning/research/
+ariadna-tools commit "docs: complete project research" --files .ariadna_planning/research/
 ```
 
 ## Step 8: Return Summary
@@ -160,12 +160,12 @@ When SUMMARY.md is written and committed:
 ## SYNTHESIS COMPLETE
 
 **Files synthesized:**
-- .planning/research/STACK.md
-- .planning/research/FEATURES.md
-- .planning/research/ARCHITECTURE.md
-- .planning/research/PITFALLS.md
+- .ariadna_planning/research/STACK.md
+- .ariadna_planning/research/FEATURES.md
+- .ariadna_planning/research/ARCHITECTURE.md
+- .ariadna_planning/research/PITFALLS.md
 
-**Output:** .planning/research/SUMMARY.md
+**Output:** .ariadna_planning/research/SUMMARY.md
 
 ### Executive Summary
 

data/data/agents/ariadna-roadmapper.md

@@ -16,6 +16,7 @@ Your job: Transform requirements into a phase structure that delivers the projec
 
 **Core responsibilities:**
 - Derive phases from requirements (not impose arbitrary structure)
+- Connect phases to product vision (why each phase matters, not just what it delivers)
 - Validate 100% requirement coverage (no orphans)
 - Apply goal-backward thinking at phase level
 - Create success criteria (2-5 observable behaviors per phase)
@@ -29,6 +30,7 @@ Your ROADMAP.md is consumed by `/ariadna:plan-phase` which uses it to:
 | Output | How Plan-Phase Uses It |
 |--------|------------------------|
 | Phase goals | Decomposed into executable plans |
+| Why this matters | Prioritize tasks that serve the phase's purpose |
 | Success criteria | Inform must_haves derivation |
 | Requirement mappings | Ensure plans cover phase scope |
 | Dependencies | Order plan execution |
@@ -79,6 +81,18 @@ Every v1 requirement must map to exactly one phase. No orphans. No duplicates.
 If a requirement doesn't fit any phase → create a phase or defer to v2.
 If a requirement fits multiple phases → assign to ONE (usually the first that could deliver it).
 
+## Phases Serve a Purpose
+
+Each phase doesn't just deliver features — it advances the product toward its vision.
+
+When identifying phases, check PROJECT.md for:
+- **Who This Serves** — which user does this phase primarily serve?
+- **Product Vision** — how does this phase advance toward the stated success outcome?
+
+Write a "Why this matters" line for each phase that answers: "If we shipped only this phase and nothing else, what user problem would be better?"
+
+Don't force it. If a phase is purely foundational (setup, CI/CD), "Why this matters" = "Enables everything that follows." That's honest and fine.
+
 </philosophy>
 
 <goal_backward_phases>
@@ -93,6 +107,16 @@ Take the phase goal from your phase identification. This is the outcome, not wor
 - Good: "Users can securely access their accounts" (outcome)
 - Bad: "Build authentication" (task)
 
+**Step 1.5: State Why This Matters**
+Using Who This Serves and Product Vision from PROJECT.md, write one sentence explaining why this phase matters to users or the product.
+
+- Good: "Users need identity before they can own content or build reputation." (connects to user need)
+- Good: "Content creation is the core value loop — without it, the product is empty." (connects to product vision)
+- Bad: "Authentication is required for security." (technical justification, not user/business)
+- Fine: "Enables everything that follows." (honest for foundational phases)
+
+This becomes the "Why this matters" line in ROADMAP.md phase details.
+
 **Step 2: Derive Observable Truths (2-5 per phase)**
 List what users can observe/do when the phase completes.
 
@@ -289,8 +313,8 @@ After roadmap creation, REQUIREMENTS.md gets updated with phase mappings:
 Use template from `~/.claude/ariadna/templates/roadmap.md`.
 
 Key sections:
-- Overview (2-3 sentences)
-- Phases with Goal, Dependencies, Requirements, Success Criteria
+- Overview (2-3 sentences + product vision one-liner + building for one-liner)
+- Phases with Goal, Why This Matters, Dependencies, Requirements, Success Criteria
 - Progress table
 
 ## STATE.md Structure
@@ -353,8 +377,8 @@ Approve roadmap or provide feedback for revision.
 ## Step 1: Receive Context
 
 Orchestrator provides:
-- PROJECT.md content (core value, constraints)
-- REQUIREMENTS.md content (v1 requirements with REQ-IDs)
+- PROJECT.md content (core value, who this serves, product vision, constraints)
+- REQUIREMENTS.md content (v1 requirements with REQ-IDs and motivation clauses)
 - research/SUMMARY.md content (if exists - phase suggestions)
 - config.json (depth setting)
 
@@ -398,9 +422,10 @@ Apply phase identification methodology:
 
 For each phase, apply goal-backward:
 1. State phase goal (outcome, not task)
-2. Derive 2-5 observable truths (user perspective)
-3. Cross-check against requirements
-4. Flag any gaps
+2. State why this matters (connects to users or product vision)
+3. Derive 2-5 observable truths (user perspective)
+4. Cross-check against requirements
+5. Flag any gaps
 
 ## Step 6: Validate Coverage
 
@@ -446,11 +471,11 @@ When files are written and returning to orchestrator:
 ## ROADMAP CREATED
 
 **Files written:**
-- .planning/ROADMAP.md
-- .planning/STATE.md
+- .ariadna_planning/ROADMAP.md
+- .ariadna_planning/STATE.md
 
 **Updated:**
-- .planning/REQUIREMENTS.md (traceability section)
+- .ariadna_planning/REQUIREMENTS.md (traceability section)
 
 ### Summary
 
@@ -476,8 +501,8 @@ When files are written and returning to orchestrator:
 ### Files Ready for Review
 
 User can review actual files:
-- `cat .planning/ROADMAP.md`
-- `cat .planning/STATE.md`
+- `cat .ariadna_planning/ROADMAP.md`
+- `cat .ariadna_planning/STATE.md`
 
 {If gaps found during creation:}
 
@@ -500,9 +525,9 @@ After incorporating user feedback and updating files:
 - {change 2}
 
 **Files updated:**
-- .planning/ROADMAP.md
-- .planning/STATE.md (if needed)
-- .planning/REQUIREMENTS.md (if traceability changed)
+- .ariadna_planning/ROADMAP.md
+- .ariadna_planning/STATE.md (if needed)
+- .ariadna_planning/REQUIREMENTS.md (if traceability changed)
 
 ### Updated Summary
 
@@ -597,6 +622,7 @@ Roadmap is complete when:
 Quality indicators:
 
 - **Coherent phases:** Each delivers one complete, verifiable capability
+- **Purpose-connected:** Each phase has a "why this matters" tied to users or product vision
 - **Clear success criteria:** Observable from user perspective, not implementation details
 - **Full coverage:** Every requirement mapped, no orphans
 - **Natural structure:** Phases feel inevitable, not arbitrary