azaion/gps-denied-onboard
1
0
Fork 0
mirror of https://github.com/azaion/gps-denied-onboard.git synced 2026-04-23 01:46:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

Refactor README to streamline project workflows and enhance clarity. Update sections for BUILD, SHIP, and EVOLVE phases, clarifying task specifications and output directories. Remove outdated rollback command documentation and improve the structure of the retrospective skill documentation.

Browse Source
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-03-19 13:08:27 +02:00
parent cfd09c79e1
commit 05411d19b8
4 changed files with 179 additions and 222 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cursor/README.md
+43 -162
View File
@@ -1,215 +1,96 @@
## Developer TODO (Project Mode)
### BUILD (green-field or new features)
### BUILD
```
1. Create _docs/00_problem/ — describe what you're building, restrictions, acceptance criteria and samples of data system works with
1. Create _docs/00_problem/ — describe what you're building
- problem.md (required)
- restrictions.md (required)
- acceptance_criteria.md (required)
- input_data (required)
- input_data/ (required)
- security_approach.md (optional)
2. /research — produces solution drafts in _docs/01_solution/
2. /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, Jira epics → _docs/02_plans/
3. /plan — architecture, data model, deployment, components, risks, tests, Jira epics → _docs/02_plans/
4. /decompose — flat numbered task specs + _dependencies_table.md → _docs/02_tasks/
4. /decompose — atomic task specs + dependency table → _docs/02_tasks/
5. /implement — auto-orchestrates all tasks: batches by dependencies, launches parallel implementers, runs code review, loops until done
6. commit & push
5. /implement — batched parallel agents, code review, commit per batch → _docs/03_implementation/
```
### SHIP (deploy and operate)
### SHIP
```
7. /deploy — containerization, CI/CD, environment strategy, observability, deployment procedures (skill, 5-step workflow)
6. /deploy — containerization, CI/CD, environments, observability, procedures → _docs/02_plans/deployment/
```
### EVOLVE (maintenance and improvement)
### EVOLVE
```
8. /refactor — structured refactoring (skill, 6-phase workflow)
9. /retrospective — collect metrics, analyze trends, produce improvement report (skill)
7. /refactor — structured refactoring → _docs/04_refactoring/
8. /retrospective — metrics, trends, improvement actions → _docs/05_metrics/
```
## Implementation Flow
### `/implement`
Reads flat task files and `_dependencies_table.md` from `_docs/02_tasks/`.
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
### `/code-review`
Multi-phase code review invoked after each implementation batch:
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
Produces structured findings with severity (Critical/High/Medium/Low) and verdict (PASS/FAIL/PASS_WITH_WARNINGS).
### `/deploy`
Comprehensive deployment skill (5-step workflow):
1. Containerization — Dockerfiles per component, docker-compose for dev and tests
2. CI/CD Pipeline — lint, test, security scan, build, deploy with quality gates
3. Environment Strategy — dev, staging, production with secrets management
4. Observability — structured logging, metrics, tracing, alerting, dashboards
5. Deployment Procedures — rollback, health checks, graceful shutdown
Outputs to `_docs/02_plans/deployment/`. Run after `/implement` or before first production release.
### `/retrospective`
Collects metrics from batch reports and code review findings, analyzes trends across implementation cycles, and produces improvement reports. Outputs to `_docs/05_metrics/`.
### `/rollback`
Reverts implementation to a specific batch checkpoint using git revert, resets Jira ticket statuses, and verifies rollback integrity with tests.
### Commit
After each confirmed batch, the `/implement` skill automatically commits and pushes to the remote branch.
## 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" | 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 |
| **deploy** | "deploy", "CI/CD", "containerize", "observability" | Containerization, CI/CD, observability, deployment procedures |
| **retrospective** | "retrospective", "retro", "metrics review" | Collect metrics, analyze trends, produce improvement report |
| Skill | Triggers | Output |
|-------|----------|--------|
| **research** | "research", "investigate" | `_docs/01_solution/` |
| **plan** | "plan", "decompose solution" | `_docs/02_plans/` |
| **decompose** | "decompose", "task decomposition" | `_docs/02_tasks/` |
| **implement** | "implement", "start implementation" | `_docs/03_implementation/` |
| **code-review** | "code review", "review code" | Verdict: PASS / FAIL / PASS_WITH_WARNINGS |
| **refactor** | "refactor", "improve code" | `_docs/04_refactoring/` |
| **security** | "security audit", "OWASP" | Security findings report |
| **deploy** | "deploy", "CI/CD", "observability" | `_docs/02_plans/deployment/` |
| **retrospective** | "retrospective", "retro" | `_docs/05_metrics/` |
| **rollback** | "rollback", "revert batch" | `_docs/03_implementation/rollback_report.md` |
## Tools
| Tool | Type | Purpose |
|------|------|---------|
| `implementer` | Subagent | Implements a single task. Launched by `/implement`. |
## Project Folder Structure
```
_docs/
├── 00_problem/
│ ├── problem.md
│ ├── restrictions.md
│ ├── acceptance_criteria.md
│ ├── input_data/
│ └── security_approach.md
├── 00_research/
│ ├── 00_ac_assessment.md
│ ├── 00_question_decomposition.md
│ ├── 01_source_registry.md
│ ├── 02_fact_cards.md
│ ├── 03_comparison_framework.md
│ ├── 04_reasoning_chain.md
│ └── 05_validation_log.md
├── 01_solution/
│ ├── solution_draft01.md
│ ├── solution_draft02.md
│ ├── solution.md
│ ├── tech_stack.md
│ └── security_analysis.md
├── 00_problem/ — problem definition, restrictions, AC, input data
├── 00_research/ — intermediate research artifacts
├── 01_solution/ — solution drafts, tech stack, security analysis
├── 02_plans/
│ ├── architecture.md
│ ├── system-flows.md
│ ├── data_model.md
│ ├── risk_mitigations.md
│ ├── components/
│ │ └── [##]_[name]/
│ │ ├── description.md
│ │ └── tests.md
│ ├── components/[##]_[name]/ — description.md + tests.md per component
│ ├── common-helpers/
│ ├── integration_tests/
│ │ ├── environment.md
│ │ ├── test_data.md
│ │ ├── functional_tests.md
│ │ ├── non_functional_tests.md
│ │ └── traceability_matrix.md
│ ├── deployment/
│ │ ├── containerization.md
│ │ ├── ci_cd_pipeline.md
│ │ ├── environment_strategy.md
│ │ ├── observability.md
│ │ └── deployment_procedures.md
│ ├── integration_tests/ — environment, test data, functional, non-functional, traceability
│ ├── deployment/ — containerization, CI/CD, environments, observability, procedures
│ ├── diagrams/
│ └── FINAL_report.md
├── 02_tasks/
│ ├── [JIRA-ID]_initial_structure.md
│ ├── [JIRA-ID]_[short_name].md
│ ├── ...
│ └── _dependencies_table.md
├── 03_implementation/
│ ├── batch_01_report.md
│ ├── batch_02_report.md
│ ├── ...
│ └── FINAL_implementation_report.md
├── 04_refactoring/
│ ├── baseline_metrics.md
│ ├── discovery/
│ ├── analysis/
│ ├── test_specs/
│ ├── coupling_analysis.md
│ ├── execution_log.md
│ ├── hardening/
│ └── FINAL_report.md
└── 05_metrics/
└── retro_[date].md
├── 02_tasks/ — [JIRA-ID]_[name].md + _dependencies_table.md
├── 03_implementation/ — batch reports, rollback report, FINAL report
├── 04_refactoring/ — baseline, discovery, analysis, execution, hardening
└── 05_metrics/ — retro_[YYYY-MM-DD].md
```
## Implementation Tools
## Standalone Mode
| Tool | Type | Purpose |
|------|------|---------|
| `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. |
| `/deploy` | Skill | Containerization, CI/CD, observability, deployment procedures. |
| `/retrospective` | Skill | Collect metrics, analyze trends, produce improvement reports. |
| `/rollback` | Command | Revert to a batch checkpoint with Jira status reset. |
## Automations (Planned)
Future automations to explore (Cursor Automations, launched March 2026):
- PR review: trigger code-review skill on PR open (start with Bugbot — read-only, comments only)
- Security scan: trigger security skill on push to main/dev
- Nightly: run integration tests on schedule
Status: experimental — validate with Bugbot first before adding write-heavy automations.
## Standalone Mode (Reference)
Only `research` and `refactor` support standalone mode by passing an explicit file:
`research` and `refactor` support standalone mode — output goes to `_standalone/` (git-ignored):
```
/research @my_problem.md
/refactor @some_component.md
```
Output goes to `_standalone/` (git-ignored) instead of `_docs/`. Standalone mode relaxes guardrails — only the provided file is required; restrictions and acceptance criteria are optional.
## Single Component Mode (Decompose)
Decompose supports single component mode when given a component file from within `_docs/02_plans/components/`:
```
/decompose @_docs/02_plans/components/03_parser/description.md
```
This appends tasks for that component to the existing `_docs/02_tasks/` directory without running bootstrap or cross-verification steps.
Appends tasks for that component to `_docs/02_tasks/` without running bootstrap or cross-verification.
.cursor/commands/rollback.md
-54
View File
@@ -1,54 +0,0 @@
# Implementation Rollback
## Role
You are a DevOps engineer performing a controlled rollback of implementation batches.
## Input
- User specifies a target batch number or commit hash to roll back to
- If not specified, present the list of available batch checkpoints and ask
## Process
1. Read `_docs/03_implementation/batch_*_report.md` files to identify all batch checkpoints with their commit hashes
2. Present batch list to user with: batch number, date, tasks included, commit hash
3. Determine which commits need to be reverted (all commits after the target batch)
4. For each commit to revert (in reverse chronological order):
- Run `git revert <commit-hash> --no-edit`
- Verify no merge conflicts; if conflicts occur, ask user for resolution
5. Run the full test suite to verify rollback integrity
6. If tests fail, report failures and ask user how to proceed
7. Reset Jira ticket statuses for all reverted tasks back to "To Do" via Jira MCP
8. Commit the revert with message: `[ROLLBACK] Reverted to batch [N]: [task list]`
## Output
Write `_docs/03_implementation/rollback_report.md`:
```markdown
# Rollback Report
**Date**: [YYYY-MM-DD]
**Target**: Batch [N] (commit [hash])
**Reverted Batches**: [list]
## Reverted Tasks
| Task | Batch | Status Before | Status After |
|------|-------|--------------|-------------|
| [JIRA-ID] | [batch #] | In Testing | To Do |
## Test Results
- [pass/fail count]
## Jira Updates
- [list of ticket transitions]
## Notes
- [any conflicts, manual steps, or issues encountered]
```
## Safety Rules
- Never force-push; always use `git revert` to preserve history
- Always run tests after rollback
- Always update Jira statuses for reverted tasks
- If rollback fails midway, stop and report — do not leave the codebase in a partial state
.cursor/skills/retrospective/SKILL.md
+6 -6
View File
@@ -160,15 +160,15 @@ Present the report summary to the user.
```
┌────────────────────────────────────────────────────────────────┐
│ Retrospective (3-Step Method) │
│ Retrospective (3-Step Method) │
├────────────────────────────────────────────────────────────────┤
│ PREREQ: batch reports exist in _docs/03_implementation/ │
│ PREREQ: batch reports exist in _docs/03_implementation/ │
│ │
│ 1. Collect Metrics → parse batch reports, compute metrics │
│ 2. Analyze Trends → patterns, comparison, improvement areas │
│ 1. Collect Metrics → parse batch reports, compute metrics │
│ 2. Analyze Trends → patterns, comparison, improvement areas │
│ 3. Produce Report → _docs/05_metrics/retro_[date].md │
├────────────────────────────────────────────────────────────────┤
│ Principles: Data-driven · Actionable · Cumulative │
│ Non-judgmental · Save immediately │
│ Principles: Data-driven · Actionable · Cumulative │
│ Non-judgmental · Save immediately │
└────────────────────────────────────────────────────────────────┘
```
.cursor/skills/rollback/SKILL.md
+130
View File
@@ -0,0 +1,130 @@
---
name: rollback
description: |
Revert implementation to a specific batch checkpoint using git revert, reset Jira ticket statuses,
verify rollback integrity with tests, and produce a rollback report.
Trigger phrases:
- "rollback", "revert", "revert batch"
- "undo implementation", "roll back to batch"
category: build
tags: [rollback, revert, recovery, implementation]
disable-model-invocation: true
---
# Implementation Rollback
Revert the codebase to a specific batch checkpoint, reset Jira statuses for reverted tasks, and verify integrity.
## Core Principles
- **Preserve history**: always use `git revert`, never force-push
- **Verify after revert**: run the full test suite after every rollback
- **Update tracking**: reset Jira ticket statuses for all reverted tasks
- **Atomic rollback**: if rollback fails midway, stop and report — do not leave the codebase in a partial state
- **Ask, don't assume**: if the target batch is ambiguous, present options and ask
## Context Resolution
- IMPL_DIR: `_docs/03_implementation/`
- Batch reports: `IMPL_DIR/batch_*_report.md`
## Prerequisite Checks (BLOCKING)
1. IMPL_DIR exists and contains at least one `batch_*_report.md` — **STOP if missing**
2. Git working tree is clean (no uncommitted changes) — **STOP if dirty**, ask user to commit or stash
## Input
- User specifies a target batch number or commit hash
- If not specified, present the list of available batch checkpoints and ask
## Workflow
### Step 1: Identify Checkpoints
1. Read all `batch_*_report.md` files from IMPL_DIR
2. Extract: batch number, date, tasks included, commit hash, code review verdict
3. Present batch list to user
**BLOCKING**: User must confirm which batch to roll back to.
### Step 2: Revert Commits
1. Determine which commits need to be reverted (all commits after the target batch)
2. For each commit in reverse chronological order:
- Run `git revert <commit-hash> --no-edit`
- If merge conflicts occur: present conflicts and ask user for resolution
3. If any revert fails and cannot be resolved, abort the rollback sequence with `git revert --abort` and report
### Step 3: Verify Integrity
1. Run the full test suite
2. If tests fail: report failures to user, ask how to proceed (fix or abort)
3. If tests pass: continue
### Step 4: Update Jira
1. Identify all tasks from reverted batches
2. Reset each task's Jira ticket status to "To Do" via Jira MCP
### Step 5: Finalize
1. Commit with message: `[ROLLBACK] Reverted to batch [N]: [task list]`
2. Write rollback report to `IMPL_DIR/rollback_report.md`
## Output
Write `_docs/03_implementation/rollback_report.md`:
```markdown
# Rollback Report
**Date**: [YYYY-MM-DD]
**Target**: Batch [N] (commit [hash])
**Reverted Batches**: [list]
## Reverted Tasks
| Task | Batch | Status Before | Status After |
|------|-------|--------------|-------------|
| [JIRA-ID] | [batch #] | In Testing | To Do |
## Test Results
- [pass/fail count]
## Jira Updates
- [list of ticket transitions]
## Notes
- [any conflicts, manual steps, or issues encountered]
```
## Escalation Rules
| Situation | Action |
|-----------|--------|
| No batch reports exist | **STOP** — nothing to roll back |
| Uncommitted changes in working tree | **STOP** — ask user to commit or stash |
| Merge conflicts during revert | **ASK user** for resolution |
| Tests fail after rollback | **ASK user** — fix or abort |
| Rollback fails midway | Abort with `git revert --abort`, report to user |
## Methodology Quick Reference
```
┌────────────────────────────────────────────────────────────────┐
│ Rollback (5-Step Method) │
├────────────────────────────────────────────────────────────────┤
│ PREREQ: batch reports exist, clean working tree │
│ │
│ 1. Identify Checkpoints → present batch list │
│ [BLOCKING: user confirms target batch] │
│ 2. Revert Commits → git revert per commit │
│ 3. Verify Integrity → run full test suite │
│ 4. Update Jira → reset statuses to "To Do" │
│ 5. Finalize → commit + rollback_report.md │
├────────────────────────────────────────────────────────────────┤
│ Principles: Preserve history · Verify after revert │
│ Atomic rollback · Ask don't assume │
└────────────────────────────────────────────────────────────────┘
```