mirror of
https://github.com/azaion/gps-denied-onboard.git
synced 2026-04-22 07:16:38 +00:00
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.
This commit is contained in:
Oleksandr Bezdieniezhnykh
+43
-44
@@ -14,71 +14,70 @@
|
||||
Run multiple times: Mode A → draft, Mode B → assess & revise
|
||||
Finalize as solution.md
|
||||
|
||||
3. /plan — architecture, components, risks, tests → _docs/02_plans/
|
||||
3. /plan — architecture, components, risks, tests, Jira epics → _docs/02_plans/
|
||||
|
||||
4. /decompose — feature specs, implementation order → _docs/02_tasks/
|
||||
4. /decompose — flat numbered task specs + _dependencies_table.md → _docs/02_tasks/
|
||||
|
||||
5. /implement-initial — scaffold project from initial_structure.md (once)
|
||||
5. /implement — auto-orchestrates all tasks: batches by dependencies, launches parallel implementers, runs code review, loops until done
|
||||
|
||||
6. /implement-wave — implement next wave of features (repeat per wave)
|
||||
6. /implement-black-box-tests — E2E tests via Docker consumer app (after all tasks)
|
||||
|
||||
7. /implement-code-review — review implemented code (after each wave or at the end)
|
||||
|
||||
8. /implement-black-box-tests — E2E tests via Docker consumer app (after all waves)
|
||||
|
||||
9. commit & push
|
||||
7. commit & push
|
||||
```
|
||||
|
||||
### SHIP (deploy and operate)
|
||||
|
||||
```
|
||||
10. /implement-cicd — validate/enhance CI/CD pipeline
|
||||
11. /deploy — deployment strategy per environment
|
||||
12. /observability — monitoring, logging, alerting plan
|
||||
8. /implement-cicd — validate/enhance CI/CD pipeline
|
||||
9. /deploy — deployment strategy per environment
|
||||
10. /observability — monitoring, logging, alerting plan
|
||||
```
|
||||
|
||||
### EVOLVE (maintenance and improvement)
|
||||
|
||||
```
|
||||
13. /refactor — structured refactoring (skill, 6-phase workflow)
|
||||
11. /refactor — structured refactoring (skill, 6-phase workflow)
|
||||
```
|
||||
|
||||
## Implementation Flow
|
||||
|
||||
### `/implement-initial`
|
||||
### `/implement`
|
||||
|
||||
Reads `_docs/02_tasks/<topic>/initial_structure.md` and scaffolds the project skeleton: folder structure, shared models, interfaces, stubs, .gitignore, .env.example, CI/CD config, DB migrations setup, test structure.
|
||||
Reads flat task files and `_dependencies_table.md` from `_docs/02_tasks/`.
|
||||
|
||||
Run once after decompose.
|
||||
1. Parses dependency graph, detects which tasks are already completed
|
||||
2. Computes next batch of tasks (max 4 parallel, respecting dependencies)
|
||||
3. Assigns file ownership per agent to prevent conflicts
|
||||
4. Launches `implementer` subagents in parallel immediately
|
||||
5. Runs `/code-review` skill on the batch's changes
|
||||
6. If review FAIL — blocks for user confirmation; otherwise continues
|
||||
7. Runs tests, commits and pushes to remote
|
||||
8. Loops until all tasks are done
|
||||
|
||||
### `/implement-wave`
|
||||
### `/code-review`
|
||||
|
||||
Reads `SUMMARY.md` and `cross_dependencies.md` from `_docs/02_tasks/<topic>/`.
|
||||
Multi-phase code review invoked after each implementation batch:
|
||||
|
||||
1. Detects which features are already implemented
|
||||
2. Identifies the next wave (phase) of independent features
|
||||
3. Presents the wave for confirmation (blocks until user confirms)
|
||||
4. Launches parallel `implementer` subagents (max 4 concurrent; same-component features run sequentially)
|
||||
5. Runs tests, reports results
|
||||
6. Suggests commit
|
||||
1. Context loading — reads task specs to understand intent
|
||||
2. Spec compliance — verifies each acceptance criterion is satisfied
|
||||
3. Code quality — SOLID, DRY, KISS, error handling, naming, complexity
|
||||
4. Security quick-scan — injection, secrets, input validation
|
||||
5. Performance scan — O(n^2), N+1, unbounded fetches
|
||||
6. Cross-task consistency — interface compatibility across batch
|
||||
|
||||
Repeat `/implement-wave` until all phases are done.
|
||||
|
||||
### `/implement-code-review`
|
||||
|
||||
Reviews implemented code against specs. Reports issues by type (Bug/Security/Performance/Style/Debt) with priorities and suggested fixes.
|
||||
Produces structured findings with severity (Critical/High/Medium/Low) and verdict (PASS/FAIL/PASS_WITH_WARNINGS).
|
||||
|
||||
### `/implement-black-box-tests`
|
||||
|
||||
Reads `_docs/02_plans/<topic>/e2e_test_infrastructure.md` (produced by plan skill). Builds a separate Docker-based consumer app that exercises the system as a black box — no internal imports, no direct DB access. Runs E2E scenarios, produces a CSV test report.
|
||||
|
||||
Run after all waves are done.
|
||||
Run after all tasks are done.
|
||||
|
||||
### `/implement-cicd`
|
||||
|
||||
Reviews existing CI/CD pipeline configuration, validates all stages work, optimizes performance (parallelization, caching), ensures quality gates are enforced (coverage, linting, security scanning).
|
||||
|
||||
Run after `/implement-initial` or after all waves.
|
||||
Run after `/implement` or after all tasks.
|
||||
|
||||
### `/deploy`
|
||||
|
||||
@@ -94,7 +93,7 @@ Run before first production release.
|
||||
|
||||
### Commit
|
||||
|
||||
After each wave or review — standard `git add && git commit`. The wave command suggests a commit message.
|
||||
After each confirmed batch, the `/implement` skill automatically commits and pushes to the remote branch.
|
||||
|
||||
## Available Skills
|
||||
|
||||
@@ -102,7 +101,9 @@ After each wave or review — standard `git add && git commit`. The wave command
|
||||
|-------|----------|---------|
|
||||
| **research** | "research", "investigate", "assess solution" | 8-step research → solution drafts |
|
||||
| **plan** | "plan", "decompose solution" | Architecture, components, risks, tests, epics |
|
||||
| **decompose** | "decompose", "task decomposition" | Feature specs + implementation order |
|
||||
| **decompose** | "decompose", "task decomposition" | Flat numbered task specs + dependency table |
|
||||
| **implement** | "implement", "start implementation" | Orchestrate task batches with parallel agents |
|
||||
| **code-review** | "code review", "review code" | 6-phase structured review with findings |
|
||||
| **refactor** | "refactor", "refactoring", "improve code" | 6-phase structured refactoring workflow |
|
||||
| **security** | "security audit", "OWASP" | OWASP-based security testing |
|
||||
|
||||
@@ -130,12 +131,11 @@ _docs/
|
||||
│ ├── components/
|
||||
│ └── FINAL_report.md
|
||||
├── 02_tasks/
|
||||
│ └── <topic>/
|
||||
│ ├── initial_structure.md
|
||||
│ ├── cross_dependencies.md
|
||||
│ ├── SUMMARY.md
|
||||
│ └── [##]_[component]/
|
||||
│ └── [##].[##]_feature_[name].md
|
||||
│ ├── 01_initial_structure.md
|
||||
│ ├── 02_[short_name].md
|
||||
│ ├── 03_[short_name].md
|
||||
│ ├── ...
|
||||
│ └── _dependencies_table.md
|
||||
└── 04_refactoring/
|
||||
├── baseline_metrics.md
|
||||
├── discovery/
|
||||
@@ -151,11 +151,10 @@ _docs/
|
||||
|
||||
| Tool | Type | Purpose |
|
||||
|------|------|---------|
|
||||
| `implementer` | Subagent | Implements a single feature from its spec. Launched by implement-wave. |
|
||||
| `/implement-initial` | Command | Scaffolds project skeleton from `initial_structure.md`. Run once. |
|
||||
| `/implement-wave` | Command | Detects next wave, launches parallel implementers. Repeatable. |
|
||||
| `/implement-code-review` | Command | Reviews code against specs. |
|
||||
| `/implement-black-box-tests` | Command | E2E tests via Docker consumer app. After all waves. |
|
||||
| `implementer` | Subagent | Implements a single task from its spec. Launched by /implement. |
|
||||
| `/implement` | Skill | Orchestrates all tasks: dependency batching, parallel agents, code review. |
|
||||
| `/code-review` | Skill | Multi-phase code review with structured findings. |
|
||||
| `/implement-black-box-tests` | Command | E2E tests via Docker consumer app. After all tasks. |
|
||||
| `/implement-cicd` | Command | Validate and enhance CI/CD pipeline. |
|
||||
| `/deploy` | Command | Plan deployment strategy per environment. |
|
||||
| `/observability` | Command | Plan logging, metrics, tracing, alerting. |
|
||||
|
||||
@@ -1,45 +1,101 @@
|
||||
---
|
||||
name: implementer
|
||||
description: |
|
||||
Implements a single feature from its spec file. Use when implementing features from _docs/02_tasks/.
|
||||
Reads the feature spec, analyzes the codebase, implements the feature with tests, and verifies acceptance criteria.
|
||||
Implements a single task from its spec file. Use when implementing tasks from _docs/02_tasks/.
|
||||
Reads the task spec, analyzes the codebase, implements the feature with tests, and verifies acceptance criteria.
|
||||
Launched by the /implement skill as a subagent.
|
||||
---
|
||||
|
||||
You are a professional software developer implementing a single feature.
|
||||
You are a professional software developer implementing a single task.
|
||||
|
||||
## Input
|
||||
|
||||
You receive a path to a feature spec file (e.g., `_docs/02_tasks/<topic>/[##]_[name]/[##].[##]_feature_[name].md`).
|
||||
You receive from the `/implement` orchestrator:
|
||||
- Path to a task spec file (e.g., `_docs/02_tasks/[JIRA-ID]_[short_name].md`)
|
||||
- Files OWNED (exclusive write access — only you may modify these)
|
||||
- Files READ-ONLY (shared interfaces, types — read but do not modify)
|
||||
- Files FORBIDDEN (other agents' owned files — do not touch)
|
||||
|
||||
## Context
|
||||
## Context (progressive loading)
|
||||
|
||||
Read these files for project context:
|
||||
- `_docs/00_problem/problem.md`
|
||||
- `_docs/00_problem/restrictions.md`
|
||||
- `_docs/00_problem/acceptance_criteria.md`
|
||||
- `_docs/01_solution/solution.md`
|
||||
Load context in this order, stopping when you have enough:
|
||||
|
||||
1. Read the task spec thoroughly — acceptance criteria, scope, constraints, dependencies
|
||||
2. Read `_docs/02_tasks/_dependencies_table.md` to understand where this task fits
|
||||
3. Read project-level context:
|
||||
- `_docs/00_problem/problem.md`
|
||||
- `_docs/00_problem/restrictions.md`
|
||||
- `_docs/01_solution/solution.md`
|
||||
4. Analyze the specific codebase areas related to your OWNED files and task dependencies
|
||||
|
||||
## Boundaries
|
||||
|
||||
**Always:**
|
||||
- Run tests before reporting done
|
||||
- Follow existing code conventions and patterns
|
||||
- Implement error handling per the project's strategy
|
||||
- Stay within the task spec's Scope/Included section
|
||||
|
||||
**Ask first:**
|
||||
- Adding new dependencies or libraries
|
||||
- Creating files outside your OWNED directories
|
||||
- Changing shared interfaces that other tasks depend on
|
||||
|
||||
**Never:**
|
||||
- Modify files in the FORBIDDEN list
|
||||
- Skip writing tests
|
||||
- Change database schema unless the task spec explicitly requires it
|
||||
- Commit secrets, API keys, or passwords
|
||||
- Modify CI/CD configuration unless the task spec explicitly requires it
|
||||
|
||||
## Process
|
||||
|
||||
1. Read the feature spec thoroughly — understand acceptance criteria, scope, constraints
|
||||
1. Read the task spec thoroughly — understand every acceptance criterion
|
||||
2. Analyze the existing codebase: conventions, patterns, related code, shared interfaces
|
||||
3. Research best implementation approaches for the tech stack if needed
|
||||
4. If the feature has a dependency on an unimplemented component, create a temporary mock
|
||||
4. If the task has a dependency on an unimplemented component, create a minimal interface mock
|
||||
5. Implement the feature following existing code conventions
|
||||
6. Implement error handling per the project's defined strategy
|
||||
7. Implement unit tests (use //Arrange //Act //Assert comments)
|
||||
8. Implement integration tests — analyze existing tests, add to them or create new
|
||||
9. Run all tests, fix any failures
|
||||
10. Verify the implementation satisfies every acceptance criterion from the spec
|
||||
10. Verify every acceptance criterion is satisfied — trace each AC with evidence
|
||||
|
||||
## After completion
|
||||
## Stop Conditions
|
||||
|
||||
Report:
|
||||
- What was implemented
|
||||
- Which acceptance criteria are satisfied
|
||||
- Test results (passed/failed)
|
||||
- Any mocks created for unimplemented dependencies
|
||||
- Any concerns or deviations from the spec
|
||||
- If the same fix fails 3+ times with different approaches, stop and report as blocker
|
||||
- If blocked on an unimplemented dependency, create a minimal interface mock and document it
|
||||
- If the task scope is unclear, stop and ask rather than assume
|
||||
|
||||
## Completion Report
|
||||
|
||||
Report using this exact structure:
|
||||
|
||||
```
|
||||
## Implementer Report: [task_name]
|
||||
|
||||
**Status**: Done | Blocked | Partial
|
||||
**Task**: [JIRA-ID]_[short_name]
|
||||
|
||||
### Acceptance Criteria
|
||||
| AC | Satisfied | Evidence |
|
||||
|----|-----------|----------|
|
||||
| AC-1 | Yes/No | [test name or description] |
|
||||
| AC-2 | Yes/No | [test name or description] |
|
||||
|
||||
### Files Modified
|
||||
- [path] (new/modified)
|
||||
|
||||
### Test Results
|
||||
- Unit: [X/Y] passed
|
||||
- Integration: [X/Y] passed
|
||||
|
||||
### Mocks Created
|
||||
- [path and reason, or "None"]
|
||||
|
||||
### Blockers
|
||||
- [description, or "None"]
|
||||
```
|
||||
|
||||
## Principles
|
||||
|
||||
|
||||
@@ -1,38 +0,0 @@
|
||||
# Code Review
|
||||
|
||||
## Initial data:
|
||||
- Problem description: `@_docs/00_problem/problem_description.md`.
|
||||
- Acceptance criteria: `@_docs/00_problem/acceptance_criteria.md`.
|
||||
- Security approach: `@_docs/00_problem/security_approach.md`.
|
||||
- Full Solution Description: `@_docs/01_solution/solution.md`
|
||||
- Components: `@_docs/02_components`
|
||||
|
||||
## Role
|
||||
You are a senior software engineer performing code review
|
||||
|
||||
## Task
|
||||
- Review implemented code against component specifications
|
||||
- Check code quality: readability, maintainability, SOLID principles
|
||||
- Check error handling consistency
|
||||
- Check logging implementation
|
||||
- Check security requirements are met
|
||||
- Check test coverage is adequate
|
||||
- Identify code smells and technical debt
|
||||
|
||||
## Output
|
||||
### Issues Found
|
||||
For each issue:
|
||||
- File/Location
|
||||
- Issue type (Bug/Security/Performance/Style/Debt)
|
||||
- Description
|
||||
- Suggested fix
|
||||
- Priority (High/Medium/Low)
|
||||
|
||||
### Summary
|
||||
- Total issues by type
|
||||
- Blocking issues that must be fixed
|
||||
- Recommended improvements
|
||||
|
||||
## Notes
|
||||
- Can also use Cursor's built-in review feature
|
||||
- Focus on critical issues first
|
||||
@@ -1,53 +0,0 @@
|
||||
# Implement Initial Structure
|
||||
|
||||
## Input
|
||||
- Structure plan: `_docs/02_tasks/<topic>/initial_structure.md` (produced by decompose skill)
|
||||
|
||||
## Context
|
||||
- Problem description: `@_docs/00_problem/problem.md`
|
||||
- Restrictions: `@_docs/00_problem/restrictions.md`
|
||||
- Solution: `@_docs/01_solution/solution.md`
|
||||
|
||||
## Role
|
||||
You are a professional software architect
|
||||
|
||||
## Task
|
||||
- Read carefully the structure plan in `initial_structure.md`
|
||||
- Execute the plan — create the project skeleton:
|
||||
- DTOs and shared models
|
||||
- Component interfaces
|
||||
- Empty implementations (stubs)
|
||||
- Helpers — empty implementations or interfaces
|
||||
- Add .gitignore appropriate for the project's language/framework
|
||||
- Add .env.example with required environment variables
|
||||
- Configure CI/CD pipeline per the structure plan stages
|
||||
- Apply environment strategy (dev, staging, production) per the structure plan
|
||||
- Add database migration setup if applicable
|
||||
- Add README.md, describe the project based on the solution
|
||||
- Create test folder structure per the structure plan
|
||||
- Configure branch protection rules recommendations
|
||||
|
||||
## Example
|
||||
The structure should roughly look like this (varies by tech stack):
|
||||
- .gitignore
|
||||
- .env.example
|
||||
- .github/workflows/ (or .gitlab-ci.yml or azure-pipelines.yml)
|
||||
- api/
|
||||
- components/
|
||||
- component1_folder/
|
||||
- component2_folder/
|
||||
- db/
|
||||
- migrations/
|
||||
- helpers/
|
||||
- models/
|
||||
- tests/
|
||||
- unit/
|
||||
- integration/
|
||||
- test_data/
|
||||
|
||||
Semantically coherent components may have their own project or subfolder. Common interfaces can be in a shared layer or per-component — follow language conventions.
|
||||
|
||||
## Notes
|
||||
- Follow SOLID, KISS, DRY
|
||||
- Follow conventions of the project's programming language
|
||||
- Ask as many questions as needed
|
||||
@@ -1,62 +0,0 @@
|
||||
# Implement Next Wave
|
||||
|
||||
Identify the next batch of independent features and implement them in parallel using the implementer subagent.
|
||||
|
||||
## Prerequisites
|
||||
- Project scaffolded (`/implement-initial` completed)
|
||||
- `_docs/02_tasks/<topic>/SUMMARY.md` exists
|
||||
- `_docs/02_tasks/<topic>/cross_dependencies.md` exists
|
||||
|
||||
## Wave Sizing
|
||||
- One wave = one phase from SUMMARY.md (features whose dependencies are all satisfied)
|
||||
- Max 4 subagents run concurrently; features in the same component run sequentially
|
||||
- If a phase has more than 8 features or more than 20 complexity points, suggest splitting into smaller waves and let the user cherry-pick which features to include
|
||||
|
||||
## Task
|
||||
|
||||
1. **Read the implementation plan**
|
||||
- Read `SUMMARY.md` for the phased implementation order
|
||||
- Read `cross_dependencies.md` for the dependency graph
|
||||
|
||||
2. **Detect current progress**
|
||||
- Analyze the codebase to determine which features are already implemented
|
||||
- Match implemented code against feature specs in `_docs/02_tasks/<topic>/`
|
||||
- Identify the next incomplete wave/phase from the implementation order
|
||||
|
||||
3. **Present the wave**
|
||||
- List all features in this wave with their complexity points
|
||||
- Show which component each feature belongs to
|
||||
- Confirm total features and estimated complexity
|
||||
- If the phase exceeds 8 features or 20 complexity points, recommend splitting and let user select a subset
|
||||
- **BLOCKING**: Do NOT proceed until user confirms
|
||||
|
||||
4. **Launch parallel implementation**
|
||||
- For each feature in the wave, launch an `implementer` subagent in background
|
||||
- Each subagent receives the path to its feature spec file
|
||||
- Features within different components can run in parallel
|
||||
- Features within the same component should run sequentially to avoid file conflicts
|
||||
|
||||
5. **Monitor and report**
|
||||
- Wait for all subagents to complete
|
||||
- Collect results from each: what was implemented, test results, any issues
|
||||
- Run the full test suite
|
||||
- Report summary:
|
||||
- Features completed successfully
|
||||
- Features that failed or need manual attention
|
||||
- Test results (passed/failed/skipped)
|
||||
- Any mocks created for future-wave dependencies
|
||||
|
||||
6. **Post-wave actions**
|
||||
- Suggest: `git add . && git commit` with a wave-level commit message
|
||||
- If all features passed: "Ready for next wave. Run `/implement-wave` again."
|
||||
- If some failed: "Fix the failing features before proceeding to the next wave."
|
||||
|
||||
## Safety Rules
|
||||
- Never launch features whose dependencies are not yet implemented
|
||||
- Features within the same component run sequentially, not in parallel
|
||||
- If a subagent fails, do NOT retry automatically — report and let user decide
|
||||
- Always run tests after the wave completes, before suggesting commit
|
||||
|
||||
## Notes
|
||||
- Ask questions if the implementation order is ambiguous
|
||||
- If SUMMARY.md or cross_dependencies.md is missing, stop and inform the user to run the decompose skill first
|
||||
@@ -0,0 +1,152 @@
|
||||
---
|
||||
name: code-review
|
||||
description: |
|
||||
Multi-phase code review against task specs with structured findings output.
|
||||
6-phase workflow: context loading, spec compliance, code quality, security quick-scan, performance scan, cross-task consistency.
|
||||
Produces a structured report with severity-ranked findings and a PASS/FAIL/PASS_WITH_WARNINGS verdict.
|
||||
Invoked by /implement skill after each batch, or manually.
|
||||
Trigger phrases:
|
||||
- "code review", "review code", "review implementation"
|
||||
- "check code quality", "review against specs"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Code Review
|
||||
|
||||
Multi-phase code review that verifies implementation against task specs, checks code quality, and produces structured findings.
|
||||
|
||||
## Core Principles
|
||||
|
||||
- **Understand intent first**: read the task specs before reviewing code — know what it should do before judging how
|
||||
- **Structured output**: every finding has severity, category, location, description, and suggestion
|
||||
- **Deduplicate**: same issue at the same location is reported once using `{file}:{line}:{title}` as key
|
||||
- **Severity-ranked**: findings sorted Critical > High > Medium > Low
|
||||
- **Verdict-driven**: clear PASS/FAIL/PASS_WITH_WARNINGS drives automation decisions
|
||||
|
||||
## Input
|
||||
|
||||
- List of task spec files that were just implemented (paths to `[JIRA-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`
|
||||
|
||||
## Phase 1: Context Loading
|
||||
|
||||
Before reviewing code, build understanding of intent:
|
||||
|
||||
1. Read each task spec — acceptance criteria, scope, constraints, dependencies
|
||||
2. Read project restrictions and solution overview
|
||||
3. Map which changed files correspond to which task specs
|
||||
4. Understand what the code is supposed to do before judging how it does it
|
||||
|
||||
## Phase 2: Spec Compliance Review
|
||||
|
||||
For each task, verify implementation satisfies every acceptance criterion:
|
||||
|
||||
- Walk through each AC (Given/When/Then) and trace it in the code
|
||||
- Check that unit tests cover each AC
|
||||
- Check that integration tests exist where specified in the task spec
|
||||
- Flag any AC that is not demonstrably satisfied as a **Spec-Gap** finding (severity: High)
|
||||
- Flag any scope creep (implementation beyond what the spec asked for) as a **Scope** finding (severity: Low)
|
||||
|
||||
## Phase 3: Code Quality Review
|
||||
|
||||
Check implemented code against quality standards:
|
||||
|
||||
- **SOLID principles** — single responsibility, open/closed, Liskov, interface segregation, dependency inversion
|
||||
- **Error handling** — consistent strategy, no bare catch/except, meaningful error messages
|
||||
- **Naming** — clear intent, follows project conventions
|
||||
- **Complexity** — functions longer than 50 lines or cyclomatic complexity > 10
|
||||
- **DRY** — duplicated logic across files
|
||||
- **Test quality** — tests assert meaningful behavior, not just "no error thrown"
|
||||
- **Dead code** — unused imports, unreachable branches
|
||||
|
||||
## Phase 4: Security Quick-Scan
|
||||
|
||||
Lightweight security checks (defer deep analysis to the `/security` skill):
|
||||
|
||||
- SQL injection via string interpolation
|
||||
- Command injection (subprocess with shell=True, exec, eval)
|
||||
- Hardcoded secrets, API keys, passwords
|
||||
- Missing input validation on external inputs
|
||||
- Sensitive data in logs or error messages
|
||||
- Insecure deserialization
|
||||
|
||||
## Phase 5: Performance Scan
|
||||
|
||||
Check for common performance anti-patterns:
|
||||
|
||||
- O(n^2) or worse algorithms where O(n) is possible
|
||||
- N+1 query patterns
|
||||
- Unbounded data fetching (missing pagination/limits)
|
||||
- Blocking I/O in async contexts
|
||||
- Unnecessary memory copies or allocations in hot paths
|
||||
|
||||
## Phase 6: Cross-Task Consistency
|
||||
|
||||
When multiple tasks were implemented in the same batch:
|
||||
|
||||
- Interfaces between tasks are compatible (method signatures, DTOs match)
|
||||
- No conflicting patterns (e.g., one task uses repository pattern, another does raw SQL)
|
||||
- Shared code is not duplicated across task implementations
|
||||
- Dependencies declared in task specs are properly wired
|
||||
|
||||
## Output Format
|
||||
|
||||
Produce a structured report with findings deduplicated and sorted by severity:
|
||||
|
||||
```markdown
|
||||
# Code Review Report
|
||||
|
||||
**Batch**: [task list]
|
||||
**Date**: [YYYY-MM-DD]
|
||||
**Verdict**: PASS | PASS_WITH_WARNINGS | FAIL
|
||||
|
||||
## Findings
|
||||
|
||||
| # | Severity | Category | File:Line | Title |
|
||||
|---|----------|----------|-----------|-------|
|
||||
| 1 | Critical | Security | src/api/auth.py:42 | SQL injection via f-string |
|
||||
| 2 | High | Spec-Gap | src/service/orders.py | AC-3 not satisfied |
|
||||
|
||||
### Finding Details
|
||||
|
||||
**F1: SQL injection via f-string** (Critical / Security)
|
||||
- Location: `src/api/auth.py:42`
|
||||
- Description: User input interpolated directly into SQL query
|
||||
- Suggestion: Use parameterized query via bind parameters
|
||||
- Task: 04_auth_service
|
||||
|
||||
**F2: AC-3 not satisfied** (High / Spec-Gap)
|
||||
- Location: `src/service/orders.py`
|
||||
- Description: AC-3 requires order total recalculation on item removal, but no such logic exists
|
||||
- Suggestion: Add recalculation in remove_item() method
|
||||
- Task: 07_order_processing
|
||||
```
|
||||
|
||||
## Severity Definitions
|
||||
|
||||
| Severity | Meaning | Blocks? |
|
||||
|----------|---------|---------|
|
||||
| Critical | Security vulnerability, data loss, crash | Yes — verdict FAIL |
|
||||
| High | Spec gap, logic bug, broken test | Yes — verdict FAIL |
|
||||
| Medium | Performance issue, maintainability concern, missing validation | No — verdict PASS_WITH_WARNINGS |
|
||||
| Low | Style, minor improvement, scope creep | No — verdict PASS_WITH_WARNINGS |
|
||||
|
||||
## Category Values
|
||||
|
||||
Bug, Spec-Gap, Security, Performance, Maintainability, Style, Scope
|
||||
|
||||
## Verdict Logic
|
||||
|
||||
- **FAIL**: any Critical or High finding exists
|
||||
- **PASS_WITH_WARNINGS**: only Medium or Low findings
|
||||
- **PASS**: no findings
|
||||
|
||||
## Integration with /implement
|
||||
|
||||
The `/implement` skill invokes this skill after each batch completes:
|
||||
|
||||
1. Collects changed files from all implementer agents in the batch
|
||||
2. Passes task spec paths + changed files to this skill
|
||||
3. If verdict is FAIL — presents findings to user (BLOCKING), user fixes or confirms
|
||||
4. If verdict is PASS or PASS_WITH_WARNINGS — proceeds automatically (findings shown as info)
|
||||
@@ -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│
|
||||
└────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
# Dependencies Table Template
|
||||
|
||||
Use this template after cross-task verification. Save as `TASKS_DIR/_dependencies_table.md`.
|
||||
|
||||
---
|
||||
|
||||
```markdown
|
||||
# Dependencies Table
|
||||
|
||||
**Date**: [YYYY-MM-DD]
|
||||
**Total Tasks**: [N]
|
||||
**Total Complexity Points**: [N]
|
||||
|
||||
| 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] |
|
||||
| ... | ... | ... | ... | ... |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Every task from TASKS_DIR must appear in this table
|
||||
- Dependencies column lists Jira 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
|
||||
+32
-10
@@ -1,15 +1,20 @@
|
||||
# Initial Structure Plan Template
|
||||
# Initial Structure Task Template
|
||||
|
||||
Use this template for the bootstrap structure plan. Save as `TASKS_DIR/<topic>/initial_structure.md`.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
```markdown
|
||||
# Initial Project Structure Plan
|
||||
# Initial Project Structure
|
||||
|
||||
**Date**: [YYYY-MM-DD]
|
||||
**Tech Stack**: [language, framework, database, etc.]
|
||||
**Source**: architecture.md, component specs from _docs/02_plans/<topic>/
|
||||
**Task**: [JIRA-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]
|
||||
**Epic**: [EPIC-ID]
|
||||
|
||||
## Project Folder Layout
|
||||
|
||||
@@ -35,7 +40,7 @@ project-root/
|
||||
|
||||
| Component | Interface | Methods | Exposed To |
|
||||
|-----------|-----------|---------|-----------|
|
||||
| [##]_[name] | [InterfaceName] | [method list] | [consumers] |
|
||||
| [name] | [InterfaceName] | [method list] | [consumers] |
|
||||
|
||||
## CI/CD Pipeline
|
||||
|
||||
@@ -97,16 +102,33 @@ tests/
|
||||
|
||||
| Order | Component | Reason |
|
||||
|-------|-----------|--------|
|
||||
| 1 | [##]_[name] | [why first — foundational, no dependencies] |
|
||||
| 2 | [##]_[name] | [depends on #1] |
|
||||
| 1 | [name] | [why first — foundational, no dependencies] |
|
||||
| 2 | [name] | [depends on #1] |
|
||||
| ... | ... | ... |
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
**AC-1: Project scaffolded**
|
||||
Given the structure plan above
|
||||
When the implementer executes this task
|
||||
Then all folders, stubs, and configuration files exist
|
||||
|
||||
**AC-2: Tests runnable**
|
||||
Given the scaffolded project
|
||||
When the test suite is executed
|
||||
Then all stub tests pass (even if they only assert true)
|
||||
|
||||
**AC-3: CI/CD configured**
|
||||
Given the scaffolded project
|
||||
When CI pipeline runs
|
||||
Then build, lint, and test stages complete successfully
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Guidance Notes
|
||||
|
||||
- This is a PLAN document, not code. The `3.05_implement_initial_structure` command executes it.
|
||||
- This is a PLAN document, not code. The `/implement` skill executes it.
|
||||
- Focus on structure and organization decisions, not implementation details.
|
||||
- Reference component specs for interface and DTO details — don't repeat everything.
|
||||
- The folder layout should follow conventions of the identified tech stack.
|
||||
@@ -1,59 +0,0 @@
|
||||
# Decomposition Summary Template
|
||||
|
||||
Use this template after all steps complete. Save as `TASKS_DIR/<topic>/SUMMARY.md`.
|
||||
|
||||
---
|
||||
|
||||
```markdown
|
||||
# Decomposition Summary
|
||||
|
||||
**Date**: [YYYY-MM-DD]
|
||||
**Topic**: [topic name]
|
||||
**Total Components**: [N]
|
||||
**Total Features**: [N]
|
||||
**Total Complexity Points**: [N]
|
||||
|
||||
## Component Breakdown
|
||||
|
||||
| # | Component | Features | Total Points | Jira Epic |
|
||||
|---|-----------|----------|-------------|-----------|
|
||||
| 01 | [name] | [count] | [sum] | [EPIC-ID] |
|
||||
| 02 | [name] | [count] | [sum] | [EPIC-ID] |
|
||||
| ... | ... | ... | ... | ... |
|
||||
|
||||
## Feature List
|
||||
|
||||
| Component | Feature | Complexity | Jira Task | Dependencies |
|
||||
|-----------|---------|-----------|-----------|-------------|
|
||||
| [##]_[name] | [##].[##]_feature_[name] | [points] | [TASK-ID] | [deps or "None"] |
|
||||
| ... | ... | ... | ... | ... |
|
||||
|
||||
## Implementation Order
|
||||
|
||||
Recommended sequence based on dependency analysis:
|
||||
|
||||
| Phase | Components / Features | Rationale |
|
||||
|-------|----------------------|-----------|
|
||||
| 1 | [list] | [foundational, no dependencies] |
|
||||
| 2 | [list] | [depends on phase 1] |
|
||||
| 3 | [list] | [depends on phase 1-2] |
|
||||
| ... | ... | ... |
|
||||
|
||||
### Parallelization Opportunities
|
||||
|
||||
[Features/components that can be implemented concurrently within each phase]
|
||||
|
||||
## Cross-Component Dependencies
|
||||
|
||||
| From (Feature) | To (Feature) | Dependency Type |
|
||||
|----------------|-------------|-----------------|
|
||||
| [comp.feature] | [comp.feature] | [data / API / event] |
|
||||
| ... | ... | ... |
|
||||
|
||||
## Artifacts Produced
|
||||
|
||||
- `initial_structure.md` — project skeleton plan
|
||||
- `cross_dependencies.md` — dependency matrix
|
||||
- `[##]_[name]/[##].[##]_feature_*.md` — feature specs per component
|
||||
- Jira tasks created under respective epics
|
||||
```
|
||||
+13
-8
@@ -1,17 +1,21 @@
|
||||
# Feature Specification Template
|
||||
# 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/<topic>/[##]_[component_name]/[##].[##]_feature_[feature_name].md`.
|
||||
Save as `TASKS_DIR/[##]_[short_name].md` initially, then rename to `TASKS_DIR/[JIRA-ID]_[short_name].md` after Jira ticket creation.
|
||||
|
||||
---
|
||||
|
||||
```markdown
|
||||
# [Feature Name]
|
||||
|
||||
**Status**: Draft | **Date**: [YYYY-MM-DD] | **Feature**: [Brief Feature Description]
|
||||
**Task**: [JIRA-ID]_[short_name]
|
||||
**Name**: [short human name]
|
||||
**Description**: [one-line description of what this task delivers]
|
||||
**Complexity**: [1|2|3|5] points
|
||||
**Dependencies**: [List dependent features or "None"]
|
||||
**Component**: [##]_[component_name]
|
||||
**Dependencies**: [AZ-43_shared_models, AZ-44_db_migrations] or "None"
|
||||
**Component**: [component name for context]
|
||||
**Jira**: [TASK-ID]
|
||||
**Epic**: [EPIC-ID]
|
||||
|
||||
## Problem
|
||||
|
||||
@@ -21,11 +25,12 @@ Clear, concise statement of the problem users are facing.
|
||||
|
||||
- Measurable or observable goal 1
|
||||
- Measurable or observable goal 2
|
||||
- ...
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- What's in scope for this feature
|
||||
- What's in scope for this task
|
||||
|
||||
### Excluded
|
||||
- Explicitly what's NOT in scope
|
||||
@@ -86,7 +91,7 @@ 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 features
|
||||
- 8 points: Too complex — split into smaller tasks
|
||||
|
||||
## Output Guidelines
|
||||
|
||||
@@ -97,7 +102,7 @@ Then [expected result]
|
||||
- Include realistic scope boundaries
|
||||
- Write from the user's perspective
|
||||
- Include complexity estimation
|
||||
- Note dependencies on other features
|
||||
- Reference dependencies by Jira ID (e.g., AZ-43_shared_models)
|
||||
|
||||
**DON'T:**
|
||||
- Include implementation details (file paths, classes, methods)
|
||||
@@ -0,0 +1,155 @@
|
||||
---
|
||||
name: implement
|
||||
description: |
|
||||
Orchestrate task implementation with dependency-aware batching, parallel subagents, and integrated code review.
|
||||
Reads flat task files and _dependencies_table.md from TASKS_DIR, computes execution batches via topological sort,
|
||||
launches up to 4 implementer subagents in parallel, runs code-review skill after each batch, and loops until done.
|
||||
Use after /decompose has produced task files.
|
||||
Trigger phrases:
|
||||
- "implement", "start implementation", "implement tasks"
|
||||
- "run implementers", "execute tasks"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Implementation Orchestrator
|
||||
|
||||
Orchestrate the implementation of all tasks produced by the `/decompose` skill. This skill is a **pure orchestrator** — it does NOT write implementation code itself. It reads task specs, computes execution order, delegates to `implementer` subagents, validates results via the `/code-review` skill, and escalates issues.
|
||||
|
||||
The `implementer` agent is the specialist that writes all the code — it receives a task spec, analyzes the codebase, implements the feature, writes tests, and verifies acceptance criteria.
|
||||
|
||||
## Core Principles
|
||||
|
||||
- **Orchestrate, don't implement**: this skill delegates all coding to `implementer` subagents
|
||||
- **Dependency-aware batching**: tasks run only when all their dependencies are satisfied
|
||||
- **Max 4 parallel agents**: never launch more than 4 implementer subagents simultaneously
|
||||
- **File isolation**: no two parallel agents may write to the same file
|
||||
- **Integrated review**: `/code-review` skill runs automatically after each batch
|
||||
- **Auto-start**: batches launch immediately — no user confirmation before a batch
|
||||
- **Gate on failure**: user confirmation is required only when code review returns FAIL
|
||||
- **Commit and push per batch**: after each batch is confirmed, commit and push to remote
|
||||
|
||||
## Context Resolution
|
||||
|
||||
- TASKS_DIR: `_docs/02_tasks/`
|
||||
- Task files: all `*.md` files in TASKS_DIR (excluding files starting with `_`)
|
||||
- Dependency table: `TASKS_DIR/_dependencies_table.md`
|
||||
|
||||
## Prerequisite Checks (BLOCKING)
|
||||
|
||||
1. TASKS_DIR exists and contains at least one task file — **STOP if missing**
|
||||
2. `_dependencies_table.md` exists — **STOP if missing**
|
||||
3. At least one task is not yet completed — **STOP if all done**
|
||||
|
||||
## Algorithm
|
||||
|
||||
### 1. Parse
|
||||
|
||||
- Read all task `*.md` files from TASKS_DIR (excluding files starting with `_`)
|
||||
- Read `_dependencies_table.md` — parse into a dependency graph (DAG)
|
||||
- Validate: no circular dependencies, all referenced dependencies exist
|
||||
|
||||
### 2. Detect Progress
|
||||
|
||||
- Scan the codebase to determine which tasks are already completed
|
||||
- Match implemented code against task acceptance criteria
|
||||
- Mark completed tasks as done in the DAG
|
||||
- Report progress to user: "X of Y tasks completed"
|
||||
|
||||
### 3. Compute Next Batch
|
||||
|
||||
- Topological sort remaining tasks
|
||||
- Select tasks whose dependencies are ALL satisfied (completed)
|
||||
- If a ready task depends on any task currently being worked on in this batch, it must wait for the next batch
|
||||
- Cap the batch at 4 parallel agents
|
||||
- If the batch would exceed 20 total complexity points, suggest splitting and let the user decide
|
||||
|
||||
### 4. Assign File Ownership
|
||||
|
||||
For each task in the batch:
|
||||
- Parse the task spec's Component field and Scope section
|
||||
- Map the component to directories/files in the project
|
||||
- Determine: files OWNED (exclusive write), files READ-ONLY (shared interfaces, types), files FORBIDDEN (other agents' owned files)
|
||||
- If two tasks in the same batch would modify the same file, schedule them sequentially instead of in parallel
|
||||
|
||||
### 5. Launch Implementer Subagents
|
||||
|
||||
For each task in the batch, launch an `implementer` subagent with:
|
||||
- Path to the task spec file
|
||||
- List of files OWNED (exclusive write access)
|
||||
- List of files READ-ONLY
|
||||
- List of files FORBIDDEN
|
||||
|
||||
Launch all subagents immediately — no user confirmation.
|
||||
|
||||
### 6. Monitor
|
||||
|
||||
- Wait for all subagents to complete
|
||||
- Collect structured status reports from each implementer
|
||||
- If any implementer reports "Blocked", log the blocker and continue with others
|
||||
|
||||
### 7. Code Review
|
||||
|
||||
- Run `/code-review` skill on the batch's changed files + corresponding task specs
|
||||
- The code-review skill produces a verdict: PASS, PASS_WITH_WARNINGS, or FAIL
|
||||
|
||||
### 8. Gate
|
||||
|
||||
- If verdict is **FAIL**: present findings to user (**BLOCKING**). User must confirm fixes or accept before proceeding.
|
||||
- If verdict is **PASS** or **PASS_WITH_WARNINGS**: show findings as info, continue automatically.
|
||||
|
||||
### 9. Test
|
||||
|
||||
- Run the full test suite
|
||||
- If failures: report to user with details
|
||||
|
||||
### 10. 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 batch-level message summarizing what was implemented
|
||||
- `git push` to the remote branch
|
||||
|
||||
### 11. Loop
|
||||
|
||||
- Go back to step 2 until all tasks are done
|
||||
- When all tasks are complete, report final summary
|
||||
|
||||
## Batch Report
|
||||
|
||||
After each batch, produce a structured report:
|
||||
|
||||
```markdown
|
||||
# Batch Report
|
||||
|
||||
**Batch**: [N]
|
||||
**Tasks**: [list]
|
||||
**Date**: [YYYY-MM-DD]
|
||||
|
||||
## Task Results
|
||||
|
||||
| Task | Status | Files Modified | Tests | Issues |
|
||||
|------|--------|---------------|-------|--------|
|
||||
| [JIRA-ID]_[name] | Done | [count] files | [pass/fail] | [count or None] |
|
||||
|
||||
## Code Review Verdict: [PASS/FAIL/PASS_WITH_WARNINGS]
|
||||
|
||||
## Next Batch: [task list] or "All tasks complete"
|
||||
```
|
||||
|
||||
## Stop Conditions and Escalation
|
||||
|
||||
| Situation | Action |
|
||||
|-----------|--------|
|
||||
| Implementer fails same approach 3+ times | Stop it, escalate to user |
|
||||
| Task blocked on external dependency (not in task list) | Report and skip |
|
||||
| File ownership conflict unresolvable | ASK user |
|
||||
| Test failures exceed 50% of suite after a batch | Stop and escalate |
|
||||
| All tasks complete | Report final summary, suggest final commit |
|
||||
| `_dependencies_table.md` missing | STOP — run `/decompose` first |
|
||||
|
||||
## Safety Rules
|
||||
|
||||
- Never launch tasks whose dependencies are not yet completed
|
||||
- Never allow two parallel agents to write to the same file
|
||||
- If a subagent fails, do NOT retry automatically — report and let user decide
|
||||
- Always run tests after each batch completes
|
||||
@@ -0,0 +1,31 @@
|
||||
# Batching Algorithm Reference
|
||||
|
||||
## Topological Sort with Batch Grouping
|
||||
|
||||
The `/implement` skill uses a topological sort to determine execution order,
|
||||
then groups tasks into batches for parallel execution.
|
||||
|
||||
## Algorithm
|
||||
|
||||
1. Build adjacency list from `_dependencies_table.md`
|
||||
2. Compute in-degree for each task node
|
||||
3. Initialize batch 0 with all nodes that have in-degree 0
|
||||
4. For each batch:
|
||||
a. Select up to 4 tasks from the ready set
|
||||
b. Check file ownership — if two tasks would write the same file, defer one to the next batch
|
||||
c. Launch selected tasks as parallel implementer subagents
|
||||
d. When all complete, remove them from the graph and decrement in-degrees of dependents
|
||||
e. Add newly zero-in-degree nodes to the next batch's ready set
|
||||
5. Repeat until the graph is empty
|
||||
|
||||
## File Ownership Conflict Resolution
|
||||
|
||||
When two tasks in the same batch map to overlapping files:
|
||||
- Prefer to run the lower-numbered task first (it's more foundational)
|
||||
- Defer the higher-numbered task to the next batch
|
||||
- If both have equal priority, ask the user
|
||||
|
||||
## Complexity Budget
|
||||
|
||||
Each batch should not exceed 20 total complexity points.
|
||||
If it does, split the batch and let the user choose which tasks to include.
|
||||
@@ -0,0 +1,36 @@
|
||||
# Batch Report Template
|
||||
|
||||
Use this template after each implementation batch completes.
|
||||
|
||||
---
|
||||
|
||||
```markdown
|
||||
# Batch Report
|
||||
|
||||
**Batch**: [N]
|
||||
**Tasks**: [list of task names]
|
||||
**Date**: [YYYY-MM-DD]
|
||||
|
||||
## Task Results
|
||||
|
||||
| Task | Status | Files Modified | Tests | Issues |
|
||||
|------|--------|---------------|-------|--------|
|
||||
| [JIRA-ID]_[name] | Done/Blocked/Partial | [count] files | [X/Y pass] | [count or None] |
|
||||
|
||||
## Code Review Verdict: [PASS / FAIL / PASS_WITH_WARNINGS]
|
||||
|
||||
[Link to code review report if FAIL or PASS_WITH_WARNINGS]
|
||||
|
||||
## Test Suite
|
||||
|
||||
- Total: [N] tests
|
||||
- Passed: [N]
|
||||
- Failed: [N]
|
||||
- Skipped: [N]
|
||||
|
||||
## Commit
|
||||
|
||||
[Suggested commit message]
|
||||
|
||||
## Next Batch: [task list] or "All tasks complete"
|
||||
```
|
||||
@@ -332,13 +332,15 @@ Fix any issues found before proceeding to risk identification.
|
||||
|
||||
**Constraints**: Be concise — fewer words with the same meaning is better
|
||||
|
||||
1. Generate Jira Epics from components using Jira MCP, structured per `templates/epic-spec.md`
|
||||
2. Order epics by dependency (which must be done first)
|
||||
3. Include effort estimation per epic (T-shirt size or story points range)
|
||||
4. Ensure each epic has clear acceptance criteria cross-referenced with component specs
|
||||
5. Generate updated draw.io diagram showing component-to-epic mapping
|
||||
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 Jira Epics for each component using Jira MCP, 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
|
||||
6. Generate updated draw.io diagram showing component-to-epic mapping
|
||||
|
||||
**Self-verification**:
|
||||
- [ ] "Bootstrap & Initial Structure" epic exists and is first in order
|
||||
- [ ] Every component maps to exactly one epic
|
||||
- [ ] Dependency order is respected (no epic depends on a later one)
|
||||
- [ ] Acceptance criteria are measurable
|
||||
@@ -384,6 +386,7 @@ Before writing the final report, verify ALL of the following:
|
||||
- [ ] Test data management is defined
|
||||
|
||||
### Epics
|
||||
- [ ] "Bootstrap & Initial Structure" epic exists
|
||||
- [ ] Every component maps to an epic
|
||||
- [ ] Dependency order is correct
|
||||
- [ ] Acceptance criteria are measurable
|
||||
|
||||
Reference in New Issue
Block a user