ariadna 1.2.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 926de51bbb2a1ecfe151263e631a8b56ad0d83cd2adb28c65dde071b3f04c1d3
-  data.tar.gz: dc451d582a82b2664f1f10095fa3324965852f1fd4241caddfe80175b2d22c73
+  metadata.gz: a3292cf913eaab6a58897e041b3d334f63b8d7ed95591a291595cb43e1c108e4
+  data.tar.gz: 78026d0448227242095141f4dbf8f9583ceecd0c334912912b5d229638f34617
 SHA512:
-  metadata.gz: 6a21f498978a0e020900c8c2c84ed5d8396c3c2f541e66d0835e8982d8244fe7b0f3767905825ad9083438dc945c23897e189b5254176ef976fa83e22ea09091
-  data.tar.gz: 02b2b683e24525ee69f58cc54d57ef2aba13f70e0d4070fe2b0c7321a7dc7f34e85e37b9e371b7b773c3bf6c630f17efe6c5d08172e218937d3141c90263d561
+  metadata.gz: f6a9a7e4b55b6fe338a4c7135e8ddbc9b15c918a2152f20bfda7efeb4f195a2e8d09412f1a3c66acbd895609938be5b197a571bd14dff7de34b47f45ac96d553
+  data.tar.gz: 2c725bd9aa6a133b5421c2f5a84ebe3c8d3122ac02b41591f78489b626d5f1e1a9d6181b1765728bf01b9a1bd77719a59c038817e6b5f7e8fd6faee4b6d5fe8e

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-phase-researcher.md

@@ -460,7 +460,7 @@ Research is complete when:
 
 Quality indicators:
 
-- **Specific, not vague:** "Devise 4.9 with OmniAuth 2.1" not "use Devise"
+- **Specific, not vague:** "Rails 8 auth generator with has_secure_password" not "add authentication"
 - **Verified, not assumed:** Findings cite Context7 or official docs
 - **Honest about gaps:** LOW confidence items flagged, unknowns admitted
 - **Actionable:** Planner could create tasks based on this research

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/checkpoints.md

@@ -124,30 +124,32 @@ Plans execute autonomously. Checkpoints formalize interaction points where human
 ```
 
 **Example: Auth Provider Selection**
+Note: Only present this checkpoint if the user explicitly asks to evaluate auth gems. For new projects, default to `has_secure_password` (Rails 8 auth generator) without asking.
 ```xml
 <task type="checkpoint:decision" gate="blocking">
   <decision>Select authentication approach</decision>
   <context>
-    Need user authentication for the app. Three solid options with different tradeoffs.
+    Need user authentication for the app. Rails built-in auth is the recommended default.
+    Only consider external gems if the user explicitly requests them.
   </context>
   <options>
+    <option id="has_secure_password">
+      <name>has_secure_password (built-in) — Recommended</name>
+      <pros>No dependencies, full control, simple and lightweight, easy to understand, Rails 8 auth generator scaffolds everything</pros>
+      <cons>More manual setup for advanced features (OAuth, 2FA)</cons>
+    </option>
     <option id="devise">
-      <name>Devise</name>
-      <pros>Most popular Rails auth gem, full-featured (registration, password reset, OAuth), well-maintained</pros>
+      <name>Devise (only if explicitly requested)</name>
+      <pros>Full-featured (registration, password reset, OAuth), well-maintained</pros>
       <cons>Heavy dependency, opinionated, can be hard to customize deeply</cons>
     </option>
-    <option id="has_secure_password">
-      <name>has_secure_password (built-in)</name>
-      <pros>No dependencies, full control, simple and lightweight, easy to understand</pros>
-      <cons>More manual setup, you build everything yourself (password reset, OAuth)</cons>
-    </option>
     <option id="rodauth">
-      <name>Rodauth</name>
+      <name>Rodauth (only if explicitly requested)</name>
       <pros>Security-focused, modular features, database-backed configuration, excellent 2FA</pros>
-      <cons>Smaller community than Devise, different conventions, steeper learning curve</cons>
+      <cons>Smaller community, different conventions, steeper learning curve</cons>
     </option>
   </options>
-  <resume-signal>Select: devise, has_secure_password, or rodauth</resume-signal>
+  <resume-signal>Select: has_secure_password (default), devise, or rodauth</resume-signal>
 </task>
 ```
 
@@ -314,20 +316,20 @@ Decision: Which auth approach should we use?
 Context: Need user authentication. Three options with different tradeoffs.
 
 Options:
-  1. devise - Full-featured auth gem, batteries included
+  1. has_secure_password - Built-in Rails (Recommended)
+     Pros: No dependencies, full control, simple, Rails 8 auth generator scaffolds everything
+     Cons: More manual setup for advanced features (OAuth, 2FA)
+
+  2. devise - Full-featured auth gem (only if explicitly requested)
      Pros: Registration, password reset, OAuth support, well-maintained
      Cons: Heavy dependency, opinionated, hard to customize deeply
 
-  2. has_secure_password - Built-in Rails, lightweight
-     Pros: No dependencies, full control, simple and easy to understand
-     Cons: More manual setup, build password reset and OAuth yourself
-
-  3. rodauth - Security-focused, modular
+  3. rodauth - Security-focused, modular (only if explicitly requested)
      Pros: Excellent 2FA, database-backed config, modular features
      Cons: Smaller community, different conventions, steeper learning curve
 
 ────────────────────────────────────────────────────────
-→ YOUR ACTION: Select devise, has_secure_password, or rodauth
+→ YOUR ACTION: Select has_secure_password (default), devise, or rodauth
 ────────────────────────────────────────────────────────
 ```
 
@@ -581,7 +583,7 @@ timeout 30 bash -c 'until curl -s localhost:3000 > /dev/null 2>&1; do sleep 1; d
 <task type="auto">
   <name>Create user model and migration</name>
   <files>app/models/user.rb, db/migrate/xxx_create_users.rb</files>
-  <action>Generate User model with Devise or has_secure_password, run migration</action>
+  <action>Generate User model with has_secure_password (Rails 8 auth generator), run migration</action>
   <verify>bin/rails db:migrate succeeds, User.count returns 0</verify>
 </task>
 

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/references/rails-conventions.md

@@ -16,7 +16,7 @@ Pre-baked Rails knowledge for Ariadna planning and execution agents. This docume
 | 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 |
+| Auth | Rails 8 built-in authentication (`has_secure_password` + auth generator) | No external gems needed |
 | Email | Action Mailer | Built-in |
 | File Upload | Active Storage | Built-in |
 | API | Rails API mode or Jbuilder | Built-in |
@@ -24,6 +24,9 @@ Pre-baked Rails knowledge for Ariadna planning and execution agents. This docume
 | Linting | RuboCop + rubocop-rails | Standard community linting |
 
 **What NOT to use (and why):**
+- Devise unless explicitly requested by the user — Rails 8 auth generator + `has_secure_password` covers signup, login, password reset, session management out of the box
+- Pundit/CanCanCan unless explicitly requested — `before_action` checks + `Current` context handle authorization for most apps without adding a gem
+- acts_as_tenant — use `Current.account` scoping with explicit scopes (see backend guide); no gem needed for path-based multi-tenancy
 - 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
@@ -32,6 +35,28 @@ Pre-baked Rails knowledge for Ariadna planning and execution agents. This docume
 
 </standard_stack>
 
+<rails_defaults_first>
+
+## Rails Defaults First (Opinionated)
+
+For new projects, ALWAYS start with Rails built-in solutions. Only introduce external gems when the user explicitly requests them or requirements demonstrably exceed what Rails provides.
+
+| Need | Rails Default | External Gem (only if explicitly requested) |
+|------|--------------|---------------------------------------------|
+| Authentication | `has_secure_password` + Rails 8 auth generator | Devise |
+| Authorization | `before_action` + `Current` context | Pundit, CanCanCan |
+| Multi-tenancy | `Current.account` + explicit scoping | acts_as_tenant |
+| Background Jobs | Solid Queue | Sidekiq |
+| Caching | Solid Cache | Redis |
+| WebSockets | Solid Cable | Redis + AnyCable |
+| Testing | Minitest + fixtures | RSpec + FactoryBot |
+
+**Why:** External gems add dependencies, upgrade burden, and conceptual overhead. Rails 8 ships with excellent defaults that cover 90% of use cases. Starting with built-ins keeps the app simple and maintainable.
+
+**The rule:** Never recommend Devise, Pundit, acts_as_tenant, or similar gems as the default choice for new projects. If the user hasn't asked for them, use Rails built-ins. If the user asks for "authentication", build it with `has_secure_password`. If they ask for "authorization", use `before_action` checks. If they ask for "multi-tenancy", use `Current.account` scoping.
+
+</rails_defaults_first>
+
 <architecture_patterns>
 
 ## Rails Architecture Patterns
@@ -369,8 +394,8 @@ These domains are well-understood in Rails and don't need web research:
 | 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 |
+| Authentication | Rails 8 auth generator, has_secure_password | No |
+| Authorization | before_action + Current context, hand-rolled | No |
 | Background Jobs | Solid Queue, ActiveJob | No |
 | Email | Action Mailer, letter_opener | No |
 | File Uploads | Active Storage | No |

data/data/ariadna/templates/codebase/architecture.md

@@ -214,7 +214,7 @@ Template for `.ariadna_planning/codebase/ARCHITECTURE.md` - captures conceptual
 - [Approach: e.g., "Rails authentication generator with `Authentication` concern", "has_secure_password with custom auth", "OmniAuth for OAuth"]
 
 **Authorization:**
-- [Approach: e.g., "Pundit policies", "CanCanCan abilities", "Custom `before_action` checks"]
+- [Approach: e.g., "Custom `before_action` checks with `Current` context", "Pundit policies (if explicitly chosen)", "CanCanCan abilities (if explicitly chosen)"]
 
 **Caching:**
 - [Approach: e.g., "Fragment caching in views", "Russian doll caching", "Rails.cache with Solid Cache/Redis"]

data/data/ariadna/templates/codebase/stack.md

@@ -123,7 +123,7 @@ Template for `.ariadna_planning/codebase/STACK.md` - captures the technology fou
 
 **Critical:**
 - authentication (built-in) — Session-based auth
-- authorization - custom implementation (no gem) — Role-based access control, pundit
+- authorization - custom implementation (before_action + Current) — Role-based access control
 - solid_queue — Background jobs (Rails 8 default)
 
 **Infrastructure:**

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/research-project/ARCHITECTURE.md

@@ -164,7 +164,7 @@ test/                      # [test framework: Minitest (default) or spec/ if RSp
 ### Authentication and Authorization
 
 **Authentication:** [Rails authentication generator / has_secure_password / custom / other]
-**Authorization:** [Custom / Pundit / CanCanCan / Action Policy / other]
+**Authorization:** [Custom (before_action + Current context) / Pundit (if explicitly requested) / other]
 
 ### Internationalization (I18n)
 

data/data/ariadna/templates/research-project/STACK.md

@@ -59,7 +59,7 @@ Template for `.ariadna_planning/research/STACK.md` — discovered technology sta
 | Category | Discovered Value | Evidence |
 |----------|-----------------|----------|
 | Authentication | [Rails authentication generator/Rodauth/Clearance/custom/none] | [Gemfile, user model] |
-| Authorization | [Custom/Pundit/CanCanCan/Action Policy/none] | [Gemfile, policy files] |
+| Authorization | [Custom (before_action + Current) / Pundit (if explicitly requested) / none] | [Gemfile, policy files] |
 | OAuth/social login | [OmniAuth/Doorkeeper/none] | [Gemfile, initializers] |
 | API authentication | [API tokens/JWT/OAuth2/none] | [Gemfile, controller concerns] |
 
@@ -223,7 +223,7 @@ bin/rails server
 
 **Authentication & Authorization:**
 - Look for `Authentication` concern generated by `rails generate authentication`.
-- Look for `app/policies/` (Pundit) or `app/models/ability.rb` (CanCanCan) or custom authorization logic.
+- Look for custom authorization in `before_action` filters and `Current` context (preferred), or `app/policies/` (Pundit) or `app/models/ability.rb` (CanCanCan) if gems were chosen.
 - Check `app/models/user.rb` for authentication modules.
 
 **Testing:**

data/data/ariadna/templates/research-project/SUMMARY.md

@@ -53,7 +53,7 @@ Template for `.ariadna_planning/research/SUMMARY.md` — executive summary of pr
 
 **Authentication & authorization:**
 - [Auth solution]: [purpose] — [why recommended — e.g., Rails authentication generator for session-based auth]
-- [Authorization]: [purpose] — [why recommended — e.g., before_action, Pundit for policies, Action Policy for scalable rules]
+- [Authorization]: [purpose] — [why recommended — e.g., before_action + Current context (default), Pundit only if explicitly requested]
 
 **Additional gems:**
 - [Gem]: [purpose] — [why recommended]

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.3.0"
 end

metadata

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