diff --git a/.opencode/AGENT-SYSTEM-BLUEPRINT.md b/.opencode/AGENT-SYSTEM-BLUEPRINT.md new file mode 100644 index 0000000..0d7770b --- /dev/null +++ b/.opencode/AGENT-SYSTEM-BLUEPRINT.md @@ -0,0 +1,760 @@ +# The OpenCode Agent System Blueprint + +_Build Intelligent Workflow Systems with Context-Aware AI_ + +## The Golden Rule + +**Context flows in one direction: Commands load context immediately, Agents can look up additional context deterministically.** + +Like a well-organized library: the librarian (command) brings you the right books immediately, but you (agent) can look up specific references when needed. + +## How @ Symbol Context Loading Works (FUNDAMENTAL) + +### The Magic of Automatic Context Injection + +When you create a slash command with @ references, OpenCode automatically loads that context into the agent's memory BEFORE the agent starts thinking: + +```markdown +# .opencode/command/create-component.md + +--- + +name: create-component +agent: simple-coder + +--- + +You are creating React components following our patterns. + +**Request:** $ARGUMENTS + +@.opencode/context/frontend/react-patterns.md +@.opencode/context/styling/design-system.md +@.opencode/context/core/validation-patterns.md + +Create the component now. +``` + +**What happens when user types `/create-component "user profile card"`:** + +1. ✅ OpenCode reads the command file +2. ✅ **Automatically loads** react-patterns.md, design-system.md, validation-patterns.md +3. ✅ **Injects all context** into the agent's working memory +4. ✅ Agent receives: user request + all loaded context + instructions +5. ✅ Agent can immediately use patterns without looking them up + +### Why This Mechanism Is Powerful + +**❌ Without @ loading:** + +``` +Agent: "I need to create a component but don't know your patterns. Let me search..." +→ Agent uses generic patterns or has to look up files +→ Inconsistent results, slower execution +``` + +**✅ With @ loading:** + +``` +Agent: "I have your React patterns, design system, and validation rules loaded. Creating component..." +→ Agent immediately follows your exact patterns +→ Consistent, fast, high-quality results +``` + +### Context Loading Strategy + +**Base Context (Always Load):** + +```markdown +@.opencode/context/core/essential-patterns.md +@.opencode/context/architecture/project-structure.md +``` + +**Domain-Specific Context (Load Based on Command Purpose):** + +```markdown +# Frontend commands + +@.opencode/context/frontend/react-patterns.md +@.opencode/context/styling/design-system.md + +# Backend commands + +@.opencode/context/backend/server-patterns.md +@.opencode/context/database/query-patterns.md + +# Testing commands + +@.opencode/context/testing/test-patterns.md +``` + +### Dynamic Context Loading + +```markdown +# Advanced: Conditional context based on request analysis + +@.opencode/context/core/essential-patterns.md +!`if echo "$ARGUMENTS" | grep -i "component\|ui" > /dev/null; then echo "@.opencode/context/frontend/react-patterns.md"; fi` +!`if echo "$ARGUMENTS" | grep -i "database\|query" > /dev/null; then echo "@.opencode/context/database/query-patterns.md"; fi` +``` + +### Best Practices for @ Context Loading + +1. **Load 2-4 context files maximum** (prevent cognitive overload) +2. **Always include core patterns** (essential-patterns.md) +3. **Load domain-specific patterns** based on command purpose +4. **Keep context files focused** (50-150 lines each) +5. **Use conditional loading** for dynamic context selection + +### Why This Architecture Matters + +Understanding @ symbol auto-loading is crucial because: + +- **It's the foundation** of how agents get consistent context +- **It determines command design** - you must anticipate what context agents need +- **It explains the architecture** - why commands are "smart loaders" and agents are "focused executors" +- **It guides best practices** - load the right context, not too much, not too little + +**This mechanism is what makes the system "intelligent" - agents always start with the right knowledge instead of having to discover it.** + +## Core Principles + +### 1. Single-Level Context Loading + +**OpenCode processes `@` references only in command templates, NOT recursively in file contents.** + +```markdown +# ✅ This works (in command template) + +@.opencode/context/frontend/patterns.md +@.opencode/context/styling/design-system.md + +# ❌ This doesn't work (inside patterns.md file) + +# If patterns.md contains @other-file.md, it's treated as plain text +``` + +**Critical Implication**: Commands must load ALL necessary context upfront using @ references. Agents can look up additional files using tools (read, grep, glob), but cannot use @ loading themselves. + +### 2. Deterministic vs Non-Deterministic Behavior + +- **Commands**: Non-deterministic - analyze requests and load appropriate context +- **Agents**: Deterministic - predictable behavior, can look up additional context + +### 3. Context Optimization + +- **Maximum 4 context files per command** (250-450 lines total) +- **50-150 lines per context file** (optimal range) +- **Always load core patterns** + request-specific context + +## The 5-Part Intelligent System + +### 1. Commands (.opencode/command/) + +**What:** Entry points that load immediate context based on request analysis +**Rule:** Commands are non-deterministic - they adapt context to the request + +``` +/workflow → Intelligent routing with dynamic context +/plan-task → Task planning with architecture context +/execute-task → Step execution with progress tracking +/create-frontend-component → UI development with styling + frontend context +/create-backend-operation → Server logic with backend + database context +/create-database-operation → Database queries with focused database context +/review-completion → Quality assurance with minimal context +/validate-with-tests → Automated testing with testing context +``` + +**Command Structure Pattern:** + +```markdown +--- +name: command-name +agent: target-agent +description: "What this command does" +--- + +You are [doing specific task]. [Direct instructions to agent]. + +**Request:** $ARGUMENTS + +**Your Instructions:** + +1. **ANALYZE** the request... +2. **IMPLEMENT** following patterns... +3. **VALIDATE** the results... + +**Context Loaded:** +@.opencode/context/core/essential-patterns.md +@.opencode/context/[domain]/[specific-patterns].md +@.opencode/context/architecture/architecture-lite.md + +**Success Criteria:** + +- [Specific measurable outcomes] + +Execute this [task type] now. +``` + +### 2. Agents (.opencode/agent/) + +**What:** Deterministic AI workers with specific capabilities +**Rule:** Agents can look up additional context but are predictable in behavior + +``` +Primary Agents: +├── workflow-orchestrator.md → Routes requests and analyzes complexity +├── task-planner.md → Creates detailed task plans with file tracking +├── task-executor.md → Executes planned steps systematically +├── post-flight-reviewer.md → Reviews completed work for compliance +└── simple-coder.md → Implements focused development tasks + +Subagents (Specialized): +├── subagents/code-reviewer.md → Security and quality reviews (read-only) +├── subagents/test-writer.md → Test creation and validation (reports issues) +├── subagents/pattern-finder.md → Discovers existing implementations +└── subagents/doc-writer.md → Documentation creation and updates +``` + +**Agent Structure Pattern:** + +```markdown +--- +description: "What this agent does" +mode: primary|subagent +model: claude-4-sonnet +temperature: 0.1-0.3 +tools: + read: true|false + edit: true|false + write: true|false + bash: true|false + task: true|false +permissions: + edit: + "**/*.env*": "deny" + "**/*.secret": "deny" +--- + +You are [specific role]. [Direct instructions for behavior]. + +**EXECUTE** this [process type] for every [task type]: + +**1. [ACTION]** the [subject]: + +- [Specific instruction 1] +- [Specific instruction 2] + +**2. [ACTION]** the [subject]: + +- [Specific instruction 1] +- [Specific instruction 2] + +**RULES**: + +- **ALWAYS** [critical requirement] +- **NEVER** [forbidden action] +- **ONLY** [scope limitation] + +Execute [task type] now. +``` + +### 3. Context (.opencode/context/) + +**What:** Layered knowledge system with focused domains +**Rule:** Single-level loading - no recursive context references + +``` +context/ +├── core/ +│ └── essential-patterns.md (76 lines - always loaded) +├── architecture/ +│ └── architecture-lite.md (74 lines - project structure) +├── frontend/ +│ ├── frontend-patterns.md (230 lines - React patterns) +│ └── styling/design-system.md (122 lines - UI standards) +├── backend/ +│ ├── backend-patterns.md (326 lines → split into focused files) +│ └── server-actions.md (100 lines - focused server action patterns) +├── database/ +│ └── database-queries.md (207 lines - query patterns) +├── security/ +│ └── security-patterns.md (205 lines - auth patterns) +├── testing/ +│ ├── testing-patterns.md (322 lines → split) +│ └── unit-testing.md (100 lines - focused test patterns) +└── debugging/ + └── common-errors.md (304 lines → split by error type) +``` + +**Context File Structure Pattern:** + +````markdown +**[ACTION]** [subject] using these exact patterns: + +**[PATTERN NAME]** - [When to use]: + +```[language] +// Example code with clear comments +// Showing exactly what to do +``` +```` + +**[ANOTHER PATTERN]** - [When to use]: + +```[language] +// Another example +``` + +**RULES**: + +- **ALWAYS** [critical requirement] +- **NEVER** [forbidden action] +- **USE** [specific tools/methods] + +``` + +### 4. Task Management (tasks/) +**What:** File-based progress tracking with checkbox systems +**Rule:** Every complex task gets a plan file with step-by-step tracking + +``` + +tasks/ +├── features/ # Feature development +│ └── [feature-name]/ +│ ├── task-plan.md # Main plan with checkboxes +│ ├── execution-log.md # Detailed progress log +│ └── review-report.md # Post-flight review +├── fixes/ # Bug fixes +│ └── [issue-name]/ +│ ├── task-plan.md +│ └── fix-report.md +├── improvements/ # Code improvements +│ └── [improvement-name]/ +└── single/ # Simple tasks +└── [task-name].md + +```` + +**Task Plan File Structure:** +```markdown +# Task: [Task Name] + +## Overview +**Request**: [Original user request] +**Complexity**: [Simple/Medium/Complex] +**Estimated Duration**: [Time estimate] +**Dependencies**: [List any blocking requirements] + +## Task Breakdown + +### Phase 1: [Phase Name] +- [ ] **Step 1.1**: [Specific action] + - **Agent**: @[agent-name] + - **Context**: [Required context files] + - **Validation**: [How to verify completion] + - **Duration**: [Time estimate] + +- [ ] **Step 1.2**: [Specific action] + - **Agent**: @[agent-name] + - **Context**: [Required context files] + - **Validation**: [How to verify completion] + - **Duration**: [Time estimate] + +## Quality Gates +- [ ] **Build Validation**: TypeScript compilation passes +- [ ] **Code Review**: Security and quality review completed +- [ ] **Testing**: All tests pass and coverage adequate +- [ ] **Integration**: Feature works end-to-end + +## Acceptance Criteria +- [ ] [Specific requirement 1] +- [ ] [Specific requirement 2] + +## Progress Tracking +**Started**: [Date/Time] +**Last Updated**: [Date/Time] +**Status**: [Planning/In Progress/Review/Complete] +**Completed Steps**: 0/[Total Steps] +```` + +### 5. Workflow Orchestration + +**What:** Multi-agent coordination with quality gates +**Rule:** Complex workflows use multiple agents with validation checkpoints + +``` +Workflow Types: +├── Simple (< 30 min) → Direct execution with focused context +├── Medium (30min-2hrs) → Task planning with step tracking +└── Complex (> 2hrs) → Multi-phase with quality gates + +Quality Gates: +├── Build Validation → TypeScript, linting, build checks +├── Code Review → Security and quality assessment +├── Testing → Automated test execution +└── Post-Flight Review → Instruction compliance verification +``` + +## System Flow (Intelligent Workflow Management) + +```mermaid +flowchart TD + A[User Request] --> B[Workflow Orchestrator] + B --> C{Analyze Request} + C --> D{Complexity?} + D -->|Simple| E[Direct Execution] + D -->|Complex| F[Task Planning] + + E --> G[Load Focused Context] + G --> H[Execute with Agent] + H --> I[Validate Results] + I --> J[Complete] + + F --> K[Create Task Plan File] + K --> L[Step-by-Step Execution] + L --> M[Update Progress Tracking] + M --> N{More Steps?} + N -->|Yes| O[Next Step] + N -->|No| P[Quality Gates] + O --> L + P --> Q[Post-Flight Review] + Q --> R[Mark Complete] + + style A fill:#E6F3FF + style J fill:#E6FFE6 + style R fill:#E6FFE6 +``` + +## Context Loading Strategy + +### Dynamic Context Loading Pattern + +```markdown +# In workflow orchestrator + +**ANALYZE** request: "$ARGUMENTS" + +**BASE CONTEXT** (always loaded): +@.opencode/context/core/essential-patterns.md +@.opencode/context/architecture/architecture-lite.md + +**CONDITIONAL CONTEXT** (based on request analysis): +!`if echo "$ARGUMENTS" | grep -i -E "(component|ui|frontend)" > /dev/null; then echo "@.opencode/context/styling/design-system.md"; fi` +!`if echo "$ARGUMENTS" | grep -i -E "(server|backend|action)" > /dev/null; then echo "@.opencode/context/backend/server-actions.md"; fi` +!`if echo "$ARGUMENTS" | grep -i -E "(database|query|data)" > /dev/null; then echo "@.opencode/context/database/database-queries.md"; fi` +``` + +### Context Size Guidelines + +- **✅ Optimal**: 50-150 lines (focused, actionable patterns) +- **⚠️ Acceptable**: 150-250 lines (comprehensive but manageable) +- **❌ Too Large**: 250+ lines (should be split into focused files) + +### Context Loading Rules + +1. **Always load core patterns** (essential-patterns.md + architecture-lite.md) +2. **Maximum 4 context files** per command (prevent overload) +3. **Load based on request analysis** (dynamic, not static) +4. **Use bash commands** for conditional loading + +## Implementation Guide + +### Step 1: Create Your Workflow Commands + +```markdown +# Essential Commands to Create: + +/workflow # Main entry with intelligent routing +/plan-task # Complex task breakdown +/execute-task # Step-by-step execution +/create-frontend-component # UI development +/create-backend-operation # Server logic +/review-completion # Quality assurance +``` + +### Step 2: Build Your Agent System + +```markdown +# Core Agents Needed: + +workflow-orchestrator.md # Request analysis and routing +task-planner.md # Detailed planning with file tracking +task-executor.md # Step execution with progress updates +post-flight-reviewer.md # Compliance and quality review +simple-coder.md # Focused implementation work + +# Specialized Subagents: + +subagents/code-reviewer.md # Security and quality (read-only) +subagents/test-writer.md # Test creation (reports issues) +``` + +### Step 3: Structure Your Context + +```markdown +# Context Organization: + +core/essential-patterns.md # Always loaded (76 lines) +architecture/architecture-lite.md # Project structure (74 lines) +frontend/frontend-patterns.md # React patterns (230 lines) +styling/design-system.md # UI standards (122 lines) +backend/server-actions.md # Server patterns (100 lines) +database/database-queries.md # Query patterns (207 lines) +``` + +### Step 4: Implement Task Management + +```markdown +# Task File Structure: + +tasks/features/[name]/task-plan.md # Main planning file +tasks/features/[name]/review-report.md # Post-completion review +tasks/fixes/[name]/task-plan.md # Bug fix planning +tasks/single/[name].md # Simple tasks +``` + +### Step 5: Add Quality Gates + +```markdown +# Automated Validation: + +!`pnpm tsc --noEmit` # TypeScript check +!`pnpm lint` # Code quality +!`pnpm build` # Build validation +!`pnpm test` # Test execution +``` + +## Best Practices + +### Context Management + +1. **Keep context files focused** (50-150 lines) +2. **Use single-level loading** (no recursive `@` references) +3. **Load dynamically** based on request analysis +4. **Always include core patterns** + architecture + +### Agent Design + +1. **Make agents deterministic** (predictable behavior) +2. **Give clear, direct instructions** (not documentation) +3. **Separate concerns** (one agent, one responsibility) +4. **Use structured response formats** + +### Task Management + +1. **Break complex work into steps** (15-30 minutes each) +2. **Use checkbox tracking** for progress visibility +3. **Include validation criteria** for each step +4. **Implement quality gates** at key milestones + +### Workflow Orchestration + +1. **Analyze before routing** (complexity and domain) +2. **Use appropriate workflows** (simple vs complex) +3. **Coordinate multiple agents** for complex tasks +4. **Validate at every step** (build, test, review) + +## System Architecture + +```mermaid +graph TB + subgraph "User Interface" + CMD["/workflow
/plan-task
/execute-task"] + end + + subgraph ".opencode/command/" + C1[workflow.md] + C2[plan-task.md] + C3[execute-task.md] + C4[create-frontend-component.md] + C5[create-backend-operation.md] + end + + subgraph ".opencode/agent/" + A1[workflow-orchestrator.md] + A2[task-planner.md] + A3[task-executor.md] + A4[simple-coder.md] + A5[post-flight-reviewer.md] + end + + subgraph ".opencode/context/" + CTX1[core/essential-patterns.md] + CTX2[architecture/architecture-lite.md] + CTX3[frontend/frontend-patterns.md] + CTX4[backend/server-actions.md] + CTX5[database/database-queries.md] + end + + subgraph "tasks/" + T1[features/[name]/task-plan.md] + T2[fixes/[name]/task-plan.md] + T3[single/[name].md] + end + + CMD --> C1 + CMD --> C2 + CMD --> C3 + + C1 --> A1 + C2 --> A2 + C3 --> A3 + C4 --> A4 + C5 --> A4 + + A1 --> CTX1 + A1 --> CTX2 + A2 --> CTX2 + A3 --> CTX1 + A4 --> CTX3 + A4 --> CTX4 + + A2 --> T1 + A3 --> T1 + A3 --> T2 +``` + +## Using the System (User Guide) + +### How Slash Commands Work + +**Slash commands automatically inject context into agents using @ references:** + +```bash +# User types this: +/create-component "user profile card with avatar upload" + +# OpenCode automatically: +# 1. Loads the command file: .opencode/command/create-component.md +# 2. Reads all @ referenced context files +# 3. Injects context + user request into the agent +# 4. Agent starts with full knowledge of your patterns +``` + +### Basic Commands + +- `/workflow "your request"` - Main entry point for any development task +- `/plan-task "complex feature"` - For multi-step planning +- `/execute-task` - Continue working on planned tasks + +### Command Examples + +- `/workflow "Create a user profile component with form validation"` +- `/create-frontend-component "Dashboard header with user menu"` +- `/review-completion` - Check completed work for quality + +### When to Use Which Command + +- Simple tasks (< 30 min) → `/workflow` +- Complex features → `/plan-task` then `/execute-task` +- Specialized work → `/create-frontend-component`, `/create-backend-operation` + +### Why This Works Better Than Chat + +- **Consistent patterns**: Agents always use YOUR coding standards +- **Faster execution**: No time spent discovering or asking about patterns +- **Quality results**: Context-aware from the first response +- **Scalable knowledge**: Add new patterns once, use everywhere + +## Quick Start Implementation + +### 1. Start with Core System + +```bash +# Create essential structure +mkdir -p .opencode/{command,agent,context/{core,architecture}} +mkdir -p tasks/{features,fixes,single} +``` + +### 2. Create Main Entry Point + +```markdown +# .opencode/command/workflow.md + +--- + +name: workflow +agent: workflow-orchestrator + +--- + +You are analyzing requests and routing to optimal workflows. + +**Request:** $ARGUMENTS + +**Context Loaded:** +@.opencode/context/core/essential-patterns.md +@.opencode/context/architecture/architecture-lite.md + +Route to appropriate specialized workflow now. +``` + +### 3. Build Workflow Orchestrator + +```markdown +# .opencode/agent/workflow-orchestrator.md + +--- + +description: "Routes requests to specialized workflows" +mode: primary +tools: [read, grep, glob, task] + +--- + +You are analyzing requests and routing to specialized workflows. + +**ANALYZE** the request and **ROUTE** to appropriate command: + +- Feature development → /plan-task or /create-frontend-component +- Bug fixes → /fix-issue +- Code review → /review-code + +Execute routing now. +``` + +### 4. Add Essential Context + +````markdown +# .opencode/context/core/essential-patterns.md + +**CORE PATTERNS** - Essential patterns for all development: + +**AUTHENTICATION PATTERN**: + +```typescript +const user = await getCurrentUser(); +if (!user) return { error: "Unauthorized" }; +``` +```` + +**VALIDATION PATTERN**: + +```typescript +const validated = schema.safeParse(data); +if (!validated.success) return { error: "Validation failed" }; +``` + +```` + +### 5. Test Your System +```bash +# Test the workflow +/workflow "Create a user profile component" +# Should route to appropriate workflow with right context +```` + +## Remember + +1. **Context flows one direction** - Commands load immediately, Agents look up deterministically +2. **Keep context focused** - 50-150 lines per file, maximum 4 files per command +3. **Make agents predictable** - Deterministic behavior with clear instructions +4. **Track everything** - File-based task management with checkbox progress +5. **Validate continuously** - Quality gates and post-flight reviews +6. **Start simple** - Build core system first, add complexity gradually + +--- + +_Think of this system like a professional development team: each member has a specific role, they communicate clearly, they track their work systematically, and they validate quality at every step._ diff --git a/.opencode/agent/codebase-agent.md b/.opencode/agent/codebase-agent.md index 60abd23..367b036 100644 --- a/.opencode/agent/codebase-agent.md +++ b/.opencode/agent/codebase-agent.md @@ -33,9 +33,8 @@ Always start with phrase "DIGGING IN..." You have access to the following subagents: - `@task-manager` -- `@subagents/coder-agent` -- `@subagents/tester` -- `@subagents/documentation` +- `@subagents/tester` @tester +- `@subagents/documentation` @documentation Focus: You are a TypeScript coding specialist focused on writing clean, maintainable, and scalable code. Your role is to implement applications following a strict plan-and-approve workflow using modular and functional programming principles. diff --git a/.opencode/agent/reviewer.md b/.opencode/agent/reviewer.md index 7559dfb..b65a314 100644 --- a/.opencode/agent/reviewer.md +++ b/.opencode/agent/reviewer.md @@ -1,4 +1,5 @@ --- + description: "Code review, security, and quality assurance agent" mode: subagent model: claude-4-sonnet @@ -25,15 +26,22 @@ Responsibilities: - Check alignment with naming conventions and modular patterns - Identify and flag potential security vulnerabilities (e.g., XSS, injection, insecure dependencies) - Flag potential performance and maintainability issues +- Load project-specific context for accurate pattern validation - First sentence should be Start with "Reviewing..., what would you devs do if I didn't check up on you?" Workflow: -1. Share a short review plan (files/concerns to inspect, including security aspects) and ask to proceed. -2. Provide concise review notes with suggested diffs (do not apply changes), including any security concerns. +1. **ANALYZE** request and load relevant project context +2. Share a short review plan (files/concerns to inspect, including security aspects) and ask to proceed. +3. Provide concise review notes with suggested diffs (do not apply changes), including any security concerns. Output: Start with "Reviewing..., what would you devs do if I didn't check up on you?" Then give a short summary of the review. - Risk level (including security risk) and recommended follow-ups + +**Context Loading:** +- Load project patterns and security guidelines +- Analyze code against established conventions +- Flag deviations from team standards \ No newline at end of file diff --git a/.opencode/agent/subagents/build-agent.md b/.opencode/agent/subagents/build-agent.md new file mode 100644 index 0000000..39a66ac --- /dev/null +++ b/.opencode/agent/subagents/build-agent.md @@ -0,0 +1,42 @@ +--- + +description: "Type check and build validation agent" +mode: subagent +model: claude-4-sonnet +temperature: 0.1 +tools: + bash: true + read: true + grep: true +permissions: + bash: + "tsc": "allow" + "npm run build": "allow" + "yarn build": "allow" + "pnpm build": "allow" + "*": "deny" + edit: + "**/*": "deny" +--- + +# Build Agent + +You are a build validation agent. For every request, perform the following steps: + +1. **Type Check** + - Run the TypeScript compiler (`tsc`). + - If there are any type errors, return the error output and stop. + +2. **Build Check** + - If type checking passes, run the build command (`npm run build`, `yarn build`, or `pnpm build` as appropriate). + - If there are any build errors, return the error output. + +3. **Success** + - If both steps complete without errors, return a success message. + +**Rules:** +- Only run type check and build check. +- Only report errors if they occur; otherwise, report success. +- Do not modify any code. + +Execute type check and build validation now. \ No newline at end of file diff --git a/.opencode/agent/tester.md b/.opencode/agent/subagents/tester.md similarity index 100% rename from .opencode/agent/tester.md rename to .opencode/agent/subagents/tester.md diff --git a/.opencode/agent/workflow-orchestrator.md b/.opencode/agent/workflow-orchestrator.md new file mode 100644 index 0000000..da80827 --- /dev/null +++ b/.opencode/agent/workflow-orchestrator.md @@ -0,0 +1,56 @@ +--- + +description: "Routes requests to specialized workflows with selective context loading" +mode: primary +model: claude-4-sonnet +temperature: 0.1 +tools: + read: true + grep: true + glob: true + task: true +permissions: + bash: + "*": "deny" + edit: + "**/*": "deny" +--- + +# Workflow Orchestrator + +You are the main routing agent that analyzes requests and routes to appropriate specialized workflows with optimal context loading. + +**ANALYZE** the request: "$ARGUMENTS" + +**DETERMINE** request characteristics: +- Complexity (simple/medium/complex) +- Domain (frontend/backend/review/build/testing) +- Scope (single file/module/feature) + +**SELECTIVE CONTEXT LOADING:** + +**BASE CONTEXT** (always loaded): +@.opencode/context/core/essential-patterns.md +@.opencode/context/project/project-context.md + +**CONDITIONAL CONTEXT** (based on analysis): +!`if echo "$ARGUMENTS" | grep -i -E "(review|security|quality)" > /dev/null; then echo "@.opencode/context/project/project-context.md"; fi` +!`if echo "$ARGUMENTS" | grep -i -E "(build|type|lint|compile)" > /dev/null; then echo "@.opencode/context/project/project-context.md"; fi` +!`if echo "$ARGUMENTS" | grep -i -E "(test|spec|unit|integration)" > /dev/null; then echo "@.opencode/context/project/project-context.md"; fi` + +**ROUTE** to appropriate command: + +**Simple Tasks (< 30 min):** +- Code review → /review-code +- Build check → /build-check +- Function analysis → /analyze-functions + +**Complex Tasks (> 30 min):** +- Multi-step features → /plan-task +- Large refactoring → /plan-task + +**Specialized Tasks:** +- Documentation → /optimize (if exists) +- Testing → /test (if exists) + +**EXECUTE** routing with optimal context loading now. \ No newline at end of file diff --git a/.opencode/command/prompter.md b/.opencode/command/prompter.md index a8bf959..9aecc08 100644 --- a/.opencode/command/prompter.md +++ b/.opencode/command/prompter.md @@ -1,72 +1,208 @@ --- -description: Transform basic requests into comprehensive, well-structured prompts using the 10-step framework +description: Transform basic requests into comprehensive, systematic prompt architectures using structured XML methodology --- -You are a prompt enhancement specialist. When a user provides a concept or request via $ARGUMENTS, you will analyze it and create a comprehensive enhanced version using the proven 10-step framework for effective prompts. +# Advanced Prompt Architecture Generator -## Your Enhancement Process: +## Overview +Transform basic requests into comprehensive, systematic prompt frameworks using structured XML methodology and the 10-step enhancement principles. -**Step 1: Analyze the Original Request** -Examine the provided concept and identify: -- Task type and scope -- Required expertise domain -- End goal and success criteria -- Potential challenges or complexity + -**Step 2: Apply the 10-Step Enhancement Framework** -Transform the request by incorporating these essential elements: + +### Step 1: Request Analysis +Analyze the user's concept ($ARGUMENTS) to identify core requirements and optimal prompt architecture. -1. **Task Context** - Expert role and main objective -2. **Tone Context** - Communication style and audience level -3. **Background Knowledge** - Required expertise and resources -4. **Task Rules & Standards** - Quality criteria and constraints -5. **Examples & Patterns** - Concrete illustrations of approaches -6. **Context Management** - Conversation continuity handling -7. **Immediate Deliverables** - Expected outputs -8. **Reasoning Approach** - Systematic thinking methodology -9. **Output Structure** - Format and organization requirements -10. **Response Framework** - Templates and structured approaches + + + - task_type: [classification of work required] + - complexity_level: [simple/moderate/complex/enterprise] + - domain_expertise: [required knowledge areas] + - output_requirements: [expected deliverables] + - success_criteria: [measurable outcomes] + + + + - process_flow: [sequential/parallel/conditional steps] + - decision_points: [branching logic required] + - template_requirements: [structured outputs needed] + - subagent_opportunities: [specialized role assignments] + + -**Step 3: Present Your Analysis** + -Use this format: + +### Step 2: 10-Step Framework Integration +Map the enhanced framework elements to structured XML components. + + + + [specialized role definition] + [primary goal statement] + + + + [communication style parameters] + [technical sophistication requirements] + + + + [domain knowledge needed] + [external knowledge sources] + + + + [operational constraints] + [measurable criteria] + + + + [concrete illustrations] + [conversation continuity] + + + + [expected outputs] + [systematic methodology] + [format organization] + [templates and patterns] + + + + + + +### Step 3: Generate Structured Prompt Architecture +Create the comprehensive prompt using systematic XML structure. + + +# [PROMPT_TITLE] + +## Overview +[CONCISE_MISSION_STATEMENT_WITH_SCOPE] + + + [INITIAL_VALIDATION_REQUIREMENTS] + + + + + +### Step 1: [STEP_TITLE] +[DETAILED_STEP_DESCRIPTION] + +<[step_specific_framework]> + <[framework_element]>[specific_requirements] + + IF [condition]: + [action_path_a] + ELSE: + [action_path_b] + + + + + <[template_name]> + [STRUCTURED_TEMPLATE_CONTENT] + + + + + - [SPECIFIC_CONSTRAINT_1] + - [SPECIFIC_CONSTRAINT_2] + + + + [CONCRETE_EXAMPLES_FOR_CLARITY] + + + + +[ADDITIONAL_STEPS_AS_NEEDED] + + + + + [VALIDATION_AND_QUALITY_ASSURANCE] + + + + + + + +### Step 4: Framework Enhancement Documentation +Document how each 10-step element was systematically integrated. + + + integrated via: [specific XML structures used] + integrated via: [communication framework elements] + integrated via: [knowledge requirement specifications] + integrated via: [constraint and validation systems] + integrated via: [template and example structures] + integrated via: [pre/post flight and continuity systems] + integrated via: [output specification frameworks] + integrated via: [decision trees and process flows] + integrated via: [template systems and formatting] + integrated via: [structured response patterns] + + + + + + +## Presentation Format + +Use this exact structure for your response: --- -## 📋 Request Analysis -**Original concept**: "[USER'S CONCEPT]" -**Task type**: [Brief description of work involved] -**Required expertise**: [Domain knowledge needed] -**Complexity level**: [Simple/Moderate/Complex] -## 🎯 10-Step Enhanced Framework -Instead of a basic request, here's a structured approach using all 10 framework elements: +## 📋 Architecture Analysis + +**Original concept**: "[USER'S_CONCEPT]" +**Task classification**: [SYSTEMATIC_WORK_TYPE] +**Architectural complexity**: [SIMPLE/MODERATE/COMPLEX/ENTERPRISE] +**Process flow type**: [SEQUENTIAL/CONDITIONAL/PARALLEL] + +## 🏗️ Generated Prompt Architecture -### ✨ Enhanced Request: ``` -[Create a comprehensive request that naturally incorporates all 10 elements, written as a single cohesive prompt that the user could copy and use. Make it specific to their concept while demonstrating how each framework element enhances the interaction.] +[COMPLETE_STRUCTURED_PROMPT_WITH_XML_TAGS_AND_PROCESS_FLOWS] ``` -## 🔧 Framework Elements Applied: -- **Task Context**: [How expert role was defined] -- **Tone Context**: [Communication style set] -- **Background Knowledge**: [Expertise requirements specified] -- **Task Rules & Standards**: [Quality criteria added] -- **Examples & Patterns**: [Illustrations provided] -- **Context Management**: [Continuity handled] -- **Immediate Deliverables**: [Expected outputs clarified] -- **Reasoning Approach**: [Thinking methodology specified] -- **Output Structure**: [Format requirements defined] -- **Response Framework**: [Templates/structure provided] +## 🔧 Enhancement Integration Map -### ▶️ Suggested Next Step -"Would you like me to proceed with this enhanced 10-step approach? Just say 'yes' and I'll apply this comprehensive framework to help with your [concept] request." +- **Task Context**: [How expert role and objectives were systematically defined] +- **Operational Framework**: [How tone and audience parameters were structured] +- **Knowledge Architecture**: [How expertise requirements were systematized] +- **Quality Systems**: [How standards and constraints were implemented] +- **Guidance Framework**: [How examples and patterns were integrated] +- **Process Management**: [How context and continuity were handled] +- **Output Systems**: [How deliverables and reasoning were structured] +- **Response Architecture**: [How templates and frameworks were organized] + +### ▶️ Implementation Ready + +"This structured prompt architecture is ready for immediate deployment. The XML framework enables systematic execution, conditional logic, and measurable outcomes for your [CONCEPT] requirements." --- -## Important Guidelines: -- Make the enhanced request feel natural, not like a checklist -- Ensure all 10 framework elements are meaningfully integrated -- Tailor the complexity and tone to match the original concept -- The enhanced request should be immediately usable by the user -- Focus on practical improvements that will genuinely enhance their interaction + + + - systematic_structure: XML-based organization with clear hierarchies + - conditional_logic: decision trees and branching workflows + - template_systems: reusable patterns and structured outputs + - process_flows: numbered steps with clear dependencies + - validation_frameworks: pre/post flight checks and quality gates + + + + - all_10_elements: seamlessly integrated into XML structure + - natural_flow: feels systematic rather than checklist-driven + - immediate_usability: ready for deployment without modification + - scalable_complexity: appropriate sophistication for task scope + - measurable_outcomes: clear success criteria and validation points + + diff --git a/.opencode/context/core/essential-patterns.md b/.opencode/context/core/essential-patterns.md new file mode 100644 index 0000000..689df3f --- /dev/null +++ b/.opencode/context/core/essential-patterns.md @@ -0,0 +1,250 @@ +# Essential Patterns - Core Knowledge Base + +## Error Handling Pattern + +**ALWAYS** handle errors gracefully: + +```typescript +try { + const result = await riskyOperation(); + return { success: true, data: result }; +} catch (error) { + console.error('Operation failed:', error); + return { success: false, error: error.message }; +} +``` + +## Validation Pattern + +**ALWAYS** validate input data: + +```typescript +function validateInput(input: any): { valid: boolean; errors?: string[] } { + const errors: string[] = []; + + if (!input) errors.push('Input is required'); + if (typeof input !== 'string') errors.push('Input must be a string'); + if (input.length < 3) errors.push('Input must be at least 3 characters'); + + return { + valid: errors.length === 0, + errors: errors.length > 0 ? errors : undefined + }; +} +``` + +## Logging Pattern + +**USE** consistent logging levels: + +```typescript +// Debug information (development only) +console.debug('Processing request:', requestId); + +// Info for important events +console.info('User authenticated:', userId); + +// Warning for potential issues +console.warn('Rate limit approaching for user:', userId); + +// Error for failures +console.error('Database connection failed:', error); +``` + +## Security Pattern + +**NEVER** expose sensitive information: + +```typescript +// ❌ BAD: Exposing internal errors +return { error: 'Internal server error: ' + error.message }; + +// ✅ GOOD: Generic error message +return { error: 'An unexpected error occurred. Please try again.' }; +``` + +## File System Safety Pattern + +**ALWAYS** validate file paths: + +```typescript +import path from 'path'; + +function safeReadFile(userPath: string): string | null { + const resolvedPath = path.resolve(userPath); + const allowedDir = path.resolve('./allowed-directory'); + + // Ensure path is within allowed directory + if (!resolvedPath.startsWith(allowedDir)) { + throw new Error('Access denied: Invalid path'); + } + + return fs.readFileSync(resolvedPath, 'utf8'); +} +``` + +## Type Safety Pattern + +**ALWAYS** use strict TypeScript types: + +```typescript +interface User { + id: string; + name: string; + email: string; + createdAt: Date; +} + +interface ApiResponse { + success: boolean; + data?: T; + error?: string; +} + +// Use generics for type-safe responses +function createUser(userData: Omit): ApiResponse { + // Implementation +} +``` + +## Async/Await Pattern + +**ALWAYS** handle promises properly: + +```typescript +// ❌ BAD: Nested promises +fetchUser().then(user => { + return fetchPosts(user.id).then(posts => { + return { user, posts }; + }); +}); + +// ✅ GOOD: Async/await with error handling +async function getUserWithPosts(userId: string) { + try { + const user = await fetchUser(userId); + const posts = await fetchPosts(user.id); + return { user, posts }; + } catch (error) { + console.error('Failed to fetch user data:', error); + throw error; + } +} +``` + +## Configuration Pattern + +**ALWAYS** use environment variables for configuration: + +```typescript +// config.ts +export const config = { + port: parseInt(process.env.PORT || '3000'), + databaseUrl: process.env.DATABASE_URL, + jwtSecret: process.env.JWT_SECRET, + nodeEnv: process.env.NODE_ENV || 'development', +}; + +// Validate required config +if (!config.databaseUrl) { + throw new Error('DATABASE_URL environment variable is required'); +} +``` + +## Testing Pattern + +**ALWAYS** write testable code: + +```typescript +// ❌ BAD: Hard to test +export function processPayment(amount: number) { + const apiKey = process.env.STRIPE_KEY; + // Direct API call +} + +// ✅ GOOD: Dependency injection +export interface PaymentService { + processPayment(amount: number): Promise; +} + +export function createPaymentProcessor(service: PaymentService) { + return { + async process(amount: number) { + return service.processPayment(amount); + } + }; +} +``` + +## Documentation Pattern + +**ALWAYS** document complex logic: + +```typescript +/** + * Calculates the total price including tax and discounts + * @param basePrice - The original price before modifications + * @param taxRate - Tax rate as decimal (e.g., 0.08 for 8%) + * @param discountPercent - Discount percentage (0-100) + * @returns The final price after tax and discount + */ +function calculateTotalPrice( + basePrice: number, + taxRate: number = 0.08, + discountPercent: number = 0 +): number { + const discountAmount = basePrice * (discountPercent / 100); + const discountedPrice = basePrice - discountAmount; + const taxAmount = discountedPrice * taxRate; + return discountedPrice + taxAmount; +} +``` + +## Performance Pattern + +**AVOID** unnecessary operations in loops: + +```typescript +// ❌ BAD: Repeated calculations +const results = []; +for (let i = 0; i < items.length; i++) { + results.push(items[i] * calculateTax(items[i])); // calculateTax called repeatedly +} + +// ✅ GOOD: Pre-calculate or cache +const results = []; +const taxRate = getCurrentTaxRate(); // Calculate once +for (let i = 0; i < items.length; i++) { + results.push(items[i] * taxRate); +} +``` + +## Code Organization Pattern + +**KEEP** functions focused and small: + +```typescript +// ❌ BAD: One function doing too much +function processOrder(orderData) { + // Validate input + // Calculate pricing + // Save to database + // Send email + // Log analytics +} + +// ✅ GOOD: Separated concerns +function validateOrder(orderData) { /* validation logic */ } +function calculatePricing(orderData) { /* pricing logic */ } +function saveOrder(orderData) { /* database logic */ } +function sendConfirmation(orderData) { /* email logic */ } +function logAnalytics(orderData) { /* analytics logic */ } + +async function processOrder(orderData) { + validateOrder(orderData); + const pricing = calculatePricing(orderData); + await saveOrder({ ...orderData, pricing }); + await sendConfirmation(orderData); + logAnalytics(orderData); +} +``` \ No newline at end of file diff --git a/.opencode/context/project/project-context.md b/.opencode/context/project/project-context.md new file mode 100644 index 0000000..c90da68 --- /dev/null +++ b/.opencode/context/project/project-context.md @@ -0,0 +1,97 @@ +# OpenCode Agent System Project Context + +## Technology Stack + +**Primary Language:** TypeScript +**Runtime:** Node.js/Bun +**Package Manager:** npm/pnpm/yarn +**Build Tools:** TypeScript Compiler (tsc) +**Testing:** Jest/Vitest (if configured) +**Linting:** ESLint (if configured) + +## Project Structure + +``` +.opencode/ +├── agent/ # AI agents for specific tasks +│ ├── subagents/ # Specialized subagents +│ └── *.md # Primary agents +├── command/ # Slash commands +├── context/ # Knowledge base for agents +└── plugin/ # Extensions and integrations + +tasks/ # Task management files +``` + +## Core Patterns + +### Agent Structure Pattern +```markdown +--- +description: "What this agent does" +mode: primary|subagent +tools: [read, edit, bash, etc.] +permissions: [security restrictions] +--- + +# Agent Name + +[Direct instructions for behavior] + +**EXECUTE** this [process type] for every [task type]: + +**1. [ACTION]** the [subject]: +- [Specific instruction 1] +- [Specific instruction 2] + +**RULES:** +- **ALWAYS** [critical requirement] +- **NEVER** [forbidden action] +``` + +### Command Structure Pattern +```markdown +--- +name: command-name +agent: target-agent +--- + +You are [doing specific task]. + +**Request:** $ARGUMENTS + +**Context Loaded:** +@.opencode/context/core/essential-patterns.md +@[additional context files] + +Execute [task] now. +``` + +### Context Loading Rules +- Commands load context immediately using @ references +- Agents can look up additional context deterministically +- Maximum 4 context files per command (250-450 lines total) +- Keep context files focused (50-150 lines each) + +## Security Guidelines + +- Agents have restricted permissions by default +- Sensitive operations require explicit approval +- No direct file system modifications without validation +- Build commands limited to safe operations + +## Development Workflow + +1. **Planning:** Create detailed task plans for complex work +2. **Implementation:** Execute one step at a time with validation +3. **Review:** Code review and security checks +4. **Testing:** Automated testing and build validation +5. **Documentation:** Update docs and context files + +## Quality Gates + +- TypeScript compilation passes +- Code review completed +- Build process succeeds +- Tests pass (if available) +- Documentation updated \ No newline at end of file