microsoft/dag-generation

DAG Generation

Two-stage DAG generation for modernization projects:

1. Stage 1 (§1.4) — select fragments from task-catalog, determine deep_planning, produce DAG JSON
2. Stage 2 (§3.2.2) — when deep planning, read plan artifacts, produce execute+validate DAG

Reference Files

• references/task-catalog.md — fragment library with when/skip-when/after/scope
• references/dag-rules.md — DAG construction rules (dependencies, compression, sizing)

Stage 1: Initial DAG

Select fragments from the task catalog and produce a DAG.

Inputs

1. Project profile — read from {{BASE_PATH}}/artifacts/project-profile.yaml (project.loc, project.languages, project.modules, assessment.change_type, assessment.grouping_needed)
2. user_ask — natural-language migration target (passed by coordinator)

Decision Procedure

Step 1: Determine deep_planning

Decide whether the project needs deep planning (two-stage DAG) or can produce a complete DAG upfront.

deep_planning: true when:

• Multiple modules with cross-module dependencies that require discovery before execute tasks can be defined
• change_type is rewrite or extract AND the target architecture is not yet clear (needs design exploration)
• The project is large enough that execute task structure genuinely cannot be enumerated without plan-phase artifacts

deep_planning: false when:

• Single module or few modules with clear structure
• change_type is upgrade — target is well-defined (version to version)
• Execute tasks can be directly derived from the project profile without intermediate artifacts
• Small projects where one developer could hold the full context

Step 2: Select fragments

Read references/task-catalog.md. For each fragment, decide include/exclude based on:

• change_type (upgrade | extract | rewrite)
• user_ask intent
• Project profile (LOC, modules)
• deep_planning decision from Step 1 (drives implementation-plan selection)

Respect when / skip-when conditions and after ordering from the catalog.

⛔ Skip-when enforcement (mandatory post-selection gate): After initial selection, sweep every selected fragment and check its skip-when against the current context (deep_planning value, change_type, project scale, other selected fragments). Any fragment whose skip-when condition is satisfied MUST be removed — no exceptions. Specifically:

• implementation-plan: remove if deep_planning: false

This gate catches cases where the initial selection included fragments that looked relevant but conflict with the deep_planning decision or project scale.

Fragment selection is an internal decision — do NOT output the selection rationale to the user. The DAG itself is the user-facing result.

Step 3: Generate DAG

Read references/dag-rules.md for construction rules.

• If deep_planning: true → produce only plan-phase tasks as JSON
• If deep_planning: false → produce the complete DAG (plan + execute + validate) as JSON

Output

Return JSON to the coordinator (do NOT write files):

{
  "deep_planning": true,
  "tasks": [
    {"id": "t1", "role": "<role>", "title": "<title>", "depends_on": [], "phase_label": "<label>"},
    {"id": "t2", "role": "<role>", "title": "<title>", "depends_on": ["t1"], "phase_label": "<label>"}
  ]
}

Stage 2: Execute+Validate DAG

When plan phase completes and deep_planning: true, generate the execute+validate DAG from plan artifacts.

Inputs (provided by coordinator)

• Artifact base path
• User ask (original migration request)
• Change type (upgrade / extract / rewrite)
• Grouping mode and in-scope groups
• Fan-out file path
• Task ID offset (continue from last plan-phase task)

Procedure

1. Read plan artifacts (implementation plan, architecture analysis, etc.)
2. Read references/dag-rules.md for construction rules
3. Read references/task-catalog.md for fragment definitions
4. Generate JSON task graph per dag-rules.md

Output

{"tasks": [{"id": "t<N>", "role": "<role>", "title": "<title>", "depends_on": ["<id>", ...], "phase_label": "<label>"}]}

What this skill does NOT do

• Does NOT decide grouping / topology (coordinator decides in §1.3)
• Does NOT compute topology groupings (that's project-decomposition)
• Does NOT perform role discovery from charters (assigns roles based on task content; coordinator refines using team-charters at dispatch)
• Does NOT match task → skill (that's worker subagent)
• Does NOT execute anything (that's coordinator + workers)
• Does NOT prompt user (that's coordinator at checkpoint)