oneie/one/things/cascade/docs/examples/readme.md

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.

---
title: Readme
dimension: things
category: cascade
tags: agent
related_dimensions: events, groups, knowledge, people
scope: global
created: 2025-11-03
updated: 2025-11-03
version: 1.0.0
ai_context: |
  This document is part of the things dimension in the cascade category.
  Location: one/things/cascade/docs/examples/readme.md
  Purpose: Documents cascade feature examples
  Related dimensions: events, groups, knowledge, people
  For AI agents: Read this to understand readme.
---

# CASCADE Feature Examples

**Real-world examples of the 6-level workflow in action**

These are the actual features used to build the CASCADE system itself. They demonstrate the complete workflow from specification through implementation.

---

## The Meta-Example

CASCADE was built using CASCADE. These 6 features show the system building itself:

### Feature 1-1: Agent Prompts System

- **Status:** ✅ Complete (12 agent files, 303KB)
- **What:** Define prompts for 8 agent roles
- **Shows:** How to specify agent behaviors and responsibilities
- **Location:** `1-1-agent-prompts.md` + `1-1-agent-prompts/`

### Feature 1-2: YAML-Driven Orchestrator

- **Status:** ✅ Complete (cascade.yaml, 15.7KB)
- **What:** Build orchestrator that reads YAML and executes workflow
- **Shows:** How to design configuration-driven systems
- **Location:** `1-2-yaml-orchestrator.md` + `1-2-yaml-orchestrator/`

### Feature 1-3: Event Coordination System

- **Status:** ✅ Complete (20+ event types)
- **What:** Implement event-driven agent coordination
- **Shows:** How to design event-driven systems with no central coordinator
- **Location:** `1-3-event-coordination.md` + `1-3-event-coordination/`

### Feature 1-4: Knowledge Management System

- **Status:** ✅ Complete (lessons-learned.md structure)
- **What:** Build knowledge accumulation system
- **Shows:** How to capture and reuse institutional knowledge
- **Location:** `1-4-knowledge-management.md` + `1-4-knowledge-management/`

### Feature 1-5: Quality Loops and Problem Solving

- **Status:** ✅ Complete (ultrathink mode + quality gates)
- **What:** Implement quality validation and problem solving
- **Shows:** How to build self-healing systems with quality loops
- **Location:** `1-5-quality-loops.md` + `1-5-quality-loops/`

### Feature 1-6: Numbering and File Structure

- **Status:** ✅ Complete (hierarchical numbering system)
- **What:** Implement hierarchical numbering system
- **Shows:** How to design scalable file organization
- **Location:** `1-6-numbering-structure.md` + `1-6-numbering-structure/`

---

## What Each Feature Contains

Each feature directory includes:

### 1. Feature Specification (`{feature-name}.md`)

- **What we're building** (not how)
- **Ontology types** (things, connections, events, knowledge)
- **Scope** (backend, frontend, integration)
- **Success criteria** (linked to tests)

### 2. Tests (`{feature-name}/tests.md`)

- **User flows** (what users accomplish)
- **Acceptance criteria** (how we know it works)
- **Technical tests** (unit, integration, e2e)
- **Definition of done** (complete checklist)

### 3. Design (`{feature-name}/design.md`)

- **Design decisions** (driven by test requirements)
- **Architecture** (component structure)
- **Design tokens** (configuration)
- **Wireframes/diagrams** (visual representation)

---

## How to Use These Examples

### For Learning

1. **Read in order:** 1-1 → 1-2 → 1-3 → 1-4 → 1-5 → 1-6
2. **Study the pattern:** Spec → Tests → Design → Implementation
3. **Notice the flow:** Each level adds clarity and reduces ambiguity

### For Your Own Features

1. **Use as templates:** Copy structure for your features
2. **Adapt the patterns:** Similar problems have similar solutions
3. **Reference the tests:** See how user flows drive design

### For Understanding CASCADE

1. **Feature 1-1:** Shows how agents are defined (prompts)
2. **Feature 1-2:** Shows how workflow is configured (YAML)
3. **Feature 1-3:** Shows how agents coordinate (events)
4. **Feature 1-4:** Shows how knowledge accumulates (lessons learned)
5. **Feature 1-5:** Shows how quality is maintained (loops + problem solving)
6. **Feature 1-6:** Shows how work is organized (numbering system)

---

## The 6-Level Workflow (Demonstrated)

Each feature demonstrates the complete flow:

```
LEVEL 1: IDEA
└─> Feature 1-1: "Need agent prompts for 8 roles"

LEVEL 2: PLAN
└─> Plan 1: "Agent-Based Workflow System" (features 1-1 through 1-6)

LEVEL 3: FEATURE
└─> Feature 1-1: "Agent Prompts System" (specification)

LEVEL 4: TESTS
└─> 1-1-agent-prompts/tests.md (user flows + acceptance criteria)

LEVEL 5: DESIGN
└─> 1-1-agent-prompts/design.md (prompt structure + architecture)

LEVEL 6: IMPLEMENTATION
└─> one/things/agents/*.md (12 agent prompt files)
```

---

## Key Patterns to Notice

### 1. Test-Driven Everything

- Tests define user flows BEFORE implementation
- Design decisions are driven by test requirements
- Implementation exists to satisfy tests

### 2. Ontology Alignment

- Every feature maps to 6-dimension ontology
- Things, connections, events, knowledge always identified
- Validation against ontology structure

### 3. Progressive Refinement

- Each level adds more detail
- Ambiguity decreases as you move through levels
- Implementation becomes obvious by Level 6

### 4. Event Coordination

- Agents log events to coordinate
- No complex handoff protocols
- Complete audit trail

### 5. Knowledge Accumulation

- Problems become lessons learned
- Patterns emerge from experience
- Quality improves over time

---

## Compare These Examples

### Simple Feature (1-1: Agent Prompts)

- ✅ Single specialist (Backend)
- ✅ Clear deliverable (markdown files)
- ✅ No dependencies
- ✅ Straightforward tests

### Complex Feature (1-5: Quality Loops)

- ✅ Multiple agents (Quality + Problem Solver)
- ✅ Abstract deliverable (problem-solving flow)
- ✅ Dependencies on 1-1, 1-3
- ✅ Sophisticated tests (ultrathink mode validation)

Both follow the same 6-level workflow. Complexity doesn't change the process.

---

## Learning Path

### Beginner: Start Here

1. Read **Feature 1-1** (Agent Prompts) - simplest example
2. Study the tests - see how user flows are defined
3. Look at the design - see how structure emerges from tests
4. Check implementation - see prompts in `one/things/agents/`

### Intermediate: Understand Coordination

1. Read **Feature 1-3** (Event Coordination) - agent communication
2. Study the event types - see how agents coordinate
3. Look at the patterns - no handoff protocols needed
4. Understand autonomy - agents watch events and act

### Advanced: Master Quality

1. Read **Feature 1-5** (Quality Loops) - self-healing systems
2. Study problem solving - ultrathink mode analysis
3. Look at knowledge capture - lessons learned system
4. Understand continuous improvement - quality over time

---

## Real-World Application

These features show how to:

- ✅ Break complex systems into manageable features
- ✅ Define clear acceptance criteria before coding
- ✅ Design test-driven architectures
- ✅ Coordinate multiple agents autonomously
- ✅ Build systems that learn and improve
- ✅ Maintain quality through automatic loops
- ✅ Document as you build

**Result:** Production-ready CASCADE system built using its own workflow.

---

## Next Steps

1. **Study one feature deeply:** Pick 1-1 or 1-3, understand completely
2. **Try the template:** Use `../../../templates/feature-template.md` for your feature
3. **Follow the flow:** Spec → Tests → Design → Implementation
4. **Use CASCADE:** Run `/one` and build something real

---

**Built by CASCADE, for CASCADE users**

These examples prove the system works. Now use it to build something amazing.