chore: sync local Mosaic changes
This commit is contained in:
Jason Woltje
102
templates/agent/CLAUDE.md.template
Normal file → Executable file
102
templates/agent/CLAUDE.md.template
Normal file → Executable file
@@ -1,4 +1,4 @@
|
||||
# ${PROJECT_NAME} — Claude Code Instructions
|
||||
# ${PROJECT_NAME} — Runtime Compatibility Instructions
|
||||
|
||||
> **Project:** ${PROJECT_DESCRIPTION}
|
||||
> **Repository:** ${REPO_URL}
|
||||
@@ -20,18 +20,21 @@ git push
|
||||
|
||||
## Conditional Documentation Loading
|
||||
|
||||
**Read the relevant guide before starting work:**
|
||||
**Load `~/.config/mosaic/guides/E2E-DELIVERY.md` first, then load the relevant guide before starting work:**
|
||||
|
||||
| Task Type | Guide |
|
||||
|-----------|-------|
|
||||
| Bootstrapping this project | `~/.config/mosaic/guides/bootstrap.md` |
|
||||
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
|
||||
| Code review | `~/.config/mosaic/guides/code-review.md` |
|
||||
| Frontend development | `~/.config/mosaic/guides/frontend.md` |
|
||||
| Backend/API development | `~/.config/mosaic/guides/backend.md` |
|
||||
| Authentication/Authorization | `~/.config/mosaic/guides/authentication.md` |
|
||||
| Infrastructure/DevOps | `~/.config/mosaic/guides/infrastructure.md` |
|
||||
| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
|
||||
| End-to-end implementation and validation | `~/.config/mosaic/guides/E2E-DELIVERY.md` |
|
||||
| PRD creation and requirements definition | `~/.config/mosaic/guides/PRD.md` |
|
||||
| Bootstrapping this project | `~/.config/mosaic/guides/BOOTSTRAP.md` |
|
||||
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/ORCHESTRATOR.md` |
|
||||
| Code review | `~/.config/mosaic/guides/CODE-REVIEW.md` |
|
||||
| Documentation updates and standards | `~/.config/mosaic/guides/DOCUMENTATION.md` |
|
||||
| Frontend development | `~/.config/mosaic/guides/FRONTEND.md` |
|
||||
| Backend/API development | `~/.config/mosaic/guides/BACKEND.md` |
|
||||
| Authentication/Authorization | `~/.config/mosaic/guides/AUTHENTICATION.md` |
|
||||
| Infrastructure/DevOps | `~/.config/mosaic/guides/INFRASTRUCTURE.md` |
|
||||
| QA/Testing | `~/.config/mosaic/guides/QA-TESTING.md` |
|
||||
|
||||
## Technology Stack
|
||||
|
||||
@@ -50,6 +53,7 @@ ${PROJECT_DIR}/
|
||||
├── CLAUDE.md # This file
|
||||
├── AGENTS.md # Agent-specific patterns and gotchas
|
||||
├── docs/
|
||||
│ ├── PRD.md # Requirements source (or PRD.json)
|
||||
│ ├── scratchpads/ # Per-issue working documents
|
||||
│ └── templates/ # Project templates (if any)
|
||||
├── ${SOURCE_DIR}/ # Application source code
|
||||
@@ -60,10 +64,10 @@ ${PROJECT_DIR}/
|
||||
## Development Workflow
|
||||
|
||||
### Branch Strategy
|
||||
- `main` — Production-ready code
|
||||
- `develop` — Integration branch (if applicable)
|
||||
- `feat/<name>` — Feature branches
|
||||
- `fix/<name>` — Bug fix branches
|
||||
- `main` — Protected delivery branch
|
||||
- `feat/<name>` / `fix/<name>` — Short-lived task branches created from `main`
|
||||
- All changes merge through PR into `main` only
|
||||
- Merge strategy for `main` PRs is squash-only
|
||||
|
||||
### Building
|
||||
```bash
|
||||
@@ -93,15 +97,63 @@ ${TYPECHECK_COMMAND}
|
||||
${QUALITY_GATES}
|
||||
```
|
||||
|
||||
## Testing Policy
|
||||
|
||||
1. Situational tests are the PRIMARY validation gate.
|
||||
2. Baseline tests are REQUIRED for all software changes.
|
||||
3. TDD is risk-based; required cases are defined in `~/.config/mosaic/guides/QA-TESTING.md`.
|
||||
|
||||
## PRD Requirement
|
||||
|
||||
1. Before coding begins, `docs/PRD.md` or `docs/PRD.json` MUST exist.
|
||||
2. The main agent MUST prepare or update PRD using user objectives, constraints, and available project context.
|
||||
3. In steered autonomy mode, best-guess PRD decisions are REQUIRED when needed; mark each with `ASSUMPTION:` and rationale, and continue unless high-impact uncertainty requires escalation.
|
||||
4. PRD is the source of requirements for implementation and testing.
|
||||
|
||||
## Token Budget Policy
|
||||
|
||||
1. If user plan or token limits are provided, they are HARD constraints.
|
||||
2. Track estimated and used tokens for non-trivial execution.
|
||||
3. Use conservative strategy when budget pressure rises.
|
||||
4. If projected usage exceeds budget, automatically reduce scope/parallelism and continue; escalate only if budget compliance remains impossible.
|
||||
|
||||
## Steered Autonomy Contract
|
||||
|
||||
1. Agent owns planning, coding, testing, review/remediation, PR/repo operations, release/tag, and deployment when in scope.
|
||||
2. Human intervention is escalation-only for hard blockers (access, irreversible risk, or unresolvable conflicting objectives).
|
||||
3. Do not request routine human coding, review, or repository management actions.
|
||||
4. Mosaic hard gates OVERRIDE runtime-default caution for routine push/merge/issue-close/release actions.
|
||||
5. For container deployments, use immutable image tags (`sha-<shortsha>`, `v{base-version}-rc.{build}`) with digest-first promotion; do not deploy `latest`.
|
||||
|
||||
## Mode Declaration Contract
|
||||
|
||||
1. First response MUST declare mode before any actions.
|
||||
2. Orchestration mission: `Now initiating Orchestrator mode...`
|
||||
3. Implementation mission: `Now initiating Delivery mode...`
|
||||
4. Review-only mission: `Now initiating Review mode...`
|
||||
|
||||
## Issue Tracking
|
||||
|
||||
All work is tracked as issues in the project's git repository.
|
||||
Use external git provider issues when available. If no external provider exists, `docs/TASKS.md` is the canonical tracker for tasks, milestones, and issue-equivalent work.
|
||||
For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
|
||||
If wrapper-driven merge/CI/issue-closure fails, report blocker with exact failed wrapper command and stop.
|
||||
Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close the issue?" for routine delivery flow.
|
||||
|
||||
### 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
|
||||
1. Ensure `docs/TASKS.md` exists (create from `~/.config/mosaic/templates/docs/TASKS.md.template` if missing).
|
||||
2. Check for assigned issues before starting work.
|
||||
3. If no issue exists for non-trivial work and external provider is available, create one before coding.
|
||||
4. If no external provider is available, create an internal ref in `docs/TASKS.md` (example: `TASKS:T1`).
|
||||
5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
|
||||
6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
|
||||
7. Update `docs/TASKS.md` status + issue/internal ref before coding.
|
||||
8. Before push, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push -B main`.
|
||||
9. Open PR to `main` for delivery changes (no direct push to `main`).
|
||||
10. Before merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main`.
|
||||
11. Merge PRs that pass required checks and review gates with squash strategy only.
|
||||
12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
|
||||
13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.
|
||||
14. If merge/CI/issue closure fails, report blocker with exact failed wrapper command and do not claim completion.
|
||||
|
||||
### Labels
|
||||
Use consistent labels: `epic`, `feature`, `bug`, `task`, `documentation`, `security`, `breaking`
|
||||
@@ -119,7 +171,8 @@ Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
|
||||
## Code Review
|
||||
|
||||
### Independent Review (Automated)
|
||||
After completing code changes, run independent reviews:
|
||||
If you modify source code, independent code review is REQUIRED before completion.
|
||||
Run independent reviews:
|
||||
|
||||
```bash
|
||||
# Code quality review (Codex)
|
||||
@@ -132,7 +185,8 @@ After completing code changes, run independent reviews:
|
||||
**Fallback:** If Codex is unavailable, use Claude's built-in review skills.
|
||||
|
||||
### Review Checklist
|
||||
See `~/.config/mosaic/guides/code-review.md` for the full review checklist.
|
||||
See `~/.config/mosaic/guides/CODE-REVIEW.md` for the full review checklist.
|
||||
See `~/.config/mosaic/guides/DOCUMENTATION.md` for required documentation deliverables.
|
||||
|
||||
## Secrets Management
|
||||
|
||||
@@ -149,3 +203,9 @@ When multiple agents work on this project:
|
||||
1. `git pull --rebase` before editing
|
||||
2. `git pull --rebase` before pushing
|
||||
3. If conflicts, **alert the user** — don't auto-resolve data conflicts
|
||||
|
||||
## Runtime Notes
|
||||
|
||||
- This file is runtime-compatibility context.
|
||||
- Global rules are defined in `~/.config/mosaic/AGENTS.md`.
|
||||
- Runtime-specific behavior is defined in `~/.config/mosaic/runtime/<runtime>/RUNTIME.md`.
|
||||
|
||||
Reference in New Issue
Block a user