ariadna 1.3.1 → 2.0.0

data/data/ariadna/references/phase-argument-parsing.md

@@ -1,61 +0,0 @@
-# Phase Argument Parsing
-
-Parse and normalize phase arguments for commands that operate on phases.
-
-## Extraction
-
-From `$ARGUMENTS`:
-- Extract phase number (first numeric argument)
-- Extract flags (prefixed with `--`)
-- Remaining text is description (for insert/add commands)
-
-## Using ariadna-tools
-
-The `find-phase` command handles normalization and validation in one step:
-
-```bash
-PHASE_INFO=$(ariadna-tools find-phase "${PHASE}")
-```
-
-Returns JSON with:
-- `found`: true/false
-- `directory`: Full path to phase directory
-- `phase_number`: Normalized number (e.g., "06", "06.1")
-- `phase_name`: Name portion (e.g., "foundation")
-- `plans`: Array of PLAN.md files
-- `summaries`: Array of SUMMARY.md files
-
-## Manual Normalization (Legacy)
-
-Zero-pad integer phases to 2 digits. Preserve decimal suffixes.
-
-```bash
-# Normalize phase number
-if [[ "$PHASE" =~ ^[0-9]+$ ]]; then
-  # Integer: 8 → 08
-  PHASE=$(printf "%02d" "$PHASE")
-elif [[ "$PHASE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
-  # Decimal: 2.1 → 02.1
-  PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
-fi
-```
-
-## Validation
-
-Use `roadmap get-phase` to validate phase exists:
-
-```bash
-PHASE_CHECK=$(ariadna-tools roadmap get-phase "${PHASE}")
-if [ "$(echo "$PHASE_CHECK" | jq -r '.found')" = "false" ]; then
-  echo "ERROR: Phase ${PHASE} not found in roadmap"
-  exit 1
-fi
-```
-
-## Directory Lookup
-
-Use `find-phase` for directory lookup:
-
-```bash
-PHASE_DIR=$(ariadna-tools find-phase "${PHASE}" --raw)
-```

data/data/ariadna/references/planning-config.md

@@ -1,194 +0,0 @@
-<planning_config>
-
-Configuration options for `.ariadna_planning/` directory behavior.
-
-<config_schema>
-```json
-"planning": {
-  "commit_docs": true,
-  "search_gitignored": false
-},
-"git": {
-  "branching_strategy": "none",
-  "phase_branch_template": "ariadna/phase-{phase}-{slug}",
-  "milestone_branch_template": "ariadna/{milestone}-{slug}"
-}
-```
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `commit_docs` | `true` | Whether to commit planning artifacts to git |
-| `search_gitignored` | `false` | Add `--no-ignore` to broad rg searches |
-| `git.branching_strategy` | `"none"` | Git branching approach: `"none"`, `"phase"`, or `"milestone"` |
-| `git.phase_branch_template` | `"ariadna/phase-{phase}-{slug}"` | Branch template for phase strategy |
-| `git.milestone_branch_template` | `"ariadna/{milestone}-{slug}"` | Branch template for milestone strategy |
-</config_schema>
-
-<commit_docs_behavior>
-
-**When `commit_docs: true` (default):**
-- Planning files committed normally
-- SUMMARY.md, STATE.md, ROADMAP.md tracked in git
-- Full history of planning decisions preserved
-
-**When `commit_docs: false`:**
-- Skip all `git add`/`git commit` for `.ariadna_planning/` files
-- User must add `.ariadna_planning/` to `.gitignore`
-- Useful for: OSS contributions, client projects, keeping planning private
-
-**Using ariadna-tools (preferred):**
-
-```bash
-# Commit with automatic commit_docs + gitignore checks:
-ariadna-tools commit "docs: update state" --files .ariadna_planning/STATE.md
-
-# Load config via state load (returns JSON):
-INIT=$(ariadna-tools state load)
-# commit_docs is available in the JSON output
-
-# Or use init commands which include commit_docs:
-INIT=$(ariadna-tools init execute-phase "1")
-# commit_docs is included in all init command outputs
-```
-
-**Auto-detection:** If `.ariadna_planning/` is gitignored, `commit_docs` is automatically `false` regardless of config.json. This prevents git errors when users have `.ariadna_planning/` in `.gitignore`.
-
-**Commit via CLI (handles checks automatically):**
-
-```bash
-ariadna-tools commit "docs: update state" --files .ariadna_planning/STATE.md
-```
-
-The CLI checks `commit_docs` config and gitignore status internally — no manual conditionals needed.
-
-</commit_docs_behavior>
-
-<search_behavior>
-
-**When `search_gitignored: false` (default):**
-- Standard rg behavior (respects .gitignore)
-- Direct path searches work: `rg "pattern" .ariadna_planning/` finds files
-- Broad searches skip gitignored: `rg "pattern"` skips `.ariadna_planning/`
-
-**When `search_gitignored: true`:**
-- Add `--no-ignore` to broad rg searches that should include `.ariadna_planning/`
-- Only needed when searching entire repo and expecting `.ariadna_planning/` matches
-
-**Note:** Most Ariadna operations use direct file reads or explicit paths, which work regardless of gitignore status.
-
-</search_behavior>
-
-<setup_uncommitted_mode>
-
-To use uncommitted mode:
-
-1. **Set config:**
-   ```json
-   "planning": {
-     "commit_docs": false,
-     "search_gitignored": true
-   }
-   ```
-
-2. **Add to .gitignore:**
-   ```
-   .ariadna_planning/
-   ```
-
-3. **Existing tracked files:** If `.ariadna_planning/` was previously tracked:
-   ```bash
-   git rm -r --cached .ariadna_planning/
-   git commit -m "chore: stop tracking planning docs"
-   ```
-
-</setup_uncommitted_mode>
-
-<branching_strategy_behavior>
-
-**Branching Strategies:**
-
-| Strategy | When branch created | Branch scope | Merge point |
-|----------|---------------------|--------------|-------------|
-| `none` | Never | N/A | N/A |
-| `phase` | At `execute-phase` start | Single phase | User merges after phase |
-| `milestone` | At first `execute-phase` of milestone | Entire milestone | At `complete-milestone` |
-
-**When `git.branching_strategy: "none"` (default):**
-- All work commits to current branch
-- Standard Ariadna behavior
-
-**When `git.branching_strategy: "phase"`:**
-- `execute-phase` creates/switches to a branch before execution
-- Branch name from `phase_branch_template` (e.g., `ariadna/phase-03-authentication`)
-- All plan commits go to that branch
-- User merges branches manually after phase completion
-- `complete-milestone` offers to merge all phase branches
-
-**When `git.branching_strategy: "milestone"`:**
-- First `execute-phase` of milestone creates the milestone branch
-- Branch name from `milestone_branch_template` (e.g., `ariadna/v1.0-mvp`)
-- All phases in milestone commit to same branch
-- `complete-milestone` offers to merge milestone branch to main
-
-**Template variables:**
-
-| Variable | Available in | Description |
-|----------|--------------|-------------|
-| `{phase}` | phase_branch_template | Zero-padded phase number (e.g., "03") |
-| `{slug}` | Both | Lowercase, hyphenated name |
-| `{milestone}` | milestone_branch_template | Milestone version (e.g., "v1.0") |
-
-**Checking the config:**
-
-Use `init execute-phase` which returns all config as JSON:
-```bash
-INIT=$(ariadna-tools init execute-phase "1")
-# JSON output includes: branching_strategy, phase_branch_template, milestone_branch_template
-```
-
-Or use `state load` for the config values:
-```bash
-INIT=$(ariadna-tools state load)
-# Parse branching_strategy, phase_branch_template, milestone_branch_template from JSON
-```
-
-**Branch creation:**
-
-```bash
-# For phase strategy
-if [ "$BRANCHING_STRATEGY" = "phase" ]; then
-  PHASE_SLUG=$(echo "$PHASE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
-  BRANCH_NAME=$(echo "$PHASE_BRANCH_TEMPLATE" | sed "s/{phase}/$PADDED_PHASE/g" | sed "s/{slug}/$PHASE_SLUG/g")
-  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
-fi
-
-# For milestone strategy
-if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
-  MILESTONE_SLUG=$(echo "$MILESTONE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
-  BRANCH_NAME=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed "s/{milestone}/$MILESTONE_VERSION/g" | sed "s/{slug}/$MILESTONE_SLUG/g")
-  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
-fi
-```
-
-**Merge options at complete-milestone:**
-
-| Option | Git command | Result |
-|--------|-------------|--------|
-| Squash merge (recommended) | `git merge --squash` | Single clean commit per branch |
-| Merge with history | `git merge --no-ff` | Preserves all individual commits |
-| Delete without merging | `git branch -D` | Discard branch work |
-| Keep branches | (none) | Manual handling later |
-
-Squash merge is recommended — keeps main branch history clean while preserving the full development history in the branch (until deleted).
-
-**Use cases:**
-
-| Strategy | Best for |
-|----------|----------|
-| `none` | Solo development, simple projects |
-| `phase` | Code review per phase, granular rollback, team collaboration |
-| `milestone` | Release branches, staging environments, PR per version |
-
-</branching_strategy_behavior>
-
-</planning_config>

data/data/ariadna/references/questioning.md

@@ -1,153 +0,0 @@
-<questioning_guide>
-
-Project initialization is dream extraction, not requirements gathering. You're helping the user discover and articulate what they want to build. This isn't a contract negotiation — it's collaborative thinking.
-
-<philosophy>
-
-**You are a thinking partner, not an interviewer.**
-
-The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
-
-Don't interrogate. Collaborate. Don't follow a script. Follow the thread.
-
-</philosophy>
-
-<the_goal>
-
-By the end of questioning, you need enough clarity to write a PROJECT.md that downstream phases can act on:
-
-- **Research** needs: what domain to research, what the user already knows, what unknowns exist
-- **Requirements** needs: clear enough vision to scope v1 features
-- **Roadmap** needs: clear enough vision to decompose into phases, what "done" looks like
-- **plan-phase** needs: specific requirements to break into tasks, context for implementation choices
-- **execute-phase** needs: success criteria to verify against, the "why" behind requirements
-
-A vague PROJECT.md forces every downstream phase to guess. The cost compounds.
-
-</the_goal>
-
-<how_to_question>
-
-**Start open.** Let them dump their mental model. Don't interrupt with structure.
-
-**Follow energy.** Whatever they emphasized, dig into that. What excited them? What problem sparked this?
-
-**Challenge vagueness.** Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how?
-
-**Make the abstract concrete.** "Walk me through using this." "What does that actually look like?"
-
-**Clarify ambiguity.** "When you say Z, do you mean A or B?" "You mentioned X — tell me more."
-
-**Know when to stop.** When you understand what they want, why they want it, who it's for, and what done looks like — offer to proceed.
-
-</how_to_question>
-
-<question_types>
-
-Use these as inspiration, not a checklist. Pick what's relevant to the thread.
-
-**Motivation — why this exists:**
-- "What prompted this?"
-- "What are you doing today that this replaces?"
-- "What would you do if this existed?"
-
-**Concreteness — what it actually is:**
-- "Walk me through using this"
-- "You said X — what does that actually look like?"
-- "Give me an example"
-
-**Clarification — what they mean:**
-- "When you say Z, do you mean A or B?"
-- "You mentioned X — tell me more about that"
-
-**Success — how you'll know it's working:**
-- "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>
-
-Use AskUserQuestion to help users think by presenting concrete options to react to.
-
-**Good options:**
-- Interpretations of what they might mean
-- Specific examples to confirm or deny
-- Concrete choices that reveal priorities
-
-**Bad options:**
-- Generic categories ("Technical", "Business", "Other")
-- Leading options that presume an answer
-- Too many options (2-4 is ideal)
-
-**Example — vague answer:**
-User says "it should be fast"
-
-- header: "Fast"
-- question: "Fast how?"
-- options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]
-
-**Example — following a thread:**
-User mentions "frustrated with current tools"
-
-- header: "Frustration"
-- question: "What specifically frustrates you?"
-- options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]
-
-</using_askuserquestion>
-
-<context_checklist>
-
-Use this as a **background checklist**, not a conversation structure. Check these mentally as you go. If gaps remain, weave questions naturally.
-
-- [ ] 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 (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?)
-
-Six things. If they volunteer more, capture it.
-
-</context_checklist>
-
-<decision_gate>
-
-When you could write a clear PROJECT.md, offer to proceed:
-
-- header: "Ready?"
-- question: "I think I understand what you're after. Ready to create PROJECT.md?"
-- options:
-  - "Create PROJECT.md" — Let's move forward
-  - "Keep exploring" — I want to share more / ask me more
-
-If "Keep exploring" — ask what they want to add or identify gaps and probe naturally.
-
-Loop until "Create PROJECT.md" selected.
-
-</decision_gate>
-
-<anti_patterns>
-
-- **Checklist walking** — Going through domains regardless of what they said
-- **Canned questions** — "What's your core value?" "What's out of scope?" regardless of context
-- **Corporate speak** — "What are your success criteria?" "Who are your stakeholders?"
-- **Interrogation** — Firing questions without building on answers
-- **Rushing** — Minimizing questions to get to "the work"
-- **Shallow acceptance** — Taking vague answers without probing
-- **Premature constraints** — Asking about tech stack before understanding the idea
-- **User skills** — NEVER ask about user's technical experience. Claude builds.
-
-</anti_patterns>
-
-</questioning_guide>