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

83
templates/agent/projects/python-library/AGENTS.md.template Normal file → Executable file
View 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
View 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