Setup Repo

Setup Repo

Create or update the three Sculptor config files:

• .sculptor/code.md — codebase structure, branch naming, build/run commands, pre-commit verification
• .sculptor/testing.md — test framework, test strategy, bug tracking, manual testing, visual verification
• .sculptor/docs.md — where specs and their associated docs live, where to find UI to imitate (for mocks), which skill to invoke for the code-review pass

The configs deliberately cover locations and operational commands, not document structure or writing conventions. Spec, mock, architecture, and plan structure is baked into the workflow skills — to keep agent behaviour consistent across repos.

Other skills (/sculptor-workflow:fix-bug, /sculptor-workflow:spec, /sculptor-workflow:mock, /sculptor-workflow:architect, /sculptor-workflow:plan, /sculptor-workflow:review) read these configs.

Step 1: Check for existing configs

Read .sculptor/code.md, .sculptor/testing.md, and .sculptor/docs.md from the repo root.

• If all three exist: you are updating. Show the user what's currently configured and ask what they'd like to change. Skip to Step 3 to make the edits.
• If some exist but not others: read the existing ones for context, then continue to Step 2 to create the missing ones. You can also offer to update the existing ones at the same time.
• If none exist: you are setting up from scratch. Continue to Step 2.

Step 2: Ask the user how to proceed

Ask with your question tool:

I'd like to set up Sculptor configs for this repo so I can build, test, and fix bugs effectively. This is a one-time setup — the configs will be saved to .sculptor/code.md, .sculptor/testing.md, and .sculptor/docs.md for future use.

How would you like to proceed?

Option A: I'll explore the repo to auto-detect your project structure, build commands, test framework, and conventions, then confirm with you.

Option B: You tell me directly — maybe you already have docs, skills, or specific instructions you'd like me to follow.

Option C: A mix — I'll auto-detect what I can, then ask you about the rest.

Wait for the user's response before proceeding.

Step 3: Gather information

Based on the user's choice, gather the information below. For auto-detection, look at package.json, pyproject.toml, Cargo.toml, Makefile, justfile, CLAUDE.md, existing test files, directory structure, and CI config.

Cap auto-detection effort: if you haven't found clear answers after reading ~10 files, stop and ask the user.

Code config information

Required:

Optional (ask about these — the user may or may not have them):

Publishing changes — what to ask:

This section is read by autonomous workflows (e.g. /fix-bug --autonomous) to decide whether and how to push and open an MR/PR on the user's behalf. Ask the user enough to fill in:

• Push command — usually git push -u origin <branch>, but some teams push to a different remote.
• MR/PR tool — glab (GitLab), gh (GitHub), or manual (no CLI; the team opens the MR/PR in the browser).
• Target branch — usually main, sometimes master or a release branch.
• Title and body — autonomous skills compose a detailed title and body themselves (see ## Proof of Work below) and pass them via --title / --description (glab) or --title / --body (gh). The captured command is the base command only — do NOT include --fill in it, because --fill would substitute a thin commit message and defeat the Proof of Work template.
• Auto-publish allowed — yes or no. If no, autonomous workflows must stop after committing the fix and leave publishing to the user. Default to no if the user is unsure — they can flip it later.
• Merge defaults — properties of the MR/PR set at creation time. Ask each as a plain yes/no:
  • Delete source branch on merge?
  • Squash on merge?
  • Auto-merge when CI passes?
  • Open as draft?
• Conventions (optional) — required labels, reviewers, title format, body template.

Assemble the MR/PR command from the tool + target branch + merge defaults using the table below. Write the assembled command into .sculptor/code.md so the autonomous workflow can run it verbatim — don't make the workflow re-derive flags at runtime.

For gh, the squash / delete-source-branch defaults can't be set at create time — they're applied when the PR is merged. Capture them in the Merge defaults block anyway (so the autonomous workflow can append the right flags to a later gh pr merge call, and so a human reviewer can see the intent).

If the team picks manual, write the manual flow as prose under Create MR/PR (e.g. "open the GitLab compare URL printed by git push") and skip the flag table.

Proof of work — what to ask:

This section is read by autonomous workflows to decide what evidence to gather while fixing a bug and what to paste into the MR/PR body. It's the team's standard for what proves a fix is real. Ask the user enough to fill in:

• UI-visible bugs — screenshot tooling. What does the team use to capture before/after screenshots? Common answers:
  • /auto-qa-changes (Sculptor's headless-browser harness, ideal for any repo with a frontend the skill can drive)
  • OS-level screenshot tools (macOS Screenshot, ShareX) for desktop apps
  • Screen recordings (QuickTime, Loom) when motion matters
• Non-UI bugs — what artifacts. Usually the failing-test commit hash plus the test runner output showing it now passes. Some teams also want logs, a benchmark before/after, or a curl-based repro transcript.
• Required vs nice-to-have. Is the evidence MANDATORY for every MR/PR, or just expected when applicable? Default to mandatory if the user is unsure — it's easy to relax later.

The goal of this section is to make the standard explicit so autonomous workflows produce MR/PR bodies a reviewer can trust without re-running the repro themselves.

Docs config information

Required:

Spec structure, mock conventions, and architecture structure are not configured here — they're baked into the workflow skills so agent behaviour stays consistent across repos. Don't ask the user about them.

Auto-written (do NOT ask): .sculptor/docs.md also includes a ## UI Reference section (empty placeholder with a guiding comment). The /sculptor-workflow:mock skill reads it to learn how to match your app's visual style. The user can fill it in later.

Auto-written (do NOT ask): .sculptor/docs.md also includes a ## Code Review section naming the skill that /sculptor-workflow:review invokes for the code-review pass. Auto-detect:

• If .claude/skills/code-review-checklist/SKILL.md exists in the repo, write Skill: /code-review-checklist.
• Otherwise leave the field empty — /sculptor-workflow:review will skip the code-review pass and only verify requirements coverage and tests.

The user can edit either section later.

Testing config information

Required:

Optional (ask about these — the user may or may not have them):

Step 4: Write the configs

Write all three files using the templates below. Only include sections that are relevant — omit optional sections that don't apply.

.sculptor/code.md

# Code

## Code Structure
- **<component>:** `<path>` (<brief description>)

## Branch Naming
- **Bug-fix branches:** <pattern, e.g. `<name>/bugs/<ticket-id>`>
- **Feature branches:** <pattern, e.g. `<name>/<feature-description>`>
- **Example:** <e.g. `jane/bugs/PROJ-42`, `fix/login-crash`>

## Build
- **Full build:** `<command>`

## Run
- **Dev mode:** `<command>`

## Pre-commit Verification
- **Format:** `<command>`
- **Check (lint + types):** `<command>`
- **Unit tests:** `<command>`

## Publishing Changes
- **Push command:** `<command, e.g. git push -u origin <branch>>`
- **Create MR/PR (base command):** `<assembled command WITHOUT --fill, e.g. glab mr create --target-branch main --remove-source-branch>` <!-- autonomous skills append --title / --description (glab) or --title / --body (gh) at runtime -->
- **Auto-publish allowed:** `<yes | no>` <!-- read by autonomous skills; if "no", they stop after committing and let the user publish -->

### Merge defaults
- **Delete source branch on merge:** `<yes | no>`
- **Squash on merge:** `<yes | no>`
- **Auto-merge when CI passes:** `<yes | no>`
- **Open as draft:** `<yes | no>`

### Conventions (optional)
- <required labels, reviewers, title format, body template>

## Proof of Work

Every MR/PR opened by an autonomous skill must include evidence that the
bug existed and is now fixed. The MR/PR body walks a reviewer through:

1. **Original bug** — exact description (and ticket link, if any).
2. **Reproduction** — repro steps, plus before-evidence (screenshots / logs /
   error trace) showing the buggy behavior.
3. **Hypothesis** — what code path was responsible and why.
4. **Fix** — what changed and why it addresses the cause.
5. **Proof the fix works** — after-evidence (screenshots / test output /
   logs) showing the correct behavior, plus a link or hash for the
   failing-test commit.

### Optional sections (only when applicable)
- **`## Deferred follow-ups`** — list any adjacent work the agent
  consciously left out of this MR. If the testing config has a
  "How to file new tickets" entry point, each item MUST also have a
  tracker ticket URL next to it. Omit the section entirely if no
  work was deferred.
- **`## Review notes`** — populated by the fix-bug self-review pass
  with any code-review findings the agent declined to act on.
  Required after every autonomous fix-bug run: if the agent acted on
  every finding (or found none), write `_(no outstanding review
  notes)_` so a reviewer knows the review pass ran.

### Evidence tooling
- **UI-visible bugs:** <e.g. capture before/after with `/auto-qa-changes`>
- **Non-UI bugs:** <e.g. paste the failing-then-passing test output from `/run-integration-test`>
- **Other artifacts (optional):** <e.g. logs, benchmark deltas, curl transcripts>

### Required vs optional
- **Required for every MR/PR:** <yes | no, with conditions> <!-- e.g. "yes for any UI-visible change" -->

## Dependencies (optional)
- **Install:** `<command>`

## Environment Setup (optional)
- <any required env vars, config files, or services>

## Deployment (optional)
- <how to deploy or release>

.sculptor/docs.md

Write the file exactly as below, substituting the path pattern from the user's answer and (if auto-detected) the Code Review skill.

# Docs

Locations and operational config for the sculptor-workflow skills.
Document structure (spec sections, architecture sections, mock
conventions, plan layout) is baked into the skills — not configured
here.

## Spec Location
- **Path pattern:** <from the user's answer, e.g. `specs/<slug>/spec.md`>

## UI Reference

<!--
  Optional: tell the `/sculptor-workflow:mock` skill how to match your app's
  visual style. Examples:
    - "Read frontend/src/components/ for the component library."
    - "See docs/design-system.md for tokens and spacing."
    - "Use the Storybook at localhost:6006."
    - "Standalone project — no existing app to match."
  If empty, the mock skill will scan the repo for UI code on its own.
  If there is neither a UI Reference nor discoverable frontend code, the
  mock skill will ask for direction before generating.
-->

## Code Review

The configured skill below is invoked for code-review passes by:
- `/sculptor-workflow:review` at the end of the full feature workflow.
- `/sculptor-workflow:fix-bug`'s self-review phase (Phase 4 interactive
  / Phase A4.5 autonomous), so a fix isn't considered done until its
  diff has been reviewed.

<!--
  Set this to your repo's review skill, e.g. /code-review-checklist.
  If left empty, both /review and fix-bug's self-review phase skip
  the code-review pass.
-->

Skill: <skill-name>

.sculptor/testing.md

# Testing

## Test Strategy
<when to write e2e vs unit tests, and when to skip tests entirely>

## Test Framework
- **Framework:** <name>
- **Run a test file:** `<command>`
- **Run a single test:** `<command>`
- **Run e2e tests:** <command or skill — omit this line if e2e tests run with the same command as unit tests>
- **Test location:** <where test files go>
- **Conventions:** <naming, fixtures, patterns, or "see <file> as reference">

## Bug Tracking (optional)
- **System:** <name>
- **Ticket ID format:** <pattern, e.g. SCU-123, PROJ-42>
- **How to fetch ticket context:** <instructions or skill name>
- **When to fetch:** <e.g. "whenever input matches ticket format", "always required", "only if user provides a ticket ID">
- **How to file new tickets:** <instructions or skill name + entry point, e.g. "use the `/linear` skill's `create-ticket` entry point"> <!-- read by /fix-bug autonomous mode to file deferred-work follow-ups -->
- **How to comment on tickets:** <instructions or skill name + entry point, e.g. "use the `/linear` skill's `comment` entry point"> <!-- read by /fix-bug autonomous mode to leave evidence on tickets the agent declines to fix -->
- **How to change ticket state:** <instructions or skill name + entry point, e.g. "use the `/linear` skill's `set-state` entry point"> <!-- read by /fix-bug autonomous mode to move tickets to a "needs info" state -->
- **Needs-info state name:** <workflow-state name, e.g. `Triage`, `Needs Info`, `Awaiting Reporter`> <!-- the state /fix-bug autonomous mode moves a ticket to when it concludes the bug is unreproducible from the description -->


## Manual Testing (optional)
- **How to test:** <instructions or skill name>
- **Notes:** <any setup steps, URLs, or caveats>

## Visual Verification (optional)
- **How to verify:** <instructions or skill name>

## Test Debugging (optional)
- **How to debug:** <instructions or skill name>

## Test Writing (optional)
- **How to write tests:** <instructions or skill name>
- **Test types and locations:** <if there are multiple categories>

Step 5: Write, confirm, and commit

Write the files

Write all three files to .sculptor/code.md, .sculptor/testing.md, and .sculptor/docs.md.

Ask the user to review

Use your question tool to ask the user to review the files:

I've written the config files to .sculptor/code.md, .sculptor/testing.md, and .sculptor/docs.md. Please review them and let me know if anything needs to be adjusted.

You MUST ask with your question tool here — mcp__sculptor__ask_user_question if it's available, otherwise the built-in AskUserQuestion — not a plain text message. The tool call is what raises the "waiting for input" status that alerts the user. The tool triggers a UI notification in Sculptor that grabs the user's attention — without it, the user may not notice the question.

Wait for the user's response. If they request changes, update the files and confirm again.

Commit

Once the user confirms, commit the files:

git add .sculptor/code.md .sculptor/testing.md .sculptor/docs.md
git commit -m "Add Sculptor repo config"