devflow-executing-tasks

Executing Tasks

Pre-flight

• git status (if repo). Dirty tree with files unrelated to the task → list them, confirm with user. Don't assume those changes are yours.
• State 3–5 assumptions about this task batch. Any that could be wrong → stop and ask before writing code.

Hard rules

1. Never edit unrelated files. Each task touches only what its goal requires.
2. Inspect before writing. Read 1–3 sibling files; match local patterns.
3. Minimal diffs. Smallest change that satisfies the task. No drive-by cleanups.
4. Preserve architecture. No refactors the plan didn't ask for.
5. TDD where behavior changes. Failing test first → implementation → green. Skip for pure config/text changes.
6. No completion claims without verification output.
7. Orphan cleanup. Your change orphans an import/variable/function → remove it. Pre-existing dead code: mention, don't touch.
8. Complexity check. After drafting: "would a senior engineer call this overcomplicated?" If yes, simplify.

Safety: never run git push, destructive SQL, or write secret-looking files unless the user explicitly asked — devflow hooks additionally deny most of these; report a denial as a blocker, never work around the guard. Operations outside the hook's reach (CI/CD edits, IAM/infra changes, dependency removals, long network-heavy commands) also require explicit user approval.

Per-task cycle

1. Goal — one verifiable line: "<what changes>" → verify: <specific check>.
2. Edit — surgical.
3. Verify — run the task's verification command (from the plan or the project profile docs/devflow/profile.md). Quote output.
4. Fix — if red, fix root cause. Respect the debug cap below.
5. Mark complete — tick the task's checkbox in the plan file. Move on.

Test-mode rules (canonical — all devflow test runs follow these)

• Manual — run NO test commands. List the exact commands for the user at each phase boundary. User reports failure → switch to debug flow.
• Autonomous — pipe every run to a file (<cmd> > <log> 2>&1). Read only the last 3 lines for pass/fail + counts. On failure: read last 80 lines, grep the error, read only the relevant block. Never dump a full log into context.
• Targeted (default) — run only the test classes you created or changed, same pipe-to-file pattern. Full suite once, at the final phase boundary, autonomous-style.

Debug attempt cap (canonical)

Per distinct error: attempt 1 (read error → hypothesis → fix), attempt 2 (re-read → revised hypothesis → fix). Still failing → STOP, return a blocker: exact error quoted, both attempts summarized, current root-cause hypothesis, what information would help. No runaway fix-test-fix loops.

Context hygiene (canonical)

1. Don't re-read a file after editing it — Edit errors on failure.
2. Never paste full file contents into conversation or subagent prompts — paths + line ranges.
3. Plan/spec: read once at session start, reference by task ID after.
4. Don't re-read files already read this session unless modified since.
5. Prefer Edit (small diff) over Read + Write (full file).
6. After a (user-requested) commit: report only SHA + file count + test summary.

Verification commands

Per-task and full-suite commands come from the project profile (docs/devflow/profile.md, written by devflow-discovery). No profile → load devflow-discovery to generate one. Per-stack command recipes live in ${CLAUDE_PLUGIN_ROOT}/skills/devflow-discovery/stack-recipes.md — consult only when the profile doesn't cover the stack.

Anti-bloat

• Don't restate plan content while implementing.
• Show only the changed hunk if narrating, never whole files.
• One line between tasks, no summary paragraphs.
• A task ballooning → stop and split it.