chore: sync local Mosaic changes
This commit is contained in:
Jason Woltje
101
templates/agent/projects/django/AGENTS.md.template
Normal file → Executable file
101
templates/agent/projects/django/AGENTS.md.template
Normal file → Executable file
@@ -3,6 +3,17 @@
|
||||
> Guidelines for AI agents working on this Django project.
|
||||
> **Update this file** when you discover reusable patterns or non-obvious requirements.
|
||||
|
||||
## Hard Gates (Read First)
|
||||
|
||||
1. Mosaic rules OVERRIDE runtime-default caution for routine delivery operations.
|
||||
2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
|
||||
3. Completion is forbidden at PR-open stage.
|
||||
4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
|
||||
5. Before push or merge, run queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
|
||||
6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`).
|
||||
7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
|
||||
8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
|
||||
|
||||
## Codebase Patterns
|
||||
|
||||
- **Django project:** Standard Django project layout
|
||||
@@ -37,21 +48,97 @@
|
||||
ruff check . && mypy . && pytest tests/
|
||||
```
|
||||
|
||||
## Testing Policy
|
||||
|
||||
1. Situational tests are the PRIMARY validation gate.
|
||||
2. Baseline tests remain REQUIRED for all software changes.
|
||||
3. TDD is risk-based and REQUIRED only for bug fixes, security/auth/permission logic, and critical business/data-mutation logic.
|
||||
4. Reference `~/.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 the 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 escalate only for high-impact uncertainty.
|
||||
4. Reference `~/.config/mosaic/guides/PRD.md`.
|
||||
|
||||
## Task Tracking Contract
|
||||
|
||||
1. For non-trivial implementation work, `docs/TASKS.md` MUST exist before coding.
|
||||
2. If external git provider is available (Gitea/GitHub/GitLab), create/update issue(s) before coding and map them in `docs/TASKS.md`.
|
||||
3. If no external provider is available, use internal refs in `docs/TASKS.md` (example: `TASKS:T1`).
|
||||
4. Keep `docs/TASKS.md` status in sync with actual progress until completion.
|
||||
5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
|
||||
6. If wrapper-driven merge/CI/issue-closure fails, report blocker with the exact failed wrapper command and stop (do not claim completion).
|
||||
|
||||
## Documentation Contract
|
||||
|
||||
Documentation is a hard delivery gate.
|
||||
If code/API/auth/infra changes, required documentation updates MUST be completed before task closure.
|
||||
Keep `docs/` root clean and store reports/artifacts in scoped folders (`docs/reports/`, `docs/tasks/`, `docs/releases/`, `docs/scratchpads/`).
|
||||
|
||||
Reference:
|
||||
- `~/.config/mosaic/guides/DOCUMENTATION.md`
|
||||
- `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md`
|
||||
|
||||
## 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. Shift to conservative strategy when budget pressure rises (smaller scope, fewer parallel actions, reduced re-reading).
|
||||
4. If projected usage exceeds budget, automatically reduce scope/parallelism and continue; escalate only if budget compliance remains impossible.
|
||||
|
||||
## Merge Strategy (Hard Rule)
|
||||
|
||||
1. Create short-lived branches from `main`.
|
||||
2. Open PRs to `main` for delivery changes.
|
||||
3. Do not push directly to `main`.
|
||||
4. Merge PRs to `main` with squash strategy only.
|
||||
5. Do not mark implementation complete until PR is merged.
|
||||
6. Do not mark implementation complete until CI/pipeline status is terminal green.
|
||||
7. Close linked issues/tasks only after merge + green CI.
|
||||
8. Before push or merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
|
||||
|
||||
|
||||
## Container Release Strategy (When Applicable)
|
||||
|
||||
1. Use immutable image tags: `sha-<shortsha>` and `v{base-version}-rc.{build}`.
|
||||
2. Use mutable environment tags only as pointers (`testing`, optional `staging`, `prod`).
|
||||
3. Deploy/promote by immutable digest; do not deploy by mutable tag alone.
|
||||
4. Do not use `latest` or `dev` as deployment references.
|
||||
5. Use blue-green by default; use canary only with automated metrics and rollback gates.
|
||||
|
||||
## Steered Autonomy Contract
|
||||
|
||||
1. Agent owns end-to-end delivery: plan, code, test, review, remediate, commit, push, 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. Code review is agent-executed and REQUIRED for any source-code change.
|
||||
|
||||
## 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...`
|
||||
|
||||
## Orchestrator Integration
|
||||
|
||||
### Task Prefix
|
||||
Use `${TASK_PREFIX}` for orchestrated tasks (e.g., `${TASK_PREFIX}-SEC-001`).
|
||||
|
||||
### Worker Checklist
|
||||
1. Read the finding details from the report
|
||||
2. Implement the fix following existing patterns
|
||||
3. Run quality gates (ALL must pass)
|
||||
4. Commit: `git commit -m "fix({finding_id}): brief description"`
|
||||
5. Push: `git push origin {branch}`
|
||||
6. Report result as JSON
|
||||
1. Read `docs/PRD.md` or `docs/PRD.json`
|
||||
2. Read the finding details from the report
|
||||
3. Implement the fix following existing patterns
|
||||
4. Run quality gates (ALL must pass)
|
||||
5. Complete required documentation updates (if applicable)
|
||||
6. Commit: `git commit -m "fix({finding_id}): brief description"`
|
||||
7. Push: `git push origin {branch}`
|
||||
8. Report result as JSON
|
||||
|
||||
### Post-Coding Review
|
||||
After implementing changes, the orchestrator will run:
|
||||
After implementing changes, code review is REQUIRED for any source-code modification.
|
||||
For orchestrated tasks, the orchestrator will run:
|
||||
1. **Codex code review** — `~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted`
|
||||
2. **Codex security review** — `~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted`
|
||||
3. If blockers/critical findings: remediation task created
|
||||
|
||||
85
templates/agent/projects/django/CLAUDE.md.template
Normal file → Executable file
85
templates/agent/projects/django/CLAUDE.md.template
Normal file → Executable file
@@ -6,11 +6,13 @@
|
||||
|
||||
| When working on... | Load this guide |
|
||||
|---|---|
|
||||
| Bootstrapping this project | `~/.config/mosaic/guides/bootstrap.md` |
|
||||
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
|
||||
| Backend/API development | `~/.config/mosaic/guides/backend.md` |
|
||||
| Code review | `~/.config/mosaic/guides/code-review.md` |
|
||||
| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
|
||||
| Bootstrapping this project | `~/.config/mosaic/guides/BOOTSTRAP.md` |
|
||||
| PRD creation and requirements definition | `~/.config/mosaic/guides/PRD.md` |
|
||||
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/ORCHESTRATOR.md` |
|
||||
| Backend/API development | `~/.config/mosaic/guides/BACKEND.md` |
|
||||
| Code review | `~/.config/mosaic/guides/CODE-REVIEW.md` |
|
||||
| Documentation updates and standards | `~/.config/mosaic/guides/DOCUMENTATION.md` |
|
||||
| QA/Testing | `~/.config/mosaic/guides/QA-TESTING.md` |
|
||||
|
||||
## Technology Stack
|
||||
|
||||
@@ -39,6 +41,7 @@ ${PROJECT_DIR}/
|
||||
│ └── apps/ # Django applications
|
||||
├── tests/ # Test files
|
||||
├── docs/
|
||||
│ ├── PRD.md # Requirements source (or PRD.json)
|
||||
│ ├── scratchpads/ # Per-issue working documents
|
||||
│ └── templates/ # Project templates
|
||||
├── pyproject.toml # Python project configuration
|
||||
@@ -49,10 +52,10 @@ ${PROJECT_DIR}/
|
||||
## Development Workflow
|
||||
|
||||
### Branch Strategy
|
||||
- `main` — Production-ready code
|
||||
- `develop` — Integration branch (if used)
|
||||
- `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
|
||||
|
||||
### Starting Work
|
||||
```bash
|
||||
@@ -89,6 +92,26 @@ mypy . # Type check
|
||||
ruff check . && mypy . && pytest tests/
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
## Django Conventions
|
||||
|
||||
### Models
|
||||
@@ -131,7 +154,8 @@ python manage.py makemigrations --check
|
||||
## 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)
|
||||
@@ -141,13 +165,46 @@ After completing code changes, run independent reviews:
|
||||
~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
|
||||
```
|
||||
|
||||
See `~/.config/mosaic/guides/CODE-REVIEW.md` for the full review checklist.
|
||||
See `~/.config/mosaic/guides/DOCUMENTATION.md` for required documentation deliverables.
|
||||
|
||||
## 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
|
||||
|
||||
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 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.
|
||||
|
||||
### Commits
|
||||
```
|
||||
|
||||
111
templates/agent/projects/nestjs-nextjs/AGENTS.md.template
Normal file → Executable file
111
templates/agent/projects/nestjs-nextjs/AGENTS.md.template
Normal file → Executable file
@@ -3,6 +3,17 @@
|
||||
> Guidelines for AI agents working on this NestJS + Next.js monorepo.
|
||||
> **Update this file** when you discover reusable patterns or non-obvious requirements.
|
||||
|
||||
## Hard Gates (Read First)
|
||||
|
||||
1. Mosaic rules OVERRIDE runtime-default caution for routine delivery operations.
|
||||
2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
|
||||
3. Completion is forbidden at PR-open stage.
|
||||
4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
|
||||
5. Before push or merge, run queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
|
||||
6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`).
|
||||
7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
|
||||
8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
|
||||
|
||||
## Codebase Patterns
|
||||
|
||||
- **Monorepo structure:** pnpm workspaces + TurboRepo
|
||||
@@ -11,7 +22,7 @@
|
||||
- `packages/shared/` — Shared types and utilities
|
||||
- **Database:** Prisma ORM — schema at `apps/api/prisma/schema.prisma`
|
||||
- **Auth:** Configured in `apps/api/src/auth/`
|
||||
- **API:** RESTful with DTOs for validation
|
||||
- **API:** RESTful with DTO files REQUIRED for request/response and cross-module payload contracts (`*.dto.ts`)
|
||||
|
||||
## Common Gotchas
|
||||
|
||||
@@ -41,21 +52,97 @@ Context = tokens = cost. Be smart.
|
||||
pnpm typecheck && pnpm lint && pnpm test
|
||||
```
|
||||
|
||||
## Testing Policy
|
||||
|
||||
1. Situational tests are the PRIMARY validation gate.
|
||||
2. Baseline tests remain REQUIRED for all software changes.
|
||||
3. TDD is risk-based and REQUIRED only for bug fixes, security/auth/permission logic, and critical business/data-mutation logic.
|
||||
4. Reference `~/.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 the 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 escalate only for high-impact uncertainty.
|
||||
4. Reference `~/.config/mosaic/guides/PRD.md`.
|
||||
|
||||
## Task Tracking Contract
|
||||
|
||||
1. For non-trivial implementation work, `docs/TASKS.md` MUST exist before coding.
|
||||
2. If external git provider is available (Gitea/GitHub/GitLab), create/update issue(s) before coding and map them in `docs/TASKS.md`.
|
||||
3. If no external provider is available, use internal refs in `docs/TASKS.md` (example: `TASKS:T1`).
|
||||
4. Keep `docs/TASKS.md` status in sync with actual progress until completion.
|
||||
5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
|
||||
6. If wrapper-driven merge/CI/issue-closure fails, report blocker with the exact failed wrapper command and stop (do not claim completion).
|
||||
|
||||
## Documentation Contract
|
||||
|
||||
Documentation is a hard delivery gate.
|
||||
If code/API/auth/infra changes, required documentation updates MUST be completed before task closure.
|
||||
Keep `docs/` root clean and store reports/artifacts in scoped folders (`docs/reports/`, `docs/tasks/`, `docs/releases/`, `docs/scratchpads/`).
|
||||
|
||||
Reference:
|
||||
- `~/.config/mosaic/guides/DOCUMENTATION.md`
|
||||
- `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md`
|
||||
|
||||
## 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. Shift to conservative strategy when budget pressure rises (smaller scope, fewer parallel actions, reduced re-reading).
|
||||
4. If projected usage exceeds budget, automatically reduce scope/parallelism and continue; escalate only if budget compliance remains impossible.
|
||||
|
||||
## Merge Strategy (Hard Rule)
|
||||
|
||||
1. Create short-lived branches from `main`.
|
||||
2. Open PRs to `main` for delivery changes.
|
||||
3. Do not push directly to `main`.
|
||||
4. Merge PRs to `main` with squash strategy only.
|
||||
5. Do not mark implementation complete until PR is merged.
|
||||
6. Do not mark implementation complete until CI/pipeline status is terminal green.
|
||||
7. Close linked issues/tasks only after merge + green CI.
|
||||
8. Before push or merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
|
||||
|
||||
|
||||
## Container Release Strategy (When Applicable)
|
||||
|
||||
1. Use immutable image tags: `sha-<shortsha>` and `v{base-version}-rc.{build}`.
|
||||
2. Use mutable environment tags only as pointers (`testing`, optional `staging`, `prod`).
|
||||
3. Deploy/promote by immutable digest; do not deploy by mutable tag alone.
|
||||
4. Do not use `latest` or `dev` as deployment references.
|
||||
5. Use blue-green by default; use canary only with automated metrics and rollback gates.
|
||||
|
||||
## Steered Autonomy Contract
|
||||
|
||||
1. Agent owns end-to-end delivery: plan, code, test, review, remediate, commit, push, 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. Code review is agent-executed and REQUIRED for any source-code change.
|
||||
|
||||
## 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...`
|
||||
|
||||
## Orchestrator Integration
|
||||
|
||||
### Task Prefix
|
||||
Use `${TASK_PREFIX}` for orchestrated tasks (e.g., `${TASK_PREFIX}-SEC-001`).
|
||||
|
||||
### Worker Checklist
|
||||
1. Read the finding details from the report
|
||||
2. Implement the fix following existing patterns
|
||||
3. Run quality gates (ALL must pass)
|
||||
4. Commit: `git commit -m "fix({finding_id}): brief description"`
|
||||
5. Push: `git push origin {branch}`
|
||||
6. Report result as JSON
|
||||
1. Read `docs/PRD.md` or `docs/PRD.json`
|
||||
2. Read the finding details from the report
|
||||
3. Implement the fix following existing patterns
|
||||
4. Run quality gates (ALL must pass)
|
||||
5. Complete required documentation updates (if applicable)
|
||||
6. Commit: `git commit -m "fix({finding_id}): brief description"`
|
||||
7. Push: `git push origin {branch}`
|
||||
8. Report result as JSON
|
||||
|
||||
### Post-Coding Review
|
||||
After implementing changes, the orchestrator will run:
|
||||
After implementing changes, code review is REQUIRED for any source-code modification.
|
||||
For orchestrated tasks, the orchestrator will run:
|
||||
1. **Codex code review** — `~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted`
|
||||
2. **Codex security review** — `~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted`
|
||||
3. If blockers/critical findings: remediation task created
|
||||
@@ -65,15 +152,15 @@ After implementing changes, the orchestrator will run:
|
||||
|
||||
```
|
||||
1. Branch → git checkout -b feature/XX-description
|
||||
2. Code → TDD: write test (RED), implement (GREEN), refactor
|
||||
2. Code → Implement with required tests; use TDD where required by policy
|
||||
3. Test → pnpm test (must pass)
|
||||
4. Push → git push origin feature/XX-description
|
||||
5. PR → Create PR to develop (not main)
|
||||
6. Review → Wait for approval or self-merge if authorized
|
||||
5. PR → Create PR to main
|
||||
6. Review → Wait for approval or self-merge if authorized using squash only
|
||||
7. Close → Close related issues
|
||||
```
|
||||
|
||||
**Never merge directly to develop without a PR.**
|
||||
**Never push directly to main. Always use a PR to main.**
|
||||
|
||||
## Key Files
|
||||
|
||||
|
||||
96
templates/agent/projects/nestjs-nextjs/CLAUDE.md.template
Normal file → Executable file
96
templates/agent/projects/nestjs-nextjs/CLAUDE.md.template
Normal file → Executable file
@@ -6,14 +6,16 @@
|
||||
|
||||
| When working on... | Load this guide |
|
||||
|---|---|
|
||||
| Bootstrapping this project | `~/.config/mosaic/guides/bootstrap.md` |
|
||||
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
|
||||
| Frontend development | `~/.config/mosaic/guides/frontend.md` |
|
||||
| Backend/API development | `~/.config/mosaic/guides/backend.md` |
|
||||
| Code review | `~/.config/mosaic/guides/code-review.md` |
|
||||
| TypeScript strict typing | `~/.config/mosaic/guides/typescript.md` |
|
||||
| Authentication/Authorization | `~/.config/mosaic/guides/authentication.md` |
|
||||
| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
|
||||
| Bootstrapping this project | `~/.config/mosaic/guides/BOOTSTRAP.md` |
|
||||
| PRD creation and requirements definition | `~/.config/mosaic/guides/PRD.md` |
|
||||
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/ORCHESTRATOR.md` |
|
||||
| Frontend development | `~/.config/mosaic/guides/FRONTEND.md` |
|
||||
| Backend/API development | `~/.config/mosaic/guides/BACKEND.md` |
|
||||
| Code review | `~/.config/mosaic/guides/CODE-REVIEW.md` |
|
||||
| Documentation updates and standards | `~/.config/mosaic/guides/DOCUMENTATION.md` |
|
||||
| TypeScript strict typing | `~/.config/mosaic/guides/TYPESCRIPT.md` |
|
||||
| Authentication/Authorization | `~/.config/mosaic/guides/AUTHENTICATION.md` |
|
||||
| QA/Testing | `~/.config/mosaic/guides/QA-TESTING.md` |
|
||||
|
||||
## Technology Stack
|
||||
|
||||
@@ -47,6 +49,7 @@ ${PROJECT_DIR}/
|
||||
│ ├── ui/ # Shared UI components
|
||||
│ └── config/ # Shared configuration
|
||||
├── docs/
|
||||
│ ├── PRD.md # Requirements source (or PRD.json)
|
||||
│ ├── scratchpads/ # Per-issue working documents
|
||||
│ └── templates/ # Project templates
|
||||
├── tests/ # Integration/E2E tests
|
||||
@@ -60,15 +63,15 @@ ${PROJECT_DIR}/
|
||||
## Development Workflow
|
||||
|
||||
### Branch Strategy
|
||||
- `main` — Stable releases only
|
||||
- `develop` — Active development (default working branch)
|
||||
- `feature/*` — Feature branches from develop
|
||||
- `fix/*` — Bug fix branches
|
||||
- `main` — Protected delivery branch
|
||||
- `feature/*` / `fix/*` — Short-lived task branches created from `main`
|
||||
- All changes merge through PR into `main` only
|
||||
- Merge strategy for `main` PRs is squash-only
|
||||
|
||||
### Starting Work
|
||||
```bash
|
||||
git checkout develop
|
||||
git pull --rebase
|
||||
git checkout main
|
||||
git pull --rebase origin main
|
||||
pnpm install
|
||||
```
|
||||
|
||||
@@ -102,10 +105,31 @@ pnpm format # Prettier formatting
|
||||
pnpm typecheck && pnpm lint && pnpm test
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
## API Conventions
|
||||
|
||||
### NestJS Patterns
|
||||
- Controllers handle HTTP, Services handle business logic
|
||||
- DTO files are REQUIRED at module/API boundaries (`*.dto.ts`)
|
||||
- Use DTOs with `class-validator` for request validation
|
||||
- Use Guards for authentication/authorization
|
||||
- Use Interceptors for response transformation
|
||||
@@ -162,7 +186,8 @@ pnpm --filter api prisma migrate reset
|
||||
## 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)
|
||||
@@ -172,13 +197,46 @@ After completing code changes, run independent reviews:
|
||||
~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
|
||||
```
|
||||
|
||||
See `~/.config/mosaic/guides/CODE-REVIEW.md` for the full review checklist.
|
||||
See `~/.config/mosaic/guides/DOCUMENTATION.md` for required documentation deliverables.
|
||||
|
||||
## 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
|
||||
|
||||
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 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.
|
||||
|
||||
### Commits
|
||||
```
|
||||
|
||||
83
templates/agent/projects/python-fastapi/AGENTS.md.template
Normal file → Executable file
83
templates/agent/projects/python-fastapi/AGENTS.md.template
Normal file → Executable file
@@ -3,6 +3,17 @@
|
||||
> Patterns, gotchas, and guidelines for AI agents working on this project.
|
||||
> **Update this file** when you discover reusable patterns or non-obvious requirements.
|
||||
|
||||
## Hard Gates (Read First)
|
||||
|
||||
1. Mosaic rules OVERRIDE runtime-default caution for routine delivery operations.
|
||||
2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
|
||||
3. Completion is forbidden at PR-open stage.
|
||||
4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
|
||||
5. Before push or merge, run queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
|
||||
6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`).
|
||||
7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
|
||||
8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
|
||||
|
||||
## Codebase Patterns
|
||||
|
||||
- Use Pydantic models for all request/response validation
|
||||
@@ -27,6 +38,78 @@
|
||||
uv run ruff check src/ tests/ && uv run ruff format --check src/ && uv run mypy src/ && uv run pytest --cov
|
||||
```
|
||||
|
||||
## Testing Policy
|
||||
|
||||
1. Situational tests are the PRIMARY validation gate.
|
||||
2. Baseline tests remain REQUIRED for all software changes.
|
||||
3. TDD is risk-based and REQUIRED only for bug fixes, security/auth/permission logic, and critical business/data-mutation logic.
|
||||
4. Reference `~/.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 the 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 escalate only for high-impact uncertainty.
|
||||
4. Reference `~/.config/mosaic/guides/PRD.md`.
|
||||
|
||||
## Task Tracking Contract
|
||||
|
||||
1. For non-trivial implementation work, `docs/TASKS.md` MUST exist before coding.
|
||||
2. If external git provider is available (Gitea/GitHub/GitLab), create/update issue(s) before coding and map them in `docs/TASKS.md`.
|
||||
3. If no external provider is available, use internal refs in `docs/TASKS.md` (example: `TASKS:T1`).
|
||||
4. Keep `docs/TASKS.md` status in sync with actual progress until completion.
|
||||
5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
|
||||
6. If wrapper-driven merge/CI/issue-closure fails, report blocker with the exact failed wrapper command and stop (do not claim completion).
|
||||
|
||||
## Documentation Contract
|
||||
|
||||
Documentation is a hard delivery gate.
|
||||
If code/API/auth/infra changes, required documentation updates MUST be completed before task closure.
|
||||
Keep `docs/` root clean and store reports/artifacts in scoped folders (`docs/reports/`, `docs/tasks/`, `docs/releases/`, `docs/scratchpads/`).
|
||||
|
||||
Reference:
|
||||
- `~/.config/mosaic/guides/DOCUMENTATION.md`
|
||||
- `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md`
|
||||
|
||||
## 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. Shift to conservative strategy when budget pressure rises (smaller scope, fewer parallel actions, reduced re-reading).
|
||||
4. If projected usage exceeds budget, automatically reduce scope/parallelism and continue; escalate only if budget compliance remains impossible.
|
||||
|
||||
## Merge Strategy (Hard Rule)
|
||||
|
||||
1. Create short-lived branches from `main`.
|
||||
2. Open PRs to `main` for delivery changes.
|
||||
3. Do not push directly to `main`.
|
||||
4. Merge PRs to `main` with squash strategy only.
|
||||
5. Do not mark implementation complete until PR is merged.
|
||||
6. Do not mark implementation complete until CI/pipeline status is terminal green.
|
||||
7. Close linked issues/tasks only after merge + green CI.
|
||||
8. Before push or merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
|
||||
|
||||
## Container Release Strategy (When Applicable)
|
||||
|
||||
1. Use immutable image tags: `sha-<shortsha>` and `v{base-version}-rc.{build}`.
|
||||
2. Use mutable environment tags only as pointers (`testing`, optional `staging`, `prod`).
|
||||
3. Deploy/promote by immutable digest; do not deploy by mutable tag alone.
|
||||
4. Do not use `latest` or `dev` as deployment references.
|
||||
5. Use blue-green by default; use canary only with automated metrics and rollback gates.
|
||||
|
||||
## Steered Autonomy Contract
|
||||
|
||||
1. Agent owns end-to-end delivery: plan, code, test, review, remediate, commit, push, 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. Code review is agent-executed and REQUIRED for any source-code change.
|
||||
|
||||
## 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...`
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|
||||
92
templates/agent/projects/python-fastapi/CLAUDE.md.template
Normal file → Executable file
92
templates/agent/projects/python-fastapi/CLAUDE.md.template
Normal file → Executable file
@@ -9,15 +9,17 @@
|
||||
|
||||
| Task Type | Guide |
|
||||
|-----------|-------|
|
||||
| Bootstrapping this project | `~/.config/mosaic/guides/bootstrap.md` |
|
||||
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
|
||||
| Ralph autonomous development | `~/.config/mosaic/guides/ralph-autonomous.md` |
|
||||
| Backend/API development | `~/.config/mosaic/guides/backend.md` |
|
||||
| Authentication/Authorization | `~/.config/mosaic/guides/authentication.md` |
|
||||
| Code review | `~/.config/mosaic/guides/code-review.md` |
|
||||
| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
|
||||
| Infrastructure/DevOps | `~/.config/mosaic/guides/infrastructure.md` |
|
||||
| Secrets management (Vault) | `~/.config/mosaic/guides/vault-secrets.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` |
|
||||
| Backend/API development | `~/.config/mosaic/guides/BACKEND.md` |
|
||||
| Authentication/Authorization | `~/.config/mosaic/guides/AUTHENTICATION.md` |
|
||||
| Code review | `~/.config/mosaic/guides/CODE-REVIEW.md` |
|
||||
| Documentation updates and standards | `~/.config/mosaic/guides/DOCUMENTATION.md` |
|
||||
| QA/Testing | `~/.config/mosaic/guides/QA-TESTING.md` |
|
||||
| Infrastructure/DevOps | `~/.config/mosaic/guides/INFRASTRUCTURE.md` |
|
||||
| Secrets management (Vault) | `~/.config/mosaic/guides/VAULT-SECRETS.md` |
|
||||
|
||||
## Technology Stack
|
||||
|
||||
@@ -43,6 +45,7 @@ ${PROJECT_DIR}/
|
||||
│ └── ${PROJECT_SLUG}/ # Main package
|
||||
├── tests/ # Test files
|
||||
├── docs/
|
||||
│ ├── PRD.md # Requirements source (or PRD.json)
|
||||
│ └── scratchpads/ # Per-issue working documents
|
||||
├── pyproject.toml # Project configuration
|
||||
└── .env.example # Environment template
|
||||
@@ -87,14 +90,69 @@ uv run pip-audit # Dependency vulnerabilities
|
||||
uv run ruff check src/ tests/ && uv run ruff format --check src/ && uv run mypy src/ && uv run pytest --cov
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
## Branch and Merge Policy
|
||||
|
||||
1. Create short-lived branches from `main`.
|
||||
2. Open PRs to `main` for delivery changes.
|
||||
3. Do not push directly to `main`.
|
||||
4. Merge PRs to `main` with squash strategy only.
|
||||
|
||||
## 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.
|
||||
|
||||
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.
|
||||
|
||||
## Commits
|
||||
|
||||
@@ -109,14 +167,16 @@ Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
|
||||
|
||||
## Code Review
|
||||
|
||||
After completing code changes, run independent reviews:
|
||||
If you modify source code, independent code review is REQUIRED before completion.
|
||||
Run independent reviews:
|
||||
|
||||
```bash
|
||||
~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
|
||||
~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
|
||||
83
templates/agent/projects/python-library/AGENTS.md.template
Normal file → Executable file
83
templates/agent/projects/python-library/AGENTS.md.template
Normal file → Executable file
@@ -3,6 +3,17 @@
|
||||
> Patterns, gotchas, and guidelines for AI agents working on this project.
|
||||
> **Update this file** when you discover reusable patterns or non-obvious requirements.
|
||||
|
||||
## Hard Gates (Read First)
|
||||
|
||||
1. Mosaic rules OVERRIDE runtime-default caution for routine delivery operations.
|
||||
2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
|
||||
3. Completion is forbidden at PR-open stage.
|
||||
4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
|
||||
5. Before push or merge, run queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
|
||||
6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`).
|
||||
7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
|
||||
8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
|
||||
|
||||
## Codebase Patterns
|
||||
|
||||
- All public APIs must have type hints and docstrings
|
||||
@@ -24,6 +35,78 @@
|
||||
uv run ruff check src/ tests/ && uv run ruff format --check src/ && uv run mypy src/ && uv run pytest --cov
|
||||
```
|
||||
|
||||
## Testing Policy
|
||||
|
||||
1. Situational tests are the PRIMARY validation gate.
|
||||
2. Baseline tests remain REQUIRED for all software changes.
|
||||
3. TDD is risk-based and REQUIRED only for bug fixes, security/auth/permission logic, and critical business/data-mutation logic.
|
||||
4. Reference `~/.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 the 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 escalate only for high-impact uncertainty.
|
||||
4. Reference `~/.config/mosaic/guides/PRD.md`.
|
||||
|
||||
## Task Tracking Contract
|
||||
|
||||
1. For non-trivial implementation work, `docs/TASKS.md` MUST exist before coding.
|
||||
2. If external git provider is available (Gitea/GitHub/GitLab), create/update issue(s) before coding and map them in `docs/TASKS.md`.
|
||||
3. If no external provider is available, use internal refs in `docs/TASKS.md` (example: `TASKS:T1`).
|
||||
4. Keep `docs/TASKS.md` status in sync with actual progress until completion.
|
||||
5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
|
||||
6. If wrapper-driven merge/CI/issue-closure fails, report blocker with the exact failed wrapper command and stop (do not claim completion).
|
||||
|
||||
## Documentation Contract
|
||||
|
||||
Documentation is a hard delivery gate.
|
||||
If code/API/auth/infra changes, required documentation updates MUST be completed before task closure.
|
||||
Keep `docs/` root clean and store reports/artifacts in scoped folders (`docs/reports/`, `docs/tasks/`, `docs/releases/`, `docs/scratchpads/`).
|
||||
|
||||
Reference:
|
||||
- `~/.config/mosaic/guides/DOCUMENTATION.md`
|
||||
- `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md`
|
||||
|
||||
## 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. Shift to conservative strategy when budget pressure rises (smaller scope, fewer parallel actions, reduced re-reading).
|
||||
4. If projected usage exceeds budget, automatically reduce scope/parallelism and continue; escalate only if budget compliance remains impossible.
|
||||
|
||||
## Merge Strategy (Hard Rule)
|
||||
|
||||
1. Create short-lived branches from `main`.
|
||||
2. Open PRs to `main` for delivery changes.
|
||||
3. Do not push directly to `main`.
|
||||
4. Merge PRs to `main` with squash strategy only.
|
||||
5. Do not mark implementation complete until PR is merged.
|
||||
6. Do not mark implementation complete until CI/pipeline status is terminal green.
|
||||
7. Close linked issues/tasks only after merge + green CI.
|
||||
8. Before push or merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
|
||||
|
||||
## Container Release Strategy (When Applicable)
|
||||
|
||||
1. Use immutable image tags: `sha-<shortsha>` and `v{base-version}-rc.{build}`.
|
||||
2. Use mutable environment tags only as pointers (`testing`, optional `staging`, `prod`).
|
||||
3. Deploy/promote by immutable digest; do not deploy by mutable tag alone.
|
||||
4. Do not use `latest` or `dev` as deployment references.
|
||||
5. Use blue-green by default; use canary only with automated metrics and rollback gates.
|
||||
|
||||
## Steered Autonomy Contract
|
||||
|
||||
1. Agent owns end-to-end delivery: plan, code, test, review, remediate, commit, push, 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. Code review is agent-executed and REQUIRED for any source-code change.
|
||||
|
||||
## 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...`
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|
||||
86
templates/agent/projects/python-library/CLAUDE.md.template
Normal file → Executable file
86
templates/agent/projects/python-library/CLAUDE.md.template
Normal file → Executable file
@@ -9,12 +9,14 @@
|
||||
|
||||
| Task Type | Guide |
|
||||
|-----------|-------|
|
||||
| Bootstrapping this project | `~/.config/mosaic/guides/bootstrap.md` |
|
||||
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
|
||||
| Ralph autonomous development | `~/.config/mosaic/guides/ralph-autonomous.md` |
|
||||
| Backend/API development | `~/.config/mosaic/guides/backend.md` |
|
||||
| Code review | `~/.config/mosaic/guides/code-review.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` |
|
||||
| Backend/API development | `~/.config/mosaic/guides/BACKEND.md` |
|
||||
| Code review | `~/.config/mosaic/guides/CODE-REVIEW.md` |
|
||||
| Documentation updates and standards | `~/.config/mosaic/guides/DOCUMENTATION.md` |
|
||||
| QA/Testing | `~/.config/mosaic/guides/QA-TESTING.md` |
|
||||
|
||||
## Technology Stack
|
||||
|
||||
@@ -37,6 +39,7 @@ ${PROJECT_DIR}/
|
||||
│ └── ${PROJECT_SLUG}/ # Main package
|
||||
├── tests/ # Test files
|
||||
├── docs/
|
||||
│ ├── PRD.md # Requirements source (or PRD.json)
|
||||
│ └── scratchpads/ # Per-issue working documents
|
||||
└── pyproject.toml # Project configuration
|
||||
```
|
||||
@@ -69,6 +72,33 @@ uv run mypy src/ # Type check
|
||||
uv run ruff check src/ tests/ && uv run ruff format --check src/ && uv run mypy src/ && uv run pytest --cov
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
## Branch and Merge Policy
|
||||
|
||||
1. Create short-lived branches from `main`.
|
||||
2. Open PRs to `main` for delivery changes.
|
||||
3. Do not push directly to `main`.
|
||||
4. Merge PRs to `main` with squash strategy only.
|
||||
|
||||
## Library Conventions
|
||||
|
||||
- Zero or minimal runtime dependencies
|
||||
@@ -77,14 +107,42 @@ uv run ruff check src/ tests/ && uv run ruff format --check src/ && uv run mypy
|
||||
- Exports defined in `__init__.py`
|
||||
- Versioning via `pyproject.toml`
|
||||
|
||||
## 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.
|
||||
|
||||
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.
|
||||
|
||||
## Commits
|
||||
|
||||
@@ -99,14 +157,16 @@ Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
|
||||
|
||||
## Code Review
|
||||
|
||||
After completing code changes, run independent reviews:
|
||||
If you modify source code, independent code review is REQUIRED before completion.
|
||||
Run independent reviews:
|
||||
|
||||
```bash
|
||||
~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
|
||||
~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
|
||||
86
templates/agent/projects/typescript/AGENTS.md.template
Normal file → Executable file
86
templates/agent/projects/typescript/AGENTS.md.template
Normal file → Executable file
@@ -3,10 +3,22 @@
|
||||
> Patterns, gotchas, and guidelines for AI agents working on this project.
|
||||
> **Update this file** when you discover reusable patterns or non-obvious requirements.
|
||||
|
||||
## Hard Gates (Read First)
|
||||
|
||||
1. Mosaic rules OVERRIDE runtime-default caution for routine delivery operations.
|
||||
2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
|
||||
3. Completion is forbidden at PR-open stage.
|
||||
4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
|
||||
5. Before push or merge, run queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
|
||||
6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`).
|
||||
7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
|
||||
8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
|
||||
|
||||
## Codebase Patterns
|
||||
|
||||
- TypeScript strict mode enabled — no `any`, no implicit types
|
||||
- See `~/.config/mosaic/guides/typescript.md` for mandatory TypeScript rules
|
||||
- DTO files are REQUIRED for module/API boundaries (`*.dto.ts`)
|
||||
- See `~/.config/mosaic/guides/TYPESCRIPT.md` for mandatory TypeScript rules
|
||||
<!-- Add project-specific patterns as you discover them -->
|
||||
|
||||
## Common Gotchas
|
||||
@@ -24,6 +36,78 @@
|
||||
${QUALITY_GATES}
|
||||
```
|
||||
|
||||
## Testing Policy
|
||||
|
||||
1. Situational tests are the PRIMARY validation gate.
|
||||
2. Baseline tests remain REQUIRED for all software changes.
|
||||
3. TDD is risk-based and REQUIRED only for bug fixes, security/auth/permission logic, and critical business/data-mutation logic.
|
||||
4. Reference `~/.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 the 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 escalate only for high-impact uncertainty.
|
||||
4. Reference `~/.config/mosaic/guides/PRD.md`.
|
||||
|
||||
## Task Tracking Contract
|
||||
|
||||
1. For non-trivial implementation work, `docs/TASKS.md` MUST exist before coding.
|
||||
2. If external git provider is available (Gitea/GitHub/GitLab), create/update issue(s) before coding and map them in `docs/TASKS.md`.
|
||||
3. If no external provider is available, use internal refs in `docs/TASKS.md` (example: `TASKS:T1`).
|
||||
4. Keep `docs/TASKS.md` status in sync with actual progress until completion.
|
||||
5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
|
||||
6. If wrapper-driven merge/CI/issue-closure fails, report blocker with the exact failed wrapper command and stop (do not claim completion).
|
||||
|
||||
## Documentation Contract
|
||||
|
||||
Documentation is a hard delivery gate.
|
||||
If code/API/auth/infra changes, required documentation updates MUST be completed before task closure.
|
||||
Keep `docs/` root clean and store reports/artifacts in scoped folders (`docs/reports/`, `docs/tasks/`, `docs/releases/`, `docs/scratchpads/`).
|
||||
|
||||
Reference:
|
||||
- `~/.config/mosaic/guides/DOCUMENTATION.md`
|
||||
- `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md`
|
||||
|
||||
## 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. Shift to conservative strategy when budget pressure rises (smaller scope, fewer parallel actions, reduced re-reading).
|
||||
4. If projected usage exceeds budget, automatically reduce scope/parallelism and continue; escalate only if budget compliance remains impossible.
|
||||
|
||||
## Merge Strategy (Hard Rule)
|
||||
|
||||
1. Create short-lived branches from `main`.
|
||||
2. Open PRs to `main` for delivery changes.
|
||||
3. Do not push directly to `main`.
|
||||
4. Merge PRs to `main` with squash strategy only.
|
||||
5. Do not mark implementation complete until PR is merged.
|
||||
6. Do not mark implementation complete until CI/pipeline status is terminal green.
|
||||
7. Close linked issues/tasks only after merge + green CI.
|
||||
8. Before push or merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
|
||||
|
||||
## Container Release Strategy (When Applicable)
|
||||
|
||||
1. Use immutable image tags: `sha-<shortsha>` and `v{base-version}-rc.{build}`.
|
||||
2. Use mutable environment tags only as pointers (`testing`, optional `staging`, `prod`).
|
||||
3. Deploy/promote by immutable digest; do not deploy by mutable tag alone.
|
||||
4. Do not use `latest` or `dev` as deployment references.
|
||||
5. Use blue-green by default; use canary only with automated metrics and rollback gates.
|
||||
|
||||
## Steered Autonomy Contract
|
||||
|
||||
1. Agent owns end-to-end delivery: plan, code, test, review, remediate, commit, push, 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. Code review is agent-executed and REQUIRED for any source-code change.
|
||||
|
||||
## 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...`
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|
||||
95
templates/agent/projects/typescript/CLAUDE.md.template
Normal file → Executable file
95
templates/agent/projects/typescript/CLAUDE.md.template
Normal file → Executable file
@@ -9,13 +9,15 @@
|
||||
|
||||
| Task Type | Guide |
|
||||
|-----------|-------|
|
||||
| Bootstrapping this project | `~/.config/mosaic/guides/bootstrap.md` |
|
||||
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
|
||||
| Ralph autonomous development | `~/.config/mosaic/guides/ralph-autonomous.md` |
|
||||
| Frontend development | `~/.config/mosaic/guides/frontend.md` |
|
||||
| TypeScript strict typing | `~/.config/mosaic/guides/typescript.md` |
|
||||
| Code review | `~/.config/mosaic/guides/code-review.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` |
|
||||
| Frontend development | `~/.config/mosaic/guides/FRONTEND.md` |
|
||||
| TypeScript strict typing | `~/.config/mosaic/guides/TYPESCRIPT.md` |
|
||||
| Code review | `~/.config/mosaic/guides/CODE-REVIEW.md` |
|
||||
| Documentation updates and standards | `~/.config/mosaic/guides/DOCUMENTATION.md` |
|
||||
| QA/Testing | `~/.config/mosaic/guides/QA-TESTING.md` |
|
||||
|
||||
## Technology Stack
|
||||
|
||||
@@ -37,6 +39,7 @@ ${PROJECT_DIR}/
|
||||
├── src/ # Source code
|
||||
├── tests/ # Test files
|
||||
├── docs/
|
||||
│ ├── PRD.md # Requirements source (or PRD.json)
|
||||
│ └── scratchpads/ # Per-issue working documents
|
||||
└── ${CONFIG_FILES} # Configuration files
|
||||
```
|
||||
@@ -67,14 +70,76 @@ ${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.
|
||||
|
||||
## DTO Contract (TypeScript)
|
||||
|
||||
1. DTO files are REQUIRED for module and API boundaries.
|
||||
2. Boundary payload types MUST be defined in `*.dto.ts` files.
|
||||
3. Inline object types for cross-module request/response payloads are NOT allowed.
|
||||
4. Shared DTOs MUST be centralized in a shared location.
|
||||
|
||||
## 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.
|
||||
|
||||
## Branch and Merge Policy
|
||||
|
||||
1. Create short-lived branches from `main`.
|
||||
2. Open PRs to `main` for delivery changes.
|
||||
3. Do not push directly to `main`.
|
||||
4. Merge PRs to `main` with squash strategy only.
|
||||
|
||||
## 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.
|
||||
|
||||
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.
|
||||
|
||||
## Commits
|
||||
|
||||
@@ -89,7 +154,8 @@ Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
|
||||
|
||||
## Code Review
|
||||
|
||||
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)
|
||||
@@ -100,7 +166,8 @@ After completing code changes, run independent reviews:
|
||||
```
|
||||
|
||||
**Fallback:** If Codex is unavailable, use Claude's built-in review skills.
|
||||
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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user