/orchestrating-software-dev

name: orchestrating-software-dev
description: Runs software development projects from idea to completion. Use when starting a software project, adding a feature, fixing a bug, or resuming an in-progress build.

Orchestrating Software Development

The orchestrator's handbook for running software projects with rageatc-code-oss: which tier to select, which agents and skills to invoke at each stage, and how to respond at every decision point. The orchestrator coordinates; agents execute. How agents do their work lives in their preloaded skills and agent definitions — never restated here.

**Orchestrator-owned stages.** Four stages are executed directly rather than delegated, because the artefact depends on holding the full project picture (or live dialogue with the user) that delegation would lose:

• **Stage 1 — Product Definition** (managing-product): dialogic requirements extraction
• **Stage 4 — Interface Design** (designing-interfaces): dialogic; only when the project has a UI
• **Stage 6 — Enrichment** (enriching-roadmap): needs PRD, architecture, and all chunk relationships simultaneously
• **Stage 7 — Planning** (planning-software): needs the full enriched roadmap to produce a coherent contract

If context window limits bite, session resumption via project files (ORCHESTRATION-PLAN.md, ORCHESTRATION-LOG.md) is the safety net.

---

Tier Selection

Select the tier before invoking any agent; it governs depth at every subsequent stage.

| Tier | Use when | |------|----------| | **Quick** | Bug fix, small isolated change, 1-3 files, no new architectural decisions | | **Standard** | New feature, moderate complexity — this is the default | | **Thorough** | Greenfield project, cross-cutting change, complex system, multiple components |

**Signals for Quick:** single component, reversible, no new dependencies, scope clear without upstream work. **Signals for Thorough:** greenfield, new architectural territory, multiple components with shared interfaces, significant non-functional requirements, parallel workstreams. When in doubt, start Standard.

Record the selected tier and justification in the orchestration log before proceeding.

---

Lifecycle Stages

Stage 0 — Upstream Entry

rageatc-code-oss sits downstream of rageatc-core-oss's thinking pipeline; the handoff point is when solutioning determines the solution is a software product.

• **Thorough:** run `/shaping` (ideating → understanding-the-ask → solutioning) before Stage 1. Output is concept_v1.md with a decision record.
• **Standard:** run `/shaping` only when direction is unclear; skip if the user arrives with a specific, bounded request.
• **Quick:** skip.

Stage 1 — Product Definition

Apply the `managing-product` skill (orchestrator-led dialogue). Pass the workflow tier — it calibrates PRD depth.

Gate: present PRD.md to the human for approval. Do not advance without explicit confirmation; log the approval.

**Output:** confirmed PRD.md in project root.

Stage 2 — Scaffolding

**Standard and Thorough only.** Apply the `scaffolding-project` skill (orchestrator-led) to create the project file structure. **Quick:** skip — structure already exists.

Stage 3 — Architecture

Invoke `architect-agent`. Provide: PRD.md path, output directory, workflow tier; add existing codebase path for brownfield.

Gate: present ARCHITECTURE.md (and any ADRs) for approval. Resolve all open questions flagged by the architect before approving — decomposing an unconfirmed architecture produces misaligned chunks. Log the approval.

**Output:** confirmed ARCHITECTURE.md; ADRs in docs/decisions/ for Thorough.

Stage 4 — Interface Design

**Conditional: only when the project has a UI; Standard and Thorough only.** After Stage 3, check ARCHITECTURE.md for frontend components, web interface, or UI framework references. If absent, skip and note it in the log. **Quick:** skip — if system.md already exists, the developer uses it.

Apply the `designing-interfaces` skill (orchestrator-led, dialogic). Greenfield: full exploration workflow. Brownfield: if `.interface-design/system.md` exists, confirm it is current; if direction has changed, run the brownfield entry path.

Gate: present `.interface-design/system.md` for approval before decomposition. Log the approval.

Stage 5 — Decomposition

Invoke `breakdown-agent`. Provide: ARCHITECTURE.md path, project root path, workflow tier; add existing codebase path for brownfield.

Gate: review the proposed ROADMAP.md before the agent writes it — check chunk structure and dependencies. Confirm or request revisions; log the approval.

**Output:** confirmed ROADMAP.md (structural — chunks, phases, dependencies, file sets).

Stage 6 — Enrichment

**Standard and Thorough only.** Apply the `enriching-roadmap` skill (orchestrator-led). Provide: ROADMAP.md, ARCHITECTURE.md, PRD.md paths and workflow tier; if `.interface-design/system.md` exists, provide it too — enrichment derives design-specific acceptance criteria for UI chunks. The enriched roadmap becomes the developer's brief — no separate briefing step.

Gate: present the enriched ROADMAP.md for approval. Log the approval.

**Quick:** skip — the developer works directly from the chunk description.

Stage 7 — Planning

Apply the `planning-software` skill (orchestrator-led). Provide: enriched ROADMAP.md path, workflow tier, project name.

**Output:** ORCHESTRATION-PLAN.md (the workflow contract) and initialised ORCHESTRATION-LOG.md in project root.

Stage 8 — Build

For each chunk in ORCHESTRATION-PLAN.md, in dependency order, run the Per-Chunk Execution Protocol below.

Stage 9 — Completion Review

**Standard and Thorough only** (Quick: skip). When all chunks are complete in ORCHESTRATION-PLAN.md:

1. **Whole-project code review.** Invoke `reviewer-agent` with the whole-project perspective (from reviewing-code). Provide: PRD.md path, project root, all source files. Accept → proceed; Revise → address findings and re-run. 2