{"id":30779411,"url":"https://github.com/lakarpusky/claude-epc-workflow","last_synced_at":"2026-05-06T02:31:54.900Z","repository":{"id":307581367,"uuid":"1030009709","full_name":"lakarpusky/claude-epc-workflow","owner":"lakarpusky","description":"Production-grade Claude Code agents for JavaScript, React and Git with concise, structured output","archived":false,"fork":false,"pushed_at":"2025-08-11T00:47:13.000Z","size":49,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-11T02:33:18.930Z","etag":null,"topics":["ai-agents","claude-ai","claude-code","developer-tools","engineering-workflow","git","javascript","llm-tools","productivity","reactjs","version-control"],"latest_commit_sha":null,"homepage":"","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/lakarpusky.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2025-08-01T00:17:26.000Z","updated_at":"2025-08-11T00:47:17.000Z","dependencies_parsed_at":"2025-08-01T02:35:38.669Z","dependency_job_id":"cbdf2ebd-35aa-4fff-ac01-8c02f3ea4bd8","html_url":"https://github.com/lakarpusky/claude-epc-workflow","commit_stats":null,"previous_names":["lakarpusky/claude-epc-workflow"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lakarpusky/claude-epc-workflow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lakarpusky%2Fclaude-epc-workflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lakarpusky%2Fclaude-epc-workflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lakarpusky%2Fclaude-epc-workflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lakarpusky%2Fclaude-epc-workflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lakarpusky","download_url":"https://codeload.github.com/lakarpusky/claude-epc-workflow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lakarpusky%2Fclaude-epc-workflow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273719138,"owners_count":25155660,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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","claude-ai","claude-code","developer-tools","engineering-workflow","git","javascript","llm-tools","productivity","reactjs","version-control"],"created_at":"2025-09-05T06:11:15.209Z","updated_at":"2026-05-06T02:31:54.894Z","avatar_url":"https://github.com/lakarpusky.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude EPC Workflow\n\nMulti-agent system for frontend development in Claude Code. Specialized agents for JavaScript, React, testing, and Git — coordinated by an orchestrator command.\n\nTested daily on Sonnet 4.6 / Pro\n\n## Install\n\n```bash\ngit clone https://github.com/lakarpusky/claude-epc-workflow.git /tmp/claude-epc\nmkdir -p ~/.claude/agents ~/.claude/commands\ncp /tmp/claude-epc/agents/*.md ~/.claude/agents/\ncp /tmp/claude-epc/commands/epc.md ~/.claude/commands/\n```\n\nThen in Claude Code:\n\n```\n/agents       # verify agents loaded\n/effort high  # set session reasoning level\n```\n\nFor the optional personal-setup files (global CLAUDE.md, project template, karpathy-guidelines skill) see [COMPANIONS.md](./COMPANIONS.md)\n\n## Usage\n\n```\n/epc [mode] [task]\n```\n\nModes are analytical depth, not token caps:\n\n| Mode | Use when |\n|---|---|\n| `quick` | Pattern is obvious; instant fix |\n| `standard` (default) | Unknown problem; explore → plan → code |\n| `architect` | Structural decision; multiple files |\n| `unbounded` | Deep architectural exploration |\n| `emergency` | Production down; revert first, investigate after |\n\nExamples:\n\n```\n/epc quick fix the null check in UserCard\n/epc standard add a filter to the product list\n/epc architect redesign state management\n/epc emergency revert last commit\n```\n\nWhen the domain is obvious, skip `/epc` and call a specialist directly to save an orchestration turn:\n\n```\n@git-wizard squash the last 5 commits\n@react-virtuoso fix re-renders in Dashboard\n@test-sentinel write integration tests for the cart flow\n@javascript-specialist optimize this O(n²) loop\n```\n\n## Agents\n\n| Agent | Domain |\n|---|---|\n| `git-wizard` | Commits, conflicts, rebases, branch strategy, recovery |\n| `javascript-specialist` | Algorithms, performance, memory, async, bundle analysis |\n| `react-virtuoso` | Components, renders, state, hooks, accessibility |\n| `test-sentinel` | Jest, RTL, integration tests, coverage, flaky-test triage |\n\nEach runs in its own context window with `effort: high` and persistent `memory: user`. Agents return text summaries to the orchestrator, which restates relevant findings in plain English when chaining specialists.\n\n## Tuning by model\n\n| Setup | Adjustment |\n|---|---|\n| Sonnet 4.6 / Pro | Default. `effort: high` on agents. `/effort high` session-wide. |\n| Opus 4.6 / Max | Same as default — `high` and `max` are the meaningful levels. |\n| Opus 4.7 / Max | Optionally bump agents to `effort: xhigh`. |\n| Quality still degraded | `export CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` (Opus 4.6 / Sonnet 4.6 only). |\n| Cost-sensitive | Drop agents to `effort: medium`. Skip `/epc` for one-domain tasks. |\n\nSlash commands can't carry `effort` in frontmatter. Set the session level once with `/effort high` or persist in `~/.claude/settings.json`:\n\n```json\n{ \"effortLevel\": \"high\" }\n```\n\n## What changed in April 2026\n\nAdaptive reasoning + a lowered default effort silently degraded the previous version's quality. Fixed by adding `effort: high` and `memory: user` frontmatter to every subagent, removing token-budget instructions that suppressed thinking under the new model behavior, and restructuring `/epc` as a proper slash command.\n\nFull rationale, citations, and per-file changes in [MIGRATION.md](./MIGRATION.md)\n\n## Scope\n\n**Covered:** Frontend JS/TS, React, Jest/RTL, Git workflows.    \n**Not covered:** Backend (beyond JS basics), Vue/Svelte/Angular, E2E (Playwright/Cypress), infrastructure/DevOps, mobile/native.\n\n## Credits\n\nAgents and `/epc` orchestrator are original to this repo.\n\n## Recommended Companions\n\nThe optional `karpathy-guidelines` companion skill is derived from [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) (MIT), which distills four principles from [Andrej Karpathy's tweet](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls. See [COMPANIONS.md](./COMPANIONS.md) for attribution details.\n\nThe files below are not part of the core system but pair well with it. They are independent: the agents + /epc work without them, and they work in any Claude Code setup without the agents.\n\n```\n~/.claude/\n├── CLAUDE.md                                         ← personal defaults (~30 lines)\n├── templates/\n│   └── PROJECT-CLAUDE.md                             ← copy to projects, fill in\n└── skills/\n    └── karpathy-guidelines/                          ← on-demand coding behavior\n        ├── SKILL.md\n        └── EXAMPLES.md\n```\n\n| File | Purpose | Loads when |\n|---|---|---|\n| `CLAUDE.md` (global) | Personal defaults: direct-mode rules, debugging discipline, bash hygiene | Every session |\n| `templates/PROJECT-CLAUDE.md` | Fillable template for per-project CLAUDE.md (tech stack, critical paths, conventions) | When you copy it to a project root |\n| `skills/karpathy-guidelines/` | Four principles that prevent common LLM coding mistakes | On code-writing tasks (description match) |\n\n### Global CLAUDE.md\n\nA lean (~30 line) personal defaults file: direct-mode rules, debugging discipline, bash hygiene. Every line answers Anthropic's [official test](https://code.claude.com/docs/en/best-practices): *\"Would removing this cause Claude to make mistakes?\"*\n\nThe previous version of this file (in earlier iterations of this workflow) was 656 lines and duplicated content that now lives correctly in agent files. Per [Anthropic's guidance](https://code.claude.com/docs/en/best-practices): *\"Bloated CLAUDE.md files cause Claude to ignore your actual instructions.\"* The official recommendation is under 200 lines.\n\n### Project template\n\n`templates/PROJECT-CLAUDE.md` is copied to each project's root and filled in. ~80% comments and prompts that guide what to include (tech stack, architecture, critical paths, file risk map) and explicit reminders to cut anything generic.\n\n### karpathy-guidelines skill\n\nA third-party skill that encodes four behavioral principles distilled from [Andrej Karpathy's observations on LLM coding pitfalls](https://x.com/karpathy/status/2015883857489522876) by [Forrest Chang](https://github.com/forrestchang) ([andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills), MIT licensed):\n\n1. **Think Before Coding** — surface assumptions, present interpretations, push back when warranted\n2. **Simplicity First** — minimum code that solves the problem, no speculative abstractions\n3. **Surgical Changes** — touch only what the request requires, match existing style\n4. **Goal-Driven Execution** — define verifiable success criteria, write tests that reproduce bugs first\n\n**This is a derivative work** of Forrest Chang's upstream skill. Two adaptations:\n\n- **Tightened skill description** for more reliable activation — explicit `MUST ACTIVATE` directive plus trigger verbs (implement, fix, refactor, build, etc.).\n- **EXAMPLES.md ported to JavaScript/TypeScript and React** — the upstream uses Python. All examples were rewritten in JS/TS for stack alignment, plus 3 React-specific examples added (don't refactor unrelated hooks while memoizing, don't reach for Context unprompted, don't optimize without Profiler data).\n\nThe four principles themselves are unchanged from the upstream. Credit for the principles goes to Karpathy and Forrest Chang.\n\n### Install\n\n```bash\nmkdir -p ~/.claude/templates ~/.claude/skills/karpathy-guidelines\n\n# Global CLAUDE.md\ncp /tmp/claude-epc/CLAUDE.md ~/.claude/CLAUDE.md\n\n# Project template\ncp /tmp/claude-epc/templates/PROJECT-CLAUDE.md ~/.claude/templates/\n\n# karpathy-guidelines skill\ncp /tmp/claude-epc/skills/karpathy-guidelines/* ~/.claude/skills/karpathy-guidelines/\n```\n\nFor new projects, copy the template into the repo root and fill in what applies:\n\n```bash\ncd ~/code/my-project\ncp ~/.claude/templates/PROJECT-CLAUDE.md ./CLAUDE.md\n$EDITOR ./CLAUDE.md\n```\n\n### Why these aren't part of the core system\n\nThese files address different problems than the agents and /epc:\n\n- **Agents + /epc** = domain expertise and multi-domain task orchestration\n- **Global CLAUDE.md** = personal defaults across all Claude Code work\n- **Project template** = per-project context (tech stack, conventions, gotchas)\n- **karpathy-guidelines skill** = general-purpose behavioral nudges for code work\n\nYou can adopt any subset independently. The agents work without the companions; the companions work without the agents. Bundling them in this repo is a convenience, not a requirement.\n\n## References\n\n**Official Anthropic docs (primary sources):**\n\n- [Create custom subagents](https://code.claude.com/docs/en/sub-agents) — frontmatter reference, scopes, memory, hooks, skills preloading\n- [Model configuration](https://code.claude.com/docs/en/model-config) — effort levels, adaptive reasoning, model aliases, environment variables\n- [Effort](https://platform.claude.com/docs/en/build-with-claude/effort) — adaptive reasoning details, per-model levels\n- [Skills](https://code.claude.com/docs/en/skills) — progressive disclosure, frontmatter, subagent integration\n- [Slash commands / commands reference](https://code.claude.com/docs/en/commands) — built-in commands and bundled skills\n- [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) — Anthropic engineering blog on Skills design\n\n**Community references on the regression:**\n\n- GitHub: [Per-subagent effortLevel feature request](https://github.com/anthropics/claude-code/issues/31536)\n- GitHub: [Effort/thinking config for Task tool subagents](https://github.com/anthropics/claude-code/issues/25669)\n- GitHub: [Configurable reasoning effort level for subagents](https://github.com/anthropics/claude-code/issues/43083)\n- [Claude Code effort levels explained](https://www.mindstudio.ai/blog/claude-code-effort-levels-explained) — practical breakdown of low/medium/high/max\n- [Claude Opus 4.7 best practices](https://claudefa.st/blog/guide/development/opus-4-7-best-practices) — `xhigh` defaults, adaptive thinking on 4.7\n\n**Background reading:**\n\n- [Claude Code Subagents complete guide](https://medium.com/@sathishkraju/claude-code-subagents-the-complete-guide-to-ai-agent-delegation-d0a9aba419d0)\n- [Mental model for Claude Code: Skills, Subagents, Plugins](https://levelup.gitconnected.com/a-mental-model-for-claude-code-skills-subagents-and-plugins-3dea9924bf05)\n\nThe files below are not part of the core system but pair well with it. They are independent: the agents + /epc work without them, and they work in any Claude Code setup without the agents.\n\n```\n~/.claude/\n├── CLAUDE.md                                         ← personal defaults (~30 lines)\n├── templates/\n│   └── PROJECT-CLAUDE.md                             ← copy to projects, fill in\n└── skills/\n    └── karpathy-guidelines/                          ← on-demand coding behavior\n        ├── SKILL.md\n        └── EXAMPLES.md\n```\n\n| File | Purpose | Loads when |\n|---|---|---|\n| `CLAUDE.md` (global) | Personal defaults: direct-mode rules, debugging discipline, bash hygiene | Every session |\n| `templates/PROJECT-CLAUDE.md` | Fillable template for per-project CLAUDE.md (tech stack, critical paths, conventions) | When you copy it to a project root |\n| `skills/karpathy-guidelines/` | Four principles that prevent common LLM coding mistakes | On code-writing tasks (description match) |\n\n### Global CLAUDE.md\n\nA lean (~30 line) personal defaults file: direct-mode rules, debugging discipline, bash hygiene. Every line answers Anthropic's [official test](https://code.claude.com/docs/en/best-practices): *\"Would removing this cause Claude to make mistakes?\"*\n\nThe previous version of this file (in earlier iterations of this workflow) was 656 lines and duplicated content that now lives correctly in agent files. Per [Anthropic's guidance](https://code.claude.com/docs/en/best-practices): *\"Bloated CLAUDE.md files cause Claude to ignore your actual instructions.\"* The official recommendation is under 200 lines.\n\n### Project template\n\n`templates/PROJECT-CLAUDE.md` is copied to each project's root and filled in. ~80% comments and prompts that guide what to include (tech stack, architecture, critical paths, file risk map) and explicit reminders to cut anything generic.\n\n### karpathy-guidelines skill\n\nA third-party skill that encodes four behavioral principles distilled from [Andrej Karpathy's observations on LLM coding pitfalls](https://x.com/karpathy/status/2015883857489522876) by [Forrest Chang](https://github.com/forrestchang) ([andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills), MIT licensed):\n\n1. **Think Before Coding** — surface assumptions, present interpretations, push back when warranted\n2. **Simplicity First** — minimum code that solves the problem, no speculative abstractions\n3. **Surgical Changes** — touch only what the request requires, match existing style\n4. **Goal-Driven Execution** — define verifiable success criteria, write tests that reproduce bugs first\n\n**This is a derivative work** of Forrest Chang's upstream skill. Two adaptations:\n\n- **Tightened skill description** for more reliable activation — explicit `MUST ACTIVATE` directive plus trigger verbs (implement, fix, refactor, build, etc.).\n- **EXAMPLES.md ported to JavaScript/TypeScript and React** — the upstream uses Python. All examples were rewritten in JS/TS for stack alignment, plus 3 React-specific examples added (don't refactor unrelated hooks while memoizing, don't reach for Context unprompted, don't optimize without Profiler data).\n\nThe four principles themselves are unchanged from the upstream. Credit for the principles goes to Karpathy and Forrest Chang.\n\n### Install\n\n```bash\nmkdir -p ~/.claude/templates ~/.claude/skills/karpathy-guidelines\n\n# Global CLAUDE.md\ncp /tmp/claude-epc/CLAUDE.md ~/.claude/CLAUDE.md\n\n# Project template\ncp /tmp/claude-epc/templates/PROJECT-CLAUDE.md ~/.claude/templates/\n\n# karpathy-guidelines skill\ncp /tmp/claude-epc/skills/karpathy-guidelines/* ~/.claude/skills/karpathy-guidelines/\n```\n\nFor new projects, copy the template into the repo root and fill in what applies:\n\n```bash\ncd ~/code/my-project\ncp ~/.claude/templates/PROJECT-CLAUDE.md ./CLAUDE.md\n$EDITOR ./CLAUDE.md\n```\n\n### Why these aren't part of the core system\n\nThese files address different problems than the agents and /epc:\n\n- **Agents + /epc** = domain expertise and multi-domain task orchestration\n- **Global CLAUDE.md** = personal defaults across all Claude Code work\n- **Project template** = per-project context (tech stack, conventions, gotchas)\n- **karpathy-guidelines skill** = general-purpose behavioral nudges for code work\n\nYou can adopt any subset independently. The agents work without the companions; the companions work without the agents. Bundling them in this repo is a convenience, not a requirement.\n\n## References\n\n**Official Anthropic docs (primary sources):**\n\n- [Create custom subagents](https://code.claude.com/docs/en/sub-agents) — frontmatter reference, scopes, memory, hooks, skills preloading\n- [Model configuration](https://code.claude.com/docs/en/model-config) — effort levels, adaptive reasoning, model aliases, environment variables\n- [Effort](https://platform.claude.com/docs/en/build-with-claude/effort) — adaptive reasoning details, per-model levels\n- [Skills](https://code.claude.com/docs/en/skills) — progressive disclosure, frontmatter, subagent integration\n- [Slash commands / commands reference](https://code.claude.com/docs/en/commands) — built-in commands and bundled skills\n- [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) — Anthropic engineering blog on Skills design\n\n**Community references on the regression:**\n\n- GitHub: [Per-subagent effortLevel feature request](https://github.com/anthropics/claude-code/issues/31536)\n- GitHub: [Effort/thinking config for Task tool subagents](https://github.com/anthropics/claude-code/issues/25669)\n- GitHub: [Configurable reasoning effort level for subagents](https://github.com/anthropics/claude-code/issues/43083)\n- [Claude Code effort levels explained](https://www.mindstudio.ai/blog/claude-code-effort-levels-explained) — practical breakdown of low/medium/high/max\n- [Claude Opus 4.7 best practices](https://claudefa.st/blog/guide/development/opus-4-7-best-practices) — `xhigh` defaults, adaptive thinking on 4.7\n\n**Background reading:**\n\n- [Claude Code Subagents complete guide](https://medium.com/@sathishkraju/claude-code-subagents-the-complete-guide-to-ai-agent-delegation-d0a9aba419d0)\n- [Mental model for Claude Code: Skills, Subagents, Plugins](https://levelup.gitconnected.com/a-mental-model-for-claude-code-skills-subagents-and-plugins-3dea9924bf05)\n\n## License\n\nMIT for the core system (agents and /epc orchestrator) all original work.\n\nThe optional `karpathy-guidelines` companion skill is a derivative of [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) (MIT); modifications retain the same license. See [Recommended Companions](#recommended-companions) for attribution details.\n\n---\n\nIf you find this workflow useful, the highest-leverage thing you can do is verify each change against the docs above and adapt it to your stack. The configuration values here are tuned for Sonnet 4.6 + Pro and a frontend/JS workload. Other setups will want different `effort` and `maxTurns` values.\n\nIssues and PRs welcome.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flakarpusky%2Fclaude-epc-workflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flakarpusky%2Fclaude-epc-workflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flakarpusky%2Fclaude-epc-workflow/lists"}