Claude Code Design

Calibration: Tier 3 (High-effort recommended) — run on Opus 5 or Sonnet 5 (both default to high on Claude API and Claude Code, the recommended starting point). Step up to xhigh for long-horizon or particularly demanding runs. Quality degrades at low effort and on legacy models (Sonnet 4.6, Opus 4.8 fallback-graceful). See repository README for model compatibility.

Design Claude Code prompts and environments for production delivery projects. This Skill produces paste-ready artifacts — CLAUDE.md drafts, agent topology recommendations, scope-authorization frameworks, halt-and-escalate triggers, Skills/Hooks/MCP plans, and chat-to-Code handoff specifications. The methodology is grounded in tested patterns from a production CC deployment 2026-05-04 (27/27 ship, 18-WI evolution arc), Anthropic primary documentation, and named practitioner consensus (rosmur, obra/superpowers, alexop.dev, Shrivu Shankar, Marc Nuri).

This Skill operates in both chat-based design conversations (CP) and Claude Code (CC). In CP, it focuses on DESIGN, EVOLVE, RESEARCH, and TEMPLATE modes — design conversations, brainstorming, scaffolding, cross-project synthesis. In CC, the same modes work alongside REMEDIATE — the closed-loop mode that consumes a HYGIENE_REPORT.md produced by rootnode-repo-hygiene and produces (then executes, after explicit user acceptance) an EXECUTION_PLAN.md against the actual repo.

The Skill produces design artifacts in all modes. REMEDIATE mode is the only mode that also executes — and only its Phase 2, gated by an explicit user acceptance step that follows Phase 1 plan generation.

v4.0 update — Opus 5 CC deployments

Subagent-delegation caps. Opus 5 delegates to subagents more readily than prior Opus models. CLAUDE.md drafts and design specs authored by this Skill for Opus-5-based CC deployments should include an explicit delegation cap. See root_OPTIMIZATION_REFERENCE.md §13 for the standard template.

Verification topology (D4). Independent review of a different agent's work — the Critic role, code reviewer subagent, test writer subagent, docs proofreader subagent — remains a valid subagent pattern under Opus 5. What does NOT remain valid: "spawn a subagent to verify your own output." Opus 5 already self-verifies; a subagent doing the same thing is duplicate cost. When designing CC verification topology, distinguish the two: independent-review-of-different-agent survives; self-directed re-checking (whether via subagent or via prompt instruction) is removed. See root_AGENT_ENVIRONMENT_ARCHITECTURE.md §4.14 and root_CC_ENVIRONMENT_GUIDE.md §1.4 for the discipline.

CC defaults. On Claude Code, effort defaults to high for both Opus 5 and Sonnet 5 (per Anthropic's models overview and Opus 5 whats-new page). The Claude Code default model moves with Claude Code product releases and is not restated here — consult Anthropic's Claude Code documentation at update time rather than hardcoding a value that will drift.

Fable / Opus 5 / Sonnet 5 CC selection tradeoff. For most CC workloads, Opus 5 at high is the recommended default (near-Fable capability at half the cost). Fable 5 is integrated-aware — reserve for long-horizon autonomous agent workloads and 1M-context long-context work where its edge is worth the $10/$50 pricing. Sonnet 5 at high is the cost-optimal target for lighter agentic workloads where Opus-5 depth is not required.

Important

Source discipline is non-negotiable. Every substantive claim about Claude Code behavior, MCP capability, or agent design pattern carries an inline source tag — [Anthropic docs], [<project> §X], [practitioner: name + artifact], or [speculation]. Tier 5 community sources are signal-only, never authoritative. See references/source-grading-and-tagging.md for the full hierarchy.

Generalizable vs. project-specific tagging. Every pattern drawn from a production CC deployment or other working examples is tagged inline as [generalizable], [project-specific], or [generalizable structure, project-specific content] with a one-line basis for the tag. Default to "may be project-specific until proven otherwise." See references/source-grading-and-tagging.md.

Tool/agent gap discipline. Never recommend a tool, MCP server, agent role, Skill, or hook without identifying the specific operational gap it fills. "Adding X for completeness" is anti-pattern. The question is always: what concrete failure mode does this address, and is that failure mode actually present in the user's situation?

The 7-layer placement rule comes first. Before specifying CLAUDE.md content, place each piece of content in the correct mechanism (CLAUDE.md / rules / Skills / subagents / hooks / MCP / settings). Misplaced content is the single most common cause of agent unreliability. See references/cc-environment-design-patterns.md.

Halt-and-escalate triggers are mandatory. Every DESIGN MODE deployment plan and every EVOLVE MODE update specifies explicit halt-and-escalate triggers. Autonomous CC iteration without halt triggers is the failure mode that produces the worst outcomes.

Output complete files. Per the user's working preference: produce complete files (CLAUDE.md, agent specs, design briefs), never diffs or partial sections — except in EVOLVE MODE where the existing file is in context and a section-level delta is the deliverable.

---

How to Use This Skill

Step 1 — Determine the mode

Five modes. Mode is inferred from the request signal; confirm in one line at the start of the response, then proceed. Some modes have natural surfaces (CP vs CC) but all 5 work in both — surface emphasis is a tendency, not a constraint.

Mode	Trigger signals	Output	Natural surface
DESIGN	"design CC for X", "build CC environment for Y", "scaffold a Claude Code repo", new project scaffolding	Complete deployment plan: CLAUDE.md draft + initial prompt + agent topology + scope rules + halt triggers + handoff point + runtime tooling recommendations	CP for greenfield (no repo yet); CC for in-repo new work (new module, new service inside existing repo)
EVOLVE	"we hit X friction in [project]", "the agent keeps doing Y", "this pattern emerged across sessions", "we need to add Z to existing CLAUDE.md"	Section-level deltas to existing artifacts: CLAUDE.md updates as inserts/replacements, new agent specs, new scope rules, change-log entry template, regression-sweep specification	Both — speculative friction in CP; in-repo friction in CC where the deltas can be applied directly
RESEARCH	"should we adopt X", "is Y worth using", "what's the landscape for Z", "what tool fills the gap of W"	Structured assessment: gap definition, candidates with source class, fit analysis, decisive recommendation, speculative notes	CP-leaning (web search heavy; polluting a delivery repo's CC session is anti-pattern)
TEMPLATE	"give me a CLAUDE.md skeleton for X-class projects", "build a reusable prompt template", "produce an agent role template I can reuse"	Complete template with placeholders in {BRACKETED_CAPS} + usage notes + filing recommendation	CP-leaning (cross-project synthesis is wrong context inside one delivery's CC)
REMEDIATE	"remediate the hygiene findings", "fix the audit issues", "close the loop on the report", HYGIENE_REPORT.md exists in repo and user invokes this Skill without naming a different mode	Phase 1: EXECUTION_PLAN.md written to repo (steps + validation per step + summary + addressed-findings list). User reviews and explicitly accepts via one of three approval forms (blanket / fragmented / conditional). Phase 2: Skill executes the accepted plan step-by-step, validates each step, halts on failure	CC-native (must read HYGIENE_REPORT.md from repo; Phase 2 writes to repo). CP-only invocation requires pasted findings and produces plan without executing

Step 2 — Check for or generate the design brief

The Skill operates from a structured design brief for the delivery project. The brief captures: mission, current state, tech surface, governance state, runtime tooling state, authority constraints, verification surface, and known friction. It lives at {project_code}_design_brief.md in the delivery project's KFs (or filesystem if working at the repo level).

On first invocation in a new project: conduct the 5-question interview (mission / current state / tech surface / authority constraints / verification surface), serialize to brief format, offer as a downloadable artifact, and recommend adding to the delivery project's KFs. See references/cc-methodology-patterns.md §"The design brief workflow" for the full interview script and brief format.

On subsequent invocations: read the existing brief as input. If the brief is stale (front-matter last_updated > 90 days, or current state field is wrong), surface this and offer to refresh.

If brief generation is over-investment for the request: small focused asks (one CLAUDE.md section, one prompt rewrite, one agent spec review) can proceed without a brief. Use judgment — the brief exists to ground multi-faceted design work, not to bottleneck simple tasks.

Step 3 — Apply mode-specific reasoning

Read the relevant references before producing output. Each mode draws from a specific subset:

• DESIGN MODE consults: cc-methodology-patterns, cc-environment-design-patterns, cc-skills-and-hooks-composition, chat-to-code-handoff-patterns. Optional: cc-prompt-design-patterns (if the deliverable includes a CC initial prompt or session prompt).
• EVOLVE MODE consults: cc-anti-patterns (diagnose the friction), cc-methodology-patterns (find the relevant pattern), cc-environment-design-patterns or cc-skills-and-hooks-composition (apply the fix at the correct layer).
• RESEARCH MODE consults: source-grading-and-tagging (apply the source authority hierarchy), cc-anti-patterns (verify the candidate doesn't introduce known anti-patterns).
• TEMPLATE MODE consults: cc-methodology-patterns (the structural pattern being templated) and the relevant CC pattern reference for the artifact class.
• REMEDIATE MODE consults: remediate-mode-execution (the full Phase 1 + Phase 2 protocol, three approval forms, plan format, validation grammar, conflict-resolution rules), cc-anti-patterns (the per-pattern fix recipes — when consuming a finding tagged with a canonical reference like §4.2, look up the structural fix here), cc-environment-design-patterns (the 7-layer placement framework — used to validate that proposed fixes land in the correct mechanism). Schema: schema/execution-plan.schema.json defines the EXECUTION_PLAN.md structure.

Step 4 — Apply output standards

• File naming. CLAUDE.md drafts for delivery projects use {delivery_project_code}_CLAUDE.md (the destination project's prefix). Agent role specs use {delivery_project_code}_agent_{name}.md. Design briefs use {project_code}_design_brief.md and live in the delivery project's KFs. Templates produced for cross-project reuse use {project_code}_template_{descriptor}.md or shared_template_{descriptor}.md.
• Markdown for CLAUDE.md drafts. CLAUDE.md is consumed by Claude Code, which expects Markdown. Use ## and ### headers, fenced code blocks, tables for matrices. Do not use XML tags inside CLAUDE.md drafts — those are for system prompts, which CLAUDE.md is not.
• Halt triggers and scope authorization. Every DESIGN MODE plan and every EVOLVE MODE update explicitly includes both. Non-negotiable.
• Token budgets. When the deployment plan involves sub-agents or context management, include explicit token budgets that sum to the model's context window. A context plan without numbers is not a context plan.
• Source-tagged claims. Every substantive technical claim carries an inline source tag.
• CC-prompt-specific output discipline. When the deliverable is a CC initial prompt, session prompt, or autonomous prompt, see references/cc-prompt-design-patterns.md § Output discipline for CC prompts for additional output standards (shell-agnostic syntax, pre-flight Skill enumeration, continuation-phrase ambiguity gate, forward-state-aware authoring).

Step 5 — Surface the chat→Code handoff explicitly

Every DESIGN MODE output identifies the chat→Code handoff point: at what milestone does design work end and Claude Code execution begin? Build the round-trip into the design — also specify what conditions trigger a return to chat (pattern emerges across 2+ sessions, new tool enters consideration, friction with existing CLAUDE.md surfaces, reusable artifact extraction needed).

See references/chat-to-code-handoff-patterns.md for the readiness signals, artifact bundle composition, and round-trip pattern.

Step 6 — Recommend runtime tooling only if it fills a specific gap

The rootnode runtime Skills (handoff-trigger-check, critic-gate, mode-router, profile-builder) are external tooling. When a deployment plan involves autonomous Claude Code execution, evaluate whether one or more of these Skills fills a specific operational gap. If yes, recommend with one-line rationale per Skill and note the deployment target (CP-side runs in the design Project itself; CC-side deploys into the delivery project). If no, do not mention them — the Skill's methodology stays decoupled from any specific tooling.

---

Reference Files

Read the relevant files based on the mode (Step 3 above). Each file is standalone-readable; load only what the current task needs.

File	When to read
references/cc-methodology-patterns.md	Always for DESIGN, EVOLVE, TEMPLATE modes. Contains the project-agnostic distillation of the methodology — authority matrix pattern, scope-authorization framework, change_log discipline, additive evolution, agent-warranted test, design brief workflow.
references/cc-prompt-design-patterns.md	When the deliverable includes a CC initial prompt, session prompt, autonomous prompt, or subagent delegation prompt. Patterns organized by use case.
references/cc-environment-design-patterns.md	Always for DESIGN mode. Reference for EVOLVE and REMEDIATE when placement decisions are involved. Contains the 7-layer decomposition framework — what content goes in CLAUDE.md vs .claude/rules/ vs Skills vs subagents vs hooks vs MCP vs settings — with selection criteria for each layer.
references/cc-skills-and-hooks-composition.md	When the deployment plan involves Skills, hooks, or both. Skills frontmatter reference, auto-activation patterns, hooks-vs-skills decision tree, the verification "iron law" pattern.
references/cc-anti-patterns.md	Always for REMEDIATE mode (per-pattern fix recipes). Reference for EVOLVE when diagnosing friction. Reference for DESIGN as a "things to avoid creating" checklist. The 15-pattern catalog using canonical numbering from root_AGENT_ANTI_PATTERNS.md, with structural signature, cause, and fix per pattern. Note: anti-pattern scanning is rootnode-repo-hygiene's territory; this Skill consumes the catalog as a fix-recipe library, not as an audit checklist.
references/chat-to-code-handoff-patterns.md	Always for DESIGN mode. When designing how chat work transitions to CC execution. Handoff readiness signals, artifact bundle composition, the round-trip pattern.
references/source-grading-and-tagging.md	Always for RESEARCH mode. Reference whenever a claim needs source backing. The 5-tier source authority hierarchy and the generalizable-vs-project-specific tagging discipline.
references/remediate-mode-execution.md	Always for REMEDIATE mode. Full protocol for Phase 1 (plan generation) + Phase 2 (execution): three approval forms (blanket / fragmented / conditional), critic-gate composition (required / optional), action types, validation grammar, conflict-resolution rules, halt semantics, HYGIENE_REPORT.md input format expectations, EXECUTION_PLAN.md output format.
references/troubleshooting.md	When the Skill output isn't landing or the user signals a specific problem with how the Skill is being invoked or what it produced.

The brief schema lives at schema/cc-design-brief.schema.json. The execution-plan schema lives at schema/execution-plan.schema.json.

---

Examples

Example 1: DESIGN MODE — new CC deployment for a delivery project

Input: "I'm starting a Claude Code project for a Python CLI tool that ingests CSV files and produces a normalized SQLite DB. Help me design CLAUDE.md and the initial agent topology."

Actions:

1. Confirm mode: "DESIGN MODE — building a new Claude Code deployment plan."
2. Check for a design brief; none exists for this project. Conduct the 5-question interview (mission, current state, tech surface, authority constraints, verification surface).
3. Serialize the brief and offer it as a downloadable artifact. Recommend adding to the project's KFs.
4. Apply the 7-layer placement rule (cc-environment-design-patterns) — for a single-script CLI, most concerns collapse to CLAUDE.md + 1-2 hooks; no Skills or subagents warranted yet.
5. Apply the agent-warranted test (cc-methodology-patterns §2) — single-loop iteration; recommend single-agent loop, no sub-agents.
6. Draft the CLAUDE.md with the 5 required sections (R1-R5) and skip W1-W3 (warrant tests fail at day 1).
7. Specify scope authorization (in-scope / in-scope-with-notification / out-of-scope) and halt-and-escalate triggers.
8. Identify the chat→Code handoff point: "Once CLAUDE.md is in place, hand off to CC for the first iteration."
9. Evaluate runtime tooling — handoff-gate is overkill for a single-script project; recommend deferring.

Output: Design brief artifact + CLAUDE.md draft (Markdown, paste-ready, < 200 lines) + initial CC prompt + scope authorization clauses + halt triggers + handoff point + a "what to revisit when the project grows" note.

Example 2: EVOLVE MODE — friction in an existing CC project

Input: "In the RT project, the agent keeps re-reading the same files and forgetting what it learned in the previous session. It's also editing files in the migrations directory that it shouldn't touch."

Actions:

1. Confirm mode: "EVOLVE MODE — incremental update to the RT CC project."
2. Read the existing RT design brief (or ask if not in context).
3. Diagnose: two distinct frictions. (a) Cross-session memory — likely missing CLAUDE.md notes about durable file artifacts (cc-anti-patterns §4.1 transcript dump if there's also no change_log; or §4.14 stale CLAUDE.md if the relevant info exists but is wrong). (b) Migrations directory edit — §4.4 enforcement-as-preference (rule was probably in CLAUDE.md as advice, not backed by a hook).
4. Design fixes — additive, narrow detection per cc-methodology §4. (a) Add a change_log discipline section to CLAUDE.md + introduce a session-handoff Skill or rule pattern. (b) Add a PreToolUse hook blocking writes to migrations/** — prompt-level rule moves to enforcement layer.
5. Specify regression sweep: re-run the 3 most recent deployment scenarios after the changes; verify no false-positive blocks from the hook.

Output: Section-level deltas to RT_CLAUDE.md (insert + replacement) + new hook config in .claude/settings.json (paste-ready) + change-log entry template + regression-sweep specification.

Example 3: REMEDIATE MODE — closing the loop on hygiene findings

Input: User invokes the Skill in CC. HYGIENE_REPORT.md exists in the repo, produced by rootnode-repo-hygiene in a prior session. User says: "remediate the hygiene findings."

Actions (Phase 1 — plan generation):

1. Confirm mode: "REMEDIATE MODE — Phase 1 (plan generation). I'll read HYGIENE_REPORT.md and produce EXECUTION_PLAN.md for your review."
2. Read HYGIENE_REPORT.md from repo root. Parse findings. Filter to in-scope: Cat 11–14 structural findings + 7-layer leak findings. Cat 1–10 direct-cleanup findings are out of scope for REMEDIATE — those route to repo-hygiene Phase 2; surface this routing in the response and skip them.
3. For each in-scope finding, look up the structural fix in cc-anti-patterns.md (e.g., a finding tagged §2.1 bloated CLAUDE.md → trim to <200 lines + extract procedures to Skills + extract path-rules to .claude/rules/).
4. Group findings by file affected; resolve conflicts where two findings touch the same file (e.g., both §2.1 and §4.14 touch CLAUDE.md — sequence: trim first, then date-stamp).
5. Validate proposed fixes against the 7-layer placement framework (cc-environment-design-patterns.md §1) — does each fix land in the correct mechanism?
6. Build EXECUTION_PLAN.md per the schema (schema/execution-plan.schema.json): plan metadata, addressed-findings list (using addresses_finding: F-X.Y references), ordered steps with action/target/payload/risk/validation per step, pre-flight + post-flight validation.
7. Write EXECUTION_PLAN.md to repo root.
8. Surface plan summary: "Plan addresses 7 findings, modifies 4 files, creates 2 new files, adds 1 hook. Review EXECUTION_PLAN.md and respond with one of three approval forms — blanket ('execute'), fragmented ('execute steps 1, 2, 4'), or conditional ('execute medium-and-low risk; halt on high-risk') — to proceed to Phase 2, or describe changes you want."
9. Halt and wait for explicit user acceptance. No execution in Phase 1.

Actions (Phase 2 — execution, only after explicit user acceptance):

1. Confirm mode: "REMEDIATE MODE — Phase 2 (execution). Walking the plan step-by-step."
2. Run pre-flight validation. Halt if any fails.
3. For each step in plan order (filtered by user's acceptance form — blanket walks all; fragmented walks named step IDs; conditional walks steps matching the risk predicate): a. (If critic_gate_threshold: required and rootnode-critic-gate installed) Submit step plan to critic-gate; APPROVE → continue; REQUEST_CHANGES → adjust + re-submit, cap 3 cycles; REJECT → halt. b. Apply the action (edit / create / delete / modify / run). c. Run the step's validation. d. If validation fails, halt and report the failure with current state. Do not auto-rollback. e. If validation passes, log step completion and continue.
4. Run post-flight validation.
5. Append a CHANGELOG entry summarizing the remediation cycle.
6. Report: steps approved / total, steps executed / approved, steps skipped (with reason), critic-gate review summary (if applicable), files modified, findings closed, any halts.

Output: Phase 1 produces EXECUTION_PLAN.md. Phase 2 produces actual repo changes + CHANGELOG entry + execution report. Both phases are gated by explicit user acceptance between them.

---

When to Use This Skill

Use this Skill when:

• The user is planning a new Claude Code deployment for a delivery project (DESIGN mode)
• An existing Claude Code project has surfaced friction or needs a new pattern added (EVOLVE mode)
• The user is evaluating a tool, MCP server, Skill, hook, or pattern for inclusion in a CC deployment (RESEARCH mode)
• The user wants a reusable artifact for cross-project use — CLAUDE.md skeleton, agent role template, scope-authorization clause template (TEMPLATE mode)
• The user has finished designing a deliverable in chat and is preparing the chat→Code handoff bundle
• A HYGIENE_REPORT.md exists in the repo and the user wants to close the loop on it (REMEDIATE mode)

REMEDIATE routing

REMEDIATE handles the structural and placement-decision portions of a hygiene report. Direct-cleanup findings have a different route. Use this routing rule when a HYGIENE_REPORT.md is in play: