mirror of https://github.com/azaion/admin.git synced 2026-04-22 22:36:33 +00:00

Files

T

Oleksandr Bezdieniezhnykh d96971b050 Update .gitignore to include .env and .DS_Store files

Add .cursor autodevelopment system

2026-03-25 17:41:10 +02:00

21 KiB

Raw Blame History

name, description, category, tags, disable-model-invocation

name

description

Task Decomposition

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

Core Principles

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
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

Context Resolution

Determine the operating mode based on invocation before any other logic runs.

Default (no explicit input file provided):

DOCUMENT_DIR: _docs/02_document/
TASKS_DIR: _docs/02_tasks/
Reads from: _docs/00_problem/, _docs/01_solution/, DOCUMENT_DIR
Runs Step 1 (bootstrap) + Step 2 (all components) + Step 3 (blackbox tests) + Step 4 (cross-verification)

Single component mode (provided file is within _docs/02_document/ and inside a components/ subdirectory):

DOCUMENT_DIR: _docs/02_document/
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, appending to existing task numbering)

Tests-only mode (provided file/directory is within tests/, or DOCUMENT_DIR/tests/ exists and input explicitly requests test decomposition):

DOCUMENT_DIR: _docs/02_document/
TASKS_DIR: _docs/02_tasks/
TESTS_DIR: DOCUMENT_DIR/tests/
Reads from: _docs/00_problem/, _docs/01_solution/, TESTS_DIR
Runs Step 1t (test infrastructure bootstrap) + Step 3 (blackbox test decomposition) + Step 4 (cross-verification against test coverage)
Skips Step 1 (project bootstrap) and Step 2 (component decomposition) — the codebase already exists

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

Input Specification

Required Files

Default:

File	Purpose
`_docs/00_problem/problem.md`	Problem description and context
`_docs/00_problem/restrictions.md`	Constraints and limitations
`_docs/00_problem/acceptance_criteria.md`	Measurable acceptance criteria
`_docs/01_solution/solution.md`	Finalized solution
`DOCUMENT_DIR/architecture.md`	Architecture from plan skill
`DOCUMENT_DIR/system-flows.md`	System flows from plan skill
`DOCUMENT_DIR/components/[##]_[name]/description.md`	Component specs from plan skill
`DOCUMENT_DIR/tests/`	Blackbox test specs from plan skill

Single component mode:

File	Purpose
The provided component `description.md`	Component spec to decompose
Corresponding `tests.md` in the same directory (if available)	Test specs for context

Tests-only mode:

File	Purpose
`TESTS_DIR/environment.md`	Test environment specification (Docker services, networks, volumes)
`TESTS_DIR/test-data.md`	Test data management (seed data, mocks, isolation)
`TESTS_DIR/blackbox-tests.md`	Blackbox functional scenarios (positive + negative)
`TESTS_DIR/performance-tests.md`	Performance test scenarios
`TESTS_DIR/resilience-tests.md`	Resilience test scenarios
`TESTS_DIR/security-tests.md`	Security test scenarios
`TESTS_DIR/resource-limit-tests.md`	Resource limit test scenarios
`TESTS_DIR/traceability-matrix.md`	AC/restriction coverage mapping
`_docs/00_problem/problem.md`	Problem context
`_docs/00_problem/restrictions.md`	Constraints for test design
`_docs/00_problem/acceptance_criteria.md`	Acceptance criteria being verified

Prerequisite Checks (BLOCKING)

Default:

DOCUMENT_DIR contains architecture.md and components/ — STOP if missing
Create TASKS_DIR if it does not exist
If TASKS_DIR already contains task files, ask user: resume from last checkpoint or start fresh?

Single component mode:

The provided component file exists and is non-empty — STOP if missing

Tests-only mode:

TESTS_DIR/blackbox-tests.md exists and is non-empty — STOP if missing
TESTS_DIR/environment.md exists — STOP if missing
Create TASKS_DIR if it does not exist
If TASKS_DIR already contains task files, ask user: resume from last checkpoint or start fresh?

Artifact Management

Directory Structure

TASKS_DIR/
├── [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 + Jira ticket created + file renamed	`[JIRA-ID]_initial_structure.md`
Step 1t	Test infrastructure bootstrap complete + Jira ticket created + file renamed	`[JIRA-ID]_test_infrastructure.md`
Step 2	Each component task decomposed + Jira ticket created + file renamed	`[JIRA-ID]_[short_name].md`
Step 3	Each blackbox test task decomposed + Jira ticket created + file renamed	`[JIRA-ID]_[short_name].md`
Step 4	Cross-task verification complete	`_dependencies_table.md`

Resumability

If TASKS_DIR already contains task files:

List existing *_*.md files (excluding _dependencies_table.md) and count them
Resume numbering from the next number (for temporary numeric prefix before Jira rename)
Inform the user which tasks already exist and are being skipped

Progress Tracking

At the start of execution, create a TodoWrite with all applicable steps. Update status as each step/component completes.

Workflow

Step 1t: Test Infrastructure Bootstrap (tests-only mode only)

Role: Professional Quality Assurance Engineer Goal: Produce 01_test_infrastructure.md — the first task describing the test project scaffold Constraints: This is a plan document, not code. The /implement skill executes it.

Read TESTS_DIR/environment.md and TESTS_DIR/test-data.md
Read problem.md, restrictions.md, acceptance_criteria.md for domain context
Document the test infrastructure plan using templates/test-infrastructure-task.md

The test infrastructure bootstrap must include:

Test project folder layout (e2e/ directory structure)
Mock/stub service definitions for each external dependency
docker-compose.test.yml structure from environment.md
Test runner configuration (framework, plugins, fixtures)
Test data fixture setup from test-data.md seed data sets
Test reporting configuration (format, output path)
Data isolation strategy

Self-verification:

Every external dependency from environment.md has a mock service defined
Docker Compose structure covers all services from environment.md
Test data fixtures cover all seed data sets from test-data.md
Test runner configuration matches the consumer app tech stack from environment.md
Data isolation strategy is defined

Save action: Write 01_test_infrastructure.md (temporary numeric name)

Jira action: Create a Jira ticket for this task under the "Blackbox Tests" epic. Write the Jira ticket ID and Epic ID back into the task header.

Rename action: Rename the file from 01_test_infrastructure.md to [JIRA-ID]_test_infrastructure.md. Update the Task field inside the file to match the new filename.

BLOCKING: Present test infrastructure plan summary to user. Do NOT proceed until user confirms.

Step 1: Bootstrap Structure Plan (default mode only)

Role: Professional software architect 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.

Read architecture.md, all component specs, system-flows.md, data_model.md, and deployment/ from DOCUMENT_DIR
Read problem, solution, and restrictions from _docs/00_problem/ and _docs/01_solution/
Research best implementation patterns for the identified tech stack
Document the structure plan using templates/initial-structure-task.md

The bootstrap structure plan must include:

Project folder layout with all component directories
Shared models, interfaces, and DTOs
Dockerfile per component (multi-stage, non-root, health checks, pinned base images)
docker-compose.yml for local development (all components + database + dependencies)
docker-compose.test.yml for blackbox test environment (blackbox test runner)
.dockerignore
CI/CD pipeline file (.github/workflows/ci.yml or azure-pipelines.yml) with stages from deployment/ci_cd_pipeline.md
Database migration setup and initial seed data scripts
Observability configuration: structured logging setup, health check endpoints (/health/live, /health/ready), metrics endpoint (/metrics)
Environment variable documentation (.env.example)
Test structure with unit and blackbox test locations

Self-verification:

All components have corresponding folders in the layout
All inter-component interfaces have DTOs defined
Dockerfile defined for each component
docker-compose.yml covers all components and dependencies
docker-compose.test.yml enables blackbox testing
CI/CD pipeline file defined with lint, test, security, build, deploy stages
Database migration setup included
Health check endpoints specified for each service
Structured logging configuration included
.env.example with all required environment variables
Environment strategy covers dev, staging, production
Test structure includes unit and blackbox test locations

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: Task Decomposition (default and single component modes)

Role: Professional software architect 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):

Read the component's description.md and tests.md (if available)
Decompose into atomic tasks; create only 1 task if the component is simple or atomic
Split into multiple tasks only when it is necessary and would be easier to implement
Do not create tasks for other components — only tasks for the current component
Each task should be atomic, containing 0 APIs or a list of semantically connected APIs
Write each task spec using templates/task.md
Estimate complexity per task (1, 2, 3, 5 points); no task should exceed 5 points — split if it does
Note task dependencies (referencing Jira IDs of already-created dependency tasks, e.g., AZ-42_initial_structure)
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 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 [##]_[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: Blackbox Test Task Decomposition (default and tests-only modes)

Role: Professional Quality Assurance Engineer Goal: Decompose blackbox test specs into atomic, implementable task specs Constraints: Behavioral specs only — describe what, not how. No test code.

Numbering:

In default mode: continue sequential numbering from where Step 2 left off.
In tests-only mode: start from 02 (01 is the test infrastructure bootstrap from Step 1t).

Read all test specs from DOCUMENT_DIR/tests/ (blackbox-tests.md, performance-tests.md, resilience-tests.md, security-tests.md, resource-limit-tests.md)
Group related test scenarios into atomic tasks (e.g., one task per test category or per component under test)
Each task should reference the specific test scenarios it implements and the environment/test-data specs
Dependencies:
- In default mode: blackbox test tasks depend on the component implementation tasks they exercise
- In tests-only mode: blackbox test tasks depend on the test infrastructure bootstrap task (Step 1t)
Write each task spec using templates/task.md
Estimate complexity per task (1, 2, 3, 5 points); no task should exceed 5 points — split if it does
Note task dependencies (referencing Jira IDs of already-created dependency tasks)
Immediately after writing each task file: create a Jira ticket under the "Blackbox Tests" epic, write the Jira ticket ID and Epic ID back into the task header, then rename the file from [##]_[short_name].md to [JIRA-ID]_[short_name].md.

Self-verification:

Every scenario from tests/blackbox-tests.md is covered by a task
Every scenario from tests/performance-tests.md, tests/resilience-tests.md, tests/security-tests.md, and tests/resource-limit-tests.md is covered by a task
No task exceeds 5 complexity points
Dependencies correctly reference the dependency tasks (component tasks in default mode, test infrastructure in tests-only mode)
Every task has a Jira ticket linked to the "Blackbox Tests" epic

Save action: Write each [##]_[short_name].md (temporary numeric name), create Jira ticket inline, then rename to [JIRA-ID]_[short_name].md.

Step 4: Cross-Task Verification (default and tests-only modes)

Role: Professional software architect and analyst Goal: Verify task consistency and produce _dependencies_table.md Constraints: Review step — fix gaps found, do not add new tasks

Verify task dependencies across all tasks are consistent
Check no gaps:
- In default mode: every interface in architecture.md has tasks covering it
- In tests-only mode: every test scenario in traceability-matrix.md is covered by a task
Check no overlaps: tasks don't duplicate work
Check no circular dependencies in the task graph
Produce _dependencies_table.md using templates/dependencies-table.md

Self-verification:

Default mode:

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

Tests-only mode:

Every test scenario from traceability-matrix.md "Covered" entries has a corresponding task
No circular dependencies in the task graph
Test task dependencies reference the test infrastructure bootstrap
_dependencies_table.md contains every task with correct dependencies

Save action: Write _dependencies_table.md

BLOCKING: Present dependency summary to user. Do NOT proceed until user confirms.

Common Mistakes

Coding during decomposition: this workflow produces specs, never code
Over-splitting: don't create many tasks if the component is simple — 1 task is fine
Tasks exceeding 5 points: split them; no task should be too complex for a single implementer
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
Task complexity exceeds 5 points after splitting	ASK user
Missing component specs in DOCUMENT_DIR	ASK user
Cross-component dependency conflict	ASK user
Jira epic not found for a component	ASK user for Epic ID
Task naming	PROCEED, confirm at next BLOCKING gate

Methodology Quick Reference

┌────────────────────────────────────────────────────────────────┐
│          Task Decomposition (Multi-Mode)                        │
├────────────────────────────────────────────────────────────────┤
│ CONTEXT: Resolve mode (default / single component / tests-only)│
│                                                                │
│ DEFAULT MODE:                                                   │
│  1.  Bootstrap Structure  → [JIRA-ID]_initial_structure.md     │
│      [BLOCKING: user confirms structure]                       │
│  2.  Component Tasks      → [JIRA-ID]_[short_name].md each    │
│  3.  Blackbox Tests       → [JIRA-ID]_[short_name].md each    │
│  4.  Cross-Verification   → _dependencies_table.md            │
│      [BLOCKING: user confirms dependencies]                    │
│                                                                │
│ TESTS-ONLY MODE:                                                │
│  1t. Test Infrastructure  → [JIRA-ID]_test_infrastructure.md   │
│      [BLOCKING: user confirms test scaffold]                   │
│  3.  Blackbox Tests       → [JIRA-ID]_[short_name].md each    │
│  4.  Cross-Verification   → _dependencies_table.md            │
│      [BLOCKING: user confirms dependencies]                    │
│                                                                │
│ SINGLE COMPONENT MODE:                                          │
│  2.  Component Tasks      → [JIRA-ID]_[short_name].md each    │
├────────────────────────────────────────────────────────────────┤
│ Principles: Atomic tasks · Behavioral specs · Flat structure   │
│   Jira inline · Rename to Jira ID · Save now · Ask don't assume│
└────────────────────────────────────────────────────────────────┘

21 KiB Raw Blame History

Task Decomposition

Core Principles

Context Resolution

Input Specification

Required Files

Prerequisite Checks (BLOCKING)

Artifact Management

Directory Structure

Save Timing

Resumability

Progress Tracking

Workflow

Step 1t: Test Infrastructure Bootstrap (tests-only mode only)

Step 1: Bootstrap Structure Plan (default mode only)

Step 2: Task Decomposition (default and single component modes)

Step 3: Blackbox Test Task Decomposition (default and tests-only modes)

Step 4: Cross-Task Verification (default and tests-only modes)

Common Mistakes

Escalation Rules

Methodology Quick Reference

21 KiB

Raw Blame History