OpenAgentsControl/plugins/claude-code/skills/using-oac/SKILL.md

---

name: using-oac

description: OpenAgents Control workflow for context-aware development. Auto-invokes on every task to ensure proper context discovery, planning, and execution with approval gates.

OpenAgents Control (OAC) Workflow

Purpose: Guide Claude through context-aware development using the 6-stage OAC workflow.

When to use: Automatically invoked for every development task to ensure proper context discovery, planning, and validation.

---

6-Stage Workflow

Execute these stages in order for every development task:

Stage 1: Analyze & Discover

Goal: Understand the task and discover relevant context files.

Actions:

1. Analyze the user's request to understand:

   • What they want to build/change
   • Technical scope and complexity
   • Potential risks or dependencies

2. Invoke the /context-discovery skill to find relevant context files:

   • Coding standards and conventions
   • Architecture patterns
   • Security guidelines
   • Domain-specific guides

3. Capture the list of context files returned by ContextScout

Output: List of context files to load, understanding of task scope

---

Stage 2: Plan & Approve

Goal: Create an execution plan and get user approval before proceeding.

Actions:

1. Based on task complexity, create a plan:
   

Simple tasks (1-3 files, <30 min):

• Direct implementation approach
• List of files to create/modify
• Key technical decisions
  

Complex tasks (4+ files, >30 min):

• High-level breakdown into phases
• Dependencies between components
• Suggest using /task-breakdown skill for detailed subtasks

1. Present the plan to the user with:

   • Summary of approach
   • Files that will be created/modified
   • Context files that will be loaded
   • Estimated complexity

2. REQUEST APPROVAL - Wait for user confirmation before proceeding

Critical: NEVER proceed to Stage 3 without explicit user approval.

Output: Approved execution plan

---

Stage 3: LoadContext

Goal: Pre-load ALL discovered context files so they're available during execution.

Actions:

1. Read EVERY context file discovered in Stage 1:

   • Use the Read tool to load each file
   • Load files in priority order (Critical → High → Medium)
   • Example: If Stage 1 found 5 files, Stage 3 reads all 5
   • Important: Don't skip any files - load everything discovered

2. Internalize the loaded context:

   • Coding standards and patterns
   • Security requirements
   • Naming conventions
   • Architecture constraints
   • Project-specific conventions

Why This Matters: This stage prevents nested ContextScout calls during execution. By loading ALL context upfront, subagents invoked in Stage 4 can use the pre-loaded context without needing to call ContextScout themselves. This maintains the flattened delegation hierarchy required by Claude Code.

1. If external libraries are involved, invoke /external-scout to fetch current API docs:
   • Example: If using Drizzle ORM → /external-scout drizzle schemas
   • Example: If using React hooks → /external-scout react hooks
   • Load the cached documentation files returned by ExternalScout
   • Apply current API patterns from external docs

Output: All context loaded (internal + external) and ready for execution

---

Stage 4: Execute

Goal: Implement the solution following loaded context and standards.

Actions:

For Simple Tasks (direct execution):

1. Implement the solution directly:

   • Follow coding standards from loaded context
   • Apply security patterns
   • Use naming conventions
   • Create tests if required

2. Self-review before completion:

   • Verify all acceptance criteria met
   • Check for type errors or missing imports
   • Scan for debug artifacts (console.log, TODO, etc.)
   • Validate against loaded standards

For Complex Tasks (delegated execution):

1. Invoke /task-breakdown skill to create detailed subtasks:

   • TaskManager will create JSON task files
   • Each subtask will have clear acceptance criteria
   • Dependencies will be mapped

2. Execute subtasks in order:

   • Use /code-execution skill for implementation subtasks
   • Use /test-generation skill for test subtasks
   • Use /code-review skill for review subtasks

3. Track progress through subtask completion

Output: Implementation complete, all deliverables created

---

Stage 5: Validate

Goal: Verify the implementation works correctly.

Actions:

1. Run tests (if they exist):

   • Execute test suite
   • Check for failures
   • Verify coverage meets requirements

2. Validate against acceptance criteria:

   • Check each criterion from the plan
   • Verify all deliverables exist
   • Confirm standards were followed

3. STOP on failure:

   • If tests fail → fix issues before proceeding
   • If criteria unmet → complete implementation
   • If standards violated → refactor to comply

Critical: Do not proceed to Stage 6 if validation fails.

Output: Validated, working implementation

---

Stage 6: Complete

Goal: Finalize the task with documentation and cleanup.

Actions:

1. Update documentation (if needed):

   • Update README if new features added
   • Add inline documentation for complex logic
   • Update API docs if endpoints changed

2. Summarize what was done:

   • List files created/modified
   • Highlight key technical decisions
   • Note any follow-up tasks needed

3. Cleanup (if applicable):

   • Remove temporary files
   • Clean up debug code
   • Archive session files (for complex tasks)

4. Present completion summary to user

Output: Task complete, documented, and summarized

---

Key Principles

Flat Delegation Hierarchy

OAC Pattern (nested - NOT supported in Claude Code):

Main Agent → TaskManager → CoderAgent → ContextScout

Claude Code Pattern (flat - CORRECT):

Main Agent → ContextScout (via /context-discovery)
Main Agent → TaskManager (via /task-breakdown)
Main Agent → CoderAgent (via /code-execution)

Rule: Only the main agent can invoke subagents. Subagents cannot call other subagents.

Context Pre-Loading

Why: Prevents nested ContextScout calls during execution.

How: Stage 3 loads ALL context upfront, so execution stages (4-6) have everything they need.

Approval Gates

Critical checkpoints:

• Stage 2 → Stage 3: User must approve the plan
• Stage 5 → Stage 6: Validation must pass

Never skip approval - it prevents wasted work and ensures alignment.

Progressive Complexity

Simple tasks: Stages 1-2-3-4-5-6 executed inline by main agent

Complex tasks: Stages 1-2-3 by main agent, Stage 4 delegated to TaskManager + specialists

---

Skill Invocations

Use these skills at the appropriate stages:

Skill	When to Invoke	Purpose
/context-discovery	Stage 1	Find relevant context files
/external-scout	Stage 3	Fetch external library documentation
/task-breakdown	Stage 4 (complex tasks)	Create detailed subtasks
/code-execution	Stage 4 (subtasks)	Implement code subtasks
/test-generation	Stage 4 (subtasks)	Create test subtasks
/code-review	Stage 4 (subtasks)	Review code subtasks

---

Example Workflow

Simple Task: "Add email validation to user registration"

Stage 1: Analyze → Invoke /context-discovery → Get validation patterns, security standards

Stage 2: Plan → "Add email regex validation to registration endpoint" → Request approval

Stage 3: Load context → Read validation patterns, security standards

Stage 4: Execute → Implement validation, add tests, self-review

Stage 5: Validate → Run tests, verify criteria met

Stage 6: Complete → Update API docs, summarize changes

Complex Task: "Build user authentication system"

Stage 1: Analyze → Invoke /context-discovery → Get auth patterns, security standards, architecture guides

Stage 2: Plan → "Multi-phase: JWT service, middleware, endpoints, tests" → Request approval

Stage 3: Load context → Read all discovered context files

Stage 4: Execute → Invoke /task-breakdown → TaskManager creates subtasks → Execute subtasks using /code-execution, /test-generation, /code-review

Stage 5: Validate → Run full test suite, verify all acceptance criteria

Stage 6: Complete → Update docs, summarize implementation, archive session

---

Anti-Patterns to Avoid

❌ Skipping Stage 1 - Coding without context discovery leads to inconsistent patterns

❌ Skipping Stage 2 approval - Implementing without user buy-in wastes effort

❌ Nested subagent calls - Subagents calling other subagents (not supported in Claude Code)

❌ Context discovery during execution - Should be done in Stage 1, loaded in Stage 3

❌ Proceeding with failed validation - Stage 5 failures must be fixed before Stage 6

---

Session Management (Complex Tasks)

For complex tasks requiring TaskManager delegation:

Session Location: .tmp/sessions/{YYYY-MM-DD}-{task-slug}/

Session Files:

• context.md - Task context, discovered files, requirements
• progress.md - Execution progress tracking

Cleanup: After Stage 6, ask user if session files should be deleted

---

Related Skills

• context-discovery - Stage 1 context discovery
• external-scout - Stage 3 external library documentation
• task-breakdown - Stage 4 complex task delegation
• code-execution - Stage 4 code implementation
• test-generation - Stage 4 test creation
• code-review - Stage 4 code review

---

Success Criteria

✅ Every task follows all 6 stages in order

✅ Context discovered before execution

✅ User approval obtained before implementation

✅ All context pre-loaded (no nested discovery)

✅ Validation passes before completion

✅ Documentation updated and task summarized