gps-denied-desktop/_docs/tutorial_kickstart.md

# 1 Research Phase


## 1.01 **🧑‍💻 Developers**: Problem statement
 ### Discuss
  Discuss the problem and create in the `_docs/00_problem` next files and folders:  
 - `problem_description.md`: Our problem to solve with the end result we want to achieve. 
 - `input_data`: Put to this folder all the necessary input data and expected results for the further tests. Analyze very thoroughly input data and form system's restrictions and acceptance criteria 
 - `restrictions.md`: Restrictions we have in real world in the -dashed list format.
 - `acceptance_criteria.md`: Acceptance criteria for the solution in the -dashed list format. 
   The most important part, determines how good the system should be.
 - `security_approach.md`: Security requirements and constraints for the system.

### Example:
 - `problem_description.md`
    We have wing type UAV (airplane). It should fly autonomously to predetermined GPS destination. During the flight it is relying on the signal form GPS module.  
    But when adversary jam or spoof GPS, then UAV either don't know where to fly, or fly to the wrong direction.
    So, we need to achieve that UAV can fly correctly to the destination without GPS or when GPS is spoofed. We can use the camera pointing downward and other sensor data like altitude, available form the flight controller. Airplane is running Ardupliot. 
 - `input_data`
    - orthophoto images from the UAV for the analysis
    - list of expected GPS for the centers for each picture in csv format: picture name, lat, lon
    - video from the UAV for the analysis
    - list of expected GPS for the centers of video per timeframe in csv format: timestamp, lat, lon for each 1-2 seconds
    - ...
 - `restrictions.md`
    - We're limiting our solution to airplane type UAVs.
    - Additional weight it could take is under 1 kg.
    - The whole system should cost under $2000.
    - The flying range is restricted by eastern and southern part of Ukraine. And so on.  
 - `acceptance_criteria.md`
    - UAV should fly without GPS for at least 30 km in the sunshine weather.
    - UAV should fly with maximum mistake no more than 40 meters from the real GPS
    - UAV should fly correctly with little foggy weather with maximum mistake no more than 100 meters from the real GPS
    - UAV should fly for minimum of 500 meters with missing internal Satellite maps and the drifting error should be no more than 50 meters.
 - `security_approach.md`
    - System runs on embedded platform (Jetson Orin Nano) with secure boot
    - Communication with ground station encrypted via AES-256
    - No remote API access during flight - fully autonomous
    - Firmware signing required for updates


## 1.05 **🧑‍💻 Developers**: Git Init
 ### Initialize Repository
  ```bash
  git init
  git add .
  git commit -m "Initial: problem statement and input data"
  ```
 
 ### Branching Strategy
  - `main`: Documentation and stable releases
  - `stage`: Planning phase artifacts
  - `dev`: Implementation code
 
 After research phase completion, all docs stay on `main`.
 Before planning phase, create `stage` branch.
 Before implementation phase, create `dev` branch from `stage`.
 After integration tests pass, merge `dev` → `stage` → `main`.


## 1.10 **✨AI Research**: Restrictions and Acceptance Criteria assessment
  
  ### Execute `/1.research/1.10_research_assesment_acceptance_criteria`
   In case of external DeepResearch (Gemini, DeepSeek, or other), copypaste command's text and put to the research context:
    - `problem_description.md`
    - `restrictions.md`
    - `acceptance_criteria.md`
    - `security_approach.md`
    - Samples of the input data

  ### Revise 
   - Revise the result, discuss it
   - Overwrite `acceptance_criteria.md` and `restrictions.md`

  ### Commit
   ```bash
   git add _docs/00_problem/
   git commit -m "Research: acceptance criteria and restrictions assessed"
   ```
 

## 1.20 **🤖✨AI Research**: Research the problem in great detail

  ### Execute `/1.research/1.20_research_problem`
   In case of external DeepResearch (Gemini, DeepSeek, or other), copypaste command's text and put to the research context:
    - `problem_description.md`
    - `restrictions.md`
    - `acceptance_criteria.md`
    - `security_approach.md`
    - Samples of the input data
  
  ### Revise 
   - Revise the result from AI.
   - Research the problem as well
   - Add/modify/remove some solution details in the draft. (Also with AI)
   - Store it to the `_docs/01_solution/solution_draft.md`


## 1.30 **🤖✨AI Research**: Solution draft assessment
  
  ### Execute `/1.research/1.30_solution_draft_assessment`
   In case of external DeepResearch (Gemini, DeepSeek, or other), copypaste command's text and put to the research context:
    - `problem_description.md`
    - `restrictions.md`
    - `acceptance_criteria.md`
    - `security_approach.md`
    - Samples of the input data
  
  ### Revise
  - Research by yourself as well - how to solve additional problems which AI figured out, and add them to the result.
  
  ### Iterate
  - Rename previous `solution_draft.md` to `{xx}_solution_draft.md`. Start {xx} from 01
  - Store the new revised result draft to the `_docs/01_solution/solution_draft.md`
  - Repeat the process 1.30 from the beginning
  
  When the next solution wouldn't differ much from the previous one, or become actually worse, store the last draft as `_docs/01_solution/solution.md`


## 1.35 **🤖📋AI plan**: Tech Stack Selection

  ### Execute `/1.research/1.35_tech_stack_selection`

  ### Revise
   - Review technology choices against requirements
   - Consider team expertise and learning curve
   - Document trade-offs and alternatives considered

  ### Store
   - Save output to `_docs/01_solution/tech_stack.md`


## 1.40 **🤖✨AI Research**: Security Research

  ### Execute `/1.research/1.40_security_research`

  ### Revise
   - Review security approach against solution architecture
   - Update `security_approach.md` with specific requirements per component

  ### Quality Gate: Research Complete
  Review `@_docs/00_templates/quality_gates.md` - Gate 1

  ### Commit
   ```bash
   git add _docs/
   git commit -m "Research: solution and security finalized"
   ```


# 2. Planning phase

> **Note**: If implementation reveals architectural issues, return to Planning phase to revise components.


## 2.05 **🧑‍💻 Developers**: Create stage branch
  ```bash
  git checkout -b stage
  ```


## 2.10 **🤖📋AI plan**: Generate components

   ### Execute `/2.planning/2.10_plan_components`

   ### Revise 
      - Revise the plan, answer questions, put detailed descriptions
      - Make sure stored components are coherent and make sense
  
   ### Store plan
      - Save plan to `_docs/02_components/00_decomposition_plan.md`


## 2.15 **🤖📋AI plan**: Components assessment

   ### Execute `/2.planning/2.15_plan_asses_components`

   ### Revise 
      - Clarify the proposals and ask to fix found issues


## 2.17 **🤖📋AI plan**: Security Check

   ### Execute `/2.planning/2.17_plan_security_check`

   ### Revise
      - Review security considerations for each component
      - Ensure security requirements from 1.40 are addressed
  

## 2.20 **🤖AI agent**: Generate Jira Epics
  
   ### Jira MCP
   Add Jira MCP to the list in IDE:
   ```
   "Jira-MCP-Server": {
      "url": "https://mcp.atlassian.com/v1/sse"
   }
   ```
   ### Execute `/2.planning/2.20_plan_jira_epics`
  
   ### Revise 
      - Revise the epics, answer questions, put detailed descriptions
      - Make sure epics are coherent and make sense


## 2.22 **🤖📋AI plan**: Data Model Design

   ### Execute `/2.planning/2.22_plan_data_model`

   ### Revise 
      - Review entity relationships
      - Verify data access patterns
      - Check migration strategy
  
   ### Store
      - Save output to `_docs/02_components/data_model.md`


## 2.25 **🤖📋AI plan**: API Contracts Design

   ### Execute `/2.planning/2.25_plan_api_contracts`

   ### Revise 
      - Review interface definitions
      - Verify error handling standards
      - Check versioning strategy
  
   ### Store
      - Save output to `_docs/02_components/api_contracts.md`
      - Save OpenAPI spec to `_docs/02_components/openapi.yaml` (if applicable)


## 2.30 **🤖📋AI plan**: Generate tests
  
   ### Execute `/2.planning/2.30_plan_tests`

   ### Revise 
      - Revise the tests, answer questions, put detailed descriptions
      - Make sure stored tests are coherent and make sense


## 2.35 **🤖📋AI plan**: Risk Assessment

   ### Execute `/2.planning/2.37_plan_risk_assessment`

   ### Revise 
      - Review identified risks
      - Verify mitigation strategies
      - Set up risk monitoring
  
   ### Store
      - Save output to `_docs/02_components/risk_assessment.md`


## 2.40 **🤖📋AI plan**: Component Decomposition To Features
   ### Execute
   For each component in `_docs/02_components` run 
   `/2.planning/2.40_plan_features_decompose --component @xx__spec_[component_name].md`

   ### Revise 
      - Revise the features, answer questions, put detailed descriptions
      - Make sure features are coherent and make sense

   ### Quality Gate: Planning Complete
   Review `@_docs/00_templates/quality_gates.md` - Gate 2

   ### Commit
   ```bash
   git add _docs/
   git commit -m "Planning: components, tests, and features defined"
   ```



# 3. Implementation phase


## 3.05 **🤖📋AI plan**: Initial structure

   ### Create dev branch
   ```bash
   git checkout -b dev
   ```

   ### Context7 MCP
   Add context7 MCP to the list in IDE:
   ```
   "context7": {
      "command": "npx",
      "args": [
        "-y",
        "@upstash/context7-mcp"
      ]
    }
   ```
  
   ### Execute: `/3.implementation/3.05_implement_initial_structure`
   
   This will create:
   - Project structure with CI/CD pipeline
   - Environment configurations (see `@_docs/00_templates/environment_strategy.md`)
   - Database migrations setup
   - Test infrastructure
  
   ### Review Plan
      - Analyze the proposals, answer questions
      - Improve plan as much as possible so it would be clear what exactly to do
   
   ### Save Plan
   - when plan is final and ready, save it as `_docs/02_components/structure_plan.md`

   ### Execute Plan
      - Press build and let AI generate the structure

   ### Revise Code
    - Read the code and check that everything is ok
   

## 3.10 **🤖📋AI plan**: Feature implementation
   ### Execute
   For each component in `_docs/02_components` run
   `/3.implementation/3.10_implement_component @component_folder`
  
   ### Revise Plan
      - Analyze the proposed development plan in a great detail, provide all necessary information
      - Possibly reorganize plan if needed, think and add more input constraints if needed
      - Improve plan as much as possible so it would be clear what exactly to do
  
  ### Save Plan
   - when plan is final and ready, save it as `[##]._plan_[component_name]` to component's folder
  
   ### Execute Plan
      - Press build and let AI generate the code

   ### Revise Code
      - Read the code and check that everything is ok


## 3.20 **🤖📋AI plan**: Code Review

   ### Execute `/3.implementation/3.20_implement_code_review`
   
   Can also use Cursor's built-in review feature.

   ### Revise
      - Address all found issues
      - Ensure code quality standards are met

   
## 3.30 **🤖📋AI plan**: CI/CD Validation

 ### Execute `/3.implementation/3.30_implement_cicd`
 
 ### Revise 
   - Review pipeline configuration
   - Verify all quality gates are enforced
   - Ensure all stages are properly configured


## 3.35 **🤖📋AI plan**: Deployment Strategy

 ### Execute `/3.implementation/3.35_plan_deployment`
 
 ### Revise 
   - Review deployment procedures per environment
   - Verify rollback procedures documented
   - Ensure health checks configured

 ### Store
   - Save output to `_docs/02_components/deployment_strategy.md`


## 3.40 **🤖📋AI plan**: Integration tests and solution checks

 ### Execute `/3.implementation/3.40_implement_tests`
 
 ### Revise 
   - Revise the plan, answer questions, put detailed descriptions
   - Make sure tests are coherent and make sense


## 3.42 **🤖📋AI plan**: Observability Setup

 ### Execute `/3.implementation/3.42_plan_observability`
 
 ### Revise 
   - Review logging strategy
   - Verify metrics and alerting
   - Check dashboard configuration

 ### Store
   - Save output to `_docs/02_components/observability_plan.md`


## 3.45 **🧑‍💻 Developer**: Final Quality Gate

 ### Quality Gate: Implementation Complete
 Review `@_docs/00_templates/quality_gates.md` - Gate 3

 ### Checklist
 - [ ] All components implemented
 - [ ] Code coverage >= 75%
 - [ ] All tests pass
 - [ ] Code review approved
 - [ ] CI/CD pipeline green
 - [ ] Deployment tested on staging
 - [ ] Observability configured

 ### Merge after tests pass
 ```bash
 git checkout stage
 git merge dev
 git checkout main
 git merge stage
 git push origin main
 ```


## 3.50 **🧑‍💻 Developer**: Post-Implementation

 ### Documentation
 - [ ] Update README with final setup instructions
 - [ ] Create/update runbooks using `@_docs/00_templates/incident_playbook.md`
 - [ ] Document rollback procedures using `@_docs/00_templates/rollback_strategy.md`

 ### Handoff
 - [ ] Stakeholders notified of completion
 - [ ] Operations team briefed on monitoring
 - [ ] Support documentation complete