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>
This commit is contained in:
93
docs/mission.md
Normal file
93
docs/mission.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# ClaudeTools — Mission & Product Direction
|
||||
|
||||
## Mission
|
||||
|
||||
ClaudeTools is the internal operations platform for Arizona Computer Guru LLC. It tracks client work, billable time, infrastructure inventory, and encrypted credentials — and it provides a real-time coordination layer so that multiple Claude Code sessions (running on different machines or by different team members) can work in parallel without stepping on each other. It is built to support a 2-person MSP that uses AI-assisted workflows as a core part of how work gets done.
|
||||
|
||||
---
|
||||
|
||||
## Target User
|
||||
|
||||
**Primary:** Mike Swanson and Howard Enos — the two team members at Arizona Computer Guru LLC. They use Claude Code sessions throughout the day to handle client work, MSP tooling development, and infrastructure operations. ClaudeTools gives those sessions a shared source of truth.
|
||||
|
||||
**Claude Code sessions themselves** are also first-class consumers of the API — particularly the coordination subsystem, which sessions query at startup and before writing to any shared resource.
|
||||
|
||||
There is no external user base. This is internal infrastructure.
|
||||
|
||||
---
|
||||
|
||||
## Current Scope (what it does today)
|
||||
|
||||
**Work tracking:**
|
||||
- Client management (`/api/clients`)
|
||||
- Project tracking (`/api/projects`)
|
||||
- Work session logging (`/api/sessions`)
|
||||
- Billable time entries with rate and amount (`/api/billable-time`)
|
||||
- Work items and task management (`/api/work-items`, `/api/tasks`)
|
||||
- Tagging system across entities (`/api/tags`)
|
||||
|
||||
**Infrastructure inventory:**
|
||||
- Machine inventory (`/api/machines`)
|
||||
- Physical sites (`/api/sites`)
|
||||
- IT assets/infrastructure (`/api/infrastructure`)
|
||||
- Application services (`/api/services`)
|
||||
- Network configurations (`/api/networks`)
|
||||
- Firewall rule documentation (`/api/firewall-rules`)
|
||||
- M365 tenant records (`/api/m365-tenants`)
|
||||
|
||||
**Credential management:**
|
||||
- Encrypted credential storage (AES-256-GCM) for client and service credentials (`/api/credentials`)
|
||||
- Immutable audit log of all credential access (`/api/credential-audit-logs`)
|
||||
- Security incident tracking (`/api/security-incidents`)
|
||||
|
||||
**Authentication:**
|
||||
- JWT-based auth with Argon2 password hashing (`/api/auth/token`)
|
||||
|
||||
**Coordination subsystem (`/api/coord`):**
|
||||
- Component state tracking per project (GuruRMM, ClaudeTools, Dataforth, client work)
|
||||
- Work locks: sessions claim a lock on a resource before writing; TTL-based auto-release
|
||||
- Inter-session messaging: one Claude session can leave a note for another (e.g., "I left the server mid-deploy")
|
||||
- No auth required — internal LAN only
|
||||
|
||||
**MCP integration:**
|
||||
- `mcp-servers/feature-management/` — GuruRMM feature request tracking, accessible from Claude Code via MCP
|
||||
|
||||
---
|
||||
|
||||
## Near-Term Roadmap
|
||||
|
||||
- Auto-deploy via Gitea webhook (planned, not yet active)
|
||||
- Optional Phase 7 extensions (all low-priority):
|
||||
- File Changes API — track file modifications over time
|
||||
- Command Runs API — command execution history
|
||||
- Problem Solutions API — internal knowledge base
|
||||
- Failure Patterns API — error pattern recognition
|
||||
- Environmental Insights API — contextual learning across sessions
|
||||
|
||||
The API is considered feature-complete for current operational needs. New endpoints are added only when a specific workflow gap appears.
|
||||
|
||||
---
|
||||
|
||||
## Explicit Non-Goals
|
||||
|
||||
- **Not a PSA replacement** — ClaudeTools tracks work for internal record-keeping. Syncro PSA handles client-facing ticketing and invoicing; the two are separate.
|
||||
- **Not a multi-tenant SaaS product** — single-tenant, self-hosted on ACG infrastructure. No plans to expose this to external users or clients.
|
||||
- **Not a monitoring platform** — GuruRMM handles endpoint monitoring. ClaudeTools tracks the work done in response to what monitoring surfaces.
|
||||
- **No external credential access UI** — credentials stored in ClaudeTools are accessed via API by Claude Code sessions. There is no web UI for browsing credentials.
|
||||
- **No hardcoded credentials anywhere** — all secrets go through SOPS vault (primary) or 1Password (fallback). This is a non-negotiable constraint, not a goal to eventually achieve.
|
||||
|
||||
---
|
||||
|
||||
## Design Principles
|
||||
|
||||
**Coordination is first-class** — the coord API is not an afterthought. Multi-session, multi-machine Claude Code workflows are the normal operating mode, and the platform is built around making that safe.
|
||||
|
||||
**Claude sessions are API consumers** — the API is designed so that Claude Code can call it directly without human-in-the-loop for reads and non-destructive writes. The coord API in particular is designed for machine callers, not humans.
|
||||
|
||||
**Credentials never leave the vault unencrypted** — every credential stored via the API is AES-256-GCM encrypted at the service layer before hitting the database. Audit logs are immutable and automatic.
|
||||
|
||||
**Softfail over hard-fail** — if the coord API is unreachable, sessions queue their calls to `.claude/coord-queue.jsonl` and continue working. The platform degrades gracefully.
|
||||
|
||||
**Internal-only, LAN-scoped** — the coordination API has no authentication because it is network-scoped to 172.16.3.x. External exposure would require adding auth first.
|
||||
|
||||
**Two users, real workflows** — features are added when a real operational gap appears, not speculatively. The Phase 7 extensions are listed but not prioritized until a specific need arises.
|
||||
137
docs/tech-stack.md
Normal file
137
docs/tech-stack.md
Normal file
@@ -0,0 +1,137 @@
|
||||
# ClaudeTools API — Tech Stack
|
||||
|
||||
## Purpose
|
||||
|
||||
ClaudeTools is an MSP work-tracking and internal tooling platform built by Arizona Computer Guru LLC. It provides a REST API for tracking clients, projects, work sessions, billable time, infrastructure inventory, and encrypted credentials — plus a real-time coordination subsystem that multiple Claude Code sessions use to avoid clobbering each other. The API is production-stable with 95+ endpoints and 38 database tables.
|
||||
|
||||
---
|
||||
|
||||
## Components
|
||||
|
||||
### API Server
|
||||
|
||||
- **Framework:** Python, FastAPI
|
||||
- **ASGI server:** Uvicorn
|
||||
- **ORM/query layer:** SQLAlchemy (models in `api/models/`), Pydantic schemas (in `api/schemas/`)
|
||||
- **Host:** 172.16.3.30, port 8001 (production)
|
||||
- **Deployment:** <!-- TODO: verify — systemd unit or direct process? auto-deploy via Gitea webhook is planned but not confirmed active -->
|
||||
- **OpenAPI docs:** http://172.16.3.30:8001/api/docs (also `http://localhost:8000/api/docs` in dev)
|
||||
- **Repo path:** `api/` directory in `azcomputerguru/claudetools` on Gitea (http://172.16.3.20:3000)
|
||||
|
||||
**Repo layout:**
|
||||
```
|
||||
api/
|
||||
├── main.py # Entry point
|
||||
├── models/ # SQLAlchemy models (38 tables)
|
||||
├── routers/ # Endpoint handlers (95+ endpoints across ~10 router files)
|
||||
├── schemas/ # Pydantic request/response schemas
|
||||
├── services/ # Business logic layer
|
||||
├── middleware/ # Auth and error handling
|
||||
└── utils/ # Crypto utilities (AES-256-GCM)
|
||||
```
|
||||
|
||||
Key endpoint groups:
|
||||
- `/api/machines`, `/api/clients`, `/api/projects`, `/api/sessions`, `/api/tags` — core entities
|
||||
- `/api/work-items`, `/api/tasks`, `/api/billable-time` — MSP work tracking
|
||||
- `/api/sites`, `/api/infrastructure`, `/api/services`, `/api/networks`, `/api/firewall-rules`, `/api/m365-tenants` — infrastructure inventory
|
||||
- `/api/credentials`, `/api/credential-audit-logs`, `/api/security-incidents` — encrypted credential storage and audit
|
||||
- `/api/auth/token` — JWT issuance
|
||||
- `/api/coord/*` — coordination subsystem (no auth required; see below)
|
||||
|
||||
---
|
||||
|
||||
### Database
|
||||
|
||||
- **Engine:** MariaDB 10.6.22
|
||||
- **Host:** 172.16.3.30:3306, database `claudetools`
|
||||
- **Tables:** 38 (as of last audit)
|
||||
- **Sensitive field encryption:** AES-256-GCM (Fernet) — applied at the service layer before write, decrypted on read. Credential passwords are the primary encrypted fields.
|
||||
- **Audit logging:** All credential read/write operations logged to `credential_audit_logs` table automatically.
|
||||
- **Migration approach:** Alembic. Migrations in `migrations/` directory. Commands: `alembic current`, `alembic upgrade head`.
|
||||
- **Credentials:** Stored in SOPS vault at `projects/claudetools/database.sops.yaml`. Retrieve with:
|
||||
```bash
|
||||
bash $CLAUDETOOLS_ROOT/.claude/scripts/vault.sh get-field projects/claudetools/database.sops.yaml credentials.password
|
||||
```
|
||||
1Password fallback: `op read "op://Projects/ClaudeTools Database/password"`
|
||||
|
||||
---
|
||||
|
||||
### Authentication
|
||||
|
||||
- **Mechanism:** JWT tokens issued by `POST /api/auth/token` (email + password)
|
||||
- **Password hashing:** Argon2
|
||||
- **API key encryption:** AES-256-GCM (Fernet) applied to stored credential values
|
||||
- **Coordination API:** No auth required — it is an internal-network-only subsystem
|
||||
|
||||
---
|
||||
|
||||
### Coordination Subsystem (`/api/coord`)
|
||||
|
||||
The coordination API is a first-class subsystem used by all Claude Code sessions (across machines and users) to prevent concurrent writes to the same resource. It requires no authentication and is intended for internal LAN use only.
|
||||
|
||||
Key endpoints:
|
||||
- `GET /api/coord/status` — current component states for all projects
|
||||
- `GET /api/coord/messages` — inter-session messages (filtered by `to_session`, `unread_only`)
|
||||
- `PUT /api/coord/messages/<id>/read` — mark message read
|
||||
- `POST /api/coord/locks` — claim a work lock on a resource (with TTL)
|
||||
- `DELETE /api/coord/locks/<id>` — release a lock
|
||||
- `PUT /api/coord/components/<project_key>/<component>` — update component state
|
||||
|
||||
Project keys: `gururmm`, `claudetools`, `dataforth-dos`, `clients/<name>`
|
||||
|
||||
Component states tracked per project:
|
||||
- `gururmm`: `server`, `agents`, `dashboard`, `db_migrations` — states: `building`, `built`, `deploying`, `deployed`, `degraded`
|
||||
- `claudetools`: `api`, `db_migrations`, `coord_api` — states: `deploying`, `deployed`, `degraded`
|
||||
|
||||
Softfail behavior: if the coord API is unreachable, sessions log failed calls to `.claude/coord-queue.jsonl` and drain on next `/sync`.
|
||||
|
||||
---
|
||||
|
||||
### Build / Deploy Pipeline
|
||||
|
||||
- **Trigger:** Gitea webhook on push to main — auto-deploy is planned but not confirmed active <!-- TODO: verify current deploy mechanism -->
|
||||
- **Dev start:**
|
||||
```bash
|
||||
api\venv\Scripts\activate
|
||||
uvicorn api.main:app --reload --host 0.0.0.0 --port 8000
|
||||
```
|
||||
- **Environment:** `.env` file for local dev; production environment variables managed separately
|
||||
|
||||
---
|
||||
|
||||
### MCP Servers
|
||||
|
||||
Custom MCP servers live in `mcp-servers/`:
|
||||
- `mcp-servers/feature-management/` — feature tracking MCP server (used by Claude Code to manage GuruRMM feature requests)
|
||||
|
||||
Config: `.mcp.json` at repo root.
|
||||
|
||||
---
|
||||
|
||||
## Key Architecture Decisions
|
||||
|
||||
- **FastAPI + SQLAlchemy** — standard Python async API stack. FastAPI chosen for automatic OpenAPI generation and Pydantic validation; SQLAlchemy for ORM flexibility across 38 tables.
|
||||
- **MariaDB, not PostgreSQL** — chosen for the ClaudeTools API (GuruRMM uses PostgreSQL on the same host). Both run on 172.16.3.30.
|
||||
- **AES-256-GCM at the service layer, not the DB layer** — credentials are encrypted before write in `api/utils/`, not via DB-native encryption. Allows key rotation and audit without DB-level access.
|
||||
- **Coordination API with no auth** — deliberately unauthenticated; scoped to internal LAN. Simplifies cross-session coordination without requiring Claude sessions to manage API tokens.
|
||||
- **Alembic for migrations** — standard SQLAlchemy migration tooling; migration history tracked in DB. All schema changes go through migration files.
|
||||
- **SOPS vault for credentials** — no plaintext credentials in any checked-in file. Vault wrapper reads `vault_path` from per-machine `identity.json`; no hardcoded paths in shared files.
|
||||
- **Agents do not run code** — Claude Code coordinator delegates all DB queries, code writes, and git operations to specialized sub-agents. The coordinator only reads 1–2 files directly.
|
||||
|
||||
---
|
||||
|
||||
## Development Workflow
|
||||
|
||||
1. Changes developed locally on developer machine (Windows: `D:\claudetools`; Mac: `~/claudetools`).
|
||||
2. `api\venv\Scripts\activate` + `uvicorn api.main:app --reload` for local dev server on port 8000.
|
||||
3. DB migrations: `alembic upgrade head` — must be applied before testing new schema.
|
||||
4. Code reviewed via Code Review Agent (mandatory before merge).
|
||||
5. Push to `azcomputerguru/claudetools` on Gitea (http://172.16.3.20:3000); production deploy to 172.16.3.30:8001.
|
||||
6. Coordination API on prod (port 8001) is always-on; dev sessions can point to it directly for lock/message coordination.
|
||||
|
||||
---
|
||||
|
||||
## Current Version
|
||||
|
||||
- **API:** Production-stable, 95+ endpoints, 38 tables. No explicit version number tracked in the codebase. <!-- TODO: verify if there is a version field in main.py -->
|
||||
- **Last context update:** 2026-04-14 (CONTEXT.md timestamp)
|
||||
Reference in New Issue
Block a user