ariadna 1.3.0 → 2.0.0

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

@@ -1,251 +0,0 @@
-# Stack Research Template
-
-Template for `.ariadna_planning/research/STACK.md` — discovered technology stack for the Rails project.
-
-<template>
-
-```markdown
-# Stack Research
-
-**Project:** [project name]
-**Researched:** [date]
-**Confidence:** [HIGH/MEDIUM/LOW]
-
-## Core Platform
-
-| Component | Discovered Value | Source |
-|-----------|-----------------|--------|
-| Ruby version | [version from .ruby-version or Gemfile] | [where found] |
-| Rails version | [version from Gemfile.lock] | [where found] |
-| Database | [SQLite/PostgreSQL/MySQL] | [config/database.yml] |
-| Ruby version manager | [rbenv/asdf/chruby/rvm/none] | [where found] |
-
-## Application Type
-
-| Aspect | Discovered Value | Evidence |
-|--------|-----------------|----------|
-| API-only or full-stack | [rails new --api or full] | [ApplicationController inherits from API or Base] |
-| Monolith or engines | [single app / modular engines] | [presence of engines/ or components/] |
-| Multi-database | [yes/no] | [database.yml configuration] |
-| Multi-tenancy | [none/schema-based/row-based] | [tenant isolation approach if any] |
-
-## Frontend & Assets
-
-| Category | Discovered Value | Evidence |
-|----------|-----------------|----------|
-| JS approach | [Importmap/esbuild/Vite/Webpacker/Shakapacker/none] | [config files, Gemfile] |
-| CSS approach | [Custom CSS/Tailwind/Bootstrap/none] | [app/assets/stylesheets/, Gemfile] |
-| Real-time | [Turbo Streams/Action Cable/AnyCable/none] | [Gemfile, channel files] |
-| Hotwire/Turbo | [yes/no, version] | [Gemfile, stimulus controllers] |
-| Stimulus | [yes/no, version] | [controllers directory, importmap pins] |
-| View layer | [ERB/Haml/Slim/ViewComponent/Phlex] | [app/views file extensions, Gemfile] |
-
-## Backend Services
-
-| Category | Discovered Value | Evidence |
-|----------|-----------------|----------|
-| Background jobs | [Solid Queue/Sidekiq/GoodJob/DelayedJob/none] | [Gemfile, config/application.rb] |
-| Caching backend | [Solid Cache/Redis/Memcached/file store] | [config/environments/, Gemfile] |
-| Action Cable adapter | [Solid Cable/Redis/async/none] | [config/cable.yml] |
-| Search | [pg_search/Elasticsearch/Meilisearch/none] | [Gemfile, model concerns] |
-| File storage | [Active Storage/Shrine/CarrierWave/none] | [Gemfile, storage.yml] |
-| File storage service | [local/S3/GCS/Azure/none] | [config/storage.yml] |
-| Email | [Action Mailer/Postmark/SendGrid/none] | [Gemfile, mailer configs] |
-| PDF generation | [Prawn/wicked_pdf/Grover/none] | [Gemfile] |
-| Internationalization | [rails-i18n gem / manual locale files only / none] | [Gemfile, config/locales/] |
-
-## Authentication & Authorization
-
-| Category | Discovered Value | Evidence |
-|----------|-----------------|----------|
-| Authentication | [Rails authentication generator/Rodauth/Clearance/custom/none] | [Gemfile, user model] |
-| 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] |
-
-## Testing
-
-| Category | Discovered Value | Evidence |
-|----------|-----------------|----------|
-| Test framework | [Minitest (recommended)/RSpec] | [test/ or spec/ directory, Gemfile] |
-| Fixtures or factories | [fixtures/FactoryBot/Fabrication] | [test/fixtures or spec/factories] |
-| System tests | [Capybara driver: Selenium/Cuprite/Playwright] | [Gemfile, test_helper or rails_helper] |
-| Code coverage | [SimpleCov/none] | [Gemfile, test_helper] |
-| Linting | [RuboCop/Standard/none] | [Gemfile, .rubocop.yml] |
-| Static analysis | [Brakeman/Bundler Audit/none] | [Gemfile, CI config] |
-
-## Infrastructure & Deployment
-
-| Category | Discovered Value | Evidence |
-|----------|-----------------|----------|
-| Deployment | [Kamal/Capistrano/Heroku/Render/Fly.io/Docker/other] | [deploy configs, Dockerfile] |
-| CI/CD | [GitHub Actions/CircleCI/GitLab CI/none] | [.github/workflows, .circleci] |
-| Containerized | [yes/no] | [Dockerfile, docker-compose.yml] |
-| Process manager | [Foreman/Overmind/Puma only] | [Procfile, Procfile.dev] |
-| Credentials management | [Rails credentials/dotenv/Figaro] | [config/credentials, .env files] |
-
-## Gem Inventory
-
-### Core Gems (from Gemfile)
-
-| Gem | Version Constraint | Group | Purpose |
-|-----|-------------------|-------|---------|
-| [gem name] | [~> X.Y] | [default/development/test/production] | [what it does in this project] |
-| [gem name] | [~> X.Y] | [default/development/test/production] | [what it does in this project] |
-| [gem name] | [~> X.Y] | [default/development/test/production] | [what it does in this project] |
-
-### Development & Debugging Gems
-
-| Gem | Purpose | Notes |
-|-----|---------|-------|
-| [gem name] | [what it does] | [configuration if relevant] |
-| [gem name] | [what it does] | [configuration if relevant] |
-
-## Project Setup
-
-```bash
-# System dependencies
-[discovered system deps: e.g., libvips for image processing — note: SQLite requires no external service; add postgresql only if project uses PostgreSQL]
-
-# Ruby setup
-[ruby version manager install command if applicable]
-
-# Application setup
-bundle install
-bin/rails db:prepare
-
-# Asset pipeline (if applicable)
-[bin/rails assets:precompile / yarn build / none]
-
-# Background jobs (if applicable)
-[bin/jobs (Solid Queue) / bundle exec sidekiq / none]
-
-# Development server
-bin/dev
-# or
-bin/rails server
-```
-
-## Alternatives Considered
-
-| In Use | Alternative | When to Consider Switching |
-|--------|-------------|---------------------------|
-| [current choice] | [other option] | [conditions where alternative fits better] |
-| [current choice] | [other option] | [conditions where alternative fits better] |
-
-## What to Avoid
-
-| Avoid | Why | Use Instead |
-|-------|-----|-------------|
-| [gem or pattern] | [specific problem: deprecated, unmaintained, security issue, incompatible] | [recommended alternative] |
-| [gem or pattern] | [specific problem] | [recommended alternative] |
-
-## Rails Variant Decisions
-
-**If API-only app:**
-- [relevant architectural notes]
-- [serialization approach: jbuilder/Alba/Blueprinter/none]
-- [API versioning strategy if any]
-
-**If full-stack with Hotwire:**
-- [Turbo Frame vs Turbo Stream usage patterns]
-- [Stimulus controller conventions]
-- [Broadcasting patterns if any]
-
-**If full-stack with SPA frontend:**
-- [Frontend framework: React/Vue/Svelte]
-- [API layer: GraphQL/REST/Inertia.js]
-- [CORS and authentication approach]
-
-**If modular monolith with engines:**
-- [Engine boundaries and responsibilities]
-- [Shared dependencies across engines]
-- [Inter-engine communication patterns]
-
-## Version Compatibility
-
-| Gem | Compatible With | Notes |
-|-----|-----------------|-------|
-| [gem @ version] | [Rails version / Ruby version] | [compatibility notes] |
-| [gem @ version] | [other gem @ version] | [known constraints] |
-
-## Configuration Files Discovered
-
-| File | Purpose | Notable Settings |
-|------|---------|-----------------|
-| [config file path] | [what it configures] | [any non-default values worth noting] |
-| [config file path] | [what it configures] | [any non-default values worth noting] |
-
-## Sources
-
-- [Gemfile and Gemfile.lock] — [primary source of gem versions]
-- [config/ directory] — [Rails configuration files]
-- [Official docs URL] — [what was verified]
-- [Other source] — [confidence level]
-
----
-*Stack research for: [project name]*
-*Researched: [date]*
-```
-
-</template>
-
-<guidelines>
-
-**Discovery, Not Prescription:**
-- This template is for discovering what the project ACTUALLY uses
-- Fill in values by inspecting `Gemfile`, `Gemfile.lock`, `config/`, and project structure
-- Do not assume or recommend — report what is found
-- If a category has nothing discovered, mark it `[none found]` rather than suggesting additions
-
-**Core Platform:**
-- Always check `.ruby-version`, `Gemfile`, and `Gemfile.lock` for exact versions
-- Check `config/database.yml` for the actual database adapter in use
-- Check `config/application.rb` and environment files for framework defaults
-
-**Application Type:**
-- Determine if `ApplicationController` inherits from `ActionController::API` or `ActionController::Base`
-- Look for `config.api_only = true` in `config/application.rb`
-- Check for presence of `engines/`, `components/`, or `packages/` directories
-- Look at `database.yml` for multiple database configurations
-
-**Frontend & Assets:**
-- Check for `config/importmap.rb` (Importmap), `package.json` (Node-based), or `vite.config.ts` (Vite).
-- Look at `app/views/layouts/application.html.erb` for asset tags.
-- Check `app/javascript/` structure and `app/assets/` for CSS approach.
-- Look for `app/components/` (ViewComponent) or Phlex usage.
-
-**Backend Services:**
-- Check `config/application.rb` for `active_job.queue_adapter` setting.
-- Check `config/environments/production.rb` for cache store configuration.
-- Look at `config/cable.yml` for Action Cable adapter.
-- Check `config/storage.yml` for Active Storage service.
-
-**Authentication & Authorization:**
-- Look for `Authentication` concern generated by `rails generate authentication`.
-- 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:**
-- Determine framework: check for `test/` (Minitest, recommended) vs `spec/` (RSpec)
-- Check `test/test_helper.rb` (Minitest) or `spec/rails_helper.rb` (if RSpec) for test configuration.
-- Look for `test/fixtures/` or `spec/factories/` to determine data strategy.
-- Check for system test configuration and browser driver.
-
-**What to Avoid:**
-- Flag gems that are no longer maintained or have known security issues.
-- Note deprecated Rails patterns found in the codebase (e.g., `before_filter`, `attr_accessible`).
-- Identify gems that duplicate Rails built-in functionality unnecessarily.
-- Flag any gems with known incompatibilities with the discovered Rails version.
-
-**Gem Inventory:**
-- Record version constraints as written in the Gemfile, not resolved versions.
-- Note which Bundler group each gem belongs to.
-- For important gems, check if the version is current or significantly outdated.
-
-**Version Compatibility:**
-- Note any gems that pin to specific Rails or Ruby versions
-- Flag if the Ruby version is approaching end-of-life
-- Check if major gem upgrades are available that would require migration work
-
-</guidelines>

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

@@ -1,247 +0,0 @@
-# Research Summary Template
-
-Template for `.ariadna_planning/research/SUMMARY.md` — executive summary of project research with roadmap implications for Ruby on Rails applications.
-
-<template>
-
-```markdown
-# Project Research Summary
-
-**Project:** [name from PROJECT.md]
-**Domain:** [inferred domain type] — Ruby on Rails application
-**Researched:** [date]
-**Confidence:** [HIGH/MEDIUM/LOW]
-
-## Executive Summary
-
-[2-3 paragraph overview of research findings]
-
-- What type of Rails application this is and how experienced Rails teams build it
-- The recommended approach based on research (conventions, gems, architectural patterns)
-- Key risks specific to this kind of Rails project and how to mitigate them
-
-## Key Findings
-
-### Recommended Stack
-
-[Summary from STACK.md — 1-2 paragraphs on why this combination of Rails technologies fits the project]
-
-**Ruby & Rails version:**
-- [Ruby version]: [why this version — e.g., YJIT support, performance, compatibility]
-- [Rails version]: [why this version — e.g., latest stable, Solid Queue/Cache built-in, Turbo maturity]
-
-**Database:**
-- [Database]: [purpose] — [why recommended — e.g., SQLite for zero-setup default (Rails ships with it); PostgreSQL when needing full-text search, jsonb, advisory locks, or high-concurrency production]
-
-**Background jobs:**
-- [Job backend]: [purpose] — [why recommended — e.g., Solid Queue for zero-dependency simplicity (Rails 8 default), Sidekiq for extreme throughput needs]
-
-**Caching & key-value:**
-- [Cache backend]: [purpose] — [why recommended — e.g., Solid Cache for DB-backed caching with no external dependencies (Rails 8 default), Redis for shared cross-process state]
-
-**Real-time:**
-- [Approach]: [purpose] — [why recommended — e.g., Turbo Streams over WebSocket, Action Cable for custom channels]
-
-**Frontend approach:**
-- [Frontend stack]: [purpose] — [why recommended — e.g., Hotwire/Turbo + Stimulus for server-rendered, React/Inertia for SPA-like]
-- [CSS approach]: [purpose] — [why recommended — e.g., custom CSS with CSS layers and custom properties (Rails default), Tailwind CSS if already in use]
-- [Asset pipeline]: [purpose] — [why recommended — e.g., Propshaft + importmap, esbuild for bundling]
-
-**Testing framework:**
-- [Test framework]: [purpose] — [why recommended — e.g., Minitest (recommended, Rails default, no extra dependencies), RSpec if team prefers]
-- [Additional test tools]: [purpose] — [e.g., Capybara for system tests, FactoryBot for fixtures]
-
-**Authentication & authorization:**
-- [Auth solution]: [purpose] — [why recommended — e.g., Rails authentication generator for session-based auth]
-- [Authorization]: [purpose] — [why recommended — e.g., before_action + Current context (default), Pundit only if explicitly requested]
-
-**Additional gems:**
-- [Gem]: [purpose] — [why recommended]
-- [Gem]: [purpose] — [why recommended]
-
-### Expected Features
-
-[Summary from FEATURES.md]
-
-**Must have (table stakes):**
-- [Feature] — users expect this
-- [Feature] — users expect this
-
-**Should have (competitive):**
-- [Feature] — differentiator
-- [Feature] — differentiator
-
-**Defer (v2+):**
-- [Feature] — not essential for launch
-
-### Architecture Approach
-
-[Summary from ARCHITECTURE.md — 1 paragraph covering the Rails MVC structure, domain model organization, and any patterns beyond vanilla Rails]
-
-**Application structure:**
-1. [Models & domain layer] — [approach — e.g., core models, concerns for shared behavior, STI vs. polymorphism decisions, value objects]
-2. [Controllers & routing] — [approach — e.g., RESTful resources, namespace organization, API vs. HTML responses]
-3. [Views & UI layer] — [approach — e.g., partials, ViewComponents, Turbo Frames for partial page updates]
-4. [Service layer] — [approach — e.g., service objects/interactors for complex operations, form objects for multi-model forms]
-5. [Background layer] — [approach — e.g., Active Job with queue backend, mailers, recurring tasks]
-6. [Data access patterns] — [approach — e.g., scopes, query objects, eager loading strategy]
-
-**Multi-tenancy approach (if applicable):**
-- [Strategy] — [e.g., Denormalise tables with account_id and use Current.account, PostgreSQL schemas, separate databases]
-
-**Engine extraction (if applicable):**
-- [Engine/mountable concern] — [e.g., admin engine, API engine, shared authentication engine]
-
-### Critical Pitfalls
-
-[Top 5-7 from PITFALLS.md — Rails-specific risks identified through research]
-
-1. **[N+1 query risk]** — [where it applies and how to avoid — e.g., strict_loading, bullet gem, includes/preload strategy]
-2. **[Migration safety]** — [how to avoid — e.g., strong_migrations gem, zero-downtime deployment considerations, backfill strategies]
-3. **[Callback complexity]** — [how to avoid — e.g., limit callback chains, prefer explicit service objects for side effects]
-4. **[Fat model/controller risk]** — [how to avoid — e.g., extract concerns, service objects, form objects early]
-5. **[Turbo/Hotwire integration pitfall]** — [how to avoid — e.g., Turbo Frame vs. Stream decisions, morphing gotchas, progressive enhancement]
-6. **[Asset pipeline / frontend build issue]** — [how to avoid — e.g., importmap limitations, JavaScript bundler configuration]
-7. **[Testing bottleneck]** — [how to avoid — e.g., slow system tests, fixture vs. factory strategy, parallel test execution]
-
-## Implications for Roadmap
-
-Based on research, suggested phase structure for this Rails application:
-
-### Phase 1: Foundation — Data Model, Authentication & Core Models
-**Rationale:** [why this comes first — e.g., Rails apps are built on a solid data model; authentication gates all other features; core models define the domain language]
-**Delivers:** [what this phase produces — e.g., migrations, core models with validations and associations, authentication flow, basic authorization, seed data, model-level tests]
-**Addresses:** [features from FEATURES.md — e.g., user registration, core domain entities]
-**Avoids:** [pitfall from PITFALLS.md — e.g., migration rework by designing schema upfront, N+1 prevention with eager loading strategy from day one]
-**Stack elements:** [from STACK.md — e.g., Rails generators, SQLite (or PostgreSQL), chosen auth gem, model concerns]
-
-### Phase 2: Core Features — Controllers, Views & Turbo Interactions
-**Rationale:** [why this order — e.g., with models stable, build the user-facing CRUD and interactions; Turbo Frames/Streams add interactivity without JavaScript complexity]
-**Delivers:** [what this phase produces — e.g., RESTful controllers, views with partials/components, Turbo Frame navigation, form handling, flash messages, system tests]
-**Addresses:** [features from FEATURES.md — e.g., primary user workflows, admin interface]
-**Uses:** [stack elements from STACK.md — e.g., Hotwire/Turbo, Stimulus, CSS framework, ViewComponents]
-**Implements:** [architecture component — e.g., controller layer, view layer, service objects for complex actions]
-
-### Phase 3: Background Processing — Jobs, Mailers & Scheduled Tasks
-**Rationale:** [why this order — e.g., core features surface the need for async work; emails, notifications, data processing should not block web requests]
-**Delivers:** [what this phase produces — e.g., Active Job classes, mailer templates, recurring job schedule, webhook processing, error handling/retry strategy]
-**Addresses:** [features from FEATURES.md — e.g., email notifications, data imports/exports, scheduled reports]
-**Uses:** [stack elements from STACK.md — e.g., Solid Queue, Action Mailer, Active Storage for file processing]
-**Avoids:** [pitfall from PITFALLS.md — e.g., long-running requests, timeout issues, job idempotency problems]
-
-### Phase 4: Polish — Caching, Performance, Search & Real-Time
-**Rationale:** [why this order — e.g., optimize after features are stable; caching and real-time add complexity best deferred until core is solid]
-**Delivers:** [what this phase produces — e.g., fragment caching, Russian doll caching, counter caches, database indexes, full-text search, Action Cable channels, Turbo Stream broadcasts, performance monitoring]
-**Addresses:** [features from FEATURES.md — e.g., search, live updates, dashboard performance]
-**Uses:** [stack elements from STACK.md — e.g., Solid Cache, pg_search/Meilisearch, Solid Cable for Action Cable]
-**Avoids:** [pitfall from PITFALLS.md — e.g., premature optimization, cache invalidation bugs, N+1 regressions under load]
-
-[Continue for additional phases if needed...]
-
-### Phase Ordering Rationale
-
-- [Why data model and auth come first — e.g., Rails convention-over-configuration rewards upfront schema design; all features depend on authentication]
-- [Why controllers/views before background jobs — e.g., user-facing flows reveal the async work needed; avoids building jobs for features that change]
-- [Why caching and real-time are last — e.g., caching strategies depend on stable views and queries; premature caching causes invalidation bugs]
-- [How this avoids pitfalls from research — e.g., early attention to eager loading prevents N+1 debt; strong_migrations from phase 1 prevents deployment issues]
-
-### Research Flags
-
-Phases likely needing deeper research during planning:
-- **Phase [X]:** [reason — e.g., "multi-tenancy approach needs benchmarking against data volume projections"]
-- **Phase [Y]:** [reason — e.g., "Turbo Stream vs. Action Cable decision depends on real-time requirements complexity"]
-- **Phase [Z]:** [reason — e.g., "search gem selection depends on hosting constraints and query patterns"]
-
-Phases with standard Rails patterns (skip research-phase):
-- **Phase [X]:** [reason — e.g., "standard RESTful CRUD, well-documented Rails conventions"]
-- **Phase [Y]:** [reason — e.g., "Active Job + mailers follow established Rails patterns"]
-
-## Confidence Assessment
-
-| Area | Confidence | Notes |
-|------|------------|-------|
-| Stack | [HIGH/MEDIUM/LOW] | [reason — e.g., "well-established Rails gems with strong community support"] |
-| Features | [HIGH/MEDIUM/LOW] | [reason — e.g., "domain-specific features need validation with stakeholders"] |
-| Architecture | [HIGH/MEDIUM/LOW] | [reason — e.g., "standard Rails MVC, but multi-tenancy approach needs validation"] |
-| Pitfalls | [HIGH/MEDIUM/LOW] | [reason — e.g., "common Rails pitfalls well-documented, project-specific risks less certain"] |
-
-**Overall confidence:** [HIGH/MEDIUM/LOW]
-
-### Gaps to Address
-
-[Any areas where research was inconclusive or needs validation during implementation]
-
-- [Gap]: [how to handle during planning/execution — e.g., "hosting environment unknown, affects cache backend and job queue selection"]
-- [Gap]: [how to handle during planning/execution — e.g., "expected data volume unclear, affects database indexing and pagination strategy"]
-- [Gap]: [how to handle during planning/execution — e.g., "third-party API integration details pending, affects service object design"]
-
-## Sources
-
-### Primary (HIGH confidence)
-- [Rails Guides / API docs] — [topics covered]
-- [Context7 library ID] — [topics]
-- [Official gem documentation] — [what was checked]
-
-### Secondary (MEDIUM confidence)
-- [Community blog / conference talk] — [finding]
-- [Source] — [finding]
-
-### Tertiary (LOW confidence)
-- [Source] — [finding, needs validation]
-
----
-*Research completed: [date]*
-*Ready for roadmap: yes*
-```
-
-</template>
-
-<guidelines>
-
-**Executive Summary:**
-- Write for someone who will only read this section
-- Include the key Rails architectural recommendation and main risk
-- Reference the Rails conventions that apply and where the project diverges from convention
-- 2-3 paragraphs maximum
-
-**Key Findings:**
-- Summarize, don't duplicate full documents
-- Link to detailed docs (STACK.md, FEATURES.md, etc.)
-- Focus on what matters for roadmap decisions
-- For the stack section, emphasize Rails-native solutions first (Solid Queue, Solid Cache, built-in authentication) before third-party alternatives
-- Note where the project follows Rails conventions and where it needs custom patterns
-
-**Architecture Approach:**
-- Start from Rails MVC conventions and note deviations
-- Be explicit about concern organization and service object boundaries
-- Address data access patterns — eager loading, scopes, query objects
-- Note multi-tenancy and engine extraction only if applicable
-
-**Critical Pitfalls:**
-- Prioritize Rails-specific pitfalls: N+1 queries, migration safety, callback chains, fat models
-- Include Turbo/Hotwire integration gotchas if the frontend uses Hotwire
-- Note deployment-specific risks (zero-downtime migrations, asset compilation)
-- Reference specific gems that mitigate pitfalls (bullet, strong_migrations, strict_loading)
-
-**Implications for Roadmap:**
-- This is the most important section
-- Directly informs roadmap creation
-- Follow the Rails-typical build order: data model first, then controllers/views, then async, then optimization
-- Be explicit about phase suggestions and rationale
-- Include research flags for each suggested phase
-- Note where phases can leverage Rails generators and conventions to move faster
-
-**Confidence Assessment:**
-- Be honest about uncertainty
-- Note gaps that need resolution during planning
-- HIGH = verified with official Rails guides or gem documentation
-- MEDIUM = community consensus, multiple sources agree, established patterns
-- LOW = single source, inference, or project-specific assumption
-
-**Integration with roadmap creation:**
-- This file is loaded as context during roadmap creation
-- Phase suggestions here become starting point for roadmap
-- Research flags inform phase planning
-- Rails convention alignment should be noted to speed up estimation
-
-</guidelines>

data/data/ariadna/templates/state.md

@@ -1,176 +0,0 @@
-# State Template
-
-Template for `.ariadna_planning/STATE.md` — the project's living memory.
-
----
-
-## File Template
-
-```markdown
-# Project State
-
-## Project Reference
-
-See: .ariadna_planning/PROJECT.md (updated [date])
-
-**Core value:** [One-liner from PROJECT.md Core Value section]
-**Current focus:** [Current phase name]
-
-## Current Position
-
-Phase: [X] of [Y] ([Phase name])
-Plan: [A] of [B] in current phase
-Status: [Ready to plan / Planning / Ready to execute / In progress / Phase complete]
-Last activity: [YYYY-MM-DD] — [What happened]
-
-Progress: [░░░░░░░░░░] 0%
-
-## Performance Metrics
-
-**Velocity:**
-- Total plans completed: [N]
-- Average duration: [X] min
-- Total execution time: [X.X] hours
-
-**By Phase:**
-
-| Phase | Plans | Total | Avg/Plan |
-|-------|-------|-------|----------|
-| - | - | - | - |
-
-**Recent Trend:**
-- Last 5 plans: [durations]
-- Trend: [Improving / Stable / Degrading]
-
-*Updated after each plan completion*
-
-## Accumulated Context
-
-### Decisions
-
-Decisions are logged in PROJECT.md Key Decisions table.
-Recent decisions affecting current work:
-
-- [Phase X]: [Decision summary]
-- [Phase Y]: [Decision summary]
-
-### Pending Todos
-
-[From .ariadna_planning/todos/pending/ — ideas captured during sessions]
-
-None yet.
-
-### Blockers/Concerns
-
-[Issues that affect future work]
-
-None yet.
-
-## Session Continuity
-
-Last session: [YYYY-MM-DD HH:MM]
-Stopped at: [Description of last completed action]
-Resume file: [Path to .continue-here*.md if exists, otherwise "None"]
-```
-
-<purpose>
-
-STATE.md is the project's short-term memory spanning all phases and sessions.
-
-**Problem it solves:** Information is captured in summaries, issues, and decisions but not systematically consumed. Sessions start without context.
-
-**Solution:** A single, small file that's:
-- Read first in every workflow
-- Updated after every significant action
-- Contains digest of accumulated context
-- Enables instant session restoration
-
-</purpose>
-
-<lifecycle>
-
-**Creation:** After ROADMAP.md is created (during init)
-- Reference PROJECT.md (read it for current context)
-- Initialize empty accumulated context sections
-- Set position to "Phase 1 ready to plan"
-
-**Reading:** First step of every workflow
-- progress: Present status to user
-- plan: Inform planning decisions
-- execute: Know current position
-- transition: Know what's complete
-
-**Writing:** After every significant action
-- execute: After SUMMARY.md created
-  - Update position (phase, plan, status)
-  - Note new decisions (detail in PROJECT.md)
-  - Add blockers/concerns
-- transition: After phase marked complete
-  - Update progress bar
-  - Clear resolved blockers
-  - Refresh Project Reference date
-
-</lifecycle>
-
-<sections>
-
-### Project Reference
-Points to PROJECT.md for full context. Includes:
-- Core value (the ONE thing that matters)
-- Current focus (which phase)
-- Last update date (triggers re-read if stale)
-
-Claude reads PROJECT.md directly for requirements, constraints, and decisions.
-
-### Current Position
-Where we are right now:
-- Phase X of Y — which phase
-- Plan A of B — which plan within phase
-- Status — current state
-- Last activity — what happened most recently
-- Progress bar — visual indicator of overall completion
-
-Progress calculation: (completed plans) / (total plans across all phases) × 100%
-
-### Performance Metrics
-Track velocity to understand execution patterns:
-- Total plans completed
-- Average duration per plan
-- Per-phase breakdown
-- Recent trend (improving/stable/degrading)
-
-Updated after each plan completion.
-
-### Accumulated Context
-
-**Decisions:** Reference to PROJECT.md Key Decisions table, plus recent decisions summary for quick access. Full decision log lives in PROJECT.md.
-
-**Pending Todos:** Ideas captured via /ariadna:add-todo
-- Count of pending todos
-- Reference to .ariadna_planning/todos/pending/
-- Brief list if few, count if many (e.g., "5 pending todos — see /ariadna:check-todos")
-
-**Blockers/Concerns:** From "Next Phase Readiness" sections
-- Issues that affect future work
-- Prefix with originating phase
-- Cleared when addressed
-
-### Session Continuity
-Enables instant resumption:
-- When was last session
-- What was last completed
-- Is there a .continue-here file to resume from
-
-</sections>
-
-<size_constraint>
-
-Keep STATE.md under 100 lines.
-
-It's a DIGEST, not an archive. If accumulated context grows too large:
-- Keep only 3-5 recent decisions in summary (full log in PROJECT.md)
-- Keep only active blockers, remove resolved ones
-
-The goal is "read once, know where we are" — if it's too long, that fails.
-
-</size_constraint>