workflow-init

name	workflow-init
description	Use when a repo wants to adopt agentic-workflow-kit, when the user says "init agentic-workflow-kit", "set up agentic-workflow-kit", "scaffold the workflow config", or runs /workflow-init. Detects the repo's package manager, verify command, CI, default branch, and branch-protection rules; chooses a PR/merge preset; writes .workflow/config.yaml; and scaffolds a tracks index plus an example tracker. Idempotent.
argument-hint	[instructions]
user-invocable	true

workflow-init

Scaffold agentic-workflow-kit configuration in the current repository: a single .workflow/config.yaml, a tracks index, and an example tracker. Detect sensible defaults; never clobber existing files without confirmation.

References (read before acting)

• Config schema (human): ${CLAUDE_PLUGIN_ROOT}/references/config-schema.md
• Config schema (machine): ${CLAUDE_PLUGIN_ROOT}/references/config.schema.json
• Tracker contract: ${CLAUDE_PLUGIN_ROOT}/references/tracker-contract.md
• Presets: ${CLAUDE_PLUGIN_ROOT}/presets/push-and-merge.yaml, gated-automerge.yaml, push-only.yaml
• Example tracker: ${CLAUDE_PLUGIN_ROOT}/examples/example-tracker/README.md

Step 1 — Detect signals

Run these, tolerating failures (a missing tool just means "unknown"):

• Package manager / verify command: check for pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb, Cargo.toml, go.mod, Makefile. If package.json has a check or test script, prefer it for verify.full. Detect a scoped changed gate distinct from the full gate when one exists (for example nx affected, turbo run <task> --filter=..., lint-staged, or a *:changed / *:affected script) and use it for verify.changed.
• CI present: any files under .github/workflows/.
• Default branch: git symbolic-ref --short refs/remotes/origin/HEAD (strip the origin/ prefix); fall back to main.
• Required reviews: gh api repos/{owner}/{repo}/branches/{base}/protection — a 404 means no branch protection (no required reviews).

Step 2 — Choose a preset

Default to push-only for new or unknown repos, regardless of detected CI or branch-protection signals. This is the conservative starter preset: open a PR and stop before merge. The auto-merge presets remain available only when the user explicitly opts into them: canonical encoding lives in packages/orchestrator/src/config/preset.ts in the agentic-workflow-kit source repo; packaged runtime behavior is owned by @agentic-workflow-kit/orchestrator.

• gated-automerge waits on CI + bot review, then auto-merges.
• push-and-merge opens a PR, uses best-effort local checks, and auto-merges.

State the chosen preset and the signals behind it, and let the user override before writing.

Step 3 — Write .workflow/config.yaml

Copy the chosen preset verbatim, then patch detected values: verify.full (from the detected full verify command), verify.changed (from a scoped changed gate when present), and git.baseBranch (from the detected default branch). Only set verify.changed equal to verify.full when no scoped command exists, and say that fallback explicitly in the summary. Leave everything else at the preset's value. Presets declare the current semver config schema version, for example version: "0.6.0". Existing configs with legacy version: 1 remain readable during the transition window, but should be reported as upgradeable before reconciling missing keys. Validate the result against config.schema.json before saving.

Step 4 — Scaffold trackers (only if absent)

• If <tracksDir>/README.md does not exist, create it as the tracks index: a short description, an "Active tracks" table (Track | Prefix | Status | README), an "Archived tracks" table, and an ID-prefix registry of reserved prefixes.
• If <tracksDir>/example-tracker/README.md does not exist, copy the bundled example tracker there as a working reference.

Never overwrite an existing index or tracker without explicit user confirmation.

Step 5 — Summarize

Print the chosen preset (and the signals behind it), the paths written, and the next command to run.

Idempotency

Re-running is safe: reconcile missing keys in an existing .workflow/config.yaml, report any drift from the schema, and skip scaffolding files that already exist. If the runtime exposes workflow_config_status or agentic-workflow-kit config status --json, use it before changing an existing config. If status reports an available upgrade, summarize the change and ask before running workflow_config_upgrade or agentic-workflow-kit config upgrade --yes --json; dry-run first when the user has not already approved the write.