[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 CLIplan.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]
| [INDEX] | [KEY] | [VALUE] |
| :-----: | -------- | --------- |
| [1] | Scope | ... |
| [2] | Tasks | N.X, N.Y |
| [3] | Priority | ... |
| [4] | Depends | WU-M or — |
[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-listVerify labels exist:
task— agentic categorytriage— 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]
| [INDEX] | [KEY] | [VALUE] |
| :-----: | ------ | ----------------- |
| [1] | Target | `path/to/file.ts` |
| [2] | Action | [Specific change] |
[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]
| [INDEX] | [WORK_UNIT] | [ISSUE] | [TITLE] | [PRIORITY] | [DEPENDS] |
| :-----: | ----------- | ------- | ------- | ---------- | --------- |
| [1] | WU-1 | #42 | [name] | high | — |
| [2] | WU-2 | #43 | [name] | medium | #42 |
| [3] | WU-3 | #44 | [name] | medium | #42, #43 |
**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.