oh-plan

Creates well-structured GitHub issues ready for oh-task agents. Works in two modes:

Task mode: Investigates codebase, asks clarifying questions, creates issues
Session mode: Reads existing .oh/<session>.md context, skips investigation, creates issues

Invocation

# Task mode - investigate from scratch
/oh-plan "Add dark mode support to the dashboard"

# Session mode - use existing context from skills workflow
/oh-plan auth-refactor

Mode Detection

At the start, check if the argument matches an existing session file:

If .oh/<arg>.md exists AND contains ## Solution Space:
    → Session mode (skip investigation, use context)
Else:
    → Task mode (investigate, ask questions)

Session Mode Flow

When .oh/<session>.md exists with solution-space context:

Read session file and extract:
- ## Aim → Goal for issues
- ## Problem Space → Constraints, terrain, assumptions
- ## Solution Space → Selected approach, trade-offs accepted
- ## Problem Statement → Framing (if present)
Skip investigation - context already gathered by grounding skills
Skip clarifying questions - decisions already made during solution-space
Decompose the selected solution into right-sized issues:
- Use the Solution Space recommendation as the starting point
- Apply standard decomposition heuristics (see below)
- Aim for 1-4 hours of work per issue

Create GitHub issues with enriched context from session:

gh issue create --title "<title>" --label "oh-planned" --body "$(cat <<'EOF'
## Goal

<from Aim section>

## Context

<from Problem Space: constraints, terrain>
<from Solution Space: selected approach>

## Acceptance Criteria

- [ ] <derived from solution trade-offs>
- [ ] <derived from aim feedback signals>

## Trade-offs Accepted

<from Solution Space>

## Notes

<from Problem Space assumptions>
EOF
)"

Update session file with created issues:

## Plan
**Updated:** <timestamp>
**Issues:** #43, #44, #45

Session Mode Example

$ /oh-plan auth-refactor

Found session file: .oh/auth-refactor.md

Reading context...
- Aim: Users complete signup in under 60 seconds
- Problem: Current flow has 5 steps, competitors have 2
- Solution: Collapse to email + password, defer profile to post-signup
- Trade-offs: Less data upfront, need progressive profiling later

Decomposing into issues...

Created 2 issues:

#43: "Simplify signup to email + password only"
  - Remove name, company, role fields from signup
  - Add post-signup redirect to profile completion
  - Depends on: none

#44: "Add progressive profile completion flow"
  - Prompt for missing fields on first dashboard visit
  - Track completion percentage
  - Depends on: #43

Updated .oh/auth-refactor.md with issue links.
Done. Issues ready for /oh-task.

Task Mode Flow

When no session file exists (current behavior):

Explore the codebase to understand:
- Project architecture and patterns
- Relevant files that would be touched
- Existing similar implementations to follow
- Potential complications or dependencies
Ask clarifying questions via AskUserQuestion:
- Scope boundaries (what's in/out of scope)
- Technical preferences (if multiple approaches exist)
- Priority and any constraints
- Only ask questions that genuinely affect the plan
Assess complexity and determine decomposition:
- Single coherent task → create 1 issue
- Multiple independent pieces → create multiple issues
- Large with dependencies → create issues with "Depends on #N" links
- Aim for issues that are 1-4 hours of work each

Create GitHub issue(s) with the oh-planned label:

# Create label if it doesn't exist (one-time)
gh label create oh-planned --description "Created via oh-plan skill" --color "0E8A16" 2>/dev/null || true

# Create issue
gh issue create --title "<clear, actionable title>" --label "oh-planned" --body "$(cat <<'EOF'
## Goal

<1-2 sentences describing what we're trying to achieve>

## Context

<relevant background - files identified, patterns to follow, constraints>

## Acceptance Criteria

- [ ] Criterion 1 (specific, testable)
- [ ] Criterion 2
- [ ] Criterion 3

## Notes

<any technical decisions, edge cases, or things to watch out for>
EOF
)"

Signal completion: Call signal_completion(status: "success") to notify the orchestrator. Fallback: If signal_completion is not available, output COMPLETION: status=success as your final message.

Issue Quality Guidelines

Issues created by oh-plan should be:

Self-contained: All context needed to start work without re-investigation
Actionable: Clear title, specific acceptance criteria, "done" is obvious
Right-sized: 1-4 hours of focused work (not too big, not trivial)
Linked: Dependencies explicitly noted if multiple issues created

Good Issue Title Examples

"Add session timeout detection with configurable threshold"
"Refactor user auth to use JWT instead of sessions"
"Fix race condition in concurrent task spawning"

Bad Issue Title Examples

"Improve the code" (too vague)
"Do the thing we discussed" (no context)
"Bug fix" (what bug?)

Decomposition Strategy

Bias toward focused issues. A well-scoped issue that does one thing well is better than a multifaceted issue that tries to do many things. When genuinely uncertain, prefer splitting - but don't create trivial issues.

When to Split

Split into multiple issues when ANY of these apply:

Multiple modules with distinct concerns - Each coherent subsystem change can be its own issue
Mix of backend and frontend - API changes and UI changes often work better as separate issues
Testable in isolation - If parts can be tested independently, they're candidates for separate issues
Different risk profiles - Risky changes shouldn't be bundled with straightforward ones

When NOT to Split

Keep as one issue when:

Integration is trivial - Just wiring things together with a few lines of code
Changes are tightly coupled - Splitting would create issues that can't be tested alone
The "integration" is obvious - No complex error handling, no new edge cases
Total scope is still reasonable - Even combined, it's 2-4 hours of work

Integration Issues

Consider a separate integration issue when connecting components involves:

Non-trivial error handling at boundaries
New edge cases that emerge from the combination
Complex state coordination between systems
A meaningful test surface (end-to-end flows worth testing explicitly)

Don't create integration issues for:

Simple API calls with straightforward error handling
Passing data from one component to another
Standard CRUD wiring

Pattern when integration IS complex:

Issue #1: "Add theme persistence API" (Foundation)
Issue #2: "Add theme toggle component" (Feature)
Issue #3: "Wire theme system with fallback handling" (Integration - Depends on #1, #2)
  - Handle API failures gracefully
  - System preference detection fallback
  - Theme flicker prevention on load

Decomposition Example

Task: "Add dark mode support to the dashboard"

Over-decomposed (too many trivial issues):

Issue #1: Add preferences API
Issue #2: Add toggle component
Issue #3: Add CSS variables
Issue #4: Wire toggle to API
Issue #5: Wire CSS to components
Issue #6: Handle loading states

Under-decomposed (one big issue):

Issue #1: Add dark mode support (everything)

Right-sized:

Issue #1: "Add user preferences API with theme support" (Foundation)
  - GET/POST /api/preferences
  - Includes theme field

Issue #2: "Add dark mode theming system" (Feature - Depends on #1)
  - CSS custom properties for light/dark
  - Theme toggle in settings
  - Wire to preferences API
  - Apply theme on app load

Issue #3: "Handle theme edge cases" (Polish - Depends on #2)
  - Only if complex: system preference fallback,
    theme flicker prevention, etc.
  - Skip if straightforward

Dependency Notation

Use "Depends on #N" in issue body:

## Goal
Add dark mode theming system with toggle and persistence.

**Depends on:** #1 (preferences API)

What NOT to Do

Don't create issues for trivial changes (typo fixes, single-line changes)
Don't over-decompose - 10 tiny issues is worse than 2-3 well-scoped ones
Don't start implementation - oh-plan is for planning only
Don't skip the clarifying questions if scope is ambiguous (task mode)
Don't re-investigate when session context exists (session mode)

Exit Conditions

Outcome	Call
Issue(s) created successfully	`signal_completion(status: "success")`
User cancelled during questions	`signal_completion(status: "error", error: "User cancelled")`
Failed to create issue	`signal_completion(status: "error", error: "<reason>")`
Session file missing solution-space	`signal_completion(status: "error", error: "Session missing Solution Space - run /solution-space first")`

Task Mode Example

$ /oh-plan "Add heartbeat monitoring for tmux sessions"

Exploring codebase...
Found relevant files:
- src/tmux/sessions.ts (session management)
- src/state/sessions.ts (session state tracking)
- src/index.ts (main loop)

I have a few questions to scope this correctly:

Q: What should happen when a session stops responding?
[1] Mark as crashed, notify user
[2] Auto-restart the session
[3] Just log and continue

User: 1

Q: How often should we check for heartbeats?
[1] Every 30 seconds (Recommended)
[2] Every minute
[3] Every 5 minutes

User: 1

Creating issue...

Created issue #67: "Add heartbeat monitoring for tmux sessions"

## Goal
Detect when tmux sessions stop responding and notify the user.

## Context
- Sessions are tracked in src/state/sessions.ts
- Tmux interactions in src/tmux/sessions.ts
- Need to add periodic check in main loop

## Acceptance Criteria
- [ ] Check session liveness every 30 seconds
- [ ] Mark session as "crashed" if not responding
- [ ] Send Telegram notification when session crashes
- [ ] Add crashed sessions to /status output

## Notes
- Use tmux has-session to check liveness
- Consider: what if tmux server itself is down?

signal_completion(status: "success")
Done. Issue #67 ready for /oh-task.

Integration with Skills Workflow

oh-plan works seamlessly with the Open Horizons skills workflow:

# Grounding phase (in skills workflow)
/aim auth-refactor
/problem-space auth-refactor
/solution-space auth-refactor

# Planning phase (oh-plan reads the context)
/oh-plan auth-refactor          # Creates GitHub issues from session

# Execution phase
/oh-task 43                      # Work the issues

This avoids duplicating investigation work - the grounding skills gather context, oh-plan transforms it into trackable issues.