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)

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)

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

# 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

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

# 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

docker compose logs [service] --tail=100
docker compose restart [service]

Git Push Rejected

git pull --rebase origin main
git push