Autonomous Workflow

Foundation skill governing how Claude executes development workflows autonomously.

Iron Law

NO SKIPPING PHASES. Explore before Plan, Plan before Code, Code before Verify. Every phase produces an artifact.

Jumping to code without exploration is the #1 cause of rework. Jumping to "done" without verification is the #1 cause of bugs reaching review.

Explore > Plan > Code > Verify

Every multi-step workflow follows this loop:

1. EXPLORE: Gather context. Use Agent(Explore) subagents for unfamiliar code. Parallel Bash for independent queries (git status, issue details, task list). Read referenced files. When LSP is available: use goToDefinition to trace code paths from issue keywords to implementation, and findReferences to assess the impact of planned changes — this enhances text-based grep searches with semantic understanding.
2. PLAN: Decompose work. TaskCreate for each deliverable. Set dependencies with addBlockedBy. Display the plan for visibility.
3. CODE: Execute tasks. TaskUpdate(in_progress) before starting. Implement. Commit incrementally (Tier 1). TaskUpdate(completed) after verification. When LSP is available: use hover to understand types and signatures of existing code before modifying it.
4. VERIFY: Prove it works. Four mandatory verification layers:

a. Static: Run quality commands (lint, test, typecheck) in parallel. When LSP diagnostics are available (lsp.diagnosticsAsQuality), collect them as an additional quality signal — errors are P1, warnings are P2. LSP diagnostics complement, never replace, CLI-based checks. b. Runtime: Build the project, start it, verify at runtime. If anything fails, enter the debug-fix-retest loop (bounded by closedLoop.maxDebugIterations). c. Review: Self-review with fix-forward — fix P1/P2 findings immediately, don't just report them. d. Verdict: Independent judgment — dispatch verdict-judge agent (when verdict.enabled) with acceptance criteria + evidence bundle. The judge has no access to code-writing rationale, diff, or decision journal. It evaluates outcomes, not process. Each criterion receives PASS/FAIL/NEEDS-HUMAN-REVIEW. FAIL verdicts trigger fix loops; NEEDS-HUMAN-REVIEW escalates to user.

Task-Driven Progress

Use Task tools as first-class workflow primitives:

Tasks have clear subjects (imperative form) and descriptions with acceptance criteria.

Per-Task Verification Gate

A task may NOT be marked completed (TaskUpdate(taskId, status: "completed")) until ALL of the following conditions are met:

1. All tests pass — both existing tests and any new tests written for this task. If any test fails, the task enters the debug-fix-retest loop and remains in_progress until tests pass or the user is escalated to.

1. Verification evidence captured — the verification command from the task description has been run and its output recorded as evidence for this task's acceptance criterion. Evidence must be collected at task-completion time, not deferred to VERIFY phase.

1. No out-of-context files — all files modified during this task have been classified. Any out-of-context files must be resolved (moved to a separate commit, removed, or explicitly approved by the user) before the task completes.

1. TDD cycle completed — when settings.json → testing.tddMode is enforce (the default), the full RED-GREEN-REFACTOR cycle must be observed:

• RED: A failing test was written before implementation
• GREEN: The simplest code was written to make the test pass
• REFACTOR: Code was cleaned up with tests still passing

If any condition is not met, TaskUpdate(completed) is blocked. The workflow must not advance to the next task. This gate is the primary quality enforcement point — the VERIFY phase provides independent confirmation, not first-pass verification.

Three-Tier Action Classification

Tier configuration is in settings.json under tiers. Actions can be promoted (journal→confirm) but never demoted (confirm→journal).

AskUserQuestion Tool Enforcement

When a command or skill says "use the AskUserQuestion tool", you MUST invoke the AskUserQuestion tool — do not substitute plain text output. The tool provides structured selectable options that plain text cannot replicate. Supply contextual options appropriate to the situation.

Decision Journal Protocol

• Init: Create {journal-dir}/issue-{N}.md at branch creation
• Log: PostToolUse hooks auto-log file changes and commits
• Structured entries: Skills add timestamped entries with category, decision, rationale, risk
• Summarize: Condense journal for PR body (public entries only, internal redacted)

Journal dir defaults to .decisions/, configurable in settings.

Anti-estimation guard for journal entries: journal entries MUST NOT include calendar-time estimates (weeks, days, hours, sprints, ETAs, "by Friday"). Use t-shirt sizing (S/M/L) only when the user has explicitly asked for size context. Describe work in terms of artifacts and tool calls, not wall-clock duration. See skills/llm-operator-principles/SKILL.md. This guard exists because journal entries are the most common surface where calendar-time framings leak through and anchor downstream deferral.

Parallel Execution

Dispatch independent operations in a single message:

• Multiple Bash calls for independent git queries
• Multiple Agent calls for independent review facets
• Never parallelize operations that depend on each other's output

Bounded Verification

Quality check loops have max iterations from settings.json. These ceilings are safety nets against true infinite loops, NOT planned stop points — see skills/llm-operator-principles/SKILL.md:

1. Run quality commands
2. If failures, fix and re-run
3. Approaching qualityCheckMaxIterations without convergence is a signal to re-check understanding (are two findings in tension? are you fixing the wrong thing?), not a budget to stop at. Continue iterating until convergence.
4. Only halt for genuine non-convergence: the same failure persists across the last 3 iterations with no progress AND the ceiling is actually reached. In that case, file a six-field Proactive-Autonomy escalation citing "genuinely ambiguous architecture decision" — NOT finding-triage.
5. Never loop indefinitely past the ceiling without surfacing the non-convergence diagnostic.

Stop Conditions

Sensitivity Classification

• public: Safe for PR bodies, comments, logs
• internal: Security rationale, credential handling, vulnerability details
• Never include internal details in public-facing outputs

Closed-Loop Mandate

The debug-fix-retest loop is mandatory — do NOT report failures and move on, DO fix them yourself.

Minimum verification by project type:

• Web apps: Build + start dev server + smoke test endpoints
• CLI tools: Build + run with --help + run with sample input
• Libraries: Build + run public API against sample data
• Static sites: Build + serve locally + verify pages load
• Whitelisted skip categories (markdown-only, config-only, dependency-bump-only — see runtime-verification skill): Static checks only, with the specific evidence the whitelist requires. Any other skip requires a Proactive-Autonomy escalation.

The loop is bounded by closedLoop.maxDebugIterations (default 5). After max iterations, escalate to user — never silently skip.

Graceful Degradation

Rationalization Prevention

Proactive Autonomy with Prepared Escalation

Agents are teammates, not tools waiting for instructions. The operating principle is:

1. Try first — attempt to resolve ambiguity yourself using available context, codebase search, and reasoning before involving a human.
2. Present options, not questions — when you genuinely cannot resolve, present 2-3 concrete options with trade-offs and a recommendation. Never ask "what should I do?" or "how should we proceed?"
3. Irreversible actions always ask — Tier 3 operations (merge, release, force operations) require human confirmation regardless of confidence.
4. Reversible actions just execute — Tier 1 actions (commits, branch creation, file edits) and Tier 2 actions (push, PR creation) proceed autonomously or with journal logging.

Six-Field Escalation Template

Every escalation to a human MUST follow this structure. Omitting fields is not permitted.

When Escalation IS Required

• Irreversible actions — merge, release, force-push, data deletion, production deploys
• Genuinely ambiguous preference decisions — two valid approaches where the trade-off depends on user priorities the agent cannot infer (product/architecture decisions only, NOT finding triage)
• Out-of-whitelist runtime skip requests — skipping verification for a category not in the markdown-only, config-only, or dependency-bump-only whitelist
• Verification ceilings exceeded after re-checking understanding — only after maxDebugIterations or fixForwardMaxIterations have been fully exhausted AND the agent has re-checked whether findings are in tension or being misunderstood. Approaching a ceiling is not a trigger; the ceiling is a safety net, not a budget. See skills/llm-operator-principles/SKILL.md.

When Escalation is NOT Needed

• Reversible local actions — file edits, commits, branch creation, staging (Tier 1)
• Actions within the three-tier safety framework — Tier 1 and Tier 2 actions that are already classified as autonomous or journal-and-proceed
• Decisions with clear policy — the skill, command, or governance framework already specifies the correct action
• Fixing any findings (P1/P2/P3) — finding triage is NEVER a valid escalation trigger. Findings are work, not decisions. Fix in this PR by default. See skills/llm-operator-principles/SKILL.md and references/escalation-format.md.
• Approaching but not exceeding an iteration ceiling — fixForwardMaxIterations, reviewCycleLimit, qualityCheckMaxIterations are safety nets, not budgets. Iteration 7 of 10 is the middle of the safety margin, not "the ceiling."

Anti-Patterns