祝融说。

One feature done right doesn't mean ten features together will work. Order determines everything.

You have 4 features that need to be completed within a month. You decide to "go parallel"—have AI write code for all 4 features at the same time.

A week later, you discover: Feature A's database model conflicts with Feature B's—both use a field called status, but A uses 0/1/2 to represent states while B uses pending/approved/rejected. The API that Feature C depends on hasn't been built, because Feature D's API interface definition has been revised three times. You examine Feature A's code and find it imported a component from Feature B—but that component is still under development itself.

The project sinks into a deadlock where "all features wait on and depend on one another." You spend twice as much time coordinating these conflicts as you do writing code.

This isn't AI's fault. It's a problem of "missing orchestration." When multiple features are developed simultaneously, they are not independent—they share databases, APIs, and component libraries. Without a "traffic controller" managing these shared resources, conflict is inevitable.

6.1 Why Orchestration Is Needed

The development flow for a single feature is clear: decompose → code → accept → commit. You're already familiar with it. But when you have 3, 5, or 10 features to implement, the question is no longer "how to build one feature" but "how to arrange the order of these features."

You might think: why not just parallelize? Having AI write code for 3 features at once sounds more efficient, doesn't it?

This intuition holds in the physical world—three workers can lay three walls at the same time. But in software engineering, features are not "independent walls"; they are "buildings on a shared foundation." Feature A and Feature B may share the same database table, call the same API, or reference the same component. When A and B are developed together, the AI may not even know the other exists—it changes the database schema in A and changes the same table in B, and the two modifications clash.

The more insidious problem: Feature B may depend on Feature A's output. If A isn't done yet, B's AI will "guess" an interface definition for A. That guess is almost certainly wrong. By the time A is finished, B's code needs substantial rewriting.

This is why orchestration is necessary. The Orchestrator's job is not to write code but to answer three questions: what to do first, what to do next, and what can run in parallel. Like a traffic controller, it keeps every feature advancing on the right track—no collisions, no waiting.

Project Orchestration (Orchestrator) is what solves these problems. It doesn't write code directly; it manages the scheduling of Workflows:

Orchestrator
  ├── Read blueprint → determine feature list and dependencies
  ├── Schedule Workflows by dependency order
  │   ├── Workflow(Feature A) → Complete → Accept
  │   ├── Workflow(Feature B) → Complete → Accept
  │   └── Workflow(Feature C) → Complete → Accept
  ├── Cross-feature integration acceptance
  └── Produce integration report

6.2 Core Principles

Principle One: A Feature Is a Task

For the Orchestrator, the smallest unit of execution is not a file or a line of code, but a complete feature. Each feature is completed by a Workflow in a fully automated manner.

The Orchestrator asks only three questions:

1. Which prerequisite features does this feature depend on? (dependency ordering)
2. Has this feature passed acceptance? (quality gate)
3. Once this feature is complete, does the whole project pass integration testing? (integration verification)

Principle Two: Progress Is State

The Orchestrator manages project state across sessions. Every time the context is reset, it can resume progress from persistent records.

Progress state machine:

TODO → IN_PROGRESS → DONE
                      ↘ BLOCKED

Key rule: Only a feature that passes acceptance may be marked DONE.

Principle Three: Integration Is the Red Line

After each feature passes its individual acceptance, the Orchestrator must run cross-feature integration checks:

• Can Feature B correctly consume Feature A's API output?
• Is Feature A's new data model compatible with Feature B's?
• Does the overall test suite pass?

An individual feature passing ≠ The whole system passing.

6.3 Dependency Tree Management

The Orchestrator's core capability is managing the dependencies between features. Not every feature can be developed in parallel. Between features there are three kinds of dependency:

Hard dependency: Feature B must wait for Feature A to finish before it can start. For example, Feature B calls Feature A's API; if A's API hasn't been written yet, B's AI will "guess" an interface definition—and that guess will almost certainly differ from the actual A.

Soft dependency: Feature B can run in parallel with Feature A, but it needs to know A's interface definition. For example, Feature B uses a component from Feature A; if A's component interface is stable, B can start early, using mock data in place of A's real output.

No dependency: Feature B has no dependence on Feature A at all and can be developed independently. For example, "user management" and "system configuration" are usually independent.

Let's walk through a real dependency-tree derivation. Suppose an e-commerce system has 4 features:

• Feature A: User authentication (login/registration/JWT)
• Feature B: Order list (depends on user authentication—orders can only be viewed after login)
• Feature C: Product management (independent, but uses the same UI component library)
• Feature D: Payment integration (depends on order list + user authentication)

Dependency tree analysis:

• A is the root node, has no dependencies, and comes first
• C is independent and can run in parallel with A
• B depends on A and comes after A
• D depends on A + B and comes last

Optimal order: A and C in parallel → B → D

If you don't follow this order—say, building B before A—B's code will need extensive rewriting once A is done. Because when B is built in A's absence, the AI will "guess" an authentication interface definition, and that guess will almost certainly differ from the actual A.

Dependency Types

Auto-sorting Algorithm

The Orchestrator reads the milestone definitions from the blueprint, analyzes the dependencies automatically, and produces an execution order:

Input: milestone list
  1.1 Project initialization (no dependencies)
  1.2 Database setup (depends on 1.1)
  1.3 User authentication (depends on 1.2)
  2.1 Order list (depends on 1.3)
  2.2 Create order (depends on 1.3)
  2.3 Order details (depends on 2.1)

Output: execution order
  Phase 1: 1.1 → 1.2 → 1.3
  Phase 2: 2.1 → 2.2 (can 2.1 and 2.2 run in parallel? no—requires manual confirmation)
           2.3 (depends on 2.1)

6.4 Context Isolation and Reset

The biggest trap in multi-feature development is "doing every feature in a single conversation." That invites serious context pollution—Feature A's debugging code, failed attempts, and discarded approaches all become "background noise" in Feature B's generation.

The Orchestrator's solution: each feature gets its own independent conversation context. Feature A's conversation contains none of Feature B's information, and vice versa.

But here lies a contradiction: Feature B needs to know Feature A's API definition in order to call it correctly. If the conversations are isolated, how does B learn what A's interface looks like?

The answer lives in the blueprint (CONTEXT.md). Before starting each new feature, the Orchestrator updates the blueprint, crystallizing the previous feature's API contracts and data model into it. When a new feature begins, the AI reads the blueprint and obtains the interface definitions of every "completed feature." Conversations are isolated, but information flows through the blueprint.

The full flow:

1. Orchestrator starts Feature A → Workflow executes → completes → blueprint updated
2. Orchestrator starts Feature B → reads the latest blueprint (containing A's API contracts) → Workflow executes → completes → blueprint updated
3. And so on

This mechanism guarantees two critical goals: each feature executes in a clean context (avoiding context pollution), while every feature still gains access to the interface definitions of all completed features (delivered through the blueprint).

6.5 Cross-Feature Integration Acceptance

Why Integration Acceptance Is Needed

When each feature is accepted individually, the AI only checks the correctness of that feature in isolation. But once multiple features are combined, the following problems can surface:

• Data format mismatch: Feature A's API returns {id: 1}, while Feature B expects {id: "1"} (type mismatch)
• Naming conflict: Feature A defines getUser(), and Feature B defines getUser() too (duplicate definition)
• State conflict: Feature A changes an order status to "paid," Feature B relies on that "paid" status for downstream processing, but the two disagree on what "paid" means
• Resource contention: Feature A and Feature B both modify the same configuration file

The Integration Acceptance Method

Integration acceptance steps:

1. Compile/build the project
   → Ensure there are no compilation errors

2. Run the full test suite
   → Ensure there are no regressions

3. Check cross-feature data flow
   → Can Feature A's output be consumed by Feature B?

4. Check configuration files
   → Are there conflicting configuration changes?

5. Check global state
   → Are there conflicts in routing, state management, or global styles?

6.6 Progress Persistence

One important capability of the Orchestrator: "even if the conversation is interrupted, progress can be recovered."

The Persistence Mechanism

Progress information is written to the file system, not kept only in the conversation context:

.agents/
├── job.state.json    # Machine-readable complete project state
└── job.progress.md   # Human-readable append-only progress ledger

A sample job.state.json:

{
  "projectName": "Order Management System",
  "phases": [
    {
      "name": "Phase 1: Foundation",
      "milestones": [
        { "id": "1.1", "name": "Project initialization", "status": "DONE" },
        { "id": "1.2", "name": "Database setup", "status": "DONE" },
        { "id": "1.3", "name": "User authentication", "status": "DONE" }
      ]
    },
    {
      "name": "Phase 2: Core Features",
      "milestones": [
        { "id": "2.1", "name": "Order list", "status": "DONE" },
        { "id": "2.2", "name": "Create order", "status": "IN_PROGRESS" },
        { "id": "2.3", "name": "Order details", "status": "TODO" }
      ]
    }
  ],
  "currentMilestone": "2.2",
  "updatedAt": "2026-07-25T10:30:00Z"
}

Even if the entire conversation context is lost, project progress can be fully recovered from these files.

6.7 Exception Handling

Scenario One: A Feature Blocks

Feature B depends on Feature A, but Feature A keeps failing acceptance.

Handling: The Orchestrator does not wait indefinitely. After Feature A fails N times, it marks it as BLOCKED and notifies the user. The user can then choose:

• Step in manually to fix Feature A
• Adjust the dependencies and work on features that don't depend on A first
• Lower Feature A's acceptance criteria

Scenario Two: Cross-Feature Integration Finds a Problem

Feature A and Feature B each pass their individual acceptance, but integration testing reveals an incompatibility.

Handling: The Orchestrator does not attempt to auto-fix integration problems (they involve changes to two features, and the risk is too high). It generates an integration problem report and waits for the user's decision.

Scenario Three: Requirements Change Mid-Project

After the 5th feature is complete, the user asks to change the implementation of the 2nd feature.

Handling: The Orchestrator does not directly modify a feature already marked DONE. Instead, it:

1. Re-marks the affected features as TODO
2. Updates the blueprint
3. Re-executes the affected features and their downstream dependencies

Chapter Summary

Project orchestration solves the "organizational problem of multiple features." Its core is dependency tree management—identifying the hard, soft, and absent dependencies between features to determine the correct development order. Context isolation and reset ensure each feature executes in a clean conversation, while interface definitions flow through the blueprint. The Orchestrator does not write code; it manages Workflow scheduling and integration acceptance. Remember: an individual feature passing ≠ the whole system passing. In the next chapter, we'll study fully automated construction—complete automation from zero to deployment.