mosaic/bootstrap
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
db2ec9524f09028f97302ad50406c8bad3648c8d
bootstrap/runtime/claude/CLAUDE.md

21 KiB
Raw Blame History

Mosaic Universal Standards (Machine-Wide)

Before applying any runtime-specific guidance in this file, load and apply:

  • ~/.mosaic/STANDARDS.md
  • project-local AGENTS.md

~/.mosaic is the canonical cross-agent standards layer. This CLAUDE.md is an adapter layer for Claude-specific capabilities only.

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

97 skills available in ~/.mosaic/skills/. Skills are instruction packages that provide domain expertise. Source: mosaic/agent-skills repo (93 community) + 4 local-only.

Load a skill by reading its SKILL.md:

Read ~/.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 via claude -p, include skill loading in the kickstart:

claude -p "Read ~/.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: ~/.mosaic/guides/ralph-autonomous.md

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 CLAUDE.md or AGENTS.md, bootstrap it:

# Automated (recommended)
~/.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 < ~/.mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
envsubst < ~/.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: ~/.mosaic/templates/agent/ (generic) and ~/.mosaic/templates/agent/projects/<type>/ (tech-stack specific).

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

Full guide: ~/.mosaic/guides/bootstrap.md

Agent Configuration Health

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

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

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

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

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

~/.mosaic/rails/git/issue-create.sh -t "Title" -l "label" -m "0.2.0"
~/.mosaic/rails/git/issue-list.sh -s open -l "bug"
~/.mosaic/rails/git/issue-list.sh -m "M6-AgentOrchestration"  # Works with milestone names!
~/.mosaic/rails/git/issue-view.sh -i 42                         # View issue details
~/.mosaic/rails/git/issue-edit.sh -i 42 -t "New Title" -l "labels"
~/.mosaic/rails/git/issue-assign.sh -i 42 -a "username"
~/.mosaic/rails/git/issue-comment.sh -i 42 -c "Comment text"
~/.mosaic/rails/git/issue-close.sh -i 42 [-c "Closing comment"]
~/.mosaic/rails/git/issue-reopen.sh -i 42 [-c "Reopening reason"]

Pull Requests:

~/.mosaic/rails/git/pr-create.sh -t "Title" -b "Description" -i 42
~/.mosaic/rails/git/pr-create.sh -t "Title" -B main -H feature-branch
~/.mosaic/rails/git/pr-list.sh -s open
~/.mosaic/rails/git/pr-view.sh -n 42                                    # View PR details
~/.mosaic/rails/git/pr-review.sh -n 42 -a approve [-c "LGTM"]
~/.mosaic/rails/git/pr-review.sh -n 42 -a request-changes -c "Fix X"
~/.mosaic/rails/git/pr-merge.sh -n 42 -m squash -d
~/.mosaic/rails/git/pr-close.sh -n 42 [-c "Closing reason"]
~/.mosaic/rails/git/pr-diff.sh -n 42 [-o diff.patch]                         # Get PR diff
~/.mosaic/rails/git/pr-metadata.sh -n 42 [-o metadata.json]                  # Get PR metadata as JSON

Milestones:

~/.mosaic/rails/git/milestone-create.sh -t "0.2.0" -d "Description"
~/.mosaic/rails/git/milestone-create.sh --list
~/.mosaic/rails/git/milestone-list.sh [-s open|closed|all]
~/.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 ~/.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):

~/.mosaic/rails/portainer/stack-redeploy.sh -n myapp -p && \
~/.mosaic/rails/portainer/stack-status.sh -n myapp && \
~/.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: ~/.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 ~/.mosaic/guides/bootstrap.md
Orchestrating autonomous task completion ~/.mosaic/guides/orchestrator.md
Ralph autonomous development ~/.mosaic/guides/ralph-autonomous.md
Frontend development ~/.mosaic/guides/frontend.md
Backend/API development ~/.mosaic/guides/backend.md
Code review ~/.mosaic/guides/code-review.md
Authentication/Authorization ~/.mosaic/guides/authentication.md
CI/CD pipelines & Docker builds ~/.mosaic/guides/ci-cd-pipelines.md
Infrastructure/DevOps ~/.mosaic/guides/infrastructure.md
QA/Testing ~/.mosaic/guides/qa-testing.md
Secrets management See section below

Project-specific skills:

Project Skill
jetrich/jarvis ~/.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 ~/.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
  • Add required permissions to .claude/settings.json → allowedCommands
  • 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