/init-workflow

name: init-workflow
description: >
  Sets up and checks the AI workflow in a project that has this plugin
  installed: scaffolds missing AGENTS.md, CLAUDE.md, hooks, settings and
  docs; detects project commands; seeds review/planning guidance; verifies
  the review gate. Use when adopting the plugin in a project, or re-run as a
  doctor when the setup may be missing or drifted.
license: MIT
metadata:
  author: André Cunha

/init-workflow

Scaffold the project-owned files missing from `${CLAUDE_SKILL_DIR}/templates/` (each independently: a project may already have its own `AGENTS.md`, `CLAUDE.md`, or neither), fill them with this project's facts, and verify the setup. Idempotent: re-run after a plugin update or suspected drift; it acts as a doctor, reporting what is missing instead of redoing what is filled.

Scope: project-owned files only. Never edit the plugin's own mechanism (skills, sub-agents, plugin docs); those change by updating the plugin.

Input

• The project (repo root as working directory), with this plugin installed
• User answers to the confirmation rounds below

Ground rules

• **Propose, then write.** Every detected value is a proposal until the user

confirms it

• Batch confirmations: one round each for the initial scaffold, commands,

AGENTS.md sections, review/planning guidance (Step 4's "already have docs?" question is a separate, first round, since it decides what the rest of that step asks)

• Never invent project facts; where the user defers, leave an explicit

`[TODO: …]`

• **Keep `AGENTS.md` lean**: one line per command, one per module, one bullet

per sensitive area. Depth belongs in `docs/`

Steps

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

Every file under `${CLAUDE_SKILL_DIR}/templates/` maps to a project-relative destination (the plugin's canonical enumeration), **except** `docs/agent-rules/code-critic.md` and `docs/agent-rules/plan-critic.md`: Step 4 creates those (or not, if the project has equivalent docs); writing them here would leave orphaned stubs. Check each other destination on its **own** trigger; one file's presence never gates another's.

• **Destination missing → scaffold it**
• Strip `.template` from `AGENTS.md.template`, `CLAUDE.md.template` (→

`AGENTS.md`, `CLAUDE.md`) and `settings.json.template` (→ `.claude/settings.json`, not project root), on the destination copy only. Never strip it on the source inside `templates/` (an un-suffixed `AGENTS.md`/`CLAUDE.md` there would be auto-loaded as live guidance)

• Copy every other file to the same relative path it has under `templates/`
• **Destination exists as plain content** (`AGENTS.md`, `docs/adr/*`,

`docs/product-context/*`) → leave untouched; list as "already present" in Step 6. Never overwrite a file the project owns

• **Destination exists, special handling** (below): `CLAUDE.md`,

`.claude/settings.json`, `githooks/pre-push`, `scripts/review-ok.sh`, `scripts/check-hook-status.sh`

**`CLAUDE.md`**

• Exists and lacks `@AGENTS.md` → offer to append the import line. Never

overwrite with the template; never append if the import is already there

• Declined → Step 6 gap: `CLAUDE.md` won't load `AGENTS.md` into Claude Code

**`.claude/settings.json`** (a merge target; already existing is common, since a project-scope plugin install can create it first)

• Exists → read it; propose adding whichever of

`${CLAUDE_SKILL_DIR}/templates/settings.json.template`'s `permissions.deny` entries are missing, preserving everything else. Never a flat overwrite

• Has any `permissions.ask` entry mentioning `scripts/review-ok.sh` (earlier

template versions) → offer to remove it: the prompt stalls unattended and parallel runs, and the merge review is the human gate

• Missing → scaffold from the template
• Doesn't parse as JSON, root isn't an object, or `permissions` /

`permissions.ask` / `permissions.deny` exist but aren't an object and arrays → no merge, no guessed fix. Flag as an unresolved item in this step's proposal (like a hook conflict) and continue; a malformed file on this security-relevant path needs the user's own eyes

**`githooks/pre-push`, `scripts/review-ok.sh`, `scripts/check-hook-status.sh`** Two questions. Q1 is decided here and written in the same single confirmation round below, never before the user confirms. Q2 runs only after that write (or its decline), as the first thing after the proposal is confirmed and written, since its verdict is meaningful only against settled state.

*Q1. Is each existing file actually this gate's own?* Check each independently:

• `githooks/pre-push`, `scripts/review-ok.sh`: ours if the content references

`.review-passed`

• `scripts/check-hook-status.sh`: ours if the content references

`DEST_FOREIGN` (unique to that script; `.review-passed` and `READY_TO_CONFIGURE` also appear in `review-ok.sh`)

• Known gap, accepted: `check-hook-status.sh` necessarily contains

`.review-passed` too, so its content placed at `githooks/pre-push` would misidentify as ours

Then:

• Missing → scaffold from the template, preserving the executable bit
• Exists, not ours → a real conflict, not "already present". Surface it and

ask: replace with the template's version, or decline

• For `githooks/pre-push`, never offer to chain the template's check into

the existing script: a pre-push hook reads its ref list from stdin once, and a chained script can consume it before the gate's `while read` loop, giving a hook that exits 0 on every push with no error

• A declined conflict is an open gap Step 6 must name
• Exists and ours → leave as is (Step 5 item 1 checks it's executable)

*Q2. Is the gate actually wired up?* Run `${CLAUDE_SKILL_DIR}/templates/scripts/check-hook-status.sh` from the project root (the plugin's read-only copy; safe even if Q1 was declined or not yet scaffolded) and act on its one-line verdict:

• `ACTIVE` / `NEEDS_CHMOD` → already wired (the latter