software-delivery-orchestrator

Software Delivery Orchestrator

Overview

Turn a product requirement into a controlled delivery workflow with explicit artifacts, a requirement challenge gate, minimal context handoff, multi-pass review, and documentation sync.

Always prefer small, auditable loops over one large speculative implementation.

Read supporting files only when needed:

• references/artifact_governance.md: root-level artifact paths, naming, ownership, update timing
• references/runtime_policies.md: required subagents, waiting rules, timeout and retry behavior, dispatch visibility
• references/bootstrap_checklist.md: repo bootstrap checklist
• references/output_templates.md: artifact templates
• references/review_rubric.md: review rubric

Workflow Decision Tree

1. Need repository rules or project context first? If durable repository rules or project context docs are missing or stale, run the repository rules and project context workflow before anything else.
2. Need task-scoped repo localization first? If the current task does not yet have a trustworthy repo brief, run the task-scoped bootstrap workflow before planning implementation.
3. Need requirement viability first? Run the requirement intake and challenge gate after task-scoped bootstrap and before requirement analysis. Do not treat the user's requested implementation as automatically approved scope.
4. Need requirement clarification? Run the requirement analysis workflow only after the gate returns go. If the user resolves a prior clarify or no-go outcome, re-run the gate and wait for a resolved go before continuing.
5. Need implementation? Only start implementation after a canonical product spec, a successful gate result, and a technical plan exist.
6. Need review or re-review? Run the review workflow on the current diff or commit range, then either fix findings or explicitly document and accept any remaining exceptions before declaring the change ready.
7. Need docs to stay accurate? Start the documentation sync workflow and the knowledge capture workflow during the review loop as separate draft-producing subagent tracks, then keep both synchronized with the latest accepted diff.
8. Need long-term knowledge capture or PR updates? Do not proceed to PR or finalization until review is clean under the current blocking / important plus accepted-exception rule, and both documentation tracks are finalized against the latest accepted code and validation results.

Non-Negotiable Operating Rules

• Treat the workflow as a pipeline of artifacts. Do not pass long discussion transcripts to the next stage when a concise structured artifact is sufficient.
• Prefer reading project rules from the repository itself before inventing conventions.
• Reuse existing repository rules and context artifacts before generating new ones, but always persist the canonical copies under docs/software-delivery-orchestrator/.
• Keep durable documentation split by concern. See references/artifact_governance.md for boundaries and update rules.
• If required subagents are available, use them with minimal shared context. If a required subagent is unavailable in the environment, stop and report the blocker instead of silently falling back to a single-agent workflow. See references/runtime_policies.md.
• If docs/software-delivery-orchestrator/external-doc-sources.md exists, treat it as a supplemental input registry for user-provided external documents. It may inform repository rules, project context, or feature specs, but it does not replace repository-native sources.
• Keep write operations gated. Reading and analysis may run automatically. Local edits and local commits may run automatically. Pushing, opening PRs, merging, or changing external systems should wait for human approval unless the user explicitly requested fully automatic execution and the tool environment supports it.
• Separate the user's goal from the user's proposed implementation. Do not assume the requested mechanism is the correct solution before the requirement gate finishes.
• If the requirement gate returns clarify or no-go, stop downstream planning and implementation until the user resolves the blocker.
• Ask only the minimum blocking questions needed to turn clarify or no-go into a safe next step.
• Record every assumption that allows work to continue. Do not silently fill requirement gaps.
• Review repeatedly until there are no unresolved blocking or important findings, or explicitly document and accept the exceptions that keep work moving.
• Start separate documentation-sync and knowledge-capture subagents during review whenever required subagents are available, and keep their ownership boundaries disjoint.
• If review changes code, tests, or validation results, send the incremental diff and validation delta back to both review-linked artifact subagents and require refreshed outputs before continuing.
• Update documentation whenever the final code diverges from the prior plan or design notes.
• If a change introduces durable product or engineering knowledge, capture it in a stable document or explicitly record why no durable document was updated.
• Do not advance to PR or final completion until review has no unresolved blocking or important findings, or documented exceptions were explicitly accepted, and both documentation tracks match the latest accepted diff.
• Reuse the same subagent within the same stage when artifact path and ownership stay unchanged. Open a new subagent only when stage, artifact, responsibility, or required perspective changes, or when replacement is justified. The review subagent is the explicit exception: use a fresh reviewer for each meaningful review round after code or validation changes.
• Treat subagent reuse as ownership continuity for the same work, not as permission to keep agents resident across later unrelated stages. Initialization subagents are stage-bound, requirement proposer and challenger are feature-spec-bound, implementation and fixer lanes are slice-bound, the review subagent is round-bound, and documentation-sync plus knowledge drafting are artifact-bound through the current feature's review loop.
• Keep the primary agent as the sole coordinator. Subagents may inform each other only through main-agent mediation.

Persistent Artifact Locations

Use these committed paths unless the user explicitly overrides them:

• docs/software-delivery-orchestrator/repo-rules.md
• docs/software-delivery-orchestrator/project-context.md
• docs/software-delivery-orchestrator/external-doc-sources.md when user-provided external documents exist
• docs/software-delivery-orchestrator/specs/<work-type>-<feature-slug>.md
• docs/software-delivery-orchestrator/knowledge/<work-type>-<feature-slug>.md

Treat all listed paths as relative to the repository root. Create the parent directories when missing. Do not keep these artifacts as conversation-only notes. For naming, boundaries, update timing, and what each artifact may contain, read references/artifact_governance.md. The current feature spec path may be created in draft form during the requirement gate and finalized during requirement analysis.

Repository Rules And Project Context Workflow

Run this before bootstrap when durable repository rules or project context are missing, outdated, or untrusted in the current conversation.

1. Ensure the repository-root directories and artifact paths described in references/artifact_governance.md exist or are ready to be created.
2. Search for existing rule and context sources such as README, CONTRIBUTING, AGENTS.md, CLAUDE.md, .cursor/rules, CI workflows, lint configs, test configs, migration docs, architecture docs, ADRs, and product or feature docs already in the repository.
3. If docs/software-delivery-orchestrator/external-doc-sources.md exists, read it and incorporate the validated entries as supplemental inputs during rules and context acquisition.
4. Build or update docs/software-delivery-orchestrator/repo-rules.md and docs/software-delivery-orchestrator/project-context.md using references/output_templates.md, while respecting the content boundaries in references/artifact_governance.md.
5. Cite both repository-native and registered external sources when they materially influenced the result.
6. If either root-level doc is missing, stale, or untrusted, follow the required initialization dispatch policy in references/runtime_policies.md.
7. Finalize both root-level docs before bootstrap or requirement analysis starts.
8. Pass repo-rules.md and project-context.md, not the raw source documents, into later stages.

Task-Scoped Bootstrap Workflow

Run this workflow when the current task does not yet have a trustworthy repo brief, or when the task shifts into a repository area that the existing brief does not cover. Use references/bootstrap_checklist.md as the default checklist.

1. Start from docs/software-delivery-orchestrator/repo-rules.md, docs/software-delivery-orchestrator/project-context.md, and docs/software-delivery-orchestrator/external-doc-sources.md if it exists.
2. Inspect only the repository entry points, modules, quality signals, and related docs that are relevant to the current task.
3. Build a concise repo brief using the template in references/output_templates.md.
4. Extract only the task-local paths, rules, commands, and durable related docs needed later.
5. Save the brief in the conversation and reuse it instead of repeatedly rescanning the repo.
6. When later work touches a new module or service, extend or refresh only the affected local portion of the repo brief.
7. If subagents are available, use them to inspect distinct task-relevant repository areas in parallel once repo-rules.md and project-context.md exist.

Requirement Intake And Challenge Gate

Run this after task-scoped bootstrap and before requirement analysis. The goal is to decide whether the user's request should move forward as-is, be clarified, or be re-scoped before spec finalization.

1. Confirm that docs/software-delivery-orchestrator/repo-rules.md and docs/software-delivery-orchestrator/project-context.md exist and that a repo brief is available.
2. Restate the user's request as two separate items:
   • the user's likely product or workflow goal
   • the user's proposed mechanism, if any
3. Produce a first-pass intake bundle with:
   • user-goal
   • request-shape
   • context-check
   • assumptions
   • missing-context
4. Compare the request against repository rules, project context, existing docs, and likely implementation boundaries. Explicitly call out conflicts, missing acceptance criteria, migration risks, security or compliance concerns, and places where the user may have specified an implementation rather than a goal.
5. If subagents are available, dispatch a dedicated proposer subagent for this gate. The proposer owns:
   • core-pain-points
   • likely-hidden-needs
   • desired-outcome
   • candidate-acceptance-criteria
   • recommended-defaults
6. After the proposer pass returns, dispatch a dedicated challenger subagent for the same current feature-spec challenge. The challenger owns:
   • challenge-summary
   • invalid-assumptions
   • missing-edge-cases
   • unreasonable-constraints
   • acceptance-gaps
   • questions-for-user
   • feasibility-verdict
7. The primary agent remains the sole coordinator. It must first summarize the proposer and challenger outputs into a requirement-conflict-matrix with:
   • accepted
   • rejected
   • assumptions
   • needs-more-analysis
   • needs-user-decision
   • deferred
   • optionally resolved-open-questions when recording decisions that were clarified and closed during the gate
8. If more evidence arrives, or if the primary agent needs deeper analysis on the same owned artifact, send only the delta back to the same proposer or challenger subagent that already owns that responsibility. Do not create a fresh same-role subagent for the same feature-spec challenge unless references/runtime_policies.md says replacement is justified.
9. Classify the gate result as exactly one of:
   • go: safe to continue into requirement analysis
   • clarify: blocked on user confirmation
   • no-go: the request should not be executed as written without re-scoping or an alternative proposal
10. Persist the intake bundle, proposer output, challenger output, and current conflict matrix in the current feature spec draft at docs/software-delivery-orchestrator/specs/<work-type>-<feature-slug>.md, or create the file shell if it does not exist yet.
11. If the verdict is clarify, ask only the minimum blocking questions that are currently classified as needs-user-decision, wait for the user's answers, update the conflict matrix, and re-run the gate before requirement analysis starts.
12. If the verdict is no-go, present the conflict, the alternative or re-scope proposal, and the reason implementation is blocked. Wait for user confirmation, then re-run the gate.
13. Only a resolved go verdict unblocks requirement analysis, technical planning, and implementation.

Requirement Analysis Workflow

Create a canonical product spec before technical planning.

1. Confirm that docs/software-delivery-orchestrator/repo-rules.md and docs/software-delivery-orchestrator/project-context.md already exist at the repository root, that the repo brief exists, and that the requirement gate returned a resolved go verdict. Do not begin requirement analysis before this is true.
2. Start from the persisted intake bundle and current conflict matrix. Restate the request as a product outcome, not as implementation guesses.
3. Run requirement analysis as a serial convergence loop:
   • proposer pass: best-faith interpretation of the requirement, updated only for items currently marked needs-more-analysis
   • challenger pass: edge cases, ambiguity, risks, scope leaks, hidden migration needs, observability gaps, and acceptance problems in that updated proposer output
4. If subagents are available, both passes MUST be performed by separate role-specific subagents. Prefer reusing the same proposer and challenger subagents from the requirement gate when the stage remains requirement work and the owned artifact remains the current feature spec. Follow the waiting rules in references/runtime_policies.md. If required subagents are unavailable, stop and report the blocker.
5. After each serial proposer/challenger pass, the primary agent must update the conflict matrix and classify every tracked item as exactly one of:
   • accepted
   • rejected
   • assumptions
   • needs-more-analysis
   • needs-user-decision
   • deferred
6. Continue internal analysis only for items still marked needs-more-analysis. Ask the user only about items marked needs-user-decision. Run at most 2 internal requirement rounds by default, or 3 for clearly complex tasks; if unresolved items remain after that, escalate the decision to the user instead of continuing the loop. Do not forward raw subagent output directly to the user as the default interaction mode.
7. Resolve the persisted intake bundle, the final proposer/challenger deltas, and the final conflict matrix into one canonical spec using the template in references/output_templates.md, then persist it to the repository-root path docs/software-delivery-orchestrator/specs/<work-type>-<feature-slug>.md.
8. Update docs/software-delivery-orchestrator/project-context.md when the new spec changes the durable project baseline.
9. If docs/software-delivery-orchestrator/external-doc-sources.md contains feature-spec-source entries for the current task, cite them in the spec as supporting inputs rather than replacing the canonical spec itself.
10. Pass only the canonical spec to the technical planning stage.

Technical Planning Workflow

Convert the canonical product spec into an implementation plan.

1. Inspect only the repository areas relevant to the spec, guided by docs/software-delivery-orchestrator/repo-rules.md, docs/software-delivery-orchestrator/project-context.md, and the repo brief.
2. Produce a technical plan using the template in references/output_templates.md.
3. Break the plan into a task graph with explicit dependencies.
4. Freeze contracts before parallel work starts, then identify which tasks can run in parallel and which must stay sequential.
5. Do not begin coding until the plan names the validation commands required for completion.

Implementation Workflow

1. Choose the smallest vertical slice that can prove progress.
2. Do not begin implementation if the requirement gate is unresolved or anything other than go.
3. Load only the canonical spec, the persisted intake bundle, the current conflict matrix when still relevant, the technical plan, docs/software-delivery-orchestrator/repo-rules.md, docs/software-delivery-orchestrator/project-context.md, the repo brief, and the files or rules directly relevant to the current slice.
4. When the plan includes distinct frontend and backend slices, and subagents are available, you MUST dispatch dedicated subagents with explicit ownership after contracts are frozen. Do not implement those parallel slices inline first. Follow references/runtime_policies.md. If required subagents are unavailable, stop and report the blocker.
5. Make the change.
6. Run the narrowest useful checks first, then broader checks:
   • format / lint
   • types
   • focused tests
   • build or integration checks when relevant
7. Record what changed, why, and what still needs review.

Commit and Review Loop

Follow this loop instead of doing one final review at the end.

1. After a coherent implementation slice and basic validation succeed, create a checkpoint commit.
2. Build a review input bundle from the current diff, validation results, canonical spec delta, and technical plan delta.
3. If subagents are available, dispatch one fresh review subagent for the current review round and two separate review-linked artifact subagents:
   • the review subagent owns only the current review pass and must return findings with severity
   • one owns documentation sync targets and draft updates
   • one owns docs/software-delivery-orchestrator/knowledge/<work-type>-<feature-slug>.md and the knowledge delta draft
4. The review subagent must review the current diff using the rubric in references/review_rubric.md. It reviews only; it must not modify code, update docs, or create commits.
5. Classify findings as blocking, important, or nice-to-have.
6. Fix blocking findings first. For important findings, fix unless there is a documented and accepted reason not to. Treat any such documented exception as an explicitly resolved review outcome rather than as an unresolved important finding.
7. Route accepted review findings to a fix or implementer subagent, or handle them in the current implementation lane if no separate fixer is available. The main agent must convert accepted findings into a fix input bundle that names the owned code slice, repair direction, constraints, and validation commands to rerun instead of forwarding raw reviewer output as the execution contract.
8. Treat the fixer as slice-bound rather than round-bound. Reuse the same fixer while the accepted findings bundle, owned code slice, and intended repair direction stay materially the same, even if a fresh reviewer is created for the next review round.
9. Replace the fixer only when the repair direction changes materially, the owned slice expands beyond the original boundary, the main agent repackages findings into a new fix bundle, or repeated validation failure or context drift makes continued reuse unsafe.
10. The fixer owns code changes, validation reruns, and any resulting fixup commit. If no separate fixer is available, the current implementation lane inherits these same obligations and boundaries for that repair slice.
11. The fixer must not review its own work, finalize docs or knowledge artifacts, or silently expand the repair scope beyond the accepted findings bundle without main-agent approval.
12. Whenever review produces a code, test, or validation change, send the incremental diff and updated validation evidence to the same documentation-sync and knowledge subagents and treat earlier drafts as stale until refreshed.
13. Re-review only the incremental diff plus any affected tests or docs, using a fresh review subagent for each meaningful review round after code or validation changes.
14. Do not finalize docs or knowledge artifacts while the latest review round still has unresolved blocking or important findings.
15. Stop the loop only when there are no unresolved blocking or important findings, the acceptance criteria are met, and both review-linked artifact subagents have finalized outputs against the latest accepted diff, or when documented exceptions were explicitly accepted.
16. Do not keep a consumed reviewer resident after its round, and do not carry any completed subagent into later unrelated stages once its owned artifact or slice has been finalized.
17. Before opening a PR, prepare a clean final history plan: keep checkpoint and fixup commits during the loop, then recommend squash or interactive rebase if the target repo prefers a cleaner history.

Documentation Sync Workflow

Start this during the review loop and keep it in draft mode until the latest review round is accepted.

1. Compare the canonical spec, technical plan, latest accepted code diff, and latest validation results.
2. Decide whether the mismatch means:
   • the code is wrong and must be fixed, or
   • the plan or docs are stale and must be updated
3. Drive this workflow with a dedicated documentation-sync subagent when required subagents are available, and keep its file ownership disjoint from the knowledge subagent.
4. Update the relevant design notes, ADRs, README fragments, migration notes, changelog entries, or PR description as draft artifacts while review is still open.
5. If review changes code, tests, or validation evidence after a draft was produced, refresh the documentation output from the new diff before treating it as current.
6. Review whether the repository-root docs docs/software-delivery-orchestrator/repo-rules.md or docs/software-delivery-orchestrator/project-context.md also need updates because the final implementation changed durable repository rules or project baseline.
7. Treat project-native docs outside docs/software-delivery-orchestrator/ as supplemental. Updating them does not satisfy the required root-level artifacts.
8. Never leave the final code and final docs silently divergent, and do not mark this workflow complete until the current review round is accepted and the draft has been refreshed against the latest accepted diff.

Knowledge Capture Workflow

Start this no later than the first review round that produces a coherent accepted diff plus validation evidence, but keep the output in draft mode until review and documentation sync have converged on the latest accepted diff.

1. Compare the latest accepted code, canonical spec, technical plan, validation results, and documentation updates.
2. Decide whether the change created knowledge that should outlive the current task.
3. Prefer updating an existing durable document before creating a new one. When the knowledge belongs to the current feature, create or update the repository-root file docs/software-delivery-orchestrator/knowledge/<work-type>-<feature-slug>.md.
4. Update docs/software-delivery-orchestrator/project-context.md when the finished feature changes the durable project baseline, feature inventory, or related-doc index.
5. Produce a concise knowledge delta using the template in references/output_templates.md so later stages can reuse only the durable changes.
6. If no durable knowledge artifact was updated, record the reason explicitly rather than silently skipping the step.
7. If subagents are available, you MUST dispatch a dedicated knowledge subagent during review to identify durable documentation targets or draft the knowledge update. Follow references/runtime_policies.md. If required subagents are unavailable, stop and report the blocker.
8. If review changes code, tests, or validation evidence after a knowledge draft exists, send the incremental diff and updated validation evidence back to the same knowledge subagent and refresh the draft before finalizing it.
9. Project-native docs outside docs/software-delivery-orchestrator/ may also be updated for humans, but they do not replace the required root-level knowledge artifact.
10. The primary agent must verify final consistency against the latest accepted code and validation evidence before declaring the stage complete.

PR Workflow

When the environment supports Git hosting tools and the user wants a PR:

1. Summarize the final change in user-facing language.
2. Include implementation notes, risks, migrations, feature flags, and test evidence.
3. Include documentation sync and knowledge capture outcomes, including updated paths under docs/software-delivery-orchestrator/, when they materially affect future maintainers.
4. Include known follow-ups separately from the merged scope.
5. Use the PR template in references/output_templates.md.
6. If opening the PR is not possible in the current environment, draft the exact title and body.

Context Minimization Rules

To reduce token usage and keep reasoning sharp:

• Carry forward artifacts, not transcripts.
• Prefer docs/software-delivery-orchestrator/repo-rules.md, docs/software-delivery-orchestrator/project-context.md, repo brief, intake bundle, requirement-conflict-matrix, canonical spec, technical plan, task graph, review findings, knowledge delta, and final PR summary over raw conversation history.
• For review, use the diff, affected file rules, acceptance criteria, and test results.
• For doc updates, use the latest accepted plan delta, latest accepted diff, and latest validation results.
• Re-open the repository only for touched paths or when a finding suggests the original repo brief is incomplete.
• For waiting-window behavior while required subagents are in flight, follow references/runtime_policies.md.

Subagent Allocation Rules

Use required and optional subagents according to references/runtime_policies.md.

• Required: repository rules acquisition, project context acquisition, requirement-gate proposer support, requirement-gate or requirement-analysis challenger support, split frontend/backend implementation when the plan contains distinct slices, a fresh review subagent for each meaningful review round, review-linked documentation sync support, and review-linked knowledge drafting support.
• Preferred: bootstrap partitioning, test generation or validation, and specialist review passes.
• Always send the minimum necessary artifact bundle.
• Reuse an existing subagent with follow-up input when the stage, artifact path, and ownership remain the same. Spawn a new subagent only for a new stage, a new owned artifact, a new required perspective, or a justified replacement. The review subagent is the explicit exception and must be fresh for each meaningful review round after code or validation changes.
• Do not treat subagents as globally resident. Initialization work ends with finalized root docs, requirement work ends with a finalized canonical spec, implementation and fix lanes end with a completed slice, and review-linked documentation or knowledge lanes end with artifacts finalized against the latest accepted diff for the current feature.
• Always keep documentation sync and knowledge drafting ownership disjoint and route review-driven code deltas back to both when their drafts become stale.
• Route cross-subagent coordination through the primary agent rather than direct subagent-to-subagent collaboration.
• Always report the stage, owned scope, expected artifact path, and return status.

Completion Criteria

Declare the workflow complete only when all of the following are true:

• docs/software-delivery-orchestrator/repo-rules.md exists and reflects current repository rules
• docs/software-delivery-orchestrator/project-context.md exists and reflects the current project baseline
• docs/software-delivery-orchestrator/specs/<work-type>-<feature-slug>.md exists for the current feature
• the requirement intake and challenge gate completed with a recorded go verdict, explicit assumptions, a persisted conflict matrix, and any blocking user questions resolved
• a canonical spec exists
• a technical plan exists
• code changes are implemented or explicitly deferred
• validation results are reported
• review loop is complete with no unresolved blocking or important findings, or documented exceptions were explicitly accepted
• the documentation sync output is finalized against the latest accepted diff
• docs/software-delivery-orchestrator/knowledge/<work-type>-<feature-slug>.md exists or an updated durable knowledge path is explicitly reported
• the knowledge artifact is finalized against the latest accepted diff
• required subagent dispatches were performed and reported
• documentation and knowledge artifacts reflect the final code, or explicit exceptions are documented
• PR artifacts reflect the final code

Response Style

When using this skill, stay operational and artifact-first.

• Label the current stage.
• Show the current artifact or delta.
• Keep rationale concise.
• Surface blockers early.
• Prefer checklists and structured sections over long prose.