Files

Mike Swanson dd0ef45645 feat: implement agent-os standards system and feature planning tools

- Split CODING_GUIDELINES.md into 19 indexed standards files under .claude/standards/
  - 9 from CODING_GUIDELINES (conventions, powershell, security, api, git, gururmm)
  - 10 from session log tribal knowledge (syncro, ssh, gitea, python, client, gururmm)
- Add .claude/standards/index.yml for cheap relevance-based lookup
- Add /inject-standards command: load targeted standards per task instead of full guidelines
- Add /shape-spec command: pre-implementation spec for GuruRMM features (plan.md,
  shape.md, references.md, standards.md) with mandatory out-of-scope gate
- Add docs/tech-stack.md and docs/mission.md for ClaudeTools API
- Add projects/msp-tools/guru-rmm/docs/tech-stack.md and mission.md for GuruRMM
- Update CLAUDE.md commands table with /inject-standards and /shape-spec

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-16 12:59:49 -07:00

2.3 KiB

Raw Blame History

name, description, applies-to

name	description	applies-to
response-format	RESTful plural nouns, consistent error format, pagination, OpenAPI documentation	claudetools-api, gururmm

API Standards

URL structure

RESTful with plural nouns: /api/users, /api/agents, /api/clients
Nested resources for sub-items: /api/agents/:id/checks, /api/sites/:id/channel
Use kebab-case for multi-word segments: /api/policy-assignments, /api/check-results

Error format

All error responses use a consistent envelope:

{
  "detail": "Human-readable error description",
  "error_code": "MACHINE_READABLE_CODE",
  "status_code": 404
}

detail — for humans; may be shown in UI
error_code — for client code to switch on; use UPPER_SNAKE format
status_code — redundant with HTTP status but helps clients that lose the HTTP layer

Pagination

Paginate all list endpoints that can return more than ~50 items. Use cursor-based or offset-based pagination:

{
  "items": [...],
  "total": 148,
  "page": 1,
  "per_page": 25
}

Do not return unbounded arrays from production endpoints.

Documentation

Document with OpenAPI — FastAPI generates this automatically from type annotations and docstrings
For Axum/Rust endpoints, add route comments with request/response shapes until an OpenAPI generator is wired

sqlx query style (GuruRMM server)

Use sqlx::query() (runtime) not sqlx::query!() (compile-time macro) for new queries. The compile-time macro requires cargo sqlx prepare after every schema change and rebuilding the .sqlx/ cache. Runtime queries avoid this overhead.

The offline cache (server/.sqlx/) only needs updating when query!() macros change. When adding a new query, default to sqlx::query() unless there is a specific reason to use the proc macro.

Migration discipline (GuruRMM)

Never manually pre-apply migrations via psql without also recording the checksum in _sqlx_migrations — sqlx will fail on startup if it finds a missing row for a migration it doesn't recognize
Use ADD COLUMN IF NOT EXISTS in all migrations so they are idempotent
Apply migrations by letting the server binary run them on startup (sqlx::migrate!())
The correct sequence for a new migration: add SQL file → apply to DB (server startup) → cargo sqlx prepare → commit .sqlx/ → rebuild

2.3 KiB Raw Blame History