jamesaphoenix/decompose-spec
.codex/skills/decompose-spec/SKILL.md
Turn a design spec into an explicit tx task graph with `tx decompose`, then refine the graph using normal tx task and dependency primitives.
$ install --global
skillsauthnpx skillsauth add jamesaphoenix/tx decompose-specInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 17, 2026, 2:13 AM57.7s1 file scanned
SKILL.md
- name:
- decompose-spec
- description:
- Turn a design spec into an explicit tx task graph with `tx decompose`, then refine the graph using normal tx task and dependency primitives.
- argument-hint:
- <design-doc-ref> [--parent <task-id>] [--runtime <auto|claude|codex>] [--dry-run]
Decompose Spec
Use this skill when the user already has a design spec and wants an explicit tx task graph created from that spec.
Default Path
- Confirm the source doc is a design spec.
tx doc show <design-doc-ref>
- Preview the decomposition before writing if the graph shape is still being discussed.
tx decompose <design-doc-ref> --dry-run --json
- Materialize the graph once the plan looks right.
tx decompose <design-doc-ref>
tx decompose <design-doc-ref> --runtime claude
tx decompose <design-doc-ref> --runtime codex
tx decompose <design-doc-ref> --parent <task-id>
Rules
- Prefer
tx decomposeover manually creating a large first-pass task graph. - Use
--parent <task-id>when the spec should decompose under an existing task. - Use
--dry-runwhen you need to inspect or compare graph options before writes. - Do NOT use
--max-tasksunless the user explicitly requests a cap. Artificial limits produce weak decompositions that miss important slices. Let the LLM produce as many tasks as the design doc warrants. - Be patient.
tx decomposemakes LLM calls and can take 60–120 seconds. If you launched it, wait for it to finish. Never re-run it because output appears empty — that wastes API credits and risks duplicate subtasks. If it was launched in the background, poll the output file at long intervals (30s+). - After materialization, tx remains canonical. Refine the graph with:
tx add "Follow-up task"
tx add "Nested subtask" --parent <task-id>
tx dep block <task-id> <blocker-id>
tx dep unblock <task-id> <blocker-id>
tx doc attach <task-id> <doc-name>
tx update <task-id> --status blocked
- If the design doc changes materially, re-run
tx decompose --dry-runfirst and repair the existing graph explicitly instead of creating duplicate work.
Practical Guidance
- Start from a stable design doc, not a vague request or partial note.
- Use
tx show <task-id>on the generated root task to inspect linked-doc and blocker state after decomposition. - If the result has too many tasks, refine by merging or removing tasks after
the fact — do not pre-cap with
--max-tasks.
Equivalent Surfaces
- REST API:
POST /api/decompose - MCP:
tx_decompose - Agent SDK:
await tx.decompose.run({
docRef: "<design-doc-ref>",
runtime: "auto",
dryRun: true,
})
Related Skills
jamesaphoenix/verify-invariants
development
VerifiedTrustedCommunity
Implement and verify design doc invariants by annotating tests and source code with [INV-*] / @spec tags, then driving tx spec coverage from BUILD toward HARDEN (100% FCI). Works with any design doc that has an invariants block.
2SKILL.mdUpdated Apr 17, 2026
jamesaphoenix/task-spec-loop
data-ai
VerifiedTrustedCommunity
Link tasks to paired PRD/design specs, export all open work to markdown, and keep Ralph-style loops moving by creating tasks, subtasks, and dependency updates through tx primitives.
2SKILL.mdUpdated Apr 17, 2026
jamesaphoenix/skills-sync
development
VerifiedTrustedCommunity
Refresh bundled tx Claude Code and Codex skills in a project from the canonical tx source without manual copy and paste.
2SKILL.mdUpdated Apr 17, 2026
jamesaphoenix/ralph-loop
development
VerifiedTrustedCommunity
Run Ralph against either the full repo queue or tasks linked to one design doc, with injected task/spec/queue context for Codex or Claude runtimes.
2SKILL.mdUpdated Apr 17, 2026