claude-code-vertical/skills/oracle/SKILL.md

---
name: oracle-planner
description: Codex 5.2 planning specialist using oracle CLI + llmjunky's proven prompt patterns. Call when planning is complex or requires structured breakdown.
model: opus
---

# Oracle Planner - Codex Planning Specialist

Leverage oracle CLI with Codex 5.2 for deep, structured planning. Uses llmjunky's battle-tested prompt patterns.

## When to Call Me

- Complex features needing careful breakdown
- Multi-phase implementations
- Unclear dependency graphs
- Parallel task identification needed
- Architecture decisions
- Migration plans
- Any planning where you need ~10min+ of deep thinking

## Prerequisites

Oracle CLI must be installed:
```bash
npm install -g @steipete/oracle
```

Reference: skill-index/skills/oracle/SKILL.md for oracle CLI best practices

## How I Work

1. **Planner gathers context** - uses AskUserTool for clarifying questions
2. **Planner crafts perfect prompt** - following templates below
3. **Planner calls oracle** - via CLI with full context
4. **Oracle outputs plan.md** - structured breakdown from Codex 5.2
5. **Planner transforms** - plan.md → spec yamls

## Calling Oracle (Exact Commands)

**1. Preview first (no tokens spent):**
```bash
npx -y @steipete/oracle --dry-run summary --files-report \
  -p "$(cat /tmp/oracle-prompt.txt)" \
  --file "src/**" \
  --file "!**/*.test.*" \
  --file "!**/*.snap"
```
Check token count (target: <196k tokens). If over budget, narrow files.

**2. Run with browser engine (main path):**
```bash
npx -y @steipete/oracle \
  --engine browser \
  --model gpt-5.2-codex \
  --slug "vertical-plan-$(date +%Y%m%d-%H%M)" \
  -p "$(cat /tmp/oracle-prompt.txt)" \
  --file "src/**" \
  --file "convex/**" \
  --file "!**/*.test.*" \
  --file "!**/*.snap" \
  --file "!node_modules" \
  --file "!dist"
```

**Why browser engine?**
- GPT-5.2 Codex runs take 10-60 minutes (normal)
- Browser mode handles long runs + reattach
- Sessions stored in `~/.oracle/sessions`

**3. Check status (if run detached):**
```bash
npx -y @steipete/oracle status --hours 1
```

**4. Reattach to session:**
```bash
npx -y @steipete/oracle session <session-id> --render > /tmp/oracle-plan-result.txt
```

**Important:**
- Don't re-run if timeout - reattach instead
- Use `--force` only if you truly want a duplicate run
- Files >1MB are rejected (split or narrow match)
- Default-ignored: node_modules, dist, coverage, .git, .next, build, tmp

## Prompt Template

Use this EXACT structure when crafting my prompt:

```
Create a detailed implementation plan for [TASK].

## Requirements
[List ALL requirements gathered from user]
- [Requirement 1]
- [Requirement 2]
- Features needed:
  - [Feature A]
  - [Feature B]
- NOT needed: [Explicitly state what's out of scope]

## Plan Structure

Use this template structure:

```markdown
# Plan: [Task Name]

**Generated**: [Date]
**Estimated Complexity**: [Low/Medium/High]

## Overview
[Brief summary of what needs to be done and the general approach, including recommended libraries/tools]

## Prerequisites
- [Dependencies or requirements that must be met first]
- [Tools, libraries, or access needed]

## Phase 1: [Phase Name]
**Goal**: [What this phase accomplishes]

### Task 1.1: [Task Name]
- **Location**: [File paths or components involved]
- **Description**: [What needs to be done]
- **Dependencies**: [Task IDs this depends on, e.g., "None" or "1.2, 2.1"]
- **Complexity**: [1-10]
- **Test-First Approach**:
  - [Test to write before implementation]
  - [What the test should verify]
- **Acceptance Criteria**:
  - [Specific, testable criteria]

### Task 1.2: [Task Name]
[Same structure...]

## Phase 2: [Phase Name]
[...]

## Testing Strategy
- **Unit Tests**: [What to unit test, frameworks to use]
- **Integration Tests**: [API/service integration tests]
- **E2E Tests**: [Critical user flows to test end-to-end]
- **Test Coverage Goals**: [Target coverage percentage]

## Dependency Graph
[Show which tasks can run in parallel vs which must be sequential]
- Tasks with no dependencies: [list - these can start immediately]
- Task dependency chains: [show critical path]

## Potential Risks
- [Things that could go wrong]
- [Mitigation strategies]

## Rollback Plan
- [How to undo changes if needed]
```

### Task Guidelines
Each task must:
- Be specific and actionable (not vague)
- Have clear inputs and outputs
- Be independently testable
- Include file paths and specific code locations
- Include dependencies so parallel execution is possible
- Include complexity score (1-10)

Break large tasks into smaller ones:
- ✗ Bad: "Implement Google OAuth"
- ✓ Good:
  - "Add Google OAuth config to environment variables"
  - "Install and configure passport-google-oauth20 package"
  - "Create OAuth callback route handler in src/routes/auth.ts"
  - "Add Google sign-in button to login UI"
  - "Write integration tests for OAuth flow"

## Instructions
- Write the complete plan to a file called `plan.md` in the current directory
- Do NOT ask any clarifying questions - you have all the information needed
- Be specific and actionable - include code snippets where helpful
- Follow test-driven development: specify what tests to write BEFORE implementation for each task
- Identify task dependencies so parallel work is possible
- Just write the plan and save the file

Begin immediately.
```

## Clarifying Question Patterns

Before calling me, gather context with these question types:

### For "implement auth"
- What authentication methods do you need? (email/password, OAuth providers like Google/GitHub, SSO, magic links)
- Do you need role-based access control (RBAC) or just authenticated/unauthenticated?
- What's your backend stack? (Node/Express, Python/Django, etc.)
- Where will you store user credentials/sessions? (Database, Redis, JWT stateless)
- Do you need features like: password reset, email verification, 2FA?
- Any compliance requirements? (SOC2, GDPR, HIPAA)

### For "build an API"
- What resources/entities does this API need to manage?
- REST or GraphQL?
- What authentication will the API use?
- Expected scale/traffic?
- Do you need rate limiting, caching, versioning?

### For "migrate to microservices"
- Which parts of the monolith are you migrating first?
- What's your deployment target? (K8s, ECS, etc.)
- How will services communicate? (REST, gRPC, message queues)
- What's your timeline and team capacity?

### For "add testing"
- What testing levels do you need? (unit, integration, e2e)
- What's your current test coverage?
- What frameworks do you prefer or already use?
- What's the most critical functionality to test first?

### For "performance optimization"
- What specific performance issues are you seeing?
- Current metrics (load time, response time, throughput)?
- What's the target performance?
- Where are the bottlenecks? (DB queries, API calls, rendering)
- What profiling have you done?

### For "database migration"
- What's the source and target database?
- How much data needs to be migrated?
- Can you afford downtime? If so, how much?
- Do you need dual-write/read during migration?
- What's your rollback strategy?

## Example Prompt (Auth)

**After gathering:**
- Methods: Email/password + Google OAuth
- Stack: Next.js + Prisma + PostgreSQL
- Roles: Admin/User
- Features: Password reset, email verification
- No 2FA, no special compliance

**Prompt to send me:**

```
Create a detailed implementation plan for adding authentication to a Next.js web application.

## Requirements
- Authentication methods: Email/password + Google OAuth
- Framework: Next.js (App Router)
- Database: PostgreSQL with Prisma ORM
- Role-based access: Admin and User roles
- Features needed:
  - User registration and login
  - Password reset flow
  - Email verification
  - Google OAuth integration
  - Session management
- NOT needed: 2FA, SSO, special compliance

## Plan Structure
[Use the full template above]

## Instructions
- Write the complete plan to a file called `plan.md` in the current directory
- Do NOT ask any clarifying questions - you have all the information needed
- Be specific and actionable - include code snippets where helpful
- Follow test-driven development: specify what tests to write BEFORE implementation for each task
- Identify task dependencies so parallel work is possible
- Just write the plan and save the file

Begin immediately.
```

## Important Notes

- **I only output plan.md** - you transform it into spec yamls
- **No interaction** - one-shot execution with full context
- **Always gpt-5.2-codex + xhigh** - this is my configuration
- **File output: plan.md** in current directory
- **Parallel tasks identified** - I explicitly list dependencies

## After I Run

1. Read `plan.md`
2. Transform phases/tasks into spec yamls
3. Map tasks to weavers
4. Hand off to orchestrator