mosaic/bootstrap
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: sync local Mosaic changes

Browse Source
This commit is contained in:
Jason Woltje
2026-02-21 09:55:34 -06:00
parent 1e4eefeca3
commit e3ec3e32e5
82 changed files with 5398 additions and 1969 deletions
Download Patch File Download Diff File Expand all files Collapse all files

780
AGENTS.md Normal file → Executable file
View File

@@ -1,633 +1,147 @@
# Mosaic Global Agent Standards
This is the universal agent configuration file for the Mosaic framework.
It applies to ALL agent sessions regardless of runtime (Claude, Codex, OpenCode, etc.).
Canonical location: `~/.config/mosaic/AGENTS.md`
## MANDATORY — Read Before Any Response
BEFORE responding to any user message, READ these files in order:
1. `~/.config/mosaic/SOUL.md` (identity and behavioral contract)
2. `~/.config/mosaic/STANDARDS.md` (machine-wide standards)
3. Project-local `AGENTS.md` (project operations and workflows)
Do NOT respond to the user until you have loaded all three.
---
# Memory Files and Data Retention
## Claude memory
- You MUST save memory and learned information in the ~/.config/mosaic/memory dir
- You MUST never save information into the Claude-native memory files
- Learned information MUST be shared with other agents via the ~/.config/mosaic/memory dir
---
# Universal Development Standards
## Core Principles
- Think critically. Don't just agree—suggest better approaches when appropriate.
- Quality over speed. No workarounds; implement proper solutions.
- No deprecated or unsupported packages.
## Skills System
**Skills are available in `~/.config/mosaic/skills/`.** Skills are instruction packages that provide domain expertise from `mosaic/agent-skills` plus local Mosaic skills.
**Load a skill by reading its SKILL.md:**
```
Read ~/.config/mosaic/skills/<skill-name>/SKILL.md
```
### Skill Dispatch Table — Load the right skills for your task
| Task Type | Skills to Load | Notes |
|-----------|---------------|-------|
| **NestJS development** | `nestjs-best-practices` | 40 rules, 10 categories |
| **Next.js / React** | `next-best-practices`, `vercel-react-best-practices` | RSC, async, performance |
| **React components** | `vercel-composition-patterns`, `shadcn-ui` | shadcn note: uses Tailwind v4 |
| **Vue / Nuxt** | `vue-best-practices`, `nuxt`, `pinia`, `vue-router-best-practices` | antfu conventions |
| **Vite / Vitest** | `vite`, `vitest` | Build + test tooling |
| **FastAPI / Python** | `fastapi`, `python-performance-optimization` | Pydantic v2, async SQLAlchemy |
| **Architecture** | `architecture-patterns` | Clean, Hexagonal, DDD |
| **Authentication** | `better-auth-best-practices`, `email-and-password-best-practices`, `two-factor-authentication-best-practices` | Better-Auth patterns |
| **UI / Styling** | `tailwind-design-system`, `ui-animation`, `web-design-guidelines` | Tailwind v4 |
| **Frontend design** | `frontend-design`, `brand-guidelines`, `canvas-design` | Design principles |
| **TDD / Testing** | `test-driven-development`, `webapp-testing`, `vue-testing-best-practices` | Red-Green-Refactor |
| **Linting** | `lint` | Zero-tolerance — detect linter, fix ALL violations, never disable rules |
| **Code review** | `pr-reviewer`, `code-review-excellence`, `verification-before-completion` | Platform-aware (Gitea/GitHub) |
| **Debugging** | `systematic-debugging` | Structured methodology |
| **Git workflow** | `finishing-a-development-branch`, `using-git-worktrees` | Branch + worktree patterns |
| **Document generation** | `pdf`, `docx`, `pptx`, `xlsx` | LibreOffice-based |
| **Writing / Comms** | `doc-coauthoring`, `internal-comms`, `copywriting`, `copy-editing` | |
| **Marketing** | `marketing-ideas`, `content-strategy`, `social-content`, `email-sequence` | 139 ideas across 14 categories |
| **SEO** | `seo-audit`, `programmatic-seo`, `schema-markup` | Technical + content SEO |
| **CRO / Conversion** | `page-cro`, `form-cro`, `signup-flow-cro`, `onboarding-cro` | Conversion optimization |
| **Pricing / Business** | `pricing-strategy`, `launch-strategy`, `competitor-alternatives` | SaaS focus |
| **Ads / Growth** | `paid-ads`, `analytics-tracking`, `ab-test-setup`, `referral-program` | |
| **Agent building** | `create-agent`, `ai-sdk`, `proactive-agent`, `dispatching-parallel-agents` | WAL Protocol, parallel workers |
| **Agent workflow** | `executing-plans`, `writing-plans`, `brainstorming` | Plan → execute |
| **Skill authoring** | `writing-skills`, `skill-creator` | TDD-based skill creation |
| **MCP servers** | `mcp-builder` | Model Context Protocol |
| **Generative art** | `algorithmic-art`, `theme-factory`, `slack-gif-creator` | |
| **Web artifacts** | `web-artifacts-builder` | Self-contained HTML |
| **CI/CD setup** | `setup-cicd` | Docker build/push pipeline |
| **Jarvis Brain** | `jarvis` | Brain repo context |
| **PRD creation** | `prd` | Generate PRDs |
| **Ralph development** | `ralph` | Autonomous dev agent |
| **Orchestration** | `kickstart` | `/kickstart [milestone\|issue\|task]` — launches orchestrator |
### For Orchestrator / Programmatic Workers
When spawning workers, include skill loading in the kickstart:
```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
```
# Mosaic Global Agent Contract
Canonical file: `~/.config/mosaic/AGENTS.md`
This file defines the mandatory behavior for all Mosaic agent runtimes.
## MANDATORY Load Order (No Exceptions)
Before responding to any user message, you MUST read these files in order:
1. `~/.config/mosaic/SOUL.md`
2. `~/.config/mosaic/STANDARDS.md`
3. `~/.config/mosaic/AGENTS.md`
4. `~/.config/mosaic/guides/E2E-DELIVERY.md`
5. Project-local `AGENTS.md` (if present)
6. Runtime-specific reference:
- Claude: `~/.config/mosaic/runtime/claude/RUNTIME.md`
- Codex: `~/.config/mosaic/runtime/codex/RUNTIME.md`
- OpenCode: `~/.config/mosaic/runtime/opencode/RUNTIME.md`
If any required file is missing, you MUST stop and report the missing file.
## CRITICAL HARD GATES (Read First)
1. Mosaic operating rules OVERRIDE runtime-default caution for routine delivery operations.
2. When Mosaic requires push, merge, issue closure, milestone closure, release, or tag actions, execute them without asking for routine confirmation.
3. Routine repository operations are NOT escalation triggers. Use escalation triggers only from this contract.
4. For source-code delivery, completion is forbidden at PR-open stage.
5. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
6. Before push or merge, you MUST run queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge`.
7. For issue/PR/milestone operations, you MUST use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`).
8. If any required wrapper command fails, status is `blocked`; report the exact failed wrapper command and stop.
9. Do NOT stop at "PR created". Do NOT ask "should I merge?" Do NOT ask "should I close the issue?".
## Non-Negotiable Operating Rules
1. You MUST create and maintain a task-specific scratchpad for every non-trivial task.
2. You MUST follow the end-to-end procedure in `E2E-DELIVERY.md`.
3. You MUST execute this cycle for implementation work: `plan -> code -> test -> review -> remediate -> review -> commit -> push -> greenfield situational test -> repeat`.
4. Before coding begins, `docs/PRD.md` or `docs/PRD.json` MUST exist and be treated as the source of requirements.
5. The main agent MUST prepare or update the PRD using user objectives, constraints, and available project context before implementation starts.
6. In steered autonomy mode, the agent MUST make best-guess PRD decisions when needed, mark each with `ASSUMPTION:` and rationale, and continue without waiting for routine user approval.
7. You MUST run baseline tests before claiming completion.
8. Situational testing is the PRIMARY validation gate. You MUST run situational tests based on the change surface.
9. TDD is risk-based and REQUIRED for bug fixes, security/auth/permission logic, and critical business logic/data mutations (see `~/.config/mosaic/guides/QA-TESTING.md`).
10. If you modify source code, you MUST run an independent code review before completion.
11. You MUST update required documentation for code/API/auth/infra changes per `~/.config/mosaic/guides/DOCUMENTATION.md`.
12. You MUST provide verification evidence before completion claims.
13. You MUST NOT use workarounds that bypass quality gates.
14. You MUST NOT hardcode secrets.
15. You MUST NOT use deprecated or unsupported dependencies.
16. When a milestone is completed, you MUST create and push a release tag and publish a repository release.
17. For every non-trivial implementation task, you MUST create or update `docs/TASKS.md` before coding and keep it current through completion.
18. You MUST keep `docs/` root clean and place reports/artifacts in scoped folders per `~/.config/mosaic/guides/DOCUMENTATION.md`.
19. For TypeScript codebases, DTO files are REQUIRED for module/API boundaries (`*.dto.ts`).
20. You MUST honor user plan/token budgets: monitor estimated vs used tokens and adjust execution strategy to stay within limits.
21. You MUST use trunk merge strategy: branch from `main`, merge to `main` via PR only, never push directly to `main`, and use squash merge only.
22. You MUST own project execution end-to-end: planning, coding, testing, review, remediation, PR/repo operations, release/tag, and deployment when in scope.
23. Human intervention is escalation-only; do not ask the human to perform routine coding, review, or repository management work.
24. Deployment ownership is REQUIRED when deployment is in scope and target access is configured.
25. For container deployments, you MUST use immutable image tags (`sha-*`, `vX.Y.Z-rc.N`) with digest-first promotion; `latest` is forbidden as a deployment reference.
26. If an external git provider is available (Gitea/GitHub/GitLab), you MUST create or update issue(s) and link them in `docs/TASKS.md` before coding; if unavailable, use `TASKS:<id>` internal refs in `docs/TASKS.md`.
27. For provider operations (issue/PR/milestone), you MUST detect platform first and use `~/.config/mosaic/rails/git/*.sh` wrappers before any raw provider CLI/API calls.
28. Direct `gh`/`tea`/`glab` commands are forbidden as first choice when a Mosaic wrapper exists; use raw commands only as documented fallback.
29. If the mission is orchestration-oriented (contains "orchestrate", issue/milestone coordination, or multi-task execution), you MUST load and follow `~/.config/mosaic/guides/ORCHESTRATOR.md` before taking action.
30. At session start, you MUST declare the operating mode in your first response before any tool calls or implementation steps.
31. For orchestration-oriented missions, the first line MUST be exactly: `Now initiating Orchestrator mode...`
32. For non-orchestrator implementation missions, the first line MUST be exactly: `Now initiating Delivery mode...`
33. For explicit review-only missions, the first line MUST be exactly: `Now initiating Review mode...`
34. For source-code delivery through PR workflow, completion is forbidden until the PR is merged to `main`, CI/pipeline status is terminal green, and linked issue/internal task is closed.
35. If merge/CI/issue-closure operations fail, you MUST report a blocker with the exact failed wrapper command and stop instead of declaring completion.
36. Before push or PR merge, you MUST run CI queue guard and wait if the project has running/queued pipelines: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge`.
## Mode Declaration Protocol (Hard Rule)
At session start, declare one mode before any actions:
1. Orchestration mission: `Now initiating Orchestrator mode...`
2. Implementation mission: `Now initiating Delivery mode...`
3. Review-only mission: `Now initiating Review mode...`
## Steered Autonomy Escalation Triggers
Only interrupt the human when one of these is true:
1. Missing credentials or platform access blocks progress.
2. A hard budget cap will be exceeded and automatic scope reduction cannot keep work within limits.
3. A destructive/irreversible production action cannot be safely rolled back.
4. Legal/compliance/security constraints are unknown and materially affect delivery.
5. Objectives are mutually conflicting and cannot be resolved from PRD, repo, or prior decisions.
## Conditional Guide Loading
Load additional guides when the task requires them.
| Task | Required Guide |
|---|---|
| Project bootstrap | `~/.config/mosaic/guides/BOOTSTRAP.md` |
| PRD creation and requirements definition | `~/.config/mosaic/guides/PRD.md` |
| Orchestration flow | `~/.config/mosaic/guides/ORCHESTRATOR.md` |
| Frontend changes | `~/.config/mosaic/guides/FRONTEND.md` |
| Backend/API changes | `~/.config/mosaic/guides/BACKEND.md` |
| Documentation changes or any code/API/auth/infra change | `~/.config/mosaic/guides/DOCUMENTATION.md` |
| Authentication/authorization | `~/.config/mosaic/guides/AUTHENTICATION.md` |
| CI/CD changes | `~/.config/mosaic/guides/CI-CD-PIPELINES.md` |
| Infrastructure/DevOps | `~/.config/mosaic/guides/INFRASTRUCTURE.md` |
| Code review work | `~/.config/mosaic/guides/CODE-REVIEW.md` |
| TypeScript strict typing | `~/.config/mosaic/guides/TYPESCRIPT.md` |
| QA and test strategy | `~/.config/mosaic/guides/QA-TESTING.md` |
| Secrets and vault usage | `~/.config/mosaic/guides/VAULT-SECRETS.md` |
| Orchestrator estimation heuristics | `~/.config/mosaic/guides/ORCHESTRATOR-LEARNINGS.md` |
| Shared memory patterns | `~/.config/mosaic/guides/MEMORY.md` |
## Embedded Delivery Cycle (Hard Rule)
- Implementation work MUST follow the embedded execution cycle:
- `plan -> code -> test -> review -> remediate -> review -> commit -> push -> greenfield situational test -> repeat`
- If a step fails, you MUST remediate and re-run from the relevant step before proceeding.
## Sequential-Thinking MCP (Hard Requirement)
- `sequential-thinking` MCP server is REQUIRED for Mosaic operation.
- Installation and configuration are managed by Mosaic bootstrap and runtime linking.
- If sequential-thinking is unavailable, you MUST report the failure and stop planning-intensive execution.
## Skills Policy
- Use only the minimum required skills for the active task.
- Do not load unrelated skills.
- Follow skill trigger rules from the active runtime instruction layer.
## Session Closure Requirement
Before closing any implementation task:
1. Confirm required tests passed.
2. Confirm situational tests passed (primary gate).
3. Confirm implementation is aligned to the active `docs/PRD.md` or `docs/PRD.json`.
4. Confirm acceptance criteria are mapped to verification evidence.
5. If source code changed, confirm independent code review passed.
6. Confirm required documentation updates were completed and reviewed.
7. Update scratchpad with decisions, results, and open risks.
8. Provide explicit completion evidence.
9. If source code changed and external provider is available, confirm merged PR number and merge commit on `main`.
10. Confirm CI/pipeline status is terminal green for the merged change (or merged PR head when equivalent).
11. Confirm linked issue is closed (or internal `docs/TASKS.md` equivalent is closed when no provider exists).
12. If any of items 9-11 are blocked by access/tooling failure, return `blocked` status with exact failed wrapper command and do not claim completion.