Init Workflow

/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 — never before, since its verdict is only meaningful against the settled state, not a proposal still awaiting confirmation.

1. Is each of the three files, if it already exists, actually this gate's own file? Check each independently: githooks/pre-push and scripts/review-ok.sh each count as ours if their content references .review-passed; scripts/check-hook-status.sh counts as ours if its content references DEST_FOREIGN (a verdict string that appears only in that script — unlike .review-passed or READY_TO_CONFIGURE, both of which also appear in scripts/review-ok.sh's own logic, so neither is unique enough to use here). This pair is not perfectly symmetric — check-hook-status.sh necessarily contains the literal string .review-passed too, since checking for that marker is its job — so a contrived case (someone's check-hook-status.sh content placed at githooks/pre-push) would misidentify as ours; accepted as a known, low-probability gap rather than solved here.

• Any of the three is missing → scaffold it from the template,

preserving the executable bit.

• Any of the three exists but isn't ours → a real conflict, not a

benign "already present." Surface it explicitly and ask the user how to proceed: replace it with the template's version, or explicitly decline. For githooks/pre-push specifically, do not offer to chain the template's check into the existing script — a pre-push hook reads its ref list from stdin exactly once, and a naively chained script can silently consume it before the gate's own while read loop runs, producing a hook that exits 0 on every push with no error. A declined conflict is an open gap Step 6 must call out by name.

• Any of the three exists and is ours → leave it as is (Step 5 item 1

checks it's still executable).

2. Once question 1 has been written (or declined), is the gate actually wired up? Don't hand-roll it: run ${CLAUDE_SKILL_DIR}/templates/scripts/check-hook-status.sh — the plugin's own read-only copy, safe to run regardless of whether question 1's write happened, since a declined or not-yet-scaffolded githooks/pre-push shouldn't stop this check — from the project root, and act on its one-line verdict:

• ACTIVE or NEEDS_CHMOD — already wired up (the second just

needs chmod +x, safe since the marker already identifies it as this gate's file). Nothing else to do.

• READY_TO_CONFIGURE — githooks/pre-push is ready but

core.hooksPath isn't wired to it. On a fresh project this is the ordinary, expected state right after question 1's scaffold — offer git config core.hooksPath githooks as the natural next step, not a special case.

• DEST_NEEDS_CHMOD — githooks/pre-push exists and is ours but

isn't executable; offer chmod +x.

• UNCONFIGURED or DEST_FOREIGN — if question 1's proposal for

githooks/pre-push was declined, this is that same gap, already in Step 6's report — don't report it a second time. If question 1 was instead confirmed and written, this verdict is unexpected: the write didn't take effect as intended, and that itself is what to report (Rule 2), not something to act on here.

• FOREIGN — something else entirely already claims the active hook

slot (another hook manager, or core.hooksPath pointing at a directory that isn't this project's own githooks/). Do not offer to change core.hooksPath or replace anything; report exactly what the script printed and leave reconciling it to the human — including, if they want the two to coexist, that their existing hook would need to invoke githooks/pre-push itself with correct stdin handling, not something to draft on their behalf here.

Known limitation: check-hook-status.sh's marker check is a presence check, not a version check, so a stale copy from before a later plugin update still reads as ACTIVE; that gap is accepted for now, not solved here.

Also append .review-passed, .qa-evidence/, and .workflow-log/ to .gitignore if not already present (create the file if it doesn't exist) — these are what the workflow writes locally and Step 5 checks for.

Known limitation: this step has no memory of a prior decline. A file the user chose not to scaffold (e.g. a deleted docs/product-context/README.md placeholder) is proposed again on the next run, since "destination missing" can't distinguish "never created" from "deliberately removed." Confirming "no" each time is the workaround until this needs solving properly.

Present the full proposal — files to scaffold, the .claude/settings.json merge diff if any, the CLAUDE.md append if applicable, any hook or settings conflict, and what's already present and left alone — in one block for confirmation before writing anything, the same confirm-then-write pattern as every other step here. Once confirmed and written, run question 2's gate-wiring check above and act on its verdict, then continue below.

Read AGENTS.md (whether just scaffolded or pre-existing). If it has a Review & Planning Guidance section, read the files it names. A named file that doesn't exist yet is not a Rule 2 failure to stop on here — it's expected input to Step 4, whether AGENTS.md was just scaffolded (its two entries default to docs/agent-rules/code-critic.md/plan-critic.md, which Step 4 hasn't created yet) or pre-existing (a project adopting this flow for the first time, whose named or default files may not exist either); Step 5 item 7 decides separately, in whichever mode you end up in, whether a still-missing file gets reported. Otherwise (no section at all) check docs/agent-rules/code-critic.md and docs/agent-rules/plan-critic.md directly. Classify each placeholder / [TODO: …] as filled or open.

• Mostly open → first-run mode: continue with Steps 2–4, then validate.
• Mostly filled → doctor mode: skip to Step 5, then report only what is

open or drifted.

Step 2 — Detect the commands, propose, confirm

Inspect the project's build configuration — whichever exist: package.json scripts, Makefile, justfile, build.gradle(.kts), pom.xml, pyproject.toml, Cargo.toml, go.mod, Gemfile, docker-compose.yml. From them, propose values for every entry in AGENTS.md → Commands:

• build / run-all-tests / all-checks / dev server / stop / single-test

example. Prefer wrapper commands (make …, npm scripts, just …) over raw tools — the wrapper may add environment setup the raw tool skips.

• app URL: from the dev-server config (port, host) if discoverable.
• default branch: git symbolic-ref refs/remotes/origin/HEAD (fall back to

asking).

Present the full proposed Commands list in one block for the user to confirm or correct. Flag any entry you could not derive — a missing stop command or check command is common and worth an explicit decision (the adversarial-qa and feature skills depend on them). After confirmation, write the section, replacing the placeholders.

Step 3 — Fill the remaining AGENTS.md sections

For each still-open section, draft from evidence and confirm before writing:

• Project Overview: draft one paragraph from the project's README and

manifest (purpose, stack, key dependencies). Replace [PROJECT_NAME] in the title.

• Architecture: generate the top-level directory tree (source dirs

only — skip vendored/build output) with a one-line purpose per module, inferred from its contents. Ask the user to correct wrong inferences — a wrong map is worse than no map.

• Testing: name the framework(s) found, where tests live, and how to

run one (mirrors the single-test command).

• Sensitive Areas: propose candidates by scanning for the usual

expensive-mistake surfaces — auth/session/token code, security config, route definitions, payment or billing flows, schema migrations, personal data fields and their rendering paths, secret/config loading. One bullet per confirmed area, naming a concrete file/package/pattern. This list gates three workflow decisions (critic-skip, reviewer model escalation, PR security flag) — an empty list disables those protections, so if the user has no time now, leave the TODO in place and say so in the report.

• Rule 5 (project hygiene rule): ask whether one applies (e.g. reset a

dev database at session end); fill it or delete the placeholder.

Step 4 — Seed review and planning guidance

AGENTS.md's Review & Planning Guidance section takes exactly two entries, labeled precisely Code review guidance and Planning guidance (Step 5 and both skills key on these literal labels — do not paraphrase them).

First ask: does this project already have docs for code review standards and/or planning risk areas — a style guide, CONTRIBUTING.md, an engineering handbook, anything like that? Handle each of the two (code review guidance, planning guidance) independently based on the answer:

• Doesn't have one → copy ${CLAUDE_SKILL_DIR}/templates/docs/agent-rules/code-critic.md

(or plan-critic.md) to the default path as the starting point — it already carries the Rules/Checklist structure, the build-enforced-rules doctrine, and the guidance comments; do not draft either file from scratch. Interview briefly to fill it in, then point AGENTS.md's section at it:

• Does the app hold personal data? Which categories are sensitive, and is

there a compliance doc? Which surfaces are public/unauthenticated? Any identifiers public by design? Do any of the three privacy fitness tests already exist? → fill the Privacy anchors section of docs/agent-rules/code-critic.md.

• Any hard constraints the team already knows agents get wrong (framework

conventions, forbidden APIs, required registrations)? → add them as rules with severities, mirrored in the Checklist section.

• What are this product's highest-risk areas — the places where a generic

plan would miss something that matters here? → fill 4–7 lenses in docs/agent-rules/plan-critic.md.

• Already has one → point AGENTS.md's section at that existing file

instead of copying the template. Still ask the privacy/compliance question above for code review guidance specifically — code-critic binds its privacy rules to whatever ## Privacy anchors section it finds in the named file (see that skill), so if the existing doc doesn't have one, it needs a home. Offer to append a ## Privacy anchors section to the end of the existing file (same headi

…

Source & license

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

• Author: cunhaax
• Source: cunhaax/ai-workflow
• License: MIT

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