mirror of
https://github.com/azaion/detections.git
synced 2026-04-22 22:46:31 +00:00
[AZ-172] Update documentation for distributed architecture, add Update Docs step to workflow
- Update module docs: main, inference, ai_config, loader_http_client - Add new module doc: media_hash - Update component docs: inference_pipeline, api - Update system-flows (F2, F3) and data_parameters - Add Task Mode to document skill for incremental doc updates - Insert Step 11 (Update Docs) in existing-code flow, renumber 11-13 to 12-14 Made-with: Cursor
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -16,11 +16,12 @@ Workflow for projects with an existing codebase. Starts with documentation, prod
|
||||
| 8 | New Task | new-task/SKILL.md | Steps 1–8 (loop) |
|
||||
| 9 | Implement | implement/SKILL.md | (batch-driven, no fixed sub-steps) |
|
||||
| 10 | Run Tests | test-run/SKILL.md | Steps 1–4 |
|
||||
| 11 | Security Audit | security/SKILL.md | Phase 1–5 (optional) |
|
||||
| 12 | Performance Test | (autopilot-managed) | Load/stress tests (optional) |
|
||||
| 13 | Deploy | deploy/SKILL.md | Step 1–7 |
|
||||
| 11 | Update Docs | document/SKILL.md (task mode) | Task Steps 0–5 |
|
||||
| 12 | Security Audit | security/SKILL.md | Phase 1–5 (optional) |
|
||||
| 13 | Performance Test | (autopilot-managed) | Load/stress tests (optional) |
|
||||
| 14 | Deploy | deploy/SKILL.md | Step 1–7 |
|
||||
|
||||
After Step 13, the existing-code workflow is complete.
|
||||
After Step 14, the existing-code workflow is complete.
|
||||
|
||||
## Detection Rules
|
||||
|
||||
@@ -157,8 +158,24 @@ Action: Read and execute `.cursor/skills/test-run/SKILL.md`
|
||||
|
||||
---
|
||||
|
||||
**Step 11 — Security Audit (optional)**
|
||||
Condition: the autopilot state shows Step 10 (Run Tests) is completed AND the autopilot state does NOT show Step 11 (Security Audit) as completed or skipped AND (`_docs/04_deploy/` does not exist or is incomplete)
|
||||
**Step 11 — Update Docs**
|
||||
Condition: the autopilot state shows Step 10 (Run Tests) is completed AND the autopilot state does NOT show Step 11 (Update Docs) as completed AND `_docs/02_document/` contains existing documentation (module or component docs)
|
||||
|
||||
Action: Read and execute `.cursor/skills/document/SKILL.md` in **Task mode**. Pass all task spec files from `_docs/02_tasks/done/` that were implemented in the current cycle (i.e., tasks moved to `done/` during Steps 8–9 of this cycle).
|
||||
|
||||
The document skill in Task mode:
|
||||
1. Reads each task spec to identify changed source files
|
||||
2. Updates affected module docs, component docs, and system-level docs
|
||||
3. Does NOT redo full discovery, verification, or problem extraction
|
||||
|
||||
If `_docs/02_document/` does not contain existing docs (e.g., documentation step was skipped), mark Step 11 as `skipped`.
|
||||
|
||||
After completion, auto-chain to Step 12 (Security Audit).
|
||||
|
||||
---
|
||||
|
||||
**Step 12 — Security Audit (optional)**
|
||||
Condition: the autopilot state shows Step 11 (Update Docs) is completed or skipped AND the autopilot state does NOT show Step 12 (Security Audit) as completed or skipped AND (`_docs/04_deploy/` does not exist or is incomplete)
|
||||
|
||||
Action: Present using Choose format:
|
||||
|
||||
@@ -173,13 +190,13 @@ Action: Present using Choose format:
|
||||
══════════════════════════════════════
|
||||
```
|
||||
|
||||
- If user picks A → Read and execute `.cursor/skills/security/SKILL.md`. After completion, auto-chain to Step 12 (Performance Test).
|
||||
- If user picks B → Mark Step 11 as `skipped` in the state file, auto-chain to Step 12 (Performance Test).
|
||||
- If user picks A → Read and execute `.cursor/skills/security/SKILL.md`. After completion, auto-chain to Step 13 (Performance Test).
|
||||
- If user picks B → Mark Step 12 as `skipped` in the state file, auto-chain to Step 13 (Performance Test).
|
||||
|
||||
---
|
||||
|
||||
**Step 12 — Performance Test (optional)**
|
||||
Condition: the autopilot state shows Step 11 (Security Audit) is completed or skipped AND the autopilot state does NOT show Step 12 (Performance Test) as completed or skipped AND (`_docs/04_deploy/` does not exist or is incomplete)
|
||||
**Step 13 — Performance Test (optional)**
|
||||
Condition: the autopilot state shows Step 12 (Security Audit) is completed or skipped AND the autopilot state does NOT show Step 13 (Performance Test) as completed or skipped AND (`_docs/04_deploy/` does not exist or is incomplete)
|
||||
|
||||
Action: Present using Choose format:
|
||||
|
||||
@@ -200,13 +217,13 @@ Action: Present using Choose format:
|
||||
2. Otherwise, check if `_docs/02_document/tests/performance-tests.md` exists for test scenarios, detect appropriate load testing tool (k6, locust, artillery, wrk, or built-in benchmarks), and execute performance test scenarios against the running system
|
||||
3. Present results vs acceptance criteria thresholds
|
||||
4. If thresholds fail → present Choose format: A) Fix and re-run, B) Proceed anyway, C) Abort
|
||||
5. After completion, auto-chain to Step 13 (Deploy)
|
||||
- If user picks B → Mark Step 12 as `skipped` in the state file, auto-chain to Step 13 (Deploy).
|
||||
5. After completion, auto-chain to Step 14 (Deploy)
|
||||
- If user picks B → Mark Step 13 as `skipped` in the state file, auto-chain to Step 14 (Deploy).
|
||||
|
||||
---
|
||||
|
||||
**Step 13 — Deploy**
|
||||
Condition: the autopilot state shows Step 10 (Run Tests) is completed AND (Step 11 is completed or skipped) AND (Step 12 is completed or skipped) AND (`_docs/04_deploy/` does not exist or is incomplete)
|
||||
**Step 14 — Deploy**
|
||||
Condition: the autopilot state shows Step 10 (Run Tests) is completed AND (Step 11 is completed or skipped) AND (Step 12 is completed or skipped) AND (Step 13 is completed or skipped) AND (`_docs/04_deploy/` does not exist or is incomplete)
|
||||
|
||||
Action: Read and execute `.cursor/skills/deploy/SKILL.md`
|
||||
|
||||
@@ -215,7 +232,7 @@ After deployment completes, the existing-code workflow is done.
|
||||
---
|
||||
|
||||
**Re-Entry After Completion**
|
||||
Condition: the autopilot state shows `step: done` OR all steps through 13 (Deploy) are completed
|
||||
Condition: the autopilot state shows `step: done` OR all steps through 14 (Deploy) are completed
|
||||
|
||||
Action: The project completed a full cycle. Print the status banner and automatically loop back to New Task — do NOT ask the user for confirmation:
|
||||
|
||||
@@ -230,6 +247,8 @@ Action: The project completed a full cycle. Print the status banner and automati
|
||||
|
||||
Set `step: 8`, `status: not_started` in the state file, then auto-chain to Step 8 (New Task).
|
||||
|
||||
Note: the loop (Steps 8 → 14 → 8) ensures every feature cycle includes: New Task → Implement → Run Tests → Update Docs → Security → Performance → Deploy.
|
||||
|
||||
## Auto-Chain Rules
|
||||
|
||||
| Completed Step | Next Action |
|
||||
@@ -243,10 +262,11 @@ Set `step: 8`, `status: not_started` in the state file, then auto-chain to Step
|
||||
| Refactor (7, done or skipped) | Auto-chain → New Task (8) |
|
||||
| New Task (8) | **Session boundary** — suggest new conversation before Implement |
|
||||
| Implement (9) | Auto-chain → Run Tests (10) |
|
||||
| Run Tests (10, all pass) | Auto-chain → Security Audit choice (11) |
|
||||
| Security Audit (11, done or skipped) | Auto-chain → Performance Test choice (12) |
|
||||
| Performance Test (12, done or skipped) | Auto-chain → Deploy (13) |
|
||||
| Deploy (13) | **Workflow complete** — existing-code flow done |
|
||||
| Run Tests (10, all pass) | Auto-chain → Update Docs (11) |
|
||||
| Update Docs (11) | Auto-chain → Security Audit choice (12) |
|
||||
| Security Audit (12, done or skipped) | Auto-chain → Performance Test choice (13) |
|
||||
| Performance Test (13, done or skipped) | Auto-chain → Deploy (14) |
|
||||
| Deploy (14) | **Workflow complete** — existing-code flow done |
|
||||
|
||||
## Status Summary Template
|
||||
|
||||
@@ -264,9 +284,10 @@ Set `step: 8`, `status: not_started` in the state file, then auto-chain to Step
|
||||
Step 8 New Task [DONE (N tasks) / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
|
||||
Step 9 Implement [DONE / IN PROGRESS (batch M of ~N) / NOT STARTED / FAILED (retry N/3)]
|
||||
Step 10 Run Tests [DONE (N passed, M failed) / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
|
||||
Step 11 Security Audit [DONE / SKIPPED / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
|
||||
Step 12 Performance Test [DONE / SKIPPED / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
|
||||
Step 13 Deploy [DONE / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
|
||||
Step 11 Update Docs [DONE / SKIPPED / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
|
||||
Step 12 Security Audit [DONE / SKIPPED / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
|
||||
Step 13 Performance Test [DONE / SKIPPED / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
|
||||
Step 14 Deploy [DONE / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
|
||||
═══════════════════════════════════════════════════
|
||||
Current: Step N — Name
|
||||
SubStep: M — [sub-skill internal step name]
|
||||
|
||||
@@ -51,9 +51,12 @@ Determine the execution mode before any other logic:
|
||||
| **Full** | No input file, no existing state | Entire codebase |
|
||||
| **Focus Area** | User provides a directory path (e.g., `@src/api/`) | Only the specified subtree + transitive dependencies |
|
||||
| **Resume** | `state.json` exists in DOCUMENT_DIR | Continue from last checkpoint |
|
||||
| **Task** | User provides a task spec file (e.g., `@_docs/02_tasks/done/AZ-173_*.md`) AND `_docs/02_document/` has existing docs | Targeted update of docs affected by the task |
|
||||
|
||||
Focus Area mode produces module + component docs for the targeted area only. It can be run repeatedly for different areas — each run appends to the existing module and component docs without overwriting other areas.
|
||||
|
||||
Task mode is a lightweight, incremental update — it reads the task spec to identify which files changed, then updates only the affected module docs, component docs, system flows, and data parameters. It does NOT redo discovery, verification, or problem extraction. See **Task Mode Workflow** below.
|
||||
|
||||
## Prerequisite Checks
|
||||
|
||||
1. If `_docs/` already exists and contains files AND mode is **Full**, ASK user: **overwrite, merge, or write to `_docs_generated/` instead?**
|
||||
@@ -387,6 +390,88 @@ Using `.cursor/skills/plan/templates/final-report.md` as structure:
|
||||
|
||||
---
|
||||
|
||||
## Task Mode Workflow
|
||||
|
||||
Triggered when a task spec file is provided as input AND `_docs/02_document/` already contains module/component docs.
|
||||
|
||||
**Accepts**: one or more task spec files (from `_docs/02_tasks/todo/` or `_docs/02_tasks/done/`).
|
||||
|
||||
### Task Step 0: Scope Analysis
|
||||
|
||||
1. Read each task spec — extract the "Files Modified" or "Scope / Included" section to identify which source files were changed
|
||||
2. Map changed source files to existing module docs in `DOCUMENT_DIR/modules/`
|
||||
3. Map affected modules to their parent components in `DOCUMENT_DIR/components/`
|
||||
4. Identify which higher-level docs might be affected (system-flows, data_model, data_parameters)
|
||||
|
||||
**Output**: a list of docs to update, organized by level:
|
||||
- Module docs (direct matches)
|
||||
- Component docs (parents of affected modules)
|
||||
- System-level docs (only if the task changed API endpoints, data models, or external integrations)
|
||||
- Problem-level docs (only if the task changed input parameters, acceptance criteria, or restrictions)
|
||||
|
||||
### Task Step 1: Module Doc Updates
|
||||
|
||||
For each affected module:
|
||||
|
||||
1. Read the current source file
|
||||
2. Read the existing module doc
|
||||
3. Diff the module doc against current code — identify:
|
||||
- New functions/methods/classes not in the doc
|
||||
- Removed functions/methods/classes still in the doc
|
||||
- Changed signatures or behavior
|
||||
- New/removed dependencies
|
||||
- New/removed external integrations
|
||||
4. Update the module doc in-place, preserving the existing structure and style
|
||||
5. If a module is entirely new (no existing doc), create a new module doc following the standard template
|
||||
|
||||
### Task Step 2: Component Doc Updates
|
||||
|
||||
For each affected component:
|
||||
|
||||
1. Read all module docs belonging to this component (including freshly updated ones)
|
||||
2. Read the existing component doc
|
||||
3. Update internal interfaces, dependency graphs, implementation details, and caveats sections
|
||||
4. Do NOT change the component's purpose, pattern, or high-level overview unless the task fundamentally changed it
|
||||
|
||||
### Task Step 3: System-Level Doc Updates (conditional)
|
||||
|
||||
Only if the task changed API endpoints, system flows, data models, or external integrations:
|
||||
|
||||
1. Update `system-flows.md` — modify affected flow diagrams and data flow tables
|
||||
2. Update `data_model.md` — if entities changed
|
||||
3. Update `architecture.md` — only if new external integrations or architectural patterns were added
|
||||
|
||||
### Task Step 4: Problem-Level Doc Updates (conditional)
|
||||
|
||||
Only if the task changed API input parameters, configuration, or acceptance criteria:
|
||||
|
||||
1. Update `_docs/00_problem/input_data/data_parameters.md`
|
||||
2. Update `_docs/00_problem/acceptance_criteria.md` — if new testable criteria emerged
|
||||
|
||||
### Task Step 5: Summary
|
||||
|
||||
Present a summary of all docs updated:
|
||||
|
||||
```
|
||||
══════════════════════════════════════
|
||||
DOCUMENTATION UPDATE COMPLETE
|
||||
══════════════════════════════════════
|
||||
Task(s): [task IDs]
|
||||
Module docs updated: [count]
|
||||
Component docs updated: [count]
|
||||
System-level docs updated: [list or "none"]
|
||||
Problem-level docs updated: [list or "none"]
|
||||
══════════════════════════════════════
|
||||
```
|
||||
|
||||
### Task Mode Principles
|
||||
|
||||
- **Minimal changes**: only update what the task actually changed. Do not rewrite unaffected sections.
|
||||
- **Preserve style**: match the existing doc's structure, tone, and level of detail.
|
||||
- **Verify against code**: for every entity added or changed in a doc, confirm it exists in the current source.
|
||||
- **New modules**: if the task introduced an entirely new source file, create a new module doc from the standard template.
|
||||
- **Dead references**: if the task removed code, remove the corresponding doc entries. Do not keep stale references.
|
||||
|
||||
## Artifact Management
|
||||
|
||||
### Directory Structure
|
||||
|
||||
Reference in New Issue
Block a user