feat: monorepo consolidation — forge pipeline, MACP protocol, framework plugin, profiles/guides/skills
Work packages completed: - WP1: packages/forge — pipeline runner, stage adapter, board tasks, brief classifier, persona loader with project-level overrides. 89 tests, 95.62% coverage. - WP2: packages/macp — credential resolver, gate runner, event emitter, protocol types. 65 tests, 96.24% coverage. Full Python-to-TS port preserving all behavior. - WP3: plugins/mosaic-framework — OC rails injection plugin (before_agent_start + subagent_spawning hooks for Mosaic contract enforcement). - WP4: profiles/ (domains, tech-stacks, workflows), guides/ (17 docs), skills/ (5 universal skills), forge pipeline assets (48 markdown files). Board deliberation: docs/reviews/consolidation-board-memo.md Brief: briefs/monorepo-consolidation.md Consolidates mosaic/stack (forge, MACP, bootstrap framework) into mosaic/mosaic-stack. 154 new tests total. Zero Python — all TypeScript/ESM.
This commit is contained in:
Mos (Agent)
193
guides/AUTHENTICATION.md
Normal file
193
guides/AUTHENTICATION.md
Normal file
@@ -0,0 +1,193 @@
|
||||
# Authentication & Authorization Guide
|
||||
|
||||
## Before Starting
|
||||
|
||||
1. Check assigned issue: `~/.config/mosaic/tools/git/issue-list.sh -a @me`
|
||||
2. Review existing auth implementation in codebase
|
||||
3. Review Vault secrets structure: `docs/vault-secrets-structure.md`
|
||||
|
||||
## Authentication Patterns
|
||||
|
||||
### JWT (JSON Web Tokens)
|
||||
|
||||
```
|
||||
Vault Path: secret-{env}/backend-api/jwt/signing-key
|
||||
Fields: key, algorithm, expiry_seconds
|
||||
```
|
||||
|
||||
**Best Practices:**
|
||||
|
||||
- Use RS256 or ES256 (asymmetric) for distributed systems
|
||||
- Use HS256 (symmetric) only for single-service auth
|
||||
- Set reasonable expiry (15min-1hr for access tokens)
|
||||
- Include minimal claims (sub, exp, iat, roles)
|
||||
- Never store sensitive data in JWT payload
|
||||
|
||||
### Session-Based
|
||||
|
||||
```
|
||||
Vault Path: secret-{env}/{service}/session/secret
|
||||
Fields: secret, cookie_name, max_age
|
||||
```
|
||||
|
||||
**Best Practices:**
|
||||
|
||||
- Use secure, httpOnly, sameSite cookies
|
||||
- Regenerate session ID on privilege change
|
||||
- Implement session timeout
|
||||
- Store sessions server-side (Redis/database)
|
||||
|
||||
### OAuth2/OIDC
|
||||
|
||||
```
|
||||
Vault Paths:
|
||||
- secret-{env}/{service}/oauth/{provider}/client_id
|
||||
- secret-{env}/{service}/oauth/{provider}/client_secret
|
||||
```
|
||||
|
||||
**Best Practices:**
|
||||
|
||||
- Use PKCE for public clients
|
||||
- Validate state parameter
|
||||
- Verify token signatures
|
||||
- Check issuer and audience claims
|
||||
|
||||
## Authorization Patterns
|
||||
|
||||
### Role-Based Access Control (RBAC)
|
||||
|
||||
```python
|
||||
# Example middleware
|
||||
def require_role(roles: list):
|
||||
def decorator(handler):
|
||||
def wrapper(request):
|
||||
user_roles = get_user_roles(request.user_id)
|
||||
if not any(role in user_roles for role in roles):
|
||||
raise ForbiddenError()
|
||||
return handler(request)
|
||||
return wrapper
|
||||
return decorator
|
||||
|
||||
@require_role(['admin', 'moderator'])
|
||||
def delete_user(request):
|
||||
pass
|
||||
```
|
||||
|
||||
### Permission-Based
|
||||
|
||||
```python
|
||||
# Check specific permissions
|
||||
def check_permission(user_id, resource, action):
|
||||
permissions = get_user_permissions(user_id)
|
||||
return f"{resource}:{action}" in permissions
|
||||
```
|
||||
|
||||
## Security Requirements
|
||||
|
||||
### Password Handling
|
||||
|
||||
- Use bcrypt, scrypt, or Argon2 for hashing
|
||||
- Minimum 12 character passwords
|
||||
- Check against breached password lists
|
||||
- Implement account lockout after failed attempts
|
||||
|
||||
### Token Security
|
||||
|
||||
- Rotate secrets regularly
|
||||
- Implement token revocation
|
||||
- Use short-lived access tokens with refresh tokens
|
||||
- Store refresh tokens securely (httpOnly cookies or encrypted storage)
|
||||
|
||||
### Multi-Factor Authentication
|
||||
|
||||
- Support TOTP (Google Authenticator compatible)
|
||||
- Consider WebAuthn for passwordless
|
||||
- Require MFA for sensitive operations
|
||||
|
||||
## Testing Authentication
|
||||
|
||||
### Test Cases Required
|
||||
|
||||
```python
|
||||
class TestAuthentication:
|
||||
def test_login_success_returns_token(self):
|
||||
pass
|
||||
def test_login_failure_returns_401(self):
|
||||
pass
|
||||
def test_invalid_token_returns_401(self):
|
||||
pass
|
||||
def test_expired_token_returns_401(self):
|
||||
pass
|
||||
def test_missing_token_returns_401(self):
|
||||
pass
|
||||
def test_insufficient_permissions_returns_403(self):
|
||||
pass
|
||||
def test_token_refresh_works(self):
|
||||
pass
|
||||
def test_logout_invalidates_token(self):
|
||||
pass
|
||||
```
|
||||
|
||||
## Authentik SSO Administration
|
||||
|
||||
Authentik is the identity provider for the Mosaic Stack. Use the Authentik tool suite for administration.
|
||||
|
||||
### Tool Suite
|
||||
|
||||
```bash
|
||||
# System health
|
||||
~/.config/mosaic/tools/authentik/admin-status.sh
|
||||
|
||||
# User management
|
||||
~/.config/mosaic/tools/authentik/user-list.sh
|
||||
~/.config/mosaic/tools/authentik/user-create.sh -u <username> -n <name> -e <email>
|
||||
|
||||
# Group and app management
|
||||
~/.config/mosaic/tools/authentik/group-list.sh
|
||||
~/.config/mosaic/tools/authentik/app-list.sh
|
||||
~/.config/mosaic/tools/authentik/flow-list.sh
|
||||
```
|
||||
|
||||
### Registering an OAuth Application
|
||||
|
||||
1. Create an OAuth2 provider in Authentik admin (Applications > Providers)
|
||||
2. Create an application linked to the provider (Applications > Applications)
|
||||
3. Configure redirect URIs for the application
|
||||
4. Store client_id and client_secret in Vault: `secret-{env}/{service}/oauth/authentik/`
|
||||
5. Verify with: `~/.config/mosaic/tools/authentik/app-list.sh`
|
||||
|
||||
### API Reference
|
||||
|
||||
- Base URL: `https://auth.diversecanvas.com`
|
||||
- API prefix: `/api/v3/`
|
||||
- OpenAPI schema: `/api/v3/schema/`
|
||||
- Auth: Bearer token (obtained via `auth-token.sh`)
|
||||
|
||||
## Common Vulnerabilities to Avoid
|
||||
|
||||
1. **Broken Authentication**
|
||||
- Weak password requirements
|
||||
- Missing brute-force protection
|
||||
- Session fixation
|
||||
|
||||
2. **Broken Access Control**
|
||||
- Missing authorization checks
|
||||
- IDOR (Insecure Direct Object Reference)
|
||||
- Privilege escalation
|
||||
|
||||
3. **Security Misconfiguration**
|
||||
- Default credentials
|
||||
- Verbose error messages
|
||||
- Missing security headers
|
||||
|
||||
## Commit Format
|
||||
|
||||
```
|
||||
feat(#89): Implement JWT authentication
|
||||
|
||||
- Add /auth/login and /auth/refresh endpoints
|
||||
- Implement token validation middleware
|
||||
- Configure 15min access token expiry
|
||||
|
||||
Fixes #89
|
||||
```
|
||||
125
guides/BACKEND.md
Normal file
125
guides/BACKEND.md
Normal file
@@ -0,0 +1,125 @@
|
||||
# Backend Development Guide
|
||||
|
||||
## Before Starting
|
||||
|
||||
1. Check assigned issue: `~/.config/mosaic/tools/git/issue-list.sh -a @me`
|
||||
2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
|
||||
3. Review API contracts and database schema
|
||||
|
||||
## Development Standards
|
||||
|
||||
### API Design
|
||||
|
||||
- Follow RESTful conventions (or GraphQL patterns if applicable)
|
||||
- Use consistent endpoint naming: `/api/v1/resource-name`
|
||||
- Return appropriate HTTP status codes
|
||||
- Include pagination for list endpoints
|
||||
- Document all endpoints (OpenAPI/Swagger preferred)
|
||||
|
||||
### Database
|
||||
|
||||
- Write migrations for schema changes
|
||||
- Use parameterized queries (prevent SQL injection)
|
||||
- Index frequently queried columns
|
||||
- Document relationships and constraints
|
||||
|
||||
### Error Handling
|
||||
|
||||
- Return structured error responses
|
||||
- Log errors with context (request ID, user ID if applicable)
|
||||
- Never expose internal errors to clients
|
||||
- Use appropriate error codes
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "VALIDATION_ERROR",
|
||||
"message": "User-friendly message",
|
||||
"details": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Security
|
||||
|
||||
- Validate all input at API boundaries
|
||||
- Implement rate limiting on public endpoints
|
||||
- Use secrets from Vault (see `docs/vault-secrets-structure.md`)
|
||||
- Never log sensitive data (passwords, tokens, PII)
|
||||
- Follow OWASP guidelines
|
||||
|
||||
### Authentication/Authorization
|
||||
|
||||
- Use project's established auth pattern
|
||||
- Validate tokens on every request
|
||||
- Check permissions before operations
|
||||
- See `~/.config/mosaic/guides/AUTHENTICATION.md` for details
|
||||
|
||||
## Testing Requirements (TDD)
|
||||
|
||||
1. Write tests BEFORE implementation
|
||||
2. Minimum 85% coverage
|
||||
3. Test categories:
|
||||
- Unit tests for business logic
|
||||
- Integration tests for API endpoints
|
||||
- Database tests with transactions/rollback
|
||||
|
||||
### Test Patterns
|
||||
|
||||
```python
|
||||
# API test example structure
|
||||
class TestResourceEndpoint:
|
||||
def test_create_returns_201(self):
|
||||
pass
|
||||
def test_create_validates_input(self):
|
||||
pass
|
||||
def test_get_returns_404_for_missing(self):
|
||||
pass
|
||||
def test_requires_authentication(self):
|
||||
pass
|
||||
```
|
||||
|
||||
## Code Style
|
||||
|
||||
- Follow Google Style Guide for your language
|
||||
- **TypeScript: Follow `~/.config/mosaic/guides/TYPESCRIPT.md` — MANDATORY**
|
||||
- Use linter/formatter from project configuration
|
||||
- Keep functions focused and small
|
||||
- Document complex business logic
|
||||
|
||||
### TypeScript Quick Rules (see TYPESCRIPT.md for full guide)
|
||||
|
||||
- **NO `any`** — define explicit types always
|
||||
- **NO lazy `unknown`** — only for error catches and external data with validation
|
||||
- **Explicit return types** on all exported functions
|
||||
- **Explicit parameter types** always
|
||||
- **DTO files are REQUIRED** for module/API boundaries (`*.dto.ts`)
|
||||
- **Interface for DTOs** — never inline object types
|
||||
- **Typed errors** — use custom error classes
|
||||
|
||||
## Performance
|
||||
|
||||
- Use database connection pooling
|
||||
- Implement caching where appropriate
|
||||
- Profile slow endpoints
|
||||
- Use async operations for I/O
|
||||
|
||||
## Commit Format
|
||||
|
||||
```
|
||||
feat(#45): Add user registration endpoint
|
||||
|
||||
- POST /api/v1/users for registration
|
||||
- Email validation and uniqueness check
|
||||
- Password hashing with bcrypt
|
||||
|
||||
Fixes #45
|
||||
```
|
||||
|
||||
## Before Completing
|
||||
|
||||
1. Run full test suite
|
||||
2. Verify migrations work (up and down)
|
||||
3. Test API with curl/httpie
|
||||
4. Update scratchpad with completion notes
|
||||
5. Reference issue in commit
|
||||
487
guides/BOOTSTRAP.md
Executable file
487
guides/BOOTSTRAP.md
Executable file
@@ -0,0 +1,487 @@
|
||||
# Project Bootstrap Guide
|
||||
|
||||
> Load this guide when setting up a new project for AI-assisted development.
|
||||
|
||||
## Overview
|
||||
|
||||
This guide covers how to bootstrap a project so AI agents (Claude, Codex, etc.) can work on it effectively. Proper bootstrapping ensures:
|
||||
|
||||
1. Agents understand the project structure and conventions
|
||||
2. Orchestration works correctly with quality gates
|
||||
3. Independent code review and security review are configured
|
||||
4. Issue tracking is consistent across projects
|
||||
5. Documentation standards and API contracts are enforced from day one
|
||||
6. PRD requirements are established before coding begins
|
||||
7. Branching/merging is consistent: `branch -> main` via PR with squash-only merges
|
||||
8. Steered-autonomy execution is enabled so agents can run end-to-end with escalation-only human intervention
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Automated bootstrap (recommended)
|
||||
~/.config/mosaic/tools/bootstrap/init-project.sh \
|
||||
--name "my-project" \
|
||||
--type "nestjs-nextjs" \
|
||||
--repo "https://git.mosaicstack.dev/owner/repo"
|
||||
|
||||
# Or manually using templates
|
||||
export PROJECT_NAME="My Project"
|
||||
export PROJECT_DESCRIPTION="What this project does"
|
||||
export TASK_PREFIX="MP"
|
||||
envsubst < ~/.config/mosaic/templates/agent/AGENTS.md.template > AGENTS.md
|
||||
envsubst < ~/.config/mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 0: Enforce Sequential-Thinking MCP (Hard Requirement)
|
||||
|
||||
`sequential-thinking` MCP must be installed and configured before project bootstrapping.
|
||||
|
||||
```bash
|
||||
# Auto-configure sequential-thinking MCP for installed runtimes
|
||||
~/.config/mosaic/bin/mosaic-ensure-sequential-thinking
|
||||
|
||||
# Verification-only check
|
||||
~/.config/mosaic/bin/mosaic-ensure-sequential-thinking --check
|
||||
```
|
||||
|
||||
If this step fails, STOP and remediate Mosaic runtime configuration before continuing.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Detect Project Type
|
||||
|
||||
Check what files exist in the project root to determine the type:
|
||||
|
||||
| File Present | Project Type | Template |
|
||||
| ------------------------------------------------------- | ------------------------- | ------------------------- |
|
||||
| `package.json` + `pnpm-workspace.yaml` + NestJS+Next.js | NestJS + Next.js Monorepo | `projects/nestjs-nextjs/` |
|
||||
| `pyproject.toml` + `manage.py` | Django | `projects/django/` |
|
||||
| `pyproject.toml` (no Django) | Python (generic) | Generic template |
|
||||
| `package.json` (no monorepo) | Node.js (generic) | Generic template |
|
||||
| Other | Generic | Generic template |
|
||||
|
||||
```bash
|
||||
# Auto-detect project type
|
||||
detect_project_type() {
|
||||
if [[ -f "pnpm-workspace.yaml" ]] && [[ -f "turbo.json" ]]; then
|
||||
# Check for NestJS + Next.js
|
||||
if grep -q "nestjs" package.json 2>/dev/null && grep -q "next" package.json 2>/dev/null; then
|
||||
echo "nestjs-nextjs"
|
||||
return
|
||||
fi
|
||||
fi
|
||||
if [[ -f "manage.py" ]] && [[ -f "pyproject.toml" ]]; then
|
||||
echo "django"
|
||||
return
|
||||
fi
|
||||
if [[ -f "pyproject.toml" ]]; then
|
||||
echo "python"
|
||||
return
|
||||
fi
|
||||
if [[ -f "package.json" ]]; then
|
||||
echo "nodejs"
|
||||
return
|
||||
fi
|
||||
echo "generic"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Create AGENTS.md (Primary Project Contract)
|
||||
|
||||
`AGENTS.md` is the primary project-level contract for all agent runtimes.
|
||||
It defines project-specific requirements, quality gates, patterns, and testing expectations.
|
||||
|
||||
### Using a Tech-Stack Template
|
||||
|
||||
```bash
|
||||
# Set variables
|
||||
export PROJECT_NAME="My Project"
|
||||
export PROJECT_DESCRIPTION="Multi-tenant SaaS platform"
|
||||
export PROJECT_DIR="my-project"
|
||||
export REPO_URL="https://git.mosaicstack.dev/owner/repo"
|
||||
export TASK_PREFIX="MP"
|
||||
|
||||
# Use tech-stack-specific template if available
|
||||
TYPE=$(detect_project_type)
|
||||
TEMPLATE_DIR="$HOME/.config/mosaic/templates/agent/projects/$TYPE"
|
||||
|
||||
if [[ -d "$TEMPLATE_DIR" ]]; then
|
||||
envsubst < "$TEMPLATE_DIR/AGENTS.md.template" > AGENTS.md
|
||||
else
|
||||
envsubst < "$HOME/.config/mosaic/templates/agent/AGENTS.md.template" > AGENTS.md
|
||||
fi
|
||||
```
|
||||
|
||||
### Using the Generic Template
|
||||
|
||||
```bash
|
||||
# Set all required variables
|
||||
export PROJECT_NAME="My Project"
|
||||
export PROJECT_DESCRIPTION="What this project does"
|
||||
export REPO_URL="https://git.mosaicstack.dev/owner/repo"
|
||||
export PROJECT_DIR="my-project"
|
||||
export SOURCE_DIR="src"
|
||||
export CONFIG_FILES="pyproject.toml / package.json"
|
||||
export FRONTEND_STACK="N/A"
|
||||
export BACKEND_STACK="Python / FastAPI"
|
||||
export DATABASE_STACK="PostgreSQL"
|
||||
export TESTING_STACK="pytest"
|
||||
export DEPLOYMENT_STACK="Docker"
|
||||
export BUILD_COMMAND="pip install -e ."
|
||||
export TEST_COMMAND="pytest tests/"
|
||||
export LINT_COMMAND="ruff check ."
|
||||
export TYPECHECK_COMMAND="mypy ."
|
||||
export QUALITY_GATES="ruff check . && mypy . && pytest tests/"
|
||||
|
||||
envsubst < ~/.config/mosaic/templates/agent/AGENTS.md.template > AGENTS.md
|
||||
```
|
||||
|
||||
### Required Sections
|
||||
|
||||
Every AGENTS.md should contain:
|
||||
|
||||
1. **Project description** — One-line summary
|
||||
2. **Quality gates** — Commands that must pass
|
||||
3. **Codebase patterns** — Reusable implementation rules
|
||||
4. **Common gotchas** — Non-obvious constraints
|
||||
5. **Testing approaches** — Project-specific test strategy
|
||||
6. **Testing policy** — Situational-first validation and risk-based TDD
|
||||
7. **Orchestrator integration** — Task prefix, worker checklist
|
||||
8. **Documentation contract** — Required documentation gates and update expectations
|
||||
9. **PRD requirement** — `docs/PRD.md` or `docs/PRD.json` required before coding
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Create Runtime Context File (Runtime-Specific)
|
||||
|
||||
Runtime context files are runtime adapters. They are not the primary project contract.
|
||||
Use `CLAUDE.md` for Claude runtime compatibility. Use other runtime adapters as required by your environment.
|
||||
|
||||
Claude runtime mandate (HARD RULE):
|
||||
|
||||
- `CLAUDE.md` MUST explicitly instruct Claude agents to read and use `AGENTS.md`.
|
||||
- `CLAUDE.md` MUST treat `AGENTS.md` as the authoritative project-level contract.
|
||||
- If `AGENTS.md` and runtime wording conflict, `AGENTS.md` project rules win.
|
||||
|
||||
```bash
|
||||
TYPE=$(detect_project_type)
|
||||
TEMPLATE_DIR="$HOME/.config/mosaic/templates/agent/projects/$TYPE"
|
||||
|
||||
if [[ -d "$TEMPLATE_DIR" ]]; then
|
||||
envsubst < "$TEMPLATE_DIR/CLAUDE.md.template" > CLAUDE.md
|
||||
else
|
||||
envsubst < "$HOME/.config/mosaic/templates/agent/CLAUDE.md.template" > CLAUDE.md
|
||||
fi
|
||||
```
|
||||
|
||||
### Required Runtime Sections
|
||||
|
||||
Every runtime context file should contain:
|
||||
|
||||
1. **AGENTS handoff rule** — Runtime MUST direct agents to read/use `AGENTS.md`
|
||||
2. **Conditional documentation loading** — Required guide loading map
|
||||
3. **Technology stack** — Runtime-facing architecture summary
|
||||
4. **Repository structure** — Important paths
|
||||
5. **Development workflow** — Build/test/lint/typecheck commands
|
||||
6. **Issue tracking** — Issue and commit conventions
|
||||
7. **Code review** — Required review process
|
||||
8. **Runtime notes** — Runtime-specific behavior references
|
||||
9. **Branch and merge policy** — Trunk workflow (`branch -> main` via PR, squash-only)
|
||||
10. **Autonomy and escalation policy** — Agent owns coding/review/PR/release/deploy lifecycle
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Create Directory Structure
|
||||
|
||||
```bash
|
||||
# Create standard directories
|
||||
mkdir -p docs/scratchpads
|
||||
mkdir -p docs/templates
|
||||
mkdir -p docs/reports/qa-automation/pending
|
||||
mkdir -p docs/reports/qa-automation/in-progress
|
||||
mkdir -p docs/reports/qa-automation/done
|
||||
mkdir -p docs/reports/qa-automation/escalated
|
||||
mkdir -p docs/reports/deferred
|
||||
mkdir -p docs/tasks
|
||||
mkdir -p docs/releases
|
||||
mkdir -p docs/USER-GUIDE docs/ADMIN-GUIDE docs/DEVELOPER-GUIDE docs/API
|
||||
|
||||
# Documentation baseline files
|
||||
touch docs/USER-GUIDE/README.md
|
||||
touch docs/ADMIN-GUIDE/README.md
|
||||
touch docs/DEVELOPER-GUIDE/README.md
|
||||
touch docs/API/OPENAPI.yaml
|
||||
touch docs/API/ENDPOINTS.md
|
||||
touch docs/SITEMAP.md
|
||||
|
||||
# PRD baseline file (requirements source before coding)
|
||||
cp ~/.config/mosaic/templates/docs/PRD.md.template docs/PRD.md
|
||||
|
||||
# TASKS baseline file (canonical tracking)
|
||||
cp ~/.config/mosaic/templates/docs/TASKS.md.template docs/TASKS.md
|
||||
|
||||
# Deployment baseline file (target/platform/runbook)
|
||||
touch docs/DEPLOYMENT.md
|
||||
```
|
||||
|
||||
Documentation root hygiene (HARD RULE):
|
||||
|
||||
- Keep `docs/` root clean.
|
||||
- Store reports in `docs/reports/`, archived task artifacts in `docs/tasks/`, releases in `docs/releases/`, and scratchpads in `docs/scratchpads/`.
|
||||
- Do not place ad-hoc report files directly under `docs/`.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Initialize Repository Labels & Milestones
|
||||
|
||||
```bash
|
||||
# Use the init script
|
||||
~/.config/mosaic/tools/bootstrap/init-repo-labels.sh
|
||||
|
||||
# Or manually create standard labels
|
||||
~/.config/mosaic/tools/git/issue-create.sh # (labels are created on first use)
|
||||
```
|
||||
|
||||
### Standard Labels
|
||||
|
||||
| Label | Color | Purpose |
|
||||
| --------------- | --------- | -------------------------------------- |
|
||||
| `epic` | `#3E4B9E` | Large feature spanning multiple issues |
|
||||
| `feature` | `#0E8A16` | New functionality |
|
||||
| `bug` | `#D73A4A` | Defect fix |
|
||||
| `task` | `#0075CA` | General work item |
|
||||
| `documentation` | `#0075CA` | Documentation updates |
|
||||
| `security` | `#B60205` | Security-related |
|
||||
| `breaking` | `#D93F0B` | Breaking change |
|
||||
|
||||
### Initial Milestone (Hard Rule)
|
||||
|
||||
Create the first pre-MVP milestone at `0.0.1`.
|
||||
Reserve `0.1.0` for the MVP release milestone.
|
||||
|
||||
```bash
|
||||
~/.config/mosaic/tools/git/milestone-create.sh -t "0.0.1" -d "Pre-MVP - Foundation Sprint"
|
||||
|
||||
# Create when MVP scope is complete and release-ready:
|
||||
~/.config/mosaic/tools/git/milestone-create.sh -t "0.1.0" -d "MVP - Minimum Viable Product"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5b: Configure Main Branch Protection (Hard Rule)
|
||||
|
||||
Apply equivalent settings in Gitea, GitHub, or GitLab:
|
||||
|
||||
1. Protect `main` from direct pushes.
|
||||
2. Require pull requests to merge into `main`.
|
||||
3. Require required CI/status checks to pass before merge.
|
||||
4. Require code review approval before merge.
|
||||
5. Allow **squash merge only** for PRs into `main` (disable merge commits and rebase merges for `main`).
|
||||
|
||||
This enforces one merge strategy across human and agent workflows.
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Set Up CI/CD Review Pipeline
|
||||
|
||||
### Woodpecker CI
|
||||
|
||||
```bash
|
||||
# Copy Codex review pipeline
|
||||
mkdir -p .woodpecker/schemas
|
||||
cp ~/.config/mosaic/tools/codex/woodpecker/codex-review.yml .woodpecker/
|
||||
cp ~/.config/mosaic/tools/codex/schemas/*.json .woodpecker/schemas/
|
||||
|
||||
# Add codex_api_key secret to Woodpecker CI dashboard
|
||||
```
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
For GitHub repos, use the official Codex GitHub Action instead:
|
||||
|
||||
```yaml
|
||||
# .github/workflows/codex-review.yml
|
||||
uses: openai/codex-action@v1
|
||||
```
|
||||
|
||||
### Python Package Publishing (Gitea PyPI)
|
||||
|
||||
If the project publishes Python packages, use Gitea's PyPI registry.
|
||||
|
||||
```bash
|
||||
# Build and publish
|
||||
python -m pip install --upgrade build twine
|
||||
python -m build
|
||||
python -m twine upload \
|
||||
--repository-url "https://GITEA_HOST/api/packages/ORG/pypi" \
|
||||
--username "$GITEA_USERNAME" \
|
||||
--password "$GITEA_TOKEN" \
|
||||
dist/*
|
||||
```
|
||||
|
||||
Use the same `gitea_username` and `gitea_token` CI secrets used for container and npm publishing.
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Verify Bootstrap
|
||||
|
||||
After bootstrapping, verify everything works:
|
||||
|
||||
```bash
|
||||
# Check files exist
|
||||
ls AGENTS.md docs/scratchpads/
|
||||
ls docs/reports/qa-automation/pending docs/reports/deferred docs/tasks docs/releases
|
||||
ls docs/USER-GUIDE/README.md docs/ADMIN-GUIDE/README.md docs/DEVELOPER-GUIDE/README.md
|
||||
ls docs/API/OPENAPI.yaml docs/API/ENDPOINTS.md docs/SITEMAP.md
|
||||
ls docs/PRD.md
|
||||
ls docs/TASKS.md
|
||||
|
||||
# Verify AGENTS.md has required sections
|
||||
grep -c "Quality Gates" AGENTS.md
|
||||
grep -c "Orchestrator Integration" AGENTS.md
|
||||
grep -c "Testing Approaches" AGENTS.md
|
||||
grep -c "Testing Policy" AGENTS.md
|
||||
grep -c "Documentation Contract" AGENTS.md
|
||||
grep -c "PRD Requirement" AGENTS.md
|
||||
|
||||
# Verify runtime context file has required sections
|
||||
if [[ -f CLAUDE.md ]]; then
|
||||
grep -c "AGENTS.md" CLAUDE.md
|
||||
grep -c "Conditional Documentation Loading" CLAUDE.md
|
||||
grep -c "Technology Stack" CLAUDE.md
|
||||
grep -c "Code Review" CLAUDE.md
|
||||
elif [[ -f RUNTIME.md ]]; then
|
||||
grep -c "Conditional Documentation Loading" RUNTIME.md
|
||||
grep -c "Technology Stack" RUNTIME.md
|
||||
grep -c "Code Review" RUNTIME.md
|
||||
else
|
||||
echo "Missing runtime context file (CLAUDE.md or RUNTIME.md)" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Run quality gates from AGENTS.md
|
||||
# (execute the command block under "Quality Gates")
|
||||
|
||||
# Test Codex review (if configured)
|
||||
~/.config/mosaic/tools/codex/codex-code-review.sh --help
|
||||
|
||||
# Verify sequential-thinking MCP remains configured
|
||||
~/.config/mosaic/bin/mosaic-ensure-sequential-thinking --check
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Available Templates
|
||||
|
||||
### Generic Templates
|
||||
|
||||
| Template | Path | Purpose |
|
||||
| ---------------------------- | ----------------------------------- | ------------------------------------------ |
|
||||
| `AGENTS.md.template` | `~/.config/mosaic/templates/agent/` | Primary project agent contract |
|
||||
| `CLAUDE.md.template` | `~/.config/mosaic/templates/agent/` | Runtime compatibility context (Claude) |
|
||||
| `DOCUMENTATION-CHECKLIST.md` | `~/.config/mosaic/templates/docs/` | Documentation completion gate |
|
||||
| `PRD.md.template` | `~/.config/mosaic/templates/docs/` | Requirements source template |
|
||||
| `TASKS.md.template` | `~/.config/mosaic/templates/docs/` | Canonical task and issue tracking template |
|
||||
|
||||
### Tech-Stack Templates
|
||||
|
||||
| Stack | Path | Includes |
|
||||
| ---------------- | ---------------------------------------------------------- | ------------------------------------ |
|
||||
| NestJS + Next.js | `~/.config/mosaic/templates/agent/projects/nestjs-nextjs/` | AGENTS.md + runtime context template |
|
||||
| Django | `~/.config/mosaic/templates/agent/projects/django/` | AGENTS.md + runtime context template |
|
||||
|
||||
### Orchestrator Templates
|
||||
|
||||
| Template | Path | Purpose |
|
||||
| -------------------------------------- | ------------------------------------------------- | ----------------------- |
|
||||
| `tasks.md.template` | `~/src/jarvis-brain/docs/templates/orchestrator/` | Task tracking |
|
||||
| `orchestrator-learnings.json.template` | `~/src/jarvis-brain/docs/templates/orchestrator/` | Variance tracking |
|
||||
| `phase-issue-body.md.template` | `~/src/jarvis-brain/docs/templates/orchestrator/` | Git provider issue body |
|
||||
| `scratchpad.md.template` | `~/src/jarvis-brain/docs/templates/` | Per-task working doc |
|
||||
|
||||
### Variables Reference
|
||||
|
||||
| Variable | Description | Example |
|
||||
| ------------------------ | --------------------------- | ------------------------------------------ |
|
||||
| `${PROJECT_NAME}` | Human-readable project name | "Mosaic Stack" |
|
||||
| `${PROJECT_DESCRIPTION}` | One-line description | "Multi-tenant platform" |
|
||||
| `${PROJECT_DIR}` | Directory name | "mosaic-stack" |
|
||||
| `${PROJECT_SLUG}` | Python package slug | "mosaic_stack" |
|
||||
| `${REPO_URL}` | Git remote URL | "https://git.mosaicstack.dev/mosaic/stack" |
|
||||
| `${TASK_PREFIX}` | Orchestrator task prefix | "MS" |
|
||||
| `${SOURCE_DIR}` | Source code directory | "src" or "apps" |
|
||||
| `${QUALITY_GATES}` | Quality gate commands | "pnpm typecheck && pnpm lint && pnpm test" |
|
||||
| `${BUILD_COMMAND}` | Build command | "pnpm build" |
|
||||
| `${TEST_COMMAND}` | Test command | "pnpm test" |
|
||||
| `${LINT_COMMAND}` | Lint command | "pnpm lint" |
|
||||
| `${TYPECHECK_COMMAND}` | Type check command | "pnpm typecheck" |
|
||||
| `${FRONTEND_STACK}` | Frontend technologies | "Next.js + React" |
|
||||
| `${BACKEND_STACK}` | Backend technologies | "NestJS + Prisma" |
|
||||
| `${DATABASE_STACK}` | Database technologies | "PostgreSQL" |
|
||||
| `${TESTING_STACK}` | Testing technologies | "Vitest + Playwright" |
|
||||
| `${DEPLOYMENT_STACK}` | Deployment technologies | "Docker" |
|
||||
| `${CONFIG_FILES}` | Key config files | "package.json, tsconfig.json" |
|
||||
|
||||
---
|
||||
|
||||
## Bootstrap Scripts
|
||||
|
||||
### init-project.sh
|
||||
|
||||
Full project bootstrap with interactive and flag-based modes:
|
||||
|
||||
```bash
|
||||
~/.config/mosaic/tools/bootstrap/init-project.sh \
|
||||
--name "My Project" \
|
||||
--type "nestjs-nextjs" \
|
||||
--repo "https://git.mosaicstack.dev/owner/repo" \
|
||||
--prefix "MP" \
|
||||
--description "Multi-tenant platform"
|
||||
```
|
||||
|
||||
### init-repo-labels.sh
|
||||
|
||||
Initialize standard labels and the first pre-MVP milestone:
|
||||
|
||||
```bash
|
||||
~/.config/mosaic/tools/bootstrap/init-repo-labels.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
|
||||
After bootstrapping, verify:
|
||||
|
||||
- [ ] `AGENTS.md` exists and is the primary project contract
|
||||
- [ ] Runtime context file exists (`CLAUDE.md` or `RUNTIME.md`)
|
||||
- [ ] `docs/scratchpads/` directory exists
|
||||
- [ ] `docs/reports/qa-automation/pending` directory exists
|
||||
- [ ] `docs/reports/deferred/` directory exists
|
||||
- [ ] `docs/tasks/` directory exists
|
||||
- [ ] `docs/releases/` directory exists
|
||||
- [ ] `docs/USER-GUIDE/README.md` exists
|
||||
- [ ] `docs/ADMIN-GUIDE/README.md` exists
|
||||
- [ ] `docs/DEVELOPER-GUIDE/README.md` exists
|
||||
- [ ] `docs/API/OPENAPI.yaml` exists
|
||||
- [ ] `docs/API/ENDPOINTS.md` exists
|
||||
- [ ] `docs/SITEMAP.md` exists
|
||||
- [ ] `docs/PRD.md` or `docs/PRD.json` exists
|
||||
- [ ] `docs/TASKS.md` exists and is ready for active tracking
|
||||
- [ ] `docs/DEPLOYMENT.md` exists with target platform and rollback notes
|
||||
- [ ] `sequential-thinking` MCP is configured and verification check passes
|
||||
- [ ] Git labels created (epic, feature, bug, task, etc.)
|
||||
- [ ] Initial pre-MVP milestone created (0.0.1)
|
||||
- [ ] MVP milestone reserved for release (0.1.0)
|
||||
- [ ] `main` is protected from direct pushes
|
||||
- [ ] PRs into `main` are required
|
||||
- [ ] Merge method for `main` is squash-only
|
||||
- [ ] Quality gates run successfully
|
||||
- [ ] `.env.example` exists (if project uses env vars)
|
||||
- [ ] CI/CD pipeline configured (if using Woodpecker/GitHub Actions)
|
||||
- [ ] Python publish path configured in CI (if project ships Python packages)
|
||||
- [ ] Codex review scripts accessible (`~/.config/mosaic/tools/codex/`)
|
||||
1082
guides/CI-CD-PIPELINES.md
Normal file
1082
guides/CI-CD-PIPELINES.md
Normal file
File diff suppressed because it is too large
Load Diff
154
guides/CODE-REVIEW.md
Executable file
154
guides/CODE-REVIEW.md
Executable file
@@ -0,0 +1,154 @@
|
||||
# Code Review Guide
|
||||
|
||||
## Hard Requirement
|
||||
|
||||
If an agent modifies source code, code review is REQUIRED before completion.
|
||||
Do not mark code-change tasks done until review is completed and blockers are resolved or explicitly tracked.
|
||||
If code/config/API contract/auth behavior changed and required docs are missing, this is a BLOCKER.
|
||||
If tests pass but acceptance criteria are not verified by situational evidence, this is a BLOCKER.
|
||||
If implementation diverges from `docs/PRD.md` or `docs/PRD.json` without PRD updates, this is a BLOCKER.
|
||||
|
||||
Merge strategy enforcement (HARD RULE):
|
||||
|
||||
- PR target for delivery is `main`.
|
||||
- Direct pushes to `main` are prohibited.
|
||||
- Merge to `main` MUST be squash-only.
|
||||
- Use `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash` (or PowerShell equivalent).
|
||||
|
||||
## Review Checklist
|
||||
|
||||
### 1. Correctness
|
||||
|
||||
- [ ] Code does what the issue/PR description says
|
||||
- [ ] Code aligns with active PRD requirements
|
||||
- [ ] Acceptance criteria are mapped to concrete verification evidence
|
||||
- [ ] Edge cases are handled
|
||||
- [ ] Error conditions are managed properly
|
||||
- [ ] No obvious bugs or logic errors
|
||||
|
||||
### 2. Security
|
||||
|
||||
- [ ] No hardcoded secrets or credentials
|
||||
- [ ] Input validation at boundaries
|
||||
- [ ] SQL injection prevention (parameterized queries)
|
||||
- [ ] XSS prevention (output encoding)
|
||||
- [ ] Authentication/authorization checks present
|
||||
- [ ] Sensitive data not logged
|
||||
- [ ] Secrets follow Vault structure (see `docs/vault-secrets-structure.md`)
|
||||
|
||||
### 2a. OWASP Coverage (Required)
|
||||
|
||||
- [ ] OWASP Top 10 categories were reviewed for change impact
|
||||
- [ ] Access control checks verified on protected actions
|
||||
- [ ] Cryptographic handling validated (keys, hashing, TLS assumptions)
|
||||
- [ ] Injection risks reviewed for all untrusted inputs
|
||||
- [ ] Security misconfiguration risks reviewed (headers, CORS, defaults)
|
||||
- [ ] Dependency/component risk reviewed (known vulnerable components)
|
||||
- [ ] Authentication/session flows reviewed for failure paths
|
||||
- [ ] Logging/monitoring preserves detection without leaking sensitive data
|
||||
|
||||
### 3. Testing
|
||||
|
||||
- [ ] Tests exist for new functionality
|
||||
- [ ] Tests cover happy path AND error cases
|
||||
- [ ] Situational tests cover all impacted change surfaces (primary gate)
|
||||
- [ ] Tests validate required behavior/outcomes, not only internal implementation details
|
||||
- [ ] TDD was applied when required by `~/.config/mosaic/guides/QA-TESTING.md`
|
||||
- [ ] Coverage meets 85% minimum
|
||||
- [ ] Tests are readable and maintainable
|
||||
- [ ] No flaky tests introduced
|
||||
|
||||
### 4. Code Quality
|
||||
|
||||
- [ ] Follows Google Style Guide for the language
|
||||
- [ ] Functions are focused and reasonably sized
|
||||
- [ ] No unnecessary complexity
|
||||
- [ ] DRY - no significant duplication
|
||||
- [ ] Clear naming for variables and functions
|
||||
- [ ] No dead code or commented-out code
|
||||
|
||||
### 4a. TypeScript Strict Typing (see `TYPESCRIPT.md`)
|
||||
|
||||
- [ ] **NO `any` types** — explicit types required everywhere
|
||||
- [ ] **NO lazy `unknown`** — only for error catches with immediate narrowing
|
||||
- [ ] **Explicit return types** on all exported/public functions
|
||||
- [ ] **Explicit parameter types** — never implicit any
|
||||
- [ ] **No type assertions** (`as Type`) — use type guards instead
|
||||
- [ ] **No non-null assertions** (`!`) — use proper null handling
|
||||
- [ ] **Interfaces for objects** — not inline types
|
||||
- [ ] **Discriminated unions** for variant types
|
||||
- [ ] **DTO files used at boundaries** — module/API contracts are in `*.dto.ts`, not inline payload types
|
||||
|
||||
### 5. Documentation
|
||||
|
||||
- [ ] Complex logic has explanatory comments
|
||||
- [ ] Required docs updated per `~/.config/mosaic/guides/DOCUMENTATION.md`
|
||||
- [ ] Public APIs are documented
|
||||
- [ ] Private/internal APIs are documented
|
||||
- [ ] API input/output schemas are documented
|
||||
- [ ] API permissions/auth requirements are documented
|
||||
- [ ] Site map updates are present when navigation changed
|
||||
- [ ] README updated if needed
|
||||
- [ ] Breaking changes noted
|
||||
|
||||
### 6. Performance
|
||||
|
||||
- [ ] No obvious N+1 queries
|
||||
- [ ] No blocking operations in hot paths
|
||||
- [ ] Resource cleanup (connections, file handles)
|
||||
- [ ] Reasonable memory usage
|
||||
|
||||
### 7. Dependencies
|
||||
|
||||
- [ ] No deprecated packages
|
||||
- [ ] No unnecessary new dependencies
|
||||
- [ ] Dependency versions pinned appropriately
|
||||
|
||||
## Review Process
|
||||
|
||||
Use `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md` whenever code/API/auth/infra changes are present.
|
||||
|
||||
### Getting Context
|
||||
|
||||
```bash
|
||||
# List the issue being addressed
|
||||
~/.config/mosaic/tools/git/issue-list.sh -i {issue-number}
|
||||
|
||||
# View the changes
|
||||
git diff main...HEAD
|
||||
```
|
||||
|
||||
### Providing Feedback
|
||||
|
||||
- Be specific: point to exact lines/files
|
||||
- Explain WHY something is problematic
|
||||
- Suggest alternatives when possible
|
||||
- Distinguish between blocking issues and suggestions
|
||||
- Be constructive, not critical of the person
|
||||
|
||||
### Feedback Categories
|
||||
|
||||
- **Blocker**: Must fix before merge (security, bugs, test failures)
|
||||
- **Should Fix**: Important but not blocking (code quality, minor issues)
|
||||
- **Suggestion**: Optional improvements (style preferences, nice-to-haves)
|
||||
- **Question**: Seeking clarification
|
||||
|
||||
### Review Comment Format
|
||||
|
||||
```
|
||||
[BLOCKER] Line 42: SQL injection vulnerability
|
||||
The user input is directly interpolated into the query.
|
||||
Use parameterized queries instead:
|
||||
`db.query("SELECT * FROM users WHERE id = ?", [userId])`
|
||||
|
||||
[SUGGESTION] Line 78: Consider extracting to helper
|
||||
This pattern appears in 3 places. A shared helper would reduce duplication.
|
||||
```
|
||||
|
||||
## After Review
|
||||
|
||||
1. Update issue with review status
|
||||
2. If changes requested, assign back to author
|
||||
3. If approved, note approval in issue comments
|
||||
4. For merges, ensure CI passes first
|
||||
5. Merge PR to `main` with squash strategy only
|
||||
132
guides/DOCUMENTATION.md
Normal file
132
guides/DOCUMENTATION.md
Normal file
@@ -0,0 +1,132 @@
|
||||
# Documentation Standard (MANDATORY)
|
||||
|
||||
This guide defines REQUIRED documentation behavior for all Mosaic projects.
|
||||
If code, API contracts, auth, or infrastructure changes, documentation updates are REQUIRED before completion.
|
||||
|
||||
## Hard Rules
|
||||
|
||||
1. Documentation is a delivery gate. Missing required documentation is a BLOCKER.
|
||||
2. `docs/PRD.md` or `docs/PRD.json` is REQUIRED as the project requirements source before coding begins.
|
||||
3. API documentation is OpenAPI-first. `docs/API/OPENAPI.yaml` (or `.json`) is the canonical API contract.
|
||||
4. Public and private/internal endpoints MUST be documented.
|
||||
5. API input and output schemas MUST be documented.
|
||||
6. API authentication and permissions MUST be documented per endpoint.
|
||||
7. A current site map MUST exist at `docs/SITEMAP.md`.
|
||||
8. Documentation updates MUST be committed in the same logical change set as the code/API change.
|
||||
9. Generated publishing output (Docusaurus/VitePress/MkDocs artifacts) is not canonical unless the project explicitly declares it canonical.
|
||||
10. `docs/` root MUST stay clean. Reports and working artifacts MUST be stored in dedicated subdirectories, not dumped at `docs/` root.
|
||||
|
||||
## Required Documentation Structure
|
||||
|
||||
```text
|
||||
docs/
|
||||
PRD.md (or PRD.json)
|
||||
TASKS.md (active orchestrator tracking, when orchestrator is used)
|
||||
SITEMAP.md
|
||||
USER-GUIDE/
|
||||
ADMIN-GUIDE/
|
||||
DEVELOPER-GUIDE/
|
||||
API/
|
||||
OPENAPI.yaml
|
||||
ENDPOINTS.md
|
||||
scratchpads/
|
||||
reports/
|
||||
tasks/
|
||||
releases/
|
||||
templates/ (optional)
|
||||
```
|
||||
|
||||
Minimum requirements:
|
||||
|
||||
- `docs/PRD.md` or `docs/PRD.json`: authoritative requirements source for implementation and testing.
|
||||
- `docs/USER-GUIDE/`: End-user workflows, feature behavior, common troubleshooting.
|
||||
- `docs/ADMIN-GUIDE/`: Configuration, deployment, operations, incident/recovery procedures.
|
||||
- `docs/DEVELOPER-GUIDE/`: Architecture, local setup, contribution/testing workflow, design constraints.
|
||||
- `docs/API/OPENAPI.yaml`: API SSOT for all HTTP endpoints.
|
||||
- `docs/API/ENDPOINTS.md`: Human-readable index for API endpoints, permissions, and change notes.
|
||||
- `docs/SITEMAP.md`: Navigation index for all user/admin/developer/API documentation pages.
|
||||
- `docs/reports/`: Review outputs, QA automation reports, deferrals, and audit artifacts.
|
||||
- `docs/tasks/`: Archived task snapshots and orchestrator learnings.
|
||||
- `docs/releases/`: Release notes and release-specific documentation.
|
||||
- `docs/scratchpads/`: Active task-level working notes.
|
||||
|
||||
## Root Hygiene Rule (MANDATORY)
|
||||
|
||||
Allowed root documentation files are intentionally limited:
|
||||
|
||||
1. `docs/PRD.md` or `docs/PRD.json`
|
||||
2. `docs/TASKS.md` (active milestone only, when task orchestration is in use)
|
||||
3. `docs/SITEMAP.md`
|
||||
4. `docs/README.md` (optional index)
|
||||
|
||||
All other docs MUST be placed in scoped folders (`docs/reports/`, `docs/tasks/`, `docs/releases/`, `docs/scratchpads/`, `docs/API/`, guide books).
|
||||
|
||||
## Artifact Placement Rules
|
||||
|
||||
| Artifact Type | REQUIRED Location |
|
||||
| ------------------------------------------ | ---------------------------------------- |
|
||||
| Code review reports, QA reports, audits | `docs/reports/<category>/` |
|
||||
| Deferred error lists / unresolved findings | `docs/reports/deferred/` |
|
||||
| Archived milestone task snapshots | `docs/tasks/` |
|
||||
| Orchestrator learnings JSON | `docs/tasks/orchestrator-learnings.json` |
|
||||
| Release notes | `docs/releases/` |
|
||||
| Active scratchpads | `docs/scratchpads/` |
|
||||
|
||||
## API Documentation Contract (OpenAPI-First)
|
||||
|
||||
For every API endpoint, documentation MUST include:
|
||||
|
||||
1. visibility: `public` or `private/internal`
|
||||
2. method and path
|
||||
3. endpoint purpose
|
||||
4. request/input schema
|
||||
5. response/output schema(s)
|
||||
6. auth method and required permission/role/scope
|
||||
7. error status codes and behavior
|
||||
|
||||
If OpenAPI cannot fully express an internal constraint, document it in `docs/API/ENDPOINTS.md`.
|
||||
|
||||
## Book/Chapter/Page Structure
|
||||
|
||||
Use this structure for every guide:
|
||||
|
||||
1. Book: one root guide folder (`USER-GUIDE`, `ADMIN-GUIDE`, `DEVELOPER-GUIDE`)
|
||||
2. Chapter: one subdirectory per topic area
|
||||
3. Page: one focused markdown file per concern
|
||||
|
||||
Required index files:
|
||||
|
||||
1. `docs/USER-GUIDE/README.md`
|
||||
2. `docs/ADMIN-GUIDE/README.md`
|
||||
3. `docs/DEVELOPER-GUIDE/README.md`
|
||||
|
||||
Each index file MUST link to all chapters and pages in that book.
|
||||
|
||||
## Situational Documentation Matrix
|
||||
|
||||
| Change Surface | REQUIRED Documentation Updates |
|
||||
| ---------------------------------------------- | ----------------------------------------------------------- |
|
||||
| New feature or behavior change | User guide + developer guide + sitemap |
|
||||
| API endpoint added/changed/removed | OpenAPI + API endpoint index + sitemap |
|
||||
| Auth/RBAC/permission change | API auth/permission docs + admin guide + developer guide |
|
||||
| Database schema/migration change | Developer guide + admin operational notes if runbook impact |
|
||||
| CI/CD or deployment change | Admin guide + developer guide |
|
||||
| Incident, recovery, or security control change | Admin guide runbook + security notes + sitemap |
|
||||
|
||||
## Publishing Target Rule (MANDATORY)
|
||||
|
||||
If the user does not specify documentation publishing target, the agent MUST ask:
|
||||
|
||||
1. Publish in-app (embedded docs)
|
||||
2. Publish on external docs platform (for example: Docusaurus, VitePress, MkDocs)
|
||||
|
||||
Default behavior before publishing decision:
|
||||
|
||||
- Keep canonical docs in-repo under `docs/`.
|
||||
- Do not assume external publishing platform.
|
||||
|
||||
## Completion Gate
|
||||
|
||||
You MUST NOT declare completion until all required documentation updates are done.
|
||||
|
||||
Use `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md` as the final gate.
|
||||
210
guides/E2E-DELIVERY.md
Normal file
210
guides/E2E-DELIVERY.md
Normal file
@@ -0,0 +1,210 @@
|
||||
# E2E Delivery Procedure (MANDATORY)
|
||||
|
||||
This guide is REQUIRED for all agent sessions.
|
||||
|
||||
## 0. Mode Handshake (Before Any Action)
|
||||
|
||||
First response MUST declare mode before tool calls or implementation steps:
|
||||
|
||||
1. Orchestration mission: `Now initiating Orchestrator mode...`
|
||||
2. Implementation mission: `Now initiating Delivery mode...`
|
||||
3. Review-only mission: `Now initiating Review mode...`
|
||||
|
||||
## 1. PRD Gate (Before Coding)
|
||||
|
||||
1. Ensure `docs/PRD.md` or `docs/PRD.json` exists before coding.
|
||||
2. Load `~/.config/mosaic/guides/PRD.md`.
|
||||
3. Prepare/update PRD from user input and available project context.
|
||||
4. If requirements are missing:
|
||||
- proceed with best-guess assumptions by default,
|
||||
- mark each assumption with `ASSUMPTION:` and rationale,
|
||||
- escalate only when uncertainty is high-impact and cannot be bounded safely.
|
||||
5. Treat PRD as the requirement source for implementation, testing, and review.
|
||||
|
||||
## 1a. Tracking Gate (Before Coding)
|
||||
|
||||
1. For non-trivial work, `docs/TASKS.md` MUST exist before coding.
|
||||
2. If `docs/TASKS.md` is missing, create it from `~/.config/mosaic/templates/docs/TASKS.md.template`.
|
||||
3. Detect provider first via `~/.config/mosaic/tools/git/detect-platform.sh`.
|
||||
4. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
|
||||
5. If external git provider is available (Gitea/GitHub/GitLab), create or update issue(s) before coding.
|
||||
6. Record provider issue reference(s) in `docs/TASKS.md` (example: `#123`).
|
||||
7. If no external provider is available, use internal task refs in `docs/TASKS.md` (example: `TASKS:T1`).
|
||||
8. Scratchpad MUST reference both task ID and issue/internal ref.
|
||||
|
||||
## 2. Intake and Scope
|
||||
|
||||
> **COMPLEXITY TRAP WARNING:** Intake applies to ALL tasks regardless of perceived complexity. "Simple" tasks (commit, push, deploy) have caused the most severe framework violations because agents skip intake when they pattern-match a task as mechanical. The procedure is unconditional.
|
||||
|
||||
1. Define scope, constraints, and acceptance criteria.
|
||||
2. Identify affected surfaces (API, DB, UI, infra, auth, CI/CD, docs).
|
||||
3. **Deployment surface check (MANDATORY if task involves deploy, images, or containers):** Before ANY build or deploy action, check for CI/CD pipeline config (`.woodpecker/`, `.woodpecker.yml`, `.github/workflows/`). If pipelines exist, CI is the canonical build path — manual `docker build`/`docker push` is forbidden. Load `~/.config/mosaic/guides/CI-CD-PIPELINES.md` immediately.
|
||||
4. Identify required guides and load them before implementation.
|
||||
5. For code/API/auth/infra changes, load `~/.config/mosaic/guides/DOCUMENTATION.md`.
|
||||
6. Determine budget constraints:
|
||||
- if the user provided a plan limit or token budget, treat it as a HARD cap,
|
||||
- if budget is unknown, derive a working budget from estimates and runtime limits, then continue autonomously.
|
||||
7. Record budget assumptions and caps in the scratchpad before implementation starts.
|
||||
8. Track estimated vs used tokens per logical unit and adapt strategy to remain inside budget.
|
||||
9. If projected usage exceeds budget, auto-reduce scope/parallelism first; escalate only if cap still cannot be met.
|
||||
|
||||
## 2a. Steered Autonomy (Lights-Out)
|
||||
|
||||
1. Agent owns delivery end-to-end: planning, coding, testing, review, PR/repo operations, release/tag, and deployment (when in scope).
|
||||
2. Human intervention is escalation-only; do not pause for routine approvals or handoffs.
|
||||
3. Continue execution until completion criteria are met or an escalation trigger is hit.
|
||||
|
||||
## 3. Scratchpad Requirement
|
||||
|
||||
1. Create a task-specific scratchpad before implementation.
|
||||
2. Record:
|
||||
- objective
|
||||
- plan
|
||||
- progress checkpoints
|
||||
- tests run
|
||||
- risks/blockers
|
||||
- final verification evidence
|
||||
|
||||
## 4. Embedded Execution Cycle (MANDATORY)
|
||||
|
||||
For implementation work, you MUST run this cycle in order:
|
||||
|
||||
1. `plan` - map PRD requirements to concrete implementation steps.
|
||||
2. `code` - implement one logical unit.
|
||||
3. `test` - run required baseline and situational checks for that unit.
|
||||
4. `review` - perform independent code review on the current delta.
|
||||
5. `remediate` - fix all findings and any test failures.
|
||||
6. `review` - re-review remediated changes until blockers are cleared.
|
||||
7. `commit` - commit only when the logical unit passes tests and review.
|
||||
8. `pre-push queue guard` - before pushing, wait for running/queued project pipelines to clear: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push`.
|
||||
9. `push` - push immediately after queue guard passes.
|
||||
10. `PR integration` - if external git provider is available, create/update PR to `main` and merge with required strategy via Mosaic wrappers.
|
||||
11. `pre-merge queue guard` - before merging PR, wait for running/queued project pipelines to clear: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge`.
|
||||
12. `CI/pipeline verification` - wait for terminal CI status and require green before completion (`~/.config/mosaic/tools/git/pr-ci-wait.sh` for PR-based workflow).
|
||||
13. `issue closure` - close linked external issue (or close internal `docs/TASKS.md` task ref when provider is unavailable).
|
||||
14. `greenfield situational test` - validate required user flows in a clean environment/startup path (post-merge for trunk workflow changes).
|
||||
15. `deploy + post-deploy validation` - when deployment is in scope, deploy to configured target and run post-deploy health/smoke checks.
|
||||
16. `repeat` - continue until all acceptance criteria are complete.
|
||||
|
||||
### Post-PR Hard Gate (Execute Sequentially, No Exceptions)
|
||||
|
||||
1. `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`
|
||||
2. `~/.config/mosaic/tools/git/pr-merge.sh -n <PR_NUMBER> -m squash`
|
||||
3. `~/.config/mosaic/tools/git/pr-ci-wait.sh -n <PR_NUMBER>`
|
||||
4. `~/.config/mosaic/tools/git/issue-close.sh -i <ISSUE_NUMBER>` (or close internal `docs/TASKS.md` ref when no provider exists)
|
||||
5. If any step fails: set status `blocked`, report the exact failed wrapper command, and stop.
|
||||
6. Do not ask the human to perform routine merge/close operations.
|
||||
7. Do not claim completion before step 4 succeeds.
|
||||
|
||||
### Forbidden Anti-Patterns
|
||||
|
||||
**PR/Merge:**
|
||||
|
||||
1. Do NOT stop at "PR created" or "PR updated".
|
||||
2. Do NOT ask "should I merge?" for routine delivery PRs.
|
||||
3. Do NOT ask "should I close the issue?" after merge + green CI.
|
||||
|
||||
**Build/Deploy:** 4. Do NOT run `docker build` or `docker push` locally to deploy images when CI/CD pipelines exist in the repository. CI is the ONLY canonical build path. 5. Do NOT skip intake and surface identification because a task "seems simple." This is the #1 cause of framework violations. 6. Do NOT deploy without first verifying whether CI/CD pipelines exist (`.woodpecker/`, `.woodpecker.yml`, `.github/workflows/`). If they exist, use them. 7. If you are about to run `docker build` and have NOT loaded `ci-cd-pipelines.md`, STOP — you are violating the framework.
|
||||
|
||||
If any step fails, you MUST remediate and re-run from the relevant step before proceeding.
|
||||
If push-queue/merge-queue/PR merge/CI/issue closure fails, status is `blocked` (not complete) and you MUST report the exact failed wrapper command.
|
||||
|
||||
## 5. Testing Priority Model
|
||||
|
||||
Use this order of priority:
|
||||
|
||||
1. Situational tests are the PRIMARY gate and MUST prove changed behavior meets requirements.
|
||||
2. Baseline tests are REQUIRED safety checks and MUST run for all software changes.
|
||||
3. TDD is risk-based and REQUIRED only for specific high-risk change types.
|
||||
|
||||
## 6. Mandatory Test Baseline
|
||||
|
||||
For all software changes, you MUST run baseline checks applicable to the repo/toolchain:
|
||||
|
||||
1. lint (or equivalent static checks)
|
||||
2. type checks (if language/tooling supports it)
|
||||
3. unit tests for changed logic
|
||||
4. integration tests for changed boundaries
|
||||
|
||||
## 7. Situational Testing Matrix (PRIMARY GATE)
|
||||
|
||||
Run additional tests based on what changed:
|
||||
|
||||
| Change Surface | Required Situational Tests |
|
||||
| ---------------------------- | ----------------------------------------------------------------------------- |
|
||||
| Authentication/authorization | auth failure-path tests, permission boundary tests, token/session validation |
|
||||
| Database schema/migrations | migration up/down validation, rollback safety, data integrity checks |
|
||||
| API contract changes | backward compatibility checks, consumer-impact tests, contract tests |
|
||||
| Frontend/UI workflow changes | end-to-end flow tests, accessibility sanity checks, state transition checks |
|
||||
| CI/CD or deployment changes | pipeline execution validation, artifact integrity checks, rollback path check |
|
||||
| Security-sensitive logic | abuse-case tests, input validation fuzzing/sanitization checks |
|
||||
| Performance-critical path | baseline comparison, regression threshold checks |
|
||||
|
||||
## 8. Risk-Based TDD Requirement
|
||||
|
||||
TDD is REQUIRED for:
|
||||
|
||||
1. bug fixes (write a reproducer test first)
|
||||
2. security/auth/permission logic changes
|
||||
3. critical business logic and data-mutation rules
|
||||
|
||||
TDD is RECOMMENDED (not mandatory) for low-risk UI, copy, styling, and mechanical refactors.
|
||||
If TDD is skipped for a non-required case, record the rationale in the scratchpad.
|
||||
|
||||
## 9. Mandatory Code Review Gate
|
||||
|
||||
If you modify source code, you MUST run an independent code review before completion.
|
||||
|
||||
1. Use automated review tooling when available.
|
||||
2. If automated tooling is unavailable, run manual review using `~/.config/mosaic/guides/CODE-REVIEW.md`.
|
||||
3. Any blocker or critical finding MUST be fixed or tracked as an explicit remediation task before closure.
|
||||
|
||||
## 10. Mandatory Documentation Gate
|
||||
|
||||
For code/API/auth/infra changes, documentation updates are REQUIRED before completion.
|
||||
|
||||
1. Apply the standard in `~/.config/mosaic/guides/DOCUMENTATION.md`.
|
||||
2. Update required docs in the same logical change set as implementation.
|
||||
3. Complete `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md`.
|
||||
4. If publish platform is unspecified, ask the user to choose in-app or external platform before publishing.
|
||||
5. Missing required documentation is a BLOCKER.
|
||||
|
||||
## 11. Completion Gate (All Required)
|
||||
|
||||
You MUST satisfy all items before completion:
|
||||
|
||||
1. Acceptance criteria met.
|
||||
2. Baseline tests passed.
|
||||
3. Situational tests passed (primary gate), including required greenfield situational validation.
|
||||
4. PRD is current and implementation is aligned with PRD.
|
||||
5. Acceptance criteria mapped to verification evidence.
|
||||
6. Code review completed for source code changes.
|
||||
7. Required documentation updates completed and reviewed.
|
||||
8. Scratchpad updated with evidence.
|
||||
9. Known risks documented.
|
||||
10. No unresolved blocker hidden.
|
||||
11. If deployment is in scope, deployment target, release version, and post-deploy verification evidence are documented.
|
||||
12. `docs/TASKS.md` status and issue/internal references are updated to match delivered work.
|
||||
13. If source code changed and external provider is available: PR merged to `main` (squash), with merge evidence recorded.
|
||||
14. CI/pipeline status is terminal green for the merged PR/head commit.
|
||||
15. Linked external issue is closed (or internal task ref is closed when no provider exists).
|
||||
16. If any of items 13-15 fail due access/tooling, report `blocked` with exact failed wrapper command and do not claim completion.
|
||||
|
||||
## 12. Review and Reporting
|
||||
|
||||
Completion report MUST include:
|
||||
|
||||
1. what changed
|
||||
2. PRD alignment summary
|
||||
3. acceptance criteria to evidence mapping
|
||||
4. what was tested (baseline + situational)
|
||||
5. what was reviewed (code review scope)
|
||||
6. what documentation was updated
|
||||
7. command-level evidence summary
|
||||
8. residual risks
|
||||
9. deployment and post-deploy verification summary (if in scope)
|
||||
10. explicit pass/fail status
|
||||
11. tracking summary (`docs/TASKS.md` updates and issue/internal refs)
|
||||
12. PR lifecycle summary (PR number, merge commit, merge method)
|
||||
13. CI/pipeline summary (run/check URL, terminal status)
|
||||
14. issue closure summary (issue number/ref and close evidence)
|
||||
91
guides/FRONTEND.md
Normal file
91
guides/FRONTEND.md
Normal file
@@ -0,0 +1,91 @@
|
||||
# Frontend Development Guide
|
||||
|
||||
## Before Starting
|
||||
|
||||
1. Check assigned issue in git repo: `~/.config/mosaic/tools/git/issue-list.sh -a @me`
|
||||
2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
|
||||
3. Review existing components and patterns in the codebase
|
||||
|
||||
## Development Standards
|
||||
|
||||
### Framework Conventions
|
||||
|
||||
- Follow project's existing framework patterns (React, Vue, Svelte, etc.)
|
||||
- Use existing component library/design system if present
|
||||
- Maintain consistent file structure with existing code
|
||||
|
||||
### Styling
|
||||
|
||||
- Use project's established styling approach (CSS modules, Tailwind, styled-components, etc.)
|
||||
- Follow existing naming conventions for CSS classes
|
||||
- Ensure responsive design unless explicitly single-platform
|
||||
|
||||
### State Management
|
||||
|
||||
- Use project's existing state management solution
|
||||
- Keep component state local when possible
|
||||
- Document any new global state additions
|
||||
|
||||
### Accessibility
|
||||
|
||||
- Include proper ARIA labels
|
||||
- Ensure keyboard navigation works
|
||||
- Test with screen reader considerations
|
||||
- Maintain color contrast ratios (WCAG 2.1 AA minimum)
|
||||
|
||||
## Testing Requirements (TDD)
|
||||
|
||||
1. Write tests BEFORE implementation
|
||||
2. Minimum 85% coverage
|
||||
3. Test categories:
|
||||
- Unit tests for utility functions
|
||||
- Component tests for UI behavior
|
||||
- Integration tests for user flows
|
||||
|
||||
### Test Patterns
|
||||
|
||||
```javascript
|
||||
// Component test example structure
|
||||
describe('ComponentName', () => {
|
||||
it('renders without crashing', () => {});
|
||||
it('handles user interaction correctly', () => {});
|
||||
it('displays error states appropriately', () => {});
|
||||
it('is accessible', () => {});
|
||||
});
|
||||
```
|
||||
|
||||
## Code Style
|
||||
|
||||
- Follow Google JavaScript/TypeScript Style Guide
|
||||
- **TypeScript: Follow `~/.config/mosaic/guides/TYPESCRIPT.md` — MANDATORY**
|
||||
- Use ESLint/Prettier configuration from project
|
||||
- Prefer functional components over class components (React)
|
||||
- TypeScript strict mode is REQUIRED, not optional
|
||||
|
||||
### TypeScript Quick Rules (see TYPESCRIPT.md for full guide)
|
||||
|
||||
- **NO `any`** — define explicit types always
|
||||
- **NO lazy `unknown`** — only for error catches and external data with validation
|
||||
- **Explicit return types** on all exported functions
|
||||
- **Explicit parameter types** always
|
||||
- **Interface for props** — never inline object types
|
||||
- **Event handlers** — use proper React event types
|
||||
|
||||
## Commit Format
|
||||
|
||||
```
|
||||
feat(#123): Add user profile component
|
||||
|
||||
- Implement avatar display
|
||||
- Add edit mode toggle
|
||||
- Include form validation
|
||||
|
||||
Refs #123
|
||||
```
|
||||
|
||||
## Before Completing
|
||||
|
||||
1. Run full test suite
|
||||
2. Verify build succeeds
|
||||
3. Update scratchpad with completion notes
|
||||
4. Reference issue in commit: `Fixes #N` or `Refs #N`
|
||||
339
guides/INFRASTRUCTURE.md
Normal file
339
guides/INFRASTRUCTURE.md
Normal file
@@ -0,0 +1,339 @@
|
||||
# Infrastructure & DevOps Guide
|
||||
|
||||
## Before Starting
|
||||
|
||||
1. Check assigned issue: `~/.config/mosaic/tools/git/issue-list.sh -a @me`
|
||||
2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
|
||||
3. Review existing infrastructure configuration
|
||||
|
||||
## Vault Secrets Management
|
||||
|
||||
**CRITICAL**: Follow canonical Vault structure for ALL secrets.
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
{mount}/{service}/{component}/{secret-name}
|
||||
|
||||
Examples:
|
||||
- secret-prod/postgres/database/app
|
||||
- secret-prod/redis/auth/default
|
||||
- secret-prod/authentik/admin/token
|
||||
```
|
||||
|
||||
### Environment Mounts
|
||||
|
||||
- `secret-dev/` - Development environment
|
||||
- `secret-staging/` - Staging environment
|
||||
- `secret-prod/` - Production environment
|
||||
|
||||
### Standard Field Names
|
||||
|
||||
- Credentials: `username`, `password`
|
||||
- Tokens: `token`
|
||||
- OAuth: `client_id`, `client_secret`
|
||||
- Connection strings: `url`, `host`, `port`
|
||||
|
||||
See `docs/vault-secrets-structure.md` for complete reference.
|
||||
|
||||
## Container Standards
|
||||
|
||||
### Dockerfile Best Practices
|
||||
|
||||
```dockerfile
|
||||
# Use specific version tags
|
||||
FROM node:20-alpine
|
||||
|
||||
# Create non-root user
|
||||
RUN addgroup -S app && adduser -S app -G app
|
||||
|
||||
# Set working directory
|
||||
WORKDIR /app
|
||||
|
||||
# Copy dependency files first (layer caching)
|
||||
COPY package*.json ./
|
||||
RUN npm ci --only=production
|
||||
|
||||
# Copy application code
|
||||
COPY --chown=app:app . .
|
||||
|
||||
# Switch to non-root user
|
||||
USER app
|
||||
|
||||
# Use exec form for CMD
|
||||
CMD ["node", "server.js"]
|
||||
```
|
||||
|
||||
### Container Security
|
||||
|
||||
- Use minimal base images (alpine, distroless)
|
||||
- Run as non-root user
|
||||
- Don't store secrets in images
|
||||
- Scan images for vulnerabilities
|
||||
- Pin dependency versions
|
||||
|
||||
## Kubernetes/Docker Compose
|
||||
|
||||
### Resource Limits
|
||||
|
||||
Always set resource limits to prevent runaway containers:
|
||||
|
||||
```yaml
|
||||
resources:
|
||||
requests:
|
||||
memory: '128Mi'
|
||||
cpu: '100m'
|
||||
limits:
|
||||
memory: '256Mi'
|
||||
cpu: '500m'
|
||||
```
|
||||
|
||||
### Health Checks
|
||||
|
||||
```yaml
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
path: /health
|
||||
port: 8080
|
||||
initialDelaySeconds: 10
|
||||
periodSeconds: 5
|
||||
|
||||
readinessProbe:
|
||||
httpGet:
|
||||
path: /ready
|
||||
port: 8080
|
||||
initialDelaySeconds: 5
|
||||
periodSeconds: 3
|
||||
```
|
||||
|
||||
## CI/CD Pipelines
|
||||
|
||||
### Pipeline Stages
|
||||
|
||||
1. **Lint**: Code style and static analysis
|
||||
2. **Test**: Unit and integration tests
|
||||
3. **Build**: Compile and package
|
||||
4. **Scan**: Security and vulnerability scanning
|
||||
5. **Deploy**: Environment-specific deployment
|
||||
|
||||
### Pipeline Security
|
||||
|
||||
- Use secrets management (not hardcoded)
|
||||
- Pin action/image versions
|
||||
- Implement approval gates for production
|
||||
- Audit pipeline access
|
||||
|
||||
## Steered-Autonomous Deployment (Hard Rule)
|
||||
|
||||
In lights-out mode, the agent owns deployment end-to-end when deployment is in scope.
|
||||
The human is escalation-only for missing access, hard policy conflicts, or irreversible risk.
|
||||
|
||||
### Deployment Target Selection
|
||||
|
||||
1. Use explicit target from `docs/PRD.md` / `docs/PRD.json` or `docs/DEPLOYMENT.md`.
|
||||
2. If unspecified, infer from existing project config/integration.
|
||||
3. If multiple targets exist, choose the target already wired in CI/CD and document rationale.
|
||||
|
||||
### Supported Targets
|
||||
|
||||
- **Portainer**: Deploy via `~/.config/mosaic/tools/portainer/stack-redeploy.sh`, then verify with `stack-status.sh`.
|
||||
- **Coolify**: Deploy via `~/.config/mosaic/tools/coolify/deploy.sh -u <uuid>`, then verify with `service-status.sh`.
|
||||
- **Vercel**: Deploy via `vercel` CLI or connected Git integration, then verify preview/production URL health.
|
||||
- **Other SaaS providers**: Use provider CLI/API/runbook with the same validation and rollback gates.
|
||||
|
||||
### Coolify API Operations
|
||||
|
||||
```bash
|
||||
# List projects and services
|
||||
~/.config/mosaic/tools/coolify/project-list.sh
|
||||
~/.config/mosaic/tools/coolify/service-list.sh
|
||||
|
||||
# Check service status
|
||||
~/.config/mosaic/tools/coolify/service-status.sh -u <uuid>
|
||||
|
||||
# Set env vars (takes effect on next deploy)
|
||||
~/.config/mosaic/tools/coolify/env-set.sh -u <uuid> -k KEY -v VALUE
|
||||
|
||||
# Deploy
|
||||
~/.config/mosaic/tools/coolify/deploy.sh -u <uuid>
|
||||
```
|
||||
|
||||
**Known Coolify Limitations:**
|
||||
|
||||
- FQDN updates on compose sub-apps not supported via API (DB workaround required)
|
||||
- Compose files must be base64-encoded in `docker_compose_raw` field
|
||||
- Magic variables (`SERVICE_FQDN_*`) require list-style env syntax, not dict-style
|
||||
- Rate limit: 200 requests per interval
|
||||
|
||||
### Cloudflare DNS Operations
|
||||
|
||||
Use the Cloudflare tools for any DNS configuration: pointing domains at services, adding TXT verification records, managing MX records, etc.
|
||||
|
||||
**Multi-instance support**: Credentials support named instances (e.g. `personal`, `work`). A `default` key in credentials.json determines which instance is used when `-a` is omitted. Pass `-a <instance>` to target a specific account.
|
||||
|
||||
```bash
|
||||
# List all zones (domains) in the account
|
||||
~/.config/mosaic/tools/cloudflare/zone-list.sh [-a instance]
|
||||
|
||||
# List DNS records for a zone (accepts zone name or ID)
|
||||
~/.config/mosaic/tools/cloudflare/record-list.sh -z <zone> [-t type] [-n name]
|
||||
|
||||
# Create a DNS record
|
||||
~/.config/mosaic/tools/cloudflare/record-create.sh -z <zone> -t <type> -n <name> -c <content> [-p] [-l ttl] [-P priority]
|
||||
|
||||
# Update a DNS record (requires record ID from record-list)
|
||||
~/.config/mosaic/tools/cloudflare/record-update.sh -z <zone> -r <record-id> -t <type> -n <name> -c <content> [-p]
|
||||
|
||||
# Delete a DNS record
|
||||
~/.config/mosaic/tools/cloudflare/record-delete.sh -z <zone> -r <record-id>
|
||||
```
|
||||
|
||||
**Flag reference:**
|
||||
|
||||
| Flag | Purpose |
|
||||
| ---- | ----------------------------------------------------------------------- |
|
||||
| `-z` | Zone name (e.g. `mosaicstack.dev`) or 32-char zone ID |
|
||||
| `-a` | Named Cloudflare instance (omit for default) |
|
||||
| `-t` | Record type: `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `SRV`, etc. |
|
||||
| `-n` | Record name: short (`app`) or FQDN (`app.example.com`) |
|
||||
| `-c` | Record content/value (IP, hostname, TXT string, etc.) |
|
||||
| `-r` | Record ID (from `record-list.sh` output) |
|
||||
| `-p` | Enable Cloudflare proxy (orange cloud) — omit for DNS-only (grey cloud) |
|
||||
| `-l` | TTL in seconds (default: `1` = auto) |
|
||||
| `-P` | Priority for MX/SRV records |
|
||||
| `-f` | Output format: `table` (default) or `json` |
|
||||
|
||||
**Common workflows:**
|
||||
|
||||
```bash
|
||||
# Point a new subdomain at a server (proxied through Cloudflare)
|
||||
~/.config/mosaic/tools/cloudflare/record-create.sh \
|
||||
-z example.com -t A -n myapp -c 203.0.113.10 -p
|
||||
|
||||
# Add a TXT record for domain verification (never proxied)
|
||||
~/.config/mosaic/tools/cloudflare/record-create.sh \
|
||||
-z example.com -t TXT -n _verify -c "verification=abc123"
|
||||
|
||||
# Check what records exist before making changes
|
||||
~/.config/mosaic/tools/cloudflare/record-list.sh -z example.com -t CNAME
|
||||
|
||||
# Update an existing record (get record ID from record-list first)
|
||||
~/.config/mosaic/tools/cloudflare/record-update.sh \
|
||||
-z example.com -r <record-id> -t A -n myapp -c 10.0.0.5 -p
|
||||
```
|
||||
|
||||
**DNS + Deployment integration**: When deploying a new service via Coolify or Portainer that needs a public domain, the typical sequence is:
|
||||
|
||||
1. Create the DNS record pointing at the host IP (with `-p` for Cloudflare proxy if desired)
|
||||
2. Deploy the service via Coolify/Portainer
|
||||
3. Verify the domain resolves and the service is reachable
|
||||
|
||||
**Proxy (`-p`) guidance:**
|
||||
|
||||
- Use proxy (orange cloud) for web services — provides CDN, DDoS protection, and hides origin IP
|
||||
- Skip proxy (grey cloud) for non-HTTP services (mail, SSH), wildcard records, or when the service handles its own TLS termination and needs direct client IP visibility
|
||||
- Proxy is NOT compatible with non-standard ports outside Cloudflare's supported range
|
||||
|
||||
### Stack Health Check
|
||||
|
||||
Verify all infrastructure services are reachable:
|
||||
|
||||
```bash
|
||||
~/.config/mosaic/tools/health/stack-health.sh
|
||||
```
|
||||
|
||||
### Image Tagging and Promotion (Hard Rule)
|
||||
|
||||
For containerized deployments:
|
||||
|
||||
1. Build immutable image tags: `sha-<shortsha>` and `v{base-version}-rc.{build}`.
|
||||
2. Use mutable environment tags only as pointers: `testing`, optional `staging`, and `prod`.
|
||||
3. Deploy by immutable digest, not by mutable tag alone.
|
||||
4. Promote the exact tested digest between environments (no rebuild between testing and prod).
|
||||
5. Do not use `latest` or `dev` as deployment references.
|
||||
|
||||
Blue-green is the default strategy for production promotion.
|
||||
Canary is allowed only when automated SLO/error-rate gates and auto-rollback triggers are implemented.
|
||||
|
||||
### Post-Deploy Validation (REQUIRED)
|
||||
|
||||
1. Health endpoints return expected status.
|
||||
2. Critical smoke tests pass in target environment.
|
||||
3. Running version and digest match the promoted release candidate.
|
||||
4. Observability signals (errors/latency) are within expected thresholds.
|
||||
|
||||
### Rollback Rule
|
||||
|
||||
If post-deploy validation fails:
|
||||
|
||||
1. Execute rollback/redeploy-safe path immediately.
|
||||
2. Mark deployment as blocked in `docs/TASKS.md`.
|
||||
3. Record failure evidence and next remediation step in scratchpad and release notes.
|
||||
|
||||
### Registry Retention and Cleanup
|
||||
|
||||
Cleanup MUST be automated.
|
||||
|
||||
- Keep all final release tags (`vX.Y.Z`) indefinitely.
|
||||
- Keep active environment digests (`prod`, `testing`, and active blue/green slots).
|
||||
- Keep recent RC tags (`vX.Y.Z-rc.N`) based on retention window.
|
||||
- Remove stale `sha-*` and RC tags outside retention window if they are not actively deployed.
|
||||
|
||||
## Monitoring & Logging
|
||||
|
||||
### Logging Standards
|
||||
|
||||
- Use structured logging (JSON)
|
||||
- Include correlation IDs
|
||||
- Log at appropriate levels (ERROR, WARN, INFO, DEBUG)
|
||||
- Never log sensitive data
|
||||
|
||||
### Metrics to Collect
|
||||
|
||||
- Request latency (p50, p95, p99)
|
||||
- Error rates
|
||||
- Resource utilization (CPU, memory)
|
||||
- Business metrics
|
||||
|
||||
### Alerting
|
||||
|
||||
- Define SLOs (Service Level Objectives)
|
||||
- Alert on symptoms, not causes
|
||||
- Include runbook links in alerts
|
||||
- Avoid alert fatigue
|
||||
|
||||
## Testing Infrastructure
|
||||
|
||||
### Test Categories
|
||||
|
||||
1. **Unit tests**: Terraform/Ansible logic
|
||||
2. **Integration tests**: Deployed resources work together
|
||||
3. **Smoke tests**: Critical paths after deployment
|
||||
4. **Chaos tests**: Failure mode validation
|
||||
|
||||
### Infrastructure Testing Tools
|
||||
|
||||
- Terraform: `terraform validate`, `terraform plan`
|
||||
- Ansible: `ansible-lint`, molecule
|
||||
- Kubernetes: `kubectl dry-run`, kubeval
|
||||
- General: Terratest, ServerSpec
|
||||
|
||||
## Commit Format
|
||||
|
||||
```
|
||||
chore(#67): Configure Redis cluster
|
||||
|
||||
- Add Redis StatefulSet with 3 replicas
|
||||
- Configure persistence with PVC
|
||||
- Add Vault secret for auth password
|
||||
|
||||
Refs #67
|
||||
```
|
||||
|
||||
## Before Completing
|
||||
|
||||
1. Validate configuration syntax
|
||||
2. Run infrastructure tests
|
||||
3. Test in dev/staging first
|
||||
4. Document any manual steps required
|
||||
5. Update scratchpad and close issue
|
||||
51
guides/MEMORY.md
Normal file
51
guides/MEMORY.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# Memory and Retention Rules
|
||||
|
||||
## Primary Memory Layer: OpenBrain
|
||||
|
||||
**OpenBrain is the canonical shared memory for all Mosaic agents across all harnesses and sessions.**
|
||||
|
||||
Use the `capture` MCP tool (or REST `POST /v1/thoughts`) to store:
|
||||
|
||||
- Discovered gotchas and workarounds
|
||||
- Architectural decisions and rationale
|
||||
- Project state and context for handoffs
|
||||
- Anything a future agent should know
|
||||
|
||||
Use `search` or `recent` at session start to load prior context before acting.
|
||||
|
||||
This is not optional. An agent that uses local file-based memory instead of OpenBrain is a broken agent — its knowledge is invisible to every other agent on the platform.
|
||||
|
||||
## Hard Rules
|
||||
|
||||
1. Agent learnings MUST go to OpenBrain — not to any file-based memory location.
|
||||
2. You MUST NOT write to runtime-native memory silos (they are write-blocked by hook).
|
||||
3. Active execution state belongs in project `docs/` — not in memory files.
|
||||
4. `~/.config/mosaic/memory/` is for mosaic framework technical notes only, not project knowledge.
|
||||
|
||||
## Runtime-Native Memory Silos (WRITE-BLOCKED)
|
||||
|
||||
These locations are blocked by PreToolUse hooks. Attempting to write there fails at the tool level.
|
||||
|
||||
| Runtime | Blocked silo | Use instead |
|
||||
| ----------- | ---------------------------------- | ------------------- |
|
||||
| Claude Code | `~/.claude/projects/*/memory/*.md` | OpenBrain `capture` |
|
||||
| Codex | Runtime session memory | OpenBrain `capture` |
|
||||
| OpenCode | Runtime session memory | OpenBrain `capture` |
|
||||
|
||||
MEMORY.md files may only contain behavioral guardrails that must be injected at load-path — not knowledge.
|
||||
|
||||
## Project Continuity Files (MANDATORY)
|
||||
|
||||
| File | Purpose | Location |
|
||||
| -------------------------------- | ----------------------------------------- | --------------------------- |
|
||||
| `docs/PRD.md` or `docs/PRD.json` | Source of requirements | Project `docs/` |
|
||||
| `docs/TASKS.md` | Task tracking, milestones, issues, status | Project `docs/` |
|
||||
| `docs/scratchpads/<task>.md` | Task-specific working memory | Project `docs/scratchpads/` |
|
||||
| `AGENTS.md` | Project-local patterns and conventions | Project root |
|
||||
|
||||
## How the Block Works
|
||||
|
||||
`~/.config/mosaic/tools/qa/prevent-memory-write.sh` is registered as a `PreToolUse` hook in
|
||||
`~/.claude/settings.json`. It intercepts Write/Edit/MultiEdit calls and rejects any targeting
|
||||
`~/.claude/projects/*/memory/*.md` before the tool executes. Exit code 2 blocks the call and
|
||||
the agent sees a message directing it to OpenBrain instead.
|
||||
127
guides/ORCHESTRATOR-LEARNINGS.md
Normal file
127
guides/ORCHESTRATOR-LEARNINGS.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# Orchestrator Learnings (Universal)
|
||||
|
||||
> Cross-project heuristic adjustments based on observed variance data.
|
||||
>
|
||||
> **Note:** This file contains generic patterns only. Project-specific evidence is stored in each project's `docs/tasks/orchestrator-learnings.json`.
|
||||
|
||||
## Task Type Multipliers
|
||||
|
||||
Apply these multipliers to base estimates from `ORCHESTRATOR.md`:
|
||||
|
||||
| Task Type | Base Estimate | Multiplier | Confidence | Samples | Last Updated |
|
||||
| --------------------- | ---------------- | ---------- | ---------- | ------- | ------------ |
|
||||
| STYLE_FIX | 3-5K | 0.64 | MEDIUM | n=1 | 2026-02-05 |
|
||||
| BULK_CLEANUP | file_count × 550 | 1.0 | MEDIUM | n=2 | 2026-02-05 |
|
||||
| GUARD_ADD | 5-8K | 1.0 | LOW | n=0 | - |
|
||||
| SECURITY_FIX | 8-12K | 2.5 | LOW | n=0 | - |
|
||||
| AUTH_ADD | 15-25K | 1.0 | HIGH | n=1 | 2026-02-05 |
|
||||
| REFACTOR | 10-15K | 1.0 | LOW | n=0 | - |
|
||||
| TEST_ADD | 15-25K | 1.0 | LOW | n=0 | - |
|
||||
| ERROR_HANDLING | 8-12K | 2.3 | MEDIUM | n=1 | 2026-02-05 |
|
||||
| CONFIG_DEFAULT_CHANGE | 5-10K | 1.8 | MEDIUM | n=1 | 2026-02-05 |
|
||||
| INPUT_VALIDATION | 5-8K | 1.7 | MEDIUM | n=1 | 2026-02-05 |
|
||||
|
||||
## Phase Factors
|
||||
|
||||
Apply to all estimates based on task position in milestone:
|
||||
|
||||
| Phase Position | Factor | Rationale |
|
||||
| ----------------- | ------ | -------------------------- |
|
||||
| Early (tasks 1-3) | 1.45 | Codebase learning overhead |
|
||||
| Mid (tasks 4-7) | 1.25 | Pattern recognition phase |
|
||||
| Late (tasks 8+) | 1.10 | Established patterns |
|
||||
|
||||
## Estimation Formula
|
||||
|
||||
```
|
||||
Final Estimate = Base Estimate × Type Multiplier × Phase Factor × TDD Overhead
|
||||
|
||||
Where:
|
||||
- Base Estimate: From ORCHESTRATOR.md task type table
|
||||
- Type Multiplier: From table above (default 1.0)
|
||||
- Phase Factor: 1.45 / 1.25 / 1.10 based on position
|
||||
- TDD Overhead: 1.20 if tests required
|
||||
```
|
||||
|
||||
## Known Patterns
|
||||
|
||||
### BULK_CLEANUP
|
||||
|
||||
**Pattern:** Multi-file cleanup tasks are severely underestimated.
|
||||
|
||||
**Why:** Iterative testing across many files, cascading fixes, and debugging compound the effort.
|
||||
|
||||
**Observed:** +112% to +276% variance when using fixed estimates.
|
||||
|
||||
**Recommendation:** Use `file_count × 550` instead of fixed estimate.
|
||||
|
||||
### ERROR_HANDLING
|
||||
|
||||
**Pattern:** Error handling changes that modify type interfaces cascade through the codebase.
|
||||
|
||||
**Why:** Adding fields to result types requires updating all callers, error messages, and tests.
|
||||
|
||||
**Observed:** +131% variance.
|
||||
|
||||
**Multiplier:** 2.3x base estimate when type interfaces are modified.
|
||||
|
||||
### CONFIG_DEFAULT_CHANGE
|
||||
|
||||
**Pattern:** Config default changes require more test coverage than expected.
|
||||
|
||||
**Why:** Security-sensitive defaults need validation tests, warning tests, and edge case coverage.
|
||||
|
||||
**Observed:** +80% variance.
|
||||
|
||||
**Multiplier:** 1.8x when config changes need security validation.
|
||||
|
||||
### INPUT_VALIDATION
|
||||
|
||||
**Pattern:** Security input validation with allowlists is more complex than simple validation.
|
||||
|
||||
**Why:** Comprehensive allowlists (e.g., OAuth error codes), encoding requirements, and security tests add up.
|
||||
|
||||
**Observed:** +70% variance.
|
||||
|
||||
**Multiplier:** 1.7x when security allowlists are involved.
|
||||
|
||||
### STYLE_FIX
|
||||
|
||||
**Pattern:** Pure formatting fixes are faster than estimated when isolated.
|
||||
|
||||
**Observed:** -36% variance.
|
||||
|
||||
**Multiplier:** 0.64x for isolated style-only fixes.
|
||||
|
||||
## Changelog
|
||||
|
||||
| Date | Change | Samples | Confidence |
|
||||
| ---------- | ------------------------------------------- | ------- | ---------- |
|
||||
| 2026-02-05 | Added BULK_CLEANUP category | n=2 | MEDIUM |
|
||||
| 2026-02-05 | Added STYLE_FIX multiplier 0.64 | n=1 | MEDIUM |
|
||||
| 2026-02-05 | Confirmed AUTH_ADD heuristic accurate | n=1 | HIGH |
|
||||
| 2026-02-05 | Added ERROR_HANDLING multiplier 2.3x | n=1 | MEDIUM |
|
||||
| 2026-02-05 | Added CONFIG_DEFAULT_CHANGE multiplier 1.8x | n=1 | MEDIUM |
|
||||
| 2026-02-05 | Added INPUT_VALIDATION multiplier 1.7x | n=1 | MEDIUM |
|
||||
|
||||
## Update Protocol
|
||||
|
||||
**Graduated Autonomy:**
|
||||
|
||||
| Phase | Condition | Action |
|
||||
| ---------------------- | ----------------------------------------- | -------------------------------------------- |
|
||||
| **Now** | All proposals | Human review required |
|
||||
| **After 3 milestones** | <30% change, n≥3 samples, HIGH confidence | Auto-update allowed |
|
||||
| **Mature** | All changes | Auto with notification, revert on regression |
|
||||
|
||||
**Validation Before Update:**
|
||||
|
||||
1. Minimum 3 samples for same task type
|
||||
2. Standard deviation < 30% of mean
|
||||
3. Outliers (>2σ) excluded
|
||||
4. New formula must not increase variance on historical data
|
||||
|
||||
## Where to Find Project-Specific Data
|
||||
|
||||
- **Project learnings:** `<project>/docs/tasks/orchestrator-learnings.json`
|
||||
- **Cross-project metrics:** `jarvis-brain/data/orchestrator-metrics.json`
|
||||
268
guides/ORCHESTRATOR-PROTOCOL.md
Normal file
268
guides/ORCHESTRATOR-PROTOCOL.md
Normal file
@@ -0,0 +1,268 @@
|
||||
# Orchestrator Protocol — Mission Lifecycle Guide
|
||||
|
||||
> **Operational guide for agent sessions.** Distilled from the full specification at
|
||||
> `jarvis-brain/docs/protocols/ORCHESTRATOR-PROTOCOL.md` (1,066 lines).
|
||||
>
|
||||
> Load this guide when: active mission detected, multi-milestone orchestration, mission continuation.
|
||||
> Load `ORCHESTRATOR.md` for per-session execution protocol (planning, coding, review, commit cycle).
|
||||
|
||||
---
|
||||
|
||||
## 1. Relationship to ORCHESTRATOR.md
|
||||
|
||||
| Concern | Guide |
|
||||
| -------------------------------------------------------------------- | ----------------- |
|
||||
| How to execute within a session (plan, code, test, review, commit) | `ORCHESTRATOR.md` |
|
||||
| How to manage a mission across sessions (resume, continue, handoff) | **This guide** |
|
||||
| Both guides are active simultaneously during orchestration missions. |
|
||||
|
||||
---
|
||||
|
||||
## 2. Mission Manifest
|
||||
|
||||
**Location:** `docs/MISSION-MANIFEST.md`
|
||||
**Owner:** Orchestrator (sole writer)
|
||||
**Template:** `~/.config/mosaic/templates/docs/MISSION-MANIFEST.md.template`
|
||||
|
||||
The manifest is the persistent document tracking full mission scope, status, milestones, and session history. It survives session death.
|
||||
|
||||
### Update Rules
|
||||
|
||||
- Update **Phase** when transitioning (Intake → Planning → Execution → Continuation → Completion)
|
||||
- Update **Current Milestone** when starting a new milestone
|
||||
- Update **Progress** after each milestone completion
|
||||
- Append to **Session History** at session start and end
|
||||
- Update **Status** to `completed` only when ALL success criteria are verified
|
||||
|
||||
### Hard Rule
|
||||
|
||||
The manifest is the source of truth for mission scope. If the manifest says a milestone is done, it is done. If it says remaining, it remains.
|
||||
|
||||
---
|
||||
|
||||
## 3. Scratchpad Protocol
|
||||
|
||||
**Location:** `docs/scratchpads/{mission-id}.md`
|
||||
**Template:** `~/.config/mosaic/templates/docs/mission-scratchpad.md.template`
|
||||
|
||||
### Rules
|
||||
|
||||
1. **First action** — Before ANY planning or coding, write the mission prompt to the scratchpad
|
||||
2. **Append-only** — NEVER delete or overwrite previous entries
|
||||
3. **Session log** — Record session start, tasks done, and outcome at session end
|
||||
4. **Decisions** — Record all planning decisions with rationale
|
||||
5. **Corrections** — Record course corrections from human or coordinator
|
||||
6. **Never deleted** — Scratchpads survive mission completion (archival reference)
|
||||
|
||||
---
|
||||
|
||||
## 4. TASKS.md as Control Plane
|
||||
|
||||
**Location:** `docs/TASKS.md`
|
||||
**Owner:** Orchestrator (sole writer). Workers read but NEVER modify.
|
||||
|
||||
### Table Schema
|
||||
|
||||
```markdown
|
||||
| id | status | milestone | description | pr | notes |
|
||||
```
|
||||
|
||||
### Status Values
|
||||
|
||||
`not-started` → `in-progress` → `done` (or `blocked` / `failed`)
|
||||
|
||||
### Planning Tasks Are First-Class
|
||||
|
||||
Include explicit planning tasks (e.g., `PLAN-001: Break down milestone into tasks`). These count toward progress.
|
||||
|
||||
### Post-Merge Tasks Are Explicit
|
||||
|
||||
Include verification tasks after merge: CI check, deployment verification, Playwright test. Don't assume they happen automatically.
|
||||
|
||||
---
|
||||
|
||||
## 5. Session Resume Protocol
|
||||
|
||||
When starting a session and an active mission is detected, follow this checklist:
|
||||
|
||||
### Detection (5-point check)
|
||||
|
||||
1. `docs/MISSION-MANIFEST.md` exists → read Phase, Current Milestone, Progress
|
||||
2. `docs/scratchpads/*.md` exists → read latest scratchpad for decisions and corrections
|
||||
3. `docs/TASKS.md` exists → read task state (what's done, what's next)
|
||||
4. Git state → current branch, open PRs, recent commits
|
||||
5. Provider state → open issues, milestone status (if accessible)
|
||||
|
||||
### Resume Procedure
|
||||
|
||||
1. Read the mission manifest FIRST
|
||||
2. Read the scratchpad for session history and corrections
|
||||
3. Read TASKS.md for current task state
|
||||
4. Identify the next `not-started` or `in-progress` task
|
||||
5. Continue execution from that task
|
||||
6. Update Session History in the manifest
|
||||
|
||||
### Dirty State Recovery
|
||||
|
||||
| State | Recovery |
|
||||
| ------------------------ | ------------------------------------------------------------------- |
|
||||
| Dirty git working tree | Stash changes, log stash ref in scratchpad, resume clean |
|
||||
| Open PR in bad state | Check PR status, close if broken, re-create if needed |
|
||||
| Half-created issues | Audit issues against TASKS.md, reconcile |
|
||||
| Tasks marked in-progress | Check if work was committed; if so, mark done; if not, restart task |
|
||||
|
||||
### Hard Rule
|
||||
|
||||
Session state is NEVER automatically deleted. The coordinator (human or automated) must explicitly request cleanup.
|
||||
|
||||
---
|
||||
|
||||
## 6. Mission Continuation
|
||||
|
||||
When a milestone completes and more milestones remain:
|
||||
|
||||
### Agent Handoff (at ~55-60% context)
|
||||
|
||||
If context usage is high, produce a handoff message:
|
||||
|
||||
1. Update TASKS.md with final task statuses
|
||||
2. Update mission manifest with session results
|
||||
3. Append session summary to scratchpad
|
||||
4. Commit all state files
|
||||
5. The coordinator will generate a continuation prompt for the next session
|
||||
|
||||
### Continuation Prompt and Capsule Format
|
||||
|
||||
The coordinator generates this (via `mosaic coord continue`) and writes a machine-readable capsule at `.mosaic/orchestrator/next-task.json`:
|
||||
|
||||
```
|
||||
## Continuation Mission
|
||||
Continue **{mission}** from existing state.
|
||||
- Read docs/MISSION-MANIFEST.md for scope and status
|
||||
- Read docs/scratchpads/{id}.md for decisions
|
||||
- Read docs/TASKS.md for current state
|
||||
- Continue from task {next-task-id}
|
||||
```
|
||||
|
||||
### Between Sessions (r0 manual)
|
||||
|
||||
1. Agent stops (expected — this is the confirmed stamina limitation)
|
||||
2. Human runs `mosaic coord mission` to check status
|
||||
3. Human runs `mosaic coord continue` to generate continuation prompt
|
||||
4. Human launches new session and pastes the prompt
|
||||
5. New agent reads manifest, scratchpad, TASKS.md and continues
|
||||
|
||||
### Between Sessions (r0 assisted)
|
||||
|
||||
Use `mosaic coord run` to remove copy/paste steps:
|
||||
|
||||
1. Agent stops
|
||||
2. Human runs `mosaic coord run [--claude|--codex]`
|
||||
3. Coordinator regenerates continuation prompt + `next-task.json`
|
||||
4. Coordinator launches selected runtime with scoped kickoff context
|
||||
5. New session resumes from next task
|
||||
|
||||
---
|
||||
|
||||
## 7. Failure Taxonomy Quick Reference
|
||||
|
||||
| Code | Type | Recovery |
|
||||
| ---- | ---------------------- | ----------------------------------------------------- |
|
||||
| F1 | Premature Stop | Continuation prompt → new session (most common) |
|
||||
| F2 | Context Exhaustion | Handoff message → new session |
|
||||
| F3 | Session Crash | Check git state → `mosaic coord resume` → new session |
|
||||
| F4 | Error Spiral | Kill session, mark task blocked, skip to next |
|
||||
| F5 | Quality Gate Failure | Create QA remediation task |
|
||||
| F6 | Infrastructure Failure | Pause, retry when service recovers |
|
||||
| F7 | False Completion | Append correction to scratchpad, relaunch |
|
||||
| F8 | Scope Drift | Kill session, relaunch with scratchpad ref |
|
||||
| F9 | Subagent Failure | Orchestrator retries or creates remediation |
|
||||
| F10 | Deadlock | Escalate to human |
|
||||
|
||||
### F1: Premature Stop — Detailed Recovery
|
||||
|
||||
This is the confirmed, most common failure. Every session will eventually trigger F1.
|
||||
|
||||
1. Session ends with tasks remaining in TASKS.md
|
||||
2. Run `mosaic coord mission` — verify milestone status
|
||||
3. If milestone complete: verify CI green, deployed, issues closed
|
||||
4. Run `mosaic coord continue` — generates scoped continuation prompt
|
||||
5. Launch new session, paste prompt
|
||||
6. New session reads state and continues from next pending task
|
||||
|
||||
---
|
||||
|
||||
## 8. r0 Manual Coordinator Process
|
||||
|
||||
In r0, the Coordinator is Jason + shell scripts. No daemon. No automation.
|
||||
|
||||
### Commands
|
||||
|
||||
| Command | Purpose |
|
||||
| --------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------ |
|
||||
| `mosaic coord init --name "..." --milestones "..."` | Initialize a new mission |
|
||||
| `mosaic coord mission` | Show mission progress dashboard |
|
||||
| `mosaic coord status` | Check if agent session is still running |
|
||||
| `mosaic coord continue` | Generate continuation prompt for next session |
|
||||
| `mosaic coord run [--claude | --codex]` | Generate continuation context and launch runtime |
|
||||
| `mosaic coord resume` | Crash recovery (detect dirty state, generate fix) |
|
||||
| `mosaic coord resume --clean-lock` | Clear stale session lock after review |
|
||||
|
||||
### Typical Workflow
|
||||
|
||||
```
|
||||
init → launch agent → [agent works] → agent stops →
|
||||
status → mission → run → repeat
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Operational Checklist
|
||||
|
||||
### Pre-Mission
|
||||
|
||||
- [ ] Mission initialized: `mosaic coord init`
|
||||
- [ ] docs/MISSION-MANIFEST.md exists with scope and milestones
|
||||
- [ ] docs/TASKS.md scaffolded
|
||||
- [ ] docs/scratchpads/{id}.md scaffolded
|
||||
- [ ] Success criteria defined in manifest
|
||||
|
||||
### Session Start
|
||||
|
||||
- [ ] Read manifest → know phase, milestone, progress
|
||||
- [ ] Read scratchpad → know decisions, corrections, history
|
||||
- [ ] Read TASKS.md → know what's done and what's next
|
||||
- [ ] Write session start to scratchpad
|
||||
- [ ] Update Session History in manifest
|
||||
|
||||
### Planning Gate (Hard Gate — No Coding Until Complete)
|
||||
|
||||
- [ ] Milestones created in provider (Gitea/GitHub)
|
||||
- [ ] Issues created for all milestone tasks
|
||||
- [ ] TASKS.md populated with all planned tasks (including planning + verification tasks)
|
||||
- [ ] All planning artifacts committed and pushed
|
||||
|
||||
### Per-Task
|
||||
|
||||
- [ ] Update task status to `in-progress` in TASKS.md
|
||||
- [ ] Execute task following ORCHESTRATOR.md cycle
|
||||
- [ ] Update task status to `done` (or `blocked`/`failed`)
|
||||
- [ ] Commit, push
|
||||
|
||||
### Milestone Completion
|
||||
|
||||
- [ ] All milestone tasks in TASKS.md are `done`
|
||||
- [ ] CI/pipeline green
|
||||
- [ ] PR merged to `main`
|
||||
- [ ] Issues closed
|
||||
- [ ] Update manifest: milestone status → completed
|
||||
- [ ] Update scratchpad: session log entry
|
||||
- [ ] If deployment target: verify accessible
|
||||
|
||||
### Mission Completion
|
||||
|
||||
- [ ] ALL milestones completed
|
||||
- [ ] ALL success criteria verified with evidence
|
||||
- [ ] manifest status → completed
|
||||
- [ ] Final scratchpad entry with completion evidence
|
||||
- [ ] Release tag created and pushed (if applicable)
|
||||
1175
guides/ORCHESTRATOR.md
Normal file
1175
guides/ORCHESTRATOR.md
Normal file
File diff suppressed because it is too large
Load Diff
63
guides/PRD.md
Normal file
63
guides/PRD.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# PRD Requirement Guide (MANDATORY)
|
||||
|
||||
This guide defines how requirements are captured before coding.
|
||||
|
||||
## Hard Rules
|
||||
|
||||
1. Before coding begins, `docs/PRD.md` or `docs/PRD.json` MUST exist.
|
||||
2. The PRD is the authoritative requirements source for implementation and testing.
|
||||
3. The main agent MUST prepare or update the PRD using user input and available project context before implementation starts.
|
||||
4. The agent MUST NOT invent requirements silently.
|
||||
5. In steered autonomy mode, best-guess decisions are REQUIRED when needed; each guessed decision MUST be marked with `ASSUMPTION:` and rationale.
|
||||
|
||||
## PRD Format
|
||||
|
||||
Allowed canonical formats:
|
||||
|
||||
1. `docs/PRD.md`
|
||||
2. `docs/PRD.json`
|
||||
|
||||
Either format is valid. Both may exist if one is a transformed representation of the other.
|
||||
For markdown PRDs, start from `~/.config/mosaic/templates/docs/PRD.md.template`.
|
||||
|
||||
## Best-Guess Mode
|
||||
|
||||
Steered autonomy is the default operating mode.
|
||||
|
||||
1. Agent SHOULD fill missing decisions in the PRD without waiting for routine confirmation.
|
||||
2. Agent MUST mark each guessed decision with `ASSUMPTION:` and rationale.
|
||||
3. If user explicitly requests strict-confirmation mode, the agent MUST ask before unresolved decisions are finalized.
|
||||
4. For high-impact security/compliance/release uncertainty, escalate only if the decision cannot be safely constrained with rollback-ready defaults.
|
||||
|
||||
## Minimum PRD Content
|
||||
|
||||
Every PRD MUST include:
|
||||
|
||||
1. Problem statement and objective
|
||||
2. In-scope and out-of-scope
|
||||
3. User/stakeholder requirements
|
||||
4. Functional requirements
|
||||
5. Non-functional requirements (security, performance, reliability, observability)
|
||||
6. Acceptance criteria
|
||||
7. Constraints and dependencies
|
||||
8. Risks and open questions
|
||||
9. Testing and verification expectations
|
||||
10. Delivery/milestone intent
|
||||
|
||||
## Pre-Coding Gate
|
||||
|
||||
Coding MUST NOT begin until:
|
||||
|
||||
1. PRD file exists (`docs/PRD.md` or `docs/PRD.json`)
|
||||
2. PRD has required sections
|
||||
3. Unresolved decisions are captured as explicit `ASSUMPTION:` entries with rationale and planned validation
|
||||
|
||||
## Change Control
|
||||
|
||||
When requirements materially change:
|
||||
|
||||
1. Update PRD first.
|
||||
2. Then update implementation plan/tasks.
|
||||
3. Then implement code changes.
|
||||
|
||||
Implementation that diverges from PRD without PRD updates is a blocker.
|
||||
125
guides/QA-TESTING.md
Normal file
125
guides/QA-TESTING.md
Normal file
@@ -0,0 +1,125 @@
|
||||
# QA & Testing Guide
|
||||
|
||||
## Before Starting
|
||||
|
||||
1. Check assigned issue: `~/.config/mosaic/tools/git/issue-list.sh -a @me`
|
||||
2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
|
||||
3. Review `docs/PRD.md` or `docs/PRD.json` as the requirements source.
|
||||
4. Review acceptance criteria and affected change surfaces.
|
||||
|
||||
## Testing Policy (Hard Rules)
|
||||
|
||||
1. Situational testing is the PRIMARY validation gate.
|
||||
2. Baseline testing is REQUIRED for all software changes.
|
||||
3. TDD is risk-based and REQUIRED only for defined high-risk change types.
|
||||
4. Tests MUST validate requirements and behavior, not only internal implementation details.
|
||||
|
||||
## Priority Order
|
||||
|
||||
1. Situational tests: prove requirements and real behavior on changed surfaces.
|
||||
2. Baseline tests: lint/type/unit/integration safety checks.
|
||||
3. TDD discipline: applied where risk justifies test-first workflow.
|
||||
|
||||
## Risk-Based TDD Requirement
|
||||
|
||||
| Change Type | TDD Requirement | Required Action |
|
||||
| ---------------------------------------------- | --------------- | ---------------------------------------------------------------------- |
|
||||
| Bug fix | REQUIRED | Write a failing reproducer test first, then fix. |
|
||||
| Security/auth/permission logic | REQUIRED | Write failing security/permission-path test first. |
|
||||
| Critical business logic or data mutation rules | REQUIRED | Write failing rule/invariant test first. |
|
||||
| API behavior regression | REQUIRED | Write failing contract/behavior test first. |
|
||||
| Low-risk UI copy/style/layout | OPTIONAL | Add verification tests as appropriate; TDD recommended, not mandatory. |
|
||||
| Mechanical refactor with unchanged behavior | OPTIONAL | Ensure regression/smoke coverage and situational evidence. |
|
||||
|
||||
If TDD is not required and skipped, record rationale in scratchpad.
|
||||
If TDD is required and skipped, task is NOT complete.
|
||||
|
||||
## Baseline Test Requirements
|
||||
|
||||
For all software changes, run baseline checks applicable to the repo:
|
||||
|
||||
1. lint/static checks
|
||||
2. type checks
|
||||
3. unit tests for changed logic
|
||||
4. integration tests for changed boundaries
|
||||
|
||||
## Situational Testing Matrix (Primary Gate)
|
||||
|
||||
| Change Surface | Required Situational Tests |
|
||||
| ---------------------------- | ----------------------------------------------------------------------------- |
|
||||
| Authentication/authorization | auth failure-path tests, permission boundary tests, token/session validation |
|
||||
| Database schema/migrations | migration up/down validation, rollback safety, data integrity checks |
|
||||
| API contract changes | backward compatibility checks, consumer-impact tests, contract tests |
|
||||
| Frontend/UI workflow changes | end-to-end flow tests, accessibility sanity checks, state transition checks |
|
||||
| CI/CD or deployment changes | pipeline execution validation, artifact integrity checks, rollback path check |
|
||||
| Security-sensitive logic | abuse-case tests, input validation fuzzing/sanitization checks |
|
||||
| Performance-critical path | baseline comparison, regression threshold checks |
|
||||
|
||||
## Coverage Requirements
|
||||
|
||||
### Minimum Standards
|
||||
|
||||
- Overall Coverage: 85% minimum
|
||||
- Critical Paths: 95% minimum (auth, payments, data mutations)
|
||||
- New Code: 90% minimum
|
||||
|
||||
Coverage is necessary but NOT sufficient. Passing coverage does not replace situational verification.
|
||||
|
||||
## Requirements-to-Evidence Mapping (Mandatory)
|
||||
|
||||
Before completion, map each acceptance criterion to concrete evidence.
|
||||
Acceptance criteria MUST come from the active PRD.
|
||||
|
||||
Template:
|
||||
|
||||
```markdown
|
||||
| Acceptance Criterion | Verification Method | Evidence |
|
||||
| -------------------- | ------------------------------------------------------ | ---------------- |
|
||||
| AC-1: ... | Situational test / baseline test / manual verification | command + result |
|
||||
| AC-2: ... | ... | ... |
|
||||
```
|
||||
|
||||
## Browser Automation (Hard Rule)
|
||||
|
||||
All browser automation (Playwright, Cypress, Puppeteer) MUST run in **headless mode**.
|
||||
Launching a visible browser collides with the user's display and active session.
|
||||
|
||||
- Playwright: use `headless: true` in config or `--headed` must NOT be passed
|
||||
- Cypress: use `cypress run` (headless by default), never `cypress open`
|
||||
- Puppeteer: use `headless: true` (default)
|
||||
|
||||
If a project's `playwright.config.ts` does not explicitly set `headless: true`, add it before running tests.
|
||||
|
||||
## Test Quality Rules
|
||||
|
||||
1. Test behavior and outcomes, not private implementation details.
|
||||
2. Include failure-path and edge-case assertions for changed behavior.
|
||||
3. Keep tests deterministic; no new flaky tests.
|
||||
4. Keep tests isolated; no dependency on execution order.
|
||||
|
||||
## Anti-Gaming Rules
|
||||
|
||||
1. Do NOT stop at "tests pass" if acceptance criteria are not verified.
|
||||
2. Do NOT write narrow tests that only satisfy assertions while missing real workflow behavior.
|
||||
3. Do NOT claim completion without situational evidence for impacted surfaces.
|
||||
|
||||
## Reporting
|
||||
|
||||
QA report MUST include:
|
||||
|
||||
1. baseline tests run and outcomes
|
||||
2. situational tests run and outcomes
|
||||
3. TDD usage decision (required/applied or optional/skipped with rationale)
|
||||
4. acceptance-criteria-to-evidence mapping
|
||||
5. coverage results
|
||||
6. residual risk notes
|
||||
|
||||
## Before Completing
|
||||
|
||||
1. Baseline tests pass.
|
||||
2. Required situational tests pass.
|
||||
3. TDD obligations met for required change types.
|
||||
4. Acceptance criteria mapped to evidence.
|
||||
5. No flaky tests introduced.
|
||||
6. CI pipeline passes (if available).
|
||||
7. Scratchpad updated with results.
|
||||
440
guides/TYPESCRIPT.md
Normal file
440
guides/TYPESCRIPT.md
Normal file
@@ -0,0 +1,440 @@
|
||||
# TypeScript Style Guide
|
||||
|
||||
**Authority**: This guide is MANDATORY for all TypeScript code. No exceptions without explicit approval.
|
||||
|
||||
Based on Google TypeScript Style Guide with stricter enforcement.
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Explicit over implicit** — Always declare types, never rely on inference for public APIs
|
||||
2. **Specific over generic** — Use the narrowest type that works
|
||||
3. **Safe over convenient** — Type safety is not negotiable
|
||||
4. **Contract-first boundaries** — Cross-module and API payloads MUST use dedicated DTO files
|
||||
|
||||
---
|
||||
|
||||
## DTO Contract (MANDATORY)
|
||||
|
||||
DTO files are REQUIRED for TypeScript module boundaries to preserve shared context and consistency.
|
||||
|
||||
Hard requirements:
|
||||
|
||||
1. Input and output payloads crossing module boundaries MUST be defined in `*.dto.ts` files.
|
||||
2. Controller/service boundary payloads MUST use DTO types; inline object literal types are NOT allowed.
|
||||
3. Public API request/response contracts MUST use DTO files and remain stable across modules.
|
||||
4. Shared DTOs used by multiple modules MUST live in a shared location (for example `src/shared/dto/` or `packages/shared/dto/`).
|
||||
5. ORM/entity models MUST NOT be exposed directly across module boundaries; map them to DTOs.
|
||||
6. DTO changes MUST be reflected in tests and documentation when contracts change.
|
||||
|
||||
```typescript
|
||||
// ❌ WRONG: inline payload contract at boundary
|
||||
export function createUser(payload: { email: string; role: string }): Promise<User> {}
|
||||
|
||||
// ✅ CORRECT: dedicated DTO file contract
|
||||
// user-create.dto.ts
|
||||
export interface UserCreateDto {
|
||||
email: string;
|
||||
role: UserRole;
|
||||
}
|
||||
|
||||
// user-response.dto.ts
|
||||
export interface UserResponseDto {
|
||||
id: string;
|
||||
email: string;
|
||||
role: UserRole;
|
||||
}
|
||||
|
||||
// service.ts
|
||||
export function createUser(payload: UserCreateDto): Promise<UserResponseDto> {}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Forbidden Patterns (NEVER USE)
|
||||
|
||||
### `any` Type — FORBIDDEN
|
||||
|
||||
```typescript
|
||||
// ❌ NEVER
|
||||
function process(data: any) {}
|
||||
const result: any = fetchData();
|
||||
Record<string, any>;
|
||||
|
||||
// ✅ ALWAYS define explicit types
|
||||
interface UserData {
|
||||
id: string;
|
||||
name: string;
|
||||
email: string;
|
||||
}
|
||||
function process(data: UserData) {}
|
||||
```
|
||||
|
||||
### `unknown` as Lazy Typing — FORBIDDEN
|
||||
|
||||
`unknown` is only acceptable in these specific cases:
|
||||
|
||||
1. Error catch blocks (then immediately narrow)
|
||||
2. JSON.parse results (then validate with Zod/schema)
|
||||
3. External API responses before validation
|
||||
|
||||
```typescript
|
||||
// ❌ NEVER - using unknown to avoid typing
|
||||
function getData(): unknown {}
|
||||
const config: Record<string, unknown> = {};
|
||||
|
||||
// ✅ ACCEPTABLE - error handling with immediate narrowing
|
||||
try {
|
||||
riskyOperation();
|
||||
} catch (error: unknown) {
|
||||
if (error instanceof Error) {
|
||||
logger.error(error.message);
|
||||
} else {
|
||||
logger.error('Unknown error', { error: String(error) });
|
||||
}
|
||||
}
|
||||
|
||||
// ✅ ACCEPTABLE - external data with validation
|
||||
const raw: unknown = JSON.parse(response);
|
||||
const validated = UserSchema.parse(raw); // Zod validation
|
||||
```
|
||||
|
||||
### Implicit `any` — FORBIDDEN
|
||||
|
||||
```typescript
|
||||
// ❌ NEVER - implicit any from missing types
|
||||
function process(data) {} // Parameter has implicit any
|
||||
const handler = (e) => {}; // Parameter has implicit any
|
||||
|
||||
// ✅ ALWAYS - explicit types
|
||||
function process(data: RequestPayload): ProcessedResult {}
|
||||
const handler = (e: React.MouseEvent<HTMLButtonElement>): void => {};
|
||||
```
|
||||
|
||||
### Type Assertions to Bypass Safety — FORBIDDEN
|
||||
|
||||
```typescript
|
||||
// ❌ NEVER - lying to the compiler
|
||||
const user = data as User;
|
||||
const element = document.getElementById('app') as HTMLDivElement;
|
||||
|
||||
// ✅ USE - type guards and narrowing
|
||||
function isUser(data: unknown): data is User {
|
||||
return typeof data === 'object' && data !== null && 'id' in data;
|
||||
}
|
||||
if (isUser(data)) {
|
||||
console.log(data.id); // Safe
|
||||
}
|
||||
|
||||
// ✅ USE - null checks
|
||||
const element = document.getElementById('app');
|
||||
if (element instanceof HTMLDivElement) {
|
||||
element.style.display = 'none'; // Safe
|
||||
}
|
||||
```
|
||||
|
||||
### Non-null Assertion (`!`) — FORBIDDEN (except tests)
|
||||
|
||||
```typescript
|
||||
// ❌ NEVER in production code
|
||||
const name = user!.name;
|
||||
const element = document.getElementById('app')!;
|
||||
|
||||
// ✅ USE - proper null handling
|
||||
const name = user?.name ?? 'Anonymous';
|
||||
const element = document.getElementById('app');
|
||||
if (element) {
|
||||
// Safe to use element
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Required Patterns
|
||||
|
||||
### Explicit Return Types — REQUIRED for all public functions
|
||||
|
||||
```typescript
|
||||
// ❌ WRONG - missing return type
|
||||
export function calculateTotal(items: Item[]) {
|
||||
return items.reduce((sum, item) => sum + item.price, 0);
|
||||
}
|
||||
|
||||
// ✅ CORRECT - explicit return type
|
||||
export function calculateTotal(items: Item[]): number {
|
||||
return items.reduce((sum, item) => sum + item.price, 0);
|
||||
}
|
||||
```
|
||||
|
||||
### Explicit Parameter Types — REQUIRED always
|
||||
|
||||
```typescript
|
||||
// ❌ WRONG
|
||||
const multiply = (a, b) => a * b;
|
||||
users.map((user) => user.name); // If user type isn't inferred
|
||||
|
||||
// ✅ CORRECT
|
||||
const multiply = (a: number, b: number): number => a * b;
|
||||
users.map((user: User): string => user.name);
|
||||
```
|
||||
|
||||
### Interface Over Type Alias — PREFERRED for objects
|
||||
|
||||
```typescript
|
||||
// ✅ PREFERRED - interface (extendable, better error messages)
|
||||
interface User {
|
||||
id: string;
|
||||
name: string;
|
||||
email: string;
|
||||
}
|
||||
|
||||
// ✅ ACCEPTABLE - type alias for unions, intersections, primitives
|
||||
type Status = 'active' | 'inactive' | 'pending';
|
||||
type ID = string | number;
|
||||
```
|
||||
|
||||
### Const Assertions for Literals — REQUIRED
|
||||
|
||||
```typescript
|
||||
// ❌ WRONG - loses literal types
|
||||
const config = {
|
||||
endpoint: '/api/users',
|
||||
method: 'GET',
|
||||
};
|
||||
// config.method is string, not 'GET'
|
||||
|
||||
// ✅ CORRECT - preserves literal types
|
||||
const config = {
|
||||
endpoint: '/api/users',
|
||||
method: 'GET',
|
||||
} as const;
|
||||
// config.method is 'GET'
|
||||
```
|
||||
|
||||
### Discriminated Unions — REQUIRED for variants
|
||||
|
||||
```typescript
|
||||
// ❌ WRONG - optional properties for variants
|
||||
interface ApiResponse {
|
||||
success: boolean;
|
||||
data?: User;
|
||||
error?: string;
|
||||
}
|
||||
|
||||
// ✅ CORRECT - discriminated union
|
||||
interface SuccessResponse {
|
||||
success: true;
|
||||
data: User;
|
||||
}
|
||||
interface ErrorResponse {
|
||||
success: false;
|
||||
error: string;
|
||||
}
|
||||
type ApiResponse = SuccessResponse | ErrorResponse;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Generic Constraints
|
||||
|
||||
### Meaningful Constraints — REQUIRED
|
||||
|
||||
```typescript
|
||||
// ❌ WRONG - unconstrained generic
|
||||
function merge<T>(a: T, b: T): T {}
|
||||
|
||||
// ✅ CORRECT - constrained generic
|
||||
function merge<T extends object>(a: T, b: Partial<T>): T {}
|
||||
```
|
||||
|
||||
### Default Generic Parameters — USE SPECIFIC TYPES
|
||||
|
||||
```typescript
|
||||
// ❌ WRONG
|
||||
interface Repository<T = unknown> {}
|
||||
|
||||
// ✅ CORRECT - no default if type should be explicit
|
||||
interface Repository<T extends Entity> {}
|
||||
|
||||
// ✅ ACCEPTABLE - meaningful default
|
||||
interface Cache<T extends Serializable = JsonValue> {}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## React/JSX Specific
|
||||
|
||||
### Event Handlers — EXPLICIT TYPES REQUIRED
|
||||
|
||||
```typescript
|
||||
// ❌ WRONG
|
||||
const handleClick = (e) => {};
|
||||
const handleChange = (e) => {};
|
||||
|
||||
// ✅ CORRECT
|
||||
const handleClick = (e: React.MouseEvent<HTMLButtonElement>): void => {};
|
||||
const handleChange = (e: React.ChangeEvent<HTMLInputElement>): void => {};
|
||||
const handleSubmit = (e: React.FormEvent<HTMLFormElement>): void => {};
|
||||
```
|
||||
|
||||
### Component Props — INTERFACE REQUIRED
|
||||
|
||||
```typescript
|
||||
// ❌ WRONG - inline types
|
||||
function Button({ label, onClick }: { label: string; onClick: () => void }) { }
|
||||
|
||||
// ✅ CORRECT - named interface
|
||||
interface ButtonProps {
|
||||
label: string;
|
||||
onClick: () => void;
|
||||
disabled?: boolean;
|
||||
}
|
||||
|
||||
function Button({ label, onClick, disabled = false }: ButtonProps): JSX.Element {
|
||||
return <button onClick={onClick} disabled={disabled}>{label}</button>;
|
||||
}
|
||||
```
|
||||
|
||||
### Children Prop — USE React.ReactNode
|
||||
|
||||
```typescript
|
||||
interface LayoutProps {
|
||||
children: React.ReactNode;
|
||||
sidebar?: React.ReactNode;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Response Typing
|
||||
|
||||
### Define Explicit Response Types
|
||||
|
||||
```typescript
|
||||
// ❌ WRONG
|
||||
const response = await fetch('/api/users');
|
||||
const data = await response.json(); // data is any
|
||||
|
||||
// ✅ CORRECT
|
||||
interface UsersResponse {
|
||||
users: User[];
|
||||
pagination: PaginationInfo;
|
||||
}
|
||||
|
||||
const response = await fetch('/api/users');
|
||||
const data: UsersResponse = await response.json();
|
||||
|
||||
// ✅ BEST - with runtime validation
|
||||
const response = await fetch('/api/users');
|
||||
const raw = await response.json();
|
||||
const data = UsersResponseSchema.parse(raw); // Zod validates at runtime
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Typed Error Classes — REQUIRED for domain errors
|
||||
|
||||
```typescript
|
||||
class ValidationError extends Error {
|
||||
constructor(
|
||||
message: string,
|
||||
public readonly field: string,
|
||||
public readonly code: string,
|
||||
) {
|
||||
super(message);
|
||||
this.name = 'ValidationError';
|
||||
}
|
||||
}
|
||||
|
||||
class NotFoundError extends Error {
|
||||
constructor(
|
||||
public readonly resource: string,
|
||||
public readonly id: string,
|
||||
) {
|
||||
super(`${resource} with id ${id} not found`);
|
||||
this.name = 'NotFoundError';
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Error Narrowing — REQUIRED
|
||||
|
||||
```typescript
|
||||
try {
|
||||
await saveUser(user);
|
||||
} catch (error: unknown) {
|
||||
if (error instanceof ValidationError) {
|
||||
return { error: error.message, field: error.field };
|
||||
}
|
||||
if (error instanceof NotFoundError) {
|
||||
return { error: 'Not found', resource: error.resource };
|
||||
}
|
||||
if (error instanceof Error) {
|
||||
logger.error('Unexpected error', { message: error.message, stack: error.stack });
|
||||
return { error: 'Internal error' };
|
||||
}
|
||||
logger.error('Unknown error type', { error: String(error) });
|
||||
return { error: 'Internal error' };
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ESLint Rules — ENFORCE THESE
|
||||
|
||||
```javascript
|
||||
{
|
||||
"@typescript-eslint/no-explicit-any": "error",
|
||||
"@typescript-eslint/explicit-function-return-type": ["error", {
|
||||
"allowExpressions": true,
|
||||
"allowTypedFunctionExpressions": true
|
||||
}],
|
||||
"@typescript-eslint/explicit-module-boundary-types": "error",
|
||||
"@typescript-eslint/no-inferrable-types": "off", // Allow explicit primitives
|
||||
"@typescript-eslint/no-non-null-assertion": "error",
|
||||
"@typescript-eslint/strict-boolean-expressions": "error",
|
||||
"@typescript-eslint/no-unsafe-assignment": "error",
|
||||
"@typescript-eslint/no-unsafe-member-access": "error",
|
||||
"@typescript-eslint/no-unsafe-call": "error",
|
||||
"@typescript-eslint/no-unsafe-return": "error"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## TSConfig Strict Mode — REQUIRED
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"strict": true,
|
||||
"noImplicitAny": true,
|
||||
"strictNullChecks": true,
|
||||
"strictFunctionTypes": true,
|
||||
"strictBindCallApply": true,
|
||||
"strictPropertyInitialization": true,
|
||||
"noImplicitThis": true,
|
||||
"useUnknownInCatchVariables": true,
|
||||
"noUncheckedIndexedAccess": true,
|
||||
"noImplicitReturns": true,
|
||||
"noFallthroughCasesInSwitch": true,
|
||||
"noImplicitOverride": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary: The Type Safety Hierarchy
|
||||
|
||||
From best to worst:
|
||||
|
||||
1. **Explicit specific type** (interface/type) — REQUIRED
|
||||
2. **Generic with constraints** — ACCEPTABLE
|
||||
3. **`unknown` with immediate validation** — ONLY for external data
|
||||
4. **`any`** — FORBIDDEN
|
||||
|
||||
**When in doubt, define an interface.**
|
||||
205
guides/VAULT-SECRETS.md
Normal file
205
guides/VAULT-SECRETS.md
Normal file
@@ -0,0 +1,205 @@
|
||||
# Vault Secrets Management Guide
|
||||
|
||||
This guide applies when the project uses HashiCorp Vault for secrets management.
|
||||
|
||||
## Before Starting
|
||||
|
||||
1. Verify Vault access: `vault status`
|
||||
2. Authenticate: `vault login` (method depends on environment)
|
||||
3. Check your permissions for the required paths
|
||||
|
||||
## Canonical Structure
|
||||
|
||||
**ALL Vault secrets MUST follow this structure:**
|
||||
|
||||
```
|
||||
{mount}/{service}/{component}/{secret-name}
|
||||
```
|
||||
|
||||
### Components
|
||||
|
||||
- **mount**: Environment-specific mount point
|
||||
- **service**: The service or application name
|
||||
- **component**: Logical grouping (database, api, oauth, etc.)
|
||||
- **secret-name**: Specific secret identifier
|
||||
|
||||
## Environment Mounts
|
||||
|
||||
| Mount | Environment | Usage |
|
||||
| ----------------- | ----------- | ---------------------- |
|
||||
| `secret-dev/` | Development | Local dev, CI |
|
||||
| `secret-staging/` | Staging | Pre-production testing |
|
||||
| `secret-prod/` | Production | Live systems |
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Database credentials
|
||||
secret-prod/postgres/database/app
|
||||
secret-prod/mysql/database/readonly
|
||||
secret-staging/redis/auth/default
|
||||
|
||||
# API tokens
|
||||
secret-prod/authentik/admin/token
|
||||
secret-prod/stripe/api/live-key
|
||||
secret-dev/sendgrid/api/test-key
|
||||
|
||||
# JWT/Authentication
|
||||
secret-prod/backend-api/jwt/signing-key
|
||||
secret-prod/auth-service/session/secret
|
||||
|
||||
# OAuth providers
|
||||
secret-prod/backend-api/oauth/google
|
||||
secret-prod/backend-api/oauth/github
|
||||
|
||||
# Internal services
|
||||
secret-prod/loki/read-auth/admin
|
||||
secret-prod/grafana/admin/password
|
||||
```
|
||||
|
||||
## Standard Field Names
|
||||
|
||||
Use consistent field names within secrets:
|
||||
|
||||
| Purpose | Fields |
|
||||
| ----------- | ---------------------------- |
|
||||
| Credentials | `username`, `password` |
|
||||
| Tokens | `token` |
|
||||
| OAuth | `client_id`, `client_secret` |
|
||||
| Connection | `url`, `host`, `port` |
|
||||
| Keys | `public_key`, `private_key` |
|
||||
|
||||
### Example Secret Structure
|
||||
|
||||
```json
|
||||
// secret-prod/postgres/database/app
|
||||
{
|
||||
"username": "app_user",
|
||||
"password": "secure-password-here",
|
||||
"host": "db.example.com",
|
||||
"port": "5432",
|
||||
"database": "myapp"
|
||||
}
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
1. **DO NOT GUESS** secret paths - Always verify the path exists
|
||||
2. **Use helper scripts** in `scripts/vault/` when available
|
||||
3. **All lowercase, hyphenated** (kebab-case) for all path segments
|
||||
4. **Standard field names** - Use the conventions above
|
||||
5. **No sensitive data in path names** - Path itself should not reveal secrets
|
||||
6. **Environment separation** - Never reference prod secrets from dev
|
||||
|
||||
## Deprecated Paths (DO NOT USE)
|
||||
|
||||
These legacy patterns are deprecated and should be migrated:
|
||||
|
||||
| Deprecated | Migrate To |
|
||||
| ------------------------- | ------------------------------------------- |
|
||||
| `secret/infrastructure/*` | `secret-{env}/{service}/...` |
|
||||
| `secret/oauth/*` | `secret-{env}/{service}/oauth/{provider}` |
|
||||
| `secret/database/*` | `secret-{env}/{service}/database/{user}` |
|
||||
| `secret/credentials/*` | `secret-{env}/{service}/{component}/{name}` |
|
||||
|
||||
## Reading Secrets
|
||||
|
||||
### CLI
|
||||
|
||||
```bash
|
||||
# Read a secret
|
||||
vault kv get secret-prod/postgres/database/app
|
||||
|
||||
# Get specific field
|
||||
vault kv get -field=password secret-prod/postgres/database/app
|
||||
|
||||
# JSON output
|
||||
vault kv get -format=json secret-prod/postgres/database/app
|
||||
```
|
||||
|
||||
### Application Code
|
||||
|
||||
**Python (hvac):**
|
||||
|
||||
```python
|
||||
import hvac
|
||||
|
||||
client = hvac.Client(url='https://vault.example.com')
|
||||
secret = client.secrets.kv.v2.read_secret_version(
|
||||
path='postgres/database/app',
|
||||
mount_point='secret-prod'
|
||||
)
|
||||
password = secret['data']['data']['password']
|
||||
```
|
||||
|
||||
**Node.js (node-vault):**
|
||||
|
||||
```javascript
|
||||
const vault = require('node-vault')({ endpoint: 'https://vault.example.com' });
|
||||
const secret = await vault.read('secret-prod/data/postgres/database/app');
|
||||
const password = secret.data.data.password;
|
||||
```
|
||||
|
||||
**Go:**
|
||||
|
||||
```go
|
||||
secret, err := client.Logical().Read("secret-prod/data/postgres/database/app")
|
||||
password := secret.Data["data"].(map[string]interface{})["password"].(string)
|
||||
```
|
||||
|
||||
## Writing Secrets
|
||||
|
||||
Only authorized personnel should write secrets. If you need a new secret:
|
||||
|
||||
1. Request through proper channels (ticket, PR to IaC repo)
|
||||
2. Follow the canonical structure
|
||||
3. Document the secret's purpose
|
||||
4. Set appropriate access policies
|
||||
|
||||
```bash
|
||||
# Example (requires write permissions)
|
||||
vault kv put secret-dev/myapp/database/app \
|
||||
username="dev_user" \
|
||||
password="dev-password" \
|
||||
host="localhost" \
|
||||
port="5432"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Permission Denied
|
||||
|
||||
```
|
||||
Error: permission denied
|
||||
```
|
||||
|
||||
- Verify your token has read access to the path
|
||||
- Check if you're using the correct mount point
|
||||
- Confirm the secret path exists
|
||||
|
||||
### Secret Not Found
|
||||
|
||||
```
|
||||
Error: no value found at secret-prod/data/service/component/name
|
||||
```
|
||||
|
||||
- Verify the exact path (use `vault kv list` to explore)
|
||||
- Check for typos in service/component names
|
||||
- Confirm you're using the correct environment mount
|
||||
|
||||
### Token Expired
|
||||
|
||||
```
|
||||
Error: token expired
|
||||
```
|
||||
|
||||
- Re-authenticate: `vault login`
|
||||
- Check token TTL: `vault token lookup`
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
1. **Least privilege** - Request only the permissions you need
|
||||
2. **Short-lived tokens** - Use tokens with appropriate TTLs
|
||||
3. **Audit logging** - All access is logged; act accordingly
|
||||
4. **No local copies** - Don't store secrets in files or env vars long-term
|
||||
5. **Rotate on compromise** - Immediately rotate any exposed secrets
|
||||
Reference in New Issue
Block a user