# 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._