mosaic/bootstrap
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
eac247c5cb3fbc0ce22cdb09a009cb1ab3d3cd8b
bootstrap/AGENTS.md

22 KiB
Raw Blame History

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:

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
Reference in New Issue View Git Blame Copy Permalink