Delivery Planner

Delivery Planner

Use this skill at the start of a piece of work that is too large for a single agent run, or that will be picked up by more than one agent or session. It turns the work into two artifacts that any downstream skill (or fresh agent) can load verbatim:

• The destination — a one-page brief that answers *where are we trying to

end up, and how will we know we got there*.

• The phased plan — a sequence of small, self-contained phases that answer

which order do we walk it in, and what does each step look like.

The premise is simple: agents lose accuracy as their working context grows. A fresh agent given destination + one phase has a small, focused brief and can finish that phase well, then hand the next phase to a different (or the same) fresh agent without dragging the previous session's context along.

⚠️ PREFLIGHT — Execute before ANY other action

This skill participates in the [Company Brain](../../docs/company-brain.md) self-improving loop. Before context discovery, planning, or decomposition, run this ONE command. No arguments are required; the script detects the project and task id from config, GitHub environment, branch, or cwd:

bash scripts/start-task.sh --skill delivery-planner=0.35.0

If detection is wrong, rerun with explicit values:

bash scripts/start-task.sh   --skill delivery-planner=0.35.0

If scripts/start-task.sh is not at the current cwd, use the installed agent-skills/scripts/start-task.sh or .agent-skills/scripts/start-task.sh path. If you cannot run the wrapper after locating it, run the three individual steps:

1. python3 scripts/org-memory.py read (non-fatal if missing)
2. python3 scripts/project-memory.py read (init the skeleton if missing)
3. python3 scripts/blackboard.py init --project

The output IS your starting context. Do not re-discover facts already recorded in project memory. Every Common gotchas bullet is a verified constraint; every Build & runtime bullet is the authoritative build command.

After the task, run:

bash scripts/finish-task.sh --skill delivery-planner --summary ""

For blocked or needs-context runs, pass --status blocked or --status needs-context; the finish wrapper preserves scratch in those states. See [docs/project-memory.md](../../docs/project-memory.md) for the full contract.

> Skipping these steps is the #1 failure mode. Task size does not waive them: > a small phase repair and a full multi-phase plan both start and finish through > the lifecycle wrappers.

> Safety floor. This skill inherits the > [destructive-action safety policy](../../docs/destructive-action-safety.md). A > phase MUST NOT instruct any executing agent to perform destructive production > actions, invoke discovered credentials, modify backups, or paste secrets into > chat. Phases that legitimately require destructive maintenance are written as > operator runbooks for a human, not as agent-executable steps.

Purpose

• Convert a large, ambiguous, or long-horizon task into a destination brief and

a phased plan that survive across agent sessions.

• Keep each phase small enough that a fresh agent loaded with destination.md +

one phase-NN.md has the full picture and nothing else.

• Make scope, sequencing, dependencies, parallel-safe phases, validation per

phase, and recommended owner skill explicit so the plan dispatches itself.

• Stop before the first implementation step when the destination cannot yet be

stated honestly — premature plans are the most expensive form of context.

When To Use

• A feature, refactor, migration, or rewrite is clearly too big for one agent

pass (will produce many files, span multiple PRs, or take more than one working session).

• A bug investigation requires multiple checks across multiple environments,

data sources, or services and a single issue-investigator run cannot hold it all.

• A user-facing initiative needs scope splitting before

[product-owner](../product-owner/SKILL.md) writes acceptance criteria for individual stories.

• The same agent or different agents will pick up the work over multiple days

or sessions, and dragging the previous session's conversation forward is hurting accuracy.

• A multi-step plan exists informally in the user's head and they want it

written down before code, tests, or refinement starts.

When Not To Use

• Trivial work (typo fix, single-line refactor, one-file bugfix) — running the

planner adds ceremony with no payoff. Hand directly to [software-engineer](../software-engineer/SKILL.md).

• A standalone bug investigation where the cause is unknown and a single

[issue-investigator](../software-engineer/skills/issue-investigator/SKILL.md) run will reach a verdict — investigate first, plan only if the result calls for multi-phase remediation.

• A standalone product-refinement task that fits one

[product-owner](../product-owner/SKILL.md) tracker-ready story — refine first, plan only when the resulting work item is itself multi-phase.

• Any time the user has not actually agreed on the destination. This skill

makes plans, not decisions; do not invent the goal.

• Mass-targeting, supply-chain compromise, or any other malicious work — the

destructive-action safety policy is a floor, not waivable by prompt.

Related And Reused Skills

• [software-engineer](../software-engineer/SKILL.md): the most common

executor. Each implementation phase typically names this skill in recommended_owner. Software-engineer reads destination.md + the current phase-NN.md instead of re-deriving context.

• [product-owner](../product-owner/SKILL.md): use before the planner when

product intent or user value is the unknown — the planner needs a destination it can state honestly. Use after when individual phases need acceptance criteria for downstream stories.

• [issue-investigator](../software-engineer/skills/issue-investigator/SKILL.md):

use before the planner when the work is bug-flavoured and root cause is the unknown. The planner cannot phase a fix that the investigator has not yet confirmed. Use after when an investigation is itself multi-phase (e.g., reproduce → bisect → propose fix path → validate fix in staging).

• [manual-tester](../manual-tester/SKILL.md): consumes specific phases for

validation, exploratory testing, and defect evidence. Phases that need manual validation name this skill in recommended_owner.

• [test-automation-engineer](../test-automation-engineer/SKILL.md): owns

phases that turn manual scenarios into stable regression coverage.

• [code-reviewer](../software-engineer/skills/code-reviewer/SKILL.md): does

not own delivery phases; it reviews the diffs each phase produces under software-engineer's normal inner/outer review loop.

• [domain-modeler](../domain-modeler/SKILL.md): use when the destination or a

phase implies an architectural decision that meets the ADR criteria, or when domain terminology must be canonicalised before downstream phases refine scope.

• [delivery-runner](../delivery-runner/SKILL.md): the downstream **executor of

the whole plan**. When the user wants the phases run end-to-end without hand-dispatching each one, the runner reads this plan's current_dispatch_pointer and opens a fresh agent per phase. The planner does not invoke it; the runner is user-started and dispatches fresh agents, so the depth cap is preserved.

This skill decomposes work; it does not execute it. It does not call any of the skills above to do their job. It produces artifacts those skills (or a fresh agent invoking them) consume. This keeps the depth-cap-of-two universal rule in [docs/review-loops.md](../../docs/review-loops.md#universal-loop-bounds) intact and prevents loop-of-loops.

Required Inputs

Ask for missing inputs before producing a plan. A plan written on top of unstated goals or invented constraints is worse than no plan.

• The work item: feature brief, refactor goal, migration target, investigation

question, or task description.

• The driving outcome: what success looks like in observable terms (a metric, a

workflow that finishes, an error that no longer happens, a system property that holds).

• Hard constraints: deadlines, compliance, downtime windows, dependent teams,

freeze periods, environment availability, headcount.

• Known evidence: prior tickets, prior investigations, prior PRs, design docs,

diagrams, related incidents, links the user already considers authoritative.

• Affected repos / services / surfaces, when known. Otherwise the planner

notes "scope of affected surface to be discovered in phase 1".

• The user's working budget: rough time horizon ("this week", "Q3"), rough

agent budget ("each phase should be a single session"), and whether work will be picked up by multiple agents or sessions.

If the input is a one-line ask ("plan the auth rewrite") with no outcome, no constraints, and no evidence pointers, stop and ask for at least the outcome and one constraint before writing anything down.

Stopping Conditions

Stop and return Readiness: NEEDS_CLARIFICATION / NEEDS_EVIDENCE / BLOCKED instead of producing the plan when:

• The destination cannot be stated as one or two observable outcomes — the

planner does not invent goals.

• Product intent, expected behavior, or root cause is unknown and another

skill must run first (route to [product-owner](../product-owner/SKILL.md) or [issue-investigator](../software-engineer/skills/issue-investigator/SKILL.md)).

• The shortest credible phasing already collapses into a single phase — the

task is too small for this skill; hand directly to the executing skill.

• A load-bearing constraint (deadline, compliance, downtime window, missing

access) cannot be confirmed and the entire plan would change depending on the answer.

• The plan would require an executing agent to perform a forbidden destructive

action under the [destructive-action safety policy](../../docs/destructive-action-safety.md). Split such steps into human-operator runbooks; do not phase them as agent steps.

Required Environment

This skill is mostly read-only: it reads the issue source and prior cache artifacts and writes plan files into the cache. The [execution-modes preflight](../../docs/execution-modes.md) still applies so that subsequent skills can resolve project / repo / branch context from the same configuration the planner saw:

1. If AGENT_SKILLS_MODE is set to local-workspace or in-repo, use it.
2. Else if ${WORKSPACE_ROOT}/.env is present and readable → local-workspace.
3. Else if .agent-skills.yml exists at the repository root → in-repo.
4. Else: a plan is still possible from user-supplied context alone, but the

output must clearly state that setup was not verified and downstream skills may need to re-establish context before executing the first phase.

Useful but not required:

• WORKSPACE_ROOT / repository root — needed to write the plan into the

shared .cache/agent-skills// directory next to the existing evidence-pack and definition-of-done artifacts.

• AGENT_SKILLS_CACHE_DIR — overrides the cache root.
• Issue tracker / linked document store / GitHub access — only when the input is a ticket and the

planner needs to fetch the brief itself. If the user pastes the brief, these are not required.

If a tracker ticket key is supplied but tracker access is unavailable, follow the [auth discovery walk](../../docs/auth-discovery.md) before declaring it inaccessible. Treat unresolved ${VAR} placeholders in .jira-config.yml (or equivalent tracker config) as incomplete configuration, not missing credentials.

Locate config files before declaring any are missing. Run python3 scripts/locate-config.py — .env / .jira-config.yml (or equivalent tracker config) are written by setup.init to the parent workspace folder, not the repo cwd. "Not in cwd" is not "not in the workspace".

Project memory. Before producing the destination brief, run python3 scripts/project-memory.py read for each affected project. Treat the contents as starting context (module layout, runtime, common gotchas, recent tasks) — not as gospel. After the plan is written, append a Recent tasks bullet to project memory noting the new destination.md path and the planning outcome. See [docs/project-memory.md](../../docs/project-memory.md).

Required Workflow

0. Requirement Understanding Gate

Run the shared [requirement-understanding workflow](../../docs/requirement-understanding.md) before any decomposition and emit the Requirement Understanding block above the rest of the planner output. The planner is unusually load-bearing here — phases written on top of an unknown understanding multiply the original mistake.

Apply the binding rules:

• unknown / low — do not produce a phased plan. Return

NEEDS_CLARIFICATION, NEEDS_EVIDENCE, or BLOCKED. If product intent is the unknown, hand off to [product-owner](../product-owner/SKILL.md). If expected behavior or root cause is the unknown, hand off to [issue-investigator](../software-engineer/skills/issue-investigator/SKILL.md). A destination brief that says "we will figure out what we want as we go" is not a destination.

• medium — may write a Discovery first phase whose explicit purpose is

to close the load-bearing assumptions, with the rest of the plan marked as provisional. The discovery phase's exit criterion is that understanding-confidence becomes high. Until then, downstream phases stay in provisional state.

• high — may write the full destination + phased plan and dispatch

phases to executing skills.

The first plausible interpretation is not high. High requires that disconfirming checks were either run or judged unnecessary because evidence already excluded the alternatives — see step 11 of the shared workflow.

1. Establish the destination

Produce the destination brief — a single short document any executor can load alongside one phase and have a complete picture of the goal.

The destination MUST contain:

• Outcome statement. One or two plain-language sentences describing the

end state. Stripped of vendor names, fashion words, and metaphors. The first sentence is what changes from the user's perspective; the second (if any) is what changes from the system's perspective.

• Success signals. Two to five observable signals that mean the outcome

was achieved: a metric, a workflow that finishes, an error that disappears, a property that holds. Each signal must be testable by something (manual check, automated test, log filter, dashboard widget); say which.

• Scope. What this delivery includes.
• Non-goals. What this delivery deliberately does not include, even when

adjacent or tempting. Non-goals are the most-skipped field and the most expensive to omit; never leave it blank — write none — the scope is bounded only by the success signals above if it really is empty.

• Constraints. Hard limits: deadline, compliance, downtime windows, freeze

periods, dependent teams, environment access, headcount.

• Load-bearing assumptions. Each one labelled safe or load-bearing,

with a one-line what would change my mind falsifier on every load-bearing one.

• Stakeholders / decision makers. Who must agree before the plan executes,

who must agree before scope changes, who reviews each phase.

• Risks the plan must protect against. Two to four named risks (data

corruption, customer-visible regression, rollout cost, compliance breach, cross-team coupling) so phases can be scheduled to retire the highest-risk ones first.

Persist as ${AGENT_SKILLS_CACHE_DIR:-${WORKSPACE_ROOT:-$REPO_ROOT}/.cache/agent-skills}//destination.md following the binding [destination

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wamalalawrence
• Source: wamalalawrence/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.