feat: Anthropic-aligned 2026 upgrade — EPC workflow, hooks, subagents#1
Open
JUNX-10010 wants to merge 5 commits into
Open
feat: Anthropic-aligned 2026 upgrade — EPC workflow, hooks, subagents#1JUNX-10010 wants to merge 5 commits into
JUNX-10010 wants to merge 5 commits into
Conversation
Encode the five practices Anthropic's own teams cited consistently across the "How Anthropic Engineers ACTUALLY Prompt Claude Code" talk, the "How Anthropic teams use Claude Code" PDF, and the Every podcast with Boris Cherny + Cat Wu. Settings (.claude/settings.json): - Wire all 7 hook scripts in the hooks block (the prior config registered none — shell scripts existed but never fired) - Add defaultMode=plan, model=sonnet-4-6, outputStyle, includeCoAuthoredBy - Add statusLine pointing at new hooks/statusline.sh - Tighten deny list (gh repo visibility public, rm -rf .) New slash commands (.claude/commands/): - /explore — read-only investigation, phase 1 of EPC - /plan — writes docs/plans/<name>.md with verification criteria first - /checkpoint — cheap WIP commit, refuses on main + dirty-secret files - /slot-machine — autonomous 30-min run + auto-rollback boundary - /dogfood — log model behavior on new snapshots (docs/dogfood/) - /compact-with-context — guided /compact that preserves the right state New subagents (.claude/agents/): - front-end-tester — Playwright visual diff + golden-path verification - opposing-perspective — two independent briefs, no synthesis (decision aid) - claude-md-curator — end-of-session learnings → CLAUDE.md patch proposal - pr-comment-fixer — fetch reviews, group fixes, push follow-up commits New hooks (.claude/hooks/, all degrade gracefully when jq absent): - session-start.sh SessionStart → inject branch/commits/plans - prompt-expand.sh UserPromptSubmit → light enrichment + deploy warnings - session-end.sh Stop → nudge claude-md-curator after substantive work - statusline.sh Custom status line (branch | mode | model | time) New skills (.claude/skills/): - anthropic-prompting.md The five practices, with sources - explore-plan-code.md The EPC workflow in skill form - screenshot-driven-dev.md Visual-first for UI/design/non-technical work New docs (docs/): - anthropic-playbook.md Distilled team-by-team workflows from the PDF - claude-code-2026-reference.md Current Claude Code feature reference MCP template: - .mcp.json with disabled-by-default servers for Playwright, GitHub, Sentry, Postgres, Filesystem (uncomment to enable; matches Anthropic Data Infra team's "MCP over CLI for sensitive data" guidance) CLAUDE.md: - New "How We Use This Kit" section mapping commands/agents to workflow - Directory tree updated to reflect 14 commands, 8 agents, 7 hooks Sources: - youtu.be/qOvc9IUKEIc — How Anthropic Engineers ACTUALLY Prompt Claude Code - www-cdn.anthropic.com/58284b19e702b49db9302d5b6f135ad8871e7658.pdf - every.to/podcast/transcript-how-to-use-claude-code-like-the-people-who-built-it - code.claude.com/docs Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ee9ea29a4d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The hooks degrade gracefully when jq is missing, which means they exit silently and you lose the security guard, verification gate, session-start context injection, and Stop-hook learnings nudge. That's a confusing failure mode — hooks "work" but do nothing. Add install instructions in three places so this can't be missed: - CLAUDE.md "Prerequisites" — install table for macOS, apt, dnf, Alpine, Arch, winget, Choco, Scoop, manual, Docker - .claude/commands/init.md — Step 0 actively checks `jq --version` before any questionnaire; refuses to proceed if missing - docs/claude-code-2026-reference.md — quickstart checklist now has "Before /init" prerequisites section - session-start.sh — comment points readers at the CLAUDE.md table Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9f38f7a802
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Addresses 3 review comments from chatgpt-codex-connector on PR #1 plus the long-standing CI failure (the workflow tested directories that don't exist until /init runs). P1 — .claude/hooks/prompt-expand.sh:27 The "the plan" branch ran `find docs/plans/` unconditionally. On a fresh repo the directory doesn't exist, find returned non-zero, and pipefail killed the hook. Codex reproduced this with {"user_prompt":"check the plan"} → exit 1. Fix: guard with `[ -d docs/plans ]` before find. Also replace the GNU-only -printf with a portable stat-based mtime sort so the hook works on macOS BSD find too. P2 — .claude/hooks/session-end.sh:46 The EDIT_COUNT greps `.claude/audit.log` for EDIT|WRITE, but security-guard.sh only writes `BASH:` entries. EDIT_COUNT was always 0, so the >=3-edits threshold never triggered and the claude-md-curator nudge never fired. Fix: count from `git status --porcelain | wc -l` instead. That's the actual file-mutation count we care about and is independent of the audit log format. P2 — .claude/settings.json:83 PreToolUse matcher was "WebFetch|WebSearch", so research-gate.sh's mcp__firecrawl__* branches were unreachable. Firecrawl calls bypassed the gate entirely. Fix: extend matcher to include firecrawl_scrape, firecrawl_search, firecrawl_crawl — the three branches research-gate.sh actually handles. CI — .github/workflows/ci.yml Failing on every PR (and main) since May 13 because the workflow ran `pip install -e backend/`, `npm ci portal/`, and node-check on chrome-extension/, but those dirs only exist after /init scaffolds them. Fix: each job now checks `if [ -d <dir> && -f <required-file> ]` first and skips cleanly when not scaffolded, with a GitHub notice explaining why. Adds a new `DevKit Itself` job that always runs and validates the template artifacts (settings.json + .mcp.json parse, hooks pass shellcheck, hooks don't crash on empty input, template configs parse). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Addresses P1 review comment 3253722688 from chatgpt-codex-connector.
The hook was emitting `{"additionalContext": "..."}` at top level, but
Claude Code's PreToolUse schema expects the envelope:
{"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"additionalContext": "..."
}}
Without the wrapper Claude Code silently ignored the output, so every
research-gate routing hint was inert — WebFetch/WebSearch/Firecrawl
calls fell through with no guidance despite the hook being wired and
firing.
Replaced 6 inline `echo '{"additionalContext": ...}'` lines with a
single `emit_ctx` helper that produces the correctly-wrapped JSON.
Also added the standard `command -v jq` graceful-degradation guard
that the other hooks have.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b101a4b288
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Addresses two Codex review comments on b101a4b. P1 — settings.json hook paths All 7 hook commands used relative paths like `bash .claude/hooks/X.sh`. Claude Code runs hooks in the *current working directory*, so after the agent `cd`s into a subdirectory (very common during builds, tests, or exploring monorepos) the path no longer resolves and the hook silently stops firing — including the security guard. Fix: prefix every hook command (and the statusLine command) with `${CLAUDE_PROJECT_DIR}/` so they resolve from the repo root regardless of cwd. Verified all 7 commands now use the anchor. P2 — security-guard.sh fail-open without jq When jq is missing, security-guard.sh fails with command-not-found before any guard check runs. Claude Code treats the non-zero exit as "hook failed" and the Bash call proceeds anyway — a silent fail-open on a destructive-command guard. Fix: explicit `command -v jq` precheck at the top. If absent, exits 0 (fail-open so the session keeps working) but emits a LOUD stderr warning so the gap is visible to the user. Pairs with CLAUDE.md Prerequisites which already tells users to install jq. Also added the same `command -v jq` guard to verification-gate.sh (silent exit — it only injects advisory context, no enforcement). The 4 hooks I authored in the initial PR already had the jq precheck; this commit applies the pattern to the 2 pre-existing devkit hooks too so the whole hook directory has consistent behavior. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Encodes the five practices Anthropic's own teams cited consistently across the "How Anthropic Engineers ACTUALLY Prompt Claude Code" talk, the "How Anthropic teams use Claude Code" PDF, and the Every podcast with Boris Cherny + Cat Wu.
The current settings.json registered no hooks despite having 4 shell scripts in
.claude/hooks/. This PR wires them up plus adds 4 more events, 6 new slash commands, 4 new subagents, 3 new skills, an MCP template, and 2 distilled-from-source reference docs.Headline features
/explore,/plan,/checkpoint,/slot-machine. Boris Cherny: "Aligning on plans can like 2-3x success rates pretty easily."/checkpointrefuses on main + dirty-secret files./slot-machinerecords a start SHA, runs autonomously for 30 min, rolls back on failure.SessionStartinjects branch/commits/plans.UserPromptSubmitsurfaces deploy warnings.Stopnudgesclaude-md-curatorafter substantive work. All degrade gracefully whenjqis missing.defaultMode: plan— every session opens read-only. Shift+tab to implement.front-end-tester(Playwright visual diff),opposing-perspective(2 independent briefs, no synthesis),claude-md-curator(end-of-session learnings),pr-comment-fixer(review-comment automation)..mcp.jsontemplate with Playwright/GitHub/Sentry/Postgres/Filesystem, disabled by default. Matches Anthropic Data Infra team's guidance: "Use MCP servers instead of CLI for sensitive data."What's NOT touched
templates/,packages/arch-viewer, CI workflows/initwizard logic (only the "next steps" footer mentions the new workflow)Files
.claude/settings.json— wire hooks + new keysCLAUDE.md— "How We Use This Kit" section + updated tree.claude/commands/init.md— pointer to EPC after init.mcp.jsonSources
Test plan
⎇ branch* | mode | model | HH:MM)/explore <some-area>returns a structured report, no edits/plan test-planwritesdocs/plans/test-plan.mdwith verification criteria template/checkpoint testrefuses on main, succeeds on a feature branchclaude-md-curatorbash .claude/hooks/statusline.sh < /dev/nullexits 0 even withoutjqinstalledpython -c "import json; json.load(open('.claude/settings.json'))"succeedssecurity-guard,verification-gate,research-gate) still fire🤖 Generated with Claude Code