NimsForest Issue Runbook

Overview

NimsForest Issue is an issue tracking service for the NimsForest ecosystem. It provides a public web form for reporting issues, an API for programmatic access, and an admin dashboard for triage and management.

Infrastructure

• Server: issues.nimsforest.nimsforest.com
• Host: land (46.225.164.179), Docker container, port 8085
• Config: /opt/nimsforestissue/config.yaml (mounted to ~/.nimsforestissue/config.yaml)
• Data: /opt/nimsforestissue/data/ (mounted to /data)
• NATS: nats://nimsforest.nimsforest.com:4222

Health Check

curl https://issues.nimsforest.nimsforest.com/api/v1/health

API Endpoints

| Method | Path | Auth | Description | |--------|------|------|-------------| | GET /api/v1/health | none | Health check | | POST /api/v1/issues | Bearer (api) | Create issue | | GET /api/v1/issues | Bearer (api) | List issues (query: status, category, project, active_only, stage) | | GET /api/v1/issues/{id} | Bearer (api) | Get single issue | | PATCH /api/v1/issues/{id} | Bearer (api) | Update issue | | DELETE /api/v1/issues/{id} | Bearer (api) | Delete issue | | PUT /api/v1/issues/{id}/plan | Bearer (api) | Update plan text and status | | POST /api/v1/issues/{id}/comments | Bearer (api) | Add comment | | POST /api/v1/issues/{id}/nim-actions | Bearer (api) | Record agent action | | GET /api/v1/stats | Bearer (api) | Aggregate statistics | | GET /api/v1/reports/quality | Bearer (api) | Quality review report | | GET /api/v1/runbook | none | This runbook (markdown) |

Issue Lifecycle

Status

| Status | Meaning | Set by | |--------|---------|--------| | open | New issue, not yet groomed | Issue creation | | groomed | Triaged and ready for planning | groom-issues skill | | planning | Agent is writing an implementation plan | plan-issues skill | | proposed | Plan submitted for human review | plan-issues skill | | accepted | Plan approved, ready for implementation | Human via UI | | rejected | Plan rejected | Human via UI | | implementing | Agent is actively implementing the plan | next-plan skill | | done | Implementation is complete | next-plan skill | | closed | Issue closed manually | Human via UI |

Stage (shorthand filter)

| Stage | Resolves to | Used by | |-------|------------|---------| | groomable | open | groom-issues | | plannable | groomed | plan-issues | | implementable | accepted | next-plan | | active | all except done, closed | dashboards |

Wind Events

Issue events are published to Wind (NATS) as leaves:

• issue.created — new issue filed
• issue.updated — status/priority/plan changed
• issue.commented — comment added

Authentication

Two separate tokens configured in config.yaml:

• admin_token: Used for web dashboard login (session cookie)
• api_token: Used as Bearer token for API access