# Pipeshape Setup

> Sets up a project so pipeshape pipelines run on it. Writes the commands block in CLAUDE.md, checks discipline skills and agents, and prepares the first saved workflow.

- Skill: `terrasnail/pipeshape-setup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add terrasnail/pipeshape-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/terrasnail/pipeshape-setup/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: terrasnail (https://skillmd.com/u/terrasnail)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/terrasnail/pipeshape-setup

---


# pipeshape-setup

Prepare a repository for `pipeshape` and the shipped workflows. Write as little
as possible: one `CLAUDE.md` block, one `.gitignore` line, and at most one
saved workflow the user asked for. Never generate agents or prompt files.

## 0. Audit

Gather all of this in one pass and report it in ten lines or fewer.

- `CLAUDE.md`: does a `<!-- pipeshape start -->` block exist already.
- Build files: `package.json` scripts, `build.gradle*`, `pom.xml`, `Makefile`,
  `pyproject.toml`, `go.mod`, `Cargo.toml`. Derive build, test, and lint
  commands from them. Read; never guess.
- `.claude/workflows/`: saved workflows and their `meta.name`.
- `.claude/agents/`: role definitions and their `name`.
- `.claude/skills/*/SKILL.md`: every project skill, with its `description`
  and whether the directory holds a `pipeline.yml` (v1 pipeline), an
  orchestration procedure (phases, roles, review or QA steps, agent
  spawning), or reusable discipline (conventions, testing rules).
- Discipline skills reachable in this session: `tdd`, `code-review`,
  `diagnosing-bugs`, `codebase-design` (bare or plugin-namespaced).
- Whether the Workflow tool is available.

Pick the branch from the audit: **fresh** (no block, no workflows),
**extend** (block exists), or **migrate** (a v1 pipeline or an orchestration
skill exists; step 1 decides what happens to it).

## 1. Review existing project skills

Always run this step when `.claude/skills/` holds anything, before touching
`CLAUDE.md`. Classify each skill from the audit as one of:

- **v1 pipeline**: the directory has `pipeline.yml`.
- **orchestration skill**: the body walks through development phases
  (analysis, implementation, testing, review, QA), names roles or agents, or
  spawns subagents. A hand-written development harness belongs here.
- **discipline skill**: conventions, testing rules, domain vocabulary,
  anything a workflow agent should follow rather than replace.
- **unrelated**: leave it alone and do not list it.

Present the v1 and orchestration skills in one `AskUserQuestion`, one
question per skill, each with these options and the recommended one first:

- **Port to a workflow**: `pipeshape-tune` migrates a v1 pipeline; for an
  orchestration skill, map its phases to `pipeshape-topologies` snippets and
  write `.claude/workflows/<skill-name>.js`, folding its role text into the
  prompts. Recommended when the skill runs a multi-step procedure.
- **Keep as discipline**: leave the skill in place and list it in the
  `CLAUDE.md` block so workflow prompts reference it by name. Recommended
  when the skill is mostly rules and conventions.
- **Leave unchanged**: record nothing.

Ask once, with every candidate in the same call. Do not port, delete, or edit
any skill before the answer. After porting, propose deleting the old skill
directory; never delete it yourself.

## 2. Confirm commands once

Show the derived build, test, and lint commands and the gate policy in a
single `AskUserQuestion`, with the derived values as the recommended option.
Gate policy is one of `spec-approval` (analysis pauses for approval before
any implementation) or `none`. Ask nothing else.

## 3. Write the CLAUDE.md block

Insert or replace the block between the markers. Keep everything outside the
markers untouched. Create `CLAUDE.md` when it is missing.

```markdown
<!-- pipeshape start -->
## Pipelines

- Build: `<command>`
- Test: `<command>`
- Lint: `<command or "none">`
- Gate policy: spec-approval | none
- State: `.pipeline/<slug>/` holds specs and decisions; gitignored.
- Saved workflows: `.claude/workflows/` (run as `/<name>`); plugin workflows
  `/pipeshape:feature-pipeline`, `/pipeshape:adversarial-review`.
- Agents available as `agentType`: <comma-separated names or "none">.
- Discipline skills present: <names or "none; prompts use inline fallbacks">.
- Project skills kept as discipline: <names or "none">; ported to workflows:
  <skill → workflow name, or "none">.
<!-- pipeshape end -->
```

Add `.pipeline/` to `.gitignore` when the user did not choose to commit
specs.

## 4. Report gaps without fixing them

- Missing discipline skills: name each and give the install command. Do not
  install anything.
- No agents: say that workflows will use the default subagent, and that a
  role definition under `.claude/agents/` becomes usable through `agentType`
  with no other change.
- Workflow tool unavailable: say that `pipeshape` will run shapes in the
  session with the Agent tool until dynamic workflows are enabled in `/config`.

## 5. First workflow

Offer exactly these two options and act on the answer:

- **Run now**: ask for a requirement and invoke `pipeshape` with it.
- **Save a project copy**: copy the plugin's `feature-pipeline.js` to
  `.claude/workflows/<project-slug>-feature.js`, set `meta.name` to the file
  stem, and bake in the confirmed commands and gate policy as defaults at the
  top of the script. Run `node --check` when `node` exists. Tell the user to
  run `/reload-skills`, then `/<project-slug>-feature`.

Skip this step when a saved workflow already exists, including one produced by
porting in step 1.

## 6. Verify and hand over

- Re-read `CLAUDE.md` and confirm the block parses as Markdown with the
  markers intact.
- List what changed: files written, lines added, nothing else.
- Name the next command the user should type.