oneie/one/things/cascade/cascade.yaml

Build apps, websites, and AI agents in English. Zero-interaction setup for AI agents (Claude Code, Cursor, Windsurf). Download to your computer, run in the cloud, deploy to the edge. Open source and free forever.

# ONE Cascade - Agent-Orchestrated Workflow System
# Version: 1.0.0
# Description: Transform ideas into reality using 6-dimension ontology and 8 AI agents

name: ONE Cascade
version: 1.0.0
description: Agent-orchestrated workflow using 6-dimension ontology

# ============================================================================
# THE 6-LEVEL FLOW
# ============================================================================
# Ideas → Plans → Features → Tests → Design → Implementation
#
# Each level adds context, reduces ambiguity, and moves toward working code.
# The ontology is the single source of truth. Agents collaborate via events.
# ============================================================================

stages:
  1_ideas:
    agent: director
    description: "Validate user ideas against ontology"
    output: "validated idea → plan"
    context_tokens: 200
    context_includes:
      - ontology type names
      - validation rules

  2_plans:
    agent: director
    description: "Create plan with feature collection"
    output: "plan with assigned features"
    context_tokens: 1500
    context_includes:
      - relevant ontology types
      - similar patterns
      - team structure

  3_features:
    agent: specialist
    description: "Write feature specifications in parallel"
    output: "feature specs (what, not how)"
    context_tokens: 1500
    parallel: true
    context_includes:
      - ontology types for feature
      - implementation patterns
      - similar features

  4_tests:
    agent: quality
    description: "Define user flows and acceptance criteria"
    output: "user flows + acceptance criteria + technical tests"
    context_tokens: 2000
    context_includes:
      - feature specification
      - ontology validation rules
      - UX patterns
      - test patterns

  5_design:
    agent: design
    description: "Create wireframes that enable tests to pass"
    output: "wireframes + component architecture + design tokens"
    context_tokens: 2000
    context_includes:
      - feature specification
      - test criteria (user flows)
      - design patterns
      - accessibility requirements

  6_implementation:
    agents: [specialist, quality, problem-solver, documenter]
    description: "Build, validate, fix, document"
    output: "working code + passing tests + documentation"
    context_tokens: 2500
    quality_loops: true
    parallel_execution: true
    context_includes:
      - feature specification
      - test criteria
      - design specification
      - implementation patterns
      - lessons learned

# ============================================================================
# AGENT ROLES
# ============================================================================
# 8 specialized agents collaborate to transform ideas into production code
# Each agent has a specific role, responsibilities, and prompt file
# ============================================================================

agents:
  director:
    role: Engineering Director
    description: "Orchestrates workflow, validates ideas, creates plans, assigns work"
    responsibilities:
      - Validate ideas against ontology
      - Create plans and assign features to specialists
      - Review and refine feature specifications
      - Create parallel task lists for implementation
      - Mark features complete after documentation
    prompt_file: one/things/agents/agent-director.md
    context_budget: 200-1500 tokens
    outputs:
      - validated ideas
      - feature assignments
      - task lists
      - completion events

  backend-specialist:
    role: Backend Specialist
    type: specialist
    description: "Services, mutations, queries, schemas"
    responsibilities:
      - Write backend feature specifications
      - Implement Effect.ts services (business logic)
      - Create Convex mutations and queries
      - Update database schemas
      - Fix backend-related problems
      - Add backend lessons learned
    prompt_file: one/things/agents/agent-backend.md
    context_budget: 1500-2500 tokens
    outputs:
      - backend services
      - mutations/queries
      - schema updates

  frontend-specialist:
    role: Frontend Specialist
    type: specialist
    description: "Pages, components, UI/UX"
    responsibilities:
      - Write frontend feature specifications
      - Create Astro pages with SSR
      - Build React components
      - Implement UI/UX designs
      - Fix frontend-related problems
      - Add frontend lessons learned
    prompt_file: one/things/agents/agent-frontend.md
    context_budget: 1500-2500 tokens
    outputs:
      - Astro pages
      - React components
      - UI implementations

  integration-specialist:
    role: Integration Specialist
    type: specialist
    description: "Connections, data flows, workflows"
    responsibilities:
      - Write integration feature specifications
      - Implement connections between systems
      - Create data flow logic
      - Coordinate multi-system features
      - Fix integration-related problems
      - Add integration lessons learned
    prompt_file: one/things/agents/agent-integration.md
    context_budget: 1500-2500 tokens
    outputs:
      - integration services
      - connection logic
      - workflow orchestration

  quality:
    role: Quality Agent
    description: "Defines tests, validates implementations, ensures ontology alignment"
    responsibilities:
      - Validate features against ontology
      - Define user flows (what users accomplish)
      - Create acceptance criteria (how we know it works)
      - Define technical tests (unit, integration, e2e)
      - Run tests after implementation
      - Validate implementations meet criteria
    prompt_file: one/things/agents/agent-quality.md
    context_budget: 2000 tokens
    outputs:
      - user flows
      - acceptance criteria
      - test specifications
      - validation results

  design:
    role: Design Agent
    description: "Creates wireframes and component architecture from test criteria"
    responsibilities:
      - Create wireframes that satisfy test criteria
      - Design UI that enables user flows to pass
      - Define component architecture
      - Set design tokens (colors, spacing, timing)
      - Ensure accessibility requirements met
    prompt_file: one/things/agents/agent-designer.md
    context_budget: 2000 tokens
    outputs:
      - wireframes
      - component architecture
      - design tokens
      - accessibility specs
    philosophy: "Design exists to make tests pass (test-driven design)"

  problem-solver:
    role: Problem Solver
    description: "Analyzes failures using ultrathink mode, proposes solutions"
    responsibilities:
      - Analyze failed tests using ultrathink mode
      - Determine root cause of failures
      - Propose specific solutions with code changes
      - Delegate fixes to appropriate specialists
      - Monitor fix implementation and re-testing
    prompt_file: one/things/agents/agent-problem-solver.md
    context_budget: 2500 tokens
    mode: ultrathink
    outputs:
      - root cause analysis
      - solution proposals
      - fix delegation

  documenter:
    role: Documenter
    description: "Writes documentation after features complete"
    responsibilities:
      - Write feature documentation
      - Create user guides
      - Document API changes
      - Update knowledge base
      - Create onboarding materials
    prompt_file: one/things/agents/agent-documenter.md
    context_budget: 1000 tokens
    outputs:
      - feature documentation
      - user guides
      - API documentation
      - knowledge base updates

# ============================================================================
# WORKFLOW EVENTS (Coordination via Events Table)
# ============================================================================
# Agents coordinate autonomously by logging and querying events
# Events table IS the message bus - no external coordination needed
# Complete audit trail of all workflow activities
# ============================================================================

workflow_events:
  # Planning Phase
  - plan_started
  - feature_assigned
  - feature_started

  # Implementation Phase
  - implementation_complete

  # Quality Phase
  - quality_check_started
  - quality_check_complete

  # Testing Phase
  - test_started
  - test_passed
  - test_failed

  # Problem Solving Phase
  - problem_analysis_started
  - solution_proposed
  - fix_started
  - fix_complete
  - lesson_learned_added

  # Documentation Phase
  - documentation_started
  - documentation_complete

  # Completion
  - feature_complete

# ============================================================================
# NUMBERING SYSTEM
# ============================================================================
# Hierarchical numbering: plan → feature → task
# Clear tracking, git-friendly, searchable
# ============================================================================

numbering:
  plan: "{plan_number}-{plan-name}"
  feature: "{plan_number}-{feature_number}-{feature-name}"
  task_list: "{plan_number}-{feature_number}-{feature-name}-tasks"
  task: "{plan_number}-{feature_number}-task-{task_number}"
  event: "events/{plan_number}-{feature_number}-{feature-name}-complete.md"

examples:
  plan: "2-course-platform"
  feature: "2-1-course-crud"
  task_list: "2-1-course-crud-tasks"
  task: "2-1-task-1"
  event: "events/2-1-course-crud-complete.md"

# ============================================================================
# COORDINATION PATTERN
# ============================================================================
# Event-driven autonomy - no handoff protocols, no dependency graphs
# Agents watch for relevant events and act autonomously
# ============================================================================

coordination:
  method: event_driven
  message_bus: events_table
  parallel_execution: true
  quality_loops: enabled
  knowledge_capture: lessons-learned.md

  patterns:
    director_watches: [quality_check_complete, documentation_complete]
    director_logs:
      [plan_started, feature_assigned, tasks_created, feature_complete]

    specialist_watches: [feature_assigned, task_created, solution_proposed]
    specialist_logs:
      [
        feature_started,
        implementation_complete,
        task_started,
        task_completed,
        fix_started,
        fix_complete,
        lesson_learned_added,
      ]

    quality_watches: [implementation_complete, task_completed]
    quality_logs:
      [
        quality_check_started,
        quality_check_complete,
        test_started,
        test_passed,
        test_failed,
      ]

    problem_solver_watches: [test_failed]
    problem_solver_logs: [problem_analysis_started, solution_proposed]

    documenter_watches: [test_passed (all tests)]
    documenter_logs: [documentation_started, documentation_complete]

# ============================================================================
# QUALITY LOOPS
# ============================================================================
# Test-driven quality with automatic problem solving
# ============================================================================

quality:
  test_driven: true
  loops_enabled: true

  flow: |
    Specialist implements → Quality validates → Tests run
      → PASS: Documenter writes docs → Complete
      → FAIL: Problem solver analyzes → Proposes fix → Specialist fixes
            → Add to lessons learned → Re-test (loop back)

  test_types:
    - user_flows: "What users must accomplish"
    - acceptance_criteria: "How we know it works"
    - unit_tests: "Service logic validation"
    - integration_tests: "API and data flow validation"
    - e2e_tests: "Complete user flow validation"

  problem_solving:
    mode: ultrathink
    steps:
      - Deep analysis of failed test + implementation
      - Root cause identification
      - Solution proposal with code changes
      - Delegation to specialist with clear instructions
      - Monitor fix and re-test

# ============================================================================
# KNOWLEDGE MANAGEMENT
# ============================================================================
# Continuous learning through lessons learned
# ============================================================================

knowledge:
  location: one/knowledge/lessons-learned.md

  structure:
    sections:
      - Backend Patterns
      - Frontend Patterns
      - Testing Patterns
      - Integration Patterns
      - Design Patterns

    entry_format: |
      ### Pattern Name
      - **Problem:** What went wrong
      - **Solution:** How it was fixed
      - **Rule:** Principle to follow
      - **Example:** Code snippet

  accumulation:
    trigger: after_every_fix
    owner: specialist_who_fixed
    usage:
      - Specialists reference when implementing
      - Quality agent references during validation
      - Problem solver searches for similar issues
      - Director uses to refine future plans

  benefits:
    - Institutional knowledge captured
    - Prevents repeated mistakes
    - Faster problem solving
    - Better quality over time
    - Onboarding new agents easier

# ============================================================================
# PERFORMANCE TARGETS
# ============================================================================

performance:
  context_reduction: "98% (from 150k → 3k tokens)"
  speed_improvement: "5x faster (from 115s → 20s per feature)"
  maintainability: "137x fewer files to update"
  code_reduction: "150 lines orchestration vs 15,000+ config"

  metrics:
    context_usage:
      idea: 200 tokens
      plan: 1500 tokens
      feature: 1500 tokens
      tests: 2000 tokens
      design: 2000 tokens
      implementation: 2500 tokens

    execution_speed:
      idea_to_plan: "3s (parallel context)"
      plan_to_features: "5s (type loading)"
      features_to_tests: "4s (pattern matching)"
      tests_to_implementation: "8s (parallel execution)"

# ============================================================================
# PHILOSOPHY
# ============================================================================

philosophy:
  core_principles:
    - "The ontology IS the workflow"
    - "Types define structure, patterns define implementation"
    - "Events coordinate everything"
    - "Agents collaborate autonomously"
    - "Quality loops ensure correctness"
    - "Knowledge accumulates continuously"
    - "Parallel by default, sequential only when required"
    - "Test-driven at every level"

  key_insight: |
    You don't need 15,000 lines of config to coordinate agents.
    You need a clear ontology + simple coordination patterns + autonomous agents.
    The workflow emerges from the ontology structure.

  result: "100x simpler, 5x faster, continuous learning, YAML-configurable"

# ============================================================================
# USAGE
# ============================================================================

usage:
  getting_started: "See one/things/cascade/docs/getting-started.md"
  workflow_details: "See one/things/cascade/docs/workflow.md"
  agent_prompts: "See one/things/agents/"
  templates: "See one/things/cascade/templates/"
  command_interface: "Run /one command in Claude Code"

  quick_start: |
    1. Run /one command
    2. Choose "1. Start New Idea"
    3. Describe what you want to build
    4. CASCADE orchestrates 8 agents to build it
    5. Get working code + tests + documentation

# ============================================================================
# END OF CASCADE CONFIGURATION
# ============================================================================