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
|
# 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:
|
# Usage:
|
||||||
# mosaic claude [args...] Launch Claude Code with SOUL.md injected
|
# mosaic claude [args...] Launch Claude Code with AGENTS.md injected
|
||||||
# mosaic opencode [args...] Launch OpenCode
|
# mosaic opencode [args...] Launch OpenCode with AGENTS.md injected
|
||||||
# mosaic codex [args...] Launch Codex
|
# mosaic codex [args...] Launch Codex with AGENTS.md injected
|
||||||
# mosaic init [args...] Generate SOUL.md interactively
|
# mosaic init [args...] Generate SOUL.md interactively
|
||||||
# mosaic doctor [args...] Health audit
|
# mosaic doctor [args...] Health audit
|
||||||
# mosaic sync [args...] Sync skills
|
# mosaic sync [args...] Sync skills
|
||||||
@@ -22,9 +25,9 @@ mosaic $VERSION — Unified agent launcher
|
|||||||
Usage: mosaic <command> [args...]
|
Usage: mosaic <command> [args...]
|
||||||
|
|
||||||
Agent Launchers:
|
Agent Launchers:
|
||||||
claude [args...] Launch Claude Code with SOUL.md injected
|
claude [args...] Launch Claude Code with AGENTS.md injected
|
||||||
opencode [args...] Launch OpenCode
|
opencode [args...] Launch OpenCode with AGENTS.md injected
|
||||||
codex [args...] Launch Codex
|
codex [args...] Launch Codex with AGENTS.md injected
|
||||||
|
|
||||||
Management:
|
Management:
|
||||||
init [args...] Generate SOUL.md (agent identity contract)
|
init [args...] Generate SOUL.md (agent identity contract)
|
||||||
@@ -49,6 +52,14 @@ check_mosaic_home() {
|
|||||||
fi
|
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() {
|
check_soul() {
|
||||||
if [[ ! -f "$MOSAIC_HOME/SOUL.md" ]]; then
|
if [[ ! -f "$MOSAIC_HOME/SOUL.md" ]]; then
|
||||||
echo "[mosaic] SOUL.md not found. Running mosaic init..."
|
echo "[mosaic] SOUL.md not found. Running mosaic init..."
|
||||||
@@ -65,31 +76,51 @@ check_runtime() {
|
|||||||
fi
|
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
|
# Launcher functions
|
||||||
launch_claude() {
|
launch_claude() {
|
||||||
check_mosaic_home
|
check_mosaic_home
|
||||||
|
check_agents_md
|
||||||
check_soul
|
check_soul
|
||||||
check_runtime "claude"
|
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..."
|
echo "[mosaic] Launching Claude Code..."
|
||||||
exec claude "$@"
|
exec claude --append-system-prompt "$agents_content" "$@"
|
||||||
}
|
}
|
||||||
|
|
||||||
launch_opencode() {
|
launch_opencode() {
|
||||||
check_mosaic_home
|
check_mosaic_home
|
||||||
|
check_agents_md
|
||||||
check_soul
|
check_soul
|
||||||
check_runtime "opencode"
|
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..."
|
echo "[mosaic] Launching OpenCode..."
|
||||||
exec opencode "$@"
|
exec opencode "$@"
|
||||||
}
|
}
|
||||||
|
|
||||||
launch_codex() {
|
launch_codex() {
|
||||||
check_mosaic_home
|
check_mosaic_home
|
||||||
|
check_agents_md
|
||||||
check_soul
|
check_soul
|
||||||
check_runtime "codex"
|
check_runtime "codex"
|
||||||
|
|
||||||
|
# Codex reads from ~/.codex/instructions.md — copy canonical version there
|
||||||
|
ensure_runtime_config "$HOME/.codex/instructions.md"
|
||||||
echo "[mosaic] Launching Codex..."
|
echo "[mosaic] Launching Codex..."
|
||||||
exec codex "$@"
|
exec codex "$@"
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -69,7 +69,7 @@ for p in "${legacy_paths[@]}"; do
|
|||||||
remove_legacy_path "$p"
|
remove_legacy_path "$p"
|
||||||
done
|
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 \
|
for runtime_file in \
|
||||||
CLAUDE.md \
|
CLAUDE.md \
|
||||||
settings.json \
|
settings.json \
|
||||||
@@ -80,13 +80,13 @@ for runtime_file in \
|
|||||||
copy_file_managed "$src" "$HOME/.claude/$runtime_file"
|
copy_file_managed "$src" "$HOME/.claude/$runtime_file"
|
||||||
done
|
done
|
||||||
|
|
||||||
# OpenCode runtime adapter (optional, copied when present).
|
# OpenCode runtime adapter (thin pointer to AGENTS.md)
|
||||||
opencode_adapter="$MOSAIC_HOME/runtime/opencode/AGENTS.md"
|
opencode_adapter="$MOSAIC_HOME/runtime/opencode/AGENTS.md"
|
||||||
if [[ -f "$opencode_adapter" ]]; then
|
if [[ -f "$opencode_adapter" ]]; then
|
||||||
copy_file_managed "$opencode_adapter" "$HOME/.config/opencode/AGENTS.md"
|
copy_file_managed "$opencode_adapter" "$HOME/.config/opencode/AGENTS.md"
|
||||||
fi
|
fi
|
||||||
|
|
||||||
# Codex runtime adapter (optional, copied when present).
|
# Codex runtime adapter (thin pointer to AGENTS.md)
|
||||||
codex_adapter="$MOSAIC_HOME/runtime/codex/instructions.md"
|
codex_adapter="$MOSAIC_HOME/runtime/codex/instructions.md"
|
||||||
if [[ -f "$codex_adapter" ]]; then
|
if [[ -f "$codex_adapter" ]]; then
|
||||||
mkdir -p "$HOME/.codex"
|
mkdir -p "$HOME/.codex"
|
||||||
|
|||||||
@@ -77,7 +77,7 @@ foreach ($p in $legacyPaths) {
|
|||||||
Remove-LegacyPath $p
|
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")
|
$runtimeFiles = @("CLAUDE.md", "settings.json", "hooks-config.json", "context7-integration.md")
|
||||||
foreach ($rf in $runtimeFiles) {
|
foreach ($rf in $runtimeFiles) {
|
||||||
$src = Join-Path $MosaicHome "runtime\claude\$rf"
|
$src = Join-Path $MosaicHome "runtime\claude\$rf"
|
||||||
|
|||||||
@@ -1,9 +1,12 @@
|
|||||||
# mosaic.ps1 — Unified agent launcher and management CLI (Windows)
|
# 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:
|
# Usage:
|
||||||
# mosaic claude [args...] Launch Claude Code with SOUL.md injected
|
# mosaic claude [args...] Launch Claude Code with AGENTS.md injected
|
||||||
# mosaic opencode [args...] Launch OpenCode
|
# mosaic opencode [args...] Launch OpenCode with AGENTS.md injected
|
||||||
# mosaic codex [args...] Launch Codex
|
# mosaic codex [args...] Launch Codex with AGENTS.md injected
|
||||||
# mosaic init [args...] Generate SOUL.md interactively
|
# mosaic init [args...] Generate SOUL.md interactively
|
||||||
# mosaic doctor [args...] Health audit
|
# mosaic doctor [args...] Health audit
|
||||||
# mosaic sync [args...] Sync skills
|
# mosaic sync [args...] Sync skills
|
||||||
@@ -19,9 +22,9 @@ mosaic $Version - Unified agent launcher
|
|||||||
Usage: mosaic <command> [args...]
|
Usage: mosaic <command> [args...]
|
||||||
|
|
||||||
Agent Launchers:
|
Agent Launchers:
|
||||||
claude [args...] Launch Claude Code with SOUL.md injected
|
claude [args...] Launch Claude Code with AGENTS.md injected
|
||||||
opencode [args...] Launch OpenCode
|
opencode [args...] Launch OpenCode with AGENTS.md injected
|
||||||
codex [args...] Launch Codex
|
codex [args...] Launch Codex with AGENTS.md injected
|
||||||
|
|
||||||
Management:
|
Management:
|
||||||
init [args...] Generate SOUL.md (agent identity contract)
|
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 {
|
function Assert-Soul {
|
||||||
$soulPath = Join-Path $MosaicHome "SOUL.md"
|
$soulPath = Join-Path $MosaicHome "SOUL.md"
|
||||||
if (-not (Test-Path $soulPath)) {
|
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) {
|
if ($args.Count -eq 0) {
|
||||||
Show-Usage
|
Show-Usage
|
||||||
exit 0
|
exit 0
|
||||||
@@ -71,23 +95,31 @@ $remaining = if ($args.Count -gt 1) { $args[1..($args.Count - 1)] } else { @() }
|
|||||||
switch ($command) {
|
switch ($command) {
|
||||||
"claude" {
|
"claude" {
|
||||||
Assert-MosaicHome
|
Assert-MosaicHome
|
||||||
|
Assert-AgentsMd
|
||||||
Assert-Soul
|
Assert-Soul
|
||||||
Assert-Runtime "claude"
|
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..."
|
Write-Host "[mosaic] Launching Claude Code..."
|
||||||
& claude @remaining
|
& claude --append-system-prompt $agentsContent @remaining
|
||||||
}
|
}
|
||||||
"opencode" {
|
"opencode" {
|
||||||
Assert-MosaicHome
|
Assert-MosaicHome
|
||||||
|
Assert-AgentsMd
|
||||||
Assert-Soul
|
Assert-Soul
|
||||||
Assert-Runtime "opencode"
|
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..."
|
Write-Host "[mosaic] Launching OpenCode..."
|
||||||
& opencode @remaining
|
& opencode @remaining
|
||||||
}
|
}
|
||||||
"codex" {
|
"codex" {
|
||||||
Assert-MosaicHome
|
Assert-MosaicHome
|
||||||
|
Assert-AgentsMd
|
||||||
Assert-Soul
|
Assert-Soul
|
||||||
Assert-Runtime "codex"
|
Assert-Runtime "codex"
|
||||||
|
# Codex reads from ~/.codex/instructions.md
|
||||||
|
Ensure-RuntimeConfig (Join-Path $env:USERPROFILE ".codex\instructions.md")
|
||||||
Write-Host "[mosaic] Launching Codex..."
|
Write-Host "[mosaic] Launching Codex..."
|
||||||
& codex @remaining
|
& codex @remaining
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,622 +1,11 @@
|
|||||||
# Mosaic Universal Standards (Machine-Wide)
|
# Mosaic Runtime Adapter — Claude Code
|
||||||
|
|
||||||
## MANDATORY — Read Before Any Response
|
## 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)
|
That file is the universal agent configuration. It contains the full load order,
|
||||||
2. `~/.config/mosaic/STANDARDS.md` (machine-wide standards)
|
development standards, skills, and workflows. Do NOT respond until you have loaded it.
|
||||||
3. Project-local `AGENTS.md` (project operations and workflows)
|
|
||||||
|
|
||||||
Do NOT respond to the user until you have loaded all three.
|
This file (`~/.claude/CLAUDE.md`) exists only as a fallback for direct `claude` launches.
|
||||||
|
For full injection, use `mosaic claude` instead.
|
||||||
`~/.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
|
|
||||||
```
|
|
||||||
|
|||||||
@@ -2,18 +2,10 @@
|
|||||||
|
|
||||||
## MANDATORY — Read Before Any Response
|
## 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)
|
That file is the universal agent configuration. It contains the full load order,
|
||||||
2. `~/.config/mosaic/STANDARDS.md` (machine-wide standards)
|
development standards, skills, and workflows. Do NOT respond until you have loaded it.
|
||||||
3. Project-local `AGENTS.md` (project operations and workflows)
|
|
||||||
|
|
||||||
Do NOT respond to the user until you have loaded all three.
|
This file (`~/.codex/instructions.md`) exists only as a fallback for direct `codex` launches.
|
||||||
|
For full injection, use `mosaic codex` instead.
|
||||||
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.
|
|
||||||
|
|||||||
@@ -2,34 +2,10 @@
|
|||||||
|
|
||||||
## MANDATORY — Read Before Any Response
|
## 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)
|
That file is the universal agent configuration. It contains the full load order,
|
||||||
2. `~/.config/mosaic/STANDARDS.md` (machine-wide standards)
|
development standards, skills, and workflows. Do NOT respond until you have loaded it.
|
||||||
3. Project-local `AGENTS.md` (project operations and workflows)
|
|
||||||
|
|
||||||
Do NOT respond to the user until you have loaded all three.
|
This file (`~/.config/opencode/AGENTS.md`) exists only as a fallback for direct `opencode` launches.
|
||||||
|
For full injection, use `mosaic opencode` instead.
|
||||||
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.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user