diff --git a/packages/omo-codex/plugin/skills/start-work/SKILL.md b/packages/omo-codex/plugin/skills/start-work/SKILL.md new file mode 100644 index 000000000..ecbcec370 --- /dev/null +++ b/packages/omo-codex/plugin/skills/start-work/SKILL.md @@ -0,0 +1,120 @@ +--- +name: start-work +description: "Execute a Prometheus work plan in Codex with Boulder state, evidence ledger updates, worktree discipline, parallel subagents, and Stop-hook continuation. Use after planning when the user says start work, execute plan, continue plan, resume plan, or asks to run a .omo/plans plan." +--- + +## Codex Harness Tool Compatibility + +This skill ports the OpenCode `/start-work` flow onto Codex. Any OpenCode-only tool name in an inherited example must be translated to its Codex equivalent: + +| OpenCode example | Codex tool to use | +| --- | --- | +| `task(subagent_type="explore", ...)` | `spawn_agent(agent_type="explorer", task_name="...", message="...")` | +| `task(subagent_type="librarian", ...)` | `spawn_agent(agent_type="librarian", task_name="...", message="...")` | +| `task(subagent_type="plan", ...)` | `spawn_agent(agent_type="plan", task_name="...", message="...")` | +| `task(subagent_type="oracle", ...)` for final verification | `spawn_agent(agent_type="codex-ultrawork-reviewer", task_name="...", message="...")` | +| `task(category="...", ...)` for implementation or QA | `spawn_agent(agent_type="worker", task_name="...", message="...")` | +| `background_output(task_id="...")` | `wait_agent(...)` | +| `dispatchInternalPrompt(...)` | the `Stop` hook emits `{"decision":"block","reason":""}` automatically; see Continuation | +| `team_*(...)` | `spawn_agent` + `send_message` + `followup_task` + `wait_agent` + `close_agent` | + +When translating `load_skills=[...]`, name the skills inside the spawned agent's `message`. If a code block below conflicts with this section, this section wins. + +# start-work + +Execute a Prometheus work plan until every top-level checkbox is complete. This skill pairs with the Codex `Stop` / `SubagentStop` continuation hook in `components/start-work-continuation`, which re-injects the next turn while `.omo/boulder.json` says the current `codex:` still has unchecked plan work. + +## Usage + +```text +$start-work [plan-name] [--worktree ] +``` + +- `plan-name` is optional. It may be a full or partial file stem under `.omo/plans/`. +- `--worktree` is optional. Use it only when the user explicitly asks to work in a separate git worktree. + +## Phase 1: Select the plan + +1. Read `.omo/boulder.json` if it exists. +2. List Prometheus plan files under `.omo/plans/`. +3. If `plan-name` was provided, select the matching plan. +4. If exactly one active or paused Boulder work exists for this session, resume it. +5. If no active work exists and exactly one plan exists, select it. +6. If multiple plans remain possible, ask one focused selection question. + +## Phase 2: Create or update Boulder state + +Write `.omo/boulder.json` before implementation starts. Session ids must be prefixed with `codex:` so the continuation hook can identify its own session. + +```json +{ + "schema_version": 2, + "active_work_id": "", + "works": { + "": { + "work_id": "", + "active_plan": ".omo/plans/.md", + "plan_name": "", + "session_ids": ["codex:"], + "status": "active", + "worktree_path": null + } + } +} +``` + +If `--worktree` is set, verify the path with `git worktree list --porcelain` or create it with `git worktree add `, then store the absolute path as `worktree_path`. All edits, commands, tests, and evidence capture must run inside that worktree. + +## Phase 3: Execute the next checkbox + +1. Read the full selected plan. +2. Find the first unchecked column-0 checkbox in `## TODOs` or `## Final Verification Wave`. +3. Ignore nested checkboxes under acceptance criteria, evidence, and definition-of-done sections. +4. Decompose that checkbox into atomic sub-tasks. +5. Dispatch independent sub-tasks in parallel with `spawn_agent`; serialize only when one sub-task has a named dependency on another. + +Each sub-task message must include: + +1. Goal and exact files or directories in scope. +2. Required red test or failing reproduction before production changes. +3. Implementation constraints from the plan and project rules. +4. Automated verification commands to run. +5. One Manual-QA channel: HTTP call, tmux session, browser use, or computer use. +6. Required artifact path and cleanup receipt. + +## Phase 4: Verify and record evidence + +For each checkbox, complete all four gates before marking it done: + +1. Plan reread: confirm the checkbox and acceptance criteria. +2. Automated verification: run tests, typecheck, lint, build, or the plan-specific equivalent. +3. Manual-QA channel: capture a real artifact, not a dry-run claim. +4. Cleanup: close temporary processes, tmux sessions, browser contexts, ports, containers, and temp directories. + +Append evidence to `.omo/start-work/ledger.jsonl` using one JSON object per line. Include at least `event`, `plan`, `task`, `session_id`, `commands`, `artifact`, and `cleanup` fields. + +## Phase 5: Mark progress + +Only after verification passes: + +1. Edit the plan checkbox from `- [ ]` to `- [x]`. +2. Re-read the plan and confirm the remaining count decreased. +3. Append a `task-completed` ledger entry. +4. Continue with the next checkbox. Do not ask whether to continue. + +## Completion + +When all top-level checkboxes in `## TODOs` and `## Final Verification Wave` are complete: + +1. Run the plan's final verification commands. +2. If worktree mode was used, sync `.omo/` state back to the main repo, merge or hand off exactly as requested, and remove the worktree only after successful merge or explicit handoff. +3. Remove or mark the Boulder work as completed. +4. Print an `ORCHESTRATION COMPLETE` block with the plan path, verification commands, artifacts, and cleanup receipts. + +## Hard rules + +- No production change before a failing test or reproduction exists. +- No `--dry-run` as completion evidence. +- No tests-only completion claim. A Manual-QA artifact is required. +- No unprefixed session ids in Boulder state. Codex sessions are always `codex:`. +- No stale-memory execution. The plan and ledger are the durable source of truth. diff --git a/packages/omo-codex/plugin/test/sync-skills.test.mjs b/packages/omo-codex/plugin/test/sync-skills.test.mjs index 7ff99f058..637b08a6e 100644 --- a/packages/omo-codex/plugin/test/sync-skills.test.mjs +++ b/packages/omo-codex/plugin/test/sync-skills.test.mjs @@ -12,11 +12,15 @@ const expectedSkills = [ "debugging", "frontend-ui-ux", "lsp", + "metis", + "momus", + "planing-prometheustic", "programming", "refactor", "remove-ai-slops", "review-work", "rules", + "start-work", "ultragoal", ]; diff --git a/packages/shared-skills/skills/start-work/SKILL.md b/packages/shared-skills/skills/start-work/SKILL.md new file mode 100644 index 000000000..ecbcec370 --- /dev/null +++ b/packages/shared-skills/skills/start-work/SKILL.md @@ -0,0 +1,120 @@ +--- +name: start-work +description: "Execute a Prometheus work plan in Codex with Boulder state, evidence ledger updates, worktree discipline, parallel subagents, and Stop-hook continuation. Use after planning when the user says start work, execute plan, continue plan, resume plan, or asks to run a .omo/plans plan." +--- + +## Codex Harness Tool Compatibility + +This skill ports the OpenCode `/start-work` flow onto Codex. Any OpenCode-only tool name in an inherited example must be translated to its Codex equivalent: + +| OpenCode example | Codex tool to use | +| --- | --- | +| `task(subagent_type="explore", ...)` | `spawn_agent(agent_type="explorer", task_name="...", message="...")` | +| `task(subagent_type="librarian", ...)` | `spawn_agent(agent_type="librarian", task_name="...", message="...")` | +| `task(subagent_type="plan", ...)` | `spawn_agent(agent_type="plan", task_name="...", message="...")` | +| `task(subagent_type="oracle", ...)` for final verification | `spawn_agent(agent_type="codex-ultrawork-reviewer", task_name="...", message="...")` | +| `task(category="...", ...)` for implementation or QA | `spawn_agent(agent_type="worker", task_name="...", message="...")` | +| `background_output(task_id="...")` | `wait_agent(...)` | +| `dispatchInternalPrompt(...)` | the `Stop` hook emits `{"decision":"block","reason":""}` automatically; see Continuation | +| `team_*(...)` | `spawn_agent` + `send_message` + `followup_task` + `wait_agent` + `close_agent` | + +When translating `load_skills=[...]`, name the skills inside the spawned agent's `message`. If a code block below conflicts with this section, this section wins. + +# start-work + +Execute a Prometheus work plan until every top-level checkbox is complete. This skill pairs with the Codex `Stop` / `SubagentStop` continuation hook in `components/start-work-continuation`, which re-injects the next turn while `.omo/boulder.json` says the current `codex:` still has unchecked plan work. + +## Usage + +```text +$start-work [plan-name] [--worktree ] +``` + +- `plan-name` is optional. It may be a full or partial file stem under `.omo/plans/`. +- `--worktree` is optional. Use it only when the user explicitly asks to work in a separate git worktree. + +## Phase 1: Select the plan + +1. Read `.omo/boulder.json` if it exists. +2. List Prometheus plan files under `.omo/plans/`. +3. If `plan-name` was provided, select the matching plan. +4. If exactly one active or paused Boulder work exists for this session, resume it. +5. If no active work exists and exactly one plan exists, select it. +6. If multiple plans remain possible, ask one focused selection question. + +## Phase 2: Create or update Boulder state + +Write `.omo/boulder.json` before implementation starts. Session ids must be prefixed with `codex:` so the continuation hook can identify its own session. + +```json +{ + "schema_version": 2, + "active_work_id": "", + "works": { + "": { + "work_id": "", + "active_plan": ".omo/plans/.md", + "plan_name": "", + "session_ids": ["codex:"], + "status": "active", + "worktree_path": null + } + } +} +``` + +If `--worktree` is set, verify the path with `git worktree list --porcelain` or create it with `git worktree add `, then store the absolute path as `worktree_path`. All edits, commands, tests, and evidence capture must run inside that worktree. + +## Phase 3: Execute the next checkbox + +1. Read the full selected plan. +2. Find the first unchecked column-0 checkbox in `## TODOs` or `## Final Verification Wave`. +3. Ignore nested checkboxes under acceptance criteria, evidence, and definition-of-done sections. +4. Decompose that checkbox into atomic sub-tasks. +5. Dispatch independent sub-tasks in parallel with `spawn_agent`; serialize only when one sub-task has a named dependency on another. + +Each sub-task message must include: + +1. Goal and exact files or directories in scope. +2. Required red test or failing reproduction before production changes. +3. Implementation constraints from the plan and project rules. +4. Automated verification commands to run. +5. One Manual-QA channel: HTTP call, tmux session, browser use, or computer use. +6. Required artifact path and cleanup receipt. + +## Phase 4: Verify and record evidence + +For each checkbox, complete all four gates before marking it done: + +1. Plan reread: confirm the checkbox and acceptance criteria. +2. Automated verification: run tests, typecheck, lint, build, or the plan-specific equivalent. +3. Manual-QA channel: capture a real artifact, not a dry-run claim. +4. Cleanup: close temporary processes, tmux sessions, browser contexts, ports, containers, and temp directories. + +Append evidence to `.omo/start-work/ledger.jsonl` using one JSON object per line. Include at least `event`, `plan`, `task`, `session_id`, `commands`, `artifact`, and `cleanup` fields. + +## Phase 5: Mark progress + +Only after verification passes: + +1. Edit the plan checkbox from `- [ ]` to `- [x]`. +2. Re-read the plan and confirm the remaining count decreased. +3. Append a `task-completed` ledger entry. +4. Continue with the next checkbox. Do not ask whether to continue. + +## Completion + +When all top-level checkboxes in `## TODOs` and `## Final Verification Wave` are complete: + +1. Run the plan's final verification commands. +2. If worktree mode was used, sync `.omo/` state back to the main repo, merge or hand off exactly as requested, and remove the worktree only after successful merge or explicit handoff. +3. Remove or mark the Boulder work as completed. +4. Print an `ORCHESTRATION COMPLETE` block with the plan path, verification commands, artifacts, and cleanup receipts. + +## Hard rules + +- No production change before a failing test or reproduction exists. +- No `--dry-run` as completion evidence. +- No tests-only completion claim. A Manual-QA artifact is required. +- No unprefixed session ids in Boulder state. Codex sessions are always `codex:`. +- No stale-memory execution. The plan and ledger are the durable source of truth.