/sw-init

name: sw-init
description: >-
  Initializes Specwright in a project. Detects stack, asks about practices,
  creates constitution and charter, configures quality gates and hooks.
argument-hint: ""
allowed-tools:
  - Bash
  - Read
  - Write
  - Glob
  - Grep
  - AskUserQuestion

Specwright Init

Goal

Set up Specwright in this project by understanding how the user works, what they're building, and what quality standards they expect. Produce configuration and anchor documents that will guide all future work. Tracked project artifacts should be shared across developers and agent sessions via Git; runtime session state stays local to each clone or worktree. New interactive installs should prefer `project-visible` runtime roots under `.specwright-local/`, while `git-admin` roots under `.git/specwright/` remain compatibility-only.

Inputs

• The codebase (scan for language, framework, dependencies, test runner)
• The user (ask about practices, vision, quality expectations)

Outputs

When complete, ALL of the following exist:

• `{projectArtifactsRoot}/config.json` -- detected + configured project settings
• `{projectArtifactsRoot}/CONSTITUTION.md` -- development practices the AI must follow
• `{projectArtifactsRoot}/CHARTER.md` -- technology vision and project identity
• `{repoStateRoot}/work/` -- shared work root, initialized and empty
• `{worktreeStateRoot}/session.json` -- initialized detached top-level session for

the current worktree

Optional (created if the user opts in):

• `{projectArtifactsRoot}/TESTING.md` -- testing strategy: boundaries,

infrastructure, mock allowances

• Hooks set up if the user wants them
• Operator follow-up: tell the user to run `/sw-status` to confirm the active

runtime roots and detached session state.

Quality gates are configured in config (all six default to enabled; user may disable).

Constraints

**Worktree context (LOW freedom):**

• Check `worktreeContext` per `protocols/context.md`.
• If `linked`, explain that tracked project artifacts under

`{projectArtifactsRoot}` are shared across developers and agent sessions via Git, while runtime session state stays local to each clone or worktree under `{repoStateRoot}` and `{worktreeStateRoot}`.

• If the shared layout already exists, reuse the tracked project artifacts and

shared runtime roots, then create or repair only this worktree's `{worktreeStateRoot}/session.json`.

• If the shared layout does not exist yet, say that `/sw-init` will create the

tracked project-artifact root plus repo-level runtime state under the Git common dir and a session root for the current worktree. This is a warning, not a block.

**Detection (MEDIUM freedom):**

• Scan codebase: language(s), framework(s), package manager, test runner, linting/formatting, git workflow, CI/CD. Read dependency manifests. Don't guess what you can detect.

**Survey (MEDIUM freedom):**

• After detection, survey the codebase using Glob/Grep/Read: directory structure, entry points, module dependencies, conventions, integration points, gotchas.
• Produce `{projectArtifactsRoot}/LANDSCAPE.md` per `protocols/landscape.md` format. User approves before saving.
• Optional — if user declines, skip. LANDSCAPE.md is never required.

**User conversation (HIGH freedom):**

• Ask the user about things you CANNOT detect from the codebase:
• What is this project? Who uses it? (→ CHARTER.md)
• Testing philosophy and coverage expectations? (→ CONSTITUTION.md)
• Security requirements? (→ gate config)
• Code review standards? (→ CONSTITUTION.md)
• Any practices or patterns they insist on? (→ CONSTITUTION.md)
• Use AskUserQuestion with concrete options based on what you detected.
• Batch related questions. Maximum 3-4 questions per interaction.
• Don't ask about things the codebase already answers.

**Constitution creation (HIGH freedom):**

• The constitution captures the user's development practices as clear rules.
• Rules should be specific and actionable, not vague aspirations.
• Bad: "Write clean code." Good: "All public functions must have error handling."
• The user must approve the constitution before it's saved.

**Charter creation (HIGH freedom):**

• The charter captures the project's identity and vision.
• What is this project? What problem does it solve? Who are the consumers?
• What are the architectural invariants (things that won't change)?
• What technologies are foundational (not up for debate)?
• Keep it concise -- one page, not a business plan.
• The user must approve the charter before it's saved.

**Testing strategy creation (HIGH freedom):**

• After constitution and charter are approved, generate `{projectArtifactsRoot}/TESTING.md`.
• Follow `protocols/testing-strategy.md` for document structure and boundary classifications.
• Ask the user about testing boundaries using AskUserQuestion:
• "What external services does this project call?" (payment APIs, email, auth providers, etc.)
• "What's your test database strategy?" (in-memory, testcontainers, shared test DB, none)
• "Are there any rate-limited or cost-attached APIs?" (metered APIs, slow services)
• "Any other expensive or unreliable dependencies?"
• Batch these into 1-2 questions based on what stack detection reveals.

Don't ask about services the codebase doesn't use.

• Generate TESTING.md with required sections:
• **Boundaries**: Classify each detected dependency as `internal` (test with real

components), `external` (mock with contracts), or `expensive` (mock with rationale)

• **Test Infrastructure**: What test database, fixtures, containers, or test servers

are available based on detected stack and user answers

• **Mock Allowances**: Which dependencies may be mocked, with explicit rationale
• **Test Commands** (added after gate configuration): If tiered commands were captured

during gate config, append this section to TESTING.md with the actual commands. See `protocols/testing-strategy.md` Test Commands section. Omi