Software Forge

Project Orchestrator

Overview

Universal project lifecycle skill. Classifies your project type, builds a phase plan, then walks through each phase sequentially — invoking existing skills where they exist and running inline design phases where they don't.

The rule: No project uses all phases. The router selects 7–18 phases based on what you're actually building.

Announce at start: "I'm using the orchestrate skill to guide this project through its lifecycle."

When to Use

• Starting a new project from scratch (greenfield)
• Adding a major feature that changes architecture, data flow, or integrations
• Unsure which skills to invoke and in what order
• Starting work on a project type you haven't classified before

When NOT to use:

• Small bug fixes, typos, minor UI tweaks — just do the work
• Pure research or exploration — use Explore agent directly
• Single-file changes with clear requirements — use TDD directly
• You already know exactly which single skill applies (e.g., just need /security-audit)

Mode Selection

Before doing anything else, ask ONE question:

How would you like to work?

(A) Build — Full-speed design and implementation. No teaching pauses. (B) Learn — Same build quality, plus I teach you software engineering concepts at every decision point. Tracks your growth across projects.

If the user selects (B) Learn, invoke the engineering-mentor skill using the Skill tool. Engineering Mentor wraps this orchestrator with an adaptive teaching layer — it handles everything from here. Stop executing this skill after invoking engineering-mentor.

If the user selects (A) Build or gives no preference, continue with Phase 0 below.

How It Works

1. Classify — Ask what you're building, determine project type
2. Route — Select the phases that apply
3. Read — Load each phase file on demand before executing it
4. Execute — Walk through each phase sequentially
5. Handoff — Each phase produces a doc artifact; later phases build on earlier ones

All artifacts are saved to docs/plans/. If resuming mid-project, check which docs already exist to determine current phase.

Phase 0: Project Classification

Ask ONE question: "What are you building?"

Sub-classification questions (if needed):

• Mobile/Web: "Does it have a backend?" — if yes, add full-stack phases
• Any type: "Does it integrate with external services?" — if yes, add resilience phase
• Any type: "Will this be deployed to cloud infrastructure you manage?" — if yes, add infrastructure phase
• Any type: "Is this a new project or adding to an existing system?" — if existing, add system assessment phase. If user wants to evaluate a full redesign, suggest /brownfield-greenfield instead.
• Any type with UI: "Does your project have state transitions, loading sequences, or interactions that would benefit from motion design?" — if yes, add motion design phase

Available cross-cutting skills (invoke during relevant phases):

• /stack-audit — Run during Phase 0.5 or standalone to audit the existing tech stack against the 15-domain taxonomy
• /stack-compatibility-oracle — Run after Phase 1 (Brainstorming) when a tech stack is proposed, to check for architectural incompatibilities before committing
• /architecture-best-practices — Queryable reference layer; invoke during any design phase (2–13) when evaluating technology choices or diagnosing issues
• /brownfield-greenfield — Alternative to Phase 0.5 for projects considering a major redesign; extracts intent, strips tech, proposes fresh architecture

Route Table

x = always applies | o = conditional (based on sub-classification) | blank = skip

Compile Your Phase Plan

After classification, explicitly list the active phases for this project before proceeding:

1. Review the route table for your project type
2. For each "o" phase, check the sub-classification answers to determine if it's active
3. Write out the numbered list of active phases (e.g., "Active phases: 0.5, 1, 2, 3, 4, 7, 10, 11, 13, 14, 15, 16, 18")
4. Present the phase plan to the user for confirmation before starting

This prevents accidentally skipping or running wrong phases.

Phase Execution

This is not optional. This is not negotiable. You cannot execute a phase from memory. You cannot summarize. You cannot skip.

When entering Phase N:

1. Read ./phases/phase-XX-name.md using the Read tool
2. Follow its instructions exactly
3. Produce the deliverable it specifies 3b. Append a Decision Log entry to the design doc on disk capturing: what was decided, what was rejected, why, and any user corrections or teaching moments.
4. Move to the next active phase in your compiled plan

If you catch yourself thinking "I know what this phase does" — STOP. Read the file. Skills evolve. Your memory is stale.

Context Compaction

Context compaction keeps the conversation window lean for implementation and validation phases. During design and planning (Phases 1–14), let the context grow naturally — the agent makes better decisions with the full chain of reasoning visible.

Compaction Points

After Phase 14 (Writing Plans), before Phase 15 (Implementation): All design decisions and task breakdowns are now saved to docs/plans/. Summarize key decisions, constraints, and tech choices into a compact handoff block, then let the natural context compression drop the verbose design conversation.

After Phase 15 (Implementation), before Phase 16 (Security Validation): Implementation details (code discussions, debugging, refactoring) are no longer needed. The code is on disk. Summarize what was built and any deviations from the plan.

Compaction Protocol

At each compaction point:

1. Verify artifacts are on disk. Check that docs/plans/ contains the expected deliverables from completed phases. If anything is missing, write it before compacting.
2. Produce a compact summary of the key decisions carried forward — architecture choices, tech stack, constraints, trade-offs, and anything the next phase needs to know.
3. After compaction, the next phase MUST re-read its inputs from disk. Phase 15 reads the plan. Validation phases (16–18) read the relevant design docs for what they're validating.

Why Only Two Compaction Points

• Design phases (1–14) need full context. Each phase builds on the previous. Compacting mid-design forces re-reading and loses nuance — rejected alternatives, trade-off discussions, and "why not" reasoning.
• Implementation (15) needs the plan, not the design conversation. The plan captures everything implementation needs.
• Validation phases (16–18) need design docs + code, not the implementation conversation. They read code from the filesystem and reference design docs on disk.

Phase File Mapping

Resumption Protocol

If starting a new session mid-project:

1. Check docs/plans/ for existing artifacts
2. Read each doc to understand decisions already made
3. Determine which phase produced the last artifact
4. Resume from the next phase
5. If docs/plans/.mentor-checkpoint.json exists, read it. If mode is "learn", invoke engineering-mentor with the stored state instead of continuing in Build mode.
6. If the design doc contains ### Decision Log sections, read them to understand prior reasoning before continuing.

Artifact -> Phase mapping:

Anti-Patterns

Book References