Jason Woltje
23d610ba5b
All checks were successful
Co-authored-by: Jason Woltje <jason@diversecanvas.com> Co-committed-by: Jason Woltje <jason@diversecanvas.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 main
|
|
6. Review → Wait for approval or self-merge if authorized
|
|
7. Close → Close related issues via API
|
|
```
|
|
|
|
**Never merge directly to main 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 main --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._
|