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.

<!-- 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.