azaion/annotations
1
0
Fork 0
mirror of https://github.com/azaion/annotations.git synced 2026-04-22 22:26:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

Sync .cursor from detections

Browse Source
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-04-12 05:05:09 +03:00
parent 587b0e3c2d
commit d818daacd1
116 changed files with 10075 additions and 4577 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cursor/README.md
+176 -137
View File
@@ -1,179 +1,218 @@
## Developer TODO (Project Mode)
## How to Use
### BUILD (green-field or new features)
Type `/autopilot` to start or continue the full workflow. The orchestrator detects where your project is and picks up from there.
```
1. Create _docs/00_problem/ — describe what you're building
/autopilot — start a new project or continue where you left off
```
If you want to run a specific skill directly (without the orchestrator), use the individual commands:
```
/problem — interactive problem gathering → _docs/00_problem/
/research — solution drafts → _docs/01_solution/
/plan — architecture, components, tests → _docs/02_document/
/decompose — atomic task specs → _docs/02_tasks/todo/
/implement — batched parallel implementation → _docs/03_implementation/
/deploy — containerization, CI/CD, observability → _docs/04_deploy/
```
## How It Works
The autopilot is a state machine that persists its state to `_docs/_autopilot_state.md`. On every invocation it reads the state file, cross-checks against the `_docs/` folder structure, shows a status summary with context from prior sessions, and continues execution.
```
/autopilot invoked
│
▼
Read _docs/_autopilot_state.md → cross-check _docs/ folders
│
▼
Show status summary (progress, key decisions, last session context)
│
▼
Execute current skill (read its SKILL.md, follow its workflow)
│
▼
Update state file → auto-chain to next skill → loop
```
The state file tracks completed steps, key decisions, blockers, and session context. This makes re-entry across conversations seamless — the autopilot knows not just where you are, but what decisions were made and why.
Skills auto-chain without pausing between them. The only pauses are:
- **BLOCKING gates** inside each skill (user must confirm before proceeding)
- **Session boundary** after decompose (suggests new conversation before implement)
A typical project runs in 2-4 conversations:
- Session 1: Problem → Research → Research decision
- Session 2: Plan → Decompose
- Session 3: Implement (may span multiple sessions)
- Session 4: Deploy
Re-entry is seamless: type `/autopilot` in a new conversation and the orchestrator reads the state file to pick up exactly where you left off.
## Skill Descriptions
### autopilot (meta-orchestrator)
Auto-chaining engine that sequences the full BUILD → SHIP workflow. Persists state to `_docs/_autopilot_state.md`, tracks key decisions and session context, and flows through problem → research → plan → decompose → implement → deploy without manual skill invocation. Maximizes work per conversation with seamless cross-session re-entry.
### problem
Interactive interview that builds `_docs/00_problem/`. Asks probing questions across 8 dimensions (problem, scope, hardware, software, acceptance criteria, input data, security, operations) until all required files can be written with concrete, measurable content.
### research
8-step deep research methodology. Mode A produces initial solution drafts. Mode B assesses and revises existing drafts. Includes AC assessment, source tiering, fact extraction, comparison frameworks, and validation. Run multiple rounds until the solution is solid.
### plan
6-step planning workflow. Produces integration test specs, architecture, system flows, data model, deployment plan, component specs with interfaces, risk assessment, test specifications, and work item epics. Heavy interaction at BLOCKING gates.
### decompose
4-step task decomposition. Produces a bootstrap structure plan, atomic task specs per component, integration test tasks, and a cross-task dependency table. Each task gets a work item ticket and is capped at 8 complexity points.
### implement
Orchestrator that reads task specs, computes dependency-aware execution batches, launches up to 4 parallel implementer subagents, runs code review after each batch, and commits per batch. Does not write code itself.
### deploy
7-step deployment planning. Status check, containerization, CI/CD pipeline, environment strategy, observability, deployment procedures, and deployment scripts. Produces documents for steps 1-6 and executable scripts in step 7.
### code-review
Multi-phase code review against task specs. Produces structured findings with verdict: PASS, FAIL, or PASS_WITH_WARNINGS.
### refactor
6-phase structured refactoring: baseline, discovery, analysis, safety net, execution, hardening.
### security
OWASP-based security testing and audit.
### retrospective
Collects metrics from implementation batch reports, analyzes trends, produces improvement reports.
### document
Bottom-up codebase documentation. Analyzes existing code from modules through components to architecture, then retrospectively derives problem/restrictions/acceptance criteria. Alternative entry point for existing codebases — produces the same `_docs/` artifacts as problem + plan, but from code analysis instead of user interview.
## Developer TODO (Project Mode)
### BUILD
```
0. /problem — interactive interview → _docs/00_problem/
- problem.md (required)
- restrictions.md (required)
- acceptance_criteria.md (required)
- input_data/ (required)
- security_approach.md (optional)
2. /research — produces solution drafts in _docs/01_solution/
1. /research — solution drafts → _docs/01_solution/
Run multiple times: Mode A → draft, Mode B → assess & revise
Finalize as solution.md
3. /plan — architecture, components, risks, tests → _docs/02_plans/
2. /plan — architecture, data model, deployment, components, risks, tests, epics → _docs/02_document/
4. /decompose — feature specs, implementation order → _docs/02_tasks/
3. /decompose — atomic task specs + dependency table → _docs/02_tasks/todo/
5. /implement-initial — scaffold project from initial_structure.md (once)
6. /implement-wave — implement next wave of features (repeat per wave)
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
4. /implement — batched parallel agents, code review, commit per batch → _docs/03_implementation/
```
### SHIP (deploy and operate)
### SHIP
```
10. /implement-cicd — validate/enhance CI/CD pipeline
11. /deploy — deployment strategy per environment
12. /observability — monitoring, logging, alerting plan
5. /deploy — containerization, CI/CD, environments, observability, procedures → _docs/04_deploy/
```
### EVOLVE (maintenance and improvement)
### EVOLVE
```
13. /refactor — structured refactoring (skill, 6-phase workflow)
6. /refactor — structured refactoring → _docs/04_refactoring/
7. /retrospective — metrics, trends, improvement actions → _docs/06_metrics/
```
## Implementation Flow
### `/implement-initial`
Reads `_docs/02_tasks/<topic>/initial_structure.md` and scaffolds the project skeleton: folder structure, shared models, interfaces, stubs, .gitignore, .env.example, CI/CD config, DB migrations setup, test structure.
Run once after decompose.
### `/implement-wave`
Reads `SUMMARY.md` and `cross_dependencies.md` from `_docs/02_tasks/<topic>/`.
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
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.
### `/implement-black-box-tests`
Reads `_docs/02_plans/<topic>/e2e_test_infrastructure.md` (produced by plan skill). Builds a separate Docker-based consumer app that exercises the system as a black box — no internal imports, no direct DB access. Runs E2E scenarios, produces a CSV test report.
Run after all waves are done.
### `/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.
### `/deploy`
Defines deployment strategy per environment: deployment procedures, rollback procedures, health checks, deployment checklist. Outputs `_docs/02_components/deployment_strategy.md`.
Run before first production release.
### `/observability`
Plans logging strategy, metrics collection, distributed tracing, alerting rules, and dashboards. Outputs `_docs/02_components/observability_plan.md`.
Run before first production release.
### Commit
After each wave or review — standard `git add && git commit`. The wave command suggests a commit message.
Or just use `/autopilot` to run steps 0-5 automatically.
## Available Skills
| Skill | Triggers | Purpose |
|-------|----------|---------|
| **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 |
| **refactor** | "refactor", "refactoring", "improve code" | 6-phase structured refactoring workflow |
| **security** | "security audit", "OWASP" | OWASP-based security testing |
| Skill | Triggers | Output |
|-------|----------|--------|
| **autopilot** | "autopilot", "auto", "start", "continue", "what's next" | Orchestrates full workflow |
| **problem** | "problem", "define problem", "new project" | `_docs/00_problem/` |
| **research** | "research", "investigate" | `_docs/01_solution/` |
| **plan** | "plan", "decompose solution" | `_docs/02_document/` |
| **test-spec** | "test spec", "blackbox tests", "test scenarios" | `_docs/02_document/tests/` + `scripts/` |
| **decompose** | "decompose", "task decomposition" | `_docs/02_tasks/todo/` |
| **implement** | "implement", "start implementation" | `_docs/03_implementation/` |
| **test-run** | "run tests", "test suite", "verify tests" | Test results + verdict |
| **code-review** | "code review", "review code" | Verdict: PASS / FAIL / PASS_WITH_WARNINGS |
| **new-task** | "new task", "add feature", "new functionality" | `_docs/02_tasks/todo/` |
| **ui-design** | "design a UI", "mockup", "design system" | `_docs/02_document/ui_mockups/` |
| **refactor** | "refactor", "improve code" | `_docs/04_refactoring/` |
| **security** | "security audit", "OWASP" | `_docs/05_security/` |
| **document** | "document", "document codebase", "reverse-engineer docs" | `_docs/02_document/` + `_docs/00_problem/` + `_docs/01_solution/` |
| **deploy** | "deploy", "CI/CD", "observability" | `_docs/04_deploy/` |
| **retrospective** | "retrospective", "retro" | `_docs/06_metrics/` |
## Tools
| Tool | Type | Purpose |
|------|------|---------|
| `implementer` | Subagent | Implements a single task. Launched by `/implement`. |
## Project Folder Structure
```
_project.md — project-specific config (tracker type, project key, etc.)
_docs/
├── 00_problem/
│ ├── problem.md
│ ├── restrictions.md
│ ├── acceptance_criteria.md
│ └── security_approach.md
├── 01_solution/
│ ├── solution_draft01.md
│ ├── solution_draft02.md
│ ├── solution.md
│ ├── tech_stack.md
│ └── security_analysis.md
├── 01_research/
│ └── <topic>/
├── 02_plans/
│ └── <topic>/
│ ├── architecture.md
│ ├── system-flows.md
│ ├── components/
│ └── FINAL_report.md
├── 02_tasks/
│ └── <topic>/
│ ├── initial_structure.md
│ ├── cross_dependencies.md
│ ├── SUMMARY.md
│ └── [##]_[component]/
│ └── [##].[##]_feature_[name].md
└── 04_refactoring/
├── baseline_metrics.md
├── discovery/
├── analysis/
├── test_specs/
├── coupling_analysis.md
├── execution_log.md
├── hardening/
└── FINAL_report.md
├── _autopilot_state.md — autopilot orchestrator state (progress, decisions, session context)
├── 00_problem/ — problem definition, restrictions, AC, input data
├── 00_research/ — intermediate research artifacts
├── 01_solution/ — solution drafts, tech stack, security analysis
├── 02_document/
│ ├── architecture.md
│ ├── system-flows.md
│ ├── data_model.md
│ ├── risk_mitigations.md
│ ├── components/[##]_[name]/ — description.md + tests.md per component
│ ├── common-helpers/
│ ├── tests/ — environment, test data, blackbox, performance, resilience, security, traceability
│ ├── deployment/ — containerization, CI/CD, environments, observability, procedures
│ ├── ui_mockups/ — HTML+CSS mockups, DESIGN.md (ui-design skill)
│ ├── diagrams/
│ └── FINAL_report.md
├── 02_tasks/ — task lifecycle folders + _dependencies_table.md
│ ├── _dependencies_table.md
│ ├── todo/ — tasks ready for implementation
│ ├── backlog/ — parked tasks (not scheduled yet)
│ └── done/ — completed/archived tasks
├── 02_task_plans/ — per-task research artifacts (new-task skill)
├── 03_implementation/ — batch reports, implementation_report_*.md
│ └── reviews/ — code review reports per batch
├── 04_deploy/ — containerization, CI/CD, environments, observability, procedures, scripts
├── 04_refactoring/ — baseline, discovery, analysis, execution, hardening
├── 05_security/ — dependency scan, SAST, OWASP review, security report
└── 06_metrics/ — retro_[YYYY-MM-DD].md
```
## Implementation Tools
## Standalone Mode
| 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. |
| `/implement-cicd` | Command | Validate and enhance CI/CD pipeline. |
| `/deploy` | Command | Plan deployment strategy per environment. |
| `/observability` | Command | Plan logging, metrics, tracing, alerting. |
## Standalone Mode (Reference)
Any skill can run in standalone mode by passing an explicit file:
`research` and `refactor` support standalone mode — output goes to `_standalone/` (git-ignored):
```
/research @my_problem.md
/plan @my_design.md
/decompose @some_spec.md
/refactor @some_component.md
```
Output goes to `_standalone/<topic>/` (git-ignored) instead of `_docs/`. Standalone mode relaxes guardrails — only the provided file is required; restrictions and acceptance criteria are optional.
Single component decompose is also supported:
## Single Component Mode (Decompose)
```
/decompose @_docs/02_plans/<topic>/components/03_parser/description.md
/decompose @_docs/02_document/components/03_parser/description.md
```
Appends tasks for that component to `_docs/02_tasks/todo/` without running bootstrap or cross-verification.