/init-workflow

name: init-workflow
description: >
  Bootstraps and validates the AI workflow in a project that has this
  plugin installed: scaffolds whichever project-owned files are missing,
  detects the project's commands, fills AGENTS.md, points it at
  review/planning guidance (seeding docs/agent-rules/ or reusing an
  existing doc), and verifies the review gate. Re-run any time as a
  doctor — it reports what is missing or drifted. (Named init-workflow so
  it does not collide with Claude Code's built-in /init command, which
  generates a CLAUDE.md.)

/init-workflow — Bootstrap and Validate the Workflow

Run this skill inside a project once this plugin is installed. It scaffolds whichever project-owned files are missing from this skill's bundled templates — independently of one another, so a project can already have its own `AGENTS.md`, its own `CLAUDE.md`, or none of it — then fills them with *this* project's facts, interactively, and verifies the setup end to end. It is idempotent — re-run it after a plugin update or whenever setup drift is suspected, and it acts as a doctor, reporting what is missing rather than redoing what is already filled.

**Division of labor:** this skill scaffolds, adapts, and validates project-owned files. It never edits the plugin's own mechanism — the skills, sub-agents, and the plugin's own documentation are off limits; updates to those come from updating the plugin itself, not from this skill.

**Ground rules:**

• **Propose, then write.** Every value you detect is a proposal until the

user confirms it. Batch the confirmations (one round for the initial scaffold, one for commands, one for AGENTS.md sections, one for review and planning guidance) instead of asking one question at a time — Step 4's own "do you already have docs?" question is a separate, necessarily-first round of its own, since it decides what the rest of that step even asks. Never invent facts about the project; where the user defers, leave an explicit `[TODO: …]` rather than a guess.

• **Keep `AGENTS.md` lean.** You are filling a map, not writing the

territory — one line per command, one line per module, one bullet per sensitive area. Depth belongs in `docs/`.

---

Step 1 — Scaffold if needed, then assess the current state

Every file under `${CLAUDE_SKILL_DIR}/templates/` maps to a project-relative destination (this is the plugin's canonical enumeration — see the file tree in the plugin's own documentation, kept in sync with this directory by rule), **except** `docs/agent-rules/code-critic.md` and `docs/agent-rules/plan-critic.md`, which Step 4 creates (or doesn't, if the project already has equivalent docs) once it knows the answer; writing them here too would leave an orphaned stub if Step 4 points elsewhere instead. Check every other mapped file's destination on its **own** trigger — one file's presence never gates another's, since a project can have hand-written its own `AGENTS.md` long before adopting this plugin's review gate, or vice versa:

• **Destination missing → scaffold it.** Strip the `.template` suffix from

`AGENTS.md.template` and `CLAUDE.md.template` (landing at `AGENTS.md`/`CLAUDE.md`) and from `settings.json.template` (landing at `.claude/settings.json`, **not** project root) — on the destination copy only; never strip it on the source inside `templates/` itself, since an un-suffixed `AGENTS.md`/`CLAUDE.md` left there would be auto-loaded by Claude Code as this project's live guidance instead of a template. Copy every other file (the rest of the `docs/` tree) to the same relative path it has under `templates/`.

• **Destination exists as plain content** (`AGENTS.md`, `docs/adr/*`,

`docs/product-context/*`) → leave it untouched and list it as "already present" in Step 6's report — never overwrite a file the project already owns.

• **Destination exists but needs special handling** (`CLAUDE.md`,

`.claude/settings.json`, `githooks/pre-push`, `scripts/review-ok.sh`, `scripts/check-hook-status.sh`) — see immediately below.

**`CLAUDE.md`.** If it exists (e.g. from Claude Code's own `/init`) and doesn't already contain `@AGENTS.md`, offer to append the import line — never overwrite it with the template's version, and never append if the import is already there (avoids a duplicate on a project that deleted `AGENTS.md` but kept `CLAUDE.md`). If the user declines, report it in Step 6 as a gap: `CLAUDE.md` won't load `AGENTS.md`'s guidance into Claude Code.

**`.claude/settings.json`.** A merge target, not a copy target — a project-scope plugin install can create this file (recording the install itself) before `/init-workflow` ever runs, so "already exists" here is a common case, not the exception. If it exists, read it and propose adding whichever of `${CLAUDE_SKILL_DIR}/templates/settings.json.template`'s `permissions.ask`/`permissions.deny` entries aren't already present, preserving everything else the file already has — never a flat overwrite. If it doesn't exist, scaffold it directly from the template. If the existing file doesn't parse as JSON, its root value isn't an object, or `permissions`/`permissions.ask`/`permissions.deny` are present but not the expected shape (an object, and two arrays), do not attempt a merge and do not guess a fix — flag it as an unresolved item in this step's proposal (the same way a hook conflict is flagged) and continue with the rest of Step 1; a malformed pre-existing file on this security-relevant path needs the user's own eyes, not an agent's improvised repair.

**`githooks/pre-push`, `scripts/review-ok.sh`, `scripts/check-hook-status.sh`.** Two separate questions. The first is decided here and, once the step's proposal is confirmed, written as part of that same single confirmation round below — never before the user confirms. The second is evaluated only *after* that write (or after the user declines it), as the first thing in "continue below" once Step 1's proposal is confirmed and written —