┌─────────────────────────────────────────────────────────────┐
│                    SESSION START                            │
│                          │                                  │
│                          ▼                                  │
│              ┌──────────────────────┐                       │
│              │ ohno: get_session_   │                       │
│              │       context()      │                       │
│              └──────────┬───────────┘                       │
│                          │                                  │
│              ┌──────────────────────┐                       │
│              │ ohno serve           │◄── Browser access     │
│              └──────────┬───────────┘                       │
│                          │                                  │
│              ┌──────────────────────┐                       │
│              │ ohno: get_next_task()│                       │
│              └──────────┬───────────┘                       │
│                          │                                  │
│              ┌──────────────────────┐                       │
│              │ WORKTREE DECISION    │◄── Smart defaults     │
│              └──────────┬───────────┘                       │
│                          │                                  │
│              ┌──────────────────────┐                       │
│              │ Route to skill       │                       │
│              └──────────┬───────────┘                       │
│                          │                                  │
│              ┌──────────────────────┐                       │
│              │ CHECKPOINT (by mode) │◄── Human decision     │
│              └──────────┬───────────┘                       │
│                          │                                  │
│              ┌──────────────────────┐                       │
│              │ WORKTREE COMPLETION  │◄── Merge/PR/Keep      │
│              └──────────┬───────────┘                       │
│                          │                                  │
│              ┌──────────────────────┐                       │
│              │ ohno: done + sync    │                       │
│              │ Git commit           │                       │
│              └──────────────────────┘                       │
└─────────────────────────────────────────────────────────────┘

Subagent Execution Model

Tasks are implemented by fresh subagents, not inline in the coordinator session.

Why Subagents?

Problem	Subagent Solution
Context degradation in long sessions	Fresh context per task
Accumulated assumptions	Each task starts clean
Token limit issues	Context discarded after task

Coordinator vs Implementer

Coordinator (this session)	Implementer (subagent)
Reads ohno tasks	Receives task from coordinator
Extracts context	Works with provided context
Dispatches subagents	Implements, tests, commits
Processes results	Reports back
Updates ohno	No ohno access
Triggers hooks	No hook access

See references/subagent-dispatch.md for details.

Parallel Execution

When running with --parallel N, multiple implementers run simultaneously.

Benefits

Benefit	Description
Throughput	N independent tasks process in ~1x time instead of Nx
Resource utilization	Better use of available API capacity
Faster feedback	Complete more work per session

Tradeoffs

Tradeoff	Mitigation
Git conflicts	Auto-rebase, manual fallback
No shared learning	Agents already isolated in sequential mode
Higher token usage	N concurrent contexts

Recommended Settings

Scenario	Parallel Count
Default (safe)	1 (sequential)
Independent tasks	2-3
Large backlog	3-4
Maximum	5

Dependency Handling

The ohno blockedBy graph is the safety mechanism:

Tasks with unmet dependencies are not dispatched
If Task B depends on Task A, B waits for A to complete
No additional conflict detection - trust the dependency graph

Quick Start

1. Initialize ohno

npx @stevestomp/ohno-cli init

2. Create Project Context (optional)

Create .claude/PROJECT.md for shared project context:

# Project Name

## Overview
Brief description of the project.

## Tech Stack
- Framework: Next.js 14
- Database: PostgreSQL
- Styling: Tailwind CSS

## Conventions
- Use TypeScript strict mode
- Follow existing patterns in codebase

3. Start Session

Use ohno MCP tools or CLI:

# Get context from previous sessions
npx @stevestomp/ohno-cli context

# See all tasks
npx @stevestomp/ohno-cli tasks

# Get recommended next task
npx @stevestomp/ohno-cli next

# Start kanban board
npx @stevestomp/ohno-cli serve

Operating Modes

SUPERVISED Mode (Default)

Human reviews after every task. Maximum control, slower pace.

Checkpoint behavior:

Task complete → PAUSE
Story complete → PAUSE
Epic complete → PAUSE

Use when: Starting new projects, unfamiliar domains, critical code.

SEMI-AUTO Mode

Human reviews at story/epic boundaries. Good balance.

Checkpoint behavior:

Task complete → Log and continue
Story complete → PAUSE
Epic complete → PAUSE

Use when: Established patterns, routine implementation.

AUTONOMOUS Mode

Human reviews at epic boundaries only. Maximum speed.

Checkpoint behavior:

Task complete → Skip
Story complete → Log and continue
Epic complete → PAUSE

Use when: Well-defined specs, trusted patterns, time pressure.

Session Protocol

Starting a Session

## Session Start Checklist

1. [ ] Get session context: `ohno context` or MCP get_session_context()
2. [ ] Read .claude/PROJECT.md if exists
3. [ ] Check task list: `ohno tasks`
4. [ ] Start kanban: `ohno serve`
5. [ ] Check git status - clean working directory?
6. [ ] Get next task: `ohno next`
7. [ ] Announce plan - tell human what you'll do

Using ohno MCP:

1. get_session_context() → Understand previous session
2. get_tasks() → See all work
3. get_next_task() → Pick what to do

Worktree Isolation

After getting the next task, decide whether to isolate work in a git worktree.

Decision Priority

Evaluate in order - first match wins:

1. Explicit flags (from /work command arguments)
   --worktree    → Always use worktree
   --in-place    → Never use worktree

2. Smart defaults by task type
   feature, bug, spike → Worktree
   chore, docs         → In-place
   test                → Inherit from sibling tasks in story

3. Fallback
   Unknown type → Worktree (safer default)

Worktree Setup

When using a worktree:

Step 1: Check for existing story worktree

# If task belongs to a story, check for reusable worktree
git worktree list --porcelain | grep "story-{story_id}-"

If found, cd into existing worktree and skip to task work.

Step 2: Create new worktree

# Generate name from task/story
NAME="task-{id}-{slug}" or "story-{story_id}-{slug}"

# Get base branch
BASE=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's|refs/remotes/origin/||')

# Create worktree with new branch
git worktree add -b $NAME .worktrees/$NAME $BASE

Step 3: Ensure ignored

# Add to .gitignore if not already
echo ".worktrees/" >> .gitignore  # (check first)

Step 4: Install dependencies

cd .worktrees/$NAME

# Detect package manager and install
if [ -f bun.lockb ]; then bun install
elif [ -f pnpm-lock.yaml ]; then pnpm install
elif [ -f yarn.lock ]; then yarn install
elif [ -f package-lock.json ]; then npm install
fi

Step 5: Announce and continue

## Worktree Setup

Creating worktree for feature task: {title}
  ✓ Branch created: task-42-user-auth
  ✓ Worktree ready at .worktrees/task-42-user-auth
  ✓ Dependencies installed (bun, 4.2s)

Ready to work.

In-Place Work

When working in-place (chore/docs or --in-place flag):

## Working In-Place

Chore task: {title}
Working directly on current branch (no worktree).

No worktree setup, no completion prompts.

Worktree Completion

After a task completes (reviews pass), handle the worktree based on context.

Task Within a Story

Commit and continue - no prompt needed:

Task 42 complete (part of Story 12).

  ✓ Committed to story-12-user-auth branch

Story has 2 more tasks remaining.
Continue with next task? [Y/n]

Stay in worktree for remaining story tasks.

Standalone Task or Story Complete

Prompt user for worktree disposition:

[Task 42 complete / Story 12 complete]

What would you like to do?

  1. Merge to main (Recommended)
  2. Create Pull Request
  3. Keep worktree (continue later)
  4. Discard work

Which option?

Option implementations:

Option	Commands
Merge	`git checkout main && git merge --no-ff {branch} && git worktree remove .worktrees/{name} && git branch -d {branch}`
PR	`git push -u origin {branch} && gh pr create --title "{task-title}" --body "Closes task #{id}"`
Keep	Do nothing - worktree remains for later
Discard	`git worktree remove --force .worktrees/{name} && git branch -D {branch}`

In-Place Completion

If working in-place, skip worktree prompts entirely. Standard commit flow only.

Hook Integration

Hooks execute automatically at lifecycle points. Do not call manually.

Work Loop with Hooks

[pre-session hooks]  <- Verify clean state

WHILE tasks remain:
  [pre-task hooks]   <- Check blockers

  1. Get next task (ohno next)
  2. Start task (ohno start <id>)
  3. WORKTREE DECISION         <- Smart defaults or flags
  4. Setup worktree (if needed) <- Create branch, install deps
  5. Extract task context
  6. Dispatch subagent          <- Fresh context per task
  7. Process subagent result

  [post-task hooks]  <- GUARANTEED: sync, commit

  8. WORKTREE COMPLETION        <- Merge/PR/Keep (if worktree)
  9. CHECKPOINT based on mode

[post-session hooks] <- Final sync, summary

Work Loop with Hooks (Parallel)

[pre-session hooks]  <- Verify clean state

WHILE tasks remain:
  [pre-task hooks]   <- Check blockers (per task)

  1. Get up to N tasks (ohno)
  2. Filter by dependencies
  3. WORKTREE DECISION (per task) <- Smart defaults or flags
  4. Setup worktrees (if needed)  <- May reuse story worktrees
  5. Dispatch N subagents         <- PARALLEL: single message, N Task tools
  6. Wait for results
  7. Process each result:
     - Reviews (sequential per task)
     - Commit (may conflict)

  [post-task hooks]  <- Per completed task

  8. WORKTREE COMPLETION          <- Per task, based on context
  9. CHECKPOINT based on mode

[post-session hooks] <- Final sync, summary

Hook Execution Output

When hooks run, you'll see:

## Hooks: post-task

| Action | Status | Time |
|--------|--------|------|
| sync | ✓ | 0.3s |
| commit | ✓ | 0.5s |

Continuing...

Mode-Specific Behavior

Mode	post-task hooks
supervised	sync only
semi-auto	sync, commit
autonomous	sync, commit, quick-test

Hook Failures

Hooks are fail-safe:

Warnings don't stop the session
Critical failures pause for human input
All results logged for review

See hooks/HOOKS.md for configuration.

During Work

For each task:

## Task: [task-id] Create grid component

### Plan
- Create responsive grid using CSS Grid
- Support 1-4 column layouts
- Add to component library

### Implementation
[Work happens here]

### Verification
- [ ] Component renders
- [ ] Responsive breakpoints work
- [ ] Exported from index

### Post-Task
Hooks handle: sync, commit (mode-dependent)
Checkpoint triggers based on mode

Ending a Session

## Session End Checklist

1. [ ] Session notes logged via ohno
2. [ ] No broken code left
3. [ ] Clear summary of what was done
4. [ ] Clear next steps documented

*Note: post-session hooks handle final sync and summary automatically.*

Checkpoint Protocol

PAUSE Checkpoint

Agent stops completely and waits for human input.

## CHECKPOINT: Task Complete

**Completed**: task-abc123 - Create grid component
**Status**: Awaiting your review
**Kanban**: http://localhost:3456 (run `ohno serve`)

### What I Did
- Created `GridLayout.tsx` component
- Added responsive breakpoints (sm, md, lg, xl)
- Exported from components/index.ts

### What I'd Do Next
- task-def456: Create dashboard header

### Your Options
1. **Continue** - Proceed to next task
2. **Modify** - Change approach before continuing
3. **Pause** - Stop session here
4. **Switch** - Work on different task

Waiting for your decision...

REVIEW Checkpoint

Agent continues but flags work for later review.

## REVIEW FLAG: Story Complete

**Completed**: Dashboard Layout (3 tasks)
**Continuing to**: Dashboard Widgets
**Kanban**: Synced ✓

Flagged for review.

NOTIFY Checkpoint

Agent logs and continues without stopping.

## ✓ Task Complete: task-abc123 - Create grid component
Kanban synced → Continuing to next task...

Skill Routing

Based on task type, load relevant skill for domain knowledge:

Task Type	Skill
API design	api-design
API tests	api-testing
Architecture	architecture-review
SDK/package	sdk-development

Note: Design work routes to /design:* commands

Skill Invocation

When routing to a skill:

## Invoking Skill: api-design

**Context**: Feature - API Endpoints
**Task**: task-xyz - Design user endpoints

Reading skill documentation...
[Skill takes over for this task]

ohno Integration

MCP Tools Available

Query Tools:

get_session_context() - Previous session notes, blockers, in-progress tasks
get_project_status() - Overall project statistics
get_tasks() - List all tasks
get_task(id) - Get specific task details
get_next_task() - Recommended next task
get_blocked_tasks() - Tasks with blockers

Update Tools:

start_task(id) - Mark task in-progress
complete_task(id, notes) - Mark task done
log_activity(message) - Log session activity
set_blocker(id, reason) - Block a task
resolve_blocker(id) - Unblock a task

CLI Commands

# Session management
ohno context              # Get session context
ohno status               # Project statistics

# Task management
ohno tasks                # List all tasks
ohno next                 # Get recommended next task
ohno start <id>           # Start working on task
ohno done <id> --notes    # Complete task with notes
ohno block <id> <reason>  # Set blocker
ohno unblock <id>         # Resolve blocker

# Kanban
ohno serve                # Start kanban server
ohno sync                 # Sync kanban HTML

Error Recovery

Build Failures

## ⚠️ Build Failed

**Error**: TypeScript compilation error in Dashboard.tsx
**Line 47**: Property 'user' does not exist on type '{}'

### Recovery Plan
1. Check recent changes (git diff)
2. Identify breaking change
3. Fix type error
4. Verify build passes
5. Block task if needed: `ohno block <id> "Build failure"`
6. Continue or escalate

Proceeding with recovery...

Blocked Tasks

# Block a task
ohno block task-abc123 "Waiting for API spec"

# View blocked tasks
ohno tasks --status blocked

# Resolve blocker
ohno unblock task-abc123

Anti-Patterns

Anti-Pattern	Problem	Fix
Skipping verification	Start on broken code	Always verify first
No git commits	Can't recover from errors	Commit every task
No kanban sync	Stale visual state	Run `ohno sync` after changes
Giant tasks	Lose progress on failure	Keep tasks ≤8 hours
Ignoring checkpoints	Lose human control	Respect mode settings
No session context	Next session confused	Use `ohno context`
Autonomous on new project	Bad patterns amplified	Start supervised

References

references/session-protocol.md — Detailed session management
references/checkpoint-types.md — Checkpoint configuration
references/skill-routing.md — Skill selection logic

project-harness

Project Harness

Core Concept