## Process

1. **Preflight.** Confirm the target dir and the discovery findings. If scaffold
   files already exist, get an explicit decision before overwriting.
2. **Fetch the template.** `npx degit gtrabanco/agentic-workflow/template <dir>`
   (into the target if empty, else a temp dir to merge from). **`degit` can't read
   a private repo — it fails, or in `--mode=git` silently leaves an empty dir; for
   a private source, `git clone` via SSH and copy the `template/` subtree instead.**
3. **Interview to adapt** — small batched rounds, each with a recommended default
   drawn from Step 0; skip whatever discovery already answers:
   - **Project** — name + one-line purpose.
   - **Gate** — dev / build / test commands and the verification gate (proposed
     from the detected stack; confirm).
   - **Forge** — issue/PR tracker + CLI (proposed from the remote URL; confirm)
     → recorded in the Workflow conventions **Forge** line.
   - **Git workflow** — how parallel work is handled: **branches** (default —
     one active unit at a time, sequential, plain `git switch -c`) or
     **worktrees** (parallel units in separate checkouts; only if the user's
     agent/tooling manages them). Recorded in the Workflow conventions
     **Git workflow** line; every skill that creates branches honors it.
   - **Agent safety hooks** — detect where the agent actually runs and which
     repository adapters apply: Claude Code, Cursor, Copilot, OpenCode, or none.
     Recommend the shared command guard for every detected platform; explain
     that shell adapters require `jq`, OpenCode uses the bundled Bun plugin,
     and hooks are defense-in-depth behind forge rulesets. Ask one explicit
     yes/no per adapter before activating it. Remote/VPS execution is not a
     reason to skip: commit the repository adapter so the remote clone loads it.
   - **Docs language.**
   - **Architecture** — pattern, layers/modules, and dependency-direction rules
     (stay architecture-agnostic; record the user's choice in `ARCHITECTURE.md`).
   - **Doc domains** — which of `providers/ brand/ domain/ business/
     infrastructure/ legal/ frontend/` apply. **Delete the folders that don't**
     (e.g. `frontend/` for a non-UI project).
   - **Capability inventory** (`docs/CAPABILITIES.md` — the substrate
     `design-feature`'s Integration closure walks). Seed it from discovery,
     not raw placeholders: on an existing codebase, propose the roles and the
     `yes|no|partial` state of each template subsystem row (auth, ACL,
     navigation, notifications, search, audit, settings, jobs, storage, i18n,
     flags, billing, public API) from what the code actually shows; on an
     empty repo, walk the same fixed rows with the user (`no` is a valid,
     load-bearing answer). Delete rows that can never apply to this product;
     confirm the result in one round — never leave the file as the raw
     template.
   - **Performance tooling** — detect what the stack offers, one slot at a
     time (fixed checklist, first match per slot; record `none` explicitly
     when nothing fits — never leave the slot undiscussed):
     - *Static complexity lint*: Biome present → enable its `complexity`
       group (incl. `noExcessiveCognitiveComplexity`); ESLint present →
       suggest `eslint-plugin-sonarjs` + `eslint-plugin-unicorn`; neither →
       ask for the stack's equivalent or record `none`.
     - *Benchmark harness*: Vitest → `vitest bench`; Bun runtime → `mitata`;
       Node → `tinybench`/`mitata`; other stacks → ask for the project's
       benchmark command or record `none`.
     - *Profiler*: Node → `node --cpu-prof` (zero-dependency default) or `0x`
       via the project's package runner; Bun → `bun --inspect` CPU profiling;
       other → ask or record `none`.
     (The named tools are the TS/JS **adapter examples**; the contract is the
     generic block below.) Offer installation — **the user confirms each
     dependency; never install silently** — and register the outcome in the
     template's `Performance commands` block next to the verification gate,
     so `review-perf` can measure instead of guess.
   - **Docs site** — does the project have (or want) a developer docs website
     the `generate-docs` skill can write into? If yes, fill the template's
     `Docs site` block in `CLAUDE.md` (format: starlight/docusaurus/markdown,
     content dir, build command, optional knowledge-map command — proposed
     from discovery: an `astro.config.*` + `@astrojs/starlight` dependency
     means Starlight). If no, leave the block commented out — `generate-docs`
     then reports NOT-CONFIGURED instead of guessing. Never scaffold the
     website itself.
   - **Naming conventions** and **MCP servers**, if any.

## Write and verify the bootstrap

4. **Write the adapted scaffold.** Fill the `CLAUDE.md` placeholders (commands,
   the documentation map rows, architecture); keep `AGENTS.md`, the
   `features/_TEMPLATE` + `ROADMAP`, the `fix/_TEMPLATE` + `README`, and the
   `.github/` templates; keep `.agentic-workflow/hooks/` and activate only the
   adapters explicitly accepted in the interview; prune unused doc folders and
   map rows. Leave honest placeholders where the user hasn't decided — never
   invent values.
5. **Seed Normalized Repository State.** Copy
   `template/docs/workflow/REPOSITORY_STATE.md` to
   `docs/workflow/REPOSITORY_STATE.md` when it is absent. If the target already
   has one, leave it unchanged and report that discovery should refresh it.
   Explain that discovery freezes evidence before planning and only
   `resolve-repository-state` updates frozen facts.
6. **Offer architectural invariants.** Keep
   `docs/architecture/ARCHITECTURAL_INVARIANTS.md` from the template only when
   the project has long-lived architectural constraints. Explain that it is
   optional: an absent document means no project invariants are declared, not
   that the scaffold failed. If retained, add its documentation-map row and
   name the project's explicit architectural-decision authority.
7. **Install accepted agent safety hooks.** Keep the canonical policy and
   fullauto wrapper at `.agentic-workflow/hooks/`. For each accepted platform,
   activate only its repository config/example as documented in the hook pack.
   Run `bash .agentic-workflow/hooks/tests/test-command-guard.sh`; missing `jq`,
   an unknown payload, or an existing customized hook file becomes a residual,
   never a silent overwrite. Direct merges remain blocked; do not create a
   `.automerge` exception.
8. **Offer the workflow skills.** Propose installing them:
   `npx skills add gtrabanco/agentic-workflow` (note the SSH/local-path variant if
   the source is private). Don't install without a yes.
9. **State that reviews are self-contained; offer optional extras.** The
   workflow ships its **own internal review pack** (`review-code`,
   `review-security`, `review-verify`, `review-debt`, `review-design`,
   `review-a11y`, `review-brand`, `review-perf`, `review-seo`) — it installs
   with the skills and covers every review axis, so **no external review skill
   is required on any agent**. If the user wants platform-specific extras (a
   framework skill, a stack-specific security skill), record them in `CLAUDE.md`
   under a short "Optional review extras" note so `review-change` and
   `product-audit` run them **in addition** — never as a dependency. Don't
   install anything without a yes.
10. **Seed the urgency labels (feature 15, injection-safe urgency).** Create the
   two capability-gated GitHub labels `triage-issue` owns and applies
   (`skills/triage-issue/SKILL.md` is the sole owner of the name/color
   vocabulary — this step only seeds it, never redefines it):
   `gh label create urgent --color B60205 --description "Evaluate for
   interrupt-now — reaches the pause-vs-finish judge"` and
   `gh label create fix-next --color D93F0B --description "Head of the fix
   queue — never interrupts the in-flight unit"`. Create-if-missing: an
   "already exists" error from `gh label create` is treated as success, not a
   failure. Requires the forge remote/auth Step 0 already detected — if the
   forge is unavailable or the user declines forge setup, skip this step and
   list the two labels as a residual for the user to create manually later
   (never fail the whole scaffold on it).
11. **Report.** List what was created, which placeholders still need human input,
   the companion skills recorded/installed, the urgency labels seeded (or
   skipped, with reason), and the next step: `discover-repository-state` →
   `design-feature` → `plan-feature` → `execute-phase`.

## Portability (agents other than Claude Code)

The workflow is the contract; Claude Code features are conveniences. On an
agent that lacks one, apply the fallback — never skip the step the feature
enables:

- **No slash-command menu** — where this skill says `/<skill>`, open that
  skill's `SKILL.md` (wherever your agent installed the skills) and follow it
  literally, in a fresh conversation: hand-offs assume a clean context.
- **No per-skill `model:`/`effort:`** — on the `#claude` branch the frontmatter pins these tiers; here, pick tiers yourself:
  the interview and adaptation are judgment work — run them on your
  **strongest** model.
- **No Claude Code hooks** — choose the Cursor, Copilot, or OpenCode adapter
  when available. If the agent exposes no pre-tool hook, report the safety hook
  as unavailable and keep forge rulesets as the hard boundary; `log-session`
  remains the manual logging alternative.

## Upgrade mode

Entered when Step 0 finds an existing **agentic-workflow scaffold** (not a
bare or foreign repo). Bootstrap mode (the Process section above) never
engages here — upgrade mode reuses the same discovery + interview machinery,
scoped to **only the blocks the current template has that this project
lacks**. Seven ordered steps:

1. **Locate the current template.** Fetch the current `template/` the same
   way bootstrap does — `npx degit gtrabanco/agentic-workflow/template <temp-dir>`
   (always into a temp dir here, never into the target); the SSH/local-path
   variant applies verbatim for a private source.
2. **Diff the substrate.** Compare the project's `CLAUDE.md` (and the `docs/`
   blocks its documentation map references) against the fetched template.
   Produce the list of blocks/conventions the template carries that this
   project's substrate lacks, or still holds as a raw, unfilled placeholder —
   e.g. a `Docs site` block, a `Performance commands` block, a `Git workflow`
   line, the five-state roadmap `Status legend`, the capability inventory
   (`docs/CAPABILITIES.md` + its documentation-map row), the optional
   architectural-invariants document
   (`docs/architecture/ARCHITECTURAL_INVARIANTS.md` + its documentation-map
   row), the portable command-guard pack and detected platform adapter, or the Normalized
   Repository State ledger (`docs/workflow/REPOSITORY_STATE.md`). This is the
   diff-against-current-template contract; it is the only source of *what's
   new*. (A missing `docs/CAPABILITIES.md` is proposed with the same
   discovery-seeded defaults bootstrap's interview uses — never as the raw
   template. A missing repository-state ledger is proposed from the template
   without overwriting any existing ledger.)
3. **Read `docs/workflow/MIGRATION.md`.** For each missing block, pull its
   dated migration note so the proposal explains *why* the block exists and
   *what* it migrates. If `MIGRATION.md` is absent, proceed on the template
   diff alone and say so in the report — never block on a missing note.
4. **Propose only the missing blocks — one short, batched interview round.**
   Each item is the block, a discovery-based default (the same detection
   bootstrap mode already runs — e.g. `astro.config.*` + Starlight ⇒ `Docs
   site` default, Biome ⇒ the complexity-lint slot, the remote URL ⇒ forge),
   and the `MIGRATION.md` rationale when available. The user accepts, edits,
   or skips each block. **Never re-ask what the project already answered** —
   a block that's already filled is skipped, not re-interviewed.
5. **Write additively.** Insert accepted blocks, including a missing
   `docs/workflow/REPOSITORY_STATE.md`; fill raw, still-placeholder
   blocks with the confirmed values. **Never rewrite a block the project has
   already tailored, and never delete anything** — a tailored block the
   template also changed is left untouched and listed as a residual, not
   silently updated. For hooks, add the canonical pack when absent and activate
   a platform adapter only after an explicit yes; never replace an existing
   platform hook config. Leave honest placeholders where the user skipped.
6. **Seed missing urgency labels, additively (feature 15).** Independent of
   the `CLAUDE.md`/`docs/` block diff above (this is forge-repo state, not a
   doc block): check whether the target repo already has the `urgent` and
   `fix-next` labels (`gh label list`); create whichever is missing with the
   same `gh label create` calls bootstrap mode uses (see Process step 9) —
   never touch a label that already exists (additive-only, same never-clobber
   rule as the doc blocks; a pre-existing `urgent`/`fix-next` label the
   project recolored or redescribed is left exactly as-is).
7. **Report + hand off.** Summarize blocks added, filled, and skipped
   (residuals), the urgency labels seeded (or already present), then print the
   recommendation to run `product-audit` next to see which newly-available
   *capabilities* apply to the code (upgrade mode migrates the substrate only,
   never the code).

**Failure edges — handle each explicitly, never silently:**

- **No drift.** The diff (step 2) finds nothing missing or placeholder-only →
  skip the interview entirely and report **"substrate current, nothing to
  migrate"**. Never fabricate a block to propose just to have something to
  show.
- **`MIGRATION.md` absent.** An older install may predate this file → proceed
  on the template diff alone (step 3 already covers this) and say so plainly
  in the proposal and the final report: rationale was unavailable, the block
  list is still complete.
- **A block the project already tailored.** If the current template also
  changed a block the project customized, **do not merge, diff-patch, or
  overwrite it** — leave it exactly as the project has it and list it as a
  residual in the report (step 5's never-clobber invariant). The user decides
  separately, via an explicit bootstrap adapt-in-place run, whether to
  re-tailor it.
- **Bootstrap stays unchanged on a bare or foreign repo.** If Step 0's
  scaffold markers (`CLAUDE.md` + `docs/features/ROADMAP.md` or
  `docs/workflow/`) are absent — no repo, an empty repo, or a `CLAUDE.md`
  that isn't this workflow's — upgrade mode never engages; the existing
  bootstrap Process (merge/adapt/abort) runs exactly as before this mode was
  added.