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.

---

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:

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:

{ "id": "US-001", "skills": ["nestjs-best-practices", "test-driven-development"], ... }

Fresh Machine Setup

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

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

# 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:

# 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

# 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:

~/.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:

~/.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:

~/.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:

# 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:

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:

woodpecker log show <owner/repo> <num>           # View logs
woodpecker log show <owner/repo> <num> <step>    # Specific step

Repositories:

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:

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:

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:

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:

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:

endpoint-list.sh                                     # List all endpoints
endpoint-list.sh -f json                             # JSON format

Common Workflow (CI/CD redeploy):

~/.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:

# 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 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:

# 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:

# 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
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:

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:

cd ~/src/traefik
docker compose up -d

Dashboard: http://localhost:8080

Connecting Services to Traefik

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

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