bootstrap/AGENTS.md

# Mosaic Global Agent Standards

This is the universal agent configuration file for the Mosaic framework.
It applies to ALL agent sessions regardless of runtime (Claude, Codex, OpenCode, etc.).

Canonical location: `~/.config/mosaic/AGENTS.md`

## MANDATORY — Read Before Any Response

BEFORE responding to any user message, READ these files in order:

1. `~/.config/mosaic/SOUL.md` (identity and behavioral contract)
2. `~/.config/mosaic/STANDARDS.md` (machine-wide standards)
3. Project-local `AGENTS.md` (project operations and workflows)

Do NOT respond to the user until you have loaded all three.

---

# Memory Files and Data Retention

## Claude memory
- You MUST save memory and learned information in the ~/.config/mosaic/memory dir
- You MUST never save information into the Claude-native memory files
- Learned information MUST be shared with other agents via the ~/.config/mosaic/memory dir

---

# Universal Development Standards

## Core Principles
- Think critically. Don't just agree—suggest better approaches when appropriate.
- Quality over speed. No workarounds; implement proper solutions.
- No deprecated or unsupported packages.

## Skills System

**Skills are available in `~/.config/mosaic/skills/`.** Skills are instruction packages that provide domain expertise from `mosaic/agent-skills` plus local Mosaic skills.

**Load a skill by reading its SKILL.md:**
```
Read ~/.config/mosaic/skills/<skill-name>/SKILL.md
```

### Skill Dispatch Table — Load the right skills for your task

| Task Type | Skills to Load | Notes |
|-----------|---------------|-------|
| **NestJS development** | `nestjs-best-practices` | 40 rules, 10 categories |
| **Next.js / React** | `next-best-practices`, `vercel-react-best-practices` | RSC, async, performance |
| **React components** | `vercel-composition-patterns`, `shadcn-ui` | shadcn note: uses Tailwind v4 |
| **Vue / Nuxt** | `vue-best-practices`, `nuxt`, `pinia`, `vue-router-best-practices` | antfu conventions |
| **Vite / Vitest** | `vite`, `vitest` | Build + test tooling |
| **FastAPI / Python** | `fastapi`, `python-performance-optimization` | Pydantic v2, async SQLAlchemy |
| **Architecture** | `architecture-patterns` | Clean, Hexagonal, DDD |
| **Authentication** | `better-auth-best-practices`, `email-and-password-best-practices`, `two-factor-authentication-best-practices` | Better-Auth patterns |
| **UI / Styling** | `tailwind-design-system`, `ui-animation`, `web-design-guidelines` | Tailwind v4 |
| **Frontend design** | `frontend-design`, `brand-guidelines`, `canvas-design` | Design principles |
| **TDD / Testing** | `test-driven-development`, `webapp-testing`, `vue-testing-best-practices` | Red-Green-Refactor |
| **Linting** | `lint` | Zero-tolerance — detect linter, fix ALL violations, never disable rules |
| **Code review** | `pr-reviewer`, `code-review-excellence`, `verification-before-completion` | Platform-aware (Gitea/GitHub) |
| **Debugging** | `systematic-debugging` | Structured methodology |
| **Git workflow** | `finishing-a-development-branch`, `using-git-worktrees` | Branch + worktree patterns |
| **Document generation** | `pdf`, `docx`, `pptx`, `xlsx` | LibreOffice-based |
| **Writing / Comms** | `doc-coauthoring`, `internal-comms`, `copywriting`, `copy-editing` | |
| **Marketing** | `marketing-ideas`, `content-strategy`, `social-content`, `email-sequence` | 139 ideas across 14 categories |
| **SEO** | `seo-audit`, `programmatic-seo`, `schema-markup` | Technical + content SEO |
| **CRO / Conversion** | `page-cro`, `form-cro`, `signup-flow-cro`, `onboarding-cro` | Conversion optimization |
| **Pricing / Business** | `pricing-strategy`, `launch-strategy`, `competitor-alternatives` | SaaS focus |
| **Ads / Growth** | `paid-ads`, `analytics-tracking`, `ab-test-setup`, `referral-program` | |
| **Agent building** | `create-agent`, `ai-sdk`, `proactive-agent`, `dispatching-parallel-agents` | WAL Protocol, parallel workers |
| **Agent workflow** | `executing-plans`, `writing-plans`, `brainstorming` | Plan → execute |
| **Skill authoring** | `writing-skills`, `skill-creator` | TDD-based skill creation |
| **MCP servers** | `mcp-builder` | Model Context Protocol |
| **Generative art** | `algorithmic-art`, `theme-factory`, `slack-gif-creator` | |
| **Web artifacts** | `web-artifacts-builder` | Self-contained HTML |
| **CI/CD setup** | `setup-cicd` | Docker build/push pipeline |
| **Jarvis Brain** | `jarvis` | Brain repo context |
| **PRD creation** | `prd` | Generate PRDs |
| **Ralph development** | `ralph` | Autonomous dev agent |
| **Orchestration** | `kickstart` | `/kickstart [milestone\|issue\|task]` — launches orchestrator |

### For Orchestrator / Programmatic Workers

When spawning workers, include skill loading in the kickstart:
```bash
claude -p "Read ~/.config/mosaic/skills/nestjs-best-practices/SKILL.md then implement..."
codex exec "Read ~/.config/mosaic/skills/nestjs-best-practices/SKILL.md then implement..."
```

For Ralph prd.json stories, add a `skills` field:
```json
{ "id": "US-001", "skills": ["nestjs-best-practices", "test-driven-development"], ... }
```

### Fresh Machine Setup
```bash
npx skills add https://git.mosaicstack.dev/mosaic/agent-skills.git --agent claude-code
```

## Ralph Autonomous Development

For autonomous feature development, use the Ralph pattern. Each iteration is a fresh context with persistent memory.

### The Ralph Loop
```
1. Read prd.json → Find highest priority story where passes: false
2. Read progress.txt → Check "Codebase Patterns" section first
3. Read AGENTS.md files → Check directory-specific patterns
4. Implement ONLY the single assigned story
5. Run quality checks (typecheck, lint, test)
6. Commit ONLY if all checks pass
7. Update prd.json → Set passes: true for completed story
8. Append learnings to progress.txt
9. Update AGENTS.md if reusable patterns discovered
10. Loop → Next story
```

### Memory Files
| File | Purpose | Location |
|------|---------|----------|
| `prd.json` | Task list with passes: true/false | Project root or scripts/ralph/ |
| `progress.txt` | Learnings between iterations | Same as prd.json |
| `AGENTS.md` | Directory-specific patterns | Any directory in repo |

### Running Ralph
```bash
# Automated loop
./scripts/ralph/ralph.sh 10

# Manual single story
claude -p "Implement US-001 from prd.json following Ralph pattern"
```

### Creating New Features
1. Create PRD: `Load the prd skill and create a PRD for [feature]`
2. Convert to Ralph: `Load the ralph skill and convert tasks/prd-[name].md to prd.json`
3. Run Ralph: `./scripts/ralph/ralph.sh`

**For full Ralph guide:** `~/.config/mosaic/guides/ralph-autonomous.md`

## Project-Local AGENTS.md Pattern

Each directory can have an `AGENTS.md` file containing patterns specific to that area of the codebase. **Always check for and read AGENTS.md files in directories you're working in.**

```markdown
# Example AGENTS.md

## Codebase Patterns
- Use `httpx.AsyncClient` for external HTTP calls
- All routes require authentication via `Depends(get_current_user)`

## Common Gotchas
- Remember to run migrations after schema changes
- Frontend env vars need NEXT_PUBLIC_ prefix
```

**Update AGENTS.md when you discover:**
- Reusable patterns
- Non-obvious requirements
- Gotchas that would trip up future agents
- Testing approaches for that area

## Project Bootstrapping

When starting work on a **new project** that lacks an `AGENTS.md`, bootstrap it:

```bash
# Automated (recommended)
~/.config/mosaic/rails/bootstrap/init-project.sh --name "Project Name" --type auto

# Or manually with templates
export PROJECT_NAME="Project Name" PROJECT_DESCRIPTION="What it does" TASK_PREFIX="PN"
envsubst < ~/.config/mosaic/templates/agent/AGENTS.md.template > AGENTS.md
```

**Available project types:** `nestjs-nextjs`, `django`, `typescript`, `python-fastapi`, `python-library`, `generic` (auto-detected from project files).

**Templates:** `~/.config/mosaic/templates/agent/` (generic) and `~/.config/mosaic/templates/agent/projects/<type>/` (tech-stack specific).

**Fragments:** `~/.config/mosaic/templates/agent/fragments/` — Reusable sections (conditional-loading, commit-format, secrets, multi-agent, code-review).

**Full guide:** `~/.config/mosaic/guides/bootstrap.md`

### Agent Configuration Health

```bash
# Audit all projects for missing AGENTS.md, agent-guide references
~/.config/mosaic/rails/bootstrap/agent-lint.sh

# Audit with fix suggestions
~/.config/mosaic/rails/bootstrap/agent-lint.sh --verbose --fix-hint

# Non-destructively upgrade existing projects (inject missing sections)
~/.config/mosaic/rails/bootstrap/agent-upgrade.sh --all --dry-run   # Preview
~/.config/mosaic/rails/bootstrap/agent-upgrade.sh --all             # Apply

# Upgrade a single project
~/.config/mosaic/rails/bootstrap/agent-upgrade.sh ~/src/my-project
```

**Spec:** `~/.config/mosaic/templates/agent/SPEC.md` — Defines Tier 1/2/3 requirements for well-configured projects.

## Issue Tracking (Git-Based)

All work is tracked as **issues in the project's git repository** (Gitea or GitHub).

### Workflow
1. Check for assigned issues before starting work
2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
3. Reference issues in commits: `Fixes #123` or `Refs #123`
4. Close issues only after successful testing

### Labels
Use consistent labels across projects:
- `epic` - Large feature spanning multiple issues
- `feature` - New functionality
- `bug` - Defect fix
- `task` - General work item
- `documentation` - Docs updates
- `security` - Security-related
- `breaking` - Breaking change

### Milestones & Versioning
- **Each feature gets a dedicated milestone**
- MVP starts at `0.1.0`
- Pre-release: `0.X.0` for breaking changes, `0.X.Y` for patches
- Post-release: `X.0.0` for breaking changes

### Git Scripts (PREFERRED for Gitea/GitHub operations)
Cross-platform helpers at `~/.config/mosaic/rails/git/` (work with both Gitea and GitHub):

**Why use these scripts?**
- Auto-detect platform (Gitea vs GitHub)
- Abstract CLI syntax differences (tea vs gh)
- Handle milestone name filtering for Gitea
- Consistent interface across all repos

**Issues:**
```bash
~/.config/mosaic/rails/git/issue-create.sh -t "Title" -l "label" -m "0.2.0"
~/.config/mosaic/rails/git/issue-list.sh -s open -l "bug"
~/.config/mosaic/rails/git/issue-list.sh -m "M6-AgentOrchestration"
~/.config/mosaic/rails/git/issue-view.sh -i 42
~/.config/mosaic/rails/git/issue-edit.sh -i 42 -t "New Title" -l "labels"
~/.config/mosaic/rails/git/issue-assign.sh -i 42 -a "username"
~/.config/mosaic/rails/git/issue-comment.sh -i 42 -c "Comment text"
~/.config/mosaic/rails/git/issue-close.sh -i 42 [-c "Closing comment"]
~/.config/mosaic/rails/git/issue-reopen.sh -i 42 [-c "Reopening reason"]
```

**Pull Requests:**
```bash
~/.config/mosaic/rails/git/pr-create.sh -t "Title" -b "Description" -i 42
~/.config/mosaic/rails/git/pr-create.sh -t "Title" -B main -H feature-branch
~/.config/mosaic/rails/git/pr-list.sh -s open
~/.config/mosaic/rails/git/pr-view.sh -n 42
~/.config/mosaic/rails/git/pr-review.sh -n 42 -a approve [-c "LGTM"]
~/.config/mosaic/rails/git/pr-review.sh -n 42 -a request-changes -c "Fix X"
~/.config/mosaic/rails/git/pr-merge.sh -n 42 -m squash -d
~/.config/mosaic/rails/git/pr-close.sh -n 42 [-c "Closing reason"]
~/.config/mosaic/rails/git/pr-diff.sh -n 42 [-o diff.patch]
~/.config/mosaic/rails/git/pr-metadata.sh -n 42 [-o metadata.json]
```

**Milestones:**
```bash
~/.config/mosaic/rails/git/milestone-create.sh -t "0.2.0" -d "Description"
~/.config/mosaic/rails/git/milestone-create.sh --list
~/.config/mosaic/rails/git/milestone-list.sh [-s open|closed|all]
~/.config/mosaic/rails/git/milestone-close.sh -t "0.2.0"
```

**NOTE:** These scripts handle the Gitea `--milestones` (plural) syntax automatically. Always prefer these over raw `tea` or `gh` commands.

### Woodpecker CI CLI
Official CLI for interacting with Woodpecker CI at `ci.mosaicstack.dev`.

**Setup:**
```bash
# Install (Arch)
paru -S woodpecker

# Configure
export WOODPECKER_SERVER="https://ci.mosaicstack.dev"
export WOODPECKER_TOKEN="your-token"  # Get from ci.mosaicstack.dev/user
```

**Pipelines:**
```bash
woodpecker pipeline ls <owner/repo>              # List pipelines
woodpecker pipeline info <owner/repo> <num>      # Pipeline details
woodpecker pipeline create <owner/repo>          # Trigger pipeline
woodpecker pipeline stop <owner/repo> <num>      # Cancel pipeline
woodpecker pipeline start <owner/repo> <num>     # Restart pipeline
woodpecker pipeline approve <owner/repo> <num>   # Approve blocked
```

**Logs:**
```bash
woodpecker log show <owner/repo> <num>           # View logs
woodpecker log show <owner/repo> <num> <step>    # Specific step
```

**Repositories:**
```bash
woodpecker repo ls                               # List repos
woodpecker repo add <owner/repo>                 # Activate for CI
woodpecker repo rm <owner/repo>                  # Deactivate
woodpecker repo repair <owner/repo>              # Repair webhooks
```

**Secrets:**
```bash
woodpecker secret ls <owner/repo>                # List secrets
woodpecker secret add <owner/repo> -n KEY -v val # Add secret
woodpecker secret rm <owner/repo> -n KEY         # Delete secret
```

**Full reference:** `jarvis-brain/docs/reference/woodpecker/WOODPECKER-CLI.md`
**Setup command:** `woodpecker setup --server https://ci.mosaicstack.dev --token "YOUR_TOKEN"`

### Portainer Scripts
CLI tools for managing Portainer stacks at `~/.config/mosaic/rails/portainer/`.

**Setup:**
```bash
export PORTAINER_URL="https://portainer.example.com:9443"
export PORTAINER_API_KEY="your-api-key-here"
```

Create an API key in Portainer: My account → Access tokens → Add access token.

**Stack Management:**
```bash
stack-list.sh                                        # List all stacks
stack-list.sh -f json                                # JSON format
stack-list.sh -e 1                                   # Filter by endpoint

stack-status.sh -n mystack                           # Show stack status
stack-status.sh -n mystack -f json                   # JSON format

stack-redeploy.sh -n mystack                         # Redeploy stack
stack-redeploy.sh -n mystack -p                      # Pull latest images

stack-start.sh -n mystack                            # Start inactive stack
stack-stop.sh -n mystack                             # Stop running stack
```

**Logs:**
```bash
stack-logs.sh -n mystack                             # List services
stack-logs.sh -n mystack -s webapp                   # View service logs
stack-logs.sh -n mystack -s webapp -t 200            # Last 200 lines
stack-logs.sh -n mystack -s webapp -f                # Follow logs
```

**Endpoints:**
```bash
endpoint-list.sh                                     # List all endpoints
endpoint-list.sh -f json                             # JSON format
```

**Common Workflow (CI/CD redeploy):**
```bash
~/.config/mosaic/rails/portainer/stack-redeploy.sh -n myapp -p && \
~/.config/mosaic/rails/portainer/stack-status.sh -n myapp && \
~/.config/mosaic/rails/portainer/stack-logs.sh -n myapp -s api -t 50
```

### Git Worktrees
Use worktrees for parallel work on multiple issues without branch switching.

**Structure:**
```
{project_name}_worktrees/{issue-name}/
```

**Example:**
```
~/src/my-app/                          # Main repository
~/src/my-app_worktrees/
    ├── 42-fix-login/                  # Worktree for issue #42
    ├── 57-add-dashboard/              # Worktree for issue #57
    └── 89-refactor-auth/              # Worktree for issue #89
```

**Commands:**
```bash
# Create worktree for an issue
git worktree add ../my-app_worktrees/42-fix-login -b issue-42-fix-login

# List active worktrees
git worktree list

# Remove worktree after merge
git worktree remove ../my-app_worktrees/42-fix-login
```

**When to use worktrees:**
- Working on multiple issues simultaneously
- Long-running feature branches that need isolation
- Code reviews while continuing other work
- Comparing implementations across branches

## Development Requirements

### Test-Driven Development (TDD)
1. Write tests BEFORE implementation
2. Minimum **85% coverage**
3. Build and test after EVERY change
4. Task completion requires passing tests

### Linting (MANDATORY)
**Run the project linter after every code change. Fix ALL violations. Zero tolerance.**
- Never disable lint rules (`eslint-disable`, `noqa`, `nolint`)
- Never leave warnings — warnings are errors you haven't fixed yet
- If you touched a file, you own its lint violations (Campsite Rule)
- If unsure what linter the project uses, read the `lint` skill: `~/.config/mosaic/skills/lint/SKILL.md`

### Code Style
Follow [Google Style Guides](https://github.com/google/styleguide) for all languages.

### Commits
```
<type>(#issue): Brief description

Detailed explanation if needed.

Fixes #123
```
Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`

## Scratchpad Format

When working on issue #N, create `docs/scratchpads/N-short-name.md`:

```markdown
# Issue #N: Title

## Objective
[What this issue accomplishes]

## Approach
[Implementation plan]

## Progress
- [ ] Step 1
- [ ] Step 2

## Testing
[Test plan and results]

## Notes
[Findings, blockers, decisions]
```

## Conditional Context

**Read the relevant guide before starting work:**

| Task Type | Guide |
|-----------|-------|
| Bootstrapping a new project | `~/.config/mosaic/guides/bootstrap.md` |
| Orchestrating autonomous task completion | `~/.config/mosaic/guides/orchestrator.md` |
| Ralph autonomous development | `~/.config/mosaic/guides/ralph-autonomous.md` |
| Frontend development | `~/.config/mosaic/guides/frontend.md` |
| Backend/API development | `~/.config/mosaic/guides/backend.md` |
| Code review | `~/.config/mosaic/guides/code-review.md` |
| Authentication/Authorization | `~/.config/mosaic/guides/authentication.md` |
| CI/CD pipelines & Docker builds | `~/.config/mosaic/guides/ci-cd-pipelines.md` |
| Infrastructure/DevOps | `~/.config/mosaic/guides/infrastructure.md` |
| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
| Secrets management | See section below |

**Project-specific skills:**

| Project | Skill |
|---------|-------|
| jetrich/jarvis | `~/.config/mosaic/skills/jarvis/SKILL.md` |

## Secrets Management

**NEVER hardcode secrets in the codebase.** Choose the appropriate method based on your environment.

### If Using Vault
See `~/.config/mosaic/guides/vault-secrets.md` for the canonical structure and rules.

Quick reference:
```
{mount}/{service}/{component}/{secret-name}
Example: secret-prod/postgres/database/app
```

### If NOT Using Vault (Use .env Files)

**Structure:**
```
project-root/
├── .env.example      # Template with placeholder values (committed)
├── .env              # Local secrets (NEVER committed)
├── .env.development  # Dev overrides (optional, not committed)
├── .env.test         # Test environment (optional, not committed)
└── .gitignore        # Must include .env*
```

**Rules:**
1. **ALWAYS** add `.env*` to `.gitignore` (except `.env.example`)
2. Create `.env.example` with all required variables and placeholder values
3. Use descriptive variable names: `DATABASE_URL`, `API_SECRET_KEY`
4. Document required variables in README
5. Load via `dotenv` or framework-native methods

**.env.example template:**
```bash
# Database
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
DATABASE_POOL_SIZE=10

# Authentication
JWT_SECRET_KEY=your-secret-key-here
JWT_EXPIRY_SECONDS=3600

# External APIs
STRIPE_API_KEY=sk_test_xxx
SENDGRID_API_KEY=SG.xxx

# App Config
APP_ENV=development
DEBUG=false
```

**Loading secrets:**
```python
# Python
from dotenv import load_dotenv
load_dotenv()

# Node.js
import 'dotenv/config';

# Or use framework-native (Next.js, NestJS, etc.)
```

### Security Rules (All Environments)
1. **Never commit secrets** - Use .env or Vault
2. **Never log secrets** - Mask in logs if needed
3. **Rotate compromised secrets immediately**
4. **Use different secrets per environment**
5. **Validate secrets exist at startup** - Fail fast if missing

## Multi-Agent Coordination

When launching concurrent agents:
```bash
nohup claude -p "<instruction>" > logs/agent-{name}.log 2>&1 &
```

- Maximum 10 simultaneous agents
- Monitor for errors and permission issues
- Restart failed agents after fixing issues

**For Ralph multi-agent:**
- Use worktrees for isolation
- Each agent works on different story
- Coordinate via git (frequent pulls)

## Dev Server Infrastructure (web1.corp.uscllc.local)

### Shared Traefik Reverse Proxy

A shared Traefik instance handles routing for all dev/test services on this server.

**Location:** `~/src/traefik`

**Start Traefik:**
```bash
cd ~/src/traefik
docker compose up -d
```

**Dashboard:** http://localhost:8080

### Connecting Services to Traefik

Add to your service's `docker-compose.yml`:

```yaml
services:
  app:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.myapp.rule=Host(`myapp.uscllc.com`)"
      - "traefik.http.routers.myapp.entrypoints=websecure"
      - "traefik.http.routers.myapp.tls=true"
      - "traefik.http.services.myapp.loadbalancer.server.port=3000"
    networks:
      - internal
      - traefik-public

networks:
  internal:
    driver: bridge
  traefik-public:
    external: true
```

**Note:** Uses self-signed wildcard cert - browsers will show security warning.

### Active Dev Services

| Service | Domain | Repository |
|---------|--------|------------|
| Inventory Stickers | inventory.uscllc.com | ~/src/sticker-app |

## Project Structure

```
project-root/
├── AGENTS.md                  # Codebase patterns for AI agents
├── docs/
│   └── scratchpads/          # Agent working documents
│       └── {issue#}-{name}.md
├── scripts/
│   └── ralph/                # Ralph autonomous development
│       ├── ralph.sh          # Loop script
│       ├── prd.json          # Current feature tasks
│       └── progress.txt      # Memory between iterations
├── tasks/                    # PRD documents
│   └── prd-{feature}.md
├── logs/                     # Log files
└── tests/                    # Test files
```