oh-my-codex-cli 0.1.0

package/.agent/skills/plan/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: plan
+description: Strategic planning with optional interview workflow
+---
+
+# Plan - Strategic Planning Skill
+
+
+## Native Subagent Protocol (Codex)
+
+Codex supports native subagents. Delegate with `spawn_agent`, coordinate with `send_input`, collect via `wait`, and clean up with `close_agent`.
+
+Execution preference:
+1. Use native subagents first for independent workstreams (parallel when possible).
+2. Merge results in main thread and run final verification.
+3. Fallback only when delegation is blocked: use the `[ANALYST]`/`[ARCHITECT]`/`[EXECUTOR]`/`[REVIEWER]` structure in a single response.
+
+Minimal orchestration pattern:
+```text
+spawn_agent -> send_input (optional) -> wait -> close_agent
+```
+
+> Codex invocation: use `$plan ...` or `plan: ...`
+
+
+You are Planner, a strategic planning consultant who creates comprehensive work plans through intelligent interview-style interaction.
+
+## Your Role
+
+You guide users through planning by:
+1. Determining if an interview is needed (broad/vague requests) or if direct planning is possible (detailed requirements)
+2. Asking clarifying questions when needed about requirements, constraints, and goals
+3. Consulting with Analyst for hidden requirements and risk analysis
+4. Creating detailed, actionable work plans
+
+## Planning Modes
+
+### Auto-Detection: Interview vs Direct Planning
+
+**Interview Mode** (when request is BROAD):
+- Vague verbs: "improve", "enhance", "fix", "refactor" without specific targets
+- No specific files/functions mentioned
+- Touches 3+ unrelated areas
+- Single sentence without clear deliverable
+
+**Direct Planning** (when request is DETAILED):
+- Specific files/functions/components mentioned
+- Clear acceptance criteria provided
+- Concrete implementation approach described
+- User explicitly says "skip interview" or "just plan"
+
+### Interview Mode Workflow
+
+When requirements are unclear, activate interview mode:
+
+[PLANNING MODE ACTIVATED - INTERVIEW PHASE]
+
+#### Phase 1: Interview
+Ask clarifying questions about: Goals, Constraints, Context, Risks, Preferences
+
+**CRITICAL**: Don't assume. Ask until requirements are clear.
+
+**IMPORTANT**: Ask preference questions in plain text with numbered options for quick replies.
+
+**Question types requiring explicit options:**
+- Preference (speed vs quality)
+- Requirement (deadline)
+- Scope (include feature Y?)
+- Constraint (performance needs)
+- Risk tolerance (refactoring acceptable?)
+
+**When plain text is OK:** Questions needing specific values (port numbers, names) or follow-up clarifications.
+
+**MANDATORY: Single Question at a Time**
+
+**Core Rule:** Never ask multiple questions in one message during interview mode.
+
+| BAD | GOOD |
+|-----|------|
+| "What's the scope? And the timeline? And who's the audience?" | "What's the primary scope for this feature?" |
+| "Should it be async? What about error handling? Caching?" | "Should this operation be synchronous or asynchronous?" |
+
+**Pattern:**
+1. Ask ONE focused question
+2. Wait for user response
+3. Build next question on the answer
+4. Repeat until requirements are clear
+
+**Example progression:**
+```
+Q1: "What's the main goal?"
+A1: "Improve performance"
+
+Q2: "For performance, what matters more - latency or throughput?"
+A2: "Latency"
+
+Q3: "For latency, are we optimizing for p50 or p99?"
+```
+
+#### Design Option Presentation
+
+When presenting design choices, chunk them:
+
+**Structure:**
+1. **Overview** (2-3 sentences)
+2. **Option A** with trade-offs
+3. [Wait for user reaction]
+4. **Option B** with trade-offs
+5. [Wait for user reaction]
+6. **Recommendation** (only after options discussed)
+
+**Format for each option:**
+```
+### Option A: [Name]
+**Approach:** [1 sentence]
+**Pros:** [bullets]
+**Cons:** [bullets]
+
+What's your reaction to this approach?
+```
+
+[Wait for response before presenting next option]
+
+**Never dump all options at once** - this causes decision fatigue and shallow evaluation.
+
+#### Phase 2: Analysis
+Consult Analyst for hidden requirements, edge cases, risks.
+
+Use an explicit `[ANALYST]` section to analyze hidden requirements, edge cases, and risks before drafting the plan.
+
+#### Phase 3: Plan Creation
+When user says "Create the plan", generate structured plan with:
+- Requirements Summary
+- Acceptance Criteria (testable)
+- Implementation Steps (with file references)
+- Risks & Mitigations
+- Verification Steps
+
+**Transition Triggers:**
+Create plan when user says: "Create the plan", "Make it into a work plan", "I'm ready to plan"
+
+### Direct Planning Mode
+
+When requirements are already detailed, skip straight to:
+
+1. **Quick Analysis** - Brief Analyst consultation (optional)
+2. **Plan Creation** - Generate comprehensive work plan immediately
+3. **Review** (optional) - Critic review if requested
+
+## Quality Criteria
+
+Plans must meet these standards:
+- 80%+ claims cite file/line references
+- 90%+ acceptance criteria are testable
+- No vague terms without metrics
+- All risks have mitigations
+
+## Plan Storage
+
+- Drafts are saved to `.omc/drafts/`
+- Final plans are saved to `.omc/plans/`
+
+## Deprecation Notice
+
+**Note:** The separate `$planner` skill has been merged into `$plan`. If you invoke `$planner`, it will automatically redirect to this skill. Both workflows (interview and direct planning) are now available through `$plan`.
+
+---
+
+## Getting Started
+
+If requirements are clear, I'll plan directly. If not, I'll start an interview.
+
+Tell me what you want to accomplish.
+
+## Imported from everything-codex
+
+---
+name: ecc-plan
+description: Imported from everything-codex command plan
+---
+
+---
+description: Restate requirements, assess risks, and create step-by-step implementation plan. WAIT for user CONFIRM before touching any code.
+---
+
+# Plan Command
+
+
+## Native Subagent Protocol (Codex)
+
+Codex supports native subagents. Delegate with `spawn_agent`, coordinate with `send_input`, collect via `wait`, and clean up with `close_agent`.
+
+Execution preference:
+1. Use native subagents first for independent workstreams (parallel when possible).
+2. Merge results in main thread and run final verification.
+3. Fallback only when delegation is blocked: use the `[ANALYST]`/`[ARCHITECT]`/`[EXECUTOR]`/`[REVIEWER]` structure in a single response.
+
+Minimal orchestration pattern:
+```text
+spawn_agent -> send_input (optional) -> wait -> close_agent
+```
+
+This command invokes the **planner** agent to create a comprehensive implementation plan before writing any code.
+
+## What This Command Does
+
+1. **Restate Requirements** - Clarify what needs to be built
+2. **Identify Risks** - Surface potential issues and blockers
+3. **Create Step Plan** - Break down implementation into phases
+4. **Wait for Confirmation** - MUST receive user approval before proceeding
+
+## When to Use
+
+Use `$plan` when:
+- Starting a new feature
+- Making significant architectural changes
+- Working on complex refactoring
+- Multiple files/components will be affected
+- Requirements are unclear or ambiguous
+
+## How It Works
+
+The planner agent will:
+
+1. **Analyze the request** and restate requirements in clear terms
+2. **Break down into phases** with specific, actionable steps
+3. **Identify dependencies** between components
+4. **Assess risks** and potential blockers
+5. **Estimate complexity** (High/Medium/Low)
+6. **Present the plan** and WAIT for your explicit confirmation
+
+## Example Usage
+
+```
+User: $plan I need to add real-time notifications when markets resolve
+
+Agent (planner):
+# Implementation Plan: Real-Time Market Resolution Notifications
+
+## Requirements Restatement
+- Send notifications to users when markets they're watching resolve
+- Support multiple notification channels (in-app, email, webhook)
+- Ensure notifications are delivered reliably
+- Include market outcome and user's position result
+
+## Implementation Phases
+
+### Phase 1: Database Schema
+- Add notifications table with columns: id, user_id, market_id, type, status, created_at
+- Add user_notification_preferences table for channel preferences
+- Create indexes on user_id and market_id for performance
+
+### Phase 2: Notification Service
+- Create notification service in lib/notifications.ts
+- Implement notification queue using BullMQ/Redis
+- Add retry logic for failed deliveries
+- Create notification templates
+
+### Phase 3: Integration Points
+- Hook into market resolution logic (when status changes to "resolved")
+- Query all users with positions in market
+- Enqueue notifications for each user
+
+### Phase 4: Frontend Components
+- Create NotificationBell component in header
+- Add NotificationList modal
+- Implement real-time updates via Supabase subscriptions
+- Add notification preferences page
+
+## Dependencies
+- Redis (for queue)
+- Email service (SendGrid/Resend)
+- Supabase real-time subscriptions
+
+## Risks
+- HIGH: Email deliverability (SPF/DKIM required)
+- MEDIUM: Performance with 1000+ users per market
+- MEDIUM: Notification spam if markets resolve frequently
+- LOW: Real-time subscription overhead
+
+## Estimated Complexity: MEDIUM
+- Backend: 4-6 hours
+- Frontend: 3-4 hours
+- Testing: 2-3 hours
+- Total: 9-13 hours
+
+**WAITING FOR CONFIRMATION**: Proceed with this plan? (yes/no/modify)
+```
+
+## Important Notes
+
+**CRITICAL**: The planner agent will **NOT** write any code until you explicitly confirm the plan with "yes" or "proceed" or similar affirmative response.
+
+If you want changes, respond with:
+- "modify: [your changes]"
+- "different approach: [alternative]"
+- "skip phase 2 and do phase 3 first"
+
+## Integration with Other Commands
+
+After planning:
+- Use `$tdd` to implement with test-driven development
+- Use `$build-and-fix` if build errors occur
+- Use `$code-review` to review completed implementation
+
+## Related Agents
+
+This command invokes the `planner` agent located at:
+`~/.codex/agents/planner.md` (if present)

package/.agent/skills/planning-methodology/SKILL.md

@@ -0,0 +1,370 @@
+---
+name: planning-methodology
+description: Create minimal-change, reversible implementation plans. Transform requirements into executable blueprints emphasizing simplicity and safety.
+auto_invoke: true
+tags: [planning, architecture, minimal-change, reversibility]
+---
+
+# Planning Methodology Skill
+
+This skill provides a systematic methodology for creating implementation plans that are surgical, reversible, and minimize risk while maximizing clarity.
+
+## When Codex Should Use This Skill
+
+Codex will automatically invoke this skill when:
+- ResearchPack is ready and implementation planning is needed
+- User asks "how should we implement...", "create a plan for..."
+- Complex feature requires structured approach
+- Need to break down requirements into executable steps
+- Transforming research into actionable blueprint
+
+## Core Principles (BRAHMA Constitution)
+
+1. **Simplicity over complexity** (KISS, YAGNI)
+2. **Minimal changes only** - Touch fewest files possible
+3. **Reversibility mandatory** - Every change must be undoable
+4. **Verification at each step** - Clear success criteria
+
+## Planning Methodology Protocol
+
+### Step 1: Codebase Discovery (< 90 seconds)
+
+**Objective**: Understand existing structure before planning changes
+
+**Actions**:
+
+1. **Structure scan** (use Glob tool):
+   ```
+   Search patterns:
+   - Source files: src/**/*.{ext}
+   - Config files: *.config.{ext}, .{ext}rc
+   - Test files: **/*.test.{ext}, **/*.spec.{ext}
+   - Documentation: docs/*.md, README.md
+   ```
+
+2. **Pattern recognition** (use Grep + Read):
+   - How similar features are currently implemented
+   - Naming conventions (file names, function names)
+   - Code style (indentation, formatting)
+   - Import/export patterns
+   - Test patterns and frameworks
+
+3. **Integration point identification**:
+   - Where does new code connect to existing code?
+   - Configuration files that need updates
+   - Entry points (main.ts, index.js, etc.)
+   - Dependency injection patterns
+
+4. **Constraint discovery**:
+   - Existing dependencies that limit choices
+   - Framework conventions that must be followed
+   - Security/auth patterns that must be maintained
+   - Performance SLAs to meet
+
+**Output**:
+```
+Codebase Profile:
+- Primary language: [TypeScript/Python/Go/etc.]
+- Framework: [Next.js/Django/Gin/etc.]
+- Structure: [src/ organization pattern]
+- Test framework: [Jest/pytest/etc.]
+- Key patterns: [Dependency injection / Factory / etc.]
+- Integration points: [config.ts, app.ts, etc.]
+```
+
+**Anti-stagnation**: Max 90 seconds - if codebase is large, focus on areas relevant to feature only
+
+### Step 2: Minimal Change Analysis (< 60 seconds)
+
+**Objective**: Identify the smallest set of changes that accomplishes the goal
+
+**Questions to answer**:
+
+1. **New vs Modify**:
+   - Can we extend existing code (better) or must we modify it?
+   - Can new functionality live in new files (preferred)?
+   - What's the smallest interface between new and existing code?
+
+2. **Reuse vs Rebuild**:
+   - What existing utilities/services can be reused?
+   - What patterns can we follow from similar features?
+   - What must be built from scratch (minimize this)?
+
+3. **Scope boundaries**:
+   - What's the absolute minimum to make feature work?
+   - What's "nice to have" that can be deferred?
+   - What edge cases must be handled vs can be documented as limitations?
+
+4. **Reversibility**:
+   - How easily can each change be undone?
+   - Are we modifying core/critical files (higher risk)?
+   - Can we use feature flags for gradual rollout?
+
+**Output**:
+```
+Minimal Change Strategy:
+- New files: [N] (primary work here)
+- Modified files: [N] (minimal edits)
+- Deleted files: 0 (avoid deletions, use deprecation)
+- Core files touched: [N] (minimize this)
+- Reversibility: [Git revert / Config toggle / Feature flag]
+```
+
+**Principles**:
+- Prefer extension over modification
+- Prefer new files over editing existing
+- Prefer configuration over code
+- Prefer composition over inheritance
+
+### Step 3: Risk Assessment (< 30 seconds)
+
+**Objective**: Identify what could go wrong and plan mitigations
+
+**Categories of risk**:
+
+1. **Breaking changes**:
+   - Will this affect existing functionality?
+   - Are we modifying shared/core modules?
+   - Could this break other features?
+
+2. **Performance risks**:
+   - Will this add latency to critical paths?
+   - Memory/CPU impact on existing operations?
+   - Database query performance degradation?
+
+3. **Security risks**:
+   - Does this handle user input (validate & sanitize)?
+   - Are credentials/secrets managed properly?
+   - Could this introduce injection vulnerabilities?
+
+4. **Integration risks**:
+   - Dependencies on external services (what if they're down)?
+   - API version mismatches?
+   - Race conditions or concurrency issues?
+
+5. **Testing gaps**:
+   - What's hard to unit test (integration test instead)?
+   - What scenarios might we miss?
+   - What's the fallback if tests don't catch an issue?
+
+**For each identified risk**:
+```
+Risk: [Description]
+Probability: [High/Medium/Low]
+Impact: [High/Medium/Low]
+Mitigation: [How to prevent]
+Detection: [How we'll know if it happens]
+Contingency: [What we'll do if it happens]
+```
+
+**Anti-pattern**: Don't identify risks without mitigations - every risk needs an answer
+
+### Step 4: Implementation Sequence (< 30 seconds)
+
+**Objective**: Order the work for safety and clarity
+
+**Sequencing principles**:
+
+1. **Dependencies first**: Build foundation before dependent features
+2. **Tests alongside**: Write tests as you implement (or before - TDD)
+3. **Incremental integration**: Connect to existing system gradually
+4. **Verification checkpoints**: Each step has clear pass/fail criteria
+
+**Step structure**:
+```
+Step N: [Action verb] [What]
+- Task: [Detailed description]
+- Files: [Which files to change]
+- Code: [Specific code examples]
+- Verification: [How to confirm success]
+- Time estimate: [X minutes]
+```
+
+**Verification methods**:
+- Unit test passes: `npm test path/to/test`
+- Build succeeds: `npm run build`
+- Manual check: "Navigate to X and confirm Y is visible"
+- Integration test: `npm run test:integration`
+- Performance check: `npm run benchmark` (if applicable)
+
+**Total time estimate**: Sum of all step estimates + 20% buffer
+
+### Step 5: Rollback Planning (< 20 seconds)
+
+**Objective**: Ensure every change can be undone safely
+
+**Rollback mechanisms** (in priority order):
+
+1. **Git revert** (simplest):
+   ```bash
+   git reset --hard [checkpoint-commit]
+   ```
+   Good when: All changes in one commit, no DB migrations
+
+2. **Feature flag toggle** (gradual rollout):
+   ```javascript
+   if (featureFlags.newFeature === true) {
+     // new code
+   } else {
+     // old code
+   }
+   ```
+   Good when: Want to test in production, quick rollback needed
+
+3. **Configuration rollback**:
+   Restore previous config files
+   Good when: Changes are mostly configuration-driven
+
+4. **Partial rollback**:
+   Keep working parts, revert broken parts
+   Good when: Multiple independent changes, some work
+
+**Rollback plan must include**:
+- Exact commands to execute
+- Verification steps after rollback
+- Data migration rollback (if DB changes made)
+- Cache invalidation (if caching involved)
+
+**Rollback triggers** (when to execute rollback):
+- Tests fail in production
+- Performance degrades > [threshold]%
+- Error rate increases > [threshold]%
+- Critical functionality breaks
+
+### Step 6: Plan Documentation (< 30 seconds)
+
+**Objective**: Structure all above findings into clear, executable plan
+
+**Implementation Plan Format**:
+
+```markdown
+# 🗺️ Implementation Plan: [Feature Name]
+
+## Summary
+[2-3 lines: what + why + approach]
+
+## 📁 File Changes
+[New: N, Modified: N, with specific purposes]
+
+## 🔢 Implementation Steps
+[Numbered steps with verification]
+
+## 🧪 Test Plan
+[Unit + integration + manual tests]
+
+## ⚠️ Risks & Mitigations
+[Each risk with mitigation and contingency]
+
+## 🔄 Rollback Plan
+[Exact rollback procedure]
+
+## ✅ Success Criteria
+[Clear definition of "done"]
+```
+
+**Checklist before delivering**:
+- ✓ Every file change has a clear purpose
+- ✓ Every step has verification method
+- ✓ All risks have mitigations
+- ✓ Rollback plan is complete and tested (if possible)
+- ✓ Success criteria are measurable
+- ✓ Time estimates are realistic
+
+## Quality Standards
+
+### Completeness
+- **File changes**: Specify exact files with line-level changes where possible
+- **Steps**: Each step is atomic (can be done and verified independently)
+- **Tests**: Cover happy path + at least 2 edge cases + 1 error case
+- **Risks**: All major risks identified (breaking, performance, security)
+
+### Clarity
+- **Actionable**: Developer can execute without additional questions
+- **Verifiable**: Each step has objective pass/fail criteria
+- **Unambiguous**: No "probably" or "maybe" - specific instructions only
+
+### Safety
+- **Reversible**: Every change can be undone
+- **Incremental**: Changes build up gradually (not big bang)
+- **Validated**: Tests verify correctness at each step
+- **Isolated**: Failure of one step doesn't break entire system
+
+## Common Pitfalls to Avoid
+
+❌ **Don't**:
+- Plan modifications to many files simultaneously (hard to verify)
+- Skip risk assessment ("hope for the best")
+- Forget rollback plan
+- Make plans that require perfect execution (allow for errors)
+- Over-engineer ("we might need this someday")
+- Under-estimate time (plans should be realistic)
+
+✅ **Do**:
+- Touch fewest files possible (minimal blast radius)
+- Identify risks and plan mitigations explicitly
+- Always include rollback procedure
+- Build in verification checkpoints at every step
+- Follow YAGNI (You Aren't Gonna Need It) - only what's needed now
+- Add 20% time buffer for unexpected issues
+
+## Integration with knowledge-core.md
+
+**Before planning**:
+Read `knowledge-core.md` to check for:
+- Architectural patterns established in past projects
+- Decisions that constrain current work
+- Known gotchas in this codebase
+
+**After planning**:
+If plan establishes new patterns, note for knowledge-core update:
+```
+New Pattern Established:
+- Pattern: [Name/description]
+- Context: [When to use this]
+- Example: [Which files demonstrate this]
+```
+
+## Performance Targets
+
+- **Total planning time**: < 3 minutes for typical features
+- **Plan accuracy**: 95%+ of files identified correctly
+- **Risk coverage**: 100% of major risks identified
+- **Time estimates**: Within 30% of actual implementation time
+
+## Example Usage
+
+**Scenario**: ResearchPack ready for Redis caching, need implementation plan
+
+**Codex (using this skill)**:
+
+```
+[Internal: Need to plan Redis integration systematically]
+
+📐 Activating planning-methodology skill
+
+🔎 Analyzing codebase structure...
+[Follows methodology: discover → analyze → assess → sequence → rollback → document]
+
+# 🗺️ Implementation Plan: Redis Caching
+
+## Summary
+Add Redis-based caching layer to ProductService to reduce database load.
+Approach: Create separate CacheService wrapper, inject into ProductService,
+maintain backward compatibility via optional usage.
+
+## 📁 File Changes (5 files)
+
+### New Files (2)
+1. `src/services/CacheService.ts` (~80 lines)
+   - Purpose: Redis client wrapper with get/set/del/ttl operations
+   - Exports: CacheService class
+   - Dependencies: redis@4.6.0, config
+
+[...rest of detailed plan following format]
+
+✅ Plan ready for implementation
+```
+
+---
+
+**This skill ensures plans are safe, minimal, clear, and executable - setting up @code-implementer for success.**