Os Task Prep

os-task-prep

Productizes the loop: find open Issues -> diagnose against the code -> map cross-Issue dependencies and blockers -> enrich the Issue on the platform -> (optionally) assign -> emit repo-build-pr prompts so autonomous ("AFK") agents can pick them up with full context.

It composes two existing skills and adds the one capability they lack:

• os-platform (read-only + issues take): list/show Issues, and assign.
• repo-build-pr: the per-Issue implementation loop the emitted prompts target. Invoke it directly (/repo-build-pr); the old /build alias is deprecated -- do not emit it.
• scripts/enrich_issue.py (this skill): the only mutation os-platform does not provide -- PATCH /v1/orgs/{org}/bounties/{number} to append diagnosis notes to body_markdown, idempotently and append-only.

Prerequisites

• OS_PLATFORM_API_KEY must be set in the environment (see the os-platform skill). Never ask the user to paste it into chat; never echo it.
• Run from a checkout of open-software-network/os-clovy so the diagnosis step can read the real code.
• The default org/project come from os-platform.json (org, limit).

Workflow

1. Find ready-to-code Issues

Use the os-platform skill. Default to the narrowest actionable queue:

python3 .claude/skills/os-platform/scripts/os_platform.py issues list <org> --status todo --limit 30

Pick candidates that are genuinely ready to code, not just status: todo:

• Prefer creator.kind: "integration" / well-specified reports with clear expected behavior over raw creator.kind: "user" reports that need triage.
• Prefer tight, self-contained scope. Flag overlap: Issues that touch the same large file (e.g. AgentWorkspace.tsx) will conflict if run in parallel worktrees -- note which to serialize.
• Skip design-only / question / vague Issues unless asked.
• Honor assignment hints: surface unassigned or already-yours first.

State how many you selected and why; log anything you dropped.

2. Diagnose each against the codebase (parallel, read-only)

Spawn one Explore subagent per Issue. Give each the Issue title + body and ask for Files (file:line), Root cause / site, Implementation sketch, Acceptance criteria, Verify. Demand real file_path:line references and an explicit "evidence thin" note when unsure. These agents must not edit anything.

This diagnosis is what makes the Issue AFK-ready: a fresh agent that has never seen the repo gets the root cause and the exact edit site for free.

3. Map dependencies and blockers (cross-Issue pass)

After diagnosing, look across the selected Issues -- not just within each one. This is the difference between "five tickets" and "a plan": an agent that knows it shares a file with another in-flight Issue can rebase deliberately instead of producing a doomed parallel diff.

• Shared-file conflicts. Build a file-overlap matrix from the diagnoses. Issues that edit the same file (e.g. several touching AgentWorkspace.tsx) collide if run as parallel worktrees. Mark them to serialize and pick an order (smallest / most-foundational change first).
• Logical dependencies. Does one fix need another to land first -- a shared helper, a refactor that must precede the rest? Record depends-on: JUN-XXX.
• External blockers. Anything that stops an agent finishing autonomously: a needed design decision, a product question, an API/backend change, a missing fixture. Record blocked-by: <what> so it is not dispatched blind.

Carry these findings into both the enrichment (step 4) and the dispatch order (step 6). When nothing applies, say so explicitly ("independent, parallel-safe").

4. Enrich the Issue description on the platform

For each Issue, distill the diagnosis into a markdown block beginning with the marker line, then append it with the bundled script:

# notes.md starts with: ## Implementation notes (investigated by agent for @<handle>)
python3 .claude/skills/os-task-prep/scripts/enrich_issue.py \
  --org <org> --number <n> --notes-file notes.md

Rules baked into the script (do not work around them):

• Append-only under a --- rule; the reporter's original text is preserved.
• Idempotent: re-runs skip if the marker is present. Use --replace to regenerate the section after a better diagnosis.
• Sets User-Agent: os-platform-agent-skill/1.0 -- the default urllib UA is Cloudflare-blocked (HTTP 403, "error code: 1010").
• Verifies the marker is present after PATCH and reports the new length.

Include a Dependencies / blockers line carrying the step 3 findings, e.g. **Dependencies / blockers:** serialize with JUN-114/116/117 (shared AgentWorkspace.tsx); depends-on: none; blocked-by: none. Write "none -- independent" when the Issue is genuinely standalone.

Keep notes tight and end with a drift caveat, e.g. _Investigated against os-clovy @ <sha>. Line refs may drift; confirm before editing._

Use plain hyphens, not en/em dashes, per repo copy conventions.

5. Optionally assign to the current user

Only when the user asks ("assign me"). Use the os-platform skill -- it is the blessed mutation path and also moves todo -> in_progress, which prevents a teammate double-claiming an Issue an agent is about to work:

python3 .claude/skills/os-platform/scripts/os_platform.py issues take <org> <n> --yes

--yes only when the user has already confirmed in chat. issues take refuses non-todo Issues, so enrich first (enriching does not change status). Tell the user assignment also flips status to in_progress and is reversible.

6. Emit the dispatch table

Output a table the user can copy, one row per Issue, carrying (a) the dispatch order / deps from step 3 and (b) a one-line prompt that invokes the build skill, references os-platform for Issue context, and states the root cause. Match the skill-trigger prefix to the runtime the agents run in:

• Claude Code triggers skills with /: /repo-build-pr /os-platform JUN-113 ...
• Codex CLI triggers skills with $: $repo-build-pr $os-platform JUN-113 ...

The user dispatches AFK agents via Codex, so the $ form is usually operative; the Claude / form is the same line with the prefix swapped. Lead with the parallel-safe rows; group serialized rows and number their order.

| Issue | Order / deps                                | Codex ($)                                                                 |
| ---   | ---                                         | ---                                                                       |
| JUN-114 | parallel-safe (CSS only)                  | $repo-build-pr $os-platform JUN-114 trim action-control padding to tokens |
| JUN-113 | serialize 1/3 -- shares AgentWorkspace.tsx | $repo-build-pr $os-platform JUN-113 onBranch ignores part.sessionId ...   |

Format: <prefix>repo-build-pr <prefix>os-platform <ISSUE-ID> <one-line root cause / fix direction>, where <prefix> is / for Claude Code and $ for Codex. The one-liner is the single most useful sentence from the diagnosis -- the same sentence a reviewer would want at the top of the PR. (/build is the deprecated alias for repo-build-pr; never emit it.)

Safety

• Enrichment mutates a shared production tracker. Append, never overwrite; confirm the PATCH path on one Issue before fanning out if unsure.
• Assignment is optional and user-gated.
• Do not print or persist OS_PLATFORM_API_KEY.
• The enrich_issue.py PATCH is intentionally the only write here beyond os-platform's issues take. Do not add more mutations without being asked.