Name: boulder-state
Author: willhama

Imported from willhama/md-file-study (corpus_full/code-yeongyu__oh-my-openagent/files/packages/omo-opencode/src/features/boulder-state/AGENTS.md). Install upstream with npx skills add willhama/md-file-study --skill boulder-state. Copyright stays with the author.

src/features/boulder-state/ — Active Work Plan Tracker

Generated: 2026-07-17 / 7d664b96b

OVERVIEW

10 files (~1k LOC excl. tests). Tracks Sisyphus's "boulder" — the active work plan being rolled across sessions, worktrees, and subagent task delegations. Named after the Sisyphus myth: the boulder must keep rolling until the plan is complete.

Inspected interactively via bunx oh-my-opencode boulder (see src/cli/boulder/).

SCHEMA (v2)

interface BoulderState {
  schema_version?: 2
  active_work_id?: string
  works?: Record<string, BoulderWorkState>
  active_plan: string                            // absolute path to active .md plan
  started_at: string                             // ISO timestamp
  ended_at?: string
  elapsed_ms?: number
  status?: "active" | "completed" | "paused" | "abandoned"
  session_ids: string[]                          // every session that has rolled the boulder
  session_origins?: Record<string, "direct" | "appended">
  plan_name: string                              // filename of active_plan
  agent?: string                                 // resume agent (atlas | sisyphus | ...)
  worktree_path?: string                         // git worktree root
  task_sessions?: Record<string, TaskSessionState>  // reusable subagent sessions per top-level task
}

FILES

File	Purpose
`types.ts`	`BoulderState`, `BoulderWorkState`, `TaskSessionState`, status enums
`storage.ts`	Atomic CRUD on `.omo/boulder.json`. Writes via temp file + rename; file lock per work_id
`constants.ts`	Path resolution + schema version constant
`top-level-task.ts`	Helpers to identify the current top-level plan task and resolve its reusable subagent session
`format-duration.ts`	`formatDurationHuman(ms)` — "1h 23m 5s" formatting for boulder duration
`index.ts`	Barrel exports

LIFECYCLE

session.startWork(plan)
  → BoulderState created with active_plan, started_at, plan_name
  → atlas-hook reads BoulderState + `task_sessions` on session.idle (boulder continuation + subagent resume)
session.idle (incomplete plan)
  → todoContinuationEnforcer + atlasHook inspect state
  → Inject CONTINUATION_PROMPT or BOULDER_COMPLETE_PROMPT
session.completed
  → BoulderState status="completed", ended_at, elapsed_ms recorded

INTEGRATION POINTS

Where	What
`src/cli/boulder/`	CLI inspector formats this state
`src/hooks/atlas/`	Reads work state + `task_sessions` (subagent resume); drives boulder-complete and parallel-delegation prompts
`src/hooks/start-work/`	Creates the BoulderState on `/start-work` invocation
`src/hooks/todo-continuation-enforcer/`	Session-idle continuation when boulder incomplete

STORAGE

<worktree-root>/.omo/boulder.json   # gitignored; one file per worktree

Atomic writes: temp file → fsync (where supported) → rename. File lock prevents concurrent corruption. Schema migrations between versions handled inline in storage.ts.

NOTES

task_sessions reuse: same subagent session is reused across iterations for the same top-level task to preserve context.
Multi-work: works map allows tracking multiple concurrent plans; active_work_id selects the current one.
Worktree-scoped: state lives in the worktree, not user-global; ensures parallel work plans across worktrees stay isolated.

Install boulder-state and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

{ "ocm": "1", "id": "willhama-md-file-study-boulder-state", "kind": "skill", "name": "boulder-state", "description": "10 files (~1k LOC excl. tests). Tracks Sisyphus's \"boulder\" — the active work plan being rolled across sessions, worktrees, and subagent task delegations. Named after the Sisyphus myth: the boulder must keep rolling until the plan is complete.", "publisher": "willhama", "version": "1.0.0", "capabilities": { "domains": [ "coding" ], "tags": [ "skill-md", "github-agents" ], "languages": [ "en" ] }, "quality_prior": 0.6, "examples": [ "10 files (~1k LOC excl. tests). Tracks Sisyphus's \"boulder\" — the active work plan being rolled across sessions, worktrees, and subagent task delegations. Named after the Sisyphus myth: the boulder must keep rolling until the plan is complete." ], "primary": false, "metadata": { "source": { "provider": "github-agents", "repository": "https://github.com/willhama/md-file-study", "path": "corpus_full/code-yeongyu__oh-my-openagent/files/packages/omo-opencode/src/features/boulder-state/AGENTS.md", "ref": "c19de1e5213e9860055ac2385c28916a272efb46", "url": "https://github.com/willhama/md-file-study/blob/c19de1e5213e9860055ac2385c28916a272efb46/corpus_full/code-yeongyu__oh-my-openagent/files/packages/omo-opencode/src/features/boulder-state/AGENTS.md", "key": "willhama/md-file-study/corpus_full/code-yeongyu__oh-my-openagent/files/packages/omo-opencode/src/features/boulder-state/AGENTS.md" } }, "instructions": "# src/features/boulder-state/ — Active Work Plan Tracker\n\n**Generated:** 2026-07-17 / 7d664b96b\n\n## OVERVIEW\n\n10 files (~1k LOC excl. tests). Tracks Sisyphus's \"boulder\" — the active work plan being rolled across sessions, worktrees, and subagent task delegations. Named after the Sisyphus myth: the boulder must keep rolling until the plan is complete.\n\nInspected interactively via `bunx oh-my-opencode boulder` (see [`src/cli/boulder/`](../../cli/boulder)).\n\n## SCHEMA (v2)\n\n```typescript\ninterface BoulderState {\n schema_version?: 2\n active_work_id?: string\n works?: Record<string, BoulderWorkS", "cost": { "context_tokens": 886 } }

boulder-state

About