pipeline-sdk 0.1.0

package/src/mcp/server.ts

@@ -0,0 +1,211 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+	CallToolRequestSchema,
+	GetPromptRequestSchema,
+	ListPromptsRequestSchema,
+	ListResourcesRequestSchema,
+	ListToolsRequestSchema,
+	ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import type { EvidenceStore } from "../core/evidence";
+import type { StateMachine } from "../core/state-machine";
+import type { PipelineDefinition } from "../types";
+import { createStagePrompt } from "./prompts";
+import { createPipelineResources } from "./resources";
+import { createPipelineTools } from "./tools";
+
+export function createMcpServer(
+	machine: StateMachine,
+	pipeline: PipelineDefinition,
+	_evidenceStore: EvidenceStore,
+) {
+	const server = new Server(
+		{ name: "pipeline-sdk", version: "1.0.0" },
+		{
+			capabilities: {
+				tools: {},
+				resources: {},
+				prompts: {},
+			},
+		},
+	);
+
+	const tools = createPipelineTools(machine);
+	const resources = createPipelineResources(machine, pipeline);
+
+	// ─── Tools ────────────────────────────────────────────────
+
+	server.setRequestHandler(ListToolsRequestSchema, async () => ({
+		tools: [
+			{
+				name: "pipeline_check",
+				description: "Check whether a tool is allowed in the current pipeline stage.",
+				inputSchema: {
+					type: "object",
+					properties: {
+						tool: { type: "string", description: "Tool name to check" },
+						command: { type: "string", description: "Optional command string" },
+					},
+					required: ["tool"],
+				},
+			},
+			{
+				name: "pipeline_advance",
+				description: "Advance the pipeline by firing a transition event.",
+				inputSchema: {
+					type: "object",
+					properties: {
+						event: { type: "string", description: "Transition event name, e.g. STAGE_COMPLETE" },
+					},
+					required: ["event"],
+				},
+			},
+			{
+				name: "pipeline_signal",
+				description: "Deliver a signal to clear a named gate.",
+				inputSchema: {
+					type: "object",
+					properties: {
+						signal: { type: "string", description: "Signal name" },
+						gate_id: { type: "string", description: "Gate ID to clear" },
+						source: { type: "string", description: "Optional signal source" },
+					},
+					required: ["signal", "gate_id"],
+				},
+			},
+			{
+				name: "pipeline_status",
+				description: "Return the current pipeline stage and gate status.",
+				inputSchema: {
+					type: "object",
+					properties: {},
+				},
+			},
+		],
+	}));
+
+	server.setRequestHandler(CallToolRequestSchema, async (req) => {
+		const { name, arguments: args } = req.params;
+		const input = (args ?? {}) as Record<string, string>;
+
+		let result: unknown;
+
+		switch (name) {
+			case "pipeline_check":
+				result = tools.check({ tool: input.tool, command: input.command });
+				break;
+			case "pipeline_advance":
+				result = tools.advance({ event: input.event });
+				break;
+			case "pipeline_signal":
+				result = tools.signal({
+					signal: input.signal,
+					gate_id: input.gate_id,
+					source: input.source,
+				});
+				break;
+			case "pipeline_status":
+				result = tools.status();
+				break;
+			default:
+				return {
+					content: [{ type: "text" as const, text: `Unknown tool: ${name}` }],
+					isError: true,
+				};
+		}
+
+		return {
+			content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+		};
+	});
+
+	// ─── Resources ────────────────────────────────────────────
+
+	server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+		resources: [
+			{
+				uri: "pipeline://state/current",
+				name: "Current Pipeline State",
+				mimeType: "application/json",
+			},
+			{
+				uri: "pipeline://instructions/current",
+				name: "Current Stage Instructions",
+				mimeType: "application/json",
+			},
+			{
+				uri: "pipeline://gates/available",
+				name: "Available Gates",
+				mimeType: "application/json",
+			},
+		],
+	}));
+
+	server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+		const { uri } = req.params;
+		const handler = resources[uri as keyof typeof resources];
+
+		if (!handler) {
+			throw new Error(`Unknown resource: ${uri}`);
+		}
+
+		const content = handler();
+		return {
+			contents: [
+				{
+					uri: content.uri,
+					mimeType: content.mimeType,
+					text: content.text,
+				},
+			],
+		};
+	});
+
+	// ─── Prompts ──────────────────────────────────────────────
+
+	server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+		prompts: [
+			{
+				name: "pipeline_stage_prompt",
+				description: "System prompt for the current pipeline stage.",
+				arguments: [
+					{
+						name: "stage",
+						description: "Stage name (defaults to current stage)",
+						required: false,
+					},
+				],
+			},
+		],
+	}));
+
+	server.setRequestHandler(GetPromptRequestSchema, async (req) => {
+		const { name, arguments: args } = req.params;
+
+		if (name !== "pipeline_stage_prompt") {
+			throw new Error(`Unknown prompt: ${name}`);
+		}
+
+		const stageName = (args as Record<string, string> | undefined)?.stage ?? machine.currentStage;
+		const text = createStagePrompt(pipeline, stageName);
+
+		return {
+			description: `Stage prompt for "${stageName}"`,
+			messages: [
+				{
+					role: "user" as const,
+					content: { type: "text" as const, text },
+				},
+			],
+		};
+	});
+
+	return {
+		server,
+		async startStdio(): Promise<void> {
+			const transport = new StdioServerTransport();
+			await server.connect(transport);
+		},
+	};
+}

package/src/mcp/tools.ts

@@ -0,0 +1,52 @@
+import type { StateMachine } from "../core/state-machine";
+import type { IpcResponse } from "../types";
+
+export function createPipelineTools(machine: StateMachine) {
+	return {
+		check(input: { tool: string; command?: string }): IpcResponse {
+			const allowedTools = machine.allowedTools;
+			if (allowedTools.length === 0) {
+				return {
+					allowed: true,
+					current_stage: machine.currentStage,
+					allowed_tools: [],
+				};
+			}
+			const allowed = allowedTools.includes(input.tool);
+			return {
+				allowed,
+				current_stage: machine.currentStage,
+				allowed_tools: allowedTools,
+				reason: allowed
+					? undefined
+					: `Tool "${input.tool}" not allowed in stage "${machine.currentStage}"`,
+			};
+		},
+
+		status(): IpcResponse {
+			const stage = machine.currentStageDefinition;
+			const state = machine.exportState();
+			return {
+				stage: machine.currentStage,
+				gates_remaining: stage?.gates?.exit ?? [],
+				elapsed: `${Math.round((Date.now() - new Date(state.started_at).getTime()) / 1000)}s`,
+			};
+		},
+
+		advance(input: { event: string }): IpcResponse {
+			const result = machine.transition(input.event);
+			return {
+				transitioned: result.success,
+				new_stage: result.newStage,
+				error: result.error,
+			};
+		},
+
+		signal(input: { signal: string; gate_id: string; source?: string }): IpcResponse {
+			return {
+				received: true,
+				gate_cleared: input.gate_id,
+			};
+		},
+	};
+}

package/src/templates/infra-gitops.yaml

@@ -0,0 +1,37 @@
+pipeline:
+  id: infra-gitops
+  version: 1
+  description: "Infrastructure changes with mandatory approval"
+  initial: validate
+  stages:
+    validate:
+      description: "Validate manifests and configs"
+      on:
+        STAGE_COMPLETE: { target: preview }
+    preview:
+      description: "Deploy to staging environment"
+      on:
+        STAGE_COMPLETE: { target: approve }
+        HEALTH_FAIL: { target: validate }
+    approve:
+      description: "Human approval required"
+      gates:
+        entry: [human-approval]
+      on:
+        APPROVED: { target: production }
+        REJECTED: { target: validate }
+    production:
+      description: "Deploy to production"
+      on:
+        STAGE_COMPLETE: { target: complete }
+        HEALTH_FAIL: { target: rollback }
+    rollback:
+      on:
+        ROLLBACK_COMPLETE: { target: complete }
+    complete:
+      type: terminal
+
+  gates:
+    human-approval:
+      type: async
+      signal: approval

package/src/templates/sdlc-full.yaml

@@ -0,0 +1,69 @@
+pipeline:
+  id: sdlc-full
+  version: 1
+  description: "Full SDLC enforcement for production monorepos"
+  initial: planning
+  stages:
+    planning:
+      description: "Analyze requirements and create implementation plan"
+      agent:
+        instructions: "Create a detailed implementation plan with TDD"
+        tools: [Read, Grep, Glob, Write, WebSearch]
+      gates:
+        exit: [plan-document-exists]
+      on:
+        STAGE_COMPLETE: { target: implement }
+    implement:
+      description: "Write code following TDD red-green-refactor"
+      agent:
+        instructions: "Implement using TDD. Write failing test first."
+        tools: [Read, Write, Edit, Bash, Grep, Glob]
+      gates:
+        exit: [lint-pass, typecheck-pass, tests-pass]
+      on:
+        STAGE_COMPLETE: { target: review }
+        TESTS_FAIL: { target: fix }
+    fix:
+      description: "Fix failing tests or lint issues"
+      max_retries: 3
+      agent:
+        instructions: "Fix the failures. Do not change test expectations."
+        tools: [Read, Edit, Bash, Grep]
+      on:
+        FIX_COMPLETE: { target: implement }
+        MAX_RETRIES: { target: escalate }
+    review:
+      description: "Code review gate"
+      on:
+        APPROVED: { target: deploy }
+        CHANGES_REQUESTED: { target: implement }
+    deploy:
+      description: "Deploy to production"
+      gates:
+        exit: [build-succeeds]
+      on:
+        STAGE_COMPLETE: { target: complete }
+    escalate:
+      type: terminal
+      description: "Human intervention required"
+    complete:
+      type: terminal
+      description: "Pipeline succeeded"
+
+  gates:
+    plan-document-exists:
+      type: custom
+      script: "test -f docs/plan.md"
+      expect: { status: pass }
+    lint-pass:
+      type: builtin
+      command: "bun run lint"
+    typecheck-pass:
+      type: builtin
+      command: "bun run typecheck"
+    tests-pass:
+      type: builtin
+      command: "bun test"
+    build-succeeds:
+      type: builtin
+      command: "bun run build"

package/src/templates/static-site.yaml

@@ -0,0 +1,45 @@
+pipeline:
+  id: static-site
+  version: 1
+  description: "Pipeline for static sites and portfolios"
+  initial: quality
+  stages:
+    quality:
+      gates:
+        exit: [lint-pass, typecheck-pass, build-succeeds]
+      on:
+        STAGE_COMPLETE: { target: visual }
+    visual:
+      description: "Visual and accessibility checks"
+      on:
+        STAGE_COMPLETE: { target: deploy }
+        ANY_FAILED: { target: fix }
+    fix:
+      max_retries: 2
+      on:
+        FIX_COMPLETE: { target: quality }
+    deploy:
+      type: terminal
+
+  gates:
+    lint-pass:
+      type: builtin
+      command: "bun run lint"
+    typecheck-pass:
+      type: builtin
+      command: "bun run typecheck"
+    build-succeeds:
+      type: builtin
+      command: "bun run build"
+    a11y-audit:
+      type: custom
+      script: "bun run a11y"
+      expect: { status: pass }
+    lighthouse-pass:
+      type: custom
+      script: "bun run lighthouse"
+      expect: { status: pass }
+    responsive-check:
+      type: custom
+      script: "bun run responsive"
+      expect: { status: pass }

package/src/templates/zship.yaml

@@ -0,0 +1,224 @@
+# zship.yaml — Dual-Model Development Pipeline
+# 6-stage pipeline with dual-phase gates (Claude + Codex)
+# Converts the zship process into Pipeline SDK format
+
+pipeline:
+  id: zship
+  version: 1
+  description: "Dual-model autonomous development pipeline (BRAINSTORM → PLAN → IMPLEMENT → TEST → REVIEW → SHIP)"
+  initial: brainstorm
+
+  stages:
+    brainstorm:
+      description: "Interrogate requirements via grill-me interrogation"
+      agent:
+        instructions: "Interrogate requirements relentlessly. Produce approved spec at docs/zship/spec.md."
+        tools: [Read, Grep, Glob, Write, WebSearch]
+      on:
+        SPEC_APPROVED: { target: plan }
+        ABORT: { target: aborted }
+
+    plan:
+      description: "Create TDD implementation plan with task breakdown"
+      agent:
+        instructions: "Produce TDD plan from spec. Each task: RED test → GREEN implement → REFACTOR."
+        tools: [Read, Grep, Glob, Write]
+      gates:
+        exit: [plan-document-exists]
+      on:
+        STAGE_COMPLETE: { target: implement }
+        SPEC_CHANGES: { target: brainstorm }
+
+    implement:
+      description: "Ralph Loop: TDD cycles per task with Gate 1 (test quality) and Gate 2 (impl review)"
+      agent:
+        instructions: "Execute TDD plan. RED → GREEN → Gate 1 review → REFACTOR. After all tasks: Gate 2 full review."
+        tools: [Read, Write, Edit, Bash, Grep, Glob]
+      gates:
+        exit: [lint-pass, typecheck-pass, tests-pass, tdd-quality-review, impl-review]
+      max_retries: 6
+      on:
+        STAGE_COMPLETE: { target: test }
+        TESTS_FAIL: { target: fix-implement }
+        GATE_FAIL: { target: fix-implement }
+
+    fix-implement:
+      description: "Fix test quality or implementation issues from Gates 1-2"
+      max_retries: 3
+      agent:
+        instructions: "Fix gate findings. Do not change test expectations unless finding specifically requires it."
+        tools: [Read, Edit, Bash, Grep]
+      on:
+        FIX_COMPLETE: { target: implement }
+        MAX_RETRIES: { target: escalate-implement }
+
+    test:
+      description: "E2E testing + smoke testing with Gate 3 (coverage) and Gate 4 (smoke gaps)"
+      agent:
+        instructions: "Create E2E tests covering spec requirements. Run smoke tests. Gates review coverage and gaps."
+        tools: [Read, Write, Edit, Bash, Grep, Glob]
+      gates:
+        exit: [e2e-tests-pass, coverage-review, smoke-gap-review]
+      max_retries: 6
+      on:
+        STAGE_COMPLETE: { target: review }
+        GATE_FAIL: { target: fix-test }
+        IMPLEMENT_CHANGES: { target: implement }
+
+    fix-test:
+      description: "Fix test coverage gaps or smoke testing issues from Gates 3-4"
+      max_retries: 3
+      agent:
+        instructions: "Fix coverage gaps and smoke test findings."
+        tools: [Read, Edit, Bash, Grep]
+      on:
+        FIX_COMPLETE: { target: test }
+        MAX_RETRIES: { target: escalate-test }
+
+    review:
+      description: "Gate 5: Adversarial code review (dual-phase Claude + Codex)"
+      agent:
+        instructions: "Process adversarial findings. Fix security, concurrency, performance issues."
+        tools: [Read, Edit, Bash, Grep]
+      gates:
+        exit: [adversarial-review]
+      max_retries: 6
+      on:
+        STAGE_COMPLETE: { target: ship }
+        GATE_FAIL: { target: fix-review }
+        TEST_CHANGES: { target: test }
+
+    fix-review:
+      description: "Fix adversarial review findings from Gate 5"
+      max_retries: 3
+      agent:
+        instructions: "Fix adversarial findings. Verify fixes via tests. Do not introduce regressions."
+        tools: [Read, Edit, Bash, Grep]
+      on:
+        FIX_COMPLETE: { target: review }
+        MAX_RETRIES: { target: escalate-review }
+
+    ship:
+      description: "Gate 6: Final quality gate then PR creation"
+      agent:
+        instructions: "Final quality check. If passes, create PR with full context and evidence links."
+        tools: [Read, Edit, Bash, Grep]
+      gates:
+        exit: [final-quality-gate]
+      on:
+        STAGE_COMPLETE: { target: complete }
+        GATE_FAIL: { target: fix-ship }
+        REVIEW_CHANGES: { target: review }
+
+    fix-ship:
+      description: "Fix regressions or unresolved issues from Gate 6"
+      max_retries: 3
+      agent:
+        instructions: "Fix final gate findings. This is the last chance before shipping."
+        tools: [Read, Edit, Bash, Grep]
+      on:
+        FIX_COMPLETE: { target: ship }
+        MAX_RETRIES: { target: escalate-ship }
+
+    complete:
+      type: terminal
+      description: "Pipeline succeeded — PR created and ready for human merge"
+
+    aborted:
+      type: terminal
+      description: "Pipeline aborted by user"
+
+    escalate-implement:
+      type: terminal
+      description: "Implementation gates failed after max retries"
+      on_enter:
+        - script: "./tools/pipeline/notify-escalation.sh"
+        - script: "./tools/pipeline/create-escalation-issue.sh"
+
+    escalate-test:
+      type: terminal
+      description: "Testing gates failed after max retries"
+      on_enter:
+        - script: "./tools/pipeline/notify-escalation.sh"
+        - script: "./tools/pipeline/create-escalation-issue.sh"
+
+    escalate-review:
+      type: terminal
+      description: "Review gate failed after max retries"
+      on_enter:
+        - script: "./tools/pipeline/notify-escalation.sh"
+        - script: "./tools/pipeline/create-escalation-issue.sh"
+
+    escalate-ship:
+      type: terminal
+      description: "Final gate failed after max retries"
+      on_enter:
+        - script: "./tools/pipeline/notify-escalation.sh"
+        - script: "./tools/pipeline/create-escalation-issue.sh"
+
+  gates:
+    plan-document-exists:
+      type: custom
+      script: "test -f docs/zship/spec.md"
+      expect: { status: pass }
+    lint-pass:
+      type: builtin
+      command: "bun run lint"
+    typecheck-pass:
+      type: builtin
+      command: "bun run typecheck"
+    tests-pass:
+      type: builtin
+      command: "bun test"
+    e2e-tests-pass:
+      type: builtin
+      command: "bun run test:e2e"
+
+    tdd-quality-review:
+      type: custom
+      script: "./tools/gates/tdd-quality-review.sh"
+      protocol: json-stdout
+      inputs:
+        mode: dual-phase
+        phase_a: claude
+        phase_b: codex
+
+    impl-review:
+      type: custom
+      script: "./tools/gates/impl-review.sh"
+      protocol: json-stdout
+      inputs:
+        mode: dual-phase
+        focus: architecture
+
+    coverage-review:
+      type: custom
+      script: "./tools/gates/coverage-review.sh"
+      protocol: json-stdout
+      inputs:
+        mode: dual-phase
+        focus: test_coverage
+
+    smoke-gap-review:
+      type: custom
+      script: "./tools/gates/smoke-gap-review.sh"
+      protocol: json-stdout
+      inputs:
+        mode: dual-phase
+        focus: smoke_analysis
+
+    adversarial-review:
+      type: custom
+      script: "./tools/gates/adversarial-review.sh"
+      protocol: json-stdout
+      inputs:
+        mode: dual-phase
+        focus: adversarial
+
+    final-quality-gate:
+      type: custom
+      script: "./tools/gates/final-quality-gate.sh"
+      protocol: json-stdout
+      inputs:
+        mode: dual-phase
+        focus: final_quality