From 3f2ba89db2f730f2b6a10d7357f587f1faf0b32b Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Thu, 19 Feb 2026 13:24:12 -0600 Subject: [PATCH] refactor: AGENTS.md is the single source of truth for all runtimes - Create ~/.config/mosaic/AGENTS.md as the canonical universal agent config - Runtime adapters (CLAUDE.md, opencode/AGENTS.md, codex/instructions.md) are now thin pointers that say "READ ~/.config/mosaic/AGENTS.md" - mosaic claude: injects AGENTS.md via --append-system-prompt - mosaic opencode/codex: copies AGENTS.md to runtime config path before launch - mosaic-link-runtime-assets: pushes thin pointers for direct launch fallback AGENTS.md is runtime-agnostic. All runtimes get the same standards. Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 624 +++++++++++++++++++++++++++++ bin/mosaic | 47 ++- bin/mosaic-link-runtime-assets | 6 +- bin/mosaic-link-runtime-assets.ps1 | 2 +- bin/mosaic.ps1 | 48 ++- runtime/claude/CLAUDE.md | 623 +--------------------------- runtime/codex/instructions.md | 18 +- runtime/opencode/AGENTS.md | 34 +- 8 files changed, 723 insertions(+), 679 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..6512c20 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,624 @@ +# 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.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//` (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 # List pipelines +woodpecker pipeline info # Pipeline details +woodpecker pipeline create # Trigger pipeline +woodpecker pipeline stop # Cancel pipeline +woodpecker pipeline start # Restart pipeline +woodpecker pipeline approve # Approve blocked +``` + +**Logs:** +```bash +woodpecker log show # View logs +woodpecker log show # Specific step +``` + +**Repositories:** +```bash +woodpecker repo ls # List repos +woodpecker repo add # Activate for CI +woodpecker repo rm # Deactivate +woodpecker repo repair # Repair webhooks +``` + +**Secrets:** +```bash +woodpecker secret ls # List secrets +woodpecker secret add -n KEY -v val # Add secret +woodpecker secret rm -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 +``` +(#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 "" > 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 +``` diff --git a/bin/mosaic b/bin/mosaic index 00a5176..d4bea29 100755 --- a/bin/mosaic +++ b/bin/mosaic @@ -3,10 +3,13 @@ set -euo pipefail # mosaic — Unified agent launcher and management CLI # +# AGENTS.md is the single source of truth for all agent sessions. +# The launcher injects it into every runtime consistently. +# # Usage: -# mosaic claude [args...] Launch Claude Code with SOUL.md injected -# mosaic opencode [args...] Launch OpenCode -# mosaic codex [args...] Launch Codex +# mosaic claude [args...] Launch Claude Code with AGENTS.md injected +# mosaic opencode [args...] Launch OpenCode with AGENTS.md injected +# mosaic codex [args...] Launch Codex with AGENTS.md injected # mosaic init [args...] Generate SOUL.md interactively # mosaic doctor [args...] Health audit # mosaic sync [args...] Sync skills @@ -22,9 +25,9 @@ mosaic $VERSION — Unified agent launcher Usage: mosaic [args...] Agent Launchers: - claude [args...] Launch Claude Code with SOUL.md injected - opencode [args...] Launch OpenCode - codex [args...] Launch Codex + claude [args...] Launch Claude Code with AGENTS.md injected + opencode [args...] Launch OpenCode with AGENTS.md injected + codex [args...] Launch Codex with AGENTS.md injected Management: init [args...] Generate SOUL.md (agent identity contract) @@ -49,6 +52,14 @@ check_mosaic_home() { fi } +check_agents_md() { + if [[ ! -f "$MOSAIC_HOME/AGENTS.md" ]]; then + echo "[mosaic] ERROR: ~/.config/mosaic/AGENTS.md not found." >&2 + echo "[mosaic] Re-run the installer: cd ~/src/mosaic-bootstrap && bash install.sh" >&2 + exit 1 + fi +} + check_soul() { if [[ ! -f "$MOSAIC_HOME/SOUL.md" ]]; then echo "[mosaic] SOUL.md not found. Running mosaic init..." @@ -65,31 +76,51 @@ check_runtime() { fi } +# Ensure AGENTS.md is present at the runtime's native config path. +# Used for runtimes that don't support CLI prompt injection. +ensure_runtime_config() { + local src="$MOSAIC_HOME/AGENTS.md" + local dst="$1" + mkdir -p "$(dirname "$dst")" + if ! cmp -s "$src" "$dst" 2>/dev/null; then + cp "$src" "$dst" + fi +} + # Launcher functions launch_claude() { check_mosaic_home + check_agents_md check_soul check_runtime "claude" - # SOUL.md is loaded via ~/.claude/CLAUDE.md directive (pushed by mosaic-link-runtime-assets) + # Claude supports --append-system-prompt for direct injection + local agents_content + agents_content="$(cat "$MOSAIC_HOME/AGENTS.md")" echo "[mosaic] Launching Claude Code..." - exec claude "$@" + exec claude --append-system-prompt "$agents_content" "$@" } launch_opencode() { check_mosaic_home + check_agents_md check_soul check_runtime "opencode" + # OpenCode reads from ~/.config/opencode/AGENTS.md — copy canonical version there + ensure_runtime_config "$HOME/.config/opencode/AGENTS.md" echo "[mosaic] Launching OpenCode..." exec opencode "$@" } launch_codex() { check_mosaic_home + check_agents_md check_soul check_runtime "codex" + # Codex reads from ~/.codex/instructions.md — copy canonical version there + ensure_runtime_config "$HOME/.codex/instructions.md" echo "[mosaic] Launching Codex..." exec codex "$@" } diff --git a/bin/mosaic-link-runtime-assets b/bin/mosaic-link-runtime-assets index ad3d0c6..a910a2a 100755 --- a/bin/mosaic-link-runtime-assets +++ b/bin/mosaic-link-runtime-assets @@ -69,7 +69,7 @@ for p in "${legacy_paths[@]}"; do remove_legacy_path "$p" done -# Runtime files are synced as regular files (not symlinks) to reduce path confusion. +# Claude-specific runtime files (settings, hooks — NOT CLAUDE.md which is now a thin pointer) for runtime_file in \ CLAUDE.md \ settings.json \ @@ -80,13 +80,13 @@ for runtime_file in \ copy_file_managed "$src" "$HOME/.claude/$runtime_file" done -# OpenCode runtime adapter (optional, copied when present). +# OpenCode runtime adapter (thin pointer to AGENTS.md) opencode_adapter="$MOSAIC_HOME/runtime/opencode/AGENTS.md" if [[ -f "$opencode_adapter" ]]; then copy_file_managed "$opencode_adapter" "$HOME/.config/opencode/AGENTS.md" fi -# Codex runtime adapter (optional, copied when present). +# Codex runtime adapter (thin pointer to AGENTS.md) codex_adapter="$MOSAIC_HOME/runtime/codex/instructions.md" if [[ -f "$codex_adapter" ]]; then mkdir -p "$HOME/.codex" diff --git a/bin/mosaic-link-runtime-assets.ps1 b/bin/mosaic-link-runtime-assets.ps1 index 94ce81e..2c150f5 100644 --- a/bin/mosaic-link-runtime-assets.ps1 +++ b/bin/mosaic-link-runtime-assets.ps1 @@ -77,7 +77,7 @@ foreach ($p in $legacyPaths) { Remove-LegacyPath $p } -# Sync runtime config files (copy, not link) +# Claude-specific runtime files (settings, hooks — CLAUDE.md is now a thin pointer) $runtimeFiles = @("CLAUDE.md", "settings.json", "hooks-config.json", "context7-integration.md") foreach ($rf in $runtimeFiles) { $src = Join-Path $MosaicHome "runtime\claude\$rf" diff --git a/bin/mosaic.ps1 b/bin/mosaic.ps1 index 28b5ad7..5a4d14f 100644 --- a/bin/mosaic.ps1 +++ b/bin/mosaic.ps1 @@ -1,9 +1,12 @@ # mosaic.ps1 — Unified agent launcher and management CLI (Windows) # +# AGENTS.md is the single source of truth for all agent sessions. +# The launcher injects it into every runtime consistently. +# # Usage: -# mosaic claude [args...] Launch Claude Code with SOUL.md injected -# mosaic opencode [args...] Launch OpenCode -# mosaic codex [args...] Launch Codex +# mosaic claude [args...] Launch Claude Code with AGENTS.md injected +# mosaic opencode [args...] Launch OpenCode with AGENTS.md injected +# mosaic codex [args...] Launch Codex with AGENTS.md injected # mosaic init [args...] Generate SOUL.md interactively # mosaic doctor [args...] Health audit # mosaic sync [args...] Sync skills @@ -19,9 +22,9 @@ mosaic $Version - Unified agent launcher Usage: mosaic [args...] Agent Launchers: - claude [args...] Launch Claude Code with SOUL.md injected - opencode [args...] Launch OpenCode - codex [args...] Launch Codex + claude [args...] Launch Claude Code with AGENTS.md injected + opencode [args...] Launch OpenCode with AGENTS.md injected + codex [args...] Launch Codex with AGENTS.md injected Management: init [args...] Generate SOUL.md (agent identity contract) @@ -43,6 +46,15 @@ function Assert-MosaicHome { } } +function Assert-AgentsMd { + $agentsPath = Join-Path $MosaicHome "AGENTS.md" + if (-not (Test-Path $agentsPath)) { + Write-Host "[mosaic] ERROR: ~/.config/mosaic/AGENTS.md not found." -ForegroundColor Red + Write-Host "[mosaic] Re-run the installer." + exit 1 + } +} + function Assert-Soul { $soulPath = Join-Path $MosaicHome "SOUL.md" if (-not (Test-Path $soulPath)) { @@ -60,6 +72,18 @@ function Assert-Runtime { } } +function Ensure-RuntimeConfig { + param([string]$Dst) + $src = Join-Path $MosaicHome "AGENTS.md" + $parent = Split-Path $Dst -Parent + if (-not (Test-Path $parent)) { New-Item -ItemType Directory -Path $parent -Force | Out-Null } + $srcHash = (Get-FileHash $src -Algorithm SHA256).Hash + $dstHash = if (Test-Path $Dst) { (Get-FileHash $Dst -Algorithm SHA256).Hash } else { "" } + if ($srcHash -ne $dstHash) { + Copy-Item $src $Dst -Force + } +} + if ($args.Count -eq 0) { Show-Usage exit 0 @@ -71,23 +95,31 @@ $remaining = if ($args.Count -gt 1) { $args[1..($args.Count - 1)] } else { @() } switch ($command) { "claude" { Assert-MosaicHome + Assert-AgentsMd Assert-Soul Assert-Runtime "claude" - # SOUL.md is loaded via ~/.claude/CLAUDE.md directive (pushed by mosaic-link-runtime-assets) + # Claude supports --append-system-prompt for direct injection + $agentsContent = Get-Content (Join-Path $MosaicHome "AGENTS.md") -Raw Write-Host "[mosaic] Launching Claude Code..." - & claude @remaining + & claude --append-system-prompt $agentsContent @remaining } "opencode" { Assert-MosaicHome + Assert-AgentsMd Assert-Soul Assert-Runtime "opencode" + # OpenCode reads from ~/.config/opencode/AGENTS.md + Ensure-RuntimeConfig (Join-Path $env:USERPROFILE ".config\opencode\AGENTS.md") Write-Host "[mosaic] Launching OpenCode..." & opencode @remaining } "codex" { Assert-MosaicHome + Assert-AgentsMd Assert-Soul Assert-Runtime "codex" + # Codex reads from ~/.codex/instructions.md + Ensure-RuntimeConfig (Join-Path $env:USERPROFILE ".codex\instructions.md") Write-Host "[mosaic] Launching Codex..." & codex @remaining } diff --git a/runtime/claude/CLAUDE.md b/runtime/claude/CLAUDE.md index 0957558..b20670a 100644 --- a/runtime/claude/CLAUDE.md +++ b/runtime/claude/CLAUDE.md @@ -1,622 +1,11 @@ -# Mosaic Universal Standards (Machine-Wide) +# Mosaic Runtime Adapter — Claude Code ## MANDATORY — Read Before Any Response -BEFORE responding to any user message, READ these files in order: +BEFORE responding to any user message, READ `~/.config/mosaic/AGENTS.md`. -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) +That file is the universal agent configuration. It contains the full load order, +development standards, skills, and workflows. Do NOT respond until you have loaded it. -Do NOT respond to the user until you have loaded all three. - -`~/.config/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 - -**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.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: -```bash -claude -p "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` - -## 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 `CLAUDE.md` or `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/CLAUDE.md.template > CLAUDE.md -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//` (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 CLAUDE.md, 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" # Works with milestone names! -~/.config/mosaic/rails/git/issue-view.sh -i 42 # View issue details -~/.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 # View PR details -~/.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] # Get PR diff -~/.config/mosaic/rails/git/pr-metadata.sh -n 42 [-o metadata.json] # Get PR metadata as 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 # List pipelines -woodpecker pipeline info # Pipeline details -woodpecker pipeline create # Trigger pipeline -woodpecker pipeline stop # Cancel pipeline -woodpecker pipeline start # Restart pipeline -woodpecker pipeline approve # Approve blocked -``` - -**Logs:** -```bash -woodpecker log show # View logs -woodpecker log show # Specific step -``` - -**Repositories:** -```bash -woodpecker repo ls # List repos -woodpecker repo add # Activate for CI -woodpecker repo rm # Deactivate -woodpecker repo repair # Repair webhooks -``` - -**Secrets:** -```bash -woodpecker secret ls # List secrets -woodpecker secret add -n KEY -v val # Add secret -woodpecker secret rm -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 -``` -(#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 "" > 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:** -```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 -``` +This file (`~/.claude/CLAUDE.md`) exists only as a fallback for direct `claude` launches. +For full injection, use `mosaic claude` instead. diff --git a/runtime/codex/instructions.md b/runtime/codex/instructions.md index fb097d7..5d65fda 100644 --- a/runtime/codex/instructions.md +++ b/runtime/codex/instructions.md @@ -2,18 +2,10 @@ ## MANDATORY — Read Before Any Response -BEFORE responding to any user message, READ these files in order: +BEFORE responding to any user message, READ `~/.config/mosaic/AGENTS.md`. -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) +That file is the universal agent configuration. It contains the full load order, +development standards, skills, and workflows. Do NOT respond until you have loaded it. -Do NOT respond to the user until you have loaded all three. - -This file is a Codex adapter layer. It does not replace project guidance. - -## Runtime Behavior - -- Favor repo lifecycle scripts under `scripts/agent/` for start/end rituals. -- Keep instructions and quality gates aligned with Mosaic standards. -- Use `~/.config/mosaic/skills/` for domain expertise when available. +This file (`~/.codex/instructions.md`) exists only as a fallback for direct `codex` launches. +For full injection, use `mosaic codex` instead. diff --git a/runtime/opencode/AGENTS.md b/runtime/opencode/AGENTS.md index 6333f58..5c72518 100644 --- a/runtime/opencode/AGENTS.md +++ b/runtime/opencode/AGENTS.md @@ -2,34 +2,10 @@ ## MANDATORY — Read Before Any Response -BEFORE responding to any user message, READ these files in order: +BEFORE responding to any user message, READ `~/.config/mosaic/AGENTS.md`. -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) +That file is the universal agent configuration. It contains the full load order, +development standards, skills, and workflows. Do NOT respond until you have loaded it. -Do NOT respond to the user until you have loaded all three. - -This file is an OpenCode adapter layer. It does not replace project guidance. - -## Orchestrator Capability Contract - -- OpenCode sessions may not expose a native subagent/background task primitive in all deployments. -- When native subagent delegation is unavailable, use Mosaic's deterministic orchestrator rail: - - `~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle` -- Keep repo task tracking in `docs/tasks.md` as the canonical human-readable state. -- Keep machine transport/controller state in `.mosaic/orchestrator/`. - -## Fallback Delegation Mode (No Native Subagents) - -1. Bootstrap repo if needed: - - `~/.config/mosaic/bin/mosaic-bootstrap-repo /path/to/repo` -2. Configure `.mosaic/orchestrator/config.json`: - - set `"enabled": true` - - set `"worker.command_template"` to your OpenCode worker command -3. Queue work items in `.mosaic/orchestrator/tasks.json` (or via Matrix command ingestion). -4. Run deterministic ticks: - - `~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle` - - or drain to completion: `~/.config/mosaic/bin/mosaic-orchestrator-drain` - -This preserves rails enforcement (`quality_gates`) even without runtime-native subagent features. +This file (`~/.config/opencode/AGENTS.md`) exists only as a fallback for direct `opencode` launches. +For full injection, use `mosaic opencode` instead.