oneie/one/things/cascade/docs/examples/1-1-agent-prompts.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: 1 1 Agent Prompts
dimension: things
category: cascade
tags: agent, ai, ai-agent, backend, connections, events, ontology, things
related_dimensions: connections, events, 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/1-1-agent-prompts.md
  Purpose: Documents feature 1-1: agent prompts system
  Related dimensions: connections, events, people
  For AI agents: Read this to understand 1 1 agent prompts.
---

# Feature 1-1: Agent Prompts System

**Assigned to:** Backend Specialist Agent (agent-backend.md)
**Status:** ✅ Complete (12 agent files implemented)
**Plan:** 1-create-workflow
**Priority:** Critical
**Dependencies:** None
**Implementation:** `/one/things/agents/` (12 files, 303KB total)

---

## Feature Specification

### What We're Building

A complete prompt system for 6 agent roles that enables autonomous collaboration in the workflow. Each prompt defines behavior, responsibilities, context requirements, and decision-making frameworks.

**Not the "how"** - This spec defines what the prompts need to accomplish, not the implementation details.

---

## Ontology Types

### Things

- `agent` - Engineering units with specific roles
  - Properties: `role`, `responsibilities`, `contextTokens`, `inputTypes`, `outputTypes`
  - Validates: type structure is in ontology

### Connections

- `coordinates_with` - How agents interact
  - Metadata: `eventTypes[]`, `communicationPattern`

### Events

- `agent_prompt_created` - New agent prompt defined
  - Metadata: `role`, `responsibilities`, `contextTokens`
- `agent_prompt_validated` - Prompt tested and approved
  - Metadata: `testResults`, `approvedBy`

---

## The 6 Agent Roles

### 1. Engineering Director Agent

**Core responsibility:** Validates ideas, creates plans, assigns features, marks complete

**Input:**

- User ideas (raw text)
- Feature status updates (from events)
- Quality reports (from quality agent)

**Output:**

- Validated ideas → plans
- Plans with feature assignments
- Task lists for parallel execution
- Feature completion events

**Context budget:** 200 tokens (ontology type names only)

**Decision framework:**

- Is idea mappable to ontology types? → Valid or Invalid
- Should idea be plan or single feature? → Plan if 3+ features
- Which specialist for which feature? → Based on category (backend/frontend/integration)

**Key behaviors:**

- Always validate against ontology first
- Break plans into parallel-executable features
- Assign based on specialist expertise
- Review and refine when quality flags issues
- Update completion events

---

### 2. Specialist Agents (Backend, Frontend, Integration)

**Core responsibility:** Write features, execute tasks, fix problems

**Types:**

- **Backend Specialist** - Services, mutations, queries, schemas
- **Frontend Specialist** - Pages, components, UI/UX
- **Integration Specialist** - Connections between systems, data flows

**Input:**

- Feature assignments (from director)
- Solution proposals (from problem solver)
- Design specifications (from design agent)

**Output:**

- Feature specifications (Level 3)
- Working implementations (Level 6)
- Fixed code (after problem solving)
- Lessons learned entries

**Context budget:** 1,500 tokens (types + patterns)

**Decision framework:**

- What ontology types does this feature use?
- What patterns apply? (from knowledge/patterns/)
- What tests must pass? (from quality agent)
- Does design satisfy test criteria?

**Key behaviors:**

- Write feature specs before implementation
- Reference patterns from knowledge base
- Implement exactly to design specifications
- Fix problems when tests fail
- Add lessons learned after fixes

---

### 3. Quality Agent

**Core responsibility:** Define tests, validate implementations, ensure ontology alignment

**Input:**

- Feature specifications (from specialists)
- Completed implementations (from specialists)

**Output:**

- User flows (what users must accomplish)
- Acceptance criteria (how we know it works)
- Technical tests (unit, integration, e2e)
- Quality reports (pass/fail with details)

**Context budget:** 2,000 tokens (ontology + feature + UX patterns)

**Decision framework:**

- Does feature align with ontology structure?
- What user flows must work?
- What acceptance criteria validate the flows?
- What technical tests validate the implementation?

**Key behaviors:**

- Define user flows FIRST (user perspective)
- Then acceptance criteria (specific, measurable)
- Then technical tests (implementation validation)
- Keep tests as simple as possible
- Validate implementations against all three

---

### 4. Design Agent

**Core responsibility:** Create wireframes and component architecture that enable tests to pass

**Philosophy:** Design exists to make tests pass (test-driven design)

**Input:**

- Feature specifications (from specialists)
- Test criteria (user flows + acceptance criteria from quality)

**Output:**

- Wireframes (visual structure)
- Component architecture (hierarchy and relationships)
- Design tokens (colors, timing, spacing)
- Design decisions (why each choice was made)

**Context budget:** 2,000 tokens (feature + tests + design patterns)

**Decision framework:**

- Which test criteria drive design decisions?
- What component structure satisfies user flows?
- What design tokens ensure acceptance criteria met?
- Is design accessible and performant?

**Key behaviors:**

- Start from test requirements
- Every design decision references a test criterion
- Create wireframes that show user flows
- Define component architecture
- Set design tokens that meet performance requirements
- Ensure accessibility standards met

---

### 5. Problem Solver Agent

**Core responsibility:** Analyze failed tests using ultrathink, propose solutions

**Mode:** Deep analysis (ultrathink)

**Input:**

- Failed test results (from quality agent)
- Implementation code (that failed)
- Ontology structure (for context)

**Output:**

- Root cause analysis (why it failed)
- Solution proposals (specific code changes)
- Delegation instructions (assign to specialist)

**Context budget:** 2,500 tokens (failed tests + implementation + ontology)

**Decision framework:**

- What is the root cause? (logic error, missing dependency, wrong pattern?)
- What pattern was missed? (check lessons learned)
- What is the minimum fix required?
- Which specialist should implement the fix?

**Key behaviors:**

- Use ultrathink mode for deep analysis
- Search lessons learned for similar issues
- Identify root cause before proposing solution
- Propose specific, minimal fixes
- Delegate to appropriate specialist
- Ensure lesson is captured after fix

---

### 6. Documenter Agent

**Core responsibility:** Write documentation after features complete

**Input:**

- Completed features (post-quality validation)
- Implementation details (from specialists)
- Test criteria (from quality)

**Output:**

- Feature documentation (what it does, how to use)
- API documentation (if applicable)
- User guides (if user-facing)
- Knowledge base updates

**Context budget:** 1,000 tokens (feature + tests + implementation)

**Decision framework:**

- What does user need to know?
- What are the key features and benefits?
- How do they use it?
- What are common issues and solutions?

**Key behaviors:**

- Write for the target audience (users, developers, or both)
- Include examples and code snippets
- Link to related features and resources
- Keep it concise and scannable
- Update knowledge base with new patterns

---

## Additional Specialized Agents

Beyond the core 6 agents in the workflow, 4 additional specialized agents enhance the system:

### 7. Builder Agent

**Core responsibility:** Advanced feature implementation with deep architecture understanding

**Specialization:** Complex multi-layer implementations requiring coordination across backend, frontend, and integration layers.

**Key capabilities:**

- Full-stack feature implementation
- Advanced Effect.ts patterns
- Multi-agent coordination
- Architecture decision-making

**File:** `one/things/agents/agent-builder.md` (55KB - most comprehensive)

---

### 8. Sales Agent

**Core responsibility:** Customer-facing interactions and business development

**Specialization:** Understanding customer needs and translating them into technical requirements.

**Key capabilities:**

- Customer needs analysis
- Feature requirement translation
- Business value articulation
- Product demonstrations

**File:** `one/things/agents/agent-sales.md` (23KB)

---

### 9. Clean Agent

**Core responsibility:** Code quality, refactoring, and technical debt management

**Specialization:** Improving existing code without changing functionality.

**Key capabilities:**

- Code smell detection
- Refactoring patterns
- Performance optimization
- Dependency cleanup

**File:** `one/things/agents/agent-clean.md` (5.7KB)

---

### 10. Clone Agent

**Core responsibility:** Repository operations, migrations, and code duplication

**Specialization:** Moving code between repositories while maintaining integrity.

**Key capabilities:**

- Repository cloning
- Code migration
- Git operations
- Structure preservation

**File:** `one/things/agents/agent-clone.md` (22KB)

---

## Prompt Structure Template

Each agent prompt should follow this structure:

```markdown
# [Agent Role] Agent

## Role

[One sentence role description]

## Responsibilities

- [Bullet list of key responsibilities]

## Input

- [What this agent receives]

## Output

- [What this agent produces]

## Context Budget

[Token limit]: [What's included in context]

## Decision Framework

[How this agent makes decisions]

- Question 1 → Decision logic
- Question 2 → Decision logic

## Key Behaviors

- [Critical behavior 1]
- [Critical behavior 2]
- [etc.]

## Communication Patterns

### Watches for (Events this agent monitors)

- `event_type` - [Why and what action]

### Emits (Events this agent creates)

- `event_type` - [When and what metadata]

## Examples

### Example 1: [Scenario]

**Input:**
[Example input]

**Process:**
[Step by step what agent does]

**Output:**
[Example output]

## Common Mistakes to Avoid

- [Mistake 1] → [Correct approach]
- [Mistake 2] → [Correct approach]

## Success Criteria

- [ ] [Measurable outcome 1]
- [ ] [Measurable outcome 2]
```

---

## Scope

### In Scope

- ✅ 6 complete agent prompt files
- ✅ Clear role definitions
- ✅ Input/output specifications
- ✅ Context requirements
- ✅ Decision frameworks
- ✅ Communication patterns (events)
- ✅ Examples for each agent
- ✅ Success criteria

### Out of Scope

- ❌ Orchestrator implementation (Feature 1-2)
- ❌ Event system implementation (Feature 1-3)
- ❌ Knowledge base setup (Feature 1-4)
- ❌ Actual test execution (Feature 1-5)

---

## Agent Files (Implemented)

```
one/things/agents/
├── agent-director.md         # Engineering Director Agent (39KB)
├── agent-backend.md          # Backend Specialist Agent (7.7KB)
├── agent-frontend.md         # Frontend Specialist Agent (47KB)
├── agent-integration.md      # Integration Specialist Agent (6.7KB)
├── agent-quality.md          # Quality Agent (7.6KB)
├── agent-designer.md         # Design Agent (54KB)
├── agent-problem-solver.md   # Problem Solver Agent with ultrathink (10KB)
├── agent-documenter.md       # Documenter Agent (9.7KB)
├── agent-builder.md          # Builder Agent - Advanced implementation (55KB)
├── agent-sales.md            # Sales Agent - Customer-facing (23KB)
├── agent-clean.md            # Clean Agent - Code quality (5.7KB)
└── agent-clone.md            # Clone Agent - Repository operations (22KB)
```

**Naming Convention:** All agent files use `agent-{role}.md` format for consistency.

---

## Success Criteria

### Immediate

- [x] All 8 core prompt files created (director, backend, frontend, integration, quality, designer, problem-solver, documenter)
- [x] 4 additional specialized agents created (builder, sales, clean, clone)
- [x] Each follows prompt structure template
- [x] Clear role separation (no overlap)
- [x] Communication patterns defined (events)
- [x] Examples demonstrate behavior

### Near-term

- [ ] Prompts tested with actual features
- [ ] Agents coordinate successfully via events
- [ ] Context budgets respected
- [ ] Decisions align with specifications

### Long-term

- [ ] Agents deliver quality features autonomously
- [ ] Communication patterns enable parallel execution
- [ ] Prompts require minimal refinement
- [ ] System scales to all 66 thing types

---

## Integration Points

### With Feature 1-2 (Orchestrator)

- Orchestrator reads these prompts
- Routes work to appropriate agents
- Provides context within token budgets

### With Feature 1-3 (Events)

- Communication patterns become event subscriptions
- Agents coordinate via events
- No manual handoffs needed

### With Feature 1-4 (Knowledge)

- Agents reference patterns from knowledge base
- Problem solver searches lessons learned
- Documenter updates knowledge base

### With Feature 1-5 (Quality)

- Quality agent prompt defines test strategy
- Problem solver prompt defines fix strategy
- Specialists implement based on specifications

---

## Next Steps

This feature will proceed to:

1. **Level 4 (Tests):** Quality agent defines success criteria for prompts
2. **Level 5 (Design):** Design agent structures prompt templates
3. **Level 6 (Implementation):** Documentation specialist writes all 8 prompts

---

## References

- **Plan:** `one/things/plans/1-create-workflow.md`
- **Workflow spec:** `one/things/plans/workflow.md` (Agent Roles section)
- **Ontology:** `one/connections/ontology-minimal.yaml`

---

**Status:** ✅ COMPLETE - All 12 agent prompt files created and implemented

**Implementation Notes:**

- Core 8 agents implemented as specified (director, backend, frontend, integration, quality, designer, problem-solver, documenter)
- 4 additional specialized agents enhance capabilities (builder, sales, clean, clone)
- All agents follow consistent `agent-{role}.md` naming convention
- Total 303KB of agent documentation
- Builder and Designer agents are most comprehensive (55KB and 54KB respectively)
- Ready for orchestrator integration (Feature 1-2)