---
name: work-plan
description: Decompose a build objective into governed runx execution steps.
runx:
  category: authoring
---

# Work Plan

Turn a build or automation objective into a bounded governed work plan.

For cross-repo or cross-surface work, the output must be a phased
`workspace_change_plan`, not just a loose list of steps. The shared plan is the
thing that keeps repo-local workers aligned when one issue fans out into
multiple mutation surfaces.

When the objective originates from an existing thread, treat that thread
as provider-backed thread. GitHub issues, chat threads, support
tickets, and local agent sessions are adapter examples, not core nouns. The
plan should preserve the generic `thread_locator` and any supplied
`thread`.

The central insight: split at governance boundaries, not cognitive boundaries.
A skill keeps its full context window. If two actions need the same context
but different scopes, they are two invocations of the same skill with
different scopes — not two separate skills. The graph defines where authority
changes, where mutation happens, and where a gate needs to approve. That is
where steps break.

Work backward from the deliverable. Name the concrete artifact the objective
produces (spec, patch, PR, docs site, report). Then identify where authority
narrows: read-only analysis, write-access mutation, approval gates, review
boundaries. Each narrowing is a step boundary. Each step gets only the scopes
it needs — no step inherits from a prior step, each derives from the graph
grant independently.

Determine data dependencies between steps. A step that consumes output from
a prior step must come after it. Steps with no data dependency are candidates
for fanout. Do not parallelize steps that share mutation targets.

If the objective is ambiguous or required context is missing, surface open
questions explicitly rather than guessing. Open questions should name what
is missing, why it matters, and who can answer it.

Prefer fewer steps with clear scope boundaries. Three well-scoped steps
beat seven single-purpose fragments. Every step should have a clear entry
condition, action, and exit artifact.

## Quality Profile

- Purpose: turn an objective into a governed plan that preserves authority,
  evidence, and handoff boundaries.
- Audience: operators, reviewers, and downstream lanes that must execute from
  the same parent change artifact.
- Artifact contract: change set, objective summary, workspace change plan,
  orchestration steps, required skills, and open questions.
- Evidence bar: derive the plan from the objective, thread, change set,
  project context, and known repo surfaces. Missing context becomes an open
  question, not an invented phase.
- Voice bar: precise engineering planning. Do not create generic task lists or
  cognitive-step decomposition that ignores scope boundaries.
- Strategic bar: the plan should make the smallest governed path obvious:
  reply, plan, build, fan out, pause, or stop.
- Stop conditions: return `needs_agent` when the objective, target
  surfaces, success criteria, or mutation boundaries are unclear.

## Output

- `change_set`: the parent change artifact inherited from intake or constructed
  for the objective when intake did not already produce one. It should preserve
  the shared objective, target surfaces, invariants, and success criteria.
- `harness_context`: when supplied, the same `runx.receipt.v1` packet with state
  advanced to `planning_ready` or `blocked`. Preserve source events, dedupe,
  and triage fields rather than reconstructing them from prose.
- `objective_summary`: one sentence capturing the deliverable.
- `workspace_change_plan`: phased plan for the whole change set. It must
  contain:
  - `plan_id`
  - `change_set_id`
  - `objective_summary`
  - `shared_invariants`
  - `success_criteria`
  - `phases`: ordered array. Each phase:
    - `id`
    - `name`
    - `depends_on`: prior phase ids
    - `parallelizable`: boolean
    - `repo_change_requests`: ordered array. Each request:
      - `repo`
      - `task_id`
      - `objective`
      - `depends_on`: sibling repo change request ids this request waits on
      - `shared_context_refs`: references into the parent change set or prior
        phase outputs
      - `validation_commands`
      - `mutating`
  - `integration_checks`: cross-repo checks that must pass before the overall
    change set is considered done
  - `open_questions`
- `orchestration_steps`: canonical execution view of the plan as an ordered array.
  Each step:
  - `id`: kebab-case identifier
  - `skill`: skill name or path
  - `scopes`: scope strings this step requires
  - `mutating`: boolean
  - `inputs`: static input map
  - `context_from`: `step_id.output_field` data dependency references
  - `description`: what this step does and produces
- `required_skills`: skill names needed. Flag which exist vs need creation.
- `open_questions`: missing context that must be answered before mutation.

## Inputs

- `objective` (required): the build or skill objective to decompose.
- `project_context` (optional): repo, product, or user context that
  constrains the decomposition.
- `change_set` (optional): parent change artifact from `issue-intake` or a
  workspace supervisor. Prefer this when present.
- `harness_context` (optional): portable issue control-plane packet from intake.
  Preserve it as state, not as a prose handoff.
- `thread_locator` (optional): canonical locator for the bounded thread the
  plan is serving.
- `thread` (optional): portable thread when the objective is
  grounded in an existing issue, chat, ticket, or other adapter surface.
