{"id":39217689,"url":"https://github.com/arikusi/claude-sage","last_synced_at":"2026-04-01T17:58:33.494Z","repository":{"id":345390699,"uuid":"1136407858","full_name":"arikusi/claude-sage","owner":"arikusi","description":"Workflow system for Claude Code — Analyze First, Fix Later","archived":false,"fork":false,"pushed_at":"2026-03-19T00:15:24.000Z","size":22,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-19T11:31:46.625Z","etag":null,"topics":["ai-agents","ai-coding","anthropic","best-practices","claude-cli","claude-code","code-quality","developer-tools","mcp","productivity","software-engineering","workflow-automation"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arikusi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-17T16:32:02.000Z","updated_at":"2026-03-19T01:22:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/arikusi/claude-sage","commit_stats":null,"previous_names":["arikusi/claude-sage"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/arikusi/claude-sage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arikusi%2Fclaude-sage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arikusi%2Fclaude-sage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arikusi%2Fclaude-sage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arikusi%2Fclaude-sage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arikusi","download_url":"https://codeload.github.com/arikusi/claude-sage/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arikusi%2Fclaude-sage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290728,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-coding","anthropic","best-practices","claude-cli","claude-code","code-quality","developer-tools","mcp","productivity","software-engineering","workflow-automation"],"created_at":"2026-01-17T23:24:52.188Z","updated_at":"2026-04-01T17:58:33.487Z","avatar_url":"https://github.com/arikusi.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-sage\n\n[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/arikusi/claude-sage/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-v2.0%2B-purple.svg)](https://code.anthropic.com)\n[![Marketplace](https://img.shields.io/badge/marketplace-arikusi-orange.svg)](https://github.com/arikusi/arikusi-marketplace)\n\n\u003e **\"Analyze First, Fix Later\"** — Workflow system for Claude Code CLI\n\nAn agent-based workflow system for Claude Code that emphasizes careful analysis, strategic planning, and controlled implementation. No more quick fixes that become technical debt.\n\n---\n\n## A quick note before you start\n\n**MCP Servers - Seriously, install these:** I *highly* recommend setting up the MCP servers (especially **Context7** and **Exa**). They're what make the `horizon-explorer` agent so powerful. Without them, you're missing out on:\n- [Exa](https://github.com/exa-labs/exa-mcp-server): Real-world code examples, API documentation, web search\n- [Context7](https://github.com/upstash/context7): Up-to-date library documentation\n\nTrust me, these aren't optional nice-to-haves—they're game-changers.\n\n\u003e **Important:** Install MCPs **locally** (not as remote/cloud-hosted servers). Subagents cannot authenticate with remote MCPs and will silently fall back to no-op. Local installation is required for agents to use them.\n\n---\n\n## Core Philosophy\n\n**Stop rushing into fixes. Start building right.**\n\nThis system replaces the \"quick fix\" mentality with a structured, multi-agent approach:\n1. **Analyze** the problem deeply (no code changes)\n2. **Architect** the solution strategically (ultrathink mode)\n3. **Explore** alternative perspectives (when stuck)\n4. **Fix** carefully with explicit approval (test-driven)\n\n---\n\n## Quick Start\n\n**Option 1 — Plugin install:**\n\n```\n/plugin marketplace add arikusi/arikusi-marketplace\n/plugin install claude-sage@arikusi-marketplace\n```\n\n**Option 2 — Tell Claude to install it for you:**\n\n```bash\n# Open Claude Code CLI\nclaude\n\n# Then say:\n\"Add the marketplace and install claude-sage:\n/plugin marketplace add arikusi/arikusi-marketplace\n/plugin install claude-sage@arikusi-marketplace\"\n```\n\nThat's it! Claude will set everything up for you.\n\n---\n\n## The Agent Team\n\n### 1. **problem-analyst**\n- **Role**: Forensic investigator\n- **Tools**: Read, Grep, Glob, Bash (read-only)\n- **Powers**: Cannot write/edit code\n- **Purpose**: Deep root cause analysis, impact assessment, reporting\n\n**When to use:** `/analyze [problem description]`\n\n### 2. **solution-architect**\n- **Role**: Strategic architect\n- **Model**: opus + extended thinking\n- **Tools**: Read, Grep, Glob, Bash, TaskCreate/Update (read-only for code)\n- **Powers**: Cannot write/edit code — produces detailed plans with step-by-step tasks\n- **Purpose**: Architecture decisions, trade-off analysis, 3+ alternative approaches\n\n**When to use:** `/architect [architectural decision]`\n\n### 3. **horizon-explorer**\n- **Role**: Lateral thinker\n- **Tools**: Read, Grep, Glob, Bash, Exa MCP, Context7, WebSearch\n- **Powers**: Cannot write/edit code, Research superpowers\n- **Purpose**: Alternative perspectives, unconventional solutions, \"are we looking in the right place?\"\n\n**When to use:** `/explore [stuck problem]`\n\n### 4. **controlled-fixer**\n- **Role**: Careful surgeon\n- **Tools**: Read, Grep, Glob, Edit, Write, Bash, TaskCreate/Update\n- **Powers**: Can modify code (ONLY with explicit approval, in isolated worktree)\n- **Purpose**: Test-driven, reversible, minimal-impact fixes in a separate git branch\n\n**When to use:** `/fix` (after analysis and approval)\n\n### 5. **code-reviewer**\n- **Role**: Independent quality gate\n- **Model**: opus + extended thinking\n- **Tools**: Read, Grep, Glob, Bash (read-only)\n- **Powers**: Cannot modify code — produces APPROVED / NEEDS CHANGES / BLOCKED\n- **Purpose**: Security (OWASP), logic correctness, edge cases, test coverage review\n\n**When to use:** `/review` (after `/fix`, before merging)\n\n---\n\n## Quick Commands\n\n| Command | Calls | What It Does | Modifies Code? |\n|---------|-------|--------------|----------------|\n| `/analyze` | problem-analyst | Deep problem analysis + report | No |\n| `/architect` | solution-architect | Strategic planning (extended thinking, opus) | No |\n| `/explore` | horizon-explorer | Alternative approaches | No |\n| `/fix` | controlled-fixer | Careful implementation in worktree | Yes (if approved) |\n| `/review` | code-reviewer | Independent review before merge | No |\n| `/setup-project` | — | Initialize Claude for new project | Yes |\n\n---\n\n## Standard Workflows\n\n### Workflow 1: Simple Bug Fix\n\n```\n1. /analyze \"npm test failing on auth module\"\n   → problem-analyst: detailed analysis + root cause\n\n2. You: \"Okay, proceed with the fix\"\n   → /fix\n   → controlled-fixer: test-driven fix in isolated worktree\n\n3. /review\n   → code-reviewer: APPROVED\n\n4. git merge [branch]\n```\n\n### Workflow 2: Critical Architectural Decision\n\n```\n1. /analyze \"should we migrate to microservices?\"\n   → problem-analyst: current state analysis\n\n2. /architect \"microservices migration strategy\"\n   → solution-architect: 3+ approaches, trade-offs, risks\n\n3. You: decide which approach\n\n4. /fix [chosen approach]\n   → controlled-fixer: careful implementation in worktree\n\n5. /review\n   → code-reviewer: review + merge decision\n```\n\n### Workflow 3: Stuck for Hours\n\n```\n1. /explore \"we can't solve the race condition in our queue\"\n   → horizon-explorer: alternative patterns, different tech stacks\n   → \"Are we looking in the right place?\"\n\n2. /analyze [new perspective]\n   → problem-analyst: re-analyze with new insights\n\n3. /architect [solution]\n   → solution-architect: strategic plan\n\n4. /fix → /review → merge\n```\n\n---\n\n## Best Practices\n\n### DO\n\n1. **Always start with /analyze** - Never skip understanding\n2. **Use /architect for critical changes** - Get strategic guidance\n3. **Call /explore when stuck** - Fresh perspective\n4. **Approve before /fix** - Controlled changes only\n5. **Request \"ultrathink\"** - For complex decisions\n\n### DON'T\n\n1. **Skip analysis** - Understanding \u003e Speed\n2. **Quick fixes** - Today's shortcut = Tomorrow's debt\n3. **Single perspective** - Use /explore when uncertain\n4. **Untested production changes** - controlled-fixer enforces tests\n5. **Breaking changes without warning** - Agents will flag\n\n---\n\n## Features\n\n### Intelligent Permissions\n```json\n{\n  \"allow\": [\"Bash(git:*)\", \"Bash(npm:*)\"],\n  \"deny\": [\"Bash(rm:-rf:*)\"]\n}\n```\n\n### Post-Tool Hooks\n```json\n{\n  \"PostToolUse\": [{\n    \"matcher\": \"Edit|Write\",\n    \"hooks\": [{\"command\": \"prettier --write $FILE\"}]\n  }]\n}\n```\n\n### Extended Thinking\n```json\n{\n  \"env\": {\n    \"MAX_THINKING_TOKENS\": \"31999\"\n  }\n}\n```\n\n### MCP Integration\n\nThe workflow system is *significantly* more powerful with MCP servers:\n\n- [Exa](https://github.com/exa-labs/exa-mcp-server): Real-world code examples, API documentation, web search\n- [Context7](https://github.com/upstash/context7): Up-to-date library documentation\n\n**Without MCPs:** Basic workflow works, but `horizon-explorer` loses 80% of its research capabilities.\n**With MCPs:** Full-powered alternative research, fresh code examples, and comprehensive documentation.\n\n\u003e **Install MCPs locally.** Subagents (spawned via the Agent tool) cannot authenticate with remote/cloud-hosted MCP servers — they will silently fail to use them. All MCP servers must be installed and running locally on your machine for the agents to access them reliably.\n\n---\n\n## Documentation\n\n- **WORKFLOW-GUIDE.md**: Comprehensive workflow documentation\n- **Agent files**: Each agent has detailed instructions\n- **Command files**: Slash command definitions\n\n---\n\n## Agent Decision Matrix\n\n| Scenario | Agent | Why |\n|----------|-------|-----|\n| \"Why is this failing?\" | problem-analyst | Analysis without changes |\n| \"Should we use GraphQL or REST?\" | solution-architect | Strategic trade-offs |\n| \"We've been stuck for 3 hours\" | horizon-explorer | New perspective |\n| \"Implement the approved fix\" | controlled-fixer | Careful execution |\n| \"Cron job failing intermittently\" | problem-analyst → architect | Race conditions need deep analysis |\n| \"Database migration strategy\" | architect | Critical architectural decision |\n\n---\n\n## Advanced Usage\n\n### Custom Agents\n\nAdd your own agents to `~/.claude/agents/`:\n\n```markdown\n---\nname: your-agent\ndescription: What it does\ntools: Read, Grep\ndisallowedTools: Write, Edit\nmodel: sonnet\n---\n\n# Your Agent Instructions\n\n...\n```\n\n---\n\n\n\n---\n\n*\"Quick fix today, big problem tomorrow.\"*\n\nUnderstand the problem first. Fix it once, fix it right.\n\n---\n\n## 📜 License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farikusi%2Fclaude-sage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farikusi%2Fclaude-sage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farikusi%2Fclaude-sage/lists"}