Advanced Claude Code setup with intelligent orchestration, cross-session learning, and AI-optimized workflows
This repository contains a production-grade configuration for Claude Code with multi-agent orchestration, semantic memory, automation scripts, and 32 domain-specific skills.
A comprehensive .claude configuration that transforms Claude Code into an intelligent development partner with:
- Smart Orchestration: Three-tier command system (
/solo,/spec,/conduct) for tasks of any complexity - Cross-Session Learning: PRISM semantic memory system that remembers patterns and decisions
- 32 Domain Skills: Pre-loaded expertise (Python, Git, testing, DevOps, API design, etc.)
- Automation Scripts: GitLab/Jira integration without token-heavy MCP servers (97.7% token savings)
- Quality Gates: Multi-agent validation (security, performance, code quality) on every build
- Hook System: Event-driven automation for formatting, validation, and learning
Token Efficiency: Scripts save 119,550 tokens per PR review workflow vs. MCP servers (99.6% reduction)
-
Clone into your home directory:
cd ~ git clone <your-repo-url> .claude
-
Set up credentials:
# GitLab credentials (optional, for GitLab scripts) cp ~/.claude/scripts/.gitlab-credentials.example ~/.claude/scripts/.gitlab-credentials # Edit with your token: vim ~/.claude/scripts/.gitlab-credentials # Jira credentials (optional, for Jira scripts) cp ~/.claude/scripts/.jira-credentials.example ~/.claude/scripts/.jira-credentials # Edit with your token: vim ~/.claude/scripts/.jira-credentials
-
Configure settings (already tracked):
- Settings are in
~/.claude/settings.json - Hooks enabled by default (auto-format on Edit/Write)
- Custom status line configured
- Output style:
daily_driver(witty, direct)
- Settings are in
-
Start using orchestration commands:
# In any project directory /solo add rate limiting to API endpoint /spec design real-time event processing system /pr_review INT-1234
Choose the right command for your task complexity:
| Command | When to Use | Prerequisites | Token Budget |
|---|---|---|---|
/solo |
Simple tasks, 1-3 files, clear requirements | None | 10-20k |
/spec |
Need investigation, architecture unclear | None | 15-30k |
/conduct |
Complex multi-component features | SPEC.md from /spec | 50k+ |
/pr_review |
Review merge request against Jira ticket | Jira ticket ID | 30-60k |
/update_docs |
Update all docs to match current code | None | 20-40k |
/coda |
End session with summary and handoff | None | 5-10k |
User Task
│
▼
┌───────────────┐
│ Is it clear │
│ what to do? │
└───────┬───────┘
│
┌───────────┴───────────┐
│ │
YES NO
│ │
▼ ▼
┌───────────────┐ ┌──────────────┐
│ Simple task? │ │ Need to │
│ (1-3 files) │ │ investigate? │
└───────┬───────┘ └──────┬───────┘
│ │
┌───────┴──────┐ │
│ │ ▼
YES NO ┌─────────┐
│ │ │ /spec │──┐
▼ ▼ └─────────┘ │
┌────────┐ ┌──────────┐ │
│ /solo │ │ /conduct │ │
└────────┘ └──────────┘ │
│ ▲ │
│ │ │
└──────────────┴──────────────────────┘
│
▼
┌─────────┐
│ Done │
└─────────┘
Special Cases:
PR Review? ──→ /pr_review
Update Docs? ──→ /update_docs
Session End? ──→ /coda
Best for: Straightforward tasks with clear scope
/solo add rate limiting middleware
/solo fix authentication bug in login endpoint
/solo implement CSV export for reportsWhat it does:
- Creates minimal spec (
.spec/BUILD_*.md) - Implements via specialized agents
- Validates with 6 reviewers (security, performance, code quality)
- Runs tests (if requested)
- Merges learnings into permanent docs
- Cleans up
.spec/
Validation Loop: Fix → Validate → Repeat (max 3 attempts, 95%+ test coverage)
┌─────────────────────────────────────────────────────────────┐
│ /solo Command │
└─────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────┐
│ Load agent-prompting │
│ skill (MANDATORY) │
└───────────┬───────────┘
│
▼
┌───────────────────────┐
│ Generate minimal spec │
│ .spec/BUILD_*.md │
└───────────┬───────────┘
│
▼
┌───────────────────────┐
│ Spawn implementation │
│ & test agents │
└───────────┬───────────┘
│
▼
┌───────────────────────────────────────┐
│ Validation Loop │
│ ┌─────────────────────────────────┐ │
│ │ Run linting (ruff/pyright) │ │
│ └─────────────┬───────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────┐ │
│ │ Spawn 6 reviewers in parallel: │ │
│ │ • Security │ │
│ │ • Performance │ │
│ │ • Code Quality (3x) │ │
│ │ • Style │ │
│ └─────────────┬───────────────────┘ │
│ ▼ │
│ ┌─────────────┐ │
│ │ Issues? │ │
│ └──────┬──────┘ │
│ │ │
│ ┌─────────┴─────────┐ │
│ YES NO │
│ │ │ │
│ ▼ │ │
│ ┌────────────┐ │ │
│ │ Spawn fix- │ │ │
│ │ executor │ │ │
│ └─────┬──────┘ │ │
│ │ │ │
│ └──────────────────┘ │
│ (Repeat max 3 times) │
└───────────────────────────────────────┘
│
▼
┌───────────────────────┐
│ Run tests (pytest) │
│ Coverage: 95%+ │
└───────────┬───────────┘
│
▼
┌───────────────────────┐
│ Merge learnings into │
│ permanent docs │
└───────────┬───────────┘
│
▼
┌───────────────────────┐
│ Cleanup .spec/ │
└───────────┬───────────┘
│
▼
┌───────┐
│ Done │
└───────┘
Best for: Complex features needing investigation
/spec design event-driven architecture with gRPC
/spec investigate options for real-time notificationsWhat it does:
- Assessment: Asks 3-5 clarifying questions
- Investigation: Auto-reads existing code
- Challenge Mode: Identifies ≥3 concerns/risks
- Spike Testing: Validates approaches in
/tmp/spike_* - Spec Creation: Writes
SPEC.mdwith 10 required sections - Component Breakdown: Creates phase specs (
SPEC_1_*.md, etc.)
Output: .spec/SPEC.md ready for /conduct
┌─────────────────────────────────────────────────────────────┐
│ /spec Command │
└─────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────┐
│ Initial Assessment │
│ Ask 3-5 questions │
└───────────┬───────────┘
│
▼
┌───────────────────────┐
│ Auto-Investigation │
│ Read existing code │
│ Understand context │
└───────────┬───────────┘
│
▼
┌───────────────────────┐
│ Challenge Mode │
│ Find ≥3 concerns: │
│ • Performance risks │
│ • Security issues │
│ • Integration points │
│ • Complexity traps │
└───────────┬───────────┘
│
▼
┌───────────────────────────────────────┐
│ Spike Testing Phase │
│ ┌─────────────────────────────────┐ │
│ │ For each approach option: │ │
│ │ │ │
│ │ 1. Create /tmp/spike_NAME/ │ │
│ │ 2. Write throwaway code │ │
│ │ 3. Run & validate │ │
│ │ 4. Document exact commands │ │
│ │ 5. Capture gotchas + recovery │ │
│ └─────────────────────────────────┘ │
│ │
│ Test in parallel: │
│ • gRPC spike │
│ • Database spike │
│ • UI integration spike │
└───────────────────────────────────────┘
│
▼
┌───────────────────────┐
│ Create SPEC.md with: │
│ • Overview │
│ • User Stories │
│ • Acceptance Criteria │
│ • Technical Design │
│ • API Contracts │
│ • Data Models │
│ • Dependencies │
│ • Testing Strategy │
│ • Rollout Plan │
│ • Spike Findings │
└───────────┬───────────┘
│
▼
┌───────────────────────┐
│ Create Component │
│ Phase Specs: │
│ • SPEC_1_auth.md │
│ • SPEC_2_api.md │
│ • SPEC_3_db.md │
└───────────┬───────────┘
│
▼
┌───────────────────────┐
│ Ready for /conduct │
└───────────────────────┘
Best for: Implementing complex features from SPEC.md
/conduct # Requires .spec/SPEC.md from /specWhat it does:
- Parses SPEC.md → extracts components + dependencies
- Builds dependency graph → topological sort
- For each component (in dependency order):
- Skeleton → Implementation → Validate → Test → Document → Checkpoint
- Integration testing across all components
- Final documentation validation
- Cleanup
.spec/
Key Features:
- Dependency-aware execution (no broken imports)
- Per-component validation (catch issues early)
- Parallel agent execution where possible
- Checkpoints after each component
┌─────────────────────────────────────────────────────────────┐
│ /conduct Command │
│ (Requires .spec/SPEC.md) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────┐
│ Parse SPEC.md │
│ Extract components │
│ Extract dependencies │
└───────────┬───────────┘
│
▼
┌───────────────────────┐
│ Build dependency │
│ graph │
│ Topological sort │
└───────────┬───────────┘
│
▼
┌───────────────────────────────────────┐
│ For Each Component (in order) │
│ │
│ ┌─────────────────────────────────┐ │
│ │ 1. Skeleton Phase │ │
│ │ • Create file structure │ │
│ │ • Define interfaces │ │
│ │ • Add NotImplementedError │ │
│ └──────────────┬──────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────┐ │
│ │ 2. Implementation Phase │ │
│ │ • Fill in logic │ │
│ │ • Working code (no TODOs) │ │
│ └──────────────┬──────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────┐ │
│ │ 3. Validation Phase │ │
│ │ • Run linting │ │
│ │ • Spawn 6 reviewers │ │
│ │ • Fix issues (max 3 loops) │ │
│ └──────────────┬──────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────┐ │
│ │ 4. Testing Phase │ │
│ │ • Write tests (95%+ cov) │ │
│ │ • Run tests │ │
│ │ • Fix failures │ │
│ └──────────────┬──────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────┐ │
│ │ 5. Documentation Phase │ │
│ │ • Update CLAUDE.md │ │
│ │ • Update README │ │
│ └──────────────┬──────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────┐ │
│ │ 6. Checkpoint │ │
│ │ • Git commit │ │
│ │ • Mark complete │ │
│ └─────────────────────────────────┘ │
│ │
│ Next component has access to │
│ working APIs from previous phases │
└───────────────────────────────────────┘
│
▼
┌───────────────────────┐
│ Integration Testing │
│ All components │
│ together │
└───────────┬───────────┘
│
▼
┌───────────────────────┐
│ Final Documentation │
│ Validation │
└───────────┬───────────┘
│
▼
┌───────────────────────┐
│ Cleanup .spec/ │
└───────────┬───────────┘
│
▼
┌───────┐
│ Done │
└───────┘
Best for: Reviewing merge requests against Jira requirements
/pr_review INT-3877
/pr_review PLAT-54What it does:
- Fetches full Jira ticket context (description, acceptance criteria, developer checklist, test plan, comments, related tickets)
- Fetches all MR comments (resolved/unresolved)
- Spawns 8 specialized reviewers in parallel:
- Requirements compliance
- Security (OWASP Top 10)
- Performance (N+1 queries, inefficiencies)
- Code quality (patterns, maintainability)
- Tests (coverage, edge cases)
- Breaking changes
- Database impacts
- Integration impacts
- 7-layer voting system (eliminates false positives)
- Outputs structured markdown report with severity levels
Token Savings: Uses lightweight scripts instead of MCP (119,550 tokens saved per review)
┌─────────────────────────────────────────────────────────────┐
│ /pr_review <TICKET_ID> │
└─────────────────────────────────────────────────────────────┘
│
┌───────────────┴───────────────┐
│ │
▼ ▼
┌───────────────────────┐ ┌───────────────────────┐
│ jira-get-issue │ │ gitlab-mr-comments │
│ Fetch FULL context: │ │ Fetch ALL comments: │
│ • Description │ │ • Resolved │
│ • Acceptance Criteria │ │ • Unresolved │
│ • Developer Checklist │ │ • Inline comments │
│ • Test Plan │ └───────────┬───────────┘
│ • ALL Comments │ │
│ • Related Tickets │ │
└───────────┬───────────┘ │
│ │
└───────────────┬───────────────┘
│
▼
┌───────────────────────────────────────┐
│ Spawn 8 Reviewers in Parallel │
│ │
│ ┌─────────────────────────────────┐ │
│ │ 1. Requirements Reviewer │ │
│ │ • Matches acceptance criteria│ │
│ │ • Fulfills user stories │ │
│ └─────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────┐ │
│ │ 2. Security Reviewer │ │
│ │ • OWASP Top 10 check │ │
│ │ • SQL injection, XSS, etc. │ │
│ └─────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────┐ │
│ │ 3. Performance Reviewer │ │
│ │ • N+1 queries │ │
│ │ • Inefficient algorithms │ │
│ └─────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────┐ │
│ │ 4. Code Quality Reviewer │ │
│ │ • Patterns, maintainability │ │
│ └─────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────┐ │
│ │ 5. Test Reviewer │ │
│ │ • Coverage, edge cases │ │
│ └─────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────┐ │
│ │ 6. Breaking Changes Reviewer │ │
│ │ • API changes, deprecations │ │
│ └─────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────┐ │
│ │ 7. Database Reviewer │ │
│ │ • Schema changes, migrations │ │
│ └─────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────┐ │
│ │ 8. Integration Reviewer │ │
│ │ • Service boundaries │ │
│ └─────────────────────────────────┘ │
└───────────────────────────────────────┘
│
▼
┌───────────────────────────────────────┐
│ 7-Layer Voting System │
│ (Eliminates false positives) │
│ │
│ Each finding must pass: │
│ 1. Evidence exists in code │
│ 2. Severity justified │
│ 3. Not a false positive │
│ 4. Actionable recommendation │
│ 5. Aligned with ticket requirements │
│ 6. Not already addressed in comments │
│ 7. Actually matters for this PR │
└───────────────────────────────────────┘
│
▼
┌───────────────────────┐
│ Generate Markdown │
│ Report: │
│ • Summary │
│ • High severity │
│ • Medium severity │
│ • Low severity │
│ • Positive findings │
└───────────┬───────────┘
│
▼
┌───────┐
│ Done │
└───────┘
Best for: Keeping docs aligned with code
/update_docsWhat it does:
- Spawns multiple documentation-writer agents in parallel
- Updates CLAUDE.md, README.md, QUICKREF.md, skills
- Validates accuracy against actual code
- Follows AI documentation best practices (tables over prose, concise, scannable)
Skills are AI expertise modules that load automatically based on task context. No manual invocation needed.
| Category | Skills | Use When |
|---|---|---|
| Python (6) | python-style, python-linting, python-packaging, async-python, testing-standards, debugging-strategies | Writing/debugging Python code |
| Git & Workflows (3) | git-workflows, test-driven-development, code-review-patterns | Git operations, TDD, PR reviews |
| DevOps (3) | ci-cd-pipelines, docker-optimization, kubernetes-patterns | CI/CD setup, containerization |
| API & Database (3) | api-design-patterns, database-design-patterns, mongodb-aggregation-optimization | API design, schema design |
| Quality (4) | code-refactoring, mutation-testing, vulnerability-triage, performance-profiling | Code quality, security, performance |
| Automation (4) | gitlab-scripts, jira-scripts, mcp-integration, orchestration-workflow | GitLab/Jira automation |
| Meta (3) | agent-prompting, ai-documentation, skill-authoring | Creating docs, skills, agents |
| Frontend (1) | frontend-patterns | React/Vue/TypeScript |
- Automatic Discovery: Claude loads skills based on their descriptions when relevant
- Progressive Disclosure: Core patterns in SKILL.md, details in reference.md
- Token Efficient: ~30-50 tokens until fully loaded
- Composable: Skills work together (see
~/.claude/skills/README.mdfor synergies)
Skills load automatically when you work on relevant tasks:
# Writing Python code → Loads: python-style, python-linting
# Writing tests → Loads: testing-standards, test-driven-development
# PR review → Loads: code-review-patterns, gitlab-scripts, jira-scripts
# Spawning agents → Loads: agent-prompting (MANDATORY before sub-agents)See skills/README.md for complete skill catalog and synergies.
Lightweight bash scripts that replace token-heavy MCP servers.
| Tool | Functions | Tokens | Scripts | Script Tokens | Savings |
|---|---|---|---|---|---|
| GitLab MCP | 82 | 80,000 | 6 | ~1,000 | 98.75% |
| Jira MCP | 30 | 40,000 | 7 | ~1,750 | 95.6% |
| Combined | 112 | 120,000 | 13 | ~2,750 | 97.7% |
Located in ~/.claude/scripts/:
gitlab-mr-comments- Fetch all MR discussions (formatted markdown)gitlab-list-mrs- List merge requests with filtersgitlab-create-mr- Create new merge requestgitlab-comment-mr- Add MR commentgitlab-update-mr- Update MR metadata (title, description, labels)gitlab-inline-comment- Add inline code review commentsgit-worktree- Smart worktree manager for parallel development
jira-get-issue- Fetch comprehensive ticket context (description, acceptance criteria, developer checklist, test plan, ALL comments, related ticket details)jira-list-tickets- List tickets with filtersjira-list-sprint- Show current sprintjira-create-ticket- Create new ticketjira-comment-ticket- Add commentjira-update-ticket- Update ticket fieldsjira-log-work- Log time (supports2h 30m,1d 4hformat)jira-link-tickets- Link tickets with relationships
# GitLab
cp ~/.claude/scripts/.gitlab-credentials.example ~/.claude/scripts/.gitlab-credentials
vim ~/.claude/scripts/.gitlab-credentials
# Add: GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_API_URL, GITLAB_PROJECT_ID
# Jira
cp ~/.claude/scripts/.jira-credentials.example ~/.claude/scripts/.jira-credentials
vim ~/.claude/scripts/.jira-credentials
# Add: ATLASSIAN_API_TOKEN, ATLASSIAN_SITE_NAME, ATLASSIAN_USER_EMAILSee scripts/README.md for complete documentation.
Event-driven automation that runs at specific points in the workflow.
PostToolUse Hooks (in settings.json):
- Edit/MultiEdit/Write →
auto-format.sh- Runs
ruff formaton Python files - Runs
prettieron JS/TS files - Auto-formats on every code change
- Runs
PreCommit Hook (Git):
hooks/pre-commit-validation.sh- Validates code against anti-patterns
- Checks security patterns
- Blocks commits with issues
Hooks in ~/.claude/hooks/:
auto-format.sh- Auto-formatting for Python/JS/TSpre-commit-validation.sh- Git pre-commit quality gatespatterns/- Pattern definitions (anti-patterns, security, complexity)archive/- Deprecated hooks (PRISM integration, old validators)transcript_parsing/- Session analysis tools
Reusable formats for specs, reviews, and documentation.
Located in ~/.claude/templates/:
spec-minimal.md- For/solo(BUILD spec)spec-full.md- For/conduct(SPEC.md with 10 sections)
pr-review-requirements.md- Requirements compliancepr-review-security.md- OWASP Top 10 security reviewpr-review-performance.md- Performance analysispr-review-code-analysis.md- Code quality patternspr-review-tests.md- Test coverage and qualitypr-review-ripple-*.md- Breaking changes, DB impacts, integration impactspr-review-verification.md- Evidence-based verification
operational.md- Algorithms (fix-validate loops, dependency resolution)agent-responses.md- Structured agent output formats (NO prose)
INVARIANTS.md- Project invariants documentationGOTCHAS_TEMPLATE.md- Gotcha documentation pattern
~/.claude/
├── CLAUDE.md # Core work contract (principles, quality gates)
├── README.md # This file (human documentation)
├── settings.json # Claude Code settings (hooks, output style)
│
├── commands/ # Slash commands (orchestration)
│ ├── solo.md # /solo - streamlined implementation
│ ├── spec.md # /spec - discovery & planning
│ ├── conduct.md # /conduct - multi-component orchestration
│ ├── pr_review.md # /pr_review - comprehensive PR review
│ ├── update_docs.md # /update_docs - documentation sync
│ └── coda.md # /coda - session summary
│
├── skills/ # 32 domain skills (auto-loaded)
│ ├── README.md # Skill catalog and synergies
│ ├── python-style/ # Python coding standards
│ ├── python-linting/ # Ruff/pyright usage
│ ├── testing-standards/ # Test organization (3-layer pyramid)
│ ├── agent-prompting/ # Sub-agent delegation (MANDATORY)
│ ├── git-workflows/ # Advanced Git (rebase, bisect, worktrees)
│ ├── gitlab-scripts/ # GitLab automation
│ ├── jira-scripts/ # Jira integration
│ └── [27 more skills...]
│
├── scripts/ # Automation scripts (GitLab/Jira)
│ ├── README.md # Script documentation
│ ├── gitlab-mr-comments # Fetch MR comments
│ ├── gitlab-inline-comment # Add inline code review
│ ├── jira-get-issue # Fetch full ticket context
│ ├── [10 more scripts...]
│ ├── .gitlab-credentials # GitLab API credentials (gitignored)
│ └── .jira-credentials # Jira API credentials (gitignored)
│
├── hooks/ # Event-driven automation
│ ├── auto-format.sh # Auto-format on Edit/Write
│ ├── pre-commit-validation.sh # Git pre-commit quality gates
│ └── patterns/ # Pattern definitions
│
├── templates/ # Reusable formats
│ ├── spec-*.md # Spec templates (minimal/full)
│ ├── pr-review-*.md # Review templates (8 reviewers)
│ ├── operational.md # Algorithms
│ └── agent-responses.md # Structured outputs
│
├── docs/ # Core documentation
│ ├── OVERVIEW.md # System architecture (this file context)
│ ├── ORCHESTRATION_GUIDE.md # Command decision tree
│ ├── TESTING_STANDARDS.md # Test requirements (95% coverage)
│ ├── AI_DOCUMENTATION_STANDARDS.md
│ ├── MCP_SETUP_INSTRUCTIONS.md
│ └── llms.txt # Documentation index for AI
│
├── orchestration/ # Orchestration instructions
│ ├── SPEC_INSTRUCTIONS.md # Discovery phase (for /spec)
│ ├── CONDUCT_INSTRUCTIONS.md # Execution phase (for /conduct)
│ └── ORCHESTRATOR_PATTERN.md # General orchestration principles
│
├── configs/ # Language tool configs (fallbacks)
│ ├── ruff.toml # Python linting
│ ├── .prettierrc # JS/TS formatting
│ └── .golangci.yml # Go linting
│
├── .claude/settings.local.json # Local Claude Code settings
├── statusline-command.sh # Custom status line
└── [session data...] # History, todos, debug logs
{
"hooks": {
"PostToolUse": [
{ "matcher": "Edit", "hooks": [{ "command": "~/.claude/hooks/auto-format.sh" }] },
{ "matcher": "Write", "hooks": [{ "command": "~/.claude/hooks/auto-format.sh" }] }
]
},
"statusLine": { "command": "~/.claude/statusline-command.sh" },
"outputStyle": "daily_driver",
"alwaysThinkingEnabled": true,
"permissions": { "defaultMode": "bypassPermissions" }
}Core principles that override default behavior:
- RUN HOT: Use full 200K token budget for thorough work
- NO PARTIAL WORK: Full implementation or explain why blocked
- FAIL LOUD: Errors surface with clear messages (never silent failures)
- QUALITY GATES: Tests + linting pass before claiming done
- MULTIEDIT FOR SAME FILE: Avoid parallel Edit race conditions
- NO MASS UPDATES: Use sub-agents, not scripts (manual = eyes on each change)
See CLAUDE.md for complete work contract.
Create CLAUDE.md in any project root to override global settings:
cd ~/my-project
cat > CLAUDE.md <<EOF
# Project-Specific Rules
## Override Global Settings
- Use 100 char line length (not 80)
- Use Jest (not pytest)
- Never use TypeScript `any` type
## Project Context
- Monorepo with 15 packages
- Nx build system
- GraphQL + REST hybrid API
EOFCross-session learning system that remembers patterns and decisions.
- Stores semantic code changes (added_error_handling, bug_fix, refactoring)
- Captures agent discoveries (patterns, decisions, gotchas)
- Detects user preferences (repeated corrections → enforced rules)
- Injects relevant context into prompts and agent launches
- Promotes patterns across tiers (WORKING → LONGTERM → ANCHORS)
- ANCHORS: Critical rules (violations block execution)
- LONGTERM: Stable patterns (3+ uses or 85%+ confidence)
- WORKING: Session-specific (cleared between sessions)
- EPISODIC: Recent events (time-based decay)
PRISM requires separate MCP server setup:
# Clone PRISM MCP
git clone <prism-mcp-repo> ~/repos/claude_mcp/prism_mcp
# Start PRISM services (Redis, Neo4j, Qdrant)
cd ~/repos/claude_mcp/prism_mcp
nerdctl compose up -d
# Verify PRISM running
curl http://localhost:8090/healthSee docs/MCP_SETUP_INSTRUCTIONS.md for complete setup.
Note: PRISM is optional. All orchestration commands work without it.
Configured in settings.json: "outputStyle": "daily_driver"
Personality: Witty companion who gets shit done
- Brutally honest and direct
- Casual tone with humor
- Concise explanations (no fluff)
- No code snippets (describes what code does verbally)
- Validates before claiming things work
Example Output:
Found 47 TODO comments from 2019. Someone was optimistic.
Spawning 6 reviewers in parallel. Code review by committee, but they can't argue.
This variable is called `data2_final_ACTUAL_final`. I have questions.
This configuration follows AI documentation best practices:
- Concise over comprehensive (agents can read code)
- Structure over prose (tables/bullets over paragraphs)
- Location over explanation (file:line references)
- Hierarchical CLAUDE.md (100-200 line rule, no duplication)
- CLAUDE.md - Core patterns and rules (100-200 lines)
- OVERVIEW.md - System architecture and navigation
- QUICKREF.md - Deep-dive examples and code snippets
- BUSINESS_RULES.md - Authoritative business logic catalog
- llms.txt - Documentation index for AI agents
See docs/AI_DOCUMENTATION_STANDARDS.md for complete guide.
┌─────────────────────────────────────────────────────────────────┐
│ Claude Code Orchestration │
│ (Multi-Agent Architecture) │
└─────────────────────────────────────────────────────────────────┘
User Request
│
▼
┌─────────────────────────────────────┐
│ Main Orchestrator (Sonnet 4.5) │
│ • Analyzes task complexity │
│ • Chooses orchestration command │
│ • Loads agent-prompting skill │
│ • Delegates to specialized agents │
└───────────────┬─────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ /solo │ │ /spec │ │ /conduct │
│ │ │ │ │ │
│ • 1-3 files │ │ • Discovery │ │ • Multi- │
│ • Clear req │ │ • Spike test │ │ component │
│ • Standard │ │ • Create │ │ • Dependency │
│ patterns │ │ SPEC.md │ │ aware │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
│ └────────┬────────┘
│ │
▼ ▼
┌──────────────────────────────────────────┐
│ Specialized Agents (Parallel) │
│ │
│ ┌────────────────────────────────────┐ │
│ │ Implementation Agents │ │
│ │ • skeleton-builder │ │
│ │ • implementation-executor │ │
│ │ • test-implementer │ │
│ └────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────┐ │
│ │ Validation Agents (6 in parallel) │ │
│ │ • security-auditor │ │
│ │ • performance-optimizer │ │
│ │ • code-reviewer (3x) │ │
│ └────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────┐ │
│ │ Utility Agents │ │
│ │ • fix-executor (for failures) │ │
│ │ • spike-tester (validation) │ │
│ │ • documentation-writer │ │
│ └────────────────────────────────────┘ │
└──────────────────┬───────────────────────┘
│
▼
┌──────────────────────┐
│ Quality Gates │
│ │
│ • Linting: ruff │
│ • Type check: pyright│
│ • Tests: 95%+ cov │
│ • Security: OWASP │
│ • Performance: N+1 │
└──────────┬───────────┘
│
┌──────┴──────┐
│ │
PASS FAIL
│ │
│ ▼
│ ┌──────────────┐
│ │ fix-executor │
│ │ (max 3 loops)│
│ └──────┬───────┘
│ │
└───────────┘
│
▼
┌──────────────────────┐
│ Documentation │
│ • Update CLAUDE.md │
│ • Update README │
│ • Update skills │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Cleanup & Commit │
│ • Remove .spec/ │
│ • Git commit │
│ • Claude co-author │
└──────────┬───────────┘
│
▼
┌────────┐
│ Done │
└────────┘
Parallel Execution Example:
┌──────────────────────────────────────────────────────────────┐
│ Main Orchestrator sends single message with 6 Task calls: │
│ │
│ Task(security-auditor, ...) ────┐ │
│ Task(performance-optimizer, ...)│ All execute │
│ Task(code-reviewer, ...)────────┤ simultaneously │
│ Task(code-reviewer, ...)────────┤ (token efficient) │
│ Task(code-reviewer, ...)────────┤ │
│ Task(style-reviewer, ...) ──────┘ │
│ │
│ Results aggregated → single validation report │
└──────────────────────────────────────────────────────────────┘
/solo add rate limiting middleware to API
# What happens:
# 1. Creates .spec/BUILD_rate-limit.md (minimal spec)
# 2. Spawns implementation-executor agent
# 3. Spawns test-implementer agent
# 4. Validates with 6 reviewers (security, performance, code quality)
# 5. Runs pytest with coverage (95%+ required)
# 6. Merges learnings into permanent docs
# 7. Cleans up .spec//spec design event-driven system with gRPC
# Discovery phase:
# 1. Asks clarifying questions
# 2. Investigates existing code
# 3. Identifies concerns/risks
# 4. Spike tests approaches in /tmp
# 5. Creates .spec/SPEC.md
/conduct
# Execution phase:
# 1. Parses SPEC.md → dependency graph
# 2. Implements components in order
# 3. Per-component validation
# 4. Integration testing
# 5. Final documentation/pr_review INT-3877
# What happens:
# 1. Fetches full Jira context (ticket + related tickets + comments)
# 2. Fetches all MR comments
# 3. Spawns 8 reviewers in parallel
# 4. Applies 7-layer voting system (eliminates false positives)
# 5. Outputs structured markdown report/update_docs
# What happens:
# 1. Spawns parallel documentation-writer agents
# 2. Updates CLAUDE.md, README.md, skills
# 3. Validates against actual code
# 4. Follows AI documentation standards# Check hook configuration
cat ~/.claude/settings.json | jq '.hooks'
# Check hook permissions
ls -la ~/.claude/hooks/*.sh
# Test hook manually
~/.claude/hooks/auto-format.sh Edit test.py# Missing credentials
# Error: "❌ Credentials file not found"
cp ~/.claude/scripts/.gitlab-credentials.example ~/.claude/scripts/.gitlab-credentials
vim ~/.claude/scripts/.gitlab-credentials
# Test script
~/.claude/scripts/gitlab-mr-comments INT-3877
echo $? # Should be 0# Check progress
cat .spec/PROGRESS.md
# Check agent output
# Look for ESCALATE or BLOCKED messages in response# Verify PRISM running
curl http://localhost:8090/health
# Restart PRISM
cd ~/repos/claude_mcp/prism_mcp
nerdctl compose restart-
For Users:
docs/ORCHESTRATION_GUIDE.md- Command decision treeskills/README.md- Skill catalog and synergiesscripts/README.md- Script documentationdocs/TESTING_STANDARDS.md- Test requirements
-
For AI Agents:
docs/OVERVIEW.md- System architecturedocs/llms.txt- Documentation indexorchestration/- Orchestration instructionstemplates/- Spec and response formats
-
For Developers:
docs/AI_DOCUMENTATION_STANDARDS.md- Writing AI-friendly docsdocs/MCP_SETUP_INSTRUCTIONS.md- MCP server setuphooks/HOOKS_IDEAS.md- Hook development ideas
cd ~/.claude/skills
mkdir my-new-skill
cd my-new-skill
cat > SKILL.md <<EOF
---
name: my-new-skill
description: Brief description (includes "Use when...")
---
# My New Skill
[Skill content following skill-authoring guidelines]
EOFSee skill-authoring skill for complete guidelines.
cd ~/.claude/scripts
# Use template from scripts/README.md
# Follow exit code conventions: 0=success, 1=args, 2=not found, 3=API error, 4=credsEdit command files in ~/.claude/commands/:
solo.md- Streamlined implementationspec.md- Discovery & planningconduct.md- Multi-component orchestration
Token Efficiency:
- Scripts vs MCP: 97.7% token savings (120,000 → 2,750 tokens)
- PR Review workflow: 119,550 tokens saved per review
Quality Gates:
- 6 parallel reviewers: security, performance, code quality (3x), style, docs
- 7-layer voting system eliminates false positives
- 95%+ test coverage required
- Zero linting errors before completion
Productivity:
/solo: 10-20k tokens, 5-15 min for simple features/spec+/conduct: 50k+ tokens, 30-60 min for complex features/pr_review: 30-60k tokens, 10-20 min for comprehensive review
Personal configuration - use and modify as you see fit.
Built on top of Claude Code by Anthropic.
Inspired by:
- AI documentation best practices
- Multi-agent orchestration patterns
- Semantic memory systems (PRISM)
- GitLab/Jira API efficiency
Version: 2.0 (October 2025) Last Updated: 2025-10-27 Claude Model: Sonnet 4.5