Proceed

Proceed — Full ADLC Pipeline

You are an autonomous ADLC orchestrator. Given a requirement number (REQ-xxx), you drive it from validated spec all the way to a pull request — validating at each gate, fixing issues automatically, and only pausing when you're stuck or need human input.

Execution Mode

This skill supports two modes:

1. Main conversation mode (default): Dispatches formal agents (defined in ~/.claude/agents/) for parallelism at Phase 4 (task implementation) and Phase 5 (verify). Use this mode when running /proceed directly.
2. Subagent mode (when running as a pipeline-runner agent inside /sprint): Execute ALL phases sequentially in-context. Do NOT dispatch sub-agents. At Phase 4, implement tasks one at a time. At Phase 5, run the reflector + reviewer checklists sequentially in your own context using the criteria from the agent definitions. Subagents cannot spawn other subagents.

You are in subagent mode if you were explicitly told so in your launch prompt.

Autonomous Execution Contract

/proceed is an autonomous orchestrator. It is designed to run end-to-end without human input. The skill has exactly three legitimate halt points; every other instruction below is a log step, not a pause:

1. Validation fails 3 times at any gate (Phase 1 or Phase 3) — surface blockers.
2. Reflector surfaces user-facing questions (Phase 5, Step C item 4) — surface as a numbered list and wait.
3. Merge conflicts during rebase (Phase 8 / wrapup) — surface conflicts and wait.

For everything else — including every End-of-phase log block below, every agent dispatch, every commit, every PR creation, every CI wait — you continue immediately to the next step without asking the user. Prompt only for tool-level permissions on truly destructive operations (these are governed by .claude/settings.json, not this skill).

Writing logs vs asking questions: when the skill says "report X" or "log Y", emit a one-line status line to the conversation and continue. Do NOT phrase it as a question or wait for acknowledgment. A bad example: "Spec validated — shall I proceed to Phase 2?" A good example: "Spec validated. Moving to Phase 2."

Ethos

!sh .adlc/partials/ethos-include.sh 2>/dev/null || sh ~/.claude/skills/partials/ethos-include.sh

Arguments

The user provides a requirement ID, e.g., /proceed REQ-023 or /proceed 23.

• Normalize to REQ-xxx format (zero-pad to 3 digits if needed)
• Locate the spec at .adlc/specs/REQ-xxx-*/requirement.md
• If the spec doesn't exist, stop and tell the user to run /spec first

Repository Configuration (single-repo vs cross-repo)

Some requirements touch one repo; others (e.g., a feature that simultaneously changes a mobile app, an API, and a web frontend) touch multiple repos. /proceed supports both.

"Primary" is per-REQ, not a fixed role. The primary repo for a given REQ is simply the repo where you invoked /proceed from — that repo's .adlc/ holds the spec, tasks, and pipeline-state.json for this REQ. A different REQ can originate in a different repo; that REQ's primary is the other repo. Every repo that might host a REQ needs its own .adlc/ structure (from /init) and its own .adlc/config.yml so it can act as primary when a REQ starts there.

Single-repo mode (the invoking repo's config has no siblings, or no config at all): existing behavior — one worktree, one PR, one merge. All phases run against the invoking repo. Used for work that's scoped to one repo.

Cross-repo mode (the invoking repo's config lists siblings): the invoking repo is primary for this REQ. Sibling repos are registered by id → path. /proceed creates a worktree in each touched repo, routes tasks by their repo: frontmatter field, opens one PR per repo, and merges in merge_order.

Config schema (.adlc/config.yml, present in every repo that can originate a REQ):

repos:
  # Self — mark the current repo as primary. Path is implicit (it's this repo).
  # Each repo's config marks ITSELF as primary. The configs across repos end
  # up being mirror images of each other; that's expected and correct.
  web:
    primary: true
  # Siblings — other repos this one might coordinate with. Path is relative
  # to THIS repo's root, or absolute. Every sibling must be cloned locally.
  api:
    path: ../api
  mobile:
    path: ../mobile

# Merge order for Phase 8 when this repo is primary. If omitted, defaults to
# the order repos appear above. Only touched repos (those with tasks in the
# current REQ) are merged; untouched ones are skipped.
merge_order:
  - api
  - web
  - mobile

Rules:

• In each repo's own config, exactly one entry — that repo itself — has primary: true. Sibling entries describe other repos.
• Every repo that can originate a REQ needs /init run in it AND its own .adlc/config.yml. Repos that will only ever participate as siblings (never originate REQs) technically don't need a config, but it's cheap insurance — configure them anyway so any of them can host a REQ later.
• Task frontmatter must include a repo: field naming one of the invoking repo's configured repo ids. A task without repo: defaults to the invoking (primary-for-this-REQ) repo.
• "Touched repos" for a REQ = the set of distinct repo: values across its tasks.
• If the invoking repo's config has only itself (no siblings), or the file is absent, behave as single-repo.
• Sibling repo paths must exist and be git repositories. Fail fast in Step 0 if any are missing.

Terminology used below:

• Primary repo — for this REQ, the repo /proceed was invoked from. Hosts .adlc/, spec, state file. Always participates.
• Touched repo — any repo (primary or sibling) that has at least one task in this REQ.
• Repo worktree — /.worktrees/REQ-xxx for each touched repo, on branch feat/REQ-xxx-short-description (same branch name across repos).

The Pipeline

Execute these phases in order. Each phase has a validation gate — if validation fails, fix the issues and re-validate. Loop up to 3 times per gate; if still failing after 3 attempts, stop and present the remaining issues to the user.

Pipeline State Tracking

CRITICAL: You MUST maintain a state file to track pipeline progress. This prevents phases from being skipped during long-running pipelines.

State file location: .adlc/specs/REQ-xxx-*/pipeline-state.json

Schema:

{
  "req": "REQ-xxx",
  "branch": "feat/REQ-xxx-short-description",
  "startedAt": "2026-03-27T10:00:00Z",
  "completed": false,
  "currentPhase": 0,
  "completedPhases": [],
  "phaseHistory": [
    { "phase": 0, "name": "Create Worktree", "completedAt": "2026-03-27T10:01:00Z" }
  ],
  "repos": {
    "web": {
      "primary": true,
      "path": "/absolute/path/to/web",
      "worktree": "/absolute/path/to/web/.worktrees/REQ-xxx",
      "branch": "feat/REQ-xxx-short-description",
      "touched": true,
      "prUrl": null,
      "merged": false,
      "snapshotBranch": null,
      "snapshotPR": null
    },
    "api": {
      "primary": false,
      "path": "/absolute/path/to/api",
      "worktree": "/absolute/path/to/api/.worktrees/REQ-xxx",
      "branch": "feat/REQ-xxx-short-description",
      "touched": true,
      "prUrl": null,
      "merged": false,
      "snapshotBranch": null,
      "snapshotPR": null
    }
  },
  "mergeOrder": ["api", "web"],
  "phase4": {
    "currentTask": null,
    "completedTasks": [],
    "failedTasks": []
  }
}

The repos block is the canonical registry for this pipeline run. Every cd/commit/push/PR/merge operation reads the target repo's path or worktree from here — never from cwd inference. touched: true means at least one task targets this repo; untouched repos skip Phases 4–8. mergeOrder is the list of touched repo ids in the order Phase 8 will merge them (primary is always a member).

Single-repo mode: repos contains exactly one entry with primary: true, touched: true, and mergeOrder is [that-one-id]. All phase logic still reads from repos — there is no separate code path.

The phase4 block tracks task-level progress during implementation so that a mid-Phase-4 context compression can resume from the exact task in progress rather than restarting the phase. currentTask holds the TASK-xxx ID being worked on right now; completedTasks holds IDs of tasks whose status is complete and whose commit has landed; failedTasks holds IDs that hit unrecoverable errors and were surfaced to the user. Other phases do not need sub-state.

The snapshotBranch and snapshotPR fields on each repos. entry are deprecated as of REQ-380. The skill no longer writes them; they remain in the schema for read-back compatibility with state files written between REQ-362 and REQ-380. A missing or null value is the expected state on all new runs. Snapshot promotion (the staging → main PR creation that previously ran in Phase 8a) is now handled out-of-band by a per-project workflow on staging-tip CI greenness; consult the project's CI configuration.

Gate Protocol — follow exactly:

1. Initialize the state file at the start of Step 0 with currentPhase: 0, completedPhases: [], completed: false, repos: {...resolved from config...}, mergeOrder: [...], phase4: { currentTask: null, completedTasks: [], failedTasks: [] }
2. Before starting any phase: read pipeline-state.json. Verify currentPhase equals the phase you're about to start AND the previous phase is in completedPhases. If either check fails, STOP — you skipped a phase. Go back and complete it.
3. After completing any phase: append the phase number to completedPhases, append an entry to phaseHistory with the completion timestamp, set currentPhase to the next phase number.
4. Phase 4 task-level writes: When starting a task, set phase4.currentTask to its TASK-xxx ID. When its commit lands (in the task's target-repo worktree), append the ID to phase4.completedTasks and clear currentTask. On unrecoverable failure surfaced to the user, append to phase4.failedTasks instead.
5. Worktree paths are immutable post-Step-0: once Step 0 records repos[].worktree, every subsequent phase (1–8) MUST read the path from state and MUST NOT re-derive it from cwd, the REQ id, or any naming convention. This applies on the happy path, not just on resume. (Step 0 itself reads cwd exactly once — at item 2 of Step 0 — to initialize the registry, then freezes the path into state; the prohibition starts from the moment Step 0 completes.)

5b. Resume from interruption: If the state file already exists when you start, read it and resume from currentPhase. Trust repos as the source of truth for worktree paths. If currentPhase is 4 and phase4.currentTask is non-null, resume that specific task (re-read its file, use repos[].worktree for every git/file operation, re-check whether its commit already landed, continue or restart as appropriate) before moving to the next task in the dependency graph. Never replay tasks already in completedTasks.

1. If context has been compressed: re-read pipeline-state.json before doing anything and treat it as the source of truth for currentPhase, repos, and phase4. Do not rely on memory of which phase, task, or repo you're in.
2. Per-repo writes during Phases 6–8: when a PR is created, write its URL to repos[id].prUrl. When a PR merges, set repos[id].merged = true. These writes let a mid-Phase-8 interruption resume merges in order without double-merging.
3. On completion: After Phase 8 (Wrapup) finishes, set "completed": true in the state file.

Each phase below has a one-line Gate reminder. The full protocol above applies to every gate.

---

Step 0: Resolve Repos + Create Worktrees + Preflight + Load Shared Context (ALWAYS FIRST)

Before doing anything else, resolve the repository set, isolate each touched repo in a git worktree, and prime the shared context so subskills don't re-read the same files:

1. Preflight — verify all prerequisite files exist in the primary repo (stop with a clear message if any are missing):

• .adlc/context/project-overview.md — run /init if missing
• .adlc/context/architecture.md — run /init if missing
• .adlc/context/conventions.md — run /init if missing
• .adlc/specs/REQ-xxx-*/requirement.md — run /spec if missing

1. Resolve repo registry:

• Read .adlc/config.yml if it exists. If absent or has no repos block, use single-repo mode: the registry is { : { primary: true, path: , touched: true } } where the repo id is the basename of the cwd.
• In cross-repo mode: the primary entry's path is cwd. Resolve each sibling's path to an absolute path (relative paths are relative to the primary repo root). Verify each path exists and is a git repo (git -C rev-parse --git-dir). If any sibling is missing, stop with a clear error listing the missing repos.

1. Determine touched repos (best-effort at Step 0; confirmed after Phase 2):

• If tasks already exist under .adlc/specs/REQ-xxx-*/tasks/, read each task's repo: field to compute the touched set.
• If tasks don't exist yet (fresh pipeline), assume every configured repo is potentially touched and create worktrees in all of them. Post-Phase-2, untouched repos will be marked touched: false and their worktrees removed.
• The primary is always touched (even if no primary tasks — it hosts the spec and state file).

1. Determine the integration branch, then fetch it in each touched repo. The base for feature branches is NOT always main (LESSON-036 — sprinted runners that hardcoded main in a staging-first repo paid a mid-pipeline rebase + PR-retarget every time). Detect the repo's branch model; any one signal is sufficient:

• .adlc/config.yml declares a gcp.staging_project (or otherwise indicates a staging-first deploy), OR
• a .github/workflows/* enforces a verify-head-ref / branch-protection head-ref check, OR
• CLAUDE.md describes a "two-branch" / "staging-first" / "staging → main promotion" pipeline.

If any signal is present, ` is the project's integration branch (staging unless the project names another); otherwise is main. **Always fetch before reasoning about any ref or spec presence** (never trust a stale local ref — LESSON-036): `bash git -C fetch origin ` Do NOT git checkout in — it may be checked out in another worktree and fail. The worktree (step 5) is created directly from origin/. Feature branches and the Phase 6 PR base MUST use , never a hardcoded main`.

Step 4 advisory — in-flight manifest (non-blocking, REQ-482). With origin now fetched and before the worktree is created, surface what else is in flight across sessions so you can spot overlaps before starting. In subagent mode (/sprint pipeline-runner): SKIP this — /sprint already built the manifest once for the batch in its pre-flight. Otherwise invoke /manifest, prefixing the same shell call with the hand-off vars so it reuses this fetch and marks the current REQ as self: MANIFEST_SELF="REQ-xxx" MANIFEST_SKIP_FETCH=1 (substitute the concrete REQ id). Display the in-flight table and any coarse component/domain overlap involving the current REQ. This is purely advisory: it MUST NOT block, halt, reorder, or gate the pipeline; it is NOT one of the three legitimate halt points; a manifest-build failure is ignored with a one-line note and the pipeline continues (BR-7, BR-8, BR-9). The worktree-collision gate (step 4b) is unchanged. 4a. Parse the declared worktree path (primary repo only) — scan the launch prompt for the dispatch-line contract. The format is normative in REQ-263 architecture.md ("The dispatch-line contract" section); do not change the regex or format here without updating that document.

• Regex: `^WORKTREE PATH \(mandatory\): (

…

Source & license

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

• Author: atelier-fashion
• Source: atelier-fashion/adlc-toolkit
• License: MIT

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