Ariadna

A meta-prompting and context engineering system for building Ruby on Rails applications with Claude Code.

Ariadna turns Claude Code into a disciplined Rails project execution engine that plans before it builds, verifies after it ships, and tracks state across sessions. It provides structured planning, multi-agent orchestration, and verification workflows via slash commands. Specialized executor agents handle backend, frontend, and testing domains with Rails-specific guides and conventions baked in.

A system of prompts, agents, and workflows that make Claude Code work like a disciplined Rails engineering team.

This is not a vibe-coding tool. You will get the best results when you review both the created plans and the outcomes of each phase.

Without Ariadna, Claude Code sessions are stateless. There's no memory between sessions, no structure to large projects, no verification that what was built matches what was planned, and no way to coordinate parallel work streams.

With Ariadna, you get:

• Persistent memory — STATE.md tracks decisions, progress, and blockers across sessions
• Structured planning — roadmaps, phases, and plans with dependency-aware execution
• Parallel agents — wave-based execution spawns multiple agents working simultaneously
• Rails-aware executors — backend, frontend, and test agents load Rails-specific guides and conventions
• Verification — automated goal checking plus conversational UAT after every phase
• Session continuity — pause mid-phase, resume later with full context restoration

1. You invoke a slash command (e.g., /ariadna:execute-phase 1)
2. The command loads a workflow definition and gathers context via ariadna-tools
3. An orchestrator spawns specialised agents (planner, executor, verifier) in parallel, routing to Rails-specific executors based on plan metadata
4. Agents execute tasks, make atomic commits, and produce summaries
5. Project state is updated in .ariadna_planning/STATE.md

gem install ariadna

Install commands and agents globally (recommended):

ariadna install --global    # Installs to ~/.claude/ — available in all projects

Or locally for a single project:

ariadna install --local     # Installs to ./.claude/ — project-specific

/ariadna:new-project           # Define vision, set preferences, create roadmap
/clear
/ariadna:plan-phase 1          # Create detailed plan for first phase
/clear
/ariadna:execute-phase 1       # Execute it with parallel agents
/ariadna:verify-work 1         # Conversational UAT

Use /clear between commands to give each orchestrator a fresh context window. Each command loads only the context it needs.

/ariadna:map-codebase          # Analyse codebase → .ariadna_planning/codebase/
/clear
/ariadna:new-project           # Define vision using codebase analysis
/clear
/ariadna:plan-phase 1          # Plan first phase
/clear
/ariadna:execute-phase 1       # Execute

For adding features to an existing project without a full roadmap, use /ariadna:new-milestone instead of /ariadna:new-project.

Every phase follows the same three-step cycle:

Plan (/ariadna:plan-phase N) — gathers context inline, then spawns a planner and plan-checker. The planner creates PLAN.md files using pre-loaded Rails conventions, and the plan-checker validates the plan against the phase goal. Use --research to force ecosystem research for non-standard domains. Output: one or more PLAN.md files in .ariadna_planning/phases/.

Execute (/ariadna:execute-phase N) — groups plans into waves based on dependency numbering. Plans in the same wave run in parallel via separate executor agents. Each agent reads its plan, executes tasks with atomic commits, and writes a SUMMARY.md. The orchestrator spot-checks results between waves.

Verify (/ariadna:verify-work N) — conversational UAT session. The verifier checks whether the phase goal was achieved (not just whether tasks were completed). If gaps are found, it creates a verification report and you can run /ariadna:plan-phase N --gaps to close them.

/ariadna:plan-phase now gathers context inline — it assesses whether the phase needs discussion and offers a quick in-line option. For most Rails phases, you can go straight to planning.

For complex phases involving unfamiliar libraries or non-standard domains, prepare before planning:

/ariadna:discuss-phase N              # Capture your vision and decisions → CONTEXT.md
/clear
/ariadna:research-phase N             # Deep ecosystem research → RESEARCH.md
/clear
/ariadna:list-phase-assumptions N     # See Claude's intended approach before committing
/clear
/ariadna:plan-phase N                 # Plan with full context

Use --research with /ariadna:plan-phase to force research for phases involving unfamiliar gems, external APIs, or non-standard patterns. Standard Rails work (models, controllers, auth, jobs, mailers, Turbo) uses pre-loaded conventions and doesn't need research.

/ariadna:pause-work        # Creates .continue-here.md handoff document
/ariadna:resume-work       # Restores context and routes to next action
/ariadna:progress          # Status overview with next-action routing

Pause before hitting context limits. The handoff document captures current position, completed work, and what's next so the new session starts informed.

/ariadna:quick             # Same guarantees, skips optional agents

For small, ad-hoc tasks that don't warrant a full phase cycle. Quick tasks live in .ariadna_planning/quick/, get atomic commits, and update STATE.md — but skip the roadmap and don't create phase directories.

Milestones represent major release boundaries (v1.0, v2.0). The full lifecycle:

# After completing all phases in a milestone:
/ariadna:audit-milestone           # Check completion against original intent
/ariadna:plan-milestone-gaps       # Create phases to close any audit gaps
# Execute gap phases...
/ariadna:complete-milestone v1.0   # Archive milestone and tag release
/ariadna:new-milestone v2.0        # Start next milestone

Roadmap manipulation commands:

• /ariadna:add-phase — append a phase to the current milestone
• /ariadna:insert-phase — insert urgent work as a decimal phase (e.g., 3.1)
• /ariadna:remove-phase — remove a future phase and renumber

/ariadna:debug [description]    # Systematic debugging with persistent state

Uses the scientific method: observe, hypothesise, test, conclude. Debug state persists in .ariadna_planning/debug/ and survives /clear, so you can continue across sessions.

Project → Milestones → Phases → Plans → Tasks

• Project — the thing you're building
• Milestones — major release boundaries (v1.0, v2.0)
• Phases — logical chunks of work within a milestone
• Plans — concrete execution steps within a phase, with wave-based parallelism
• Tasks — individual items within a plan

Plans use wave-based numbering (e.g., 01-01, 01-02) to express parallelism. Plans sharing a wave number execute in parallel; higher waves wait for lower waves to complete.

Lightweight coordinators that spawn specialised agents. They stay lean (~10-15% context usage), passing file paths to subagents rather than content. Each subagent gets a fresh 200k context window.

Plans include a domain field in their frontmatter. The execute-phase orchestrator routes each plan to the appropriate Rails-aware executor:

Each specialised executor loads its domain guide automatically, applying domain-specific patterns and best practices.

Guides encode Rails patterns, conventions, and best practices that executors follow during plan execution. Read below how to customise them for your project.

Executors load the relevant guide automatically based on plan domain. The security and performance guides are also used during verification.

Guides are installed to ~/.claude/guides/ (global) or .claude/guides/ (local). Edit them to match your project's conventions. After updating Ariadna, use /ariadna:reapply-patches to restore your customisations.

.ariadna_planning/
├── PROJECT.md                # Project vision and requirements
├── ROADMAP.md                # Phase breakdown with status
├── STATE.md                  # Project memory across sessions
├── REQUIREMENTS.md           # Detailed requirements
├── CONTEXT.md                # Phase discussion decisions
├── config.json               # Workflow mode and agent toggles
├── quick/                    # Quick task plans and summaries
├── todos/
│   ├── pending/
│   └── done/
├── debug/
│   └── resolved/
├── research/                 # Project-level research outputs
├── codebase/                 # Brownfield project analysis
│   ├── STACK.md              # Languages, frameworks, dependencies
│   ├── INTEGRATIONS.md       # External APIs, databases, auth
│   ├── ARCHITECTURE.md       # Patterns, layers, data flow
│   ├── STRUCTURE.md          # Directory layout, key locations
│   ├── CONVENTIONS.md        # Code style, naming, patterns
│   ├── TESTING.md            # Test framework, structure, coverage
│   └── CONCERNS.md           # Tech debt, security, performance
└── phases/
    ├── 01-foundation/
    │   ├── RESEARCH.md
    │   ├── 01-01-PLAN.md
    │   └── 01-01-SUMMARY.md
    └── 02-core-features/
        ├── 02-01-PLAN.md
        └── 02-01-SUMMARY.md

Control which Claude models agents use via /ariadna:set-profile:

Configure via /ariadna:settings:

Per-command overrides: --research, --skip-research, --skip-context, --skip-verify.

Configure via /ariadna:settings or directly in .ariadna_planning/config.json.

/ariadna:update              # Shows changelog, confirms before installing

Local modifications to guides and templates are backed up automatically during updates. After updating, use /ariadna:reapply-patches to restore your customisations.

Ariadna is configured to generate Ruby on Rails applications following the Rails philosophy and conventions. We believe in the Rails is plenty approach — vanilla Rails with minimal dependencies.

This project has taken inspiration from Fizzy and Once Campfire, both great resources for Ruby on Rails best practices. Remember that you can customise Ariadna by editing the guides installed at ~/.claude/guides/.

• Ruby >= 3.1.0
• Claude Code

• Mario Alvarez
• Jorge Alvarez

• GSD for inspiring the project and providing a solid foundation to build upon.
• 37 Signals we stand on the shoulders of giants.
• The Ruby on Rails community.
• Matz and the Ruby team for creating such a wonderful language.

MIT