/init-workspace

name: init-workspace
user-invocable: true
version: 4.10.0
argument-hint: <target-dir>
author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
license: MIT
description: >
  Adapt the workflow scaffold to a new repository or add only missing substrate
  blocks to an existing install. Every install, hook, and overwrite needs
  explicit consent. Triggers: "init-workspace", "set up agentic workflow",
  "upgrade workflow scaffold".

Init Workspace

> **Runner commands** below are `bunx @gtrabanco/agentic-workflow@<pin> …` — read `<pin>` > from [references/RUNNER.md](../runner-contract/references/RUNNER.md). It is stamped at > release and never guessed: a hard-coded version re-opens the per-release sweep the > contract removes, and `latest` is not a legal pin.

Turn an empty or existing repo into one that works with the agentic workflow: copy the generic scaffold, then **tailor it to this project** instead of leaving raw placeholders.

Turn contract — verify before ending the turn

Load and verify the **canonical** [Turn contract](../orchestration-envelope/references/TURN_CONTRACT.md) (11 boxes) before ending every turn. Skill-specific additions (the docs-language and `→ Next:` boxes are canonical-owned and not restated here):

✓ Required user inputs were answered concretely (not defaulted). Consent for
  every install, hook, and overwrite is explicit; a consent gap runs the
  three-tier dispatch and stops with the dispatcher's `open-questions@1` block
  — against a scratch unit folder when no unit exists yet (§Consent).
✓ The project charter's identity layer was asked and answered before any
  substrate byte was copied — never guessed; an unanswered identity question
  halts through the same `open-questions@1` flow (§Charter).
✓ The adapted scaffold and repository-state ledger are written (or the merge/abort decision was asked) and remaining placeholders are listed
✓ Nothing was installed, registered (MCP) or overwritten — including the global
  Serena config — without an explicit yes

About to end the turn with any box unchecked? The turn is NOT done — complete the missing box first (weak models drop end-of-document duties; this list is first on purpose).

When to use

• Setting up a repo to use these skills and you want the documentation substrate

(`AGENTS.md` + `docs/` map + templates) adapted to the project, not just copied.

• Prefer this over a static `npx degit gtrabanco/agentic-workflow/template` when you

want the gate commands, architecture, and doc domains filled in by interview.

Consent — mandatory, never defaulted

Installing a tool, wiring a hook, or overwriting an existing file each need an explicit yes; context never supplies one, and an ambiguous repository state (partially scaffolding) is not a route to guess. A consent gap is an open question: **(0) provenance** (search the repo's own docs and record where) → **(1) research** (concrete options) → **(2) halt**: run `bun `bunx @gtrabanco/agentic-workflow@<pin> needs-input <unit-dir>`, paste the `open-questions@1` block verbatim, stop with the questions carried in it. The dispatcher needs a unit folder, and consent gaps usually precede any unit — so the run first writes a scratch one (`SPEC.md` + `decisions.md` in a `mktemp` directory, deleted after the paste) and runs the dispatcher against that. Grammar and exit codes: `orchestration-envelope`'s `references/TURN_CONTRACT.md` §Open questions. `[target-dir]` is optional — absent means the current directory, recorded.

Identity hardening (#514) — the pre-commit `git-identity-check.sh` hook and an empty `gitIdentity` block — is offered once; a no installs nothing.

Step 0 — Discover the project (always first)

Inspect the target dir (`[target-dir]`, default cwd) before touching anything:

• An existing **agent guide** (`AGENTS.md`, or a legacy `CLAUDE.md`), `docs/`,

`.github/`? If so, **do not clobber** — check first whether it's an **agentic-workflow scaffold** (marker: an agent guide present *and* either `docs/ROADMAP.md` — or the pre-319 `docs/features/ROADMAP.md` — or a `docs/workflow/` dir). If both markers are present, offer **upgrade** as the default action, alongside merge / adapt-in-place / abort — see **Upgrade mode** below. If an agent guide or `docs/` exists but the markers are absent (a foreign scaffold), stay in bootstrap and ask merge / adapt in place / abort as before.

• Detect the stack from manifests (`package.json`, `pyproject.toml`, `go.mod`,

`Cargo.toml`, `Gemfile`, …) to *propose* gate commands and naming conventions.

• Note the git state (is it a repo, what's the default branch, and the **remote

URL → forge**: github.com → GitHub/`gh`, gitlab → GitLab/`glab`, else ask).

• Read the **tool evidence once**: `bunx @gtrabanco/agentic-workflow@<pin>

doctor --json` prints one row per documented tool with its real evidence and a move — take the rows as the tool facts instead of re-deriving a path, a version or a hook by hand. An `instruct-only` row is the exact command to print, an `ask-consent-write` row is the project's own installer and still needs this skill's consent, and a `residual` row names what another owner decides. The row contract is the crate README's `tool-inventory@1` block.

Progressive loading — bootstrap or upgrade, never both

The reference allowlist is exactly the six linked paths below. Never invent or read another `references/` path. Step 0 selects exactly one route:

**Hard rule for an existing Claude Code, Cursor, Copilot, or OpenCode scaffold:** LOAD exactly `references/UPGRADE.md`. A missing committed safety adapter is upgrade work, not a missing vendor primitive. Do not load bootstrap or portability unless the runtime platform has no named adapter at all.

• Bare/foreign repository: read

[bootstrap discovery](references/BOOTSTRAP_DISCOVERY.md), complete its interview — **the charter round first: the identity layer is blocking, the domain layer is op