AGENT SKILL

x-lib-decompose-task

Decomposes an implementation plan into tasks. Primary mode: derives tasks from test scenarios (x-plan-tests output) using TDD structure (RED/GREEN/REFACTOR). Fallback mode: uses Layer Task Catalog (G1-G7) when no test plan exists.

License 许可
MIT
最近更新
2026-10-27
Stars
★ 0
Forks
1

01 前言 Front Matter

name
x-lib-decompose-task
description
Decomposes an implementation plan into tasks. Primary mode: derives tasks from test scenarios (x-plan-tests output) using TDD structure (RED/GREEN/REFACTOR). Fallback mode: uses Layer Task Catalog (G1-G7) when no test plan exists.
allowed-tools
Read, Write, Grep, Glob
context-budget
medium
user-invocable
false
requires-capabilities
[]

02 资源文件 1

03 SKILL.md 正文

Global Output Policy

  • Language: English ONLY.
  • Tone: Technical, Direct, and Concise.
  • Efficiency: Remove all conversational fillers and greetings to save tokens.

Skill: Task Decomposer (Library)

Purpose

Decomposes an implementation plan into granular tasks. When a test plan exists (from x-plan-tests), derives tasks from test scenarios using TDD structure (RED/GREEN/REFACTOR) with a per-task Parallel flag. Falls back to the Layer Task Catalog (G1-G7) when no test plan is available, where tasks are additionally assigned to parallelism groups. Each task is assigned a model tier (Junior/Mid/Senior) and context budget.

When Called

Caller Skill Phase Context
x-implement-story Phase 1C After the Architect produces the plan, BEFORE implementation
(standalone) N/A When breaking down a plan into implementable tasks

Inputs

Input Path Required
Architect's plan ai/epics/epic-XXXX/plans/plan-story-XXXX-YYYY.md Yes
Story requirements Story file Yes
Test plan (from x-plan-tests) ai/epics/epic-XXXX/plans/tests-story-XXXX-YYYY.md No

Procedure

Step 0 — Idempotency Pre-Check (RULE-002 — Artifact reuse)

Before any decomposition work, verify whether a valid task breakdown already exists:

  1. Derive artifact path: ai/epics/epic-XXXX/plans/tasks-story-XXXX-YYYY.md (extract epic ID XXXX and story sequence YYYY from the story ID)
  2. Check existence: Use Glob or Read to verify if the file exists
  3. Staleness check (if file exists):
    • Compare modification times: mtime(story file) vs mtime(tasks file)
    • Fresh (mtime(story) <= mtime(tasks)): Log "Reusing existing task breakdown from {date}" and RETURN the existing file without regeneration. No subagent invocation needed.
    • Stale (mtime(story) > mtime(tasks)): Log "Regenerating stale task breakdown for {story-id}" and proceed to STEP 0.5
  4. File absent: Log "Generating task breakdown for {story-id}" and proceed to STEP 0.5

Rationale: Task breakdowns are expensive to generate (2-5 min, significant token cost). When a session is resumed after interruption, the existing breakdown should be reused if the story has not changed. This saves tokens and ensures continuity.

Idempotency Summary:

Aspect Behavior
Check Compare mtime(story) vs mtime(tasks)
Skip Reuse existing breakdown when mtime(story) <= mtime(tasks)
Override Regenerate when story is newer than existing breakdown

Step 0.5 — Read Architecture Context

Before decomposing, read the project's architecture and layer definitions:

  • knowledge/architecture/architecture-principles.md — layer structure, dependency direction, package organization
  • knowledge/layer-templates.md — complete layer catalog with package locations, code templates, and checklist per layer

These files define the available layers for YOUR project. The Layer Task Catalog below is derived from them.

Step 1 — Read Story Context and Template (RULE-007, RULE-012)

Read these files:

  • ai/epics/epic-XXXX/plans/plan-story-XXXX-YYYY.md (Architect's plan)
  • Story requirements file

Template Reference (RULE-007):

Read template at .claude/templates/_TEMPLATE-TASK-BREAKDOWN.md for required output format.

  • Template found: Use the template's sections as the mandatory output structure. The template defines: Header (Story ID, Date, Author), Summary, Dependency Graph, Tasks Table, and Escalation Notes.
  • Template NOT found (RULE-012 fallback): Log "Template not found, using inline format" and use the inline format defined in STEP 2A (test-driven) or STEP 2B (layer-based) of this skill. Execution continues normally without interruption.

Note: The template contains {{PLACEHOLDER}} markers. These are NOT rendered by the engine — they are filled by the LLM at runtime based on the decomposition results.

Step 1.5 — Detect Decomposition Mode

Check if test plan exists at ai/epics/epic-XXXX/plans/tests-story-XXXX-YYYY.md:

  1. File exists AND has structured TPP scenario markers (scenario IDs like UT-01:, AT-01:, IT-01: at start of line under a dedicated scenarios section):

    • Use TEST-DRIVEN MODE (proceed to STEP 2A)
    • Derive tasks from test scenarios with RED/GREEN/REFACTOR structure
  2. File exists but NO structured TPP markers (may mention TPP/UT/AT in prose but lacks scenario ID lines):

    • Use LAYER-BASED MODE (proceed to STEP 2B)
    • Emit warning: "Test plan found but lacks structured TPP markers. Falling back to layer-based decomposition (G1-G7)."
  3. File absent:

    • Use LAYER-BASED MODE (proceed to STEP 2B)
    • Emit warning: "No test plan found. Falling back to layer-based decomposition (G1-G7)."

Step 2A — Test-Driven Decomposition (Primary Mode)

Used when a test plan with TPP markers is available at ai/epics/epic-XXXX/plans/tests-story-XXXX-YYYY.md.

For each test scenario in the test plan (ordered by TPP level):

  1. Map scenario to task: One task per test scenario (UT/IT/AT)
  2. Identify layer components: Which layers does this scenario touch?
  3. Determine dependencies: Which tasks must complete before this one?
  4. Assess parallelism: Can this task run concurrently with others?
  5. Assign tier: Based on the highest-complexity layer touched

TDD Task Structure

Each generated task MUST contain:

Field Required Description
Test Scenario M Reference to UT-N, IT-N, or AT-N from test plan
TPP Level M 1-7 from TPP ordering
RED M What the test asserts (expected behavior)
GREEN M Minimum implementation to make test pass
REFACTOR O Refactoring opportunities after green
Layer Components M Which layers/classes are touched
Parallel M yes/no — can run concurrently with other tasks
Depends On M List of prerequisite TASK-N references
Tier M Junior/Mid/Senior based on complexity
Budget M S/M/L context budget

Parallelism Detection

A task is parallelizable when ALL of:

  1. Its test scenario operates on different layers than concurrent tasks
  2. No shared state with concurrent tasks
  3. No dependency on output of concurrent tasks

Ordering Rules

  1. Unit test tasks ordered by TPP level (degenerate first, complex last)
  2. Within same TPP level, inner layers before outer layers
  3. Acceptance test tasks ALWAYS come after ALL related unit test tasks
  4. Tasks with dependencies come after their prerequisites

Task Type Classification

Scenario Type Task Marker Dependency Rule
UT (Unit Test) [UT] Depends on earlier TPP-level tasks that create shared components
AT (Acceptance Test) [AT] Depends on ALL related UT tasks
IT (Integration Test) [IT] Depends on UT tasks for involved components

TDD Task Output Format

When using test-driven mode, generate tasks in this format:

### TASK-N: [UT-X/AT-X] scenario-name
- **TPP Level:** N
- **Type:** UT | AT | IT
- **Tier:** Junior | Mid | Senior
- **Budget:** S | M | L
- **Parallel:** yes | no
- **Depends On:** TASK-N, TASK-M (or "none")

**RED:** [What the test asserts — expected behavior]

**GREEN:** [Minimum implementation steps]
- Layer: component to create/modify
- Layer: component to create/modify

**REFACTOR:** [Optional refactoring opportunities]

**Layer Components:**
- domain.model: EntityName
- domain.port: PortName
- adapter.outbound: RepositoryName

After generating all TDD tasks, proceed to STEP 5 (Generate Output).

Step 2B — Identify Affected Layers (Layer-Based Fallback)

Used when no test plan with TPP markers is available.

For each section in the Architect's plan, check which architectural layers are involved. Mark each layer as active or inactive.

Step 3B — Apply the Layer Task Catalog (Layer-Based Fallback)

Used when no test plan with TPP markers is available.

For each active layer, create ONE task using the fixed catalog below.

Step 4B — Variable Tier Decision (Layer-Based Fallback)

Used when no test plan with TPP markers is available.

For complex domain logic tasks, read the Architect's plan carefully:

  • Simple mapping/lookup (1 decision, no state) -> Mid tier
  • Multi-branch logic (type hierarchies with 3+ implementations, resilience patterns) -> Senior tier

Step 5 — Generate Output

Save to: ai/epics/epic-XXXX/plans/tasks-story-XXXX-YYYY.md (extract epic ID XXXX and story sequence YYYY from the story ID). Ensure directory exists: mkdir -p ai/epics/epic-XXXX/plans.

Output format selection:

  • If the template was loaded in STEP 1, structure the output following the template's sections (Header, Summary, Dependency Graph, Tasks Table, Escalation Notes)
  • If the template was not found (fallback), use the inline TDD Task Output Format (STEP 2A) or Layer Task Catalog format (STEP 2B) as defined in this skill

Fallback: Layer Task Catalog (G1-G7)

When to use: Only when no test plan with TPP markers exists at ai/epics/epic-XXXX/plans/tests-story-XXXX-YYYY.md. Prefer test-driven decomposition when test plan is available.

Derive the task catalog from the layer-templates knowledge pack (knowledge/layer-templates.md). Each section in the knowledge pack corresponds to one task type. The table below shows the generic structure — adapt layer names and packages to match YOUR project's architecture rules (knowledge/architecture/architecture-principles.md).

Task Type Architecture Layer Tier Budget Group
Database Migration migration Junior S G1
Domain Models domain model Junior S G1
Ports (Inbound Interfaces) domain port inbound Junior S G2
Ports (Outbound Interfaces) domain port outbound Junior S G2
DTOs (Request/Response) inbound adapter dto Junior S G2
Domain Engine/Rules (simple) domain engine Mid M G2
Domain Engine/Rules (complex) domain engine Senior L G2
Persistence Entity outbound adapter entity Junior S G3
Entity Mapper outbound adapter mapper Junior S G3
DTO Mapper (Inbound) inbound adapter mapper Junior S G3
Repository outbound adapter repo Mid M G3
Use Case (Application) application Mid M G4
REST Resource/Controller inbound adapter rest Mid M G5
Exception Mapper inbound adapter rest Mid M G5
Protocol Handler inbound adapter protocol Senior L G5
Configuration config Junior S G5
Observability (Spans/Metrics) cross-cutting Mid M G6
Unit Tests test Follows tested layer G7
Integration Tests test Mid M G7
API Tests test Mid M G7
E2E Tests test Mid M G7

Note: The exact package names (e.g., domain.model, adapter.outbound.entity) are defined in knowledge/architecture/architecture-principles.md. Consult that file for your project's specific package structure.

Fallback: Layer Dependency Graph (G1-G7)

When to use: Only when no test plan with TPP markers exists at ai/epics/epic-XXXX/plans/tests-story-XXXX-YYYY.md. Prefer test-driven decomposition when test plan is available.

The dependency direction follows the architecture rule: adapter.inbound → application → domain ← adapter.outbound. Groups are derived from this dependency chain:

G1: FOUNDATION (Migration + Domain Models) — PARALLEL
G2: CONTRACTS (Ports + DTOs + Engine) — PARALLEL, depends on G1
G3: OUTBOUND ADAPTERS (Entity + Mapper + Repository) — PARALLEL, depends on G1, G2
G4: ORCHESTRATION (Use Case) — SEQUENTIAL, depends on G2, G3
G5: INBOUND ADAPTERS (Controllers + Protocol Handlers + Config) — PARALLEL, depends on G4
G6: OBSERVABILITY — SEQUENTIAL, depends on G4, G5
G7: TESTS — PARALLEL (max 4 concurrent), depends on ALL previous

Note: Group contents may vary by project architecture. The principle is: inner layers first, then outer layers. Verify against knowledge/architecture/architecture-principles.md for your project.

Context Budget Sizes

Size Range Includes
S 100-200 lines Plan section + inline rules + 1 template
M 250-400 lines Plan section + rules files + dependency outputs
L 500-800 lines Story + plan + rules + dependency outputs + existing code

Review Tier Assignment

Each engineer's model tier = highest task tier in their review domain:

Engineer Relevant Task Types
Security Domain Engine, TCP Handler, Repository
QA All test tasks
Performance Domain Engine, TCP Handler, Repository
Database Migration, Entity, Repository
Observability Observability task
DevOps Config task
API DTOs, REST Resource

Tech Lead tier = story max task tier (highest across ALL tasks).

Escalation Rules

When a task fails compilation after 2 retries at its assigned tier:

  • Junior -> Mid (escalate)
  • Mid -> Senior (escalate)
  • Senior -> Flag for manual intervention

Target: < 15% of tasks escalate.

Error Handling

Scenario Action
Architect's plan not found Abort with message: "Plan file not found at expected path. Run planning phase first."
Story requirements file not found Abort with message: "Story file not found. Verify story ID and epic directory."
Template _TEMPLATE-TASK-BREAKDOWN.md missing Log warning, use inline format as fallback (RULE-012 — Graceful template fallback)
Test plan has no structured TPP markers Fall back to layer-based decomposition (G1-G7) with warning
Escalation threshold exceeded (>15% tasks escalate) Flag in output report for manual review

Integration Notes

Skill Relationship Context
x-implement-story called-by Invoked during Phase 1C
x-plan-tests reads Consumes test plan (Phase 1B output) when available
x-implement-story Phase 2 produces-for Output consumed by group-based or TDD-based implementation
  • Works with any layered architecture (hexagonal, clean, onion) — layer names derived from project rules
  • When test plan present: generates TDD tasks with RED/GREEN/REFACTOR structure
  • When test plan absent: generates layer-based tasks using G1-G7 catalog (backward compatible)
  • Idempotency (RULE-002 — Artifact reuse): Checks ai/epics/epic-XXXX/plans/tasks-story-XXXX-YYYY.md existence and staleness before regenerating. Second invocation with unchanged story reuses existing breakdown.
  • Template reference (RULE-007): Reads .claude/templates/_TEMPLATE-TASK-BREAKDOWN.md for standardized output format
  • Graceful fallback (RULE-012 — Graceful template fallback): Functions without template (pre-EPIC-0024 projects). Logs warning and uses inline format when template absent.

04 同仓库更多 Skills

review-bench
review-bench/edercnj_ia-dev-environment

x-parallel-eval

Detects and classifies file-collision risks between work units (tasks, stories, or epic phases) before parallel execution. Reads ## File Footprint blocks produced by x-task-plan / x-story-plan, applies the parallelism-heuristics knowledge pack (hard / regen / soft categories + hotspot overrides), and emits a collision matrix + serialization recommendation in Markdown (default) or JSON.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

parallelism-heuristics

Canonical catalog of file-collision heuristics for parallel task, story, and epic execution. Defines the File Footprint block format, the three Conflict Categories (hard / regen / soft), a hotspot list of high-contention paths, and the degrade-with-warning policy. Consumed by x-task-plan, x-story-plan, x-epic-map, x-parallel-eval, and x-dev-*-implement.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

x-watch-pr-ci

Polls a PR's CI checks and Copilot review status, blocking until checks complete or timeout. Returns one of 8 stable exit codes (SUCCESS=0, CI_PENDING_PROCEED=10, CI_FAILED=20, TIMEOUT=30, PR_ALREADY_MERGED=40, NO_CI_CONFIGURED=50, PR_CLOSED=60, PR_NOT_FOUND=70). Writes a versioned state-file for session resume.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

x-validate-docs

Documentation freshness gate: validates 6 dimensions (readme, api-specs, grpc-proto, adr, skill-docs, system-architecture) against code changes in a PR. Stack-aware — only validates targets declared/auto-detected from ProjectConfig.documentation.targets. Returns exit non-zero on staleness; produces structured report.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

x-update-system-architecture

Incrementally updates docs/architecture/system.md after an epic completes. Appends new entries to the Decision Log (§11) using x-internal-write-report --append (dedup by ## ID: marker) and surgically inserts component/integration changes into sections 1-10 via Edit. Idempotent: re-running with the same epic produces a byte-identical system.md.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

x-update-architecture

Incrementally updates the service architecture document with changes from architecture plans. Adds new components, integrations, flows, and ADR references without rewriting existing content. Use after implementation to keep architecture documentation current.

★ 0