generalize runtime ownership with doctor and local skill migration
This commit is contained in:
Jason Woltje
616
runtime/claude/CLAUDE.md
Normal file
616
runtime/claude/CLAUDE.md
Normal file
@@ -0,0 +1,616 @@
|
||||
# Mosaic Universal Standards (Machine-Wide)
|
||||
|
||||
Before applying any runtime-specific guidance in this file, load and apply:
|
||||
- `~/.mosaic/STANDARDS.md`
|
||||
- project-local `AGENTS.md`
|
||||
|
||||
`~/.mosaic` is the canonical cross-agent standards layer. This `CLAUDE.md` is an adapter layer for Claude-specific capabilities only.
|
||||
|
||||
---
|
||||
|
||||
# Universal Development Standards
|
||||
|
||||
## Core Principles
|
||||
- Think critically. Don't just agree—suggest better approaches when appropriate.
|
||||
- Quality over speed. No workarounds; implement proper solutions.
|
||||
- No deprecated or unsupported packages.
|
||||
|
||||
## Skills System
|
||||
|
||||
**97 skills available in `~/.mosaic/skills/`.** Skills are instruction packages that provide domain expertise. Source: `mosaic/agent-skills` repo (93 community) + 4 local-only.
|
||||
|
||||
**Load a skill by reading its SKILL.md:**
|
||||
```
|
||||
Read ~/.mosaic/skills/<skill-name>/SKILL.md
|
||||
```
|
||||
|
||||
### Skill Dispatch Table — Load the right skills for your task
|
||||
|
||||
| Task Type | Skills to Load | Notes |
|
||||
|-----------|---------------|-------|
|
||||
| **NestJS development** | `nestjs-best-practices` | 40 rules, 10 categories |
|
||||
| **Next.js / React** | `next-best-practices`, `vercel-react-best-practices` | RSC, async, performance |
|
||||
| **React components** | `vercel-composition-patterns`, `shadcn-ui` | shadcn note: uses Tailwind v4 |
|
||||
| **Vue / Nuxt** | `vue-best-practices`, `nuxt`, `pinia`, `vue-router-best-practices` | antfu conventions |
|
||||
| **Vite / Vitest** | `vite`, `vitest` | Build + test tooling |
|
||||
| **FastAPI / Python** | `fastapi`, `python-performance-optimization` | Pydantic v2, async SQLAlchemy |
|
||||
| **Architecture** | `architecture-patterns` | Clean, Hexagonal, DDD |
|
||||
| **Authentication** | `better-auth-best-practices`, `email-and-password-best-practices`, `two-factor-authentication-best-practices` | Better-Auth patterns |
|
||||
| **UI / Styling** | `tailwind-design-system`, `ui-animation`, `web-design-guidelines` | Tailwind v4 |
|
||||
| **Frontend design** | `frontend-design`, `brand-guidelines`, `canvas-design` | Design principles |
|
||||
| **TDD / Testing** | `test-driven-development`, `webapp-testing`, `vue-testing-best-practices` | Red-Green-Refactor |
|
||||
| **Linting** | `lint` | Zero-tolerance — detect linter, fix ALL violations, never disable rules |
|
||||
| **Code review** | `pr-reviewer`, `code-review-excellence`, `verification-before-completion` | Platform-aware (Gitea/GitHub) |
|
||||
| **Debugging** | `systematic-debugging` | Structured methodology |
|
||||
| **Git workflow** | `finishing-a-development-branch`, `using-git-worktrees` | Branch + worktree patterns |
|
||||
| **Document generation** | `pdf`, `docx`, `pptx`, `xlsx` | LibreOffice-based |
|
||||
| **Writing / Comms** | `doc-coauthoring`, `internal-comms`, `copywriting`, `copy-editing` | |
|
||||
| **Marketing** | `marketing-ideas`, `content-strategy`, `social-content`, `email-sequence` | 139 ideas across 14 categories |
|
||||
| **SEO** | `seo-audit`, `programmatic-seo`, `schema-markup` | Technical + content SEO |
|
||||
| **CRO / Conversion** | `page-cro`, `form-cro`, `signup-flow-cro`, `onboarding-cro` | Conversion optimization |
|
||||
| **Pricing / Business** | `pricing-strategy`, `launch-strategy`, `competitor-alternatives` | SaaS focus |
|
||||
| **Ads / Growth** | `paid-ads`, `analytics-tracking`, `ab-test-setup`, `referral-program` | |
|
||||
| **Agent building** | `create-agent`, `ai-sdk`, `proactive-agent`, `dispatching-parallel-agents` | WAL Protocol, parallel workers |
|
||||
| **Agent workflow** | `executing-plans`, `writing-plans`, `brainstorming` | Plan → execute |
|
||||
| **Skill authoring** | `writing-skills`, `skill-creator` | TDD-based skill creation |
|
||||
| **MCP servers** | `mcp-builder` | Model Context Protocol |
|
||||
| **Generative art** | `algorithmic-art`, `theme-factory`, `slack-gif-creator` | |
|
||||
| **Web artifacts** | `web-artifacts-builder` | Self-contained HTML |
|
||||
| **CI/CD setup** | `setup-cicd` | Docker build/push pipeline |
|
||||
| **Jarvis Brain** | `jarvis` | Brain repo context |
|
||||
| **PRD creation** | `prd` | Generate PRDs |
|
||||
| **Ralph development** | `ralph` | Autonomous dev agent |
|
||||
| **Orchestration** | `kickstart` | `/kickstart [milestone\|issue\|task]` — launches orchestrator |
|
||||
|
||||
### For Orchestrator / Programmatic Workers
|
||||
|
||||
When spawning workers via `claude -p`, include skill loading in the kickstart:
|
||||
```bash
|
||||
claude -p "Read ~/.mosaic/skills/nestjs-best-practices/SKILL.md then implement..."
|
||||
```
|
||||
|
||||
For Ralph prd.json stories, add a `skills` field:
|
||||
```json
|
||||
{ "id": "US-001", "skills": ["nestjs-best-practices", "test-driven-development"], ... }
|
||||
```
|
||||
|
||||
### Fresh Machine Setup
|
||||
```bash
|
||||
npx skills add https://git.mosaicstack.dev/mosaic/agent-skills.git --agent claude-code
|
||||
```
|
||||
|
||||
## Ralph Autonomous Development
|
||||
|
||||
For autonomous feature development, use the Ralph pattern. Each iteration is a fresh context with persistent memory.
|
||||
|
||||
### The Ralph Loop
|
||||
```
|
||||
1. Read prd.json → Find highest priority story where passes: false
|
||||
2. Read progress.txt → Check "Codebase Patterns" section first
|
||||
3. Read AGENTS.md files → Check directory-specific patterns
|
||||
4. Implement ONLY the single assigned story
|
||||
5. Run quality checks (typecheck, lint, test)
|
||||
6. Commit ONLY if all checks pass
|
||||
7. Update prd.json → Set passes: true for completed story
|
||||
8. Append learnings to progress.txt
|
||||
9. Update AGENTS.md if reusable patterns discovered
|
||||
10. Loop → Next story
|
||||
```
|
||||
|
||||
### Memory Files
|
||||
| File | Purpose | Location |
|
||||
|------|---------|----------|
|
||||
| `prd.json` | Task list with passes: true/false | Project root or scripts/ralph/ |
|
||||
| `progress.txt` | Learnings between iterations | Same as prd.json |
|
||||
| `AGENTS.md` | Directory-specific patterns | Any directory in repo |
|
||||
|
||||
### Running Ralph
|
||||
```bash
|
||||
# Automated loop
|
||||
./scripts/ralph/ralph.sh 10
|
||||
|
||||
# Manual single story
|
||||
claude -p "Implement US-001 from prd.json following Ralph pattern"
|
||||
```
|
||||
|
||||
### Creating New Features
|
||||
1. Create PRD: `Load the prd skill and create a PRD for [feature]`
|
||||
2. Convert to Ralph: `Load the ralph skill and convert tasks/prd-[name].md to prd.json`
|
||||
3. Run Ralph: `./scripts/ralph/ralph.sh`
|
||||
|
||||
**For full Ralph guide:** `~/.mosaic/guides/ralph-autonomous.md`
|
||||
|
||||
## AGENTS.md Pattern
|
||||
|
||||
Each directory can have an `AGENTS.md` file containing patterns specific to that area of the codebase. **Always check for and read AGENTS.md files in directories you're working in.**
|
||||
|
||||
```markdown
|
||||
# Example AGENTS.md
|
||||
|
||||
## Codebase Patterns
|
||||
- Use `httpx.AsyncClient` for external HTTP calls
|
||||
- All routes require authentication via `Depends(get_current_user)`
|
||||
|
||||
## Common Gotchas
|
||||
- Remember to run migrations after schema changes
|
||||
- Frontend env vars need NEXT_PUBLIC_ prefix
|
||||
```
|
||||
|
||||
**Update AGENTS.md when you discover:**
|
||||
- Reusable patterns
|
||||
- Non-obvious requirements
|
||||
- Gotchas that would trip up future agents
|
||||
- Testing approaches for that area
|
||||
|
||||
## Project Bootstrapping
|
||||
|
||||
When starting work on a **new project** that lacks `CLAUDE.md` or `AGENTS.md`, bootstrap it:
|
||||
|
||||
```bash
|
||||
# Automated (recommended)
|
||||
~/.mosaic/rails/bootstrap/init-project.sh --name "Project Name" --type auto
|
||||
|
||||
# Or manually with templates
|
||||
export PROJECT_NAME="Project Name" PROJECT_DESCRIPTION="What it does" TASK_PREFIX="PN"
|
||||
envsubst < ~/.mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
|
||||
envsubst < ~/.mosaic/templates/agent/AGENTS.md.template > AGENTS.md
|
||||
```
|
||||
|
||||
**Available project types:** `nestjs-nextjs`, `django`, `typescript`, `python-fastapi`, `python-library`, `generic` (auto-detected from project files).
|
||||
|
||||
**Templates:** `~/.mosaic/templates/agent/` (generic) and `~/.mosaic/templates/agent/projects/<type>/` (tech-stack specific).
|
||||
|
||||
**Fragments:** `~/.mosaic/templates/agent/fragments/` — Reusable sections (conditional-loading, commit-format, secrets, multi-agent, code-review).
|
||||
|
||||
**Full guide:** `~/.mosaic/guides/bootstrap.md`
|
||||
|
||||
### Agent Configuration Health
|
||||
|
||||
```bash
|
||||
# Audit all projects for missing CLAUDE.md, AGENTS.md, agent-guide references
|
||||
~/.mosaic/rails/bootstrap/agent-lint.sh
|
||||
|
||||
# Audit with fix suggestions
|
||||
~/.mosaic/rails/bootstrap/agent-lint.sh --verbose --fix-hint
|
||||
|
||||
# Non-destructively upgrade existing projects (inject missing sections)
|
||||
~/.mosaic/rails/bootstrap/agent-upgrade.sh --all --dry-run # Preview
|
||||
~/.mosaic/rails/bootstrap/agent-upgrade.sh --all # Apply
|
||||
|
||||
# Upgrade a single project
|
||||
~/.mosaic/rails/bootstrap/agent-upgrade.sh ~/src/my-project
|
||||
```
|
||||
|
||||
**Spec:** `~/.mosaic/templates/agent/SPEC.md` — Defines Tier 1/2/3 requirements for well-configured projects.
|
||||
|
||||
## Issue Tracking (Git-Based)
|
||||
|
||||
All work is tracked as **issues in the project's git repository** (Gitea or GitHub).
|
||||
|
||||
### Workflow
|
||||
1. Check for assigned issues before starting work
|
||||
2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
|
||||
3. Reference issues in commits: `Fixes #123` or `Refs #123`
|
||||
4. Close issues only after successful testing
|
||||
|
||||
### Labels
|
||||
Use consistent labels across projects:
|
||||
- `epic` - Large feature spanning multiple issues
|
||||
- `feature` - New functionality
|
||||
- `bug` - Defect fix
|
||||
- `task` - General work item
|
||||
- `documentation` - Docs updates
|
||||
- `security` - Security-related
|
||||
- `breaking` - Breaking change
|
||||
|
||||
### Milestones & Versioning
|
||||
- **Each feature gets a dedicated milestone**
|
||||
- MVP starts at `0.1.0`
|
||||
- Pre-release: `0.X.0` for breaking changes, `0.X.Y` for patches
|
||||
- Post-release: `X.0.0` for breaking changes
|
||||
|
||||
### Git Scripts (PREFERRED for Gitea/GitHub operations)
|
||||
Cross-platform helpers at `~/.mosaic/rails/git/` (work with both Gitea and GitHub):
|
||||
|
||||
**Why use these scripts?**
|
||||
- ✅ Auto-detect platform (Gitea vs GitHub)
|
||||
- ✅ Abstract CLI syntax differences (tea vs gh)
|
||||
- ✅ Handle milestone name filtering for Gitea
|
||||
- ✅ Consistent interface across all repos
|
||||
|
||||
**Issues:**
|
||||
```bash
|
||||
~/.mosaic/rails/git/issue-create.sh -t "Title" -l "label" -m "0.2.0"
|
||||
~/.mosaic/rails/git/issue-list.sh -s open -l "bug"
|
||||
~/.mosaic/rails/git/issue-list.sh -m "M6-AgentOrchestration" # Works with milestone names!
|
||||
~/.mosaic/rails/git/issue-view.sh -i 42 # View issue details
|
||||
~/.mosaic/rails/git/issue-edit.sh -i 42 -t "New Title" -l "labels"
|
||||
~/.mosaic/rails/git/issue-assign.sh -i 42 -a "username"
|
||||
~/.mosaic/rails/git/issue-comment.sh -i 42 -c "Comment text"
|
||||
~/.mosaic/rails/git/issue-close.sh -i 42 [-c "Closing comment"]
|
||||
~/.mosaic/rails/git/issue-reopen.sh -i 42 [-c "Reopening reason"]
|
||||
```
|
||||
|
||||
**Pull Requests:**
|
||||
```bash
|
||||
~/.mosaic/rails/git/pr-create.sh -t "Title" -b "Description" -i 42
|
||||
~/.mosaic/rails/git/pr-create.sh -t "Title" -B main -H feature-branch
|
||||
~/.mosaic/rails/git/pr-list.sh -s open
|
||||
~/.mosaic/rails/git/pr-view.sh -n 42 # View PR details
|
||||
~/.mosaic/rails/git/pr-review.sh -n 42 -a approve [-c "LGTM"]
|
||||
~/.mosaic/rails/git/pr-review.sh -n 42 -a request-changes -c "Fix X"
|
||||
~/.mosaic/rails/git/pr-merge.sh -n 42 -m squash -d
|
||||
~/.mosaic/rails/git/pr-close.sh -n 42 [-c "Closing reason"]
|
||||
~/.mosaic/rails/git/pr-diff.sh -n 42 [-o diff.patch] # Get PR diff
|
||||
~/.mosaic/rails/git/pr-metadata.sh -n 42 [-o metadata.json] # Get PR metadata as JSON
|
||||
```
|
||||
|
||||
**Milestones:**
|
||||
```bash
|
||||
~/.mosaic/rails/git/milestone-create.sh -t "0.2.0" -d "Description"
|
||||
~/.mosaic/rails/git/milestone-create.sh --list
|
||||
~/.mosaic/rails/git/milestone-list.sh [-s open|closed|all]
|
||||
~/.mosaic/rails/git/milestone-close.sh -t "0.2.0"
|
||||
```
|
||||
|
||||
**NOTE:** These scripts handle the Gitea `--milestones` (plural) syntax automatically. Always prefer these over raw `tea` or `gh` commands.
|
||||
|
||||
### Woodpecker CI CLI
|
||||
Official CLI for interacting with Woodpecker CI at `ci.mosaicstack.dev`.
|
||||
|
||||
**Setup:**
|
||||
```bash
|
||||
# Install (Arch)
|
||||
paru -S woodpecker
|
||||
|
||||
# Configure
|
||||
export WOODPECKER_SERVER="https://ci.mosaicstack.dev"
|
||||
export WOODPECKER_TOKEN="your-token" # Get from ci.mosaicstack.dev/user
|
||||
```
|
||||
|
||||
**Pipelines:**
|
||||
```bash
|
||||
woodpecker pipeline ls <owner/repo> # List pipelines
|
||||
woodpecker pipeline info <owner/repo> <num> # Pipeline details
|
||||
woodpecker pipeline create <owner/repo> # Trigger pipeline
|
||||
woodpecker pipeline stop <owner/repo> <num> # Cancel pipeline
|
||||
woodpecker pipeline start <owner/repo> <num> # Restart pipeline
|
||||
woodpecker pipeline approve <owner/repo> <num> # Approve blocked
|
||||
```
|
||||
|
||||
**Logs:**
|
||||
```bash
|
||||
woodpecker log show <owner/repo> <num> # View logs
|
||||
woodpecker log show <owner/repo> <num> <step> # Specific step
|
||||
```
|
||||
|
||||
**Repositories:**
|
||||
```bash
|
||||
woodpecker repo ls # List repos
|
||||
woodpecker repo add <owner/repo> # Activate for CI
|
||||
woodpecker repo rm <owner/repo> # Deactivate
|
||||
woodpecker repo repair <owner/repo> # Repair webhooks
|
||||
```
|
||||
|
||||
**Secrets:**
|
||||
```bash
|
||||
woodpecker secret ls <owner/repo> # List secrets
|
||||
woodpecker secret add <owner/repo> -n KEY -v val # Add secret
|
||||
woodpecker secret rm <owner/repo> -n KEY # Delete secret
|
||||
```
|
||||
|
||||
**Full reference:** `jarvis-brain/docs/reference/woodpecker/WOODPECKER-CLI.md`
|
||||
**Setup command:** `woodpecker setup --server https://ci.mosaicstack.dev --token "YOUR_TOKEN"`
|
||||
|
||||
### Portainer Scripts
|
||||
CLI tools for managing Portainer stacks at `~/.mosaic/rails/portainer/`.
|
||||
|
||||
**Setup:**
|
||||
```bash
|
||||
export PORTAINER_URL="https://portainer.example.com:9443"
|
||||
export PORTAINER_API_KEY="your-api-key-here"
|
||||
```
|
||||
|
||||
Create an API key in Portainer: My account → Access tokens → Add access token.
|
||||
|
||||
**Stack Management:**
|
||||
```bash
|
||||
stack-list.sh # List all stacks
|
||||
stack-list.sh -f json # JSON format
|
||||
stack-list.sh -e 1 # Filter by endpoint
|
||||
|
||||
stack-status.sh -n mystack # Show stack status
|
||||
stack-status.sh -n mystack -f json # JSON format
|
||||
|
||||
stack-redeploy.sh -n mystack # Redeploy stack
|
||||
stack-redeploy.sh -n mystack -p # Pull latest images
|
||||
|
||||
stack-start.sh -n mystack # Start inactive stack
|
||||
stack-stop.sh -n mystack # Stop running stack
|
||||
```
|
||||
|
||||
**Logs:**
|
||||
```bash
|
||||
stack-logs.sh -n mystack # List services
|
||||
stack-logs.sh -n mystack -s webapp # View service logs
|
||||
stack-logs.sh -n mystack -s webapp -t 200 # Last 200 lines
|
||||
stack-logs.sh -n mystack -s webapp -f # Follow logs
|
||||
```
|
||||
|
||||
**Endpoints:**
|
||||
```bash
|
||||
endpoint-list.sh # List all endpoints
|
||||
endpoint-list.sh -f json # JSON format
|
||||
```
|
||||
|
||||
**Common Workflow (CI/CD redeploy):**
|
||||
```bash
|
||||
~/.mosaic/rails/portainer/stack-redeploy.sh -n myapp -p && \
|
||||
~/.mosaic/rails/portainer/stack-status.sh -n myapp && \
|
||||
~/.mosaic/rails/portainer/stack-logs.sh -n myapp -s api -t 50
|
||||
```
|
||||
|
||||
### Git Worktrees
|
||||
Use worktrees for parallel work on multiple issues without branch switching.
|
||||
|
||||
**Structure:**
|
||||
```
|
||||
{project_name}_worktrees/{issue-name}/
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```
|
||||
~/src/my-app/ # Main repository
|
||||
~/src/my-app_worktrees/
|
||||
├── 42-fix-login/ # Worktree for issue #42
|
||||
├── 57-add-dashboard/ # Worktree for issue #57
|
||||
└── 89-refactor-auth/ # Worktree for issue #89
|
||||
```
|
||||
|
||||
**Commands:**
|
||||
```bash
|
||||
# Create worktree for an issue
|
||||
git worktree add ../my-app_worktrees/42-fix-login -b issue-42-fix-login
|
||||
|
||||
# List active worktrees
|
||||
git worktree list
|
||||
|
||||
# Remove worktree after merge
|
||||
git worktree remove ../my-app_worktrees/42-fix-login
|
||||
```
|
||||
|
||||
**When to use worktrees:**
|
||||
- Working on multiple issues simultaneously
|
||||
- Long-running feature branches that need isolation
|
||||
- Code reviews while continuing other work
|
||||
- Comparing implementations across branches
|
||||
|
||||
## Development Requirements
|
||||
|
||||
### Test-Driven Development (TDD)
|
||||
1. Write tests BEFORE implementation
|
||||
2. Minimum **85% coverage**
|
||||
3. Build and test after EVERY change
|
||||
4. Task completion requires passing tests
|
||||
|
||||
### Linting (MANDATORY)
|
||||
**Run the project linter after every code change. Fix ALL violations. Zero tolerance.**
|
||||
- Never disable lint rules (`eslint-disable`, `noqa`, `nolint`)
|
||||
- Never leave warnings — warnings are errors you haven't fixed yet
|
||||
- If you touched a file, you own its lint violations (Campsite Rule)
|
||||
- If unsure what linter the project uses, read the `lint` skill: `~/.mosaic/skills/lint/SKILL.md`
|
||||
|
||||
### Code Style
|
||||
Follow [Google Style Guides](https://github.com/google/styleguide) for all languages.
|
||||
|
||||
### Commits
|
||||
```
|
||||
<type>(#issue): Brief description
|
||||
|
||||
Detailed explanation if needed.
|
||||
|
||||
Fixes #123
|
||||
```
|
||||
Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
|
||||
|
||||
## Scratchpad Format
|
||||
|
||||
When working on issue #N, create `docs/scratchpads/N-short-name.md`:
|
||||
|
||||
```markdown
|
||||
# Issue #N: Title
|
||||
|
||||
## Objective
|
||||
[What this issue accomplishes]
|
||||
|
||||
## Approach
|
||||
[Implementation plan]
|
||||
|
||||
## Progress
|
||||
- [ ] Step 1
|
||||
- [ ] Step 2
|
||||
|
||||
## Testing
|
||||
[Test plan and results]
|
||||
|
||||
## Notes
|
||||
[Findings, blockers, decisions]
|
||||
```
|
||||
|
||||
## Conditional Context
|
||||
|
||||
**Read the relevant guide before starting work:**
|
||||
|
||||
| Task Type | Guide |
|
||||
|-----------|-------|
|
||||
| Bootstrapping a new project | `~/.mosaic/guides/bootstrap.md` |
|
||||
| Orchestrating autonomous task completion | `~/.mosaic/guides/orchestrator.md` |
|
||||
| Ralph autonomous development | `~/.mosaic/guides/ralph-autonomous.md` |
|
||||
| Frontend development | `~/.mosaic/guides/frontend.md` |
|
||||
| Backend/API development | `~/.mosaic/guides/backend.md` |
|
||||
| Code review | `~/.mosaic/guides/code-review.md` |
|
||||
| Authentication/Authorization | `~/.mosaic/guides/authentication.md` |
|
||||
| CI/CD pipelines & Docker builds | `~/.mosaic/guides/ci-cd-pipelines.md` |
|
||||
| Infrastructure/DevOps | `~/.mosaic/guides/infrastructure.md` |
|
||||
| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
|
||||
| Secrets management | See section below |
|
||||
|
||||
**Project-specific skills:**
|
||||
|
||||
| Project | Skill |
|
||||
|---------|-------|
|
||||
| jetrich/jarvis | `~/.mosaic/skills/jarvis/SKILL.md` |
|
||||
|
||||
## Secrets Management
|
||||
|
||||
**NEVER hardcode secrets in the codebase.** Choose the appropriate method based on your environment.
|
||||
|
||||
### If Using Vault
|
||||
See `~/.mosaic/guides/vault-secrets.md` for the canonical structure and rules.
|
||||
|
||||
Quick reference:
|
||||
```
|
||||
{mount}/{service}/{component}/{secret-name}
|
||||
Example: secret-prod/postgres/database/app
|
||||
```
|
||||
|
||||
### If NOT Using Vault (Use .env Files)
|
||||
|
||||
**Structure:**
|
||||
```
|
||||
project-root/
|
||||
├── .env.example # Template with placeholder values (committed)
|
||||
├── .env # Local secrets (NEVER committed)
|
||||
├── .env.development # Dev overrides (optional, not committed)
|
||||
├── .env.test # Test environment (optional, not committed)
|
||||
└── .gitignore # Must include .env*
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
1. **ALWAYS** add `.env*` to `.gitignore` (except `.env.example`)
|
||||
2. Create `.env.example` with all required variables and placeholder values
|
||||
3. Use descriptive variable names: `DATABASE_URL`, `API_SECRET_KEY`
|
||||
4. Document required variables in README
|
||||
5. Load via `dotenv` or framework-native methods
|
||||
|
||||
**.env.example template:**
|
||||
```bash
|
||||
# Database
|
||||
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
|
||||
DATABASE_POOL_SIZE=10
|
||||
|
||||
# Authentication
|
||||
JWT_SECRET_KEY=your-secret-key-here
|
||||
JWT_EXPIRY_SECONDS=3600
|
||||
|
||||
# External APIs
|
||||
STRIPE_API_KEY=sk_test_xxx
|
||||
SENDGRID_API_KEY=SG.xxx
|
||||
|
||||
# App Config
|
||||
APP_ENV=development
|
||||
DEBUG=false
|
||||
```
|
||||
|
||||
**Loading secrets:**
|
||||
```python
|
||||
# Python
|
||||
from dotenv import load_dotenv
|
||||
load_dotenv()
|
||||
|
||||
# Node.js
|
||||
import 'dotenv/config';
|
||||
|
||||
# Or use framework-native (Next.js, NestJS, etc.)
|
||||
```
|
||||
|
||||
### Security Rules (All Environments)
|
||||
1. **Never commit secrets** - Use .env or Vault
|
||||
2. **Never log secrets** - Mask in logs if needed
|
||||
3. **Rotate compromised secrets immediately**
|
||||
4. **Use different secrets per environment**
|
||||
5. **Validate secrets exist at startup** - Fail fast if missing
|
||||
|
||||
## Multi-Agent Coordination
|
||||
|
||||
When launching concurrent agents:
|
||||
```bash
|
||||
nohup claude -p "<instruction>" > logs/agent-{name}.log 2>&1 &
|
||||
```
|
||||
|
||||
- Maximum 10 simultaneous agents
|
||||
- Monitor for errors and permission issues
|
||||
- Add required permissions to `.claude/settings.json` → `allowedCommands`
|
||||
- Restart failed agents after fixing issues
|
||||
|
||||
**For Ralph multi-agent:**
|
||||
- Use worktrees for isolation
|
||||
- Each agent works on different story
|
||||
- Coordinate via git (frequent pulls)
|
||||
|
||||
## Dev Server Infrastructure (web1.corp.uscllc.local)
|
||||
|
||||
### Shared Traefik Reverse Proxy
|
||||
|
||||
A shared Traefik instance handles routing for all dev/test services on this server.
|
||||
|
||||
**Location:** `~/src/traefik`
|
||||
|
||||
**Start Traefik:**
|
||||
```bash
|
||||
cd ~/src/traefik
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
**Dashboard:** http://localhost:8080
|
||||
|
||||
### Connecting Services to Traefik
|
||||
|
||||
Add to your service's `docker-compose.yml`:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
app:
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.myapp.rule=Host(`myapp.uscllc.com`)"
|
||||
- "traefik.http.routers.myapp.entrypoints=websecure"
|
||||
- "traefik.http.routers.myapp.tls=true"
|
||||
- "traefik.http.services.myapp.loadbalancer.server.port=3000"
|
||||
networks:
|
||||
- internal
|
||||
- traefik-public
|
||||
|
||||
networks:
|
||||
internal:
|
||||
driver: bridge
|
||||
traefik-public:
|
||||
external: true
|
||||
```
|
||||
|
||||
**Note:** Uses self-signed wildcard cert - browsers will show security warning.
|
||||
|
||||
### Active Dev Services
|
||||
|
||||
| Service | Domain | Repository |
|
||||
|---------|--------|------------|
|
||||
| Inventory Stickers | inventory.uscllc.com | ~/src/sticker-app |
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
project-root/
|
||||
├── AGENTS.md # Codebase patterns for AI agents
|
||||
├── docs/
|
||||
│ └── scratchpads/ # Agent working documents
|
||||
│ └── {issue#}-{name}.md
|
||||
├── scripts/
|
||||
│ └── ralph/ # Ralph autonomous development
|
||||
│ ├── ralph.sh # Loop script
|
||||
│ ├── prd.json # Current feature tasks
|
||||
│ └── progress.txt # Memory between iterations
|
||||
├── tasks/ # PRD documents
|
||||
│ └── prd-{feature}.md
|
||||
├── logs/ # Log files
|
||||
└── tests/ # Test files
|
||||
```
|
||||
294
runtime/claude/context7-integration.md
Normal file
294
runtime/claude/context7-integration.md
Normal file
@@ -0,0 +1,294 @@
|
||||
# Context7 Integration for Atomic Code Implementer
|
||||
|
||||
## Overview
|
||||
|
||||
The atomic-code-implementer agent uses Context7 MCP server to dynamically fetch up-to-date documentation for libraries and frameworks. This integration provides real-time access to the latest API documentation, best practices, and code examples.
|
||||
|
||||
## Integration Points
|
||||
|
||||
### 1. Preset-Driven Documentation Lookup
|
||||
|
||||
Each preset configuration includes a `context7Libraries` array that specifies which libraries to fetch documentation for:
|
||||
|
||||
```json
|
||||
{
|
||||
"context7Libraries": [
|
||||
"@nestjs/common",
|
||||
"@nestjs/core",
|
||||
"@nestjs/typeorm",
|
||||
"typeorm",
|
||||
"class-validator"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
When a preset is loaded, the agent automatically resolves and fetches documentation for all specified libraries.
|
||||
|
||||
### 2. Error-Driven Documentation Lookup
|
||||
|
||||
When build errors, type errors, or runtime issues occur, the agent can automatically lookup documentation for:
|
||||
|
||||
- Error resolution patterns
|
||||
- API migration guides
|
||||
- Breaking change documentation
|
||||
- Best practice guidelines
|
||||
|
||||
### 3. Implementation-Driven Lookup
|
||||
|
||||
During atomic task implementation, the agent can fetch:
|
||||
|
||||
- Framework-specific implementation patterns
|
||||
- Library-specific configuration examples
|
||||
- Performance optimization techniques
|
||||
- Security best practices
|
||||
|
||||
## Context7 Usage Patterns
|
||||
|
||||
### Library Resolution
|
||||
|
||||
```javascript
|
||||
// Resolve library ID from preset configuration
|
||||
const libraryId = await mcp__context7__resolve_library_id({
|
||||
libraryName: "@nestjs/common"
|
||||
});
|
||||
```
|
||||
|
||||
### Documentation Retrieval
|
||||
|
||||
```javascript
|
||||
// Get comprehensive documentation
|
||||
const docs = await mcp__context7__get_library_docs({
|
||||
context7CompatibleLibraryID: "/nestjs/nest",
|
||||
topic: "controllers",
|
||||
tokens: 8000
|
||||
});
|
||||
```
|
||||
|
||||
### Error-Specific Lookups
|
||||
|
||||
```javascript
|
||||
// Look up specific error patterns
|
||||
const errorDocs = await mcp__context7__get_library_docs({
|
||||
context7CompatibleLibraryID: "/typescript/typescript",
|
||||
topic: "type errors",
|
||||
tokens: 5000
|
||||
});
|
||||
```
|
||||
|
||||
## Automatic Lookup Triggers
|
||||
|
||||
### 1. Preset Loading Phase
|
||||
When an atomic task is started:
|
||||
1. Detect tech stack from file extensions
|
||||
2. Load appropriate preset configuration
|
||||
3. Extract `context7Libraries` array
|
||||
4. Resolve all library IDs
|
||||
5. Fetch relevant documentation based on task context
|
||||
|
||||
### 2. Error Detection Phase
|
||||
When quality hooks detect issues:
|
||||
1. Parse error messages for library/framework references
|
||||
2. Resolve documentation for problematic libraries
|
||||
3. Look up error-specific resolution patterns
|
||||
4. Apply common fixes based on documentation
|
||||
|
||||
### 3. Implementation Phase
|
||||
During code implementation:
|
||||
1. Detect new library imports or API usage
|
||||
2. Automatically fetch documentation for unknown patterns
|
||||
3. Provide implementation examples and best practices
|
||||
4. Validate against latest API specifications
|
||||
|
||||
## Context7 Library Mappings
|
||||
|
||||
### NestJS Backend
|
||||
```json
|
||||
{
|
||||
"@nestjs/common": "/nestjs/nest",
|
||||
"@nestjs/typeorm": "/nestjs/typeorm",
|
||||
"typeorm": "/typeorm/typeorm",
|
||||
"class-validator": "/typestack/class-validator",
|
||||
"bcrypt": "/kelektiv/node.bcrypt.js"
|
||||
}
|
||||
```
|
||||
|
||||
### React Frontend
|
||||
```json
|
||||
{
|
||||
"react": "/facebook/react",
|
||||
"react-dom": "/facebook/react",
|
||||
"@tanstack/react-query": "/tanstack/query",
|
||||
"tailwindcss": "/tailwindlabs/tailwindcss",
|
||||
"@testing-library/react": "/testing-library/react-testing-library"
|
||||
}
|
||||
```
|
||||
|
||||
### Python FastAPI
|
||||
```json
|
||||
{
|
||||
"fastapi": "/tiangolo/fastapi",
|
||||
"sqlalchemy": "/sqlalchemy/sqlalchemy",
|
||||
"pydantic": "/samuelcolvin/pydantic",
|
||||
"pytest": "/pytest-dev/pytest"
|
||||
}
|
||||
```
|
||||
|
||||
## Integration Workflow
|
||||
|
||||
### Sequential Thinking Enhanced Lookup
|
||||
|
||||
```markdown
|
||||
1. **Preset Analysis Phase**
|
||||
- Use sequential thinking to determine optimal documentation needs
|
||||
- Analyze task requirements for specific library features
|
||||
- Prioritize documentation lookup based on complexity
|
||||
|
||||
2. **Dynamic Documentation Loading**
|
||||
- Load core framework documentation first
|
||||
- Fetch specialized library docs based on task specifics
|
||||
- Cache documentation for session reuse
|
||||
|
||||
3. **Implementation Guidance**
|
||||
- Use retrieved docs to guide implementation decisions
|
||||
- Apply documented best practices and patterns
|
||||
- Validate implementation against official examples
|
||||
```
|
||||
|
||||
### Error Resolution Workflow
|
||||
|
||||
```markdown
|
||||
1. **Error Detection**
|
||||
- Parse error messages for library/API references
|
||||
- Identify deprecated or changed APIs
|
||||
- Extract relevant context from error stack traces
|
||||
|
||||
2. **Documentation Lookup**
|
||||
- Resolve library documentation for error context
|
||||
- Fetch migration guides for breaking changes
|
||||
- Look up troubleshooting and FAQ sections
|
||||
|
||||
3. **Automated Remediation**
|
||||
- Apply documented fixes and workarounds
|
||||
- Update code to use current APIs
|
||||
- Add proper error handling based on docs
|
||||
```
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
### Preset Configuration with Context7
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "NestJS HIPAA Healthcare",
|
||||
"techStack": {
|
||||
"framework": "NestJS",
|
||||
"database": "TypeORM + PostgreSQL"
|
||||
},
|
||||
"context7Libraries": [
|
||||
"@nestjs/common",
|
||||
"@nestjs/typeorm",
|
||||
"typeorm",
|
||||
"bcrypt",
|
||||
"helmet"
|
||||
],
|
||||
"context7Topics": {
|
||||
"security": ["authentication", "authorization", "encryption"],
|
||||
"database": ["migrations", "relationships", "transactions"],
|
||||
"testing": ["unit tests", "integration tests", "mocking"]
|
||||
},
|
||||
"context7AutoLookup": {
|
||||
"onError": true,
|
||||
"onImport": true,
|
||||
"onDeprecation": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Agent Integration Points
|
||||
|
||||
```markdown
|
||||
## Context7 Integration in atomic-code-implementer.md
|
||||
|
||||
### Phase 1: Preset Loading
|
||||
```javascript
|
||||
// Load preset and resolve documentation
|
||||
const preset = loadPreset(detectedTechStack, domainContext);
|
||||
const libraryDocs = await loadContext7Documentation(preset.context7Libraries);
|
||||
```
|
||||
|
||||
### Phase 2: Implementation Guidance
|
||||
```javascript
|
||||
// Get implementation examples during coding
|
||||
const implementationDocs = await mcp__context7__get_library_docs({
|
||||
context7CompatibleLibraryID: "/nestjs/nest",
|
||||
topic: "controllers authentication",
|
||||
tokens: 6000
|
||||
});
|
||||
```
|
||||
|
||||
### Phase 3: Error Resolution
|
||||
```javascript
|
||||
// Look up error-specific documentation
|
||||
if (buildError.includes("TypeError: Cannot read property")) {
|
||||
const errorDocs = await mcp__context7__get_library_docs({
|
||||
context7CompatibleLibraryID: extractLibraryFromError(buildError),
|
||||
topic: "common errors troubleshooting",
|
||||
tokens: 4000
|
||||
});
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Documentation Caching
|
||||
- Cache resolved library IDs for session duration
|
||||
- Store frequently accessed documentation locally
|
||||
- Implement intelligent cache invalidation
|
||||
|
||||
### 2. Context-Aware Lookups
|
||||
- Tailor documentation queries to specific atomic task context
|
||||
- Use targeted topics rather than generic documentation
|
||||
- Prioritize relevant sections based on implementation needs
|
||||
|
||||
### 3. Error-Driven Learning
|
||||
- Maintain error pattern → documentation mapping
|
||||
- Learn from successful error resolutions
|
||||
- Build knowledge base of common issues and solutions
|
||||
|
||||
### 4. Performance Optimization
|
||||
- Batch documentation requests when possible
|
||||
- Use appropriate token limits for different use cases
|
||||
- Implement request deduplication
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Library Not Found**
|
||||
```javascript
|
||||
// Fallback to generic search
|
||||
const fallbackId = await mcp__context7__resolve_library_id({
|
||||
libraryName: `${libraryName} documentation`
|
||||
});
|
||||
```
|
||||
|
||||
2. **Documentation Too Generic**
|
||||
```javascript
|
||||
// Use more specific topics
|
||||
const specificDocs = await mcp__context7__get_library_docs({
|
||||
context7CompatibleLibraryID: libraryId,
|
||||
topic: `${specificFeature} implementation examples`,
|
||||
tokens: 8000
|
||||
});
|
||||
```
|
||||
|
||||
3. **Rate Limiting**
|
||||
```javascript
|
||||
// Implement exponential backoff
|
||||
const docs = await retryWithBackoff(() =>
|
||||
mcp__context7__get_library_docs(params)
|
||||
);
|
||||
```
|
||||
|
||||
This integration ensures the atomic code implementer always has access to the most current and relevant documentation, enabling it to produce high-quality, up-to-date implementations while following current best practices.
|
||||
288
runtime/claude/hooks-config.json
Normal file
288
runtime/claude/hooks-config.json
Normal file
@@ -0,0 +1,288 @@
|
||||
{
|
||||
"name": "Universal Atomic Code Implementer Hooks",
|
||||
"description": "Comprehensive hooks configuration for quality enforcement and automatic remediation",
|
||||
"version": "1.0.0",
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit|MultiEdit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "bash",
|
||||
"args": [
|
||||
"-c",
|
||||
"echo '[HOOK] Universal quality enforcement for $FILE_PATH'; if [[ \"$FILE_PATH\" == *.ts || \"$FILE_PATH\" == *.tsx ]]; then echo '[HOOK] TypeScript checks'; npx eslint --fix \"$FILE_PATH\" && npx prettier --write \"$FILE_PATH\" && npx tsc --noEmit || echo '[HOOK] TS completed'; elif [[ \"$FILE_PATH\" == *.js || \"$FILE_PATH\" == *.jsx ]]; then echo '[HOOK] JavaScript checks'; npx eslint --fix \"$FILE_PATH\" && npx prettier --write \"$FILE_PATH\" || echo '[HOOK] JS completed'; elif [[ \"$FILE_PATH\" == *.py ]]; then echo '[HOOK] Python checks'; black \"$FILE_PATH\" && flake8 \"$FILE_PATH\" && mypy \"$FILE_PATH\" || echo '[HOOK] Python completed'; fi"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"fileTypeHooks": {
|
||||
"*.ts": {
|
||||
"afterChange": [
|
||||
"echo '[HOOK] TypeScript file modified: ${FILE_PATH}'",
|
||||
"npx eslint --fix ${FILE_PATH}",
|
||||
"npx prettier --write ${FILE_PATH}",
|
||||
"npx tsc --noEmit --project tsconfig.json"
|
||||
],
|
||||
"beforeDelete": [
|
||||
"echo '[HOOK] Checking for TypeScript file dependencies before deletion'"
|
||||
]
|
||||
},
|
||||
"*.tsx": {
|
||||
"afterChange": [
|
||||
"echo '[HOOK] React TypeScript file modified: ${FILE_PATH}'",
|
||||
"npx eslint --fix ${FILE_PATH}",
|
||||
"npx prettier --write ${FILE_PATH}",
|
||||
"npx tsc --noEmit --project tsconfig.json",
|
||||
"if command -v npm >/dev/null 2>&1; then",
|
||||
" npm run test:component -- ${FILE_NAME} 2>/dev/null || echo '[HOOK] Component tests checked'",
|
||||
"fi"
|
||||
]
|
||||
},
|
||||
"*.js": {
|
||||
"afterChange": [
|
||||
"echo '[HOOK] JavaScript file modified: ${FILE_PATH}'",
|
||||
"npx eslint --fix ${FILE_PATH}",
|
||||
"npx prettier --write ${FILE_PATH}"
|
||||
]
|
||||
},
|
||||
"*.jsx": {
|
||||
"afterChange": [
|
||||
"echo '[HOOK] React JavaScript file modified: ${FILE_PATH}'",
|
||||
"npx eslint --fix ${FILE_PATH}",
|
||||
"npx prettier --write ${FILE_PATH}",
|
||||
"if command -v npm >/dev/null 2>&1; then",
|
||||
" npm run test:component -- ${FILE_NAME} 2>/dev/null || echo '[HOOK] Component tests checked'",
|
||||
"fi"
|
||||
]
|
||||
},
|
||||
"*.py": {
|
||||
"afterChange": [
|
||||
"echo '[HOOK] Python file modified: ${FILE_PATH}'",
|
||||
"black ${FILE_PATH}",
|
||||
"flake8 ${FILE_PATH} || echo '[HOOK] Flake8 linting completed'",
|
||||
"mypy ${FILE_PATH} || echo '[HOOK] MyPy type checking completed'",
|
||||
"if command -v pytest >/dev/null 2>&1; then",
|
||||
" pytest ${FILE_PATH%.*}_test.py 2>/dev/null || echo '[HOOK] Python tests checked'",
|
||||
"fi"
|
||||
]
|
||||
},
|
||||
"package.json": {
|
||||
"afterChange": [
|
||||
"echo '[HOOK] package.json modified, updating dependencies'",
|
||||
"npm install --no-audit --no-fund || echo '[HOOK] Dependency update completed'"
|
||||
]
|
||||
},
|
||||
"requirements.txt": {
|
||||
"afterChange": [
|
||||
"echo '[HOOK] requirements.txt modified, updating Python dependencies'",
|
||||
"pip install -r requirements.txt || echo '[HOOK] Python dependency update completed'"
|
||||
]
|
||||
},
|
||||
"*.json": {
|
||||
"afterChange": [
|
||||
"echo '[HOOK] JSON file modified: ${FILE_PATH}'",
|
||||
"if command -v jq >/dev/null 2>&1; then",
|
||||
" jq . ${FILE_PATH} > /dev/null || echo '[HOOK] JSON validation failed'",
|
||||
"fi"
|
||||
]
|
||||
},
|
||||
"*.md": {
|
||||
"afterChange": [
|
||||
"echo '[HOOK] Markdown file modified: ${FILE_PATH}'",
|
||||
"if command -v prettier >/dev/null 2>&1; then",
|
||||
" npx prettier --write ${FILE_PATH} || echo '[HOOK] Markdown formatting completed'",
|
||||
"fi"
|
||||
]
|
||||
}
|
||||
},
|
||||
"remediationActions": {
|
||||
"RETRY_OPERATION": {
|
||||
"description": "Retry the last file operation after applying fixes",
|
||||
"maxRetries": 2,
|
||||
"backoffMs": 1000
|
||||
},
|
||||
"CONTINUE_WITH_WARNING": {
|
||||
"description": "Continue execution but log warnings for manual review",
|
||||
"logLevel": "warning"
|
||||
},
|
||||
"ABORT_WITH_ERROR": {
|
||||
"description": "Stop execution and require manual intervention",
|
||||
"logLevel": "error"
|
||||
},
|
||||
"TRIGGER_QA_AGENT": {
|
||||
"description": "Escalate to QA validation agent for complex issues",
|
||||
"agent": "qa-validation-agent"
|
||||
},
|
||||
"REQUEST_CONTEXT7_HELP": {
|
||||
"description": "Look up documentation for error resolution",
|
||||
"tool": "mcp__context7__get-library-docs"
|
||||
}
|
||||
},
|
||||
"qualityGates": {
|
||||
"typescript": {
|
||||
"eslint": {
|
||||
"enabled": true,
|
||||
"config": ".eslintrc.js",
|
||||
"autoFix": true,
|
||||
"failOnError": false
|
||||
},
|
||||
"prettier": {
|
||||
"enabled": true,
|
||||
"config": ".prettierrc",
|
||||
"autoFix": true
|
||||
},
|
||||
"typeCheck": {
|
||||
"enabled": true,
|
||||
"config": "tsconfig.json",
|
||||
"failOnError": false
|
||||
},
|
||||
"testing": {
|
||||
"enabled": true,
|
||||
"runAffected": true,
|
||||
"coverage": 80
|
||||
}
|
||||
},
|
||||
"python": {
|
||||
"black": {
|
||||
"enabled": true,
|
||||
"lineLength": 88,
|
||||
"autoFix": true
|
||||
},
|
||||
"flake8": {
|
||||
"enabled": true,
|
||||
"config": ".flake8",
|
||||
"failOnError": false
|
||||
},
|
||||
"mypy": {
|
||||
"enabled": true,
|
||||
"config": "mypy.ini",
|
||||
"failOnError": false
|
||||
},
|
||||
"pytest": {
|
||||
"enabled": true,
|
||||
"coverage": 90
|
||||
}
|
||||
},
|
||||
"javascript": {
|
||||
"eslint": {
|
||||
"enabled": true,
|
||||
"autoFix": true
|
||||
},
|
||||
"prettier": {
|
||||
"enabled": true,
|
||||
"autoFix": true
|
||||
}
|
||||
}
|
||||
},
|
||||
"performanceOptimization": {
|
||||
"parallelExecution": {
|
||||
"enabled": true,
|
||||
"maxConcurrency": 4
|
||||
},
|
||||
"caching": {
|
||||
"enabled": true,
|
||||
"eslint": true,
|
||||
"prettier": true,
|
||||
"typescript": true
|
||||
},
|
||||
"incrementalChecks": {
|
||||
"enabled": true,
|
||||
"onlyModifiedFiles": true
|
||||
}
|
||||
},
|
||||
"monitoring": {
|
||||
"metrics": {
|
||||
"hookExecutionTime": true,
|
||||
"errorRates": true,
|
||||
"remediationSuccess": true
|
||||
},
|
||||
"logging": {
|
||||
"level": "info",
|
||||
"format": "json",
|
||||
"includeStackTrace": true
|
||||
},
|
||||
"alerts": {
|
||||
"highErrorRate": {
|
||||
"threshold": 0.1,
|
||||
"action": "log"
|
||||
},
|
||||
"slowHookExecution": {
|
||||
"thresholdMs": 10000,
|
||||
"action": "log"
|
||||
}
|
||||
}
|
||||
},
|
||||
"integration": {
|
||||
"presets": {
|
||||
"loadHooksFromPresets": true,
|
||||
"overrideWithProjectConfig": true
|
||||
},
|
||||
"cicd": {
|
||||
"skipInCI": false,
|
||||
"reportToCI": true
|
||||
},
|
||||
"ide": {
|
||||
"vscode": {
|
||||
"showNotifications": true,
|
||||
"autoSave": false
|
||||
}
|
||||
}
|
||||
},
|
||||
"customCommands": {
|
||||
"fullQualityCheck": {
|
||||
"description": "Run comprehensive quality checks",
|
||||
"commands": [
|
||||
"npm run lint",
|
||||
"npm run format",
|
||||
"npm run build",
|
||||
"npm run test",
|
||||
"npm run type-check"
|
||||
]
|
||||
},
|
||||
"securityScan": {
|
||||
"description": "Run security scanning",
|
||||
"commands": [
|
||||
"npm audit",
|
||||
"npx eslint . --ext .ts,.tsx,.js,.jsx --config .eslintrc.security.js || echo 'Security scan completed'"
|
||||
]
|
||||
},
|
||||
"performanceCheck": {
|
||||
"description": "Run performance analysis",
|
||||
"commands": [
|
||||
"npm run build:analyze || echo 'Bundle analysis completed'",
|
||||
"npm run lighthouse || echo 'Lighthouse audit completed'"
|
||||
]
|
||||
}
|
||||
},
|
||||
"documentation": {
|
||||
"usage": "This configuration provides comprehensive quality enforcement through hooks",
|
||||
"examples": [
|
||||
{
|
||||
"scenario": "TypeScript file creation",
|
||||
"flow": "Write file → ESLint auto-fix → Prettier format → TypeScript check → Tests"
|
||||
},
|
||||
{
|
||||
"scenario": "Python file modification",
|
||||
"flow": "Edit file → Black format → Flake8 lint → MyPy type check → Pytest"
|
||||
},
|
||||
{
|
||||
"scenario": "Build error",
|
||||
"flow": "Error detected → Analyze common issues → Apply fixes → Retry or continue"
|
||||
}
|
||||
],
|
||||
"troubleshooting": [
|
||||
{
|
||||
"issue": "Hooks taking too long",
|
||||
"solution": "Enable parallelExecution and incremental checks"
|
||||
},
|
||||
{
|
||||
"issue": "False positive errors",
|
||||
"solution": "Adjust quality gate thresholds or use CONTINUE_WITH_WARNING"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
228
runtime/claude/settings.json
Normal file
228
runtime/claude/settings.json
Normal file
@@ -0,0 +1,228 @@
|
||||
{
|
||||
"model": "opus",
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Edit|MultiEdit|Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "~/.mosaic/rails/qa/qa-hook-stdin.sh",
|
||||
"timeout": 60
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"enabledPlugins": {
|
||||
"frontend-design@claude-plugins-official": true,
|
||||
"feature-dev@claude-plugins-official": true,
|
||||
"code-review@claude-plugins-official": true,
|
||||
"pr-review-toolkit@claude-plugins-official": true
|
||||
},
|
||||
"skipDangerousModePermissionPrompt": true,
|
||||
"allowedCommands": [
|
||||
"npm",
|
||||
"npm install",
|
||||
"npm run",
|
||||
"npm test",
|
||||
"npm build",
|
||||
"npm start",
|
||||
"npm run dev",
|
||||
"npm run build",
|
||||
"npm run lint",
|
||||
"npm run typecheck",
|
||||
"npm run test:ci",
|
||||
"npm run test:e2e",
|
||||
"npm run test:unit",
|
||||
"npm run test:integration",
|
||||
"npm run test:cov",
|
||||
"npm run test:security",
|
||||
"npm run security:scan",
|
||||
"npm run security:audit",
|
||||
"npm run performance:benchmark",
|
||||
"npm run build:dev",
|
||||
"npm run build:prod",
|
||||
"npm run test",
|
||||
"npm run test:watch",
|
||||
"npm run migrate",
|
||||
"npm run migrate:rollback",
|
||||
"npm run db:seed",
|
||||
"npm run db:reset",
|
||||
"node",
|
||||
"yarn",
|
||||
"pnpm",
|
||||
"npx",
|
||||
"npx tsc",
|
||||
"npx eslint",
|
||||
"npx prettier",
|
||||
"npx jest",
|
||||
"npx vitest",
|
||||
"git",
|
||||
"git add",
|
||||
"git commit",
|
||||
"git push",
|
||||
"git pull",
|
||||
"git status",
|
||||
"git diff",
|
||||
"git log",
|
||||
"git branch",
|
||||
"git checkout",
|
||||
"git merge",
|
||||
"git init",
|
||||
"git remote",
|
||||
"git fetch",
|
||||
"git reset",
|
||||
"git rebase",
|
||||
"git stash",
|
||||
"git tag",
|
||||
"git show",
|
||||
"git config",
|
||||
"gh",
|
||||
"gh issue",
|
||||
"gh pr",
|
||||
"gh repo",
|
||||
"gh api",
|
||||
"docker",
|
||||
"docker build",
|
||||
"docker run",
|
||||
"docker ps",
|
||||
"docker logs",
|
||||
"docker exec",
|
||||
"docker stop",
|
||||
"docker start",
|
||||
"docker pull",
|
||||
"docker push",
|
||||
"docker-compose",
|
||||
"docker-compose up",
|
||||
"docker-compose down",
|
||||
"docker-compose build",
|
||||
"docker-compose logs",
|
||||
"docker-compose ps",
|
||||
"docker-compose exec",
|
||||
"kubectl",
|
||||
"kubectl get",
|
||||
"kubectl describe",
|
||||
"kubectl logs",
|
||||
"kubectl apply",
|
||||
"kubectl delete",
|
||||
"kubectl port-forward",
|
||||
"mkdir",
|
||||
"touch",
|
||||
"chmod",
|
||||
"chown",
|
||||
"ls",
|
||||
"cd",
|
||||
"pwd",
|
||||
"cp",
|
||||
"mv",
|
||||
"rm",
|
||||
"cat",
|
||||
"echo",
|
||||
"head",
|
||||
"tail",
|
||||
"grep",
|
||||
"grep -E",
|
||||
"grep -r",
|
||||
"find",
|
||||
"find -name",
|
||||
"find -type",
|
||||
"find -path",
|
||||
"find -exec",
|
||||
"find . -type f",
|
||||
"find . -type d",
|
||||
"wc",
|
||||
"sort",
|
||||
"uniq",
|
||||
"curl",
|
||||
"wget",
|
||||
"ping",
|
||||
"netstat",
|
||||
"ss",
|
||||
"lsof",
|
||||
"psql",
|
||||
"pg_dump",
|
||||
"pg_restore",
|
||||
"sqlite3",
|
||||
"jest",
|
||||
"vitest",
|
||||
"playwright",
|
||||
"cypress",
|
||||
"artillery",
|
||||
"lighthouse",
|
||||
"tsc",
|
||||
"eslint",
|
||||
"prettier",
|
||||
"snyk",
|
||||
"semgrep",
|
||||
"tar",
|
||||
"gzip",
|
||||
"unzip",
|
||||
"zip",
|
||||
"which",
|
||||
"whoami",
|
||||
"id",
|
||||
"env",
|
||||
"export",
|
||||
"source",
|
||||
"sleep",
|
||||
"date",
|
||||
"uptime",
|
||||
"df",
|
||||
"du",
|
||||
"free",
|
||||
"top",
|
||||
"htop",
|
||||
"ps",
|
||||
"tree",
|
||||
"jq",
|
||||
"sed",
|
||||
"awk",
|
||||
"xargs",
|
||||
"tee",
|
||||
"test",
|
||||
"true",
|
||||
"false",
|
||||
"basename",
|
||||
"dirname",
|
||||
"realpath",
|
||||
"readlink",
|
||||
"stat",
|
||||
"file",
|
||||
"make",
|
||||
"cmake",
|
||||
"gcc",
|
||||
"g++",
|
||||
"clang",
|
||||
"python",
|
||||
"python3",
|
||||
"pip",
|
||||
"pip3",
|
||||
"pip install",
|
||||
"poetry",
|
||||
"pipenv",
|
||||
"go",
|
||||
"go build",
|
||||
"go test",
|
||||
"go run",
|
||||
"go mod",
|
||||
"cargo",
|
||||
"rustc",
|
||||
"ruby",
|
||||
"gem",
|
||||
"bundle",
|
||||
"rake",
|
||||
"java",
|
||||
"javac",
|
||||
"mvn",
|
||||
"gradle",
|
||||
"dotnet",
|
||||
"msbuild",
|
||||
"php",
|
||||
"composer",
|
||||
"perl",
|
||||
"cpan",
|
||||
"nohup"
|
||||
],
|
||||
"enableAllMcpTools": true
|
||||
}
|
||||
Reference in New Issue
Block a user