spec scheme 2 + oracle skill

This commit is contained in:
Rathi Harivansh 2026-01-19 16:29:06 +00:00
parent df11c2b826
commit 593bdb8208
2 changed files with 504 additions and 0 deletions

218
docs/spec-schema-v2.md Normal file
View file

@ -0,0 +1,218 @@
# Spec Schema v2
Enhanced spec format incorporating learnings from agent workflows + oracle planning patterns.
## Full Schema
```yaml
# === METADATA ===
name: feature-name # Short identifier (no spaces)
description: | # What this PR accomplishes
Multi-line description of what this spec implements.
Should be clear to someone reviewing the PR.
# === ATOMICITY ===
atomic: true # REQUIRED: Each spec = one commit
complexity: 3 # 1-10 scale (for orchestrator scheduling)
estimated_minutes: 45 # Rough estimate (helps parallel scheduling)
# === DEMO & SPRINT CONTEXT ===
demo_goal: | # What this makes demoable at sprint level
User can now authenticate with Google OAuth and see their profile.
sprint_checkpoint: true # Is this a sprint demo milestone?
# === SKILLS ===
skill_hints: # Orchestrator matches to skill-index
- typescript-patterns
- react-testing
- security-best-practices
# === BUILDING ===
building_spec:
requirements: # What to build (specific, technical)
- Add Google OAuth button to login page
- Create /api/auth/google/callback route
- Store OAuth tokens in Prisma database
- Add GoogleUser type to schema
constraints: # Rules to follow
- Must use existing AuthContext pattern
- No direct database access (use Prisma only)
- Follow existing error handling patterns
- Keep bundle size <5kb increase
files: # Where code lives (helps weaver focus)
- src/components/auth/GoogleButton.tsx
- src/pages/api/auth/google/**
- prisma/schema.prisma
dependencies: # Task IDs this depends on
- auth-01-schema # Must complete before this
test_first: # OPTIONAL: Write tests before implementation
- test: "Google button redirects to OAuth URL"
file: "src/components/auth/__tests__/GoogleButton.test.tsx"
- test: "Callback route exchanges code for token"
file: "src/pages/api/auth/google/__tests__/callback.test.ts"
# === VERIFICATION ===
verification_spec:
# Deterministic checks first
- type: command
name: "typecheck"
run: "npm run typecheck"
expect: exit_code 0
- type: command
name: "tests"
run: "npm test -- google"
expect: exit_code 0
- type: file-contains
path: "src/components/auth/GoogleButton.tsx"
pattern: "window.location.href.*google.*oauth"
reason: "OAuth redirect must be implemented"
- type: file-not-contains
path: "src/"
pattern: "console.log.*token"
reason: "No token logging in production"
# Test-first validation (if specified)
- type: test-first-check
description: "Verify tests were written before implementation"
test_files:
- "src/components/auth/__tests__/GoogleButton.test.tsx"
- "src/pages/api/auth/google/__tests__/callback.test.ts"
# Agent-based checks (last, non-deterministic)
- type: agent
name: "security-review"
prompt: |
Review OAuth implementation for security:
1. No client secret exposed to frontend
2. PKCE code_verifier generated securely
3. State parameter validated (CSRF protection)
4. Tokens stored server-side only
Report PASS/FAIL with evidence.
# Demo validation (for sprint checkpoints)
- type: demo
name: "google-oauth-flow"
description: "Manual verification of OAuth flow"
steps:
- "npm run dev"
- "Navigate to /login"
- "Click 'Sign in with Google'"
- "Complete OAuth flow in popup"
- "Verify: redirected to dashboard with user profile"
acceptance: "User can complete full OAuth flow without errors"
# === REVIEW (before weaver execution) ===
review_spec:
type: subagent # Spawn reviewer before building
model: opus # Review uses Opus
prompt: |
Review this spec for quality before building:
Check:
1. Is each requirement atomic (one commit)?
2. Are tests defined clearly (or validation method)?
3. Are dependencies identified?
4. Is demo goal clear and testable?
5. Are constraints specific (not vague)?
Report PASS or FAIL with specific issues.
accept_criteria:
- "Requirements are atomic and specific"
- "Tests or validation method defined"
- "Dependencies identified (or none)"
- "Demo goal is testable"
# === PR METADATA ===
pr:
branch: auth/03-google-oauth
base: auth/02-password # Stacked on previous spec
title: "feat(auth): add Google OAuth login"
labels: # GitHub PR labels
- auth
- security
reviewers: # Optional: auto-assign reviewers
- security-team
```
## Key Changes from v1
### Added Fields
1. **`atomic: true`** - Enforces one-commit rule
2. **`complexity: 1-10`** - Helps orchestrator schedule parallel work
3. **`estimated_minutes`** - Rough time estimate
4. **`demo_goal`** - Sprint-level demoable outcome
5. **`sprint_checkpoint: true`** - Marks sprint milestones
6. **`dependencies`** - Explicit task IDs (not just PR base)
7. **`test_first`** - Write tests before implementation
8. **`review_spec`** - Subagent reviews spec before building
### Enhanced Sections
#### `verification_spec` additions:
- **`test-first-check`** - Validates tests exist
- **`demo`** type - Manual verification with steps
- **`name`** + **`reason`** fields for clarity
#### `building_spec` additions:
- **`test_first`** - List tests to write first
- **`dependencies`** - Task IDs (separate from PR stacking)
### Validation Types
```yaml
validation_type: "tests" # Default: automated tests
validation_type: "manual" # Visual/UX verification
validation_type: "demo" # Sprint checkpoint demo
validation_type: "benchmark" # Performance validation
```
## Usage in Vertical
### Planner Flow
1. **Gather requirements** (AskUserTool)
2. **Call oracle** with full context
3. **Oracle outputs** plan.md (following this schema)
4. **Planner transforms** plan.md tasks → spec yamls
5. **Review subagent** validates each spec
6. **Orchestrator executes** validated specs
### Orchestrator Scheduling
Uses new fields for smart scheduling:
- **`complexity`** - balance heavy/light tasks
- **`estimated_minutes`** - predict completion
- **`dependencies`** - build execution graph
- **`atomic: true`** - enforce one-commit rule
### Weaver Execution
1. Read spec (all fields)
2. If `test_first` exists, write tests first
3. Implement `building_spec.requirements`
4. Run `verification_spec` checks in order
5. If `demo` type exists, prompt human for manual verification
6. Create PR only after all checks pass
## Migration from v1
Old specs still work. New fields are optional except:
- **`atomic: true`** - should be added to all specs
- **`demo_goal`** - required for sprint checkpoints
## Examples
See:
- `examples/auth-google-oauth.yaml` - Full example above
- `examples/simple-bugfix.yaml` - Minimal spec (no test-first, no demo)
- `examples/sprint-milestone.yaml` - Sprint checkpoint with demo validation

286
skills/oracle/SKILL.md Normal file
View file

@ -0,0 +1,286 @@
---
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