[H1][PLAN-DECOMPOSE]

Dictum: Work units become issues; issues enable parallel agent execution.

Decompose plan into GitHub issues via work unit extraction.

Workflow:

• §PARSE — Extract work units from plan

• §VALIDATE — Verify labels exist, check structure

• §CREATE — Create issues in dependency order

• §LINK — Add blocker references to dependent issues

Dependencies:

• github-tools — Issue creation via gh CLI

• plan.md — Input with Work Units section

Input:

• Plan : Path to plan artifact with Work Units section

[1][PARSE]

Dictum: Accurate issues require complete context extraction.

Extract from plan:

[INDEX] [SECTION] [EXTRACT]

[1] Context Plan title, summary

[2] Approach Selected approach for reference

[3] Phases Task details for embedding

[4] Work Units WU-N blocks with scope, tasks, priority, depends, validation

Work Unit Structure:

[N.M][WU_M]: [Name]

[VERIFY]:

• check 1
• check 2

[IMPORTANT]:

• [ALWAYS] Parse ALL work units before creating any issues.

• [ALWAYS] Extract task details for embedding in issue body.

• [NEVER] Proceed if Work Units section missing.

[2][VALIDATE]

Dictum: Failed operations waste agent cycles.

[2.1][VALIDATE_LABELS]

Fetch available labels via github-tools:

uv run .claude/skills/github-tools/scripts/gh.py label-list

Verify labels exist:

• task — agentic category

• triage — initial status

• Priority labels: critical , high , medium , low

[IMPORTANT] If priority label missing, fall back to task,triage only.

[2.2][VALIDATE_STRUCTURE]

[INDEX] [CHECK] [REQUIREMENT]

[1] Work Units At least 1 WU-N block

[2] Scope Non-empty per work unit

[3] Tasks Reference valid task numbers

[4] Validation At least typecheck + lint

[CRITICAL] Abort if structure invalid—report missing elements.

[3][CREATE]

Dictum: Dependency tracking requires creation order.

Create issues in dependency order (WU-1 before WU-2 if WU-2 depends on WU-1).

Per Work Unit:

[3.1][BUILD_TITLE]

[TASK]: [Work unit descriptive name]

[3.2][BUILD_LABELS]

task,triage,[priority]

[3.3][BUILD_BODY]

[1][WORK_UNIT]: [Name]

Plan: [Plan title]

[2][SCOPE]

[File/module area from work unit]

[3][TASKS]

[3.1][TASK_N_X]

[Repeat for each task in work unit]

[4][DEPENDENCIES]

[None OR Blocked by: #[prior issue numbers]]

[5][VALIDATION]

[VERIFY]: [Copied from work unit validation section]

[6][PR_WORKFLOW]

Branch: feat/[issue-number]-[slug]

[EXECUTE]:

1. Create branch: git checkout -b feat/[issue-number]-[slug]
2. Implement all tasks in §TASKS
3. Run validation checks in §VALIDATION
4. Commit changes with message referencing issue
5. Push branch: git push -u origin feat/[issue-number]-[slug]
6. Create PR: gh pr create --title "[TASK]: [name]" (uses .github/PULL_REQUEST_TEMPLATE.md)
7. Add Closes #[issue-number] to PR summary section

[7][COMPLETION]

[VERIFY]:

• All tasks implemented
• nx run-many -t typecheck — zero errors
• nx run-many -t check — zero Biome violations
• pnpm sonar — no new code smells/issues
• PR created and linked to issue

[3.4][CREATE_ISSUE]

uv run .claude/skills/github-tools/scripts/gh.py issue-create
--title "[TASK]: [name]"
--body "[body]"

Then add labels:

uv run .claude/skills/github-tools/scripts/gh.py issue-edit
--number [N]
--labels "task,triage,[priority]"

Track mapping: {WU-N: issue_number}

[CRITICAL]:

• [ALWAYS] Create in dependency order.

• [ALWAYS] Track WU → issue number mapping.

• [ALWAYS] Wait for creation success before next issue.

[4][LINK]

Dictum: Workflow sequencing requires explicit blockers.

After all issues created, update dependent issues with blocker references.

For each issue with dependencies:

• Look up prior issue numbers from mapping

• Edit issue body to include: Blocked by: #[N], #[M]

uv run .claude/skills/github-tools/scripts/gh.py issue-edit
--number [dependent_issue]
--body "[updated body with blocker refs]"

[IMPORTANT] Blocker format: Blocked by: #42, #43

[5][OUTPUT]

Dictum: Verification confirms successful decomposition.

Return creation summary:

[1][DECOMPOSITION_COMPLETE]

Total: N issues created<br> Plan: [plan title]

[6][VALIDATION]

Dictum: Incomplete execution corrupts downstream workflow.

[VERIFY]:

• Parse: All work units extracted

• Validate: Labels verified, structure valid

• Create: Issues created in order

• Link: Dependencies added to issue bodies

• Output: Summary table returned

[7][CONSTRAINTS]

[CRITICAL]:

• [ALWAYS] Parse before create—never stream.

• [ALWAYS] Create in dependency order.

• [ALWAYS] Track WU → issue mapping.

• [ALWAYS] Include validation checklist in every issue.

• [ALWAYS] Include PR_WORKFLOW section in every issue.

• [ALWAYS] Use [TASK]: prefix for titles.

• [NEVER] Create issues without Work Units section.

• [NEVER] Skip dependency linking.

• [NEVER] Hardcode labels—verify they exist first.