mirror of
https://github.com/azaion/ai-training.git
synced 2026-04-22 11:16:35 +00:00
Fix .cursor skills consistency: flow resolution, tracker-agnostic refs, report naming, error recovery
- Rewrite autopilot flow resolution to 4 deterministic rules based on source code + docs + state file presence - Replace all hard-coded Jira references with tracker-agnostic terminology across 30+ files - Move project-management.mdc to _project.md (project-specific, not portable with .cursor) - Rename FINAL_implementation_report.md to context-dependent names (implementation_report_tests/features/refactor) - Remove "acknowledged tech debt" option from test-run — failing tests must be fixed or removed - Add debug/error recovery protocol to protocols.md - Align directory paths: metrics -> 06_metrics/, add 05_security/, reviews/, 02_task_plans/ to README - Add missing skills (test-spec, test-run, new-task, ui-design) to README - Use language-appropriate comment syntax for Arrange/Act/Assert in coderule + testing rules - Copy updated coderule.mdc to parent suite/.cursor/rules/ - Raise max task complexity from 5 to 8 points in decompose - Skip test-spec Phase 4 (script generation) during planning context - Document per-batch vs post-implement test run as intentional - Add skill-internal state cross-check rule to state.md
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -24,7 +24,7 @@ Auto-chaining execution engine that drives the full BUILD → SHIP workflow. Det
|
||||
| `flows/greenfield.md` | Detection rules, step table, and auto-chain rules for new projects |
|
||||
| `flows/existing-code.md` | Detection rules, step table, and auto-chain rules for existing codebases |
|
||||
| `state.md` | State file format, rules, re-entry protocol, session boundaries |
|
||||
| `protocols.md` | User interaction, Jira MCP auth, choice format, error handling, status summary |
|
||||
| `protocols.md` | User interaction, tracker auth, choice format, error handling, status summary |
|
||||
|
||||
**On every invocation**: read all four files above before executing any logic.
|
||||
|
||||
@@ -43,10 +43,10 @@ Auto-chaining execution engine that drives the full BUILD → SHIP workflow. Det
|
||||
|
||||
Determine which flow to use:
|
||||
|
||||
1. If workspace has source code files **and** `_docs/` does not exist → **existing-code flow** (Pre-Step detection)
|
||||
2. If `_docs/_autopilot_state.md` exists and `step >= 2` (i.e. Document already ran) → **existing-code flow**
|
||||
3. If `_docs/_autopilot_state.md` exists and `step: done` AND workspace contains source code → **existing-code flow** (completed project re-entry — loops to New Task)
|
||||
4. Otherwise → **greenfield flow**
|
||||
1. If workspace has **no source code files** → **greenfield flow**
|
||||
2. If workspace has source code files **and** `_docs/` does not exist → **existing-code flow**
|
||||
3. If workspace has source code files **and** `_docs/` exists **and** `_docs/_autopilot_state.md` does not exist → **existing-code flow**
|
||||
4. If workspace has source code files **and** `_docs/_autopilot_state.md` exists → read the `flow` field from the state file and use that flow
|
||||
|
||||
After selecting the flow, apply its detection rules (first match wins) to determine the current step.
|
||||
|
||||
|
||||
@@ -88,7 +88,7 @@ If `_docs/02_tasks/` subfolders have some task files already (e.g., refactoring
|
||||
---
|
||||
|
||||
**Step 5 — Implement Tests**
|
||||
Condition: `_docs/02_tasks/todo/` contains task files AND `_dependencies_table.md` exists AND the autopilot state shows Step 4 (Decompose Tests) is completed AND `_docs/03_implementation/FINAL_implementation_report.md` does not exist
|
||||
Condition: `_docs/02_tasks/todo/` contains task files AND `_dependencies_table.md` exists AND the autopilot state shows Step 4 (Decompose Tests) is completed AND `_docs/03_implementation/implementation_report_tests.md` does not exist
|
||||
|
||||
Action: Read and execute `.cursor/skills/implement/SKILL.md`
|
||||
|
||||
@@ -99,7 +99,7 @@ If `_docs/03_implementation/` has batch reports, the implement skill detects com
|
||||
---
|
||||
|
||||
**Step 6 — Run Tests**
|
||||
Condition: `_docs/03_implementation/FINAL_implementation_report.md` exists AND the autopilot state shows Step 5 (Implement Tests) is completed AND the autopilot state does NOT show Step 6 (Run Tests) as completed
|
||||
Condition: `_docs/03_implementation/implementation_report_tests.md` exists AND the autopilot state shows Step 5 (Implement Tests) is completed AND the autopilot state does NOT show Step 6 (Run Tests) as completed
|
||||
|
||||
Action: Read and execute `.cursor/skills/test-run/SKILL.md`
|
||||
|
||||
@@ -140,7 +140,7 @@ The new-task skill interactively guides the user through defining new functional
|
||||
---
|
||||
|
||||
**Step 9 — Implement**
|
||||
Condition: the autopilot state shows Step 8 (New Task) is completed AND `_docs/03_implementation/` does not contain a FINAL report covering the new tasks (check state for distinction between test implementation and feature implementation)
|
||||
Condition: the autopilot state shows Step 8 (New Task) is completed AND `_docs/03_implementation/` does not contain an `implementation_report_*.md` file other than `implementation_report_tests.md` (the tests report from Step 5 is excluded from this check)
|
||||
|
||||
Action: Read and execute `.cursor/skills/implement/SKILL.md`
|
||||
|
||||
|
||||
@@ -119,16 +119,16 @@ If `_docs/02_tasks/` subfolders have some task files already, the decompose skil
|
||||
---
|
||||
|
||||
**Step 6 — Implement**
|
||||
Condition: `_docs/02_tasks/todo/` contains task files AND `_dependencies_table.md` exists AND `_docs/03_implementation/FINAL_implementation_report.md` does not exist
|
||||
Condition: `_docs/02_tasks/todo/` contains task files AND `_dependencies_table.md` exists AND `_docs/03_implementation/` does not contain any `implementation_report_*.md` file
|
||||
|
||||
Action: Read and execute `.cursor/skills/implement/SKILL.md`
|
||||
|
||||
If `_docs/03_implementation/` has batch reports, the implement skill detects completed tasks and continues.
|
||||
If `_docs/03_implementation/` has batch reports, the implement skill detects completed tasks and continues. The FINAL report filename is context-dependent — see implement skill documentation for naming convention.
|
||||
|
||||
---
|
||||
|
||||
**Step 7 — Run Tests**
|
||||
Condition: `_docs/03_implementation/FINAL_implementation_report.md` exists AND the autopilot state does NOT show Step 7 (Run Tests) as completed AND (`_docs/04_deploy/` does not exist or is incomplete)
|
||||
Condition: `_docs/03_implementation/` contains an `implementation_report_*.md` file AND the autopilot state does NOT show Step 7 (Run Tests) as completed AND (`_docs/04_deploy/` does not exist or is incomplete)
|
||||
|
||||
Action: Read and execute `.cursor/skills/test-run/SKILL.md`
|
||||
|
||||
|
||||
@@ -51,12 +51,11 @@ Rules:
|
||||
|
||||
## Work Item Tracker Authentication
|
||||
|
||||
Several workflow steps create work items (epics, tasks, links). The system supports **Jira MCP** and **Azure DevOps MCP** as interchangeable backends. Detect which is configured by listing available MCP servers.
|
||||
Several workflow steps create work items (epics, tasks, links). The system requires some task tracker MCP as interchangeable backend.
|
||||
|
||||
### Tracker Detection
|
||||
|
||||
1. Check for available MCP servers: Jira MCP (`user-Jira-MCP-Server`) or Azure DevOps MCP (`user-AzureDevops`)
|
||||
2. If both are available, ask the user which to use (Choose format)
|
||||
1. If there is no task tracker MCP or it is not authorized, ask the user about it
|
||||
3. Record the choice in the state file: `tracker: jira` or `tracker: ado`
|
||||
4. If neither is available, set `tracker: local` and proceed without external tracking
|
||||
|
||||
@@ -294,6 +293,71 @@ For steps that produce `_docs/` artifacts (problem, research, plan, decompose, d
|
||||
3. **Git safety net**: artifacts are committed with each autopilot step completion. To roll back: `git log --oneline _docs/` to find the commit, then `git checkout <commit> -- _docs/<folder>/`
|
||||
4. **State file rollback**: when rolling back artifacts, also update `_docs/_autopilot_state.md` to reflect the rolled-back step (set it to `in_progress`, clear completed date)
|
||||
|
||||
## Debug / Error Recovery Protocol
|
||||
|
||||
When the implement skill's auto-fix loop fails (code review FAIL after 2 auto-fix attempts) or an implementer subagent reports a blocker, the user is asked to intervene. This protocol guides the recovery process.
|
||||
|
||||
### Structured Debugging Workflow
|
||||
|
||||
When escalated to the user after implementation failure:
|
||||
|
||||
1. **Classify the failure** — determine the category:
|
||||
- **Missing dependency**: a package, service, or module the task needs but isn't available
|
||||
- **Logic error**: code runs but produces wrong results (assertion failures, incorrect output)
|
||||
- **Integration mismatch**: interfaces between components don't align (type errors, missing methods, wrong signatures)
|
||||
- **Environment issue**: Docker, database, network, or configuration problem
|
||||
- **Spec ambiguity**: the task spec is unclear or contradictory
|
||||
|
||||
2. **Reproduce** — isolate the failing behavior:
|
||||
- Run the specific failing test(s) in isolation
|
||||
- Check whether the failure is deterministic or intermittent
|
||||
- Capture the exact error message, stack trace, and relevant file:line
|
||||
|
||||
3. **Narrow scope** — focus on the minimal reproduction:
|
||||
- For logic errors: trace the data flow from input to the point of failure
|
||||
- For integration mismatches: compare the caller's expectations against the callee's actual interface
|
||||
- For environment issues: verify Docker services are running, DB is accessible, env vars are set
|
||||
|
||||
4. **Fix and verify** — apply the fix and confirm:
|
||||
- Make the minimal change that fixes the root cause
|
||||
- Re-run the failing test(s) to confirm the fix
|
||||
- Run the full test suite to check for regressions
|
||||
- If the fix changes a shared interface, check all consumers
|
||||
|
||||
5. **Report** — update the batch report with:
|
||||
- Root cause category
|
||||
- Fix applied (file:line, description)
|
||||
- Tests that now pass
|
||||
|
||||
### Common Recovery Patterns
|
||||
|
||||
| Failure Pattern | Typical Root Cause | Recovery Action |
|
||||
|----------------|-------------------|----------------|
|
||||
| ImportError / ModuleNotFoundError | Missing dependency or wrong path | Install dependency or fix import path |
|
||||
| TypeError on method call | Interface mismatch between tasks | Align caller with callee's actual signature |
|
||||
| AssertionError in test | Logic bug or wrong expected value | Fix logic or update test expectations |
|
||||
| ConnectionRefused | Service not running | Start Docker services, check docker-compose |
|
||||
| Timeout | Blocking I/O or infinite loop | Add timeout, fix blocking call |
|
||||
| FileNotFoundError | Hardcoded path or missing fixture | Make path configurable, add fixture |
|
||||
|
||||
### Escalation
|
||||
|
||||
If debugging does not resolve the issue after 2 focused attempts:
|
||||
|
||||
```
|
||||
══════════════════════════════════════
|
||||
DEBUG ESCALATION: [failure description]
|
||||
══════════════════════════════════════
|
||||
Root cause category: [category]
|
||||
Attempted fixes: [list]
|
||||
Current state: [what works, what doesn't]
|
||||
══════════════════════════════════════
|
||||
A) Continue debugging with more context
|
||||
B) Revert this batch and skip the task (move to backlog)
|
||||
C) Simplify the task scope and retry
|
||||
══════════════════════════════════════
|
||||
```
|
||||
|
||||
## Status Summary
|
||||
|
||||
On every invocation, before executing any skill, present a status summary built from the state file (with folder scan fallback). Use the Status Summary Template from the active flow file (`flows/greenfield.md` or `flows/existing-code.md`).
|
||||
|
||||
@@ -47,6 +47,7 @@ retry_count: 3
|
||||
5. **Never delete** the state file
|
||||
6. **Retry tracking**: increment `retry_count` on each failed auto-retry; reset to `0` on success. If `retry_count` reaches 3, set `status: failed`
|
||||
7. **Failed state on re-entry**: if `status: failed` with `retry_count: 3`, do NOT auto-retry — present the issue to the user first
|
||||
8. **Skill-internal state**: when the active skill maintains its own state file (e.g., document skill's `_docs/02_document/state.json`), the autopilot's `sub_step` field should reflect the skill's internal progress. On re-entry, cross-check the skill's state file against the autopilot's `sub_step` for consistency.
|
||||
|
||||
## State Detection
|
||||
|
||||
|
||||
@@ -27,7 +27,7 @@ Multi-phase code review that verifies implementation against task specs, checks
|
||||
|
||||
## Input
|
||||
|
||||
- List of task spec files that were just implemented (paths to `[JIRA-ID]_[short_name].md`)
|
||||
- List of task spec files that were just implemented (paths to `[TRACKER-ID]_[short_name].md`)
|
||||
- Changed files (detected via `git diff` or provided by the `/implement` skill)
|
||||
- Project context: `_docs/00_problem/restrictions.md`, `_docs/01_solution/solution.md`
|
||||
|
||||
|
||||
@@ -10,23 +10,23 @@ description: |
|
||||
- "prepare for implementation"
|
||||
- "decompose tests", "test decomposition"
|
||||
category: build
|
||||
tags: [decomposition, tasks, dependencies, jira, implementation-prep]
|
||||
tags: [decomposition, tasks, dependencies, work-items, implementation-prep]
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Task Decomposition
|
||||
|
||||
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.
|
||||
Decompose planned components into atomic, implementable task specs with a bootstrap structure plan through a systematic workflow. All tasks are named with their work item tracker ID prefix in a flat directory.
|
||||
|
||||
## Core Principles
|
||||
|
||||
- **Atomic tasks**: each task does one thing; if it exceeds 5 complexity points, split it
|
||||
- **Atomic tasks**: each task does one thing; if it exceeds 8 complexity points, split it
|
||||
- **Behavioral specs, not implementation plans**: describe what the system should do, not how to build it
|
||||
- **Flat structure**: all tasks are Jira-ID-prefixed files in TASKS_DIR — no component subdirectories
|
||||
- **Flat structure**: all tasks are tracker-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
|
||||
- **Tracker inline**: create work item 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
|
||||
- **Plan, don't code**: this workflow produces documents and work item tickets, never implementation code
|
||||
|
||||
## Context Resolution
|
||||
|
||||
@@ -122,23 +122,23 @@ Announce the detected mode and resolved paths to the user before proceeding.
|
||||
TASKS_DIR/
|
||||
├── _dependencies_table.md
|
||||
├── todo/
|
||||
│ ├── [JIRA-ID]_initial_structure.md
|
||||
│ ├── [JIRA-ID]_[short_name].md
|
||||
│ ├── [TRACKER-ID]_initial_structure.md
|
||||
│ ├── [TRACKER-ID]_[short_name].md
|
||||
│ └── ...
|
||||
├── backlog/
|
||||
└── done/
|
||||
```
|
||||
|
||||
**Naming convention**: Each task file is initially saved in `TASKS_TODO/` 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: `todo/01_initial_structure.md` → `todo/AZ-42_initial_structure.md`.
|
||||
**Naming convention**: Each task file is initially saved in `TASKS_TODO/` with a temporary numeric prefix (`[##]_[short_name].md`). After creating the work item ticket, rename the file to use the work item ticket ID as prefix (`[TRACKER-ID]_[short_name].md`). For example: `todo/01_initial_structure.md` → `todo/AZ-42_initial_structure.md`.
|
||||
|
||||
### Save Timing
|
||||
|
||||
| Step | Save immediately after | Filename |
|
||||
|------|------------------------|----------|
|
||||
| Step 1 | Bootstrap structure plan complete + Jira ticket created + file renamed | `todo/[JIRA-ID]_initial_structure.md` |
|
||||
| Step 1t | Test infrastructure bootstrap complete + Jira ticket created + file renamed | `todo/[JIRA-ID]_test_infrastructure.md` |
|
||||
| Step 2 | Each component task decomposed + Jira ticket created + file renamed | `todo/[JIRA-ID]_[short_name].md` |
|
||||
| Step 3 | Each blackbox test task decomposed + Jira ticket created + file renamed | `todo/[JIRA-ID]_[short_name].md` |
|
||||
| Step 1 | Bootstrap structure plan complete + work item ticket created + file renamed | `todo/[TRACKER-ID]_initial_structure.md` |
|
||||
| Step 1t | Test infrastructure bootstrap complete + work item ticket created + file renamed | `todo/[TRACKER-ID]_test_infrastructure.md` |
|
||||
| Step 2 | Each component task decomposed + work item ticket created + file renamed | `todo/[TRACKER-ID]_[short_name].md` |
|
||||
| Step 3 | Each blackbox test task decomposed + work item ticket created + file renamed | `todo/[TRACKER-ID]_[short_name].md` |
|
||||
| Step 4 | Cross-task verification complete | `_dependencies_table.md` |
|
||||
|
||||
### Resumability
|
||||
@@ -146,7 +146,7 @@ TASKS_DIR/
|
||||
If TASKS_DIR subfolders already contain task files:
|
||||
|
||||
1. List existing `*_*.md` files across `todo/`, `backlog/`, and `done/` (excluding `_dependencies_table.md`) and count them
|
||||
2. Resume numbering from the next number (for temporary numeric prefix before Jira rename)
|
||||
2. Resume numbering from the next number (for temporary numeric prefix before tracker rename)
|
||||
3. Inform the user which tasks already exist and are being skipped
|
||||
|
||||
## Progress Tracking
|
||||
@@ -183,9 +183,9 @@ The test infrastructure bootstrap must include:
|
||||
|
||||
**Save action**: Write `todo/01_test_infrastructure.md` (temporary numeric name)
|
||||
|
||||
**Jira action**: Create a Jira ticket for this task under the "Blackbox Tests" epic. Write the Jira ticket ID and Epic ID back into the task header.
|
||||
**Tracker action**: Create a work item ticket for this task under the "Blackbox Tests" epic. Write the work item ticket ID and Epic ID back into the task header.
|
||||
|
||||
**Rename action**: Rename the file from `todo/01_test_infrastructure.md` to `todo/[JIRA-ID]_test_infrastructure.md`. Update the **Task** field inside the file to match the new filename.
|
||||
**Rename action**: Rename the file from `todo/01_test_infrastructure.md` to `todo/[TRACKER-ID]_test_infrastructure.md`. Update the **Task** field inside the file to match the new filename.
|
||||
|
||||
**BLOCKING**: Present test infrastructure plan summary to user. Do NOT proceed until user confirms.
|
||||
|
||||
@@ -231,9 +231,9 @@ The bootstrap structure plan must include:
|
||||
|
||||
**Save action**: Write `todo/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.
|
||||
**Tracker action**: Create a work item ticket for this task under the "Bootstrap & Initial Structure" epic. Write the work item ticket ID and Epic ID back into the task header.
|
||||
|
||||
**Rename action**: Rename the file from `todo/01_initial_structure.md` to `todo/[JIRA-ID]_initial_structure.md` (e.g., `todo/AZ-42_initial_structure.md`). Update the **Task** field inside the file to match the new filename.
|
||||
**Rename action**: Rename the file from `todo/01_initial_structure.md` to `todo/[TRACKER-ID]_initial_structure.md` (e.g., `todo/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.
|
||||
|
||||
@@ -257,19 +257,19 @@ For each component (or the single provided component):
|
||||
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 `todo/[##]_[short_name].md` to `todo/[JIRA-ID]_[short_name].md`.
|
||||
7. Estimate complexity per task (1, 2, 3, 5, 8 points); no task should exceed 8 points — split if it does
|
||||
8. Note task dependencies (referencing tracker IDs of already-created dependency tasks, e.g., `AZ-42_initial_structure`)
|
||||
9. **Immediately after writing each task file**: create a work item ticket, link it to the component's epic, write the work item ticket ID and Epic ID back into the task header, then rename the file from `todo/[##]_[short_name].md` to `todo/[TRACKER-ID]_[short_name].md`.
|
||||
|
||||
**Self-verification** (per component):
|
||||
- [ ] Every task is atomic (single concern)
|
||||
- [ ] No task exceeds 5 complexity points
|
||||
- [ ] Task dependencies reference correct Jira IDs
|
||||
- [ ] No task exceeds 8 complexity points
|
||||
- [ ] Task dependencies reference correct tracker 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
|
||||
- [ ] Every task has a work item ticket linked to the correct epic
|
||||
|
||||
**Save action**: Write each `todo/[##]_[short_name].md` (temporary numeric name), create Jira ticket inline, then rename to `todo/[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.
|
||||
**Save action**: Write each `todo/[##]_[short_name].md` (temporary numeric name), create work item ticket inline, then rename to `todo/[TRACKER-ID]_[short_name].md`. Update the **Task** field inside the file to match the new filename. Update **Dependencies** references in the file to use tracker IDs of the dependency tasks.
|
||||
|
||||
---
|
||||
|
||||
@@ -290,18 +290,18 @@ For each component (or the single provided component):
|
||||
- In default mode: blackbox test tasks depend on the component implementation tasks they exercise
|
||||
- In tests-only mode: blackbox test tasks depend on the test infrastructure bootstrap task (Step 1t)
|
||||
5. Write each task spec using `templates/task.md`
|
||||
6. Estimate complexity per task (1, 2, 3, 5 points); no task should exceed 5 points — split if it does
|
||||
7. Note task dependencies (referencing Jira IDs of already-created dependency tasks)
|
||||
8. **Immediately after writing each task file**: create a Jira ticket under the "Blackbox Tests" epic, write the Jira ticket ID and Epic ID back into the task header, then rename the file from `todo/[##]_[short_name].md` to `todo/[JIRA-ID]_[short_name].md`.
|
||||
6. Estimate complexity per task (1, 2, 3, 5, 8 points); no task should exceed 8 points — split if it does
|
||||
7. Note task dependencies (referencing tracker IDs of already-created dependency tasks)
|
||||
8. **Immediately after writing each task file**: create a work item ticket under the "Blackbox Tests" epic, write the work item ticket ID and Epic ID back into the task header, then rename the file from `todo/[##]_[short_name].md` to `todo/[TRACKER-ID]_[short_name].md`.
|
||||
|
||||
**Self-verification**:
|
||||
- [ ] Every scenario from `tests/blackbox-tests.md` is covered by a task
|
||||
- [ ] Every scenario from `tests/performance-tests.md`, `tests/resilience-tests.md`, `tests/security-tests.md`, and `tests/resource-limit-tests.md` is covered by a task
|
||||
- [ ] No task exceeds 5 complexity points
|
||||
- [ ] No task exceeds 8 complexity points
|
||||
- [ ] Dependencies correctly reference the dependency tasks (component tasks in default mode, test infrastructure in tests-only mode)
|
||||
- [ ] Every task has a Jira ticket linked to the "Blackbox Tests" epic
|
||||
- [ ] Every task has a work item ticket linked to the "Blackbox Tests" epic
|
||||
|
||||
**Save action**: Write each `todo/[##]_[short_name].md` (temporary numeric name), create Jira ticket inline, then rename to `todo/[JIRA-ID]_[short_name].md`.
|
||||
**Save action**: Write each `todo/[##]_[short_name].md` (temporary numeric name), create work item ticket inline, then rename to `todo/[TRACKER-ID]_[short_name].md`.
|
||||
|
||||
---
|
||||
|
||||
@@ -343,23 +343,23 @@ Tests-only mode:
|
||||
|
||||
- **Coding during decomposition**: this workflow produces specs, never code
|
||||
- **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
|
||||
- **Tasks exceeding 8 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_TODO/`
|
||||
- **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
|
||||
- **Forgetting tracker**: every task must have a work item ticket created inline — do not defer to a separate step
|
||||
- **Forgetting to rename**: after work item ticket creation, always rename the file from numeric prefix to tracker ID prefix
|
||||
|
||||
## Escalation Rules
|
||||
|
||||
| Situation | Action |
|
||||
|-----------|--------|
|
||||
| Ambiguous component boundaries | ASK user |
|
||||
| Task complexity exceeds 5 points after splitting | ASK user |
|
||||
| Task complexity exceeds 8 points after splitting | ASK user |
|
||||
| Missing component specs in DOCUMENT_DIR | ASK user |
|
||||
| Cross-component dependency conflict | ASK user |
|
||||
| Jira epic not found for a component | ASK user for Epic ID |
|
||||
| Tracker epic not found for a component | ASK user for Epic ID |
|
||||
| Task naming | PROCEED, confirm at next BLOCKING gate |
|
||||
|
||||
## Methodology Quick Reference
|
||||
@@ -371,24 +371,24 @@ Tests-only mode:
|
||||
│ CONTEXT: Resolve mode (default / single component / tests-only)│
|
||||
│ │
|
||||
│ DEFAULT MODE: │
|
||||
│ 1. Bootstrap Structure → [JIRA-ID]_initial_structure.md │
|
||||
│ 1. Bootstrap Structure → [TRACKER-ID]_initial_structure.md │
|
||||
│ [BLOCKING: user confirms structure] │
|
||||
│ 2. Component Tasks → [JIRA-ID]_[short_name].md each │
|
||||
│ 3. Blackbox Tests → [JIRA-ID]_[short_name].md each │
|
||||
│ 2. Component Tasks → [TRACKER-ID]_[short_name].md each │
|
||||
│ 3. Blackbox Tests → [TRACKER-ID]_[short_name].md each │
|
||||
│ 4. Cross-Verification → _dependencies_table.md │
|
||||
│ [BLOCKING: user confirms dependencies] │
|
||||
│ │
|
||||
│ TESTS-ONLY MODE: │
|
||||
│ 1t. Test Infrastructure → [JIRA-ID]_test_infrastructure.md │
|
||||
│ 1t. Test Infrastructure → [TRACKER-ID]_test_infrastructure.md │
|
||||
│ [BLOCKING: user confirms test scaffold] │
|
||||
│ 3. Blackbox Tests → [JIRA-ID]_[short_name].md each │
|
||||
│ 3. Blackbox Tests → [TRACKER-ID]_[short_name].md each │
|
||||
│ 4. Cross-Verification → _dependencies_table.md │
|
||||
│ [BLOCKING: user confirms dependencies] │
|
||||
│ │
|
||||
│ SINGLE COMPONENT MODE: │
|
||||
│ 2. Component Tasks → [JIRA-ID]_[short_name].md each │
|
||||
│ 2. Component Tasks → [TRACKER-ID]_[short_name].md each │
|
||||
├────────────────────────────────────────────────────────────────┤
|
||||
│ Principles: Atomic tasks · Behavioral specs · Flat structure │
|
||||
│ Jira inline · Rename to Jira ID · Save now · Ask don't assume│
|
||||
│ Tracker inline · Rename to tracker ID · Save now · Ask don't assume│
|
||||
└────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
@@ -13,10 +13,10 @@ Use this template after cross-task verification. Save as `TASKS_DIR/_dependencie
|
||||
|
||||
| Task | Name | Complexity | Dependencies | Epic |
|
||||
|------|------|-----------|-------------|------|
|
||||
| [JIRA-ID] | initial_structure | [points] | None | [EPIC-ID] |
|
||||
| [JIRA-ID] | [short_name] | [points] | [JIRA-ID] | [EPIC-ID] |
|
||||
| [JIRA-ID] | [short_name] | [points] | [JIRA-ID] | [EPIC-ID] |
|
||||
| [JIRA-ID] | [short_name] | [points] | [JIRA-ID], [JIRA-ID] | [EPIC-ID] |
|
||||
| [TRACKER-ID] | initial_structure | [points] | None | [EPIC-ID] |
|
||||
| [TRACKER-ID] | [short_name] | [points] | [TRACKER-ID] | [EPIC-ID] |
|
||||
| [TRACKER-ID] | [short_name] | [points] | [TRACKER-ID] | [EPIC-ID] |
|
||||
| [TRACKER-ID] | [short_name] | [points] | [TRACKER-ID], [TRACKER-ID] | [EPIC-ID] |
|
||||
| ... | ... | ... | ... | ... |
|
||||
```
|
||||
|
||||
@@ -25,7 +25,7 @@ Use this template after cross-task verification. Save as `TASKS_DIR/_dependencie
|
||||
## Guidelines
|
||||
|
||||
- Every task from TASKS_DIR must appear in this table
|
||||
- Dependencies column lists Jira IDs (e.g., "AZ-43, AZ-44") or "None"
|
||||
- Dependencies column lists tracker IDs (e.g., "AZ-43, AZ-44") or "None"
|
||||
- No circular dependencies allowed
|
||||
- Tasks should be listed in recommended execution order
|
||||
- The `/implement` skill reads this table to compute parallel batches
|
||||
|
||||
@@ -1,19 +1,19 @@
|
||||
# Initial Structure Task Template
|
||||
|
||||
Use this template for the bootstrap structure plan. Save as `TASKS_DIR/01_initial_structure.md` initially, then rename to `TASKS_DIR/[JIRA-ID]_initial_structure.md` after Jira ticket creation.
|
||||
Use this template for the bootstrap structure plan. Save as `TASKS_DIR/01_initial_structure.md` initially, then rename to `TASKS_DIR/[TRACKER-ID]_initial_structure.md` after work item ticket creation.
|
||||
|
||||
---
|
||||
|
||||
```markdown
|
||||
# Initial Project Structure
|
||||
|
||||
**Task**: [JIRA-ID]_initial_structure
|
||||
**Task**: [TRACKER-ID]_initial_structure
|
||||
**Name**: Initial Structure
|
||||
**Description**: Scaffold the project skeleton — folders, shared models, interfaces, stubs, CI/CD, DB migrations, test structure
|
||||
**Complexity**: [3|5] points
|
||||
**Dependencies**: None
|
||||
**Component**: Bootstrap
|
||||
**Jira**: [TASK-ID]
|
||||
**Tracker**: [TASK-ID]
|
||||
**Epic**: [EPIC-ID]
|
||||
|
||||
## Project Folder Layout
|
||||
|
||||
@@ -1,20 +1,20 @@
|
||||
# Task Specification Template
|
||||
|
||||
Create a focused behavioral specification that describes **what** the system should do, not **how** it should be built.
|
||||
Save as `TASKS_DIR/[##]_[short_name].md` initially, then rename to `TASKS_DIR/[JIRA-ID]_[short_name].md` after Jira ticket creation.
|
||||
Save as `TASKS_DIR/[##]_[short_name].md` initially, then rename to `TASKS_DIR/[TRACKER-ID]_[short_name].md` after work item ticket creation.
|
||||
|
||||
---
|
||||
|
||||
```markdown
|
||||
# [Feature Name]
|
||||
|
||||
**Task**: [JIRA-ID]_[short_name]
|
||||
**Task**: [TRACKER-ID]_[short_name]
|
||||
**Name**: [short human name]
|
||||
**Description**: [one-line description of what this task delivers]
|
||||
**Complexity**: [1|2|3|5] points
|
||||
**Complexity**: [1|2|3|5|8] points
|
||||
**Dependencies**: [AZ-43_shared_models, AZ-44_db_migrations] or "None"
|
||||
**Component**: [component name for context]
|
||||
**Jira**: [TASK-ID]
|
||||
**Tracker**: [TASK-ID]
|
||||
**Epic**: [EPIC-ID]
|
||||
|
||||
## Problem
|
||||
@@ -91,7 +91,8 @@ Then [expected result]
|
||||
- 2 points: Non-trivial, low complexity, minimal coordination
|
||||
- 3 points: Multi-step, moderate complexity, potential alignment needed
|
||||
- 5 points: Difficult, interconnected logic, medium-high risk
|
||||
- 8 points: Too complex — split into smaller tasks
|
||||
- 8 points: High difficulty, high ambiguity or coordination, multiple components
|
||||
- 13 points: Too complex — split into smaller tasks
|
||||
|
||||
## Output Guidelines
|
||||
|
||||
@@ -102,7 +103,7 @@ Then [expected result]
|
||||
- Include realistic scope boundaries
|
||||
- Write from the user's perspective
|
||||
- Include complexity estimation
|
||||
- Reference dependencies by Jira ID (e.g., AZ-43_shared_models)
|
||||
- Reference dependencies by tracker ID (e.g., AZ-43_shared_models)
|
||||
|
||||
**DON'T:**
|
||||
- Include implementation details (file paths, classes, methods)
|
||||
|
||||
@@ -1,19 +1,19 @@
|
||||
# Test Infrastructure Task Template
|
||||
|
||||
Use this template for the test infrastructure bootstrap (Step 1t in tests-only mode). Save as `TASKS_DIR/01_test_infrastructure.md` initially, then rename to `TASKS_DIR/[JIRA-ID]_test_infrastructure.md` after Jira ticket creation.
|
||||
Use this template for the test infrastructure bootstrap (Step 1t in tests-only mode). Save as `TASKS_DIR/01_test_infrastructure.md` initially, then rename to `TASKS_DIR/[TRACKER-ID]_test_infrastructure.md` after work item ticket creation.
|
||||
|
||||
---
|
||||
|
||||
```markdown
|
||||
# Test Infrastructure
|
||||
|
||||
**Task**: [JIRA-ID]_test_infrastructure
|
||||
**Task**: [TRACKER-ID]_test_infrastructure
|
||||
**Name**: Test Infrastructure
|
||||
**Description**: Scaffold the Blackbox test project — test runner, mock services, Docker test environment, test data fixtures, reporting
|
||||
**Complexity**: [3|5] points
|
||||
**Dependencies**: None
|
||||
**Component**: Blackbox Tests
|
||||
**Jira**: [TASK-ID]
|
||||
**Tracker**: [TASK-ID]
|
||||
**Epic**: [EPIC-ID]
|
||||
|
||||
## Test Project Folder Layout
|
||||
|
||||
@@ -85,7 +85,7 @@ For each task in the batch:
|
||||
|
||||
### 5. Update Tracker Status → In Progress
|
||||
|
||||
For each task in the batch, transition its ticket status to **In Progress** via the configured work item tracker (Jira MCP or Azure DevOps MCP — see `protocols.md` for detection) before launching the implementer. If `tracker: local`, skip this step.
|
||||
For each task in the batch, transition its ticket status to **In Progress** via the configured work item tracker (see `protocols.md` for tracker detection) before launching the implementer. If `tracker: local`, skip this step.
|
||||
|
||||
### 6. Launch Implementer Subagents
|
||||
|
||||
@@ -132,12 +132,13 @@ Track `auto_fix_attempts` count in the batch report for retrospective analysis.
|
||||
|
||||
- Read and execute `.cursor/skills/test-run/SKILL.md` (detect runner, run suite, diagnose failures, present blocking choices)
|
||||
- Test failures are a **blocking gate** — do not proceed to commit until the test-run skill completes with a user decision
|
||||
- Note: the autopilot also runs a separate full test suite after all implementation batches complete (greenfield Step 7, existing-code Steps 6/10). This is intentional — per-batch tests are regression checks, the post-implement run is final validation.
|
||||
|
||||
### 11. Commit and Push
|
||||
|
||||
- After user confirms the batch (explicitly for FAIL, implicitly for PASS/PASS_WITH_WARNINGS):
|
||||
- `git add` all changed files from the batch
|
||||
- `git commit` with a message that includes ALL task IDs (Jira IDs, ADO IDs, or numeric prefixes) of tasks implemented in the batch, followed by a summary of what was implemented. Format: `[TASK-ID-1] [TASK-ID-2] ... Summary of changes`
|
||||
- `git commit` with a message that includes ALL task IDs (tracker IDs or numeric prefixes) of tasks implemented in the batch, followed by a summary of what was implemented. Format: `[TASK-ID-1] [TASK-ID-2] ... Summary of changes`
|
||||
- `git push` to the remote branch
|
||||
|
||||
### 12. Update Tracker Status → In Testing
|
||||
@@ -155,7 +156,13 @@ Move each completed task file from `TASKS_DIR/todo/` to `TASKS_DIR/done/`.
|
||||
|
||||
## Batch Report Persistence
|
||||
|
||||
After each batch completes, save the batch report to `_docs/03_implementation/batch_[NN]_report.md`. Create the directory if it doesn't exist. When all tasks are complete, produce `_docs/03_implementation/FINAL_implementation_report.md` with a summary of all batches.
|
||||
After each batch completes, save the batch report to `_docs/03_implementation/batch_[NN]_report.md`. Create the directory if it doesn't exist. When all tasks are complete, produce a FINAL implementation report with a summary of all batches. The filename depends on context:
|
||||
|
||||
- **Test implementation** (tasks from test decomposition): `_docs/03_implementation/implementation_report_tests.md`
|
||||
- **Feature implementation**: `_docs/03_implementation/implementation_report_{feature_slug}.md` where `{feature_slug}` is derived from the batch task names (e.g., `implementation_report_core_api.md`)
|
||||
- **Refactoring**: `_docs/03_implementation/implementation_report_refactor_{run_name}.md`
|
||||
|
||||
Determine the context from the task files being implemented: if all tasks have test-related names or belong to a test epic, use the tests filename; otherwise derive the feature slug from the component names.
|
||||
|
||||
## Batch Report
|
||||
|
||||
@@ -172,7 +179,7 @@ After each batch, produce a structured report:
|
||||
|
||||
| Task | Status | Files Modified | Tests | Issues |
|
||||
|------|--------|---------------|-------|--------|
|
||||
| [JIRA-ID]_[name] | Done | [count] files | [pass/fail] | [count or None] |
|
||||
| [TRACKER-ID]_[name] | Done | [count] files | [pass/fail] | [count or None] |
|
||||
|
||||
## Code Review Verdict: [PASS/FAIL/PASS_WITH_WARNINGS]
|
||||
## Auto-Fix Attempts: [0/1/2]
|
||||
|
||||
@@ -15,7 +15,7 @@ Use this template after each implementation batch completes.
|
||||
|
||||
| Task | Status | Files Modified | Tests | Issues |
|
||||
|------|--------|---------------|-------|--------|
|
||||
| [JIRA-ID]_[name] | Done/Blocked/Partial | [count] files | [X/Y pass] | [count or None] |
|
||||
| [TRACKER-ID]_[name] | Done/Blocked/Partial | [count] files | [X/Y pass] | [count or None] |
|
||||
|
||||
## Code Review Verdict: [PASS / FAIL / PASS_WITH_WARNINGS]
|
||||
|
||||
|
||||
@@ -4,19 +4,19 @@ description: |
|
||||
Interactive skill for adding new functionality to an existing codebase.
|
||||
Guides the user through describing the feature, assessing complexity,
|
||||
optionally running research, analyzing the codebase for insertion points,
|
||||
validating assumptions with the user, and producing a task spec with Jira ticket.
|
||||
validating assumptions with the user, and producing a task spec with work item ticket.
|
||||
Supports a loop — the user can add multiple tasks in one session.
|
||||
Trigger phrases:
|
||||
- "new task", "add feature", "new functionality"
|
||||
- "I want to add", "new component", "extend"
|
||||
category: build
|
||||
tags: [task, feature, interactive, planning, jira]
|
||||
tags: [task, feature, interactive, planning, work-items]
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# New Task (Interactive Feature Planning)
|
||||
|
||||
Guide the user through defining new functionality for an existing codebase. Produces one or more task specifications with Jira tickets, optionally running deep research for complex features.
|
||||
Guide the user through defining new functionality for an existing codebase. Produces one or more task specifications with work item tickets, optionally running deep research for complex features.
|
||||
|
||||
## Core Principles
|
||||
|
||||
@@ -197,11 +197,12 @@ Present using the Choose format for each decision that has meaningful alternativ
|
||||
**Goal**: Produce the task specification file.
|
||||
|
||||
1. Determine the next numeric prefix by scanning all TASKS_DIR subfolders (`todo/`, `backlog/`, `done/`) for existing files
|
||||
2. Write the task file using `.cursor/skills/decompose/templates/task.md`:
|
||||
2. If research was performed (Step 3), the research artifacts live in `PLANS_DIR/<task_slug>/` — reference them from the task spec where relevant
|
||||
3. Write the task file using `.cursor/skills/decompose/templates/task.md`:
|
||||
- Fill all fields from the gathered information
|
||||
- Set **Complexity** based on the assessment from Step 2
|
||||
- Set **Dependencies** by cross-referencing existing tasks in TASKS_DIR subfolders
|
||||
- Set **Jira** and **Epic** to `pending` (filled in Step 7)
|
||||
- Set **Tracker** and **Epic** to `pending` (filled in Step 7)
|
||||
3. Save as `TASKS_TODO/[##]_[short_name].md`
|
||||
|
||||
**Self-verification**:
|
||||
@@ -209,7 +210,7 @@ Present using the Choose format for each decision that has meaningful alternativ
|
||||
- [ ] Acceptance criteria are testable (Gherkin format)
|
||||
- [ ] Scope boundaries are explicit
|
||||
- [ ] Complexity points match the assessment
|
||||
- [ ] Dependencies reference existing task Jira IDs where applicable
|
||||
- [ ] Dependencies reference existing task tracker IDs where applicable
|
||||
- [ ] No implementation details leaked into the spec
|
||||
|
||||
---
|
||||
@@ -219,20 +220,20 @@ Present using the Choose format for each decision that has meaningful alternativ
|
||||
**Role**: Project coordinator
|
||||
**Goal**: Create a work item ticket and link it to the task file.
|
||||
|
||||
1. Create a ticket via the configured work item tracker (Jira MCP or Azure DevOps MCP — see `autopilot/protocols.md` for detection):
|
||||
1. Create a ticket via the configured work item tracker (see `autopilot/protocols.md` for tracker detection):
|
||||
- Summary: the task's **Name** field
|
||||
- Description: the task's **Problem** and **Acceptance Criteria** sections
|
||||
- Story points: the task's **Complexity** value
|
||||
- Link to the appropriate epic (ask user if unclear which epic)
|
||||
2. Write the ticket ID and Epic ID back into the task file header:
|
||||
- Update **Task** field: `[TICKET-ID]_[short_name]`
|
||||
- Update **Jira** field: `[TICKET-ID]`
|
||||
- Update **Tracker** field: `[TICKET-ID]`
|
||||
- Update **Epic** field: `[EPIC-ID]`
|
||||
3. Rename the file from `[##]_[short_name].md` to `[TICKET-ID]_[short_name].md`
|
||||
|
||||
If the work item tracker is not authenticated or unavailable (`tracker: local`):
|
||||
- Keep the numeric prefix
|
||||
- Set **Jira** to `pending`
|
||||
- Set **Tracker** to `pending`
|
||||
- Set **Epic** to `pending`
|
||||
- The task is still valid and can be implemented; tracker sync happens later
|
||||
|
||||
@@ -244,7 +245,7 @@ Ask the user:
|
||||
|
||||
```
|
||||
══════════════════════════════════════
|
||||
Task created: [JIRA-ID or ##] — [task name]
|
||||
Task created: [TRACKER-ID or ##] — [task name]
|
||||
══════════════════════════════════════
|
||||
A) Add another task
|
||||
B) Done — finish and update dependencies
|
||||
@@ -270,8 +271,8 @@ After the user chooses **Done**:
|
||||
Tasks created: N
|
||||
Total complexity: M points
|
||||
─────────────────────────────────────
|
||||
[JIRA-ID] [name] ([complexity] pts)
|
||||
[JIRA-ID] [name] ([complexity] pts)
|
||||
[TRACKER-ID] [name] ([complexity] pts)
|
||||
[TRACKER-ID] [name] ([complexity] pts)
|
||||
...
|
||||
══════════════════════════════════════
|
||||
```
|
||||
@@ -285,7 +286,7 @@ After the user chooses **Done**:
|
||||
| Research skill hits a blocker | Follow research skill's own escalation rules |
|
||||
| Codebase analysis reveals conflicting architectures | **ASK** user which pattern to follow |
|
||||
| Complexity exceeds 5 points | **WARN** user and suggest splitting into multiple tasks |
|
||||
| Jira MCP unavailable | **WARN**, continue with local-only task files |
|
||||
| Work item tracker MCP unavailable | **WARN**, continue with local-only task files |
|
||||
|
||||
## Trigger Conditions
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: plan
|
||||
description: |
|
||||
Decompose a solution into architecture, data model, deployment plan, system flows, components, tests, and Jira epics.
|
||||
Decompose a solution into architecture, data model, deployment plan, system flows, components, tests, and work item epics.
|
||||
Systematic planning workflow with BLOCKING gates, self-verification, and structured artifact management.
|
||||
Uses _docs/ + _docs/02_document/ structure.
|
||||
Trigger phrases:
|
||||
@@ -9,13 +9,13 @@ description: |
|
||||
- "break down the solution", "create planning documents"
|
||||
- "component decomposition", "solution analysis"
|
||||
category: build
|
||||
tags: [planning, architecture, components, testing, jira, epics]
|
||||
tags: [planning, architecture, components, testing, work-items, epics]
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Solution Planning
|
||||
|
||||
Decompose a problem and solution into architecture, data model, deployment plan, system flows, components, tests, and Jira epics through a systematic 6-step workflow.
|
||||
Decompose a problem and solution into architecture, data model, deployment plan, system flows, components, tests, and work item epics through a systematic 6-step workflow.
|
||||
|
||||
## Core Principles
|
||||
|
||||
@@ -61,7 +61,7 @@ At the start of execution, create a TodoWrite with all steps (1 through 6 plus F
|
||||
|
||||
### Step 1: Blackbox Tests
|
||||
|
||||
Read and execute `.cursor/skills/test-spec/SKILL.md`.
|
||||
Read and execute `.cursor/skills/test-spec/SKILL.md`. This is a planning context — no source code exists yet, so test-spec Phase 4 (script generation) is skipped. Script creation is handled later by the decompose skill as a task.
|
||||
|
||||
Capture any new questions, findings, or insights that arise during test specification — these feed forward into Steps 2 and 3.
|
||||
|
||||
@@ -91,9 +91,9 @@ Read and follow `steps/05_test-specifications.md`.
|
||||
|
||||
---
|
||||
|
||||
### Step 6: Jira Epics
|
||||
### Step 6: Work Item Epics
|
||||
|
||||
Read and follow `steps/06_jira-epics.md`.
|
||||
Read and follow `steps/06_work-item-epics.md`.
|
||||
|
||||
---
|
||||
|
||||
@@ -144,7 +144,7 @@ Read and follow `steps/07_quality-checklist.md`.
|
||||
│ 4. Review & Risk → risk register, iterations │
|
||||
│ [BLOCKING: user confirms mitigations] │
|
||||
│ 5. Test Specifications → per-component test specs │
|
||||
│ 6. Jira Epics → epic per component + bootstrap │
|
||||
│ 6. Work Item Epics → epic per component + bootstrap │
|
||||
│ ───────────────────────────────────────────────── │
|
||||
│ Final: Quality Checklist → FINAL_report.md │
|
||||
├────────────────────────────────────────────────────────────────┤
|
||||
|
||||
@@ -67,7 +67,7 @@ DOCUMENT_DIR/
|
||||
| Step 3 | Diagrams generated | `diagrams/` |
|
||||
| Step 4 | Risk assessment complete | `risk_mitigations.md` |
|
||||
| Step 5 | Tests written per component | `components/[##]_[name]/tests.md` |
|
||||
| Step 6 | Epics created in Jira | Jira via MCP |
|
||||
| Step 6 | Epics created in work item tracker | Tracker via MCP |
|
||||
| Final | All steps complete | `FINAL_report.md` |
|
||||
|
||||
### Save Principles
|
||||
|
||||
+2
-2
@@ -7,7 +7,7 @@
|
||||
**Constraints**: Epic descriptions must be **comprehensive and self-contained** — a developer reading only the epic should understand the full context without needing to open separate files.
|
||||
|
||||
1. **Create "Bootstrap & Initial Structure" epic first** — this epic will parent the `01_initial_structure` task created by the decompose skill. It covers project scaffolding: folder structure, shared models, interfaces, stubs, CI/CD config, DB migrations setup, test structure.
|
||||
2. Generate epics for each component using the configured work item tracker (Jira MCP or Azure DevOps MCP — see `autopilot/protocols.md`), structured per `templates/epic-spec.md`
|
||||
2. Generate epics for each component using the configured work item tracker (see `autopilot/protocols.md` for tracker detection), structured per `templates/epic-spec.md`
|
||||
3. Order epics by dependency (Bootstrap epic is always first, then components based on their dependency graph)
|
||||
4. Include effort estimation per epic (T-shirt size or story points range)
|
||||
5. Ensure each epic has clear acceptance criteria cross-referenced with component specs
|
||||
@@ -22,7 +22,7 @@ Each epic description MUST include ALL of the following sections with substantia
|
||||
- **Architecture notes**: relevant ADRs, technology choices, patterns used, key design decisions
|
||||
- **Interface specification**: full method signatures, input/output types, error types (from component description.md)
|
||||
- **Data flow**: how data enters and exits this component (include Mermaid sequence or flowchart diagram)
|
||||
- **Dependencies**: epic dependencies (with Jira IDs) and external dependencies (libraries, hardware, services)
|
||||
- **Dependencies**: epic dependencies (with tracker IDs) and external dependencies (libraries, hardware, services)
|
||||
- **Acceptance criteria**: measurable criteria with specific thresholds (from component tests.md)
|
||||
- **Non-functional requirements**: latency, memory, throughput targets with failure thresholds
|
||||
- **Risks & mitigations**: relevant risks from risk_mitigations.md with concrete mitigation strategies
|
||||
@@ -1,6 +1,6 @@
|
||||
# Epic Template
|
||||
|
||||
Use this template for each epic. Create epics via the configured work item tracker (Jira MCP or Azure DevOps MCP).
|
||||
Use this template for each epic. Create epics via the configured work item tracker (see `autopilot/protocols.md` for tracker detection).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -27,8 +27,8 @@ Use this template after completing all 6 steps and the quality checklist. Save a
|
||||
|
||||
| # | Component | Purpose | Dependencies | Epic |
|
||||
|---|-----------|---------|-------------|------|
|
||||
| 01 | [name] | [one-line purpose] | — | [Jira ID] |
|
||||
| 02 | [name] | [one-line purpose] | 01 | [Jira ID] |
|
||||
| 01 | [name] | [one-line purpose] | — | [Tracker ID] |
|
||||
| 02 | [name] | [one-line purpose] | 01 | [Tracker ID] |
|
||||
| ... | | | | |
|
||||
|
||||
**Implementation order** (based on dependency graph):
|
||||
@@ -71,8 +71,8 @@ Use this template after completing all 6 steps and the quality checklist. Save a
|
||||
|
||||
| Order | Epic | Component | Effort | Dependencies |
|
||||
|-------|------|-----------|--------|-------------|
|
||||
| 1 | [Jira ID]: [name] | [component] | [S/M/L/XL] | — |
|
||||
| 2 | [Jira ID]: [name] | [component] | [S/M/L/XL] | Epic 1 |
|
||||
| 1 | [Tracker ID]: [name] | [component] | [S/M/L/XL] | — |
|
||||
| 2 | [Tracker ID]: [name] | [component] | [S/M/L/XL] | Epic 1 |
|
||||
| ... | | | | |
|
||||
|
||||
**Total estimated effort**: [sum or range]
|
||||
|
||||
@@ -102,7 +102,7 @@ FINAL_report.md after all phases
|
||||
|
||||
Task files produced during Phase 2 go to TASKS_TODO (not RUN_DIR):
|
||||
```
|
||||
TASKS_TODO/[JIRA-ID]_refactor_[short_name].md
|
||||
TASKS_TODO/[TRACKER-ID]_refactor_[short_name].md
|
||||
TASKS_DIR/_dependencies_table.md (appended)
|
||||
```
|
||||
|
||||
|
||||
@@ -50,7 +50,7 @@ Write `RUN_DIR/analysis/refactoring_roadmap.md`:
|
||||
|
||||
## 2c. Create Epic
|
||||
|
||||
Create a Jira/ADO epic for this refactoring run:
|
||||
Create a work item tracker epic for this refactoring run:
|
||||
|
||||
1. Epic name: the RUN_DIR name (e.g., `01-testability-refactoring`)
|
||||
2. Create the epic via configured tracker MCP
|
||||
@@ -68,12 +68,12 @@ Convert the finalized `RUN_DIR/list-of-changes.md` into implementable task files
|
||||
- **Task**: `PENDING_refactor_[short_name]`
|
||||
- **Description**: derived from the change entry's Problem + Change fields
|
||||
- **Complexity**: estimate 1-5 points; split into multiple tasks if >5
|
||||
- **Dependencies**: map change-level dependencies (C01, C02) to task-level Jira IDs
|
||||
- **Dependencies**: map change-level dependencies (C01, C02) to task-level tracker IDs
|
||||
- **Component**: from the change entry's File(s) field
|
||||
- **Epic**: the epic created in 2c
|
||||
- **Acceptance Criteria**: derived from the change entry — verify the problem is resolved
|
||||
3. Create Jira/ADO ticket for each task under the epic from 2c
|
||||
4. Rename each file to `[JIRA-ID]_refactor_[short_name].md` after ticket creation
|
||||
3. Create work item ticket for each task under the epic from 2c
|
||||
4. Rename each file to `[TRACKER-ID]_refactor_[short_name].md` after ticket creation
|
||||
5. Update or append to `TASKS_DIR/_dependencies_table.md` with the refactoring tasks
|
||||
|
||||
**Self-verification**:
|
||||
@@ -85,7 +85,7 @@ Convert the finalized `RUN_DIR/list-of-changes.md` into implementable task files
|
||||
- [ ] No task exceeds 5 complexity points
|
||||
- [ ] Task dependencies are consistent (no circular dependencies)
|
||||
- [ ] `_dependencies_table.md` includes all refactoring tasks
|
||||
- [ ] Every task has a Jira ticket (or PENDING placeholder)
|
||||
- [ ] Every task has a work item ticket (or PENDING placeholder)
|
||||
|
||||
**Save action**: Write analysis artifacts to RUN_DIR, task files to TASKS_DIR
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
## 4a. Pre-Flight Checks
|
||||
|
||||
1. Verify refactoring task files exist in TASKS_DIR (created during Phase 2d):
|
||||
- All `[JIRA-ID]_refactor_*.md` files are present
|
||||
- All `[TRACKER-ID]_refactor_*.md` files are present
|
||||
- Each task file has valid header fields (Task, Name, Description, Complexity, Dependencies)
|
||||
2. Verify `TASKS_DIR/_dependencies_table.md` includes the refactoring tasks
|
||||
3. Verify all tests pass (safety net from Phase 3 is green)
|
||||
@@ -24,7 +24,7 @@ The implement skill will:
|
||||
4. Launch implementer subagents (up to 4 in parallel)
|
||||
5. Run code review after each batch
|
||||
6. Commit and push per batch
|
||||
7. Update Jira/ADO ticket status
|
||||
7. Update work item ticket status
|
||||
|
||||
Do NOT modify, skip, or abbreviate any part of the implement skill's workflow. The refactor skill is delegating execution, not optimizing it.
|
||||
|
||||
@@ -33,7 +33,7 @@ Do NOT modify, skip, or abbreviate any part of the implement skill's workflow. T
|
||||
After the implement skill completes:
|
||||
|
||||
1. Read batch reports from `_docs/03_implementation/batch_*_report.md`
|
||||
2. Read `_docs/03_implementation/FINAL_implementation_report.md`
|
||||
2. Read the latest `_docs/03_implementation/implementation_report_*.md` file
|
||||
3. Write `RUN_DIR/execution_log.md` summarizing:
|
||||
- Total tasks executed
|
||||
- Batches completed
|
||||
@@ -46,14 +46,14 @@ After the implement skill completes:
|
||||
|
||||
For each successfully completed refactoring task:
|
||||
|
||||
1. Transition the Jira/ADO ticket status to **Done** via the configured tracker MCP
|
||||
1. Transition the work item ticket status to **Done** via the configured tracker MCP
|
||||
2. If tracker unavailable, note the pending status transitions in `RUN_DIR/execution_log.md`
|
||||
|
||||
For any failed or blocked tasks, leave their status as-is (the implement skill already set them to In Testing or blocked).
|
||||
|
||||
**Self-verification**:
|
||||
- [ ] All refactoring tasks show as completed in batch reports
|
||||
- [ ] All completed tasks have Jira/ADO status set to Done
|
||||
- [ ] All completed tasks have work item tracker status set to Done
|
||||
- [ ] All tests still pass after execution
|
||||
- [ ] No tasks remain in blocked or failed state (or user has acknowledged them)
|
||||
- [ ] `RUN_DIR/execution_log.md` written with links to batch reports
|
||||
|
||||
@@ -44,6 +44,6 @@ Save as `RUN_DIR/list-of-changes.md`. Produced during Phase 1 (Discovery).
|
||||
- **File(s)** must reference actual files verified to exist in the codebase
|
||||
- **Problem** describes the current state, not the desired state
|
||||
- **Change** describes what the system should do differently — behavioral, not prescriptive
|
||||
- **Dependencies** reference other change IDs within this list; cross-run dependencies use Jira IDs
|
||||
- **Dependencies** reference other change IDs within this list; cross-run dependencies use tracker IDs
|
||||
- In guided mode, the input file entries are validated against actual code and enriched with file paths, risk, and dependencies before writing
|
||||
- In automatic mode, entries are derived from Phase 1 component analysis and Phase 2 research findings
|
||||
|
||||
@@ -72,7 +72,7 @@ At the start of execution, create a TodoWrite with all steps (1 through 3). Upda
|
||||
| `batch_*_report.md` | Tasks per batch, batch count, task statuses (Done/Blocked/Partial) |
|
||||
| Code review sections in batch reports | PASS/FAIL/PASS_WITH_WARNINGS ratios, finding counts by severity and category |
|
||||
| Task spec files in TASKS_DIR | Complexity points per task, dependency count |
|
||||
| `FINAL_implementation_report.md` | Total tasks, total batches, overall duration |
|
||||
| `implementation_report_*.md` | Total tasks, total batches, overall duration |
|
||||
| Git log (if available) | Commits per batch, files changed per batch |
|
||||
|
||||
#### Metrics to Compute
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Retrospective Report Template
|
||||
|
||||
Save as `_docs/05_metrics/retro_[YYYY-MM-DD].md`.
|
||||
Save as `_docs/06_metrics/retro_[YYYY-MM-DD].md`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -106,8 +106,7 @@ Categorize each as: **missing dependency**, **broken import**, **logic/assertion
|
||||
══════════════════════════════════════
|
||||
A) Investigate and fix failing tests/code, then re-run
|
||||
B) Remove obsolete tests (if diagnosis shows they are no longer relevant)
|
||||
C) Leave as-is — acknowledged tech debt (not recommended)
|
||||
D) Abort — fix manually
|
||||
C) Abort — fix manually
|
||||
══════════════════════════════════════
|
||||
Recommendation: A — fix failures before proceeding
|
||||
══════════════════════════════════════
|
||||
@@ -115,8 +114,7 @@ Categorize each as: **missing dependency**, **broken import**, **logic/assertion
|
||||
|
||||
- If user picks A → investigate root causes, attempt fixes, then re-run (loop back to step 2)
|
||||
- If user picks B → confirm which tests to remove, delete them, then re-run (loop back to step 2)
|
||||
- If user picks C → require explicit user confirmation; log as acknowledged tech debt in the report, then return success with warning to the autopilot
|
||||
- If user picks D → return failure to the autopilot
|
||||
- If user picks C → return failure to the autopilot
|
||||
|
||||
## Trigger Conditions
|
||||
|
||||
|
||||
@@ -379,6 +379,8 @@ Docker is the **preferred** test execution environment (reproducibility, isolati
|
||||
|
||||
### Phase 4: Test Runner Script Generation
|
||||
|
||||
**Skip condition**: If this skill was invoked from the `/plan` skill (planning context, no code exists yet), skip Phase 4 entirely. Script creation should instead be planned as a task during decompose — the decomposer creates a task for creating these scripts. Phase 4 only runs when invoked from the existing-code flow (where source code already exists) or standalone.
|
||||
|
||||
**Role**: DevOps engineer
|
||||
**Goal**: Generate executable shell scripts that run the specified tests, so the autopilot and CI can invoke them consistently.
|
||||
**Constraints**: Scripts must be idempotent, portable across dev/CI, and exit with non-zero on failure. Respect the Docker Suitability Assessment decision above.
|
||||
|
||||
Reference in New Issue
Block a user