Dev Flow

Development Flow Evaluation

Project Config (auto-injected)

!cat .claude/dev-flow-config.md 2>/dev/null || true

Model Routing (for subagent dispatch)

!cat .claude/model-routing-config.md 2>/dev/null || true

If no project config above, use defaults from [references/model-routing.md](references/model-routing.md).

Dispatch Chains (for orchestrator routing)

!cat .claude/dispatch-config.md 2>/dev/null || true

If no project config above, autopilot's own fallback skills are primary for methodology; native Task dispatch for parallel; autopilot:reviewer for code review. See [project-config-template/dispatch-config.md](../../project-config-template/dispatch-config.md) for the schema.

---

Phase 1: Session Start

Run before any code changes. Size determines which path executes.

S-Size Fast Path

Total overhead target: under 5 seconds.

1. Confirm task: restate what will be done in one sentence.
2. Branch check: `git branch --show-current` -- confirm on expected branch.
3. Proceed to S Workflow. No further gates.

S-size skips: branch freshness, knowledge/digest review, draft plan overlap, risk escalation.

L-Size Full Gates

All gates must pass before any code changes begin. If any gate is blocked, surface to the decision-maker (user in normal mode, CEO in CEO mode).

1. Record session start SHA:
   git rev-parse HEAD > .claude/session-start-sha

2. Branch check:
   git branch --show-current

3. Branch freshness:
   BEHIND=$(git log HEAD..main --oneline 2>/dev/null | wc -l)
   AHEAD=$(git log main..HEAD --oneline 2>/dev/null | wc -l)
   Evaluate using the freshness table below.
   If main does not exist (new repo), skip this gate.

4. Knowledge and digest review:
   Check .claude/knowledge/ for relevant prior learnings.
   Check for unprocessed session digests.

5. Draft plan overlap check:
   ls doc/plans/*.md 2>/dev/null  (or project-configured path)
   If draft plans exist, check if the current task overlaps with any draft plan
   (same feature, same module, or same user story).
   If overlap found:
   - Normal mode: surface to user -- confirm whether to proceed or adopt the draft.
   - CEO mode: CEO decides within DOA (tactical decision).
   If no draft plans or no overlap: proceed.

6. Skill routing:
   Check CLAUDE.md (or project config) for code-area-specific skills.
   If a skill is listed for the target code area, invoke it before writing code.
   **Active enforcement**: For L-size, this gate is backed by the L-1.6 TaskCreate
   parent task (see L Workflow → Task tracking). Reading this bullet is NOT enough —
   the TaskCreate is the forcing function that prevents skipping.

Branch Freshness Table

| Behind | Ahead | Status | Action | |--------|-------|--------|--------| | 0 | any | Up to date with main | Proceed | | 1-5 | any | Slightly behind | Proceed with note | | >5 | 0 | Behind, no local work | Warn user, recommend merge | | >5 | >0 | DIVERGED | Flag to user before proceeding |

Fix Path

Same lightweight start as S, plus branch creation:

1. Confirm root cause: restate the bug and known fix in one sentence.
2. Branch: `git checkout -b fix/`
3. Skill routing check for the target code area.
4. Proceed to Fix Workflow.

Fix skips: knowledge/digest review, plan overlap, branch freshness (short-lived branch).

Context Continuation (Resuming Prior Work)

Resuming work on an existing feature branch with an active project → follow the 5-step procedure in [references/context-continuation.md](references/context-continuation.md) (uncommitted-changes check, SHA refresh, branch freshness, resume point, skill routing). Context continuation never re-evaluates size — it uses the size from the original session.

---

Session Rules (persist throughout)

These rules apply to ALL subsequent work in this session, regardless of which skills are invoked. They complement (not replace) any built-in skills — providing project-specific context.

Config Injection Rules

When performing these activities, FIRST read the corresponding config file if it exists. The config provides project-specific tools, commands, known issues, and conventions. If the config file does not exist, proceed normally without it.

| Activity | Config File | What It Contains | |----------|------------|-----------------| | Debugging (bugs, crashes, logic errors) | .claude/debug-config.md | Debug tools, Docker commands, known gotchas, layer-by-layer diagnosis | | Writing or running tests | .claude/test-strategy-config.md | Test framework, commands, coverage thresholds, test pyramid conventions | | Parallel task dispatch (team work) | .claude/team-config.md | Role templates, tech stack context, team size rules | | Performance profiling | .claude/profiling-config.md | Profiling tools, metrics collection, baseline commands | | Comparison audit (old vs new) | .claude/audit-config.md | Known by-design divergences, audit scope definitions | | Methodology / reviewer / parallel dispatch routing | .claude/dispatch-config.md | Preference chains for debugging / testing / profiling / team / review / parallel dispatch (also auto-injected at top of this skill) |

Quality Gate Rule

Before committing or merging, invoke autopilot:quality-pipeline. This is non-negotiable. The quality pipeline runs: test → scan → completeness → review.

Session End Rule

When the user signals session end (or task completion for S-size):

• Update project tracking if L-size (docs/projects/*/README.md + INDEX.md)
• Record knowledge if something was surprising or took >1 retry (autopilot:learn)

---

Quick Decision

First ask: what kind of work is this?

| Nature | Criteria | Workflow | |--------|----------|----------| | Fix | Bug fix — root cause known, solution clear. No design needed. | Fix (any module count) | | H | Production broken — immediate fix needed. | Hotfix |

If neither → size the feature:

| Size | Criteria | Workflow | |------|----------|----------| | S | Single commit (single module, no interface change, self-contained) | Direct commit | | L | Multiple commits (3+ modules / public API / incompatible data / Feature Flag / user requests planning) | Plan + Project |

Fix vs L: "Do I need to design the solution, or just implement a known fix?" Design → L. Known fix → Fix.

Risk Escalation (force L for features): money/points, auth/security, production protocol changes. Risk-escalated bug fixes stay Fix but add PR review before merge.

Scope Creep Detection

Size is evaluated once at start, but scope can grow silently. Two escalation paths:

S → L escalation is enforced by the S-scope-gate TaskCreate (created at S-start — see S Workflow). That task stays pending and surfaces before every tool use, forcing an explicit check before each commit. Passive self-checks after commits fail because memory is exactly what keeps failing.

L scope expansion (L work grows beyond its original README scope boundary — new subsystems, unplanned API surfaces, additional stakeholder requirements mid-flight):

After every phase completion, ask:
  "Does the REMAINING scope still match the README's scope boundary?"

Indicators of L-scope expansion:
  - New subsystem not listed in original README phases
  - Public API surface larger than original estimate
  - Estimate doubled (2x+ original effort)
  - User added requirements beyond original OKR

If expanded:
  → STOP. This is a Board Decision (user in normal mode, CEO escalates in CEO mode).
  → Update README scope boundary FIRST.
  → Only proceed after explicit approval.
  → Record in project decision log.

---

S Workflow -- Direct Commit

Scope gate (MANDATORY before any implementation): Create this task at S-start:

TaskCreate: "S-scope-gate: Evaluate scope before every commit"
  description: MANDATORY before every commit. Check all three indicators:
    (1) Fewer than 3 commits on this task so far?
    (2) Fewer than 3 different modules touched?
    (3) No features added beyond original goal?
  If ANY indicator is NO → STOP. Escalate to L:
    - Create project dir + README + INDEX (retroactive)
    - Record prior commits as completed phases
    - Create L-1.6 and L-5 TaskCreates, then continue with L Workflow tracking
  Mark this task ONLY when: work is complete AND scope stayed S throughout (all YES),
  OR L-escalation is complete and project tracking is in place.

This task stays pending and surfaces before every tool use — the forcing function that prevents "it was obviously S" from silently becoming a multi-module project without tracking.

1. Implement
2. Quality gate (per project config, or: lint + test)
3. Evaluate S-scope-gate indicators before committing
4. Commit to current branch (descriptive message)
5. Cleanup: if from backlog, delete the item

> Unlike L's multi-task infrastructure, S creates exactly ONE TaskCreate: the S-scope-gate. > Intentionally minimal — one pending task that surfaces the scope-creep check without adding L-level overhead.

S Session End (lite):

1. Retry check:
   "Did I retry any non-trivial operation 2+ times?
   If yes, invoke `learn` skill to record the finding."

2. Deferred items:
   If anything was postponed, add to BACKLOG with context + trigger condition.

3. Confirm commit:
   Verify the change landed on the correct branch.

> S does not use TodoWrite -- too few steps to justify tracking overhead.

---

Fix Workflow -- Bug Fix (any module count)

> Bug fix with clear root cause. No plan/project needed. Feature branch for traceability.

1. git checkout -b fix/
2. Investigate root cause (read code, trace data flow)
3. Implement fix
4. Quality gate (per project config, or: lint + test)
5. Commit with detailed message: root cause + what was wrong + how it's fixed
6. Write ongoing-maintenance entry — append one line to doc/projects/ongoing-maintenance/YYYY-MM.md (or the project-configured projects path — e.g. docs/ plural; check the injected config so you don't create a stray sibling tree):

| MM-DD | commit_hash | fix(area): 根因 → 修法 (跨 N 模組) |

1. Merge to develop
2. Cleanup: delete fix branch

If the fix revealed a non-obvious lesson, invoke learn skill.

Fix does NOT create: plan, project dir, or PR (unless risk-escalated).

---

L Workflow -- Plan + Project

> Continuous execution: proceed between Phases without asking "continue?". > Stop only for: Staging Gate | Build/test failure | Design decision needed | Context near limit.

Task tracking (MANDATORY at L-1): Create Phase Todos at start (extract p0...pN + completion from plan) AND create TWO parent tasks. Both are non-optional forcing functions — missing either one = failed L-1 gate:

TaskCreate: "L-1.6: Skill routing — invoke required skills for all affected code areas"
  description: MANDATORY before any implementation phase. Input: the module/surface list
  produced by L-1.5 Scope Completeness Audit. For each affected area, consult project
  CLAUDE.md and/or .claude/skill-routing.md for required skills. Invoke each required
  skill via the Skill tool (reading the file is NOT invoking). Mark this task completed
  ONLY after:
    (a) every required skill has been invoked via Skill tool, AND
    (b) one-line summary of "what this skill told me for this task" is captured in
        session context (either a note or a TaskCreate subtask).
  If a module has no skill routing entry, mark N/A with a one-line justification.
  Phase implementation tasks (P0..PN) MUST be created with blockedBy=[this task] so
  they cannot start until skill routing is confirmed done.

TaskCreate: "L-5: Invoke autopilot:finish-flow"
  description: MANDATORY L-size completion. Invoke autopilot:finish-flow which will
  expand into 7 discrete sub-tasks (Final Goal Review, Pre-Merge Review, Merge,
  Post-Merge Review, Archive, L Session End, Delete merged branch). Do not mark this
  completed until the skill has run and all 7 sub-tasks reach completed.

Both parent tasks are forcing functions: they remain pending through every phase and are surfaced by system-reminder after each tool use. They cannot be silently skipped because marking them completed requires explicit work — L-1.6 requires Skill-tool invocations, L-5 requires invoking autopilot:finish-flow which itself creates 6 more discrete pending tasks.

Why L-1.6 exists (historical rationale): On 2026-04-11, reconnect-regression-fix ran the full fix workflow against src/network/, src/lobby/, and E2E tests without invoking twgs-network / twgs-debug / other project skills. The existing "gate 6: Skill routing" bullet in L-size Full Gates (Phase 1 Session Start, line ~65) is passive markdown and got mentally compressed into "I know this area" — the same failure mode that L-5 hit before finish-flow replaced it. This active TaskCreate applies the identical passive→active pattern that worked for L-5. Missing twgs-* skill invocations don't produce immediate bugs, but they systematically waste the knowledge base the project has invested in.

Phase task dependency (mechanical enforcement, not just a reminder): When TaskCreating phase tasks P0..PN, each MUST be created with blockedBy=[L-1.6]. This means phases literally cannot be claimed/started until L-1.6 reaches completed. The system-reminder surfaces pending L-1.6 after every tool use; the blockedBy dependency makes starting implementation impossible without first resolving it. Two layers of defense.

If either parent task is missing at any point after L-1: STOP, create it retroactively, then continue. For L-1.6 specifically, if implementation has already started without skill routing: pause current phase, create L-1.6 now, invoke the missing skills, then resume.

L-1. Intent Confirmation

Confirm before starting. Record in the project README:

## Project Goal

> **Final goal**: [one sentence]
> **Success criteria**: [quantifiable conditions]
> **Scope boundary**: [explicit include/exclude]

Quantifiable means each criterion must include (a) a measurable threshold (number, percentage, boolean state, or named command output), AND (b) how it will be verified.

| | Example | |------|---------| | PASS | "API returns .md`

L-3. Project Setup (mandatory)

• Create project directory structure, branch, update project index
• Per project config for specific bootstrap commands

L-4. Per Phase

Goal verification -- answer all three before starting each phase:

1. Does this change move us closer to the final goal?
2. Is this phase essential — would skipping it prevent the final goal from being achieved?
3. Does my understanding match the user's stated goal?

Pass threshold: Q1=yes, Q2=yes (essential), Q3=yes. Any "no" or "unsure" = blocked. Surface to decision-maker before proceeding.

CEO mode: CEO evaluates the three questions autonomously. Only escalate to user (Board) if the answer is "no" AND the required response is a strategic pivot (goal change, scope expansion) -- per CEO's DOA.

Drift signals:

| Signal | Response | |--------|----------| | "This phase has low ROI, skip it" | STOP -- Does it affect the final goal? | | "We can do this later" | STOP -- Any hidden dependencies? | | "Project is basically done" | STOP -- Has the final goal been achieved? | | "User probably just wants..." | STOP -- Ask and confirm directly. |

Execution: Implement -> quality gate -> commit -> mark phase done.

Backlog safety (before deferring anything):

1. Does this item affect the final goal? If yes, do NOT defer.
2. Can the goal be achieved without it? If no, do NOT defer.
3. Unsure? Ask the user.

If deferral passes: add to BACKLOG with context + trigger condition, mark phase "Deferred" in project docs.

Phase advance gate -- all must be true before starting the next phase:

• [ ] Goal check: all three verification questions answered "yes"

-

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cookys
• Source: cookys/autopilot
• License: MIT

Install and usage instructions live in the source repository linked above.