centralize guides and rails under mosaic with runtime compatibility links
This commit is contained in:
Jason Woltje
79
templates/agent/projects/django/AGENTS.md.template
Normal file
79
templates/agent/projects/django/AGENTS.md.template
Normal file
@@ -0,0 +1,79 @@
|
||||
# ${PROJECT_NAME} — Agent Context
|
||||
|
||||
> Guidelines for AI agents working on this Django project.
|
||||
> **Update this file** when you discover reusable patterns or non-obvious requirements.
|
||||
|
||||
## Codebase Patterns
|
||||
|
||||
- **Django project:** Standard Django project layout
|
||||
- **Database:** PostgreSQL with Django ORM
|
||||
- **API:** Django REST Framework for REST endpoints
|
||||
- **Tasks:** Celery for background/async tasks
|
||||
- **Config:** Environment variables via `.env` / `python-dotenv`
|
||||
|
||||
## Common Gotchas
|
||||
|
||||
- **Run migrations** after model changes: `python manage.py makemigrations && python manage.py migrate`
|
||||
- **Import order matters:** Django setup must happen before model imports
|
||||
- **Celery tasks** must be importable from `tasks.py` in each app
|
||||
- **Settings module:** Check `DJANGO_SETTINGS_MODULE` environment variable
|
||||
- **Test database:** Tests use a separate database — check `TEST` config in settings
|
||||
- **Static files:** Run `collectstatic` before deployment
|
||||
|
||||
## Context Management
|
||||
|
||||
| Strategy | When |
|
||||
|----------|------|
|
||||
| **Spawn sub-agents** | Isolated coding tasks, research |
|
||||
| **Batch operations** | Group related operations |
|
||||
| **Check existing patterns** | Before writing new code |
|
||||
| **Minimize re-reading** | Don't re-read files you just wrote |
|
||||
|
||||
## Quality Gates
|
||||
|
||||
**All must pass before any commit:**
|
||||
|
||||
```bash
|
||||
ruff check . && mypy . && pytest tests/
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
### Post-Coding Review
|
||||
After implementing changes, the orchestrator will run:
|
||||
1. **Codex code review** — `~/.mosaic/rails/codex/codex-code-review.sh --uncommitted`
|
||||
2. **Codex security review** — `~/.mosaic/rails/codex/codex-security-review.sh --uncommitted`
|
||||
3. If blockers/critical findings: remediation task created
|
||||
4. If clean: task marked done
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `CLAUDE.md` | Project overview and conventions |
|
||||
| `pyproject.toml` | Python dependencies and tool config |
|
||||
| `${SOURCE_DIR}/manage.py` | Django management entry point |
|
||||
| `.env.example` | Required environment variables |
|
||||
|
||||
## Testing Approaches
|
||||
|
||||
- Unit tests: `pytest` with fixtures in `conftest.py`
|
||||
- API tests: DRF's `APITestCase` or pytest with `api_client` fixture
|
||||
- Database tests: Use `@pytest.mark.django_db` decorator
|
||||
- Mocking: `unittest.mock.patch` for external services
|
||||
- Minimum 85% coverage for new code
|
||||
|
||||
---
|
||||
|
||||
_Model-agnostic. Works for Claude, Codex, GPT, Llama, etc._
|
||||
168
templates/agent/projects/django/CLAUDE.md.template
Normal file
168
templates/agent/projects/django/CLAUDE.md.template
Normal file
@@ -0,0 +1,168 @@
|
||||
# ${PROJECT_NAME} — Claude Code Instructions
|
||||
|
||||
> **${PROJECT_DESCRIPTION}**
|
||||
|
||||
## Conditional Documentation Loading
|
||||
|
||||
| When working on... | Load this guide |
|
||||
|---|---|
|
||||
| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
|
||||
| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
|
||||
| Backend/API development | `~/.mosaic/guides/backend.md` |
|
||||
| Code review | `~/.mosaic/guides/code-review.md` |
|
||||
| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
|
||||
|
||||
## Technology Stack
|
||||
|
||||
| Layer | Technology |
|
||||
|-------|------------|
|
||||
| **Backend** | Django / Django REST Framework |
|
||||
| **Database** | PostgreSQL |
|
||||
| **Task Queue** | Celery + Redis/Valkey |
|
||||
| **Testing** | pytest + pytest-django |
|
||||
| **Linting** | ruff |
|
||||
| **Type Checking** | mypy |
|
||||
| **Deployment** | Docker + docker-compose |
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
${PROJECT_DIR}/
|
||||
├── CLAUDE.md # This file
|
||||
├── AGENTS.md # Agent-specific patterns and gotchas
|
||||
├── ${SOURCE_DIR}/ # Django project root
|
||||
│ ├── manage.py
|
||||
│ ├── ${PROJECT_SLUG}/ # Django settings module
|
||||
│ │ ├── settings.py
|
||||
│ │ ├── urls.py
|
||||
│ │ └── wsgi.py
|
||||
│ └── apps/ # Django applications
|
||||
├── tests/ # Test files
|
||||
├── docs/
|
||||
│ ├── scratchpads/ # Per-issue working documents
|
||||
│ └── templates/ # Project templates
|
||||
├── pyproject.toml # Python project configuration
|
||||
├── .env.example
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Branch Strategy
|
||||
- `main` — Production-ready code
|
||||
- `develop` — Integration branch (if used)
|
||||
- `feat/<name>` — Feature branches
|
||||
- `fix/<name>` — Bug fix branches
|
||||
|
||||
### Starting Work
|
||||
```bash
|
||||
git pull --rebase
|
||||
uv sync # or pip install -e ".[dev]"
|
||||
```
|
||||
|
||||
### Building / Running
|
||||
```bash
|
||||
python manage.py runserver # Development server
|
||||
python manage.py migrate # Apply migrations
|
||||
python manage.py shell # Django shell
|
||||
```
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
pytest tests/ # Run all tests
|
||||
pytest tests/ -x # Stop on first failure
|
||||
pytest tests/ --cov # With coverage
|
||||
```
|
||||
|
||||
### Linting & Type Checking
|
||||
```bash
|
||||
ruff check . # Lint
|
||||
ruff format . # Format
|
||||
mypy . # Type check
|
||||
```
|
||||
|
||||
## Quality Gates
|
||||
|
||||
**All must pass before committing:**
|
||||
|
||||
```bash
|
||||
ruff check . && mypy . && pytest tests/
|
||||
```
|
||||
|
||||
## Django Conventions
|
||||
|
||||
### Models
|
||||
- All tunable parameters stored in the database with `get_effective_*()` fallback patterns
|
||||
- Always create migrations for model changes: `python manage.py makemigrations`
|
||||
- Include migrations in commits
|
||||
- Use `models.TextChoices` or `models.IntegerChoices` for enum-like fields
|
||||
|
||||
### Views / API
|
||||
- Use Django REST Framework for API endpoints
|
||||
- Use serializers for validation
|
||||
- Use ViewSets for standard CRUD
|
||||
- Use permissions classes for authorization
|
||||
|
||||
### Management Commands
|
||||
- Place in `<app>/management/commands/`
|
||||
- Use `self.stdout.write()` for output
|
||||
- Handle interrupts gracefully
|
||||
|
||||
## Database
|
||||
|
||||
### Migration Workflow
|
||||
```bash
|
||||
# Create migration after model changes
|
||||
python manage.py makemigrations <app_name>
|
||||
|
||||
# Apply migrations
|
||||
python manage.py migrate
|
||||
|
||||
# Check for missing migrations
|
||||
python manage.py makemigrations --check
|
||||
```
|
||||
|
||||
### Rules
|
||||
- Always create migrations for schema changes
|
||||
- Include migrations in commits
|
||||
- Use `RunPython` for data migrations
|
||||
- Use transactions for multi-table operations
|
||||
|
||||
## Code Review
|
||||
|
||||
### Independent Review (Automated)
|
||||
After completing code changes, run independent reviews:
|
||||
|
||||
```bash
|
||||
# Code quality review (Codex)
|
||||
~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
|
||||
|
||||
# Security review (Codex)
|
||||
~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
|
||||
```
|
||||
|
||||
## Issue Tracking
|
||||
|
||||
### 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
|
||||
|
||||
### Commits
|
||||
```
|
||||
<type>(#issue): Brief description
|
||||
|
||||
Fixes #123
|
||||
```
|
||||
Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
|
||||
|
||||
## Secrets Management
|
||||
|
||||
**NEVER hardcode secrets.**
|
||||
|
||||
```bash
|
||||
# .env.example is committed (with placeholders)
|
||||
# .env is NOT committed (contains real values)
|
||||
# Load via python-dotenv or django-environ
|
||||
```
|
||||
91
templates/agent/projects/nestjs-nextjs/AGENTS.md.template
Normal file
91
templates/agent/projects/nestjs-nextjs/AGENTS.md.template
Normal file
@@ -0,0 +1,91 @@
|
||||
# ${PROJECT_NAME} — Agent Context
|
||||
|
||||
> Guidelines for AI agents working on this NestJS + Next.js monorepo.
|
||||
> **Update this file** when you discover reusable patterns or non-obvious requirements.
|
||||
|
||||
## Codebase Patterns
|
||||
|
||||
- **Monorepo structure:** pnpm workspaces + TurboRepo
|
||||
- `apps/api/` — NestJS backend
|
||||
- `apps/web/` — Next.js frontend
|
||||
- `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
|
||||
|
||||
## Common Gotchas
|
||||
|
||||
- **Always run `pnpm install`** after pulling — lockfile changes frequently
|
||||
- **Prisma generate** after schema changes: `pnpm --filter api prisma generate`
|
||||
- **Environment variables:** Frontend vars need `NEXT_PUBLIC_` prefix
|
||||
- **Import paths:** Use `@shared/` alias for shared package imports
|
||||
- **Tests require running database:** Set `DATABASE_URL` in `.env.test`
|
||||
- **TurboRepo caching:** Run `pnpm clean` if builds behave unexpectedly
|
||||
|
||||
## Context Management
|
||||
|
||||
Context = tokens = cost. Be smart.
|
||||
|
||||
| Strategy | When |
|
||||
|----------|------|
|
||||
| **Spawn sub-agents** | Isolated coding tasks, research |
|
||||
| **Batch operations** | Group related API calls |
|
||||
| **Check existing patterns** | Before writing new code |
|
||||
| **Minimize re-reading** | Don't re-read files you just wrote |
|
||||
|
||||
## Quality Gates
|
||||
|
||||
**All must pass before any commit:**
|
||||
|
||||
```bash
|
||||
pnpm typecheck && pnpm lint && pnpm test
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
### Post-Coding Review
|
||||
After implementing changes, the orchestrator will run:
|
||||
1. **Codex code review** — `~/.mosaic/rails/codex/codex-code-review.sh --uncommitted`
|
||||
2. **Codex security review** — `~/.mosaic/rails/codex/codex-security-review.sh --uncommitted`
|
||||
3. If blockers/critical findings: remediation task created
|
||||
4. If clean: task marked done
|
||||
|
||||
## Workflow (Non-Negotiable)
|
||||
|
||||
```
|
||||
1. Branch → git checkout -b feature/XX-description
|
||||
2. Code → TDD: write test (RED), implement (GREEN), refactor
|
||||
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
|
||||
7. Close → Close related issues
|
||||
```
|
||||
|
||||
**Never merge directly to develop without a PR.**
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `CLAUDE.md` | Project overview and conventions |
|
||||
| `apps/api/prisma/schema.prisma` | Database schema |
|
||||
| `apps/api/src/` | Backend source |
|
||||
| `apps/web/app/` | Frontend pages |
|
||||
| `packages/shared/` | Shared types |
|
||||
| `.env.example` | Required environment variables |
|
||||
|
||||
---
|
||||
|
||||
_Model-agnostic. Works for Claude, Codex, GPT, Llama, etc._
|
||||
200
templates/agent/projects/nestjs-nextjs/CLAUDE.md.template
Normal file
200
templates/agent/projects/nestjs-nextjs/CLAUDE.md.template
Normal file
@@ -0,0 +1,200 @@
|
||||
# ${PROJECT_NAME} — Claude Code Instructions
|
||||
|
||||
> **${PROJECT_DESCRIPTION}**
|
||||
|
||||
## Conditional Documentation Loading
|
||||
|
||||
| When working on... | Load this guide |
|
||||
|---|---|
|
||||
| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
|
||||
| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
|
||||
| Frontend development | `~/.mosaic/guides/frontend.md` |
|
||||
| Backend/API development | `~/.mosaic/guides/backend.md` |
|
||||
| Code review | `~/.mosaic/guides/code-review.md` |
|
||||
| TypeScript strict typing | `~/.mosaic/guides/typescript.md` |
|
||||
| Authentication/Authorization | `~/.mosaic/guides/authentication.md` |
|
||||
| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
|
||||
|
||||
## Technology Stack
|
||||
|
||||
| Layer | Technology |
|
||||
|-------|------------|
|
||||
| **Frontend** | Next.js + React + TailwindCSS + Shadcn/ui |
|
||||
| **Backend** | NestJS + Prisma ORM |
|
||||
| **Database** | PostgreSQL |
|
||||
| **Testing** | Vitest + Playwright |
|
||||
| **Monorepo** | pnpm workspaces + TurboRepo |
|
||||
| **Deployment** | Docker + docker-compose |
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
${PROJECT_DIR}/
|
||||
├── CLAUDE.md # This file
|
||||
├── AGENTS.md # Agent-specific patterns and gotchas
|
||||
├── apps/
|
||||
│ ├── api/ # NestJS backend
|
||||
│ │ ├── src/
|
||||
│ │ ├── prisma/
|
||||
│ │ │ └── schema.prisma
|
||||
│ │ └── Dockerfile
|
||||
│ └── web/ # Next.js frontend
|
||||
│ ├── app/
|
||||
│ ├── components/
|
||||
│ └── Dockerfile
|
||||
├── packages/
|
||||
│ ├── shared/ # Shared types, utilities
|
||||
│ ├── ui/ # Shared UI components
|
||||
│ └── config/ # Shared configuration
|
||||
├── docs/
|
||||
│ ├── scratchpads/ # Per-issue working documents
|
||||
│ └── templates/ # Project templates
|
||||
├── tests/ # Integration/E2E tests
|
||||
├── docker/ # Docker configuration
|
||||
├── .env.example
|
||||
├── turbo.json
|
||||
├── pnpm-workspace.yaml
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Branch Strategy
|
||||
- `main` — Stable releases only
|
||||
- `develop` — Active development (default working branch)
|
||||
- `feature/*` — Feature branches from develop
|
||||
- `fix/*` — Bug fix branches
|
||||
|
||||
### Starting Work
|
||||
```bash
|
||||
git checkout develop
|
||||
git pull --rebase
|
||||
pnpm install
|
||||
```
|
||||
|
||||
### Building
|
||||
```bash
|
||||
pnpm build # Build all packages
|
||||
pnpm --filter api build # Build API only
|
||||
pnpm --filter web build # Build web only
|
||||
```
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
pnpm test # Run all tests
|
||||
pnpm test:unit # Unit tests (Vitest)
|
||||
pnpm test:e2e # E2E tests (Playwright)
|
||||
pnpm test:coverage # Coverage report
|
||||
```
|
||||
|
||||
### Linting & Type Checking
|
||||
```bash
|
||||
pnpm lint # ESLint
|
||||
pnpm typecheck # TypeScript type checking
|
||||
pnpm format # Prettier formatting
|
||||
```
|
||||
|
||||
## Quality Gates
|
||||
|
||||
**All must pass before committing:**
|
||||
|
||||
```bash
|
||||
pnpm typecheck && pnpm lint && pnpm test
|
||||
```
|
||||
|
||||
## API Conventions
|
||||
|
||||
### NestJS Patterns
|
||||
- Controllers handle HTTP, Services handle business logic
|
||||
- Use DTOs with `class-validator` for request validation
|
||||
- Use Guards for authentication/authorization
|
||||
- Use Interceptors for response transformation
|
||||
- Use Prisma for database access (no raw SQL)
|
||||
|
||||
### REST API Standards
|
||||
- `GET /resource` — List (with pagination)
|
||||
- `GET /resource/:id` — Get single
|
||||
- `POST /resource` — Create
|
||||
- `PATCH /resource/:id` — Update
|
||||
- `DELETE /resource/:id` — Delete
|
||||
- Return proper HTTP status codes (201 Created, 204 No Content, etc.)
|
||||
|
||||
## Frontend Conventions
|
||||
|
||||
### Next.js Patterns
|
||||
- Use App Router (`app/` directory)
|
||||
- Server Components by default, `'use client'` only when needed
|
||||
- Use Shadcn/ui components — don't create custom UI primitives
|
||||
- Use TailwindCSS for styling — no CSS modules or styled-components
|
||||
|
||||
### Component Structure
|
||||
```
|
||||
components/
|
||||
├── ui/ # Shadcn/ui components (auto-generated)
|
||||
├── layout/ # Layout components (header, sidebar, etc.)
|
||||
├── forms/ # Form components
|
||||
└── features/ # Feature-specific components
|
||||
```
|
||||
|
||||
## Database
|
||||
|
||||
### Prisma Workflow
|
||||
```bash
|
||||
# Generate client after schema changes
|
||||
pnpm --filter api prisma generate
|
||||
|
||||
# Create migration
|
||||
pnpm --filter api prisma migrate dev --name description
|
||||
|
||||
# Apply migrations
|
||||
pnpm --filter api prisma migrate deploy
|
||||
|
||||
# Reset database (dev only)
|
||||
pnpm --filter api prisma migrate reset
|
||||
```
|
||||
|
||||
### Rules
|
||||
- Always create migrations for schema changes
|
||||
- Include migrations in commits
|
||||
- Never use raw SQL — use Prisma client
|
||||
- Use transactions for multi-table operations
|
||||
|
||||
## Code Review
|
||||
|
||||
### Independent Review (Automated)
|
||||
After completing code changes, run independent reviews:
|
||||
|
||||
```bash
|
||||
# Code quality review (Codex)
|
||||
~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
|
||||
|
||||
# Security review (Codex)
|
||||
~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
|
||||
```
|
||||
|
||||
## Issue Tracking
|
||||
|
||||
### 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
|
||||
|
||||
### Commits
|
||||
```
|
||||
<type>(#issue): Brief description
|
||||
|
||||
Fixes #123
|
||||
```
|
||||
Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
|
||||
|
||||
## Secrets Management
|
||||
|
||||
**NEVER hardcode secrets.**
|
||||
|
||||
```bash
|
||||
# .env.example is committed (with placeholders)
|
||||
# .env is NOT committed (contains real values)
|
||||
```
|
||||
|
||||
Required environment variables are documented in `.env.example`.
|
||||
43
templates/agent/projects/python-fastapi/AGENTS.md.template
Normal file
43
templates/agent/projects/python-fastapi/AGENTS.md.template
Normal file
@@ -0,0 +1,43 @@
|
||||
# ${PROJECT_NAME} — Agent Context
|
||||
|
||||
> Patterns, gotchas, and guidelines for AI agents working on this project.
|
||||
> **Update this file** when you discover reusable patterns or non-obvious requirements.
|
||||
|
||||
## Codebase Patterns
|
||||
|
||||
- Use Pydantic models for all request/response validation
|
||||
- Use dependency injection (`Depends()`) for shared resources
|
||||
- Use `httpx.AsyncClient` for external HTTP calls
|
||||
- Use `BackgroundTasks` for fire-and-forget operations
|
||||
- Structured logging with `structlog` or `logging`
|
||||
<!-- Add project-specific patterns as you discover them -->
|
||||
|
||||
## Common Gotchas
|
||||
|
||||
- Always run `uv sync` after pulling — dependencies may have changed
|
||||
- Database migrations must be run before tests that use the DB
|
||||
- Async tests need `@pytest.mark.asyncio` decorator
|
||||
<!-- Add project-specific gotchas -->
|
||||
|
||||
## Quality Gates
|
||||
|
||||
**All must pass before any commit:**
|
||||
|
||||
```bash
|
||||
uv run ruff check src/ tests/ && uv run ruff format --check src/ && uv run mypy src/ && uv run pytest --cov
|
||||
```
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `pyproject.toml` | Project configuration, dependencies |
|
||||
| `src/${PROJECT_SLUG}/main.py` | Application entry point |
|
||||
<!-- Add project-specific key files -->
|
||||
|
||||
## Testing Approaches
|
||||
|
||||
- Unit tests: pytest with fixtures in `conftest.py`
|
||||
- API tests: `httpx.AsyncClient` with `TestClient`
|
||||
- Coverage minimum: 85%
|
||||
<!-- Document project-specific testing patterns -->
|
||||
135
templates/agent/projects/python-fastapi/CLAUDE.md.template
Normal file
135
templates/agent/projects/python-fastapi/CLAUDE.md.template
Normal file
@@ -0,0 +1,135 @@
|
||||
# ${PROJECT_NAME} — Claude Code Instructions
|
||||
|
||||
> **Project:** ${PROJECT_DESCRIPTION}
|
||||
> **Repository:** ${REPO_URL}
|
||||
|
||||
## Conditional Documentation Loading
|
||||
|
||||
**Read the relevant guide before starting work:**
|
||||
|
||||
| Task Type | Guide |
|
||||
|-----------|-------|
|
||||
| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
|
||||
| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
|
||||
| Ralph autonomous development | `~/.mosaic/guides/ralph-autonomous.md` |
|
||||
| Backend/API development | `~/.mosaic/guides/backend.md` |
|
||||
| Authentication/Authorization | `~/.mosaic/guides/authentication.md` |
|
||||
| Code review | `~/.mosaic/guides/code-review.md` |
|
||||
| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
|
||||
| Infrastructure/DevOps | `~/.mosaic/guides/infrastructure.md` |
|
||||
| Secrets management (Vault) | `~/.mosaic/guides/vault-secrets.md` |
|
||||
|
||||
## Technology Stack
|
||||
|
||||
| Layer | Technology |
|
||||
|-------|------------|
|
||||
| **Backend** | FastAPI |
|
||||
| **Language** | Python 3.11+ |
|
||||
| **Database** | ${DATABASE_STACK} |
|
||||
| **Testing** | pytest + httpx |
|
||||
| **Linting** | ruff |
|
||||
| **Type Checking** | mypy (strict) |
|
||||
| **Security** | bandit + pip-audit |
|
||||
| **Package Manager** | uv |
|
||||
| **Deployment** | ${DEPLOYMENT_STACK} |
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
${PROJECT_DIR}/
|
||||
├── CLAUDE.md # This file
|
||||
├── AGENTS.md # Agent-specific patterns and gotchas
|
||||
├── src/ # Source code
|
||||
│ └── ${PROJECT_SLUG}/ # Main package
|
||||
├── tests/ # Test files
|
||||
├── docs/
|
||||
│ └── scratchpads/ # Per-issue working documents
|
||||
├── pyproject.toml # Project configuration
|
||||
└── .env.example # Environment template
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Setup
|
||||
```bash
|
||||
uv sync --all-extras
|
||||
```
|
||||
|
||||
### Running
|
||||
```bash
|
||||
uv run uvicorn ${PROJECT_SLUG}.main:app --reload --port 8000
|
||||
```
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
uv run pytest # Run all tests
|
||||
uv run pytest --cov # With coverage (85% min)
|
||||
```
|
||||
|
||||
### Linting & Type Checking
|
||||
```bash
|
||||
uv run ruff check src/ tests/ # Lint
|
||||
uv run ruff format --check src/ # Format check
|
||||
uv run mypy src/ # Type check
|
||||
```
|
||||
|
||||
### Security
|
||||
```bash
|
||||
uv run bandit -r src/ # SAST scanning
|
||||
uv run pip-audit # Dependency vulnerabilities
|
||||
```
|
||||
|
||||
## Quality Gates
|
||||
|
||||
**All must pass before committing:**
|
||||
|
||||
```bash
|
||||
uv run ruff check src/ tests/ && uv run ruff format --check src/ && uv run mypy src/ && uv run pytest --cov
|
||||
```
|
||||
|
||||
## Issue Tracking
|
||||
|
||||
All work is tracked as issues in the project's git repository.
|
||||
|
||||
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
|
||||
|
||||
## Commits
|
||||
|
||||
```
|
||||
<type>(#issue): Brief description
|
||||
|
||||
Detailed explanation if needed.
|
||||
|
||||
Fixes #123
|
||||
```
|
||||
Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
|
||||
|
||||
## Code Review
|
||||
|
||||
After completing code changes, run independent reviews:
|
||||
|
||||
```bash
|
||||
~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
|
||||
~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
|
||||
```
|
||||
|
||||
See `~/.mosaic/guides/code-review.md` for the full review checklist.
|
||||
|
||||
## Secrets Management
|
||||
|
||||
**NEVER hardcode secrets.** Use `.env` files (gitignored) or a secrets manager.
|
||||
|
||||
```bash
|
||||
# .env.example is committed (with placeholders)
|
||||
# .env is NOT committed (contains real values)
|
||||
```
|
||||
|
||||
## Multi-Agent Coordination
|
||||
|
||||
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
|
||||
39
templates/agent/projects/python-library/AGENTS.md.template
Normal file
39
templates/agent/projects/python-library/AGENTS.md.template
Normal file
@@ -0,0 +1,39 @@
|
||||
# ${PROJECT_NAME} — Agent Context
|
||||
|
||||
> Patterns, gotchas, and guidelines for AI agents working on this project.
|
||||
> **Update this file** when you discover reusable patterns or non-obvious requirements.
|
||||
|
||||
## Codebase Patterns
|
||||
|
||||
- All public APIs must have type hints and docstrings
|
||||
- Zero or minimal runtime dependencies — be conservative adding deps
|
||||
- Exports defined in `__init__.py`
|
||||
<!-- Add project-specific patterns as you discover them -->
|
||||
|
||||
## Common Gotchas
|
||||
|
||||
- Always run `uv sync` after pulling — dependencies may have changed
|
||||
- Ensure backward compatibility — this is a library consumed by other projects
|
||||
<!-- Add project-specific gotchas -->
|
||||
|
||||
## Quality Gates
|
||||
|
||||
**All must pass before any commit:**
|
||||
|
||||
```bash
|
||||
uv run ruff check src/ tests/ && uv run ruff format --check src/ && uv run mypy src/ && uv run pytest --cov
|
||||
```
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `pyproject.toml` | Project configuration, dependencies, build |
|
||||
| `src/${PROJECT_SLUG}/__init__.py` | Public API exports |
|
||||
<!-- Add project-specific key files -->
|
||||
|
||||
## Testing Approaches
|
||||
|
||||
- Unit tests: pytest with fixtures in `conftest.py`
|
||||
- Coverage minimum: 85%
|
||||
<!-- Document project-specific testing patterns -->
|
||||
120
templates/agent/projects/python-library/CLAUDE.md.template
Normal file
120
templates/agent/projects/python-library/CLAUDE.md.template
Normal file
@@ -0,0 +1,120 @@
|
||||
# ${PROJECT_NAME} — Claude Code Instructions
|
||||
|
||||
> **Project:** ${PROJECT_DESCRIPTION}
|
||||
> **Repository:** ${REPO_URL}
|
||||
|
||||
## Conditional Documentation Loading
|
||||
|
||||
**Read the relevant guide before starting work:**
|
||||
|
||||
| Task Type | Guide |
|
||||
|-----------|-------|
|
||||
| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
|
||||
| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
|
||||
| Ralph autonomous development | `~/.mosaic/guides/ralph-autonomous.md` |
|
||||
| Backend/API development | `~/.mosaic/guides/backend.md` |
|
||||
| Code review | `~/.mosaic/guides/code-review.md` |
|
||||
| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
|
||||
|
||||
## Technology Stack
|
||||
|
||||
| Layer | Technology |
|
||||
|-------|------------|
|
||||
| **Language** | Python 3.11+ |
|
||||
| **Testing** | pytest |
|
||||
| **Linting** | ruff |
|
||||
| **Type Checking** | mypy (strict) |
|
||||
| **Package Manager** | uv |
|
||||
| **Build** | ${BUILD_SYSTEM} |
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
${PROJECT_DIR}/
|
||||
├── CLAUDE.md # This file
|
||||
├── AGENTS.md # Agent-specific patterns and gotchas
|
||||
├── src/
|
||||
│ └── ${PROJECT_SLUG}/ # Main package
|
||||
├── tests/ # Test files
|
||||
├── docs/
|
||||
│ └── scratchpads/ # Per-issue working documents
|
||||
└── pyproject.toml # Project configuration
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Setup
|
||||
```bash
|
||||
uv sync --all-extras
|
||||
```
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
uv run pytest # Run all tests
|
||||
uv run pytest --cov # With coverage (85% min)
|
||||
```
|
||||
|
||||
### Linting & Type Checking
|
||||
```bash
|
||||
uv run ruff check src/ tests/ # Lint
|
||||
uv run ruff format --check src/ # Format check
|
||||
uv run mypy src/ # Type check
|
||||
```
|
||||
|
||||
## Quality Gates
|
||||
|
||||
**All must pass before committing:**
|
||||
|
||||
```bash
|
||||
uv run ruff check src/ tests/ && uv run ruff format --check src/ && uv run mypy src/ && uv run pytest --cov
|
||||
```
|
||||
|
||||
## Library Conventions
|
||||
|
||||
- Zero or minimal runtime dependencies
|
||||
- All public APIs must have type hints
|
||||
- All public functions must have docstrings
|
||||
- Exports defined in `__init__.py`
|
||||
- Versioning via `pyproject.toml`
|
||||
|
||||
## Issue Tracking
|
||||
|
||||
All work is tracked as issues in the project's git repository.
|
||||
|
||||
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
|
||||
|
||||
## Commits
|
||||
|
||||
```
|
||||
<type>(#issue): Brief description
|
||||
|
||||
Detailed explanation if needed.
|
||||
|
||||
Fixes #123
|
||||
```
|
||||
Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
|
||||
|
||||
## Code Review
|
||||
|
||||
After completing code changes, run independent reviews:
|
||||
|
||||
```bash
|
||||
~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
|
||||
~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
|
||||
```
|
||||
|
||||
See `~/.mosaic/guides/code-review.md` for the full review checklist.
|
||||
|
||||
## Secrets Management
|
||||
|
||||
**NEVER hardcode secrets.** Use `.env` files (gitignored) or a secrets manager.
|
||||
|
||||
## Multi-Agent Coordination
|
||||
|
||||
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
|
||||
41
templates/agent/projects/typescript/AGENTS.md.template
Normal file
41
templates/agent/projects/typescript/AGENTS.md.template
Normal file
@@ -0,0 +1,41 @@
|
||||
# ${PROJECT_NAME} — Agent Context
|
||||
|
||||
> Patterns, gotchas, and guidelines for AI agents working on this project.
|
||||
> **Update this file** when you discover reusable patterns or non-obvious requirements.
|
||||
|
||||
## Codebase Patterns
|
||||
|
||||
- TypeScript strict mode enabled — no `any`, no implicit types
|
||||
- See `~/.mosaic/guides/typescript.md` for mandatory TypeScript rules
|
||||
<!-- Add project-specific patterns as you discover them -->
|
||||
|
||||
## Common Gotchas
|
||||
|
||||
<!-- Add things that trip up agents -->
|
||||
<!-- Examples: -->
|
||||
<!-- - Frontend env vars need NEXT_PUBLIC_ prefix -->
|
||||
<!-- - Tests require specific setup (describe in Testing section) -->
|
||||
|
||||
## Quality Gates
|
||||
|
||||
**All must pass before any commit:**
|
||||
|
||||
```bash
|
||||
${QUALITY_GATES}
|
||||
```
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `tsconfig.json` | TypeScript configuration |
|
||||
| `package.json` | Dependencies and scripts |
|
||||
<!-- Add project-specific key files -->
|
||||
|
||||
## Testing Approaches
|
||||
|
||||
<!-- Document how tests should be written for this project -->
|
||||
<!-- Examples: -->
|
||||
<!-- - Unit tests use Vitest with fixtures -->
|
||||
<!-- - Component tests use React Testing Library -->
|
||||
<!-- - E2E tests use Playwright -->
|
||||
119
templates/agent/projects/typescript/CLAUDE.md.template
Normal file
119
templates/agent/projects/typescript/CLAUDE.md.template
Normal file
@@ -0,0 +1,119 @@
|
||||
# ${PROJECT_NAME} — Claude Code Instructions
|
||||
|
||||
> **Project:** ${PROJECT_DESCRIPTION}
|
||||
> **Repository:** ${REPO_URL}
|
||||
|
||||
## Conditional Documentation Loading
|
||||
|
||||
**Read the relevant guide before starting work:**
|
||||
|
||||
| Task Type | Guide |
|
||||
|-----------|-------|
|
||||
| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
|
||||
| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
|
||||
| Ralph autonomous development | `~/.mosaic/guides/ralph-autonomous.md` |
|
||||
| Frontend development | `~/.mosaic/guides/frontend.md` |
|
||||
| TypeScript strict typing | `~/.mosaic/guides/typescript.md` |
|
||||
| Code review | `~/.mosaic/guides/code-review.md` |
|
||||
| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
|
||||
|
||||
## Technology Stack
|
||||
|
||||
| Layer | Technology |
|
||||
|-------|------------|
|
||||
| **Language** | TypeScript (strict mode) |
|
||||
| **Framework** | ${FRAMEWORK} |
|
||||
| **Testing** | ${TESTING_STACK} |
|
||||
| **Linting** | ESLint + Prettier |
|
||||
| **Package Manager** | ${PACKAGE_MANAGER} |
|
||||
| **Deployment** | ${DEPLOYMENT_STACK} |
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
${PROJECT_DIR}/
|
||||
├── CLAUDE.md # This file
|
||||
├── AGENTS.md # Agent-specific patterns and gotchas
|
||||
├── src/ # Source code
|
||||
├── tests/ # Test files
|
||||
├── docs/
|
||||
│ └── scratchpads/ # Per-issue working documents
|
||||
└── ${CONFIG_FILES} # Configuration files
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Building
|
||||
```bash
|
||||
${BUILD_COMMAND}
|
||||
```
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
${TEST_COMMAND}
|
||||
```
|
||||
|
||||
### Linting & Type Checking
|
||||
```bash
|
||||
${LINT_COMMAND}
|
||||
${TYPECHECK_COMMAND}
|
||||
```
|
||||
|
||||
## Quality Gates
|
||||
|
||||
**All must pass before committing:**
|
||||
|
||||
```bash
|
||||
${QUALITY_GATES}
|
||||
```
|
||||
|
||||
## Issue Tracking
|
||||
|
||||
All work is tracked as issues in the project's git repository.
|
||||
|
||||
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
|
||||
|
||||
## Commits
|
||||
|
||||
```
|
||||
<type>(#issue): Brief description
|
||||
|
||||
Detailed explanation if needed.
|
||||
|
||||
Fixes #123
|
||||
```
|
||||
Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
|
||||
|
||||
## Code Review
|
||||
|
||||
After completing code changes, run independent reviews:
|
||||
|
||||
```bash
|
||||
# Code quality review (Codex)
|
||||
~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
|
||||
|
||||
# Security review (Codex)
|
||||
~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
|
||||
```
|
||||
|
||||
**Fallback:** If Codex is unavailable, use Claude's built-in review skills.
|
||||
See `~/.mosaic/guides/code-review.md` for the full review checklist.
|
||||
|
||||
## Secrets Management
|
||||
|
||||
**NEVER hardcode secrets.** Use `.env` files (gitignored) or a secrets manager.
|
||||
|
||||
```bash
|
||||
# .env.example is committed (with placeholders)
|
||||
# .env is NOT committed (contains real values)
|
||||
```
|
||||
|
||||
## Multi-Agent Coordination
|
||||
|
||||
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
|
||||
Reference in New Issue
Block a user