Jason Woltje
6521cba735
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
- Add OpenBao services to docker-compose.yml with profiles (openbao, full) - Add docker-compose.build.yml for local builds vs registry pulls - Make PostgreSQL and Valkey optional via profiles (database, cache) - Create example compose files for common deployment scenarios: - docker/docker-compose.example.turnkey.yml (all bundled) - docker/docker-compose.example.external.yml (all external) - docker/docker.example.hybrid.yml (mixed deployment) - Update documentation: - Enhance .env.example with profiles and external service examples - Update README.md with deployment mode quick starts - Add deployment scenarios to docs/OPENBAO.md - Create docker/DOCKER-COMPOSE-GUIDE.md with comprehensive guide - Clean up repository structure: - Move shell scripts to scripts/ directory - Move documentation to docs/ directory - Move docker compose examples to docker/ directory - Configure for external Authentik with internal services: - Comment out Authentik services (using external OIDC) - Comment out unused volumes for disabled services - Keep postgres, valkey, openbao as internal services This provides a flexible deployment architecture supporting turnkey, production (all external), and hybrid configurations via Docker Compose profiles. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
102 lines
3.5 KiB
Markdown
102 lines
3.5 KiB
Markdown
# AGENTS.md — Mosaic Stack
|
|
|
|
Guidelines for AI agents working on this codebase.
|
|
|
|
## Quick Start
|
|
|
|
1. Read `CLAUDE.md` for project-specific patterns
|
|
2. Check this file for workflow and context management
|
|
3. Use `TOOLS.md` patterns (if present) before fumbling with CLIs
|
|
|
|
## Context Management
|
|
|
|
Context = tokens = cost. Be smart.
|
|
|
|
| Strategy | When |
|
|
| ----------------------------- | -------------------------------------------------------------- |
|
|
| **Spawn sub-agents** | Isolated coding tasks, research, anything that can report back |
|
|
| **Batch operations** | Group related API calls, don't do one-at-a-time |
|
|
| **Check existing patterns** | Before writing new code, see how similar features were built |
|
|
| **Minimize re-reading** | Don't re-read files you just wrote |
|
|
| **Summarize before clearing** | Extract learnings to memory before context reset |
|
|
|
|
## Workflow (Non-Negotiable)
|
|
|
|
### Code Changes
|
|
|
|
```
|
|
1. Branch → git checkout -b feature/XX-description
|
|
2. Code → TDD: write test (RED), implement (GREEN), refactor
|
|
3. Test → pnpm test (must pass)
|
|
4. Push → git push origin feature/XX-description
|
|
5. PR → Create PR to develop (not main)
|
|
6. Review → Wait for approval or self-merge if authorized
|
|
7. Close → Close related issues via API
|
|
```
|
|
|
|
**Never merge directly to develop without a PR.**
|
|
|
|
### Issue Management
|
|
|
|
```bash
|
|
# Get Gitea token
|
|
TOKEN="$(jq -r '.gitea.mosaicstack.token' ~/src/jarvis-brain/credentials.json)"
|
|
|
|
# Create issue
|
|
curl -s -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
|
|
"https://git.mosaicstack.dev/api/v1/repos/mosaic/stack/issues" \
|
|
-d '{"title":"Title","body":"Description","milestone":54}'
|
|
|
|
# Close issue (REQUIRED after merge)
|
|
curl -s -X PATCH -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
|
|
"https://git.mosaicstack.dev/api/v1/repos/mosaic/stack/issues/XX" \
|
|
-d '{"state":"closed"}'
|
|
|
|
# Create PR (tea CLI works for this)
|
|
tea pulls create --repo mosaic/stack --base develop --head feature/XX-name \
|
|
--title "feat(#XX): Title" --description "Description"
|
|
```
|
|
|
|
### Commit Messages
|
|
|
|
```
|
|
<type>(#issue): Brief description
|
|
|
|
Detailed explanation if needed.
|
|
|
|
Closes #XX, #YY
|
|
```
|
|
|
|
Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
|
|
|
|
## TDD Requirements
|
|
|
|
**All code must follow TDD. This is non-negotiable.**
|
|
|
|
1. **RED** — Write failing test first
|
|
2. **GREEN** — Minimal code to pass
|
|
3. **REFACTOR** — Clean up while tests stay green
|
|
|
|
Minimum 85% coverage for new code.
|
|
|
|
## Token-Saving Tips
|
|
|
|
- **Sub-agents die after task** — their context doesn't pollute main session
|
|
- **API over CLI** when CLI needs TTY or confirmation prompts
|
|
- **One commit** with all issue numbers, not separate commits per issue
|
|
- **Don't re-read** files you just wrote
|
|
- **Batch similar operations** — create all issues at once, close all at once
|
|
|
|
## Key Files
|
|
|
|
| File | Purpose |
|
|
| ------------------------------- | ----------------------------------------- |
|
|
| `CLAUDE.md` | Project overview, tech stack, conventions |
|
|
| `CONTRIBUTING.md` | Human contributor guide |
|
|
| `apps/api/prisma/schema.prisma` | Database schema |
|
|
| `docs/` | Architecture and setup docs |
|
|
|
|
---
|
|
|
|
_Model-agnostic. Works for Claude, MiniMax, GPT, Llama, etc._
|