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 <noreply@anthropic.com>
This commit is contained in:
Jason Woltje
624
AGENTS.md
Normal file
624
AGENTS.md
Normal file
@@ -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-name>/SKILL.md
|
||||
```
|
||||
|
||||
### Skill Dispatch Table — Load the right skills for your task
|
||||
|
||||
| Task Type | Skills to Load | Notes |
|
||||
|-----------|---------------|-------|
|
||||
| **NestJS development** | `nestjs-best-practices` | 40 rules, 10 categories |
|
||||
| **Next.js / React** | `next-best-practices`, `vercel-react-best-practices` | RSC, async, performance |
|
||||
| **React components** | `vercel-composition-patterns`, `shadcn-ui` | shadcn note: uses Tailwind v4 |
|
||||
| **Vue / Nuxt** | `vue-best-practices`, `nuxt`, `pinia`, `vue-router-best-practices` | antfu conventions |
|
||||
| **Vite / Vitest** | `vite`, `vitest` | Build + test tooling |
|
||||
| **FastAPI / Python** | `fastapi`, `python-performance-optimization` | Pydantic v2, async SQLAlchemy |
|
||||
| **Architecture** | `architecture-patterns` | Clean, Hexagonal, DDD |
|
||||
| **Authentication** | `better-auth-best-practices`, `email-and-password-best-practices`, `two-factor-authentication-best-practices` | Better-Auth patterns |
|
||||
| **UI / Styling** | `tailwind-design-system`, `ui-animation`, `web-design-guidelines` | Tailwind v4 |
|
||||
| **Frontend design** | `frontend-design`, `brand-guidelines`, `canvas-design` | Design principles |
|
||||
| **TDD / Testing** | `test-driven-development`, `webapp-testing`, `vue-testing-best-practices` | Red-Green-Refactor |
|
||||
| **Linting** | `lint` | Zero-tolerance — detect linter, fix ALL violations, never disable rules |
|
||||
| **Code review** | `pr-reviewer`, `code-review-excellence`, `verification-before-completion` | Platform-aware (Gitea/GitHub) |
|
||||
| **Debugging** | `systematic-debugging` | Structured methodology |
|
||||
| **Git workflow** | `finishing-a-development-branch`, `using-git-worktrees` | Branch + worktree patterns |
|
||||
| **Document generation** | `pdf`, `docx`, `pptx`, `xlsx` | LibreOffice-based |
|
||||
| **Writing / Comms** | `doc-coauthoring`, `internal-comms`, `copywriting`, `copy-editing` | |
|
||||
| **Marketing** | `marketing-ideas`, `content-strategy`, `social-content`, `email-sequence` | 139 ideas across 14 categories |
|
||||
| **SEO** | `seo-audit`, `programmatic-seo`, `schema-markup` | Technical + content SEO |
|
||||
| **CRO / Conversion** | `page-cro`, `form-cro`, `signup-flow-cro`, `onboarding-cro` | Conversion optimization |
|
||||
| **Pricing / Business** | `pricing-strategy`, `launch-strategy`, `competitor-alternatives` | SaaS focus |
|
||||
| **Ads / Growth** | `paid-ads`, `analytics-tracking`, `ab-test-setup`, `referral-program` | |
|
||||
| **Agent building** | `create-agent`, `ai-sdk`, `proactive-agent`, `dispatching-parallel-agents` | WAL Protocol, parallel workers |
|
||||
| **Agent workflow** | `executing-plans`, `writing-plans`, `brainstorming` | Plan → execute |
|
||||
| **Skill authoring** | `writing-skills`, `skill-creator` | TDD-based skill creation |
|
||||
| **MCP servers** | `mcp-builder` | Model Context Protocol |
|
||||
| **Generative art** | `algorithmic-art`, `theme-factory`, `slack-gif-creator` | |
|
||||
| **Web artifacts** | `web-artifacts-builder` | Self-contained HTML |
|
||||
| **CI/CD setup** | `setup-cicd` | Docker build/push pipeline |
|
||||
| **Jarvis Brain** | `jarvis` | Brain repo context |
|
||||
| **PRD creation** | `prd` | Generate PRDs |
|
||||
| **Ralph development** | `ralph` | Autonomous dev agent |
|
||||
| **Orchestration** | `kickstart` | `/kickstart [milestone\|issue\|task]` — launches orchestrator |
|
||||
|
||||
### For Orchestrator / Programmatic Workers
|
||||
|
||||
When spawning workers, include skill loading in the kickstart:
|
||||
```bash
|
||||
claude -p "Read ~/.config/mosaic/skills/nestjs-best-practices/SKILL.md then implement..."
|
||||
codex exec "Read ~/.config/mosaic/skills/nestjs-best-practices/SKILL.md then implement..."
|
||||
```
|
||||
|
||||
For Ralph prd.json stories, add a `skills` field:
|
||||
```json
|
||||
{ "id": "US-001", "skills": ["nestjs-best-practices", "test-driven-development"], ... }
|
||||
```
|
||||
|
||||
### Fresh Machine Setup
|
||||
```bash
|
||||
npx skills add https://git.mosaicstack.dev/mosaic/agent-skills.git --agent claude-code
|
||||
```
|
||||
|
||||
## Ralph Autonomous Development
|
||||
|
||||
For autonomous feature development, use the Ralph pattern. Each iteration is a fresh context with persistent memory.
|
||||
|
||||
### The Ralph Loop
|
||||
```
|
||||
1. Read prd.json → Find highest priority story where passes: false
|
||||
2. Read progress.txt → Check "Codebase Patterns" section first
|
||||
3. Read AGENTS.md files → Check directory-specific patterns
|
||||
4. Implement ONLY the single assigned story
|
||||
5. Run quality checks (typecheck, lint, test)
|
||||
6. Commit ONLY if all checks pass
|
||||
7. Update prd.json → Set passes: true for completed story
|
||||
8. Append learnings to progress.txt
|
||||
9. Update AGENTS.md if reusable patterns discovered
|
||||
10. Loop → Next story
|
||||
```
|
||||
|
||||
### Memory Files
|
||||
| File | Purpose | Location |
|
||||
|------|---------|----------|
|
||||
| `prd.json` | Task list with passes: true/false | Project root or scripts/ralph/ |
|
||||
| `progress.txt` | Learnings between iterations | Same as prd.json |
|
||||
| `AGENTS.md` | Directory-specific patterns | Any directory in repo |
|
||||
|
||||
### Running Ralph
|
||||
```bash
|
||||
# Automated loop
|
||||
./scripts/ralph/ralph.sh 10
|
||||
|
||||
# Manual single story
|
||||
claude -p "Implement US-001 from prd.json following Ralph pattern"
|
||||
```
|
||||
|
||||
### Creating New Features
|
||||
1. Create PRD: `Load the prd skill and create a PRD for [feature]`
|
||||
2. Convert to Ralph: `Load the ralph skill and convert tasks/prd-[name].md to prd.json`
|
||||
3. Run Ralph: `./scripts/ralph/ralph.sh`
|
||||
|
||||
**For full Ralph guide:** `~/.config/mosaic/guides/ralph-autonomous.md`
|
||||
|
||||
## Project-Local AGENTS.md Pattern
|
||||
|
||||
Each directory can have an `AGENTS.md` file containing patterns specific to that area of the codebase. **Always check for and read AGENTS.md files in directories you're working in.**
|
||||
|
||||
```markdown
|
||||
# Example AGENTS.md
|
||||
|
||||
## Codebase Patterns
|
||||
- Use `httpx.AsyncClient` for external HTTP calls
|
||||
- All routes require authentication via `Depends(get_current_user)`
|
||||
|
||||
## Common Gotchas
|
||||
- Remember to run migrations after schema changes
|
||||
- Frontend env vars need NEXT_PUBLIC_ prefix
|
||||
```
|
||||
|
||||
**Update AGENTS.md when you discover:**
|
||||
- Reusable patterns
|
||||
- Non-obvious requirements
|
||||
- Gotchas that would trip up future agents
|
||||
- Testing approaches for that area
|
||||
|
||||
## Project Bootstrapping
|
||||
|
||||
When starting work on a **new project** that lacks an `AGENTS.md`, bootstrap it:
|
||||
|
||||
```bash
|
||||
# Automated (recommended)
|
||||
~/.config/mosaic/rails/bootstrap/init-project.sh --name "Project Name" --type auto
|
||||
|
||||
# Or manually with templates
|
||||
export PROJECT_NAME="Project Name" PROJECT_DESCRIPTION="What it does" TASK_PREFIX="PN"
|
||||
envsubst < ~/.config/mosaic/templates/agent/AGENTS.md.template > AGENTS.md
|
||||
```
|
||||
|
||||
**Available project types:** `nestjs-nextjs`, `django`, `typescript`, `python-fastapi`, `python-library`, `generic` (auto-detected from project files).
|
||||
|
||||
**Templates:** `~/.config/mosaic/templates/agent/` (generic) and `~/.config/mosaic/templates/agent/projects/<type>/` (tech-stack specific).
|
||||
|
||||
**Fragments:** `~/.config/mosaic/templates/agent/fragments/` — Reusable sections (conditional-loading, commit-format, secrets, multi-agent, code-review).
|
||||
|
||||
**Full guide:** `~/.config/mosaic/guides/bootstrap.md`
|
||||
|
||||
### Agent Configuration Health
|
||||
|
||||
```bash
|
||||
# Audit all projects for missing AGENTS.md, agent-guide references
|
||||
~/.config/mosaic/rails/bootstrap/agent-lint.sh
|
||||
|
||||
# Audit with fix suggestions
|
||||
~/.config/mosaic/rails/bootstrap/agent-lint.sh --verbose --fix-hint
|
||||
|
||||
# Non-destructively upgrade existing projects (inject missing sections)
|
||||
~/.config/mosaic/rails/bootstrap/agent-upgrade.sh --all --dry-run # Preview
|
||||
~/.config/mosaic/rails/bootstrap/agent-upgrade.sh --all # Apply
|
||||
|
||||
# Upgrade a single project
|
||||
~/.config/mosaic/rails/bootstrap/agent-upgrade.sh ~/src/my-project
|
||||
```
|
||||
|
||||
**Spec:** `~/.config/mosaic/templates/agent/SPEC.md` — Defines Tier 1/2/3 requirements for well-configured projects.
|
||||
|
||||
## Issue Tracking (Git-Based)
|
||||
|
||||
All work is tracked as **issues in the project's git repository** (Gitea or GitHub).
|
||||
|
||||
### Workflow
|
||||
1. Check for assigned issues before starting work
|
||||
2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
|
||||
3. Reference issues in commits: `Fixes #123` or `Refs #123`
|
||||
4. Close issues only after successful testing
|
||||
|
||||
### Labels
|
||||
Use consistent labels across projects:
|
||||
- `epic` - Large feature spanning multiple issues
|
||||
- `feature` - New functionality
|
||||
- `bug` - Defect fix
|
||||
- `task` - General work item
|
||||
- `documentation` - Docs updates
|
||||
- `security` - Security-related
|
||||
- `breaking` - Breaking change
|
||||
|
||||
### Milestones & Versioning
|
||||
- **Each feature gets a dedicated milestone**
|
||||
- MVP starts at `0.1.0`
|
||||
- Pre-release: `0.X.0` for breaking changes, `0.X.Y` for patches
|
||||
- Post-release: `X.0.0` for breaking changes
|
||||
|
||||
### Git Scripts (PREFERRED for Gitea/GitHub operations)
|
||||
Cross-platform helpers at `~/.config/mosaic/rails/git/` (work with both Gitea and GitHub):
|
||||
|
||||
**Why use these scripts?**
|
||||
- Auto-detect platform (Gitea vs GitHub)
|
||||
- Abstract CLI syntax differences (tea vs gh)
|
||||
- Handle milestone name filtering for Gitea
|
||||
- Consistent interface across all repos
|
||||
|
||||
**Issues:**
|
||||
```bash
|
||||
~/.config/mosaic/rails/git/issue-create.sh -t "Title" -l "label" -m "0.2.0"
|
||||
~/.config/mosaic/rails/git/issue-list.sh -s open -l "bug"
|
||||
~/.config/mosaic/rails/git/issue-list.sh -m "M6-AgentOrchestration"
|
||||
~/.config/mosaic/rails/git/issue-view.sh -i 42
|
||||
~/.config/mosaic/rails/git/issue-edit.sh -i 42 -t "New Title" -l "labels"
|
||||
~/.config/mosaic/rails/git/issue-assign.sh -i 42 -a "username"
|
||||
~/.config/mosaic/rails/git/issue-comment.sh -i 42 -c "Comment text"
|
||||
~/.config/mosaic/rails/git/issue-close.sh -i 42 [-c "Closing comment"]
|
||||
~/.config/mosaic/rails/git/issue-reopen.sh -i 42 [-c "Reopening reason"]
|
||||
```
|
||||
|
||||
**Pull Requests:**
|
||||
```bash
|
||||
~/.config/mosaic/rails/git/pr-create.sh -t "Title" -b "Description" -i 42
|
||||
~/.config/mosaic/rails/git/pr-create.sh -t "Title" -B main -H feature-branch
|
||||
~/.config/mosaic/rails/git/pr-list.sh -s open
|
||||
~/.config/mosaic/rails/git/pr-view.sh -n 42
|
||||
~/.config/mosaic/rails/git/pr-review.sh -n 42 -a approve [-c "LGTM"]
|
||||
~/.config/mosaic/rails/git/pr-review.sh -n 42 -a request-changes -c "Fix X"
|
||||
~/.config/mosaic/rails/git/pr-merge.sh -n 42 -m squash -d
|
||||
~/.config/mosaic/rails/git/pr-close.sh -n 42 [-c "Closing reason"]
|
||||
~/.config/mosaic/rails/git/pr-diff.sh -n 42 [-o diff.patch]
|
||||
~/.config/mosaic/rails/git/pr-metadata.sh -n 42 [-o metadata.json]
|
||||
```
|
||||
|
||||
**Milestones:**
|
||||
```bash
|
||||
~/.config/mosaic/rails/git/milestone-create.sh -t "0.2.0" -d "Description"
|
||||
~/.config/mosaic/rails/git/milestone-create.sh --list
|
||||
~/.config/mosaic/rails/git/milestone-list.sh [-s open|closed|all]
|
||||
~/.config/mosaic/rails/git/milestone-close.sh -t "0.2.0"
|
||||
```
|
||||
|
||||
**NOTE:** These scripts handle the Gitea `--milestones` (plural) syntax automatically. Always prefer these over raw `tea` or `gh` commands.
|
||||
|
||||
### Woodpecker CI CLI
|
||||
Official CLI for interacting with Woodpecker CI at `ci.mosaicstack.dev`.
|
||||
|
||||
**Setup:**
|
||||
```bash
|
||||
# Install (Arch)
|
||||
paru -S woodpecker
|
||||
|
||||
# Configure
|
||||
export WOODPECKER_SERVER="https://ci.mosaicstack.dev"
|
||||
export WOODPECKER_TOKEN="your-token" # Get from ci.mosaicstack.dev/user
|
||||
```
|
||||
|
||||
**Pipelines:**
|
||||
```bash
|
||||
woodpecker pipeline ls <owner/repo> # List pipelines
|
||||
woodpecker pipeline info <owner/repo> <num> # Pipeline details
|
||||
woodpecker pipeline create <owner/repo> # Trigger pipeline
|
||||
woodpecker pipeline stop <owner/repo> <num> # Cancel pipeline
|
||||
woodpecker pipeline start <owner/repo> <num> # Restart pipeline
|
||||
woodpecker pipeline approve <owner/repo> <num> # Approve blocked
|
||||
```
|
||||
|
||||
**Logs:**
|
||||
```bash
|
||||
woodpecker log show <owner/repo> <num> # View logs
|
||||
woodpecker log show <owner/repo> <num> <step> # Specific step
|
||||
```
|
||||
|
||||
**Repositories:**
|
||||
```bash
|
||||
woodpecker repo ls # List repos
|
||||
woodpecker repo add <owner/repo> # Activate for CI
|
||||
woodpecker repo rm <owner/repo> # Deactivate
|
||||
woodpecker repo repair <owner/repo> # Repair webhooks
|
||||
```
|
||||
|
||||
**Secrets:**
|
||||
```bash
|
||||
woodpecker secret ls <owner/repo> # List secrets
|
||||
woodpecker secret add <owner/repo> -n KEY -v val # Add secret
|
||||
woodpecker secret rm <owner/repo> -n KEY # Delete secret
|
||||
```
|
||||
|
||||
**Full reference:** `jarvis-brain/docs/reference/woodpecker/WOODPECKER-CLI.md`
|
||||
**Setup command:** `woodpecker setup --server https://ci.mosaicstack.dev --token "YOUR_TOKEN"`
|
||||
|
||||
### Portainer Scripts
|
||||
CLI tools for managing Portainer stacks at `~/.config/mosaic/rails/portainer/`.
|
||||
|
||||
**Setup:**
|
||||
```bash
|
||||
export PORTAINER_URL="https://portainer.example.com:9443"
|
||||
export PORTAINER_API_KEY="your-api-key-here"
|
||||
```
|
||||
|
||||
Create an API key in Portainer: My account → Access tokens → Add access token.
|
||||
|
||||
**Stack Management:**
|
||||
```bash
|
||||
stack-list.sh # List all stacks
|
||||
stack-list.sh -f json # JSON format
|
||||
stack-list.sh -e 1 # Filter by endpoint
|
||||
|
||||
stack-status.sh -n mystack # Show stack status
|
||||
stack-status.sh -n mystack -f json # JSON format
|
||||
|
||||
stack-redeploy.sh -n mystack # Redeploy stack
|
||||
stack-redeploy.sh -n mystack -p # Pull latest images
|
||||
|
||||
stack-start.sh -n mystack # Start inactive stack
|
||||
stack-stop.sh -n mystack # Stop running stack
|
||||
```
|
||||
|
||||
**Logs:**
|
||||
```bash
|
||||
stack-logs.sh -n mystack # List services
|
||||
stack-logs.sh -n mystack -s webapp # View service logs
|
||||
stack-logs.sh -n mystack -s webapp -t 200 # Last 200 lines
|
||||
stack-logs.sh -n mystack -s webapp -f # Follow logs
|
||||
```
|
||||
|
||||
**Endpoints:**
|
||||
```bash
|
||||
endpoint-list.sh # List all endpoints
|
||||
endpoint-list.sh -f json # JSON format
|
||||
```
|
||||
|
||||
**Common Workflow (CI/CD redeploy):**
|
||||
```bash
|
||||
~/.config/mosaic/rails/portainer/stack-redeploy.sh -n myapp -p && \
|
||||
~/.config/mosaic/rails/portainer/stack-status.sh -n myapp && \
|
||||
~/.config/mosaic/rails/portainer/stack-logs.sh -n myapp -s api -t 50
|
||||
```
|
||||
|
||||
### Git Worktrees
|
||||
Use worktrees for parallel work on multiple issues without branch switching.
|
||||
|
||||
**Structure:**
|
||||
```
|
||||
{project_name}_worktrees/{issue-name}/
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```
|
||||
~/src/my-app/ # Main repository
|
||||
~/src/my-app_worktrees/
|
||||
├── 42-fix-login/ # Worktree for issue #42
|
||||
├── 57-add-dashboard/ # Worktree for issue #57
|
||||
└── 89-refactor-auth/ # Worktree for issue #89
|
||||
```
|
||||
|
||||
**Commands:**
|
||||
```bash
|
||||
# Create worktree for an issue
|
||||
git worktree add ../my-app_worktrees/42-fix-login -b issue-42-fix-login
|
||||
|
||||
# List active worktrees
|
||||
git worktree list
|
||||
|
||||
# Remove worktree after merge
|
||||
git worktree remove ../my-app_worktrees/42-fix-login
|
||||
```
|
||||
|
||||
**When to use worktrees:**
|
||||
- Working on multiple issues simultaneously
|
||||
- Long-running feature branches that need isolation
|
||||
- Code reviews while continuing other work
|
||||
- Comparing implementations across branches
|
||||
|
||||
## Development Requirements
|
||||
|
||||
### Test-Driven Development (TDD)
|
||||
1. Write tests BEFORE implementation
|
||||
2. Minimum **85% coverage**
|
||||
3. Build and test after EVERY change
|
||||
4. Task completion requires passing tests
|
||||
|
||||
### Linting (MANDATORY)
|
||||
**Run the project linter after every code change. Fix ALL violations. Zero tolerance.**
|
||||
- Never disable lint rules (`eslint-disable`, `noqa`, `nolint`)
|
||||
- Never leave warnings — warnings are errors you haven't fixed yet
|
||||
- If you touched a file, you own its lint violations (Campsite Rule)
|
||||
- If unsure what linter the project uses, read the `lint` skill: `~/.config/mosaic/skills/lint/SKILL.md`
|
||||
|
||||
### Code Style
|
||||
Follow [Google Style Guides](https://github.com/google/styleguide) for all languages.
|
||||
|
||||
### Commits
|
||||
```
|
||||
<type>(#issue): Brief description
|
||||
|
||||
Detailed explanation if needed.
|
||||
|
||||
Fixes #123
|
||||
```
|
||||
Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
|
||||
|
||||
## Scratchpad Format
|
||||
|
||||
When working on issue #N, create `docs/scratchpads/N-short-name.md`:
|
||||
|
||||
```markdown
|
||||
# Issue #N: Title
|
||||
|
||||
## Objective
|
||||
[What this issue accomplishes]
|
||||
|
||||
## Approach
|
||||
[Implementation plan]
|
||||
|
||||
## Progress
|
||||
- [ ] Step 1
|
||||
- [ ] Step 2
|
||||
|
||||
## Testing
|
||||
[Test plan and results]
|
||||
|
||||
## Notes
|
||||
[Findings, blockers, decisions]
|
||||
```
|
||||
|
||||
## Conditional Context
|
||||
|
||||
**Read the relevant guide before starting work:**
|
||||
|
||||
| Task Type | Guide |
|
||||
|-----------|-------|
|
||||
| Bootstrapping a new project | `~/.config/mosaic/guides/bootstrap.md` |
|
||||
| Orchestrating autonomous task completion | `~/.config/mosaic/guides/orchestrator.md` |
|
||||
| Ralph autonomous development | `~/.config/mosaic/guides/ralph-autonomous.md` |
|
||||
| Frontend development | `~/.config/mosaic/guides/frontend.md` |
|
||||
| Backend/API development | `~/.config/mosaic/guides/backend.md` |
|
||||
| Code review | `~/.config/mosaic/guides/code-review.md` |
|
||||
| Authentication/Authorization | `~/.config/mosaic/guides/authentication.md` |
|
||||
| CI/CD pipelines & Docker builds | `~/.config/mosaic/guides/ci-cd-pipelines.md` |
|
||||
| Infrastructure/DevOps | `~/.config/mosaic/guides/infrastructure.md` |
|
||||
| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
|
||||
| Secrets management | See section below |
|
||||
|
||||
**Project-specific skills:**
|
||||
|
||||
| Project | Skill |
|
||||
|---------|-------|
|
||||
| jetrich/jarvis | `~/.config/mosaic/skills/jarvis/SKILL.md` |
|
||||
|
||||
## Secrets Management
|
||||
|
||||
**NEVER hardcode secrets in the codebase.** Choose the appropriate method based on your environment.
|
||||
|
||||
### If Using Vault
|
||||
See `~/.config/mosaic/guides/vault-secrets.md` for the canonical structure and rules.
|
||||
|
||||
Quick reference:
|
||||
```
|
||||
{mount}/{service}/{component}/{secret-name}
|
||||
Example: secret-prod/postgres/database/app
|
||||
```
|
||||
|
||||
### If NOT Using Vault (Use .env Files)
|
||||
|
||||
**Structure:**
|
||||
```
|
||||
project-root/
|
||||
├── .env.example # Template with placeholder values (committed)
|
||||
├── .env # Local secrets (NEVER committed)
|
||||
├── .env.development # Dev overrides (optional, not committed)
|
||||
├── .env.test # Test environment (optional, not committed)
|
||||
└── .gitignore # Must include .env*
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
1. **ALWAYS** add `.env*` to `.gitignore` (except `.env.example`)
|
||||
2. Create `.env.example` with all required variables and placeholder values
|
||||
3. Use descriptive variable names: `DATABASE_URL`, `API_SECRET_KEY`
|
||||
4. Document required variables in README
|
||||
5. Load via `dotenv` or framework-native methods
|
||||
|
||||
**.env.example template:**
|
||||
```bash
|
||||
# Database
|
||||
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
|
||||
DATABASE_POOL_SIZE=10
|
||||
|
||||
# Authentication
|
||||
JWT_SECRET_KEY=your-secret-key-here
|
||||
JWT_EXPIRY_SECONDS=3600
|
||||
|
||||
# External APIs
|
||||
STRIPE_API_KEY=sk_test_xxx
|
||||
SENDGRID_API_KEY=SG.xxx
|
||||
|
||||
# App Config
|
||||
APP_ENV=development
|
||||
DEBUG=false
|
||||
```
|
||||
|
||||
**Loading secrets:**
|
||||
```python
|
||||
# Python
|
||||
from dotenv import load_dotenv
|
||||
load_dotenv()
|
||||
|
||||
# Node.js
|
||||
import 'dotenv/config';
|
||||
|
||||
# Or use framework-native (Next.js, NestJS, etc.)
|
||||
```
|
||||
|
||||
### Security Rules (All Environments)
|
||||
1. **Never commit secrets** - Use .env or Vault
|
||||
2. **Never log secrets** - Mask in logs if needed
|
||||
3. **Rotate compromised secrets immediately**
|
||||
4. **Use different secrets per environment**
|
||||
5. **Validate secrets exist at startup** - Fail fast if missing
|
||||
|
||||
## Multi-Agent Coordination
|
||||
|
||||
When launching concurrent agents:
|
||||
```bash
|
||||
nohup claude -p "<instruction>" > logs/agent-{name}.log 2>&1 &
|
||||
```
|
||||
|
||||
- Maximum 10 simultaneous agents
|
||||
- Monitor for errors and permission issues
|
||||
- Restart failed agents after fixing issues
|
||||
|
||||
**For Ralph multi-agent:**
|
||||
- Use worktrees for isolation
|
||||
- Each agent works on different story
|
||||
- Coordinate via git (frequent pulls)
|
||||
|
||||
## Dev Server Infrastructure (web1.corp.uscllc.local)
|
||||
|
||||
### Shared Traefik Reverse Proxy
|
||||
|
||||
A shared Traefik instance handles routing for all dev/test services on this server.
|
||||
|
||||
**Location:** `~/src/traefik`
|
||||
|
||||
**Start Traefik:**
|
||||
```bash
|
||||
cd ~/src/traefik
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
**Dashboard:** http://localhost:8080
|
||||
|
||||
### Connecting Services to Traefik
|
||||
|
||||
Add to your service's `docker-compose.yml`:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
app:
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.myapp.rule=Host(`myapp.uscllc.com`)"
|
||||
- "traefik.http.routers.myapp.entrypoints=websecure"
|
||||
- "traefik.http.routers.myapp.tls=true"
|
||||
- "traefik.http.services.myapp.loadbalancer.server.port=3000"
|
||||
networks:
|
||||
- internal
|
||||
- traefik-public
|
||||
|
||||
networks:
|
||||
internal:
|
||||
driver: bridge
|
||||
traefik-public:
|
||||
external: true
|
||||
```
|
||||
|
||||
**Note:** Uses self-signed wildcard cert - browsers will show security warning.
|
||||
|
||||
### Active Dev Services
|
||||
|
||||
| Service | Domain | Repository |
|
||||
|---------|--------|------------|
|
||||
| Inventory Stickers | inventory.uscllc.com | ~/src/sticker-app |
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
project-root/
|
||||
├── AGENTS.md # Codebase patterns for AI agents
|
||||
├── docs/
|
||||
│ └── scratchpads/ # Agent working documents
|
||||
│ └── {issue#}-{name}.md
|
||||
├── scripts/
|
||||
│ └── ralph/ # Ralph autonomous development
|
||||
│ ├── ralph.sh # Loop script
|
||||
│ ├── prd.json # Current feature tasks
|
||||
│ └── progress.txt # Memory between iterations
|
||||
├── tasks/ # PRD documents
|
||||
│ └── prd-{feature}.md
|
||||
├── logs/ # Log files
|
||||
└── tests/ # Test files
|
||||
```
|
||||
47
bin/mosaic
47
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 <command> [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 "$@"
|
||||
}
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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 <command> [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
|
||||
}
|
||||
|
||||
@@ -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-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:
|
||||
```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/<type>/` (tech-stack specific).
|
||||
|
||||
**Fragments:** `~/.config/mosaic/templates/agent/fragments/` — Reusable sections (conditional-loading, commit-format, secrets, multi-agent, code-review).
|
||||
|
||||
**Full guide:** `~/.config/mosaic/guides/bootstrap.md`
|
||||
|
||||
### Agent Configuration Health
|
||||
|
||||
```bash
|
||||
# Audit all projects for missing 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 <owner/repo> # List pipelines
|
||||
woodpecker pipeline info <owner/repo> <num> # Pipeline details
|
||||
woodpecker pipeline create <owner/repo> # Trigger pipeline
|
||||
woodpecker pipeline stop <owner/repo> <num> # Cancel pipeline
|
||||
woodpecker pipeline start <owner/repo> <num> # Restart pipeline
|
||||
woodpecker pipeline approve <owner/repo> <num> # Approve blocked
|
||||
```
|
||||
|
||||
**Logs:**
|
||||
```bash
|
||||
woodpecker log show <owner/repo> <num> # View logs
|
||||
woodpecker log show <owner/repo> <num> <step> # Specific step
|
||||
```
|
||||
|
||||
**Repositories:**
|
||||
```bash
|
||||
woodpecker repo ls # List repos
|
||||
woodpecker repo add <owner/repo> # Activate for CI
|
||||
woodpecker repo rm <owner/repo> # Deactivate
|
||||
woodpecker repo repair <owner/repo> # Repair webhooks
|
||||
```
|
||||
|
||||
**Secrets:**
|
||||
```bash
|
||||
woodpecker secret ls <owner/repo> # List secrets
|
||||
woodpecker secret add <owner/repo> -n KEY -v val # Add secret
|
||||
woodpecker secret rm <owner/repo> -n KEY # Delete secret
|
||||
```
|
||||
|
||||
**Full reference:** `jarvis-brain/docs/reference/woodpecker/WOODPECKER-CLI.md`
|
||||
**Setup command:** `woodpecker setup --server https://ci.mosaicstack.dev --token "YOUR_TOKEN"`
|
||||
|
||||
### Portainer Scripts
|
||||
CLI tools for managing Portainer stacks at `~/.config/mosaic/rails/portainer/`.
|
||||
|
||||
**Setup:**
|
||||
```bash
|
||||
export PORTAINER_URL="https://portainer.example.com:9443"
|
||||
export PORTAINER_API_KEY="your-api-key-here"
|
||||
```
|
||||
|
||||
Create an API key in Portainer: My account → Access tokens → Add access token.
|
||||
|
||||
**Stack Management:**
|
||||
```bash
|
||||
stack-list.sh # List all stacks
|
||||
stack-list.sh -f json # JSON format
|
||||
stack-list.sh -e 1 # Filter by endpoint
|
||||
|
||||
stack-status.sh -n mystack # Show stack status
|
||||
stack-status.sh -n mystack -f json # JSON format
|
||||
|
||||
stack-redeploy.sh -n mystack # Redeploy stack
|
||||
stack-redeploy.sh -n mystack -p # Pull latest images
|
||||
|
||||
stack-start.sh -n mystack # Start inactive stack
|
||||
stack-stop.sh -n mystack # Stop running stack
|
||||
```
|
||||
|
||||
**Logs:**
|
||||
```bash
|
||||
stack-logs.sh -n mystack # List services
|
||||
stack-logs.sh -n mystack -s webapp # View service logs
|
||||
stack-logs.sh -n mystack -s webapp -t 200 # Last 200 lines
|
||||
stack-logs.sh -n mystack -s webapp -f # Follow logs
|
||||
```
|
||||
|
||||
**Endpoints:**
|
||||
```bash
|
||||
endpoint-list.sh # List all endpoints
|
||||
endpoint-list.sh -f json # JSON format
|
||||
```
|
||||
|
||||
**Common Workflow (CI/CD redeploy):**
|
||||
```bash
|
||||
~/.config/mosaic/rails/portainer/stack-redeploy.sh -n myapp -p && \
|
||||
~/.config/mosaic/rails/portainer/stack-status.sh -n myapp && \
|
||||
~/.config/mosaic/rails/portainer/stack-logs.sh -n myapp -s api -t 50
|
||||
```
|
||||
|
||||
### Git Worktrees
|
||||
Use worktrees for parallel work on multiple issues without branch switching.
|
||||
|
||||
**Structure:**
|
||||
```
|
||||
{project_name}_worktrees/{issue-name}/
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```
|
||||
~/src/my-app/ # Main repository
|
||||
~/src/my-app_worktrees/
|
||||
├── 42-fix-login/ # Worktree for issue #42
|
||||
├── 57-add-dashboard/ # Worktree for issue #57
|
||||
└── 89-refactor-auth/ # Worktree for issue #89
|
||||
```
|
||||
|
||||
**Commands:**
|
||||
```bash
|
||||
# Create worktree for an issue
|
||||
git worktree add ../my-app_worktrees/42-fix-login -b issue-42-fix-login
|
||||
|
||||
# List active worktrees
|
||||
git worktree list
|
||||
|
||||
# Remove worktree after merge
|
||||
git worktree remove ../my-app_worktrees/42-fix-login
|
||||
```
|
||||
|
||||
**When to use worktrees:**
|
||||
- Working on multiple issues simultaneously
|
||||
- Long-running feature branches that need isolation
|
||||
- Code reviews while continuing other work
|
||||
- Comparing implementations across branches
|
||||
|
||||
## Development Requirements
|
||||
|
||||
### Test-Driven Development (TDD)
|
||||
1. Write tests BEFORE implementation
|
||||
2. Minimum **85% coverage**
|
||||
3. Build and test after EVERY change
|
||||
4. Task completion requires passing tests
|
||||
|
||||
### Linting (MANDATORY)
|
||||
**Run the project linter after every code change. Fix ALL violations. Zero tolerance.**
|
||||
- Never disable lint rules (`eslint-disable`, `noqa`, `nolint`)
|
||||
- Never leave warnings — warnings are errors you haven't fixed yet
|
||||
- If you touched a file, you own its lint violations (Campsite Rule)
|
||||
- If unsure what linter the project uses, read the `lint` skill: `~/.config/mosaic/skills/lint/SKILL.md`
|
||||
|
||||
### Code Style
|
||||
Follow [Google Style Guides](https://github.com/google/styleguide) for all languages.
|
||||
|
||||
### Commits
|
||||
```
|
||||
<type>(#issue): Brief description
|
||||
|
||||
Detailed explanation if needed.
|
||||
|
||||
Fixes #123
|
||||
```
|
||||
Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
|
||||
|
||||
## Scratchpad Format
|
||||
|
||||
When working on issue #N, create `docs/scratchpads/N-short-name.md`:
|
||||
|
||||
```markdown
|
||||
# Issue #N: Title
|
||||
|
||||
## Objective
|
||||
[What this issue accomplishes]
|
||||
|
||||
## Approach
|
||||
[Implementation plan]
|
||||
|
||||
## Progress
|
||||
- [ ] Step 1
|
||||
- [ ] Step 2
|
||||
|
||||
## Testing
|
||||
[Test plan and results]
|
||||
|
||||
## Notes
|
||||
[Findings, blockers, decisions]
|
||||
```
|
||||
|
||||
## Conditional Context
|
||||
|
||||
**Read the relevant guide before starting work:**
|
||||
|
||||
| Task Type | Guide |
|
||||
|-----------|-------|
|
||||
| Bootstrapping a new project | `~/.config/mosaic/guides/bootstrap.md` |
|
||||
| Orchestrating autonomous task completion | `~/.config/mosaic/guides/orchestrator.md` |
|
||||
| Ralph autonomous development | `~/.config/mosaic/guides/ralph-autonomous.md` |
|
||||
| Frontend development | `~/.config/mosaic/guides/frontend.md` |
|
||||
| Backend/API development | `~/.config/mosaic/guides/backend.md` |
|
||||
| Code review | `~/.config/mosaic/guides/code-review.md` |
|
||||
| Authentication/Authorization | `~/.config/mosaic/guides/authentication.md` |
|
||||
| CI/CD pipelines & Docker builds | `~/.config/mosaic/guides/ci-cd-pipelines.md` |
|
||||
| Infrastructure/DevOps | `~/.config/mosaic/guides/infrastructure.md` |
|
||||
| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
|
||||
| Secrets management | See section below |
|
||||
|
||||
**Project-specific skills:**
|
||||
|
||||
| Project | Skill |
|
||||
|---------|-------|
|
||||
| jetrich/jarvis | `~/.config/mosaic/skills/jarvis/SKILL.md` |
|
||||
|
||||
## Secrets Management
|
||||
|
||||
**NEVER hardcode secrets in the codebase.** Choose the appropriate method based on your environment.
|
||||
|
||||
### If Using Vault
|
||||
See `~/.config/mosaic/guides/vault-secrets.md` for the canonical structure and rules.
|
||||
|
||||
Quick reference:
|
||||
```
|
||||
{mount}/{service}/{component}/{secret-name}
|
||||
Example: secret-prod/postgres/database/app
|
||||
```
|
||||
|
||||
### If NOT Using Vault (Use .env Files)
|
||||
|
||||
**Structure:**
|
||||
```
|
||||
project-root/
|
||||
├── .env.example # Template with placeholder values (committed)
|
||||
├── .env # Local secrets (NEVER committed)
|
||||
├── .env.development # Dev overrides (optional, not committed)
|
||||
├── .env.test # Test environment (optional, not committed)
|
||||
└── .gitignore # Must include .env*
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
1. **ALWAYS** add `.env*` to `.gitignore` (except `.env.example`)
|
||||
2. Create `.env.example` with all required variables and placeholder values
|
||||
3. Use descriptive variable names: `DATABASE_URL`, `API_SECRET_KEY`
|
||||
4. Document required variables in README
|
||||
5. Load via `dotenv` or framework-native methods
|
||||
|
||||
**.env.example template:**
|
||||
```bash
|
||||
# Database
|
||||
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
|
||||
DATABASE_POOL_SIZE=10
|
||||
|
||||
# Authentication
|
||||
JWT_SECRET_KEY=your-secret-key-here
|
||||
JWT_EXPIRY_SECONDS=3600
|
||||
|
||||
# External APIs
|
||||
STRIPE_API_KEY=sk_test_xxx
|
||||
SENDGRID_API_KEY=SG.xxx
|
||||
|
||||
# App Config
|
||||
APP_ENV=development
|
||||
DEBUG=false
|
||||
```
|
||||
|
||||
**Loading secrets:**
|
||||
```python
|
||||
# Python
|
||||
from dotenv import load_dotenv
|
||||
load_dotenv()
|
||||
|
||||
# Node.js
|
||||
import 'dotenv/config';
|
||||
|
||||
# Or use framework-native (Next.js, NestJS, etc.)
|
||||
```
|
||||
|
||||
### Security Rules (All Environments)
|
||||
1. **Never commit secrets** - Use .env or Vault
|
||||
2. **Never log secrets** - Mask in logs if needed
|
||||
3. **Rotate compromised secrets immediately**
|
||||
4. **Use different secrets per environment**
|
||||
5. **Validate secrets exist at startup** - Fail fast if missing
|
||||
|
||||
## Multi-Agent Coordination
|
||||
|
||||
When launching concurrent agents:
|
||||
```bash
|
||||
nohup claude -p "<instruction>" > logs/agent-{name}.log 2>&1 &
|
||||
```
|
||||
|
||||
- Maximum 10 simultaneous agents
|
||||
- Monitor for errors and permission issues
|
||||
- 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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user