stack/AGENTS.md

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 scripts/agent/session-start.sh
bash scripts/agent/critical.sh
bash scripts/agent/session-end.sh

Optional:

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

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