ariadna 1.2.2 → 1.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 926de51bbb2a1ecfe151263e631a8b56ad0d83cd2adb28c65dde071b3f04c1d3
-  data.tar.gz: dc451d582a82b2664f1f10095fa3324965852f1fd4241caddfe80175b2d22c73
+  metadata.gz: 3937059c39a236024b08eb67fea88f5ec4ac193e13c9a99a5a34b365a7f9d53e
+  data.tar.gz: 7b4b5a4dbc80527bfbe6202336dbe85bee931ac323a976a0207f0e3ccb3cd3e8
 SHA512:
-  metadata.gz: 6a21f498978a0e020900c8c2c84ed5d8396c3c2f541e66d0835e8982d8244fe7b0f3767905825ad9083438dc945c23897e189b5254176ef976fa83e22ea09091
-  data.tar.gz: 02b2b683e24525ee69f58cc54d57ef2aba13f70e0d4070fe2b0c7321a7dc7f34e85e37b9e371b7b773c3bf6c630f17efe6c5d08172e218937d3141c90263d561
+  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-planner.md

@@ -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.
 

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
 
@@ -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

data/data/ariadna/references/questioning.md

@@ -64,6 +64,16 @@ Use these as inspiration, not a checklist. Pick what's relevant to the thread.
 - "How will you know this is working?"
 - "What does done look like?"
 
+**Users — who this serves:**
+- "Who's the person using this? Walk me through their day."
+- "What are they doing right now without this?"
+- "What would make them stop using this?"
+
+**Bigger picture — where this is going:**
+- "Is this the whole thing, or part of something bigger?"
+- "What does success look like in 6 months?"
+- "If this works perfectly, what do you do next?"
+
 </question_types>
 
 <using_askuserquestion>
@@ -102,10 +112,12 @@ Use this as a **background checklist**, not a conversation structure. Check thes
 
 - [ ] What they're building (concrete enough to explain to a stranger)
 - [ ] Why it needs to exist (the problem or desire driving it)
-- [ ] Who it's for (even if just themselves)
+- [ ] Who it's for (what do they care about? what frustrates them?)
+- [ ] What success looks like for the builder (what outcome makes this worth building?)
 - [ ] What "done" looks like (observable outcomes)
+- [ ] What's the bigger picture (standalone tool? part of something larger? stepping stone?)
 
-Four things. If they volunteer more, capture it.
+Six things. If they volunteer more, capture it.
 
 </context_checklist>
 

data/data/ariadna/templates/project.md

@@ -17,6 +17,23 @@ Use the user's language and framing. Update whenever reality drifts from this de
 [The ONE thing that matters most. If everything else fails, this must work.
 One sentence that drives prioritization when tradeoffs arise.]
 
+## Who This Serves
+
+[Who uses this and what they care about. Not formal personas — just enough
+that downstream planning knows whose problem each feature solves.
+
+Examples:
+- **Solo creator** — Wants to publish without fighting tools. Cares about speed, not features.
+- **Small team lead** — Needs visibility into what everyone's doing. Frustrated by status meetings.
+
+If it's just you, say so: "Me — I want X because Y."]
+
+## Product Vision
+
+- **Success means:** [The outcome that justifies the effort — "teams stop using spreadsheets", "I can charge $X/month", "my workflow drops from 2 hours to 10 minutes"]
+- **Bigger picture:** [Is this standalone? Part of a platform? An experiment? A business?]
+- **Not optimizing for:** [What you're deliberately NOT chasing — growth, scale, polish, monetization, etc.]
+
 ## Requirements
 
 ### Validated
@@ -83,6 +100,20 @@ Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Perform
 - Drives prioritization when tradeoffs arise
 - Rarely changes; if it does, it's a significant pivot
 
+**Who This Serves:**
+- Informal user descriptions, not enterprise personas
+- Focus on what they care about and what frustrates them
+- "Me" is a valid answer if building for yourself
+- Drives feature prioritization: which user does this feature serve?
+- Updated when you learn more about actual users
+
+**Product Vision:**
+- The "why build this" beyond individual features
+- Success means: measurable or observable outcome that justifies the work
+- Bigger picture: product direction, not a detailed roadmap
+- Not optimizing for: explicit de-priorities that prevent scope creep
+- Rarely changes; if it does, revisit roadmap structure
+
 **Requirements — Validated:**
 - Requirements that shipped and proved valuable
 - Format: `- ✓ [Requirement] — [version/phase]`
@@ -138,8 +169,10 @@ PROJECT.md evolves throughout the project lifecycle.
 **After each milestone:**
 1. Full review of all sections
 2. Core Value check — still the right priority?
-3. Audit Out of Scope — reasons still valid?
-4. Update Context with current state (users, feedback, metrics)
+3. Who This Serves still accurate? → Update with real user feedback
+4. Product Vision success criteria met? → Celebrate or revisit
+5. Audit Out of Scope — reasons still valid?
+6. Update Context with current state (users, feedback, metrics)
 
 </evolution>
 

data/data/ariadna/templates/requirements.md

@@ -16,21 +16,21 @@ Requirements for initial release. Each maps to roadmap phases.
 
 ### Authentication
 
-- [ ] **AUTH-01**: User can sign up with email and password
-- [ ] **AUTH-02**: User receives email verification after signup
-- [ ] **AUTH-03**: User can reset password via email link
-- [ ] **AUTH-04**: User session persists across browser refresh
+- [ ] **AUTH-01**: User can sign up with email and password — *enables personalized experience*
+- [ ] **AUTH-02**: User receives email verification after signup — *prevents spam accounts*
+- [ ] **AUTH-03**: User can reset password via email link — *reduces support burden*
+- [ ] **AUTH-04**: User session persists across browser refresh — *removes friction from daily use*
 
 ### [Category 2]
 
-- [ ] **[CAT]-01**: [Requirement description]
-- [ ] **[CAT]-02**: [Requirement description]
-- [ ] **[CAT]-03**: [Requirement description]
+- [ ] **[CAT]-01**: [Requirement description] — *[why this matters]*
+- [ ] **[CAT]-02**: [Requirement description] — *[why this matters]*
+- [ ] **[CAT]-03**: [Requirement description] — *[why this matters]*
 
 ### [Category 3]
 
-- [ ] **[CAT]-01**: [Requirement description]
-- [ ] **[CAT]-02**: [Requirement description]
+- [ ] **[CAT]-01**: [Requirement description] — *[why this matters]*
+- [ ] **[CAT]-02**: [Requirement description] — *[why this matters]*
 
 ## v2 Requirements
 
@@ -79,8 +79,17 @@ Which phases cover which requirements. Updated during roadmap creation.
 **Requirement Format:**
 - ID: `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02, SOCIAL-03)
 - Description: User-centric, testable, atomic
+- Motivation: brief "why" clause after em-dash — `— *reason this matters*`
 - Checkbox: Only for v1 requirements (v2 are not yet actionable)
 
+**Requirement Motivation:**
+- Each requirement gets a brief "why" clause: `— *reason this matters*`
+- Connects features to user needs or business goals from Product Vision
+- Helps the roadmapper understand WHY requirements cluster, not just WHAT they are
+- Helps the verifier check "did we solve the problem?" not just "did we ship the feature?"
+- Keep it short: one clause, italicized, after an em-dash
+- Draw from Who This Serves and Product Vision in PROJECT.md
+
 **Categories:**
 - Derive from research FEATURES.md categories
 - Keep consistent with domain conventions
@@ -141,33 +150,33 @@ Which phases cover which requirements. Updated during roadmap creation.
 
 ### Authentication
 
-- [ ] **AUTH-01**: User can sign up with email and password
-- [ ] **AUTH-02**: User receives email verification after signup
-- [ ] **AUTH-03**: User can reset password via email link
-- [ ] **AUTH-04**: User session persists across browser refresh
+- [ ] **AUTH-01**: User can sign up with email and password — *enables personalized experience*
+- [ ] **AUTH-02**: User receives email verification after signup — *prevents spam accounts*
+- [ ] **AUTH-03**: User can reset password via email link — *reduces support burden*
+- [ ] **AUTH-04**: User session persists across browser refresh — *removes friction from daily use*
 
 ### Profiles
 
-- [ ] **PROF-01**: User can create profile with display name
-- [ ] **PROF-02**: User can upload avatar image
-- [ ] **PROF-03**: User can write bio (max 500 chars)
-- [ ] **PROF-04**: User can view other users' profiles
+- [ ] **PROF-01**: User can create profile with display name — *gives users identity in the community*
+- [ ] **PROF-02**: User can upload avatar image — *makes profiles recognizable*
+- [ ] **PROF-03**: User can write bio (max 500 chars) — *enables self-expression and discovery*
+- [ ] **PROF-04**: User can view other users' profiles — *supports finding people with shared interests*
 
 ### Content
 
-- [ ] **CONT-01**: User can create text post
-- [ ] **CONT-02**: User can upload image with post
-- [ ] **CONT-03**: User can edit own posts
-- [ ] **CONT-04**: User can delete own posts
-- [ ] **CONT-05**: User can view feed of posts
+- [ ] **CONT-01**: User can create text post — *core content creation loop*
+- [ ] **CONT-02**: User can upload image with post — *richer content drives engagement*
+- [ ] **CONT-03**: User can edit own posts — *reduces friction of sharing (can fix mistakes)*
+- [ ] **CONT-04**: User can delete own posts — *user controls their own content*
+- [ ] **CONT-05**: User can view feed of posts — *content consumption is the primary activity*
 
 ### Social
 
-- [ ] **SOCL-01**: User can follow other users
-- [ ] **SOCL-02**: User can unfollow users
-- [ ] **SOCL-03**: User can like posts
-- [ ] **SOCL-04**: User can comment on posts
-- [ ] **SOCL-05**: User can view activity feed (followed users' posts)
+- [ ] **SOCL-01**: User can follow other users — *builds the social graph that makes the feed work*
+- [ ] **SOCL-02**: User can unfollow users — *user controls their experience*
+- [ ] **SOCL-03**: User can like posts — *lightweight engagement signal*
+- [ ] **SOCL-04**: User can comment on posts — *discussion is core to community value*
+- [ ] **SOCL-05**: User can view activity feed (followed users' posts) — *personalized content keeps users returning*
 
 ## v2 Requirements
 

data/data/ariadna/templates/roadmap.md

@@ -11,6 +11,9 @@ Template for `.ariadna_planning/ROADMAP.md`.
 
 [One paragraph describing the journey from start to finish]
 
+**Product vision:** [One-liner from PROJECT.md Product Vision — what success means]
+**Building for:** [One-liner from PROJECT.md Who This Serves — who benefits]
+
 ## Phases
 
 **Phase Numbering:**
@@ -28,6 +31,7 @@ Decimal phases appear between their surrounding integers in numeric order.
 
 ### Phase 1: [Name]
 **Goal**: [What this phase delivers]
+**Why this matters**: [How this serves users or advances the product vision — one sentence]
 **Depends on**: Nothing (first phase)
 **Requirements**: [REQ-01, REQ-02, REQ-03]
 **Success Criteria** (what must be TRUE):
@@ -43,6 +47,7 @@ Plans:
 
 ### Phase 2: [Name]
 **Goal**: [What this phase delivers]
+**Why this matters**: [How this serves users or advances the product vision — one sentence]
 **Depends on**: Phase 1
 **Requirements**: [REQ-04, REQ-05]
 **Success Criteria** (what must be TRUE):
@@ -66,6 +71,7 @@ Plans:
 
 ### Phase 3: [Name]
 **Goal**: [What this phase delivers]
+**Why this matters**: [How this serves users or advances the product vision — one sentence]
 **Depends on**: Phase 2
 **Requirements**: [REQ-06, REQ-07, REQ-08]
 **Success Criteria** (what must be TRUE):
@@ -80,6 +86,7 @@ Plans:
 
 ### Phase 4: [Name]
 **Goal**: [What this phase delivers]
+**Why this matters**: [How this serves users or advances the product vision — one sentence]
 **Depends on**: Phase 3
 **Requirements**: [REQ-09, REQ-10]
 **Success Criteria** (what must be TRUE):
@@ -113,6 +120,14 @@ Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 - Progress table updated by execute workflow
 - Plan count can be "TBD" initially, refined during planning
 
+**Why this matters:**
+- One sentence connecting the phase to user needs or product vision
+- Pulled from PROJECT.md Who This Serves and Product Vision
+- NOT implementation justification ("we need auth before content")
+- IS user/business justification ("users need identity before they can own content")
+- Helps planner understand the phase's purpose, not just its scope
+- For foundational phases, "Enables everything that follows" is honest and fine
+
 **Success criteria:**
 - 2-5 observable behaviors per phase (from user's perspective)
 - Cross-checked against requirements during roadmap creation
@@ -170,6 +185,7 @@ Plans:
 
 #### Phase 5: [Name]
 **Goal**: [What this phase delivers]
+**Why this matters**: [How this serves users or advances the product vision — one sentence]
 **Depends on**: Phase 4
 **Plans**: 2 plans
 

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

@@ -630,6 +630,14 @@ Reject vague requirements. Push for specificity:
 - "Handle authentication" → "User can log in with email/password and stay logged in across sessions"
 - "Support sharing" → "User can share post via link that opens in recipient's browser"
 
+**Requirement motivation:**
+
+Each requirement should include a brief "why" clause connecting it to Who This Serves or Product Vision from PROJECT.md:
+- `User can reset password via email link — *reduces support burden*`
+- `User can create text post — *core content creation loop*`
+- Draw the "why" from the user descriptions and product vision captured earlier
+- If the "why" is obvious, it's still worth stating — it helps the roadmapper cluster phases by purpose
+
 **Present full requirements list (interactive mode only):**
 
 Show every requirement (not counts) for user confirmation:
@@ -638,13 +646,13 @@ Show every requirement (not counts) for user confirmation:
 ## v1 Requirements
 
 ### Authentication
-- [ ] **AUTH-01**: User can create account with email/password
-- [ ] **AUTH-02**: User can log in and stay logged in across sessions
-- [ ] **AUTH-03**: User can log out from any page
+- [ ] **AUTH-01**: User can create account with email/password — *enables personalized experience*
+- [ ] **AUTH-02**: User can log in and stay logged in across sessions — *removes friction from daily use*
+- [ ] **AUTH-03**: User can log out from any page — *user controls their session*
 
 ### Content
-- [ ] **CONT-01**: User can create posts with text
-- [ ] **CONT-02**: User can edit their own posts
+- [ ] **CONT-01**: User can create posts with text — *core content creation loop*
+- [ ] **CONT-02**: User can edit their own posts — *reduces friction of sharing*
 
 [... full list ...]
 

data/lib/ariadna/version.rb

@@ -1,3 +1,3 @@
 module Ariadna
-  VERSION = "1.2.2"
+  VERSION = "1.2.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ariadna
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.2.3
 platform: ruby
 authors:
 - Jorge Alvarez
@@ -9,9 +9,9 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-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.
+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.
 email: jorge@alvareznavarro.es
 executables:
 - ariadna