Update README and implementer documentation to reflect changes in task orchestration and structure. Remove obsolete commands and templates related to initial implementation and code review. Enhance task decomposition workflow and clarify input specifications for improved task management.

2026-04-22 09:16:38 +00:00 · 2026-03-18 18:41:22 +02:00
parent d969bec3b6
commit ae69d02f1e
15 changed files with 659 additions and 400 deletions
@@ -1,8 +1,8 @@
 ---
 name: decompose
 description: |
-  Decompose planned components into atomic implementable features with bootstrap structure plan.
-  4-step workflow: bootstrap structure plan, feature decomposition, cross-component verification, and Jira task creation.
+  Decompose planned components into atomic implementable tasks with bootstrap structure plan.
+  3-step workflow: bootstrap structure plan, task decomposition with inline Jira ticket creation, and cross-task verification.
  Supports full decomposition (_docs/ structure) and single component mode.
  Trigger phrases:
  - "decompose", "decompose features", "feature decomposition"
@@ -11,15 +11,17 @@ description: |
 disable-model-invocation: true
 ---

-# Feature Decomposition
+# Task Decomposition

-Decompose planned components into atomic, implementable feature specs with a bootstrap structure plan through a systematic workflow.
+Decompose planned components into atomic, implementable task specs with a bootstrap structure plan through a systematic workflow. All tasks are named with their Jira ticket ID prefix in a flat directory.

 ## Core Principles

- **Atomic features**: each feature does one thing; if it exceeds 5 complexity points, split it
+- **Atomic tasks**: each task does one thing; if it exceeds 5 complexity points, split it
 - **Behavioral specs, not implementation plans**: describe what the system should do, not how to build it
- **Save immediately**: write artifacts to disk after each component; never accumulate unsaved work
+- **Flat structure**: all tasks are Jira-ID-prefixed files in TASKS_DIR — no component subdirectories
+- **Save immediately**: write artifacts to disk after each task; never accumulate unsaved work
+- **Jira inline**: create Jira ticket immediately after writing each task file
 - **Ask, don't assume**: when requirements are ambiguous, ask the user before proceeding
 - **Plan, don't code**: this workflow produces documents and Jira tasks, never implementation code

@@ -31,15 +33,14 @@ Determine the operating mode based on invocation before any other logic runs.
 - PLANS_DIR: `_docs/02_plans/`
 - TASKS_DIR: `_docs/02_tasks/`
 - Reads from: `_docs/00_problem/`, `_docs/01_solution/`, PLANS_DIR
- Runs Step 1 (bootstrap) + Step 2 (all components) + Step 3 (cross-verification) + Step 4 (Jira)
+- Runs Step 1 (bootstrap) + Step 2 (all components) + Step 3 (cross-verification)

 **Single component mode** (provided file is within `_docs/02_plans/` and inside a `components/` subdirectory):
 - PLANS_DIR: `_docs/02_plans/`
 - TASKS_DIR: `_docs/02_tasks/`
 - Derive component number and component name from the file path
 - Ask user for the parent Epic ID
- Runs Step 2 (that component only) + Step 4 (Jira)
- Overwrites existing feature files in that component's TASKS_DIR subdirectory
+- Runs Step 2 (that component only, appending to existing task numbering)

 Announce the detected mode and resolved paths to the user before proceeding.

@@ -71,11 +72,10 @@ Announce the detected mode and resolved paths to the user before proceeding.
 **Default:**
 1. PLANS_DIR contains `architecture.md` and `components/` — **STOP if missing**
 2. Create TASKS_DIR if it does not exist
-3. If TASKS_DIR already contains artifacts, ask user: **resume from last checkpoint or start fresh?**
+3. If TASKS_DIR already contains task files, ask user: **resume from last checkpoint or start fresh?**

 **Single component mode:**
 1. The provided component file exists and is non-empty — **STOP if missing**
-2. Create the component's subdirectory under TASKS_DIR if it does not exist

 ## Artifact Management

@@ -83,36 +83,30 @@ Announce the detected mode and resolved paths to the user before proceeding.

 ```
 TASKS_DIR/
-├── initial_structure.md                        (Step 1, full mode only)
-├── cross_dependencies.md                       (Step 3, full mode only)
-├── SUMMARY.md                                  (final)
-├── [##]_[component_name]/
-│   ├── [##].[##]_feature_[feature_name].md
-│   ├── [##].[##]_feature_[feature_name].md
-│   └── ...
-├── [##]_[component_name]/
-│   └── ...
-└── ...
+├── [JIRA-ID]_initial_structure.md
+├── [JIRA-ID]_[short_name].md
+├── [JIRA-ID]_[short_name].md
+├── ...
+└── _dependencies_table.md
 ```

+**Naming convention**: Each task file is initially saved with a temporary numeric prefix (`[##]_[short_name].md`). After creating the Jira ticket, rename the file to use the Jira ticket ID as prefix (`[JIRA-ID]_[short_name].md`). For example: `01_initial_structure.md` → `AZ-42_initial_structure.md`.
+
 ### Save Timing

 | Step | Save immediately after | Filename |
 |------|------------------------|----------|
-| Step 1 | Bootstrap structure plan complete | `initial_structure.md` |
-| Step 2 | Each component decomposed | `[##]_[name]/[##].[##]_feature_[feature_name].md` |
-| Step 3 | Cross-component verification complete | `cross_dependencies.md` |
-| Step 4 | Jira tasks created | Jira via MCP |
-| Final | All steps complete | `SUMMARY.md` |
+| Step 1 | Bootstrap structure plan complete + Jira ticket created + file renamed | `[JIRA-ID]_initial_structure.md` |
+| Step 2 | Each task decomposed + Jira ticket created + file renamed | `[JIRA-ID]_[short_name].md` |
+| Step 3 | Cross-task verification complete | `_dependencies_table.md` |

 ### Resumability

-If TASKS_DIR already contains artifacts:
+If TASKS_DIR already contains task files:

-1. List existing files and match them to the save timing table
-2. Identify the last completed component based on which feature files exist
-3. Resume from the next incomplete component
-4. Inform the user which components are being skipped
+1. List existing `*_*.md` files (excluding `_dependencies_table.md`) and count them
+2. Resume numbering from the next number (for temporary numeric prefix before Jira rename)
+3. Inform the user which tasks already exist and are being skipped

 ## Progress Tracking

@@ -123,13 +117,13 @@ At the start of execution, create a TodoWrite with all applicable steps. Update
 ### Step 1: Bootstrap Structure Plan (default mode only)

 **Role**: Professional software architect
-**Goal**: Produce `initial_structure.md` describing the project skeleton for implementation
-**Constraints**: This is a plan document, not code. The `implement-initial` command executes it.
+**Goal**: Produce `01_initial_structure.md` — the first task describing the project skeleton
+**Constraints**: This is a plan document, not code. The `/implement` skill executes it.

 1. Read architecture.md, all component specs, and system-flows.md from PLANS_DIR
 2. Read problem, solution, and restrictions from `_docs/00_problem/` and `_docs/01_solution/`
 3. Research best implementation patterns for the identified tech stack
-4. Document the structure plan using `templates/initial-structure.md`
+4. Document the structure plan using `templates/initial-structure-task.md`

 **Self-verification**:
 - [ ] All components have corresponding folders in the layout
@@ -138,124 +132,111 @@ At the start of execution, create a TodoWrite with all applicable steps. Update
 - [ ] Environment strategy covers dev, staging, production
 - [ ] Test structure includes unit and integration test locations

-**Save action**: Write `initial_structure.md`
+**Save action**: Write `01_initial_structure.md` (temporary numeric name)
+
+**Jira action**: Create a Jira ticket for this task under the "Bootstrap & Initial Structure" epic. Write the Jira ticket ID and Epic ID back into the task header.
+
+**Rename action**: Rename the file from `01_initial_structure.md` to `[JIRA-ID]_initial_structure.md` (e.g., `AZ-42_initial_structure.md`). Update the **Task** field inside the file to match the new filename.

 **BLOCKING**: Present structure plan summary to user. Do NOT proceed until user confirms.

 ---

-### Step 2: Feature Decomposition (all modes)
+### Step 2: Task Decomposition (all modes)

 **Role**: Professional software architect
-**Goal**: Decompose each component into atomic, implementable feature specs
+**Goal**: Decompose each component into atomic, implementable task specs — numbered sequentially starting from 02
 **Constraints**: Behavioral specs only — describe what, not how. No implementation code.

+**Numbering**: Tasks are numbered sequentially across all components in dependency order. Start from 02 (01 is initial_structure). In single component mode, start from the next available number in TASKS_DIR.
+
+**Component ordering**: Process components in dependency order — foundational components first (shared models, database), then components that depend on them.
+
 For each component (or the single provided component):

 1. Read the component's `description.md` and `tests.md` (if available)
-2. Decompose into atomic features; create only 1 feature if the component is simple or atomic
-3. Split into multiple features only when it is necessary and would be easier to implement
-4. Do not create features of other components — only features of the current component
-5. Each feature should be atomic, containing 0 APIs or a list of semantically connected APIs
-6. Write each feature spec using `templates/feature-spec.md`
-7. Estimate complexity per feature (1, 2, 3, 5 points); no feature should exceed 5 points — split if it does
-8. Note feature dependencies (within component and cross-component)
+2. Decompose into atomic tasks; create only 1 task if the component is simple or atomic
+3. Split into multiple tasks only when it is necessary and would be easier to implement
+4. Do not create tasks for other components — only tasks for the current component
+5. Each task should be atomic, containing 0 APIs or a list of semantically connected APIs
+6. Write each task spec using `templates/task.md`
+7. Estimate complexity per task (1, 2, 3, 5 points); no task should exceed 5 points — split if it does
+8. Note task dependencies (referencing Jira IDs of already-created dependency tasks, e.g., `AZ-42_initial_structure`)
+9. **Immediately after writing each task file**: create a Jira ticket, link it to the component's epic, write the Jira ticket ID and Epic ID back into the task header, then rename the file from `[##]_[short_name].md` to `[JIRA-ID]_[short_name].md`.

 **Self-verification** (per component):
- [ ] Every feature is atomic (single concern)
- [ ] No feature exceeds 5 complexity points
- [ ] Feature dependencies are noted
- [ ] Features cover all interfaces defined in the component spec
- [ ] No features duplicate work from other components
+- [ ] Every task is atomic (single concern)
+- [ ] No task exceeds 5 complexity points
+- [ ] Task dependencies reference correct Jira IDs
+- [ ] Tasks cover all interfaces defined in the component spec
+- [ ] No tasks duplicate work from other components
+- [ ] Every task has a Jira ticket linked to the correct epic

-**Save action**: Write each `[##]_[name]/[##].[##]_feature_[feature_name].md`
+**Save action**: Write each `[##]_[short_name].md` (temporary numeric name), create Jira ticket inline, then rename the file to `[JIRA-ID]_[short_name].md`. Update the **Task** field inside the file to match the new filename. Update **Dependencies** references in the file to use Jira IDs of the dependency tasks.

 ---

-### Step 3: Cross-Component Verification (default mode only)
+### Step 3: Cross-Task Verification (default mode only)

 **Role**: Professional software architect and analyst
-**Goal**: Verify feature consistency across all components
-**Constraints**: Review step — fix gaps found, do not add new features
+**Goal**: Verify task consistency and produce `_dependencies_table.md`
+**Constraints**: Review step — fix gaps found, do not add new tasks

-1. Verify feature dependencies across all components are consistent
-2. Check no gaps: every interface in architecture.md has features covering it
-3. Check no overlaps: features don't duplicate work across components
-4. Produce dependency matrix showing cross-component feature dependencies
-5. Determine recommended implementation order based on dependencies
+1. Verify task dependencies across all tasks are consistent
+2. Check no gaps: every interface in architecture.md has tasks covering it
+3. Check no overlaps: tasks don't duplicate work across components
+4. Check no circular dependencies in the task graph
+5. Produce `_dependencies_table.md` using `templates/dependencies-table.md`

 **Self-verification**:
- [ ] Every architecture interface is covered by at least one feature
- [ ] No circular feature dependencies across components
- [ ] Cross-component dependencies are explicitly noted in affected feature specs
+- [ ] Every architecture interface is covered by at least one task
+- [ ] No circular dependencies in the task graph
+- [ ] Cross-component dependencies are explicitly noted in affected task specs
+- [ ] `_dependencies_table.md` contains every task with correct dependencies

-**Save action**: Write `cross_dependencies.md`
+**Save action**: Write `_dependencies_table.md`

-**BLOCKING**: Present cross-component summary to user. Do NOT proceed until user confirms.
+**BLOCKING**: Present dependency summary to user. Do NOT proceed until user confirms.

 ---

-### Step 4: Jira Tasks (all modes)
-
-**Role**: Professional product manager
-**Goal**: Create Jira tasks from feature specs under the appropriate parent epics
-**Constraints**: Be concise — fewer words with the same meaning is better
-
-1. For each feature spec, create a Jira task following the parsing rules and field mapping from `gen_jira_task_and_branch.md` (skip branch creation and file renaming — those happen during implementation)
-2. In full mode: search Jira for epics matching component names/labels to find parent epic IDs
-3. In single component mode: use the Epic ID obtained during context resolution
-4. Do NOT create git branches or rename files — that happens during implementation
-
-**Self-verification**:
- [ ] Every feature has a corresponding Jira task
- [ ] Every task is linked to the correct parent epic
- [ ] Task descriptions match feature spec content
-
-**Save action**: Jira tasks created via MCP
-
---
-
-## Summary Report
-
-After all steps complete, write `SUMMARY.md` using `templates/summary.md` as structure.
-
 ## Common Mistakes

 - **Coding during decomposition**: this workflow produces specs, never code
- **Over-splitting**: don't create many features if the component is simple — 1 feature is fine
- **Features exceeding 5 points**: split them; no feature should be too complex for a single task
- **Cross-component features**: each feature belongs to exactly one component
+- **Over-splitting**: don't create many tasks if the component is simple — 1 task is fine
+- **Tasks exceeding 5 points**: split them; no task should be too complex for a single implementer
+- **Cross-component tasks**: each task belongs to exactly one component
 - **Skipping BLOCKING gates**: never proceed past a BLOCKING marker without user confirmation
 - **Creating git branches**: branch creation is an implementation concern, not a decomposition one
+- **Creating component subdirectories**: all tasks go flat in TASKS_DIR
+- **Forgetting Jira**: every task must have a Jira ticket created inline — do not defer to a separate step
+- **Forgetting to rename**: after Jira ticket creation, always rename the file from numeric prefix to Jira ID prefix

 ## Escalation Rules

 | Situation | Action |
 |-----------|--------|
 | Ambiguous component boundaries | ASK user |
-| Feature complexity exceeds 5 points after splitting | ASK user |
+| Task complexity exceeds 5 points after splitting | ASK user |
 | Missing component specs in PLANS_DIR | ASK user |
 | Cross-component dependency conflict | ASK user |
 | Jira epic not found for a component | ASK user for Epic ID |
-| Component naming | PROCEED, confirm at next BLOCKING gate |
+| Task naming | PROCEED, confirm at next BLOCKING gate |

 ## Methodology Quick Reference

 ```
 ┌────────────────────────────────────────────────────────────────┐
-│            Feature Decomposition (4-Step Method)               │
+│          Task Decomposition (3-Step Method)                     │
 ├────────────────────────────────────────────────────────────────┤
 │ CONTEXT: Resolve mode (default / single component)             │
-│ 1. Bootstrap Structure  → initial_structure.md (full only)     │
+│ 1. Bootstrap Structure  → [JIRA-ID]_initial_structure.md       │
 │    [BLOCKING: user confirms structure]                         │
-│ 2. Feature Decompose    → [##]_[name]/[##].[##]_feature_*     │
-│ 3. Cross-Verification   → cross_dependencies.md (full only)   │
+│ 2. Task Decompose       → [JIRA-ID]_[short_name].md each      │
+│ 3. Cross-Verification   → _dependencies_table.md              │
 │    [BLOCKING: user confirms dependencies]                      │
-│ 4. Jira Tasks           → Jira via MCP                        │
-│    ─────────────────────────────────────────────────           │
-│    Summary → SUMMARY.md                                        │
 ├────────────────────────────────────────────────────────────────┤
-│ Principles: Atomic features · Behavioral specs · Save now      │
-│             Ask don't assume · Plan don't code                 │
+│ Principles: Atomic tasks · Behavioral specs · Flat structure   │
+│   Jira inline · Rename to Jira ID · Save now · Ask don't assume│
 └────────────────────────────────────────────────────────────────┘
 ```