mirror of
https://github.com/azaion/ai-training.git
synced 2026-04-23 06:16:36 +00:00
Refactor task management structure and update documentation
- Changed the directory structure for task specifications to include a dedicated `todo/` folder within `_docs/02_tasks/` for tasks ready for implementation. - Updated references in various skills and documentation to reflect the new task lifecycle, including changes in the `implementer` and `decompose` skills. - Enhanced the README and flow documentation to clarify the new task organization and its implications for the implementation process. These updates improve task management clarity and streamline the implementation workflow.
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -35,12 +35,14 @@ 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/`
|
||||
- TASKS_TODO: `_docs/02_tasks/todo/`
|
||||
- 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/`
|
||||
- TASKS_TODO: `_docs/02_tasks/todo/`
|
||||
- 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)
|
||||
@@ -48,6 +50,7 @@ Determine the operating mode based on invocation before any other logic runs.
|
||||
**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/`
|
||||
- TASKS_TODO: `_docs/02_tasks/todo/`
|
||||
- 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)
|
||||
@@ -99,8 +102,8 @@ Announce the detected mode and resolved paths to the user before proceeding.
|
||||
|
||||
**Default:**
|
||||
1. DOCUMENT_DIR contains `architecture.md` and `components/` — **STOP if missing**
|
||||
2. Create TASKS_DIR if it does not exist
|
||||
3. If TASKS_DIR already contains task files, ask user: **resume from last checkpoint or start fresh?**
|
||||
2. Create TASKS_DIR and TASKS_TODO if they do not exist
|
||||
3. If TASKS_DIR subfolders (`todo/`, `backlog/`, `done/`) already contain 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**
|
||||
@@ -108,8 +111,8 @@ Announce the detected mode and resolved paths to the user before proceeding.
|
||||
**Tests-only mode:**
|
||||
1. `TESTS_DIR/blackbox-tests.md` exists and is non-empty — **STOP if missing**
|
||||
2. `TESTS_DIR/environment.md` exists — **STOP if missing**
|
||||
3. Create TASKS_DIR if it does not exist
|
||||
4. If TASKS_DIR already contains task files, ask user: **resume from last checkpoint or start fresh?**
|
||||
3. Create TASKS_DIR and TASKS_TODO if they do not exist
|
||||
4. If TASKS_DIR subfolders (`todo/`, `backlog/`, `done/`) already contain task files, ask user: **resume from last checkpoint or start fresh?**
|
||||
|
||||
## Artifact Management
|
||||
|
||||
@@ -117,30 +120,32 @@ Announce the detected mode and resolved paths to the user before proceeding.
|
||||
|
||||
```
|
||||
TASKS_DIR/
|
||||
├── [JIRA-ID]_initial_structure.md
|
||||
├── [JIRA-ID]_[short_name].md
|
||||
├── [JIRA-ID]_[short_name].md
|
||||
├── ...
|
||||
└── _dependencies_table.md
|
||||
├── _dependencies_table.md
|
||||
├── todo/
|
||||
│ ├── [JIRA-ID]_initial_structure.md
|
||||
│ ├── [JIRA-ID]_[short_name].md
|
||||
│ └── ...
|
||||
├── backlog/
|
||||
└── done/
|
||||
```
|
||||
|
||||
**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`.
|
||||
**Naming convention**: Each task file is initially saved in `TASKS_TODO/` with a temporary numeric prefix (`[##]_[short_name].md`). After creating the Jira ticket, rename the file to use the Jira ticket ID as prefix (`[JIRA-ID]_[short_name].md`). For example: `todo/01_initial_structure.md` → `todo/AZ-42_initial_structure.md`.
|
||||
|
||||
### 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 1 | Bootstrap structure plan complete + Jira ticket created + file renamed | `todo/[JIRA-ID]_initial_structure.md` |
|
||||
| Step 1t | Test infrastructure bootstrap complete + Jira ticket created + file renamed | `todo/[JIRA-ID]_test_infrastructure.md` |
|
||||
| Step 2 | Each component task decomposed + Jira ticket created + file renamed | `todo/[JIRA-ID]_[short_name].md` |
|
||||
| Step 3 | Each blackbox test task decomposed + Jira ticket created + file renamed | `todo/[JIRA-ID]_[short_name].md` |
|
||||
| Step 4 | Cross-task verification complete | `_dependencies_table.md` |
|
||||
|
||||
### Resumability
|
||||
|
||||
If TASKS_DIR already contains task files:
|
||||
If TASKS_DIR subfolders already contain task files:
|
||||
|
||||
1. List existing `*_*.md` files (excluding `_dependencies_table.md`) and count them
|
||||
1. List existing `*_*.md` files across `todo/`, `backlog/`, and `done/` (excluding `_dependencies_table.md`) and count them
|
||||
2. Resume numbering from the next number (for temporary numeric prefix before Jira rename)
|
||||
3. Inform the user which tasks already exist and are being skipped
|
||||
|
||||
@@ -176,11 +181,11 @@ The test infrastructure bootstrap must include:
|
||||
- [ ] 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)
|
||||
**Save action**: Write `todo/01_test_infrastructure.md` (temporary numeric name)
|
||||
|
||||
**Jira action**: Create a Jira ticket for this task under the "Blackbox Tests" epic. Write the Jira ticket ID and Epic ID back into the task header.
|
||||
|
||||
**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.
|
||||
**Rename action**: Rename the file from `todo/01_test_infrastructure.md` to `todo/[JIRA-ID]_test_infrastructure.md`. Update the **Task** field inside the file to match the new filename.
|
||||
|
||||
**BLOCKING**: Present test infrastructure plan summary to user. Do NOT proceed until user confirms.
|
||||
|
||||
@@ -224,11 +229,11 @@ The bootstrap structure plan must include:
|
||||
- [ ] Environment strategy covers dev, staging, production
|
||||
- [ ] Test structure includes unit and blackbox test locations
|
||||
|
||||
**Save action**: Write `01_initial_structure.md` (temporary numeric name)
|
||||
**Save action**: Write `todo/01_initial_structure.md` (temporary numeric name)
|
||||
|
||||
**Jira action**: Create a Jira ticket for this task under the "Bootstrap & Initial Structure" epic. Write the Jira ticket ID and Epic ID back into the task header.
|
||||
|
||||
**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.
|
||||
**Rename action**: Rename the file from `todo/01_initial_structure.md` to `todo/[JIRA-ID]_initial_structure.md` (e.g., `todo/AZ-42_initial_structure.md`). Update the **Task** field inside the file to match the new filename.
|
||||
|
||||
**BLOCKING**: Present structure plan summary to user. Do NOT proceed until user confirms.
|
||||
|
||||
@@ -254,7 +259,7 @@ For each component (or the single provided component):
|
||||
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`.
|
||||
9. **Immediately after writing each task file**: create a Jira ticket, link it to the component's epic, write the Jira ticket ID and Epic ID back into the task header, then rename the file from `todo/[##]_[short_name].md` to `todo/[JIRA-ID]_[short_name].md`.
|
||||
|
||||
**Self-verification** (per component):
|
||||
- [ ] Every task is atomic (single concern)
|
||||
@@ -264,7 +269,7 @@ For each component (or the single provided component):
|
||||
- [ ] 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.
|
||||
**Save action**: Write each `todo/[##]_[short_name].md` (temporary numeric name), create Jira ticket inline, then rename to `todo/[JIRA-ID]_[short_name].md`. Update the **Task** field inside the file to match the new filename. Update **Dependencies** references in the file to use Jira IDs of the dependency tasks.
|
||||
|
||||
---
|
||||
|
||||
@@ -287,7 +292,7 @@ For each component (or the single provided component):
|
||||
5. Write each task spec using `templates/task.md`
|
||||
6. Estimate complexity per task (1, 2, 3, 5 points); no task should exceed 5 points — split if it does
|
||||
7. Note task dependencies (referencing Jira IDs of already-created dependency tasks)
|
||||
8. **Immediately after writing each task file**: create a Jira ticket under the "Blackbox Tests" epic, write the Jira ticket ID and Epic ID back into the task header, then rename the file from `[##]_[short_name].md` to `[JIRA-ID]_[short_name].md`.
|
||||
8. **Immediately after writing each task file**: create a Jira ticket under the "Blackbox Tests" epic, write the Jira ticket ID and Epic ID back into the task header, then rename the file from `todo/[##]_[short_name].md` to `todo/[JIRA-ID]_[short_name].md`.
|
||||
|
||||
**Self-verification**:
|
||||
- [ ] Every scenario from `tests/blackbox-tests.md` is covered by a task
|
||||
@@ -296,7 +301,7 @@ For each component (or the single provided component):
|
||||
- [ ] 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`.
|
||||
**Save action**: Write each `todo/[##]_[short_name].md` (temporary numeric name), create Jira ticket inline, then rename to `todo/[JIRA-ID]_[short_name].md`.
|
||||
|
||||
---
|
||||
|
||||
@@ -342,7 +347,7 @@ Tests-only mode:
|
||||
- **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
|
||||
- **Creating component subdirectories**: all tasks go flat in `TASKS_TODO/`
|
||||
- **Forgetting Jira**: every task must have a Jira ticket created inline — do not defer to a separate step
|
||||
- **Forgetting to rename**: after Jira ticket creation, always rename the file from numeric prefix to Jira ID prefix
|
||||
|
||||
|
||||
Reference in New Issue
Block a user