rootnode-cc-design v4.1.0A

Immutable. This exact content is served forever at /api/v1/blob/4450dff9f436b6c1.

---
name: rootnode-cc-design
description: >-
  Designs Claude Code prompts and CC environments. Produces CLAUDE.md drafts,
  agent topologies, scope-authorization frameworks, halt triggers,
  Skills/hooks/MCP plans, chat-to-CC handoff specs, and EXECUTION_PLAN.md
  remediation plans. Five modes: DESIGN (new CC deployments), EVOLVE (updates
  from friction), RESEARCH (evaluate a CC tool/pattern), TEMPLATE (reusable
  artifacts), REMEDIATE (consume hygiene findings → produce + execute plan).
  Use when user says "design CC for X", "build CC environment", "design
  CLAUDE.md", "build a CC prompt", "design a CC prompt for X", "write a
  session prompt", "we hit X friction in CC", "should we adopt Y for CC",
  "give me a CLAUDE.md skeleton", "remediate the hygiene findings". Do NOT
  use REMEDIATE for direct cleanup (Cat 1–10 — use rootnode-repo-hygiene
  Phase 2; REMEDIATE handles Cat 11–14 + 7-layer leaks). Do NOT use for
  hygiene scanning (use rootnode-repo-hygiene). Do NOT use for chat prompts
  (rootnode-prompt-validation) or chat Projects (rootnode-project-audit).
license: Apache-2.0
metadata:
  author: rootnode
  version: "4.1.0"
  predecessor: "rootnode-cc-design v4.0"
  original-source: "root.node seed Project KFs (post-Phase 27/28 methodology absorption: root_AGENT_ENVIRONMENT_ARCHITECTURE.md, root_CC_ENVIRONMENT_GUIDE.md, root_AGENT_ANTI_PATTERNS.md) + accumulated CC deployment research (2026-05-04). v2 evolved REMEDIATE acceptance flow (three approval forms, step-level risk tags) and critic-gate composition (required/optional) to align with rootnode-repo-hygiene v1's contracts. Substantive rebuild of cc-anti-patterns.md to canonical numbering. Brand-surface clean (cchq references stripped or restructured; hyge contamination anonymized to \"production CC deployment 2026-05-04\"). v4.1 adds the end-state assertion rule to Step 4 output standards (observed 2026-09-07: a file-replacement prompt asserted a pre-state line count that had gone stale between authoring and execution, halting the run), and absorbs the orchestrator/worker delegation architecture — role-tiered subagents, the delegation-brief contract, the Builder-to-Refuter loop, and mechanism-enforced delegation caps — grounded in Anthropic subagent documentation verified 2026-09-09 and in community practitioner reports graded Tier 5 (signal-only)."
  discipline_post: phase-30
---

# 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 include an explicit delegation cap. The prose cap explains the intent; the cap itself is placed in `settings.json` or agent frontmatter, because a cap that only exists as CLAUDE.md prose is enforcement-as-preference (`cc-anti-patterns.md` §4.4). See the cap mechanism table in `references/cc-delegation-patterns.md` and the countermeasure template in `root_OPTIMIZATION_REFERENCE.md` (subagent over-delegation tendency). Every Claude Code setting a draft names — a `CLAUDE_CODE_*` variable, its default, a managed-settings key — carries the dated product-fact marker on every line that names it — in JSON, on the line after the block — per the emission rule above that table; the settings drift with releases, and an unmarked setting reads as verified.

**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.

## v4.1 update — delegation architecture

Role tiering is a design decision, not a default: every subagent resolves a model, an effort level, a tool set, an isolation mode, and a return contract, and leaving them unset bills mechanical work at orchestrator rates. The role table is a menu, not a roster: add a role only for work the orchestrator cannot do from what it already holds. Integrating what the agents returned — composing the report, merging the result — is the orchestrator's own row, not a new role. The landscape-independent rule is that reviewer capability is greater than or equal to builder capability. **Explore no longer defaults to Haiku** — as of Claude Code v2.1.198 it inherits the main conversation's model, capped at Opus on the Claude API, so a cheap scout requires a project `Explore` defined with `model: haiku`. **[Anthropic docs, verified 2026-09-09]** Recommend the Builder-to-Refuter loop as the default coding topology and escalate to the four-agent verification topology only when the agent-warranted test shows verification perspectives that conflict by design. Every delegation carries a brief and a numeric return cap; unbounded delegation is the mechanism behind both subagent over-delegation and orchestrator context bloat.

Role table, brief fields, loop mechanics, cap mechanisms, and the reasoning behind each are in `references/cc-delegation-patterns.md`.

## 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, scope authorization and the ultracode default.** Every DESIGN MODE plan and every EVOLVE MODE update explicitly includes all three — ultracode stays off and is opted into per task, stated even when the plan proposes no topology. Non-negotiable.
- **Assert the END state, never the PRE state.** A prompt that states what a file currently contains goes stale the moment anything touches the working tree between authoring and execution, and nothing detects that staleness until CC halts mid-run. Write the starting condition as report-only ("report `wc -l` and `sha256sum`") and bind the halt to a post-action digest ("HALT if the resulting hash ≠ `<sha256>`"). Never write "expect N lines" as a precondition. **Corollary:** every prompt that replaces a file carries that file's digest, computed in the same turn the file is produced so the digest and the bytes cannot drift apart. The gate is for files whose bytes the prompt author holds. When the agent generates the change — a migration, a refactor — no digest exists at authoring time: assert the end state with the check that defines done, such as the suite or the type-check, not a digest over generated files. Bind the digest to LF-normalized content, never to raw bytes: on a Windows checkout with `core.autocrlf=true` git stores the LF blob, so a raw-bytes gate on a text file cannot be satisfied by any commit. State the normalization in the prompt; do not assert the target repo's git config unless the brief establishes it. Rationale and the observed instance are in `references/cc-prompt-design-patterns.md`. `[generalizable]`
- **Delegation briefs are complete or absent.** Any role the plan names carries a model, an effort level, a tool set, an isolation mode, and a return contract including a numeric length cap. Verification clauses name external artifacts; never instruct an agent to re-check its own output.
- **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, competing hypotheses and instrument fit for diagnostic prompts).

### 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-delegation-patterns.md` | When the deployment plan involves subagents, model tiering, parallel work, or delegation caps. Role table (model / effort / tools / isolation / return), the eight-field delegation brief, the Builder-to-Refuter loop, orchestrator context hygiene, and the cap mechanism table. |
| `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:

| Finding type | Owner | Action |
|---|---|---|
| Cat 1–10 (permissions, hooks, parent-vestige, stale code, Skills hygiene, etc.) | `rootnode-repo-hygiene` Phase 2 | Direct cleanup. Run repo-hygiene Phase 2 against the `[APPROVED]` markers in the report. **Not** REMEDIATE territory. |
| Cat 11–14 (structural, including process-abstraction candidates) | `rootnode-cc-design` REMEDIATE | Structural fix recipes from `cc-anti-patterns.md`; conflict resolution; 7-layer placement validation. |
| 7-layer leak findings | `rootnode-cc-design` REMEDIATE | Placement-decision required; route to REMEDIATE for layer reassignment. |

Phase 1 surfaces this routing explicitly: when REMEDIATE is invoked on a report containing Cat 1–10 findings, the response names them as out-of-scope and recommends the repo-hygiene Phase 2 path before walking the in-scope findings.

Do NOT use this Skill when:
- The user wants to scan or audit an existing CC environment for hygiene issues / anti-patterns (use rootnode-repo-hygiene if available — that Skill produces the HYGIENE_REPORT.md this Skill consumes)
- The user wants to evaluate or score a chat prompt (use rootnode-prompt-validation if available)
- The user wants to compile a chat prompt or scaffold a chat Project (use rootnode-prompt-compilation if available)
- The user wants to audit a chat-based Claude Project's Custom Instructions or knowledge files (use rootnode-project-audit if available — different surface from CC)
- The user is doing non-CC delivery work that doesn't involve Claude Code at all

---

## Troubleshooting

**Skill produces generic CLAUDE.md not tailored to the project:** The design brief was missing or thin. Generate the brief first via the 5-question interview before producing the deployment plan. The brief is the grounding artifact — without it, output drifts toward generic patterns.

**Skill recommends rootnode runtime tooling for a project that doesn't need it:** The tool/agent gap discipline was skipped. For each runtime Skill, name the specific operational gap it fills in this project. If you can't, don't recommend it. See SKILL.md Step 6.

**Skill outputs are too long / context-heavy:** TEMPLATE mode is a useful pressure release — extract the reusable structural pattern into a `{project_code}_template_*` or `shared_template_*` artifact and reference it from delivery-project briefs. Avoid re-deriving the same pattern across multiple project deployments.

**Skill produces "vibe" recommendations without source backing:** Source discipline was skipped. Every substantive claim about CC behavior, MCP capability, or pattern needs an inline source tag. See `references/source-grading-and-tagging.md`. If a tag is `[speculation]`, that's acceptable as long as it's marked.

**User asks for a quick answer and the brief workflow feels heavy:** Skip the brief for narrow asks (one section, one prompt, one review). The brief grounds multi-faceted design work, not single-shot questions. Use judgment.

**A CC prompt halted because its stated starting state was wrong:** The prompt asserted a pre-state ("expect N lines", "the file currently contains X") that went stale between authoring and execution — commonly because the replacement file was already staged, or another pass touched the tree. The guard was correct; the assertion was not. Fix at the prompt, not at the guard: make the starting condition report-only and bind the halt to a post-action digest. See Step 4, *Assert the END state, never the PRE state*. Resolve the specific stuck run by giving CC the expected `sha256sum` and instructing it to skip the already-satisfied step on an exact match.

**The orchestrator session fills up even though the work was delegated:** Delegation isolates the agent's working set, not its report. An agent that returns a full file, a full test log, or a full diff moves the flood one layer out and then back in. Fix at the brief: set a return-length cap, require locations and findings rather than contents, and route oversized results to a scratch file the next agent reads. See `references/cc-delegation-patterns.md`.

**User asks the Skill to "audit my CC project" — the Skill claims this is rootnode-repo-hygiene's territory but the user disagrees:** Different verbs. rootnode-repo-hygiene scans for hygiene issues against the 15-anti-pattern catalog and produces findings. This Skill *consumes* those findings (REMEDIATE mode) or designs new artifacts from scratch (DESIGN/EVOLVE/TEMPLATE). If the user wants a "review" of a draft CLAUDE.md *during design work* (not against a deployed environment), that fits EVOLVE mode framed as "review and propose deltas." If the user wants the deployed-environment scan, route to rootnode-repo-hygiene.

**REMEDIATE mode invoked but no HYGIENE_REPORT.md exists in the repo:** The Skill cannot proceed. Two options: (a) ask the user to run rootnode-repo-hygiene first to produce the report, then re-invoke REMEDIATE; (b) accept findings pasted directly into the conversation, but recommend the file-based workflow for repeatability. Plan generation without source findings is anti-pattern — the loop only closes when there's a defined input to remediate against.

**REMEDIATE Phase 2 step validation fails:** Halt. Do not auto-rollback. Report which step failed, which validation, and the current repo state (what was completed before the halt). The user decides whether to manually revert, fix forward, or re-plan. Safety-via-halt is the v2 discipline; rollback semantics are out of scope.

**Two REMEDIATE conflict resolutions seem reasonable for the same finding cluster:** Phase 1 still produces a plan, but the conflicting steps are marked `requires_user_choice: true` and Phase 2 will halt at those steps for explicit choice. Don't silently choose one — the conflict surfaced because the proper sequencing isn't unambiguous, and that's a user decision, not a Skill decision.

**EVOLVE mode keeps re-deriving the same fix:** This is a signal the fix should be promoted to a TEMPLATE. After the second invocation of the same pattern, extract it as a template and reference from future EVOLVE outputs.