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)

If user_ask names an explicit target stack or version, preserve it verbatim in every selected task. Do not replace, downgrade, or reinterpret the requested version based on model familiarity or LTS defaults.

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)

Always include target-env-prep when the target runtime/framework/language/tooling differs from source or when the user specifies an explicit target version. This is an environment preparation task: it must install/provision/activate the requested target when possible, produce a preparation artifact, and run before scaffold/implementation/build/test tasks. It normally has no dependency on architecture/source analysis and should run in parallel with those tasks. This is true even for small projects and even when deep_planning: false.

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.

✅ Explicit-request override (runs AFTER skip-when enforcement — highest precedence): If user_ask explicitly requests a completeness, consistency, or feature-parity check (e.g. "run a completeness check", "verify nothing was missed", "enforce consistency", "feature parity sign-off"), force-include the completeness/conformance validation fragment (conformance-review, and feature-parity-signoff when applicable) even if its skip-when condition matched and removed it above. User intent overrides the size/type heuristic. This override is one-directional — it can only ADD a gate the heuristics dropped, never remove one they selected. It must run after the skip-when sweep, otherwise the sweep would strip the fragment back out (e.g. skip-when: same-stack upgrade).

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)