# OpenCodeKit Prompt Cascade Design Analysis

**Date:** November 20, 2025  
**Mission:** Design elegant, explicit prompt hierarchy with cascade precedence rules

## Facts (Current State - Verified)

✅ **Current Prompt Organization:**
- Global: `~/.config/opencode/AGENTS.md` (170 lines, core rules + system design)
- Project: `/AGENTS.md` (16 lines, only code style guidelines - minimal!)
- Agent-specific: `.opencode/agent/{name}.md` (YAML frontmatter + markdown)
- 7 agents: build, plan, researcher, code-auditor, orchestrator, rush, general

✅ **Current Inheritance Model (Implicit):**
- Build agent reads its own `.opencode/agent/build.md` (references AGENTS.md)
- Plan agent has own `.opencode/agent/plan.md` (similar structure)
- No explicit inheritance syntax or override rules
- YAML frontmatter contains mode (primary/subagent), tools, model config

✅ **Key Architectural Facts:**
- Global AGENTS.md covers: Priority hierarchy, Skills system, Memory, Context strategy, Agentic workflow, Phase transitions, Knowledge base, Core constraints
- Project AGENTS.md is SEVERELY underutilized (just code style, 16 lines)
- Agent configs have YAML frontmatter (metadata) + Markdown body (behavior)
- Mode-aware loading exists implicitly but not documented (build=primary, others=subagent)
- Security constraints stated as "#1 priority" but not formally codified per layer

✅ **Existing Tool Patterns:**
- `memory-read/update` → Cross-session knowledge
- `backlog_task_*` → Multi-session project tracking  
- `todowrite/todoread` → In-session tasks
- No explicit inheritance tools (must use file references manually)

## Guesses (Hypotheses to Validate)

⚠️ **Guess 1: Current system has implicit cascades that cause confusion**
- Rationale: Global rules exist, project rules underutilized, agent prompts reference files that may not exist
- Validation: Show cascade precedence table + identify conflicts in real prompts
- Impact if wrong: May be more organized than observed; redesign anyway for explicitness

⚠️ **Guess 2: Project override capability is intentionally minimal (not accidentally)**
- Rationale: AGENTS.md has only style guidelines, not agent behavior
- Validation: Check if intentional design vs. incomplete setup
- Impact if wrong: May have missed feature layer

⚠️ **Guess 3: Mode-aware loading (primary vs. subagent) should differ in inherited content**
- Rationale: Subagents should skip domain-specific workflows, use narrower focus
- Validation: Design mode-aware inheritance rules
- Impact if wrong: Subagents may get bloated with irrelevant project context

⚠️ **Guess 4: Three alternatives will emerge, one clearly superior**
- Rationale: Cascade systems have limited elegant forms (depth-based, scope-based, importance-based)
- Validation: Design 3 alternatives, assess each
- Impact if wrong: May need 4th alternative or hybrid approach

## Plans (Next Steps)

### Phase 1: Cascade Precedence Analysis
1. [ ] Document current implicit cascade behavior
2. [ ] Identify conflict resolution rules
3. [ ] Show what each layer can override
4. [ ] Document mode-aware loading semantics

### Phase 2: Design Three Alternatives
1. [ ] Alternative A: Linear Cascade (Global → Project → Agent)
2. [ ] Alternative B: Layered Composition (Security core → Conventions → Domain → Agent)
3. [ ] Alternative C: Scope-Based Inheritance (with explicit inheritance paths)
4. [ ] Assess each for elegance, clarity, extensibility

### Phase 3: Recommend Optimal Solution
1. [ ] Honest assessment of trade-offs
2. [ ] Show file structure for recommended approach
3. [ ] Explain precedence rules clearly
4. [ ] Provide implementation roadmap

### Phase 4: Documentation Package
1. [ ] Cascade precedence table
2. [ ] Inheritance rules matrix
3. [ ] Mode-loading semantics diagram
4. [ ] Real-world examples (4 scenarios)
5. [ ] File structure proposal with 100-line limit per file
