Default Workflow

Default Workflow Skill

Relationship to Dev Orchestrator

Normal execution path: This workflow is invoked as a sub-recipe by the dev-orchestrator skill via smart-orchestrator. You do NOT normally need to activate this skill directly.

User request → dev-orchestrator → smart-orchestrator recipe
    → default-workflow recipe (this skill's recipe)

Direct invocation is supported as a compatibility path when the dev-orchestrator is unavailable or when explicitly requested. In that case, use the recipe runner (see Execution Instructions below).

Workflow Graph

flowchart TD
    subgraph P1["Phase 1: Requirements Clarification"]
        S0[Step 0: Workflow Preparation] --> S1[Step 1: Prepare Workspace]
        S1 --> S2[Step 2: Clarify Requirements]
        S2 --> S2b[Step 2b: Analyze Codebase]
        S2b --> S2c{Ambiguity?}
        S2c -->|yes| S2d[Step 2c: Resolve Ambiguity]
        S2c -->|no| S3
        S2d --> S3[Step 3: Create GitHub Issue]
        S3 --> S3b[Step 3b: Extract Issue Number]
    end

    subgraph P2["Phase 2: Design"]
        S4[Step 4: Setup Worktree/Branch] --> S5[Step 5: Architecture Design]
        S5 --> S5b{API needed?}
        S5b -->|yes| S5c[Step 5b: API Design]
        S5b -->|no| S5d
        S5c --> S5d{Database needed?}
        S5d -->|yes| S5e[Step 5c: Database Design]
        S5d -->|no| S5f
        S5e --> S5f[Step 5d: Security Review]
        S5f --> S5g[Step 5e: Design Consolidation]
    end

    subgraph P3["Phase 3: Implementation"]
        S6[Step 6: Documentation] --> S6b[Step 6b: Doc Review]
        S6b --> S6c[Step 6c: Doc Refinement]
        S6c --> S7[Step 7: Write Tests - TDD]
        S7 --> S8[Step 8: Implement]
        S8 --> S8b[Step 8b: Integration]
        S8b --> S9[Step 9: Refactor]
        S9 --> S9b[Step 9b: Optimize]
    end

    subgraph P4["Phase 4: Testing & Review"]
        S10[Step 10: Pre-commit Review] --> S10b[Step 10b: Security Review]
        S10b --> S10c[Step 10c: Philosophy Check]
        S10c --> S11[Step 11: Incorporate Feedback]
        S11 --> S11b[Step 11b: Implement Feedback]
        S11b --> S12[Step 12: Run Pre-commit Hooks]
        S12 --> S13[Step 13: Local Testing]
    end

    subgraph P5["Phase 5: Version & PR"]
        S14[Step 14: Bump Version - MANDATORY] --> S15[Step 15: Commit & Push]
        S15 --> S16[Step 16: Create Draft PR]
        S16 --> S16b[Step 16b: Outside-In Fix Loop]
    end

    subgraph P6["Phase 6: PR Review - MANDATORY"]
        S17a[Step 17a: Testing-Evidence Gate] --> S17b[Step 17b: Reviewer Agent]
        S17b --> S17c[Step 17c: Security Review]
        S17c --> S17d[Step 17d: Philosophy Guardian]
        S17d --> S17e{Blocking issues?}
        S17e -->|yes| S17f[Step 17e: Address Blocking]
        S17e -->|no| S17g
        S17f --> S17g[Step 17f: Verification Gate]
        S17g --> S18a[Step 18a: Analyze Feedback]
        S18a --> S18b[Step 18b: Implement Feedback]
        S18b --> S18c[Step 18c: Push Changes]
        S18c --> S18d[Step 18d: Respond to Comments]
        S18d --> S18e[Step 18e: Verification Gate]
    end

    subgraph P7["Phase 7: Merge"]
        S19a[Step 19a: Philosophy Check] --> S19b[Step 19b: Patterns Check]
        S19b --> S19c[Step 19c: Zero-BS Verification]
        S19c --> S19d[Step 19d: Verification Gate]
        S19d --> S20[Step 20: Final Cleanup]
        S20 --> S20b[Step 20b: Push Cleanup]
        S20b --> S20c[Step 20c: Quality Audit]
        S20c --> S21[Step 21: PR Ready]
        S21 --> S22[Step 22: Ensure Mergeable]
        S22 --> S22b[Step 22b: Final Status]
    end

    P1 --> P2 --> P3 --> P4 --> P5 --> P6 --> P7

Purpose

This skill provides the standard development workflow for all non-trivial code changes in amplihack. It is normally executed as a sub-recipe by the dev-orchestrator via smart-orchestrator, but can also be invoked directly via the recipe runner.

The workflow defines the canonical execution process: from requirements clarification through design, implementation, testing, review, and merge. It ensures consistent quality by orchestrating specialized agents at each step and enforcing philosophy compliance throughout.

Canonical Sources

• Skill documentation: amplifier-bundle/skills/default-workflow/SKILL.md
• Executable source (recipe): amplifier-bundle/recipes/default-workflow.yaml

The skill and recipe are the authoritative representation. Legacy DEFAULT_WORKFLOW.md files are deprecated compatibility references only.

The two copies of this file — docs/claude/skills/default-workflow/SKILL.md and amplifier-bundle/skills/default-workflow/SKILL.md — are mirrored byte-for-byte. Because they live at different directory depths, cross-references to other repository docs must use a repo-relative inline-code path (for example docs/reference/foo.md) rather than a relative ../ markdown link, so the reference stays valid from both locations.

Execution Instructions

Normal path (via dev-orchestrator)

If you reached this skill via dev-orchestrator / smart-orchestrator, the recipe runner is already managing execution. Do not re-invoke the recipe runner. The orchestrator handles the full lifecycle including goal-seeking reflection loops.

Direct invocation (standalone)

If this skill is activated directly (not via dev-orchestrator), you MUST use the recipe runner — do NOT read a legacy markdown workflow file and follow steps manually:

The default workflow exposes one direct executable recipe interface:

amplihack recipe run default-workflow \
  -c task_description="TASK_DESCRIPTION_HERE" \
  -c repo_path="."

Or with verbose output:

cd /path/to/repo && amplihack recipe run default-workflow \
  -c task_description="TASK_DESCRIPTION_HERE" \
  -c repo_path="." \
  --verbose

Do NOT read legacy DEFAULT_WORKFLOW.md files and follow steps manually. The recipe runner enforces step ordering, recursion guards, checkpoints, and quality gates that manual execution cannot replicate.

Preferred: Use dev-orchestrator instead

For most tasks, invoke Skill(skill="dev-orchestrator") or use /dev <task> rather than activating this skill directly. The dev-orchestrator adds goal-seeking reflection, workstream decomposition, and adaptive error recovery on top of this workflow.

Command Interface

The default workflow exposes one direct executable recipe interface:

amplihack recipe run default-workflow \
  -c task_description="Add password reset support" \
  -c repo_path=.

The normal orchestrated interface remains:

amplihack recipe run smart-orchestrator \
  -c task_description="Add password reset support" \
  -c repo_path=.

Agent runtimes that support skills should enter through Skill(skill="dev-orchestrator") for DEV, INVESTIGATE, and HYBRID tasks. Direct Skill(skill="default-workflow") activation is for explicit standalone use or orchestrator-unavailable compatibility.

Step 13 Local Validation Contract

Step 13 is a mandatory outside-in local validation gate. It is agentic and toolchain-aware: the acting agent detects affected languages, manifests, lockfiles, package managers, entry points, changed files, and documented project commands before selecting validation commands.

The step must not require one global validation mechanism across all projects. Rust/Cargo, Node/npm, Python/uv, Go, .NET, and other detected toolchains each use their own local consumer-facing validation pattern. Python uvx is only a Python/uv-specific option when that project shape warrants it.

For the full evidence contract and examples, see docs/reference/default-workflow-step-13-validation.md.

Configuration

Generated preferences and session context name the canonical skill/recipe, not a legacy markdown path:

## Workflow Configuration

**Selected**: `default-workflow` skill/recipe
**Consensus Depth**: balanced

Use the `consensus-workflow` skill/recipe for: ambiguous requirements,
architectural changes, critical/security code, public APIs.

Do not render DEFAULT_WORKFLOW.md paths as selected workflow configuration. Those paths are compatibility references only.

Auto-Activation Triggers

This skill auto-activates for:

• Features spanning multiple files (5+)
• Complex integrations across components
• Refactoring affecting 5+ files
• Any non-trivial code changes requiring structured workflow

Note: The dev-orchestrator skill has higher priority and broader triggers. In most cases, it will activate first and invoke this workflow as a sub-recipe.

Known Failure Points & Resilience Guidance

Steps that commonly fail during workflow execution. Agents executing this workflow MUST apply the documented resilience patterns when encountering these steps.

Step 1 — Git Fetch (credential failure)

Failure: git fetch --all fails with exit 128 when the remote requires credentials that are not configured — most commonly Azure DevOps remotes where only the GitHub credential helper (gh auth git-credential) is wired up. Resilience: Fetch failure is caught and downgraded to a WARNING. The step continues with local branch state. ADO remotes (dev.azure.com, visualstudio.com) receive specific remediation guidance (az login, GCM install, PAT setup). The remote URL is never echoed to avoid leaking embedded credentials. See docs/recipes/issue-655-656-skill-invocation-and-fetch-resilience.md for details.

Step 3 — Issue Creation (label missing)

Failure: gh label create fails silently when labels cannot be created (permission denied, API timeout). Resilience: Label attachment is best-effort. If gh issue create --label fails, retry without --label. The issue itself is the critical artifact, not its labels.

Step 4 — Worktree Setup (non-main default branch)

Failure: Worktree setup aborts when a repository does not have origin/main, even though its remote default branch is master or develop. Resilience: Remote base detection runs before worktree creation. Prefer Git-verified origin/HEAD, then fall back to origin/master, then origin/develop. origin/HEAD may target origin/main, origin/master, origin/develop, or another remote default branch as long as Git verifies it as a remote-tracking ref under refs/remotes/origin/. If no supported remote base source exists, fail closed with a clear error; do not bootstrap from local HEAD or silently skip push/upstream setup.

Step 4 — Initial Push (network transient)

Failure: git push origin <branch> fails on fresh branch creation due to network issues. Resilience: Push failure at step 4 emits a visible WARNING and defers to step 15/16. Push is retried with bounded retry (3 attempts, 2s backoff) at commit-and-push time. Step 16 also retries push before PR creation.

Step 5b — Agent Output Artifact Missing

Failure: Agent output file not written or corrupted, causing downstream steps to fail with empty input. Resilience: If an agent step produces empty output, the recipe runner should surface the error visibly. Checkpoints after design (step 5e) and after implementation (step 8b) preserve partial work so the workflow can resume from the nearest safe point.

Step 15 — Push to Remote (upstream tracking, ancestry-aware)

Failure: git rev-list --count @{u}..HEAD fails when upstream is not set (first push scenario). Resilience: Detect missing upstream explicitly. If @{u} fails, push unconditionally instead of silently skipping. Retry push with backoff on transient network errors.

Failure (#978): A temporary workstream branch tracks an unrelated/stale upstream; a blind git pull --rebase replays already-integrated historical commits and produces add/add conflicts. Resilience: Step 15 is ancestry-aware. After fetching, it compares HEAD to @{u}:

• upstream is an ancestor of HEAD (behind == 0) → fast-forward push, preserving the tested commit identities (no history rewrite, no rebase);
• histories diverged (behind > 0) → fail closed with structured merge-base / ahead / behind evidence and require an explicit merge/rebase decision. Step 15 never auto-rebases divergent history onto a possibly-unrelated upstream.

Step 16 — PR Creation (already exists / no commits)

Failure: gh pr create fails with "No commits between main and branch" or duplicate PR. Resilience: Idempotency guard checks for existing PRs by branch name before creating. If PR already exists, reuse it. If no commits ahead, surface the error visibly rather than creating an empty PR.

Step 21 — PR Ready (large template variables)

Failure: Shell &&-chain breaks when philosophy_check, patterns_check, or quality_audit_results template variables contain shell metacharacters or exceed ARG_MAX. Resilience: Large template variables are captured via heredoc and truncated to 1KB before use in shell commands. Step 21 avoids echoing raw template content in bash; agent steps handle large text natively.

Evidence & Bookkeeping Gate Policy (no-discard invariant, issue #962)

Several steps are bookkeeping / evidence-collection gates (e.g. implementation-terminal-evidence in workflow-tdd, step-17a-testing-evidence-gate in workflow-pr-review, and the workflow_runtime_artifacts.sh artifact preflight). These gates exist to record evidence — they do not themselves verify the code. A bookkeeping gate that cannot run, or that finds no applicable work, MUST NEVER abort the recipe and discard fully-implemented, tested, and committed work.

The recipe enforces three explicit outcomes at every such gate:

1. Applicable + evidence present → PASS. Normal success (exit 0).
2. Not-applicable OR the evidence tool is unresolvable → visible DEGRADE. The gate emits a loud WARNING ... continuing in degraded mode to stderr and exits 0 (no-discard) so the branch/PR is preserved. Degradation is always visible — never a silent skip.
3. Genuine code-verification failure → FATAL (fail-visible). A real failing-tests or missing-implementation verdict (e.g. VERDICT: FAILED, HOLLOW_SUCCESS, zero-BS) stays fatal and aborts loudly. Bookkeeping degradation must never mask a real code failure.

Every bundled-helper resolution site uses the canonical resolution ladder (AMPLIHACK_HOME → REPO_PATH → $(pwd) → ~/.copilot → ~/.amplihack) so a helper installed at the amplihack root is always found, even when cwd/repo_path is a downstream product repo whose amplifier-bundle/tools/ is gitignored. The single fail-visible terminal action is kept last per site. The FATAL allowlist (step-08c-enforce-verdict, step-19c-zero-bs-verification, git-identity resolution) is preserved; only bookkeeping/evidence gates are converted to visible-degrade.

See docs/reference/workflow-implementation-evidence.md for the full gate inventory.

Checkpoint Strategy

The workflow creates automatic checkpoints at these points to prevent work loss:

If a step fails after a checkpoint, the worktree branch retains all committed work. Agents can resume from the latest checkpoint by re-running the workflow with the existing worktree.

Related Files

• Skill docs: amplifier-bundle/skills/default-workflow/SKILL.md
• Recipe (executable): amplifier-bundle/recipes/default-workflow.yaml
• Command Interface: .claude/commands/amplihack/dev.md
• Orchestrator Skill: .claude/skills/dev-orchestrator/
• Investigation Workflow: .claude/skills/investigation-workflow/