devplatform/QUICK_REFERENCE.md

# ClearGrow Quick Reference

## Slash Commands

### Firmware Commands (`/firmware:*`)

| Command | Description | Usage |
|---------|-------------|-------|
| `/build-controller` | Build ESP32-S3 controller firmware | `/build-controller` |
| `/build-probe` | Build nRF52840 probe firmware | `/build-probe [board]` |
| `/flash-controller` | Flash controller to device | `/flash-controller [port]` |
| `/flash-probe` | Flash probe via J-Link | `/flash-probe` |
| `/test-controller` | Run controller unit tests | `/test-controller` |
| `/test-probe` | Run probe unit tests | `/test-probe` |

### Git Commands (`/git:*`)

| Command | Description | Usage |
|---------|-------------|-------|
| `/status` | Show status of all repos | `/status` |
| `/commit` | Create commit with issue link | `/commit CG-123 "Fix bug"` |
| `/push` | Push to Gitea | `/push [branch]` |
| `/pull` | Pull from Gitea | `/pull` |
| `/branch` | Create feature branch | `/branch CG-123 feature-name` |
| `/pr` | Create pull request | `/pr "PR title"` |

### Platform Commands (`/platform:*`)

| Command | Description | Usage |
|---------|-------------|-------|
| `/health` | Check all service health | `/health` |
| `/logs` | View service logs | `/logs [service]` |
| `/restart` | Restart a service | `/restart [service]` |
| `/backup` | Run platform backup | `/backup` |
| `/disk` | Check disk usage | `/disk` |

### Issue Commands (`/issues:*`)

| Command | Description | Usage |
|---------|-------------|-------|
| `/list` | List issues by state | `/list [state]` |
| `/view` | View issue details | `/view CG-123` |
| `/comment` | Add comment to issue | `/comment CG-123 "text"` |
| `/transition` | Change issue state | `/transition CG-123 Done` |
| `/create` | Create new issue | `/create "Summary"` |
| `/start` | Start work on issue | `/start CG-123` |

---

## Sub-Agents

| Agent | Purpose | Invoke With |
|-------|---------|-------------|
| `controller-dev` | ESP32-S3 firmware development | "Use controller-dev agent to..." |
| `probe-dev` | nRF52840 firmware development | "Use probe-dev agent to..." |
| `docs-writer` | Technical documentation | "Use docs-writer agent to..." |
| `code-reviewer` | Code review and quality | "Use code-reviewer agent to..." |
| `devops` | Platform infrastructure | "Use devops agent to..." |
| `test-runner` | Test automation | "Use test-runner agent to..." |

---

## Skills (Auto-invoked)

| Skill | Triggers |
|-------|----------|
| `esp-idf` | ESP-IDF, ESP32, FreeRTOS, controller firmware |
| `zephyr` | Zephyr, nRF52840, probe firmware |
| `documentation` | docs, documentation, writing guides |
| `devplatform` | Docker, Gitea, YouTrack, TeamCity |

---

## Common Build Commands

### Controller (ESP-IDF)
```bash
cd /opt/repos/controller
source ~/esp/esp-idf/export.sh
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor
idf.py size-components
```

### Probe (Zephyr)
```bash
cd /opt/repos/probe
west build -b nrf52840dk_nrf52840
west flash
west debug
```

---

## Platform URLs

| Service | URL |
|---------|-----|
| Gitea | https://git.cleargrow.io |
| YouTrack | https://track.cleargrow.io |
| TeamCity | https://ci.cleargrow.io |

---

## Git Workflow

```bash
# Start feature
git checkout main && git pull
git checkout -b feature/CG-123-description

# Work and commit
git add .
git commit -m "Add feature CG-123"

# Push and create PR
git push -u origin feature/CG-123-description
```

### Commit Message Format
```
<verb> <description> CG-XXX [#state]

Examples:
Fix sensor parsing CG-123
Add temperature calibration CG-124 #fixed
Update API documentation CG-125
```

---

## YouTrack Issue States

```
Backlog → Ready → In Progress → Verify → Document → Review → Done
                      ↓
                   Triage (on failure)
```

---

## Repository Paths

| Repo | Path | Tech |
|------|------|------|
| Controller | `/opt/repos/controller` | ESP-IDF (C) |
| Probe | `/opt/repos/probe` | Zephyr (C) |
| Docs | `/opt/repos/docs` | Markdown |
| DevPlatform | `/opt/devplatform` | Docker |

---

## Useful Docker Commands

```bash
cd /opt/devplatform

# Service management
docker compose up -d
docker compose down
docker compose restart [service]
docker compose logs -f [service]

# Health check
docker compose ps
./scripts/healthcheck.sh

# Backup
./scripts/backup.sh
```

---

## Environment Variables

```bash
# YouTrack API
export YOUTRACK_TOKEN="perm:xxx"

# Gitea API
export GITEA_TOKEN="xxx"
```

---

## Troubleshooting

### Build Fails
- Controller: Check `source ~/esp/esp-idf/export.sh`
- Probe: Check `west update` was run

### Service Down
```bash
docker compose logs [service] --tail=100
docker compose restart [service]
```

### Git Push Rejected
```bash
git pull --rebase origin main
git push
```