chore(templates): merge Karpathy principles into Process Discipline

AndreJorgeLopes · claude · AndreJorgeLopes · commit 05c4d068ae48 · 2026-04-23T16:56:05.000+02:00
Fold Andrej Karpathy's four LLM-coding principles (Think before coding,
Simplicity first, Surgical changes, Goal-driven execution) into
CLAUDE.md.tmpl's Process Discipline section as phase anchors. Add a
Discipline Inheritance intro to AGENTS.md.tmpl and sharpen five
workflow skills with concrete inserts (new-feature, spec-feature,
codebase-walkthrough, finish-feature, pre-push-check). Mirror copies
in skills/ updated in lockstep. Editorial change; no version bump.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/devflow-plugin/commands/codebase-walkthrough.md b/devflow-plugin/commands/codebase-walkthrough.md
@@ -51,6 +51,7 @@ Guide the user through a deep technical walkthrough of the codebase areas affect
    - State what you believe to be true
    - Verify it against the ticket, Confluence docs, or codebase — do NOT present unverified assumptions as facts
    - If you can't verify, say "I need to verify this" and check
+   - Better to surface a confused assumption than hide it. Name what's unclear before proceeding.
 
 7. **Present the walkthrough.** Structure it so it takes ~30 minutes to read:
 
diff --git a/devflow-plugin/commands/finish-feature.md b/devflow-plugin/commands/finish-feature.md
@@ -35,15 +35,23 @@ You are finishing a feature. Run the full completion pipeline before handing off
 
    **If checks fail**, report the failures clearly and stop. Do NOT continue past this step with failing checks. Help the user fix issues if they ask.
 
-3. **Stage and commit.** If there are uncommitted changes:
+3. **Diff self-test (Surgical Changes).** Run `git diff origin/main...HEAD` and scan for:
+
+   - Changes unrelated to the feature (formatting, adjacent refactors, comment cleanup).
+   - Dead-code removals beyond orphans YOUR changes created.
+   - "Improvements" made in passing.
+
+   If any exist, surface them to the user. Offer to move them to a separate PR or revert. Don't silently ship them.
+
+4. **Stage and commit.** If there are uncommitted changes:
    - Stage relevant changes: `git add -A`
    - Analyze the full diff to generate a commit message:
      - Follow conventional commits format (`feat:`, `fix:`, `refactor:`, etc.)
      - Be concise (1-2 lines)
      - Reference the ticket ID if present in the branch name
    - Present the commit message to the user for approval before committing.
 
-4. **Push and create PR.** Push the branch and create a pull request:
+5. **Push and create PR.** Push the branch and create a pull request:
 
    ```bash
    git push -u origin HEAD
@@ -62,13 +70,13 @@ You are finishing a feature. Run the full completion pipeline before handing off
 
    Present the PR URL to the user.
 
-5. **Retain session learnings.** Review the session and retain important discoveries:
+6. **Retain session learnings.** Review the session and retain important discoveries:
    - Architecture decisions made during this feature
    - Gotchas or non-obvious patterns encountered
    - Bug root causes and fixes
    - Use Hindsight `retain` for each learning, tagged with the project name
 
-6. **Present the summary and hand off cleanup:**
+7. **Present the summary and hand off cleanup:**
 
    ```
    ## Feature Complete
diff --git a/devflow-plugin/commands/new-feature.md b/devflow-plugin/commands/new-feature.md
@@ -46,6 +46,8 @@ You have been launched inside a feature worktree. Your job is to orient yourself
 
 4. **Ask what the feature is about.** If the branch name is descriptive enough, summarize your understanding and ask for confirmation. Otherwise, ask the user to describe the feature.
 
+   **Don't guess from the branch name.** If the branch is descriptive, summarize your reading in one sentence and ask for confirmation. If it leaves gaps (what behavior changes, what success looks like), ask BEFORE recalling more. Silent interpretations compound.
+
 5. **Offer codebase walkthrough (optional).** Ask the user:
 
    > "Would you like a codebase walkthrough before we start? This traces the full end-to-end flow affected by this task, shows you the actual code at each step, and identifies the key files. Useful if this is an unfamiliar area of the codebase."
@@ -61,5 +63,6 @@ You have been launched inside a feature worktree. Your job is to orient yourself
 - Never skip the brainstorming step for non-trivial features.
 - The codebase walkthrough is optional but recommended for unfamiliar areas.
 - If the branch name contains a ticket ID, use it as a namespace prefix in all Hindsight interactions.
+- Surface any assumption the branch name or recalled memories lead you to make. The user is one line away — ask before guessing.
 
 $ARGUMENTS
diff --git a/devflow-plugin/commands/pre-push-check.md b/devflow-plugin/commands/pre-push-check.md
@@ -17,6 +17,7 @@ You are about to push code. Run the full pre-push quality pipeline before pushin
    Capture and parse the output. This uses Claude Code (primary) or OpenCode (fallback) to review against `.devflow/checks/*.md` rules. If neither CLI is available, fall back to running the project's lint and type-check commands directly (e.g., `yarn lint`, `yarn build`).
 
 3. **Self-review the diff against CLAUDE.md**. Read the project's `CLAUDE.md` file and review the staged changes against its rules:
+   - **Scope discipline**: every changed line traces to the task. No speculative abstractions, no adjacent refactors, no dead-code removals beyond orphans created by this change.
    - Are naming conventions followed?
    - Are the architectural patterns respected (clean architecture layers)?
    - Are imports using the correct path aliases?
@@ -44,6 +45,7 @@ You are about to push code. Run the full pre-push quality pipeline before pushin
    - [PASS/FAIL] [details]
 
    ### CLAUDE.md Compliance
+   - [PASS/WARN/FAIL] Scope discipline (every line traces to task)
    - [PASS/WARN/FAIL] Naming conventions
    - [PASS/WARN/FAIL] Architecture patterns
    - [PASS/WARN/FAIL] Import paths
diff --git a/devflow-plugin/commands/spec-feature.md b/devflow-plugin/commands/spec-feature.md
@@ -11,6 +11,7 @@ You are speccing a new feature. This command enforces a structured planning proc
    - Why it's needed (motivation, problem it solves)
    - Any constraints or requirements mentioned
    - If arguments are vague, ask clarifying questions before proceeding.
+   - If the feature request has multiple valid interpretations, list them and ask the user to pick — don't silently commit to one.
 
 2. **Recall architecture knowledge**. Use the Hindsight `recall` tool to retrieve:
    - Past architectural decisions related to this domain
@@ -51,6 +52,12 @@ You are speccing a new feature. This command enforces a structured planning proc
    - [recalled hard rules that apply]
    - [architectural decisions that constrain the approach]
 
+   ## Non-goals
+
+   Explicitly out of scope:
+   - [thing we are NOT building]
+   - [thing we are NOT refactoring]
+
    ## Edge Cases
 
    - [edge case 1]
@@ -76,6 +83,7 @@ You are speccing a new feature. This command enforces a structured planning proc
 6. **Present the spec** to the user for review. Ask:
    - Does this match your intent?
    - Are there constraints I'm missing?
+   - Is there a simpler approach we're missing?
    - Should we adjust the scope?
 
 7. **Retain the architectural decisions** from this spec using the Hindsight `retain` tool, so they're available in future sessions.
diff --git a/skills/code-review/pre-push-check.md b/skills/code-review/pre-push-check.md
@@ -17,6 +17,7 @@ You are about to push code. Run the full pre-push quality pipeline before pushin
    Capture and parse the output. This uses Claude Code (primary) or OpenCode (fallback) to review against `.devflow/checks/*.md` rules. If neither CLI is available, fall back to running the project's lint and type-check commands directly (e.g., `yarn lint`, `yarn build`).
 
 3. **Self-review the diff against CLAUDE.md**. Read the project's `CLAUDE.md` file and review the staged changes against its rules:
+   - **Scope discipline**: every changed line traces to the task. No speculative abstractions, no adjacent refactors, no dead-code removals beyond orphans created by this change.
    - Are naming conventions followed?
    - Are the architectural patterns respected (clean architecture layers)?
    - Are imports using the correct path aliases?
@@ -44,6 +45,7 @@ You are about to push code. Run the full pre-push quality pipeline before pushin
    - [PASS/FAIL] [details]
 
    ### CLAUDE.md Compliance
+   - [PASS/WARN/FAIL] Scope discipline (every line traces to task)
    - [PASS/WARN/FAIL] Naming conventions
    - [PASS/WARN/FAIL] Architecture patterns
    - [PASS/WARN/FAIL] Import paths
diff --git a/skills/process-discipline/codebase-walkthrough.md b/skills/process-discipline/codebase-walkthrough.md
@@ -51,6 +51,7 @@ Guide the user through a deep technical walkthrough of the codebase areas affect
    - State what you believe to be true
    - Verify it against the ticket, Confluence docs, or codebase — do NOT present unverified assumptions as facts
    - If you can't verify, say "I need to verify this" and check
+   - Better to surface a confused assumption than hide it. Name what's unclear before proceeding.
 
 7. **Present the walkthrough.** Structure it so it takes ~30 minutes to read:
 
diff --git a/skills/process-discipline/spec-feature.md b/skills/process-discipline/spec-feature.md
@@ -11,6 +11,7 @@ You are speccing a new feature. This command enforces a structured planning proc
    - Why it's needed (motivation, problem it solves)
    - Any constraints or requirements mentioned
    - If arguments are vague, ask clarifying questions before proceeding.
+   - If the feature request has multiple valid interpretations, list them and ask the user to pick — don't silently commit to one.
 
 2. **Recall architecture knowledge**. Use the Hindsight `recall` tool to retrieve:
    - Past architectural decisions related to this domain
@@ -51,6 +52,12 @@ You are speccing a new feature. This command enforces a structured planning proc
    - [recalled hard rules that apply]
    - [architectural decisions that constrain the approach]
 
+   ## Non-goals
+
+   Explicitly out of scope:
+   - [thing we are NOT building]
+   - [thing we are NOT refactoring]
+
    ## Edge Cases
 
    - [edge case 1]
@@ -76,6 +83,7 @@ You are speccing a new feature. This command enforces a structured planning proc
 6. **Present the spec** to the user for review. Ask:
    - Does this match your intent?
    - Are there constraints I'm missing?
+   - Is there a simpler approach we're missing?
    - Should we adjust the scope?
 
 7. **Retain the architectural decisions** from this spec using the Hindsight `retain` tool, so they're available in future sessions.
diff --git a/skills/worktree-flow/finish-feature.md b/skills/worktree-flow/finish-feature.md
@@ -35,15 +35,23 @@ You are finishing a feature. Run the full completion pipeline before handing off
 
    **If checks fail**, report the failures clearly and stop. Do NOT continue past this step with failing checks. Help the user fix issues if they ask.
 
-3. **Stage and commit.** If there are uncommitted changes:
+3. **Diff self-test (Surgical Changes).** Run `git diff origin/main...HEAD` and scan for:
+
+   - Changes unrelated to the feature (formatting, adjacent refactors, comment cleanup).
+   - Dead-code removals beyond orphans YOUR changes created.
+   - "Improvements" made in passing.
+
+   If any exist, surface them to the user. Offer to move them to a separate PR or revert. Don't silently ship them.
+
+4. **Stage and commit.** If there are uncommitted changes:
    - Stage relevant changes: `git add -A`
    - Analyze the full diff to generate a commit message:
      - Follow conventional commits format (`feat:`, `fix:`, `refactor:`, etc.)
      - Be concise (1-2 lines)
      - Reference the ticket ID if present in the branch name
    - Present the commit message to the user for approval before committing.
 
-4. **Push and create PR.** Push the branch and create a pull request:
+5. **Push and create PR.** Push the branch and create a pull request:
 
    ```bash
    git push -u origin HEAD
@@ -62,13 +70,13 @@ You are finishing a feature. Run the full completion pipeline before handing off
 
    Present the PR URL to the user.
 
-5. **Retain session learnings.** Review the session and retain important discoveries:
+6. **Retain session learnings.** Review the session and retain important discoveries:
    - Architecture decisions made during this feature
    - Gotchas or non-obvious patterns encountered
    - Bug root causes and fixes
    - Use Hindsight `retain` for each learning, tagged with the project name
 
-6. **Present the summary and hand off cleanup:**
+7. **Present the summary and hand off cleanup:**
 
    ```
    ## Feature Complete
diff --git a/skills/worktree-flow/new-feature.md b/skills/worktree-flow/new-feature.md
@@ -46,6 +46,8 @@ You have been launched inside a feature worktree. Your job is to orient yourself
 
 4. **Ask what the feature is about.** If the branch name is descriptive enough, summarize your understanding and ask for confirmation. Otherwise, ask the user to describe the feature.
 
+   **Don't guess from the branch name.** If the branch is descriptive, summarize your reading in one sentence and ask for confirmation. If it leaves gaps (what behavior changes, what success looks like), ask BEFORE recalling more. Silent interpretations compound.
+
 5. **Offer codebase walkthrough (optional).** Ask the user:
 
    > "Would you like a codebase walkthrough before we start? This traces the full end-to-end flow affected by this task, shows you the actual code at each step, and identifies the key files. Useful if this is an unfamiliar area of the codebase."
@@ -61,5 +63,6 @@ You have been launched inside a feature worktree. Your job is to orient yourself
 - Never skip the brainstorming step for non-trivial features.
 - The codebase walkthrough is optional but recommended for unfamiliar areas.
 - If the branch name contains a ticket ID, use it as a namespace prefix in all Hindsight interactions.
+- Surface any assumption the branch name or recalled memories lead you to make. The user is one line away — ask before guessing.
 
 $ARGUMENTS
diff --git a/templates/AGENTS.md.tmpl b/templates/AGENTS.md.tmpl
@@ -3,6 +3,17 @@
 > Coordination rules for AI agents working in this project.
 > Generated by `devflow init`.
 
+## Discipline Inheritance
+
+All agents follow the Process Discipline defined in CLAUDE.md:
+
+1. **Think before coding** — surface assumptions, name confusion.
+2. **Simplicity first** — minimum code, no speculative abstractions.
+3. **Surgical changes** — every changed line traces to the request.
+4. **Goal-driven execution** — define success criteria before coding.
+
+Role boundaries below do not override these principles. An Implementer under deadline pressure still surfaces assumptions. A Reviewer still flags overcomplication. A Tester still writes tests that verify defined goals.
+
 ## Agent Roles
 
 ### Implementer
@@ -76,12 +87,14 @@ recall("{{PROJECT_NAME}}-<role>: <query>")
 
 **Ask the developer when:**
 
-- Requirements are ambiguous and no prior memory clarifies them
-- A change would affect more than 10 files
-- You encounter a security concern
-- Tests are failing for reasons unrelated to your changes
-- You need access to external services or credentials
-- Two agents have conflicting instructions
+- Assumptions diverge — multiple valid interpretations exist and recall doesn't resolve them.
+- A simpler approach exists and you want to push back on the requested one.
+- Requirements are ambiguous and no prior memory clarifies them.
+- A change would affect more than 10 files.
+- You encounter a security concern.
+- Tests are failing for reasons unrelated to your changes.
+- You need access to external services or credentials.
+- Two agents have conflicting instructions.
 
 **Do NOT ask the developer when:**
 
diff --git a/templates/CLAUDE.md.tmpl b/templates/CLAUDE.md.tmpl
@@ -56,35 +56,51 @@ Good uses for reflect: identifying recurring issues, summarizing project evoluti
 
 ## Process Discipline
 
-Follow this workflow for any non-trivial task:
-
-### 1. Spec (Understand)
-
-- Recall relevant memories
-- Read the issue/request carefully
-- Identify what's being asked and what's ambiguous
-- Ask clarifying questions if requirements are unclear — don't guess
-
-### 2. Plan (Design)
-
-- Break the task into concrete steps
-- Identify files that need to change
-- Consider edge cases and failure modes
-- Write the plan down (use TodoWrite or equivalent)
-
-### 3. Implement (Build)
-
-- Follow the plan step by step
-- Mark tasks complete as you go
-- Run tests after each meaningful change
-- Retain discoveries and decisions in Hindsight
-
-### 4. Verify (Confirm)
-
-- Run the full relevant test suite
-- Self-review against the project's conventions
-- Verify the change actually solves the original problem
-- Do not claim "done" without evidence
+Four phases, each with a principle that anchors it.
+
+### 1. Spec (Understand) — *Think before coding*
+
+- Recall relevant memories first (Hindsight).
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+### 2. Plan (Design) — *Simplicity first*
+
+- Break the task into concrete steps with a verify check each.
+- Identify files that need to change; consider edge cases.
+- Minimum code that solves the problem — nothing speculative:
+  - No features beyond what was asked.
+  - No abstractions for single-use code.
+  - No "flexibility" or "configurability" unless requested.
+  - No error handling for impossible scenarios.
+- "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+- Write the plan down (TodoWrite or equivalent).
+
+### 3. Implement (Build) — *Surgical changes*
+
+- Follow the plan step by step; mark tasks complete as you go.
+- Touch only what you must:
+  - Don't "improve" adjacent code, comments, or formatting.
+  - Don't refactor what isn't broken.
+  - Match existing style, even if you'd do it differently.
+  - Remove imports/variables YOUR changes orphaned — leave pre-existing dead code alone unless asked.
+- Every changed line should trace directly to the user's request.
+- Retain discoveries and decisions in Hindsight as you go.
+
+### 4. Verify (Confirm) — *Goal-driven execution*
+
+Define success criteria BEFORE coding, not after. Transform vague tasks:
+
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+Then:
+- Run the full relevant test suite.
+- Self-review against project conventions.
+- Do not claim "done" without evidence.
 
 ## Worktree Workflow
 
