ahmedhamadto/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?"

| Type | Indicators | Phase Count | |------|-----------|-------------| | macOS App | Desktop UI, SwiftUI, AppKit, menu bar app | 8–10 phases | | iOS Mobile App | iPhone/iPad, SwiftUI, UIKit, App Store | 8–15 phases | | Web Frontend | React, Vue, static site, no backend | 8–10 phases | | Full-Stack Web | Frontend + database + API + auth | 14–17 phases | | Voice Agent | LiveKit, telephony, STT/TTS, conversational AI | 13–15 phases | | Edge/IoT + ML | Hardware devices, computer vision, ML pipeline, fleet management | 16–19 phases |

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

| Phase | macOS | iOS | Web FE | Full-Stack | Voice | Edge/IoT+ML | |-------|:-----:|:---:|:------:|:----------:|:-----:|:-----------:| | 0.5 System Assessment | o | o | o | o | o | o | | 1. Brainstorm | x | x | x | x | x | x | | 2. Domain Model | | o | | x | x | x | | 3. System Design + Security | | o | | x | x | x | | 4. Resilience | | o | | x | x | x | | 5. ML Pipeline | | | | | | x | | 6. Edge Architecture | | | | | | x | | 7. API Specification | | o | | x | x | x | | 8. Voice Prompt Design | | | | | x | | | 9. Infrastructure | | | | o | o | x | | 10. UI Design | x | x | x | x | | o | | 11. UX Design | x | x | x | x | | o | | 12. Motion Design | o | o | o | o | | | | 13. Cost Analysis & Risk | x | x | x | x | x | x | | 14. Writing Plans | x | x | x | x | x | x | | ⟳ COMPACT | x | x | x | x | x | x | | 15. Implementation | x | x | x | x | x | x | | ⟳ COMPACT | x | x | x | x | x | x | | 16. Security Validation | | o | | x | x | x | | 17. Observability | | | | x | x | x | | 18. ML Validation | | | | | | x | | 19. Polish & Review | x | x | x | x | x | x | | 20. Retrospective | x | x | x | x | x | x |

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

<HARD-GATE> BEFORE executing any phase, you MUST use the Read tool to read the corresponding phase file from ./phases/.

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. </HARD-GATE>

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

| Phase | File | |-------|------| | 0.5 | ./phases/phase-00.5-system-assessment.md | | 1 | ./phases/phase-01-brainstorming.md | | 2 | ./phases/phase-02-domain-modeling.md | | 3 | ./phases/phase-03-system-design.md | | 4 | ./phases/phase-04-resilience.md | | 5 | ./phases/phase-05-ml-pipeline.md | | 6 | ./phases/phase-06-edge-architecture.md | | 7 | ./phases/phase-07-api-specification.md | | 8 | ./phases/phase-08-voice-prompt.md | | 9 | ./phases/phase-09-infrastructure.md | | 10 | ./phases/phase-10-ui-design.md | | 11 | ./phases/phase-11-ux-design.md | | 12 | ./phases/phase-12-motion-design.md | | 13 | ./phases/phase-13-cost-analysis.md | | 14 | ./phases/phase-14-writing-plans.md | | 15 | ./phases/phase-15-implementation.md | | 16 | ./phases/phase-16-security-validation.md | | 17 | ./phases/phase-17-observability.md | | 18 | ./phases/phase-18-ml-validation.md | | 19 | ./phases/phase-19-polish-review.md | | 20 | ./phases/phase-20-retrospective.md |

---

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: | Artifact | Phase Completed | |----------|----------------| | System Assessment section | Phase 0.5 (Existing System Assessment) | | *-design.md | Phase 1 (Brainstorming) | | Domain Model section in design doc | Phase 2 | | *-system-design.md | Phase 3 (DDIA) | | Resilience section in system design | Phase 4 | | *-ml-pipeline.md | Phase 5 | | Edge Architecture section | Phase 6 | | API Specification section/doc | Phase 7 | | Voice prompt doc | Phase 8 | | Infrastructure section | Phase 9 | | UI Design section in design doc | Phase 10 | | UX Design section in design doc | Phase 11 | | Motion Design section in design doc | Phase 12 | | Cost & Risk section in design doc | Phase 13 (Cost Analysis) | | *-plan.md | Phase 14 (Writing Plans) | | Code exists + tests pass | Phase 15 (Implementation) | | Security audit report | Phase 16 | | Observability section | Phase 17 | | ML validation report | Phase 18 | | Review findings addressed | Phase 19 | | Retrospective section in design doc | Phase 20 |

---

Anti-Patterns

| Mistake | Fix | |---------|-----| | Skipping to implementation | Always start at Phase 0, even if "you know what you're building" | | Running all phases for a simple macOS app | Trust the router — it selects only applicable phases | | Treating security as Phase 16 only | Security-by-design is in Phase 3; Phase 16 validates it was implemented | | Designing the ML pipeline after building the API | Phases are sequential — ML decisions affect API shape | | Writing plans without a domain model | Plans based on a vague domain produce vague tasks | | Skipping resilience for "internal" services | Internal services fail too — especially at 3am | | Averaging latency instead of using percentiles | p50 hides tail latency; use p95/p99 | | Adding features to an existing system without mapping it first | Run Phase 0.5 — understand what exists before designing what's new | | Treating accessibility as a Phase 19 afterthought | Accessibility-by-design in Phase 3 catches issues that are expensive to retrofit | | Ignoring cloud costs until the bill arrives | Phase 13 (Cost Analysis) exists for this — unit economics matter | | Skipping the phase file read | Always read the phase file, even if you think you remember it | | Designing UI before knowing the API shape | UI/UX/Motion phases come after API spec for a reason | | Committing to a tech stack without compatibility checking | Run /stack-compatibility-oracle after brainstorming to catch blockers early | | Rewriting a brownfield system without extraction | Use /brownfield-greenfield to separate intent from accident before proposing changes |

---

Book References

| Phase | Book | Author | |-------|------|--------| | 2. Domain Modeling | Domain-Driven Design | Eric Evans | | 3. System Design | Designing Data-Intensive Applications | Martin Kleppmann | | 4. Resilience | Release It! | Michael Nygard | | 5. ML Pipeline | Designing Machine Learning Systems | Chip Huyen | | 9. Infrastructure | Infrastructure as Code | Kief Morris | | 10. UI Design | Refactoring UI | Wathan & Schoger | | 10. UI Design | Every Layout | Andy Bell & Heydon Pickering | | 10. UI Design | Design Systems | Alla Kholmatova | | 11. UX Design | Don't Make Me Think | Steve Krug | | 11. UX Design | About Face | Alan Cooper | | 11. UX Design | Inclusive Design Patterns | Heydon Pickering | | 12. Motion Design | The Illusion of Life | Frank Thomas & Ollie Johnston | | 12. Motion Design | Animation at Work | Rachel Nabors | | 12. Motion Design | Designing Interface Animation | Val Head | | 14. Writing Plans | Growing Object-Oriented Software, Guided by Tests | Freeman & Pryce | | 17. Observability | Observability Engineering | Charity Majors | | 18. ML Validation | Reliable Machine Learning | Cathy Chen et al. |