Jason Woltje
bf299bb672
Co-authored-by: Jason Woltje <jason@diversecanvas.com> Co-committed-by: Jason Woltje <jason@diversecanvas.com>
83 lines
2.7 KiB
Markdown
83 lines
2.7 KiB
Markdown
# Mosaic Stack — Agent Guidelines
|
|
|
|
## Load Order
|
|
|
|
1. `SOUL.md` (repo identity + behavior invariants)
|
|
2. `~/.config/mosaic/STANDARDS.md` (machine-wide standards rails)
|
|
3. `AGENTS.md` (repo-specific overlay)
|
|
4. `.mosaic/repo-hooks.sh` (repo lifecycle hooks)
|
|
|
|
## Runtime Contract
|
|
|
|
- This file is authoritative for repo-local operations.
|
|
- `CLAUDE.md` is a compatibility pointer to `AGENTS.md`.
|
|
- Follow universal rails from `~/.config/mosaic/guides/` and `~/.config/mosaic/rails/`.
|
|
|
|
## Session Lifecycle
|
|
|
|
```bash
|
|
bash scripts/agent/session-start.sh
|
|
bash scripts/agent/critical.sh
|
|
bash scripts/agent/session-end.sh
|
|
```
|
|
|
|
Optional:
|
|
|
|
```bash
|
|
bash scripts/agent/log-limitation.sh "Short Name"
|
|
bash scripts/agent/orchestrator-daemon.sh status
|
|
bash scripts/agent/orchestrator-events.sh recent --limit 50
|
|
```
|
|
|
|
## Repo Context
|
|
|
|
- Platform: multi-tenant personal assistant stack
|
|
- Monorepo: `pnpm` workspaces + Turborepo
|
|
- Core apps: `apps/api` (NestJS), `apps/web` (Next.js), orchestrator/coordinator services
|
|
- Infrastructure: Docker Compose + PostgreSQL + Valkey + Authentik
|
|
|
|
## Quick Command Set
|
|
|
|
```bash
|
|
pnpm install
|
|
pnpm dev
|
|
pnpm test
|
|
pnpm lint
|
|
pnpm build
|
|
```
|
|
|
|
## Versioning Protocol (HARD GATE)
|
|
|
|
**This project is ALPHA. All versions MUST be `0.0.x`.**
|
|
|
|
- The `0.1.0` release is FORBIDDEN until Jason explicitly authorizes it.
|
|
- Every milestone bump increments the patch: `0.0.20` → `0.0.21` → `0.0.22`, etc.
|
|
- ALL package.json files in the monorepo MUST stay in sync at the same version.
|
|
- Use `scripts/version-bump.sh <version>` to bump — it enforces the alpha constraint and updates all packages atomically.
|
|
- The script rejects any version >= `0.1.0`.
|
|
- When creating a release tag, the tag MUST match the package version: `v0.0.x`.
|
|
|
|
**Milestone-to-version mapping** is defined in the PRD (`docs/PRD.md`) under "Delivery/Milestone Intent". Agents MUST use the version from that table when tagging a milestone release.
|
|
|
|
**Violation of this protocol is a blocking error.** If an agent attempts to set a version >= `0.1.0`, stop and escalate.
|
|
|
|
## Standards and Quality
|
|
|
|
- Enforce strict typing and no unsafe shortcuts.
|
|
- Keep lint/typecheck/tests green before completion.
|
|
- Prefer small, focused commits and clear change descriptions.
|
|
|
|
## App-Specific Overlays
|
|
|
|
- `apps/api/AGENTS.md`
|
|
- `apps/web/AGENTS.md`
|
|
- `apps/coordinator/AGENTS.md`
|
|
- `apps/orchestrator/AGENTS.md`
|
|
|
|
## Additional Guidance
|
|
|
|
- Orchestrator guidance: `docs/claude/orchestrator.md`
|
|
- Security remediation context: `docs/reports/codebase-review-2026-02-05/01-security-review.md`
|
|
- Code quality context: `docs/reports/codebase-review-2026-02-05/02-code-quality-review.md`
|
|
- QA context: `docs/reports/codebase-review-2026-02-05/03-qa-test-coverage.md`
|