diff --git a/.cursor/README.md b/.cursor/README.md index 6d85d07..bf9601b 100644 --- a/.cursor/README.md +++ b/.cursor/README.md @@ -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//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//`. +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//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/ -│ └── / -│ ├── 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. | diff --git a/.cursor/agents/implementer.md b/.cursor/agents/implementer.md index b16c7d1..ef29c36 100644 --- a/.cursor/agents/implementer.md +++ b/.cursor/agents/implementer.md @@ -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//[##]_[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 diff --git a/.cursor/commands/implement-code-review.md b/.cursor/commands/implement-code-review.md deleted file mode 100644 index ef99112..0000000 --- a/.cursor/commands/implement-code-review.md +++ /dev/null @@ -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 diff --git a/.cursor/commands/implement-initial.md b/.cursor/commands/implement-initial.md deleted file mode 100644 index 9407e3c..0000000 --- a/.cursor/commands/implement-initial.md +++ /dev/null @@ -1,53 +0,0 @@ -# Implement Initial Structure - -## Input -- Structure plan: `_docs/02_tasks//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 diff --git a/.cursor/commands/implement-wave.md b/.cursor/commands/implement-wave.md deleted file mode 100644 index 11c517a..0000000 --- a/.cursor/commands/implement-wave.md +++ /dev/null @@ -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//SUMMARY.md` exists -- `_docs/02_tasks//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//` - - 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 diff --git a/.cursor/skills/code-review/SKILL.md b/.cursor/skills/code-review/SKILL.md new file mode 100644 index 0000000..bca12ae --- /dev/null +++ b/.cursor/skills/code-review/SKILL.md @@ -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) diff --git a/.cursor/skills/decompose/SKILL.md b/.cursor/skills/decompose/SKILL.md index 56b88c4..d54063d 100644 --- a/.cursor/skills/decompose/SKILL.md +++ b/.cursor/skills/decompose/SKILL.md @@ -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│ └────────────────────────────────────────────────────────────────┘ ``` diff --git a/.cursor/skills/decompose/templates/dependencies-table.md b/.cursor/skills/decompose/templates/dependencies-table.md new file mode 100644 index 0000000..65612ba --- /dev/null +++ b/.cursor/skills/decompose/templates/dependencies-table.md @@ -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 diff --git a/.cursor/skills/decompose/templates/initial-structure.md b/.cursor/skills/decompose/templates/initial-structure-task.md similarity index 70% rename from .cursor/skills/decompose/templates/initial-structure.md rename to .cursor/skills/decompose/templates/initial-structure-task.md index 92f124b..9642f65 100644 --- a/.cursor/skills/decompose/templates/initial-structure.md +++ b/.cursor/skills/decompose/templates/initial-structure-task.md @@ -1,15 +1,20 @@ -# Initial Structure Plan Template +# Initial Structure Task Template -Use this template for the bootstrap structure plan. Save as `TASKS_DIR//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// +**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. diff --git a/.cursor/skills/decompose/templates/summary.md b/.cursor/skills/decompose/templates/summary.md deleted file mode 100644 index 9241e74..0000000 --- a/.cursor/skills/decompose/templates/summary.md +++ /dev/null @@ -1,59 +0,0 @@ -# Decomposition Summary Template - -Use this template after all steps complete. Save as `TASKS_DIR//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 -``` diff --git a/.cursor/skills/decompose/templates/feature-spec.md b/.cursor/skills/decompose/templates/task.md similarity index 78% rename from .cursor/skills/decompose/templates/feature-spec.md rename to .cursor/skills/decompose/templates/task.md index bc0ef6e..d8547a9 100644 --- a/.cursor/skills/decompose/templates/feature-spec.md +++ b/.cursor/skills/decompose/templates/task.md @@ -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//[##]_[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) diff --git a/.cursor/skills/implement/SKILL.md b/.cursor/skills/implement/SKILL.md new file mode 100644 index 0000000..8540519 --- /dev/null +++ b/.cursor/skills/implement/SKILL.md @@ -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 diff --git a/.cursor/skills/implement/references/batching-algorithm.md b/.cursor/skills/implement/references/batching-algorithm.md new file mode 100644 index 0000000..74a1c29 --- /dev/null +++ b/.cursor/skills/implement/references/batching-algorithm.md @@ -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. diff --git a/.cursor/skills/implement/templates/batch-report.md b/.cursor/skills/implement/templates/batch-report.md new file mode 100644 index 0000000..33e2616 --- /dev/null +++ b/.cursor/skills/implement/templates/batch-report.md @@ -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" +``` diff --git a/.cursor/skills/plan/SKILL.md b/.cursor/skills/plan/SKILL.md index 5b2a5ee..8b11465 100644 --- a/.cursor/skills/plan/SKILL.md +++ b/.cursor/skills/plan/SKILL.md @@ -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