Meta Pipeline Creator

Write all pipeline content in English, regardless of the project's primary language.

Examples

Six reference patterns in examples/:

implement procedure selection

Before writing

1. Read src/types/pipeline.ts — authoritative schema for all task fields.
2. Read the matching example from examples/ for the chosen pattern.
3. If tasks will use a procedure, read procedures/<skill>/<name>.md to confirm required inputs and which tools it calls.

Naming files

Place new pipelines in pipelines/ root. Never create files inside pipelines/done/ or any subdirectory.

Filename format: <pattern>__<layer>__<target>.(json|yaml|yml)

• __ separates namespace segments; - separates words within a segment
• All lowercase; no underscores within segments, no camelCase

❌ pipelines/review-fix/cli/commands-analyze.json   (subdirectory — forbidden)
✅ pipelines/review-fix__cli__commands-analyze.yaml

❌ pipelines/unitTest__fooService.yaml              (camelCase — forbidden)
✅ pipelines/unit-test__foo-service.yaml

Naming tasks

name doubles as the resume key — a second run resumes the named session instead of starting fresh.

• Format: <taskName>-<role> where role is a noun: implementer, reviewer, committer (e.g. unit-test-foo-service-implementer, unit-test-foo-service-reviewer)
• Stable: no dates or run numbers; unique across all pipelines in the repo

Omit name only for stateless or one-shot tasks.

Reviewer continuity: when a pipeline has an initial reviewer followed by a loop reviewer, both agents MUST share the same name. The loop run resumes the initial session — the reviewer already knows what violations it found and skips re-scanning from scratch. procedure is ignored on resume; the flowchart remains in conversation history. Write the loop reviewer's task as a re-review instruction, not a repeat of the initial inputs. Do NOT split into initial-reviewer / loop-reviewer — that forces a cold-start and wastes tokens re-acquiring context.

See examples/review-fix__layer__target.yaml for a complete working example.

allowed_tools

Start minimal, then add:

1. Standard tools: Read, Write, Edit, Bash
2. MCP tools the procedure calls — full name mcp__<server>__<tool> (e.g. mcp__perclst__ts_test_strategist). Missing MCP tools stall the run on a permission prompt.

Procedures

• Set procedure when the task description would otherwise duplicate the procedure's flowchart logic.
• Keep task minimal — pass only required inputs (e.g. target_file_path: src/foo.ts).
• procedure applies on session start only; ignored on resume.

Nested pipelines

Use type: "pipeline" to group sequences under a named unit. name is required (doubles as rejected.to target).

Use a nested pipeline when:

• An outer script rejection needs to re-run a multi-agent sequence, not just one agent.
• Multiple independent targets each need isolated failure handling.

Multiple targets → sibling pipeline tasks at the top level.

ng_output_path (review rejection)

When a review agent should reject the implement agent:

• Pass ng_output_path: .claude/tmp/<review-agent-name> in the review agent's task.
• Set rejected on the review agent pointing to the implement agent.
• The review agent writes rejection feedback to that file; perclst loops back with it as feedback.

Stale file cleanup: Add a script task as the first item in the outer tasks array to delete the file before the pipeline runs:

{ "type": "script", "command": "rm -f .claude/tmp/<ng-output-path-name>" }

Script gates and rejection loops

Add a script task after each agent (or nested pipeline) that produces testable output:

• command: npm run test:unit (not npm run test)
• rejected.to: the agent or pipeline name to fix the failure
• rejected.max_retries: 2–3 is usually sufficient
• The referenced name must appear before the script task in the same tasks array

Commit task

Assign the commit task to the implement agent (resume the same named session). Never create a standalone commit agent — the implement agent leaves knowledge after committing and has the full context of what changed and why.

Place the commit agent outside the nested pipeline, after the outer script gate. Use the same name as the implement agent so perclst resumes the existing session.

See examples/implement__feature-name.yaml for a complete working example.

Validation

Before running, verify the file with:

bash ${CLAUDE_SKILL_DIR}/scripts/validate-name.sh pipelines/<name>.yaml
node ${CLAUDE_SKILL_DIR}/scripts/validate-schema.cjs pipelines/<name>.yaml

validate-name.sh checks filename conventions (placement, extension, __ separators). validate-schema.cjs parses the file (YAML → JSON if needed) and validates against schemas/pipeline.schema.json.

Running

perclst run pipelines/<name>.yaml   # YAML recommended (more token-efficient)
perclst run pipelines/<name>.json

Checklist

• File at pipelines/<name>.(json|yaml|yml) — not in pipelines/done/ or a subdirectory
• Filename: __ namespace separators, - word separators, all lowercase
• Every MCP tool called by a procedure is listed in allowed_tools
• rejected.to names an existing task in the same tasks array scope
• Task names unique, follow <taskName>-<role> convention (role is a noun: implementer, reviewer, committer)
• task text minimal when procedure is set
• Each agent with testable output is followed by a npm run test:unit gate
• Review agents with ng_output_path have rejected pointing to the implement agent
• Nested pipeline name is set