@stackforgeai/copilot-pipeline

Stage-gated AI pipeline orchestration with multi-agent coordination, prompt contracts, cost-aware routing, and structured observability — all LLM calls guarded by @stackforgeai/copilot-guard.

Overview

@stackforgeai/copilot-pipeline is a production-grade orchestration framework designed to build reliable, auditable, and cost-controlled AI pipelines and multi-agent systems.

This project addresses key challenges in modern AI workflows:

• Spec-driven pipelines: 4-block prompt contracts with human approval gates, retry logic, and stage chaining
• Multi-agent coordination: Dependency-aware task scheduling with parallel execution up to a configurable concurrency limit
• Cost-aware routing: Complexity-based model selection with budget constraints (low/medium/high → free/standard/premium models)
• Prompt quality: "Grill me" alignment step that surfaces clarifying questions before generation
• Observability: Span-based tracing with events, status tracking, and JSON export for any observability backend
• Token safety: All calls flow through @stackforgeai/copilot-guard for enforced budget limits

Backed by AI industry trends (week17 analysis: agent orchestration, spec-driven development, observability, token economics, prompt engineering).

Features

• 4-Block Prompt Contracts: Structured template format (Instructions, Context, Task, Output) with variable interpolation and validation
• "Grill Me" Alignment: Send a contract to the model first; receive clarifying questions before the main generation starts
• Stage-Gated Pipelines: Execute multiple stages in sequence; each stage's output becomes the next stage's input context
• Human Approval Gates: Mark stages as requiresApproval=true to require human sign-off before execution
• Cost Router: Route tasks to models based on complexity, respecting a maximum cost multiplier budget
• Multi-Agent Orchestration: Coordinate multiple agents with dependency graphs; run independent tasks in parallel
• Meta-Agent Planning: Use an agent to generate an execution plan before running the full task fleet
• Structured Observability: Span-based tracing with events, status tracking, duration metrics, and JSON export
• Integrated Token Guard: All Copilot calls are routed through the injected IGuard for token budget enforcement
• Retry Logic: Configurable retry attempts per stage with exponential backoff
• Full TypeScript Support: Strict types for all APIs and configurations

Installation

npm install @stackforgeai/copilot-pipeline @stackforgeai/copilot-guard @github/copilot-sdk

Requirements:

• Node.js >=20
• @stackforgeai/copilot-guard — peer dependency for token budget enforcement
• @github/copilot-sdk — peer dependency (the underlying LLM client)

Quick Start

Example 1: Basic 3-Stage Pipeline

import { Pipeline } from "@stackforgeai/copilot-pipeline";

const pipeline = new Pipeline({
  name: "spec-driven-design",
  stages: [
    {
      name: "requirements",
      model: "gpt-4o-mini",
      contract: {
        instructions: "You are a requirements analyst.",
        context: "Product: {{input}}",
        task: "Extract the top 5 functional requirements.",
        output: "Return a numbered list. Each requirement starts with 'The system shall'."
      }
    },
    {
      name: "design",
      model: "gpt-4o-mini",
      contract: {
        instructions: "You are a domain-driven design expert.",
        context: "Requirements: {{input}}",
        task: "Design the domain model from these requirements.",
        output: "Return entities, attributes, and relationships in plain text."
      },
      requiresApproval: true // Gate: human reviews before design
    }
  ],
  premiumLimit: 5_000,
  approvalHandler: async (stageName, contract, input) => {
    // In production: call a real approval UI
    console.log(`Reviewing stage: ${stageName}`);
    return true; // Auto-approve for this example
  },
  onStageComplete: (result) => {
    console.log(`✓ ${result.stageName} — ${result.status}`);
  }
});

const result = await pipeline.run("A real-time logistics tracking platform");
console.log("Pipeline result:", result);

Example 2: Multi-Agent Coordination

import { AgentCoordinator } from "@stackforgeai/copilot-pipeline";

const coordinator = new AgentCoordinator({
  metaModel: "gpt-4o-mini",
  taskModel: "gpt-4o-mini",
  premiumLimit: 10_000,
  maxConcurrency: 2
});

// Market analyst and security analyst run in parallel (no dependencies)
// Tech researcher depends on market analyst
// Report writer depends on all three
const result = await coordinator.orchestrate("Produce an AI industry report", [
  {
    id: "market",
    agentName: "Market Analyst",
    prompt: "Analyze the AI developer tooling market. Top 3 trends and key players."
  },
  {
    id: "security",
    agentName: "Security Analyst",
    prompt: "Top 5 security risks for AI agent pipelines in 2026."
  },
  {
    id: "tech",
    agentName: "Tech Researcher",
    prompt: "Research MCP adoption patterns.",
    dependencies: ["market"] // Waits for market analyst
  },
  {
    id: "report",
    agentName: "Report Writer",
    prompt: "Synthesize all findings into an executive summary.",
    dependencies: ["market", "security", "tech"] // Waits for all three
  }
]);

console.log("Plan:", result.plan);
console.log("Results:", result.results);

Example 3: Cost-Aware Model Routing

import { CostRouter, PromptContract } from "@stackforgeai/copilot-pipeline";

// Define available model tiers (cheapest to most expensive)
const router = new CostRouter({
  tiers: [
    { model: "gpt-4o-mini", multiplier: 0.5 },
    { model: "gpt-4o", multiplier: 1.0 },
    { model: "claude-3.5-sonnet", multiplier: 1.5 },
    { model: "gpt-4.1", multiplier: 2.0 }
  ],
  maxMultiplier: 1.5 // Stay within 1.5× cost — exclude full premium models
});

// Route based on task complexity
const lowDecision = router.route("low");    // → gpt-4o-mini
const mediumDecision = router.route("medium"); // → gpt-4o
const highDecision = router.route("high");   // → claude-3.5-sonnet

console.log(`High complexity routed to: ${highDecision.model}`);
console.log(`Reason: ${highDecision.reason}`);

Example 4: Prompt Contract with "Grill Me"

import { PromptContract } from "@stackforgeai/copilot-pipeline";
import { CopilotGuard } from "@stackforgeai/copilot-guard";

const contract = new PromptContract({
  instructions: "You are a data engineer.",
  context: "Client: {{industry}}, Events/sec: {{eventsPerSecond}}, Budget: {{budget}}/month",
  task: "Design a scalable streaming architecture.",
  output: "Architecture document: Overview, Components, Data Flow, Cost Estimate, Risks."
});

// Validate before sending
const validation = contract.validate();
if (!validation.valid) {
  console.error("Contract issues:", validation.warnings);
}

// "Grill me" step: ask the model for clarifying questions before generation
const guard = new CopilotGuard({ premiumLimit: 2_000 });
const questions = await contract.grillMe(guard, "gpt-4o-mini");
console.log("Clarifying questions:", questions);
// Output: ["What is the expected scale?", "What auth strategy?", ...]

// Once questions are answered, render and send the final prompt
const prompt = contract.render({
  industry: "fintech",
  eventsPerSecond: "50 000",
  budget: "$5 000"
});

API Reference

PromptContract

4-block prompt template with variable interpolation, validation, and "grill me" alignment.

const contract = new PromptContract(block, defaults?);

// Methods:
contract.render(vars?)           // → rendered prompt string
contract.validate(vars?)         // → { valid, warnings, totalChars, estimatedTokens }
contract.getBlock()              // → readonly contract definition
await contract.grillMe(guard, model) // → string[] of clarifying questions

CostRouter

Route tasks to models based on complexity and cost budget.

const router = new CostRouter({ tiers, maxMultiplier?, fallbackModel? });

// Methods:
router.route(complexity)         // → { model, multiplier, reason }
router.isAffordable(model)       // → boolean
router.getTiers()                // → ModelTier[]
router.getMaxMultiplier()        // → number

Pipeline

Stage-gated, spec-driven pipeline execution.

const pipeline = new Pipeline(config, guard?);

// Methods:
await pipeline.run(initialInput) // → PipelineResult
pipeline.getObserver()           // → PipelineObserver
pipeline.getGuardUsage()         // → { premiumTokensUsed, premiumLimit, remaining }

Config fields:

• name — human-readable pipeline name
• stages — array of StageConfig
• premiumLimit — token budget (default: 50_000)
• approvalHandler? — async function to approve stages marked requiresApproval
• onStageComplete? — callback after each stage

AgentCoordinator

Multi-agent coordination with dependency-aware scheduling.

const coordinator = new AgentCoordinator(config, guard?);

// Methods:
await coordinator.coordinate(tasks)           // → AgentResult[]
await coordinator.orchestrate(goal, tasks)    // → { plan, results }
coordinator.getGuardUsage()                   // → { premiumTokensUsed, ... }

Config fields:

• metaModel — model for the planning step in orchestrate()
• taskModel? — default model for task agents
• premiumLimit — token budget (default: 50_000)
• maxConcurrency — max parallel tasks (default: 3)

PipelineObserver

Structured observability with span-based tracing.

const observer = new PipelineObserver();

// Methods:
observer.startSpan(name, attributes?)  // → spanId
observer.endSpan(spanId, status?, attrs?)
observer.addEvent(spanId, message)
observer.getSpans()                    // → Span[]
observer.getSummary()                  // → ObservabilitySummary
observer.export()                      // → JSON string
observer.reset()

Use Cases

• Spec-driven API design: Requirements → Domain model → REST endpoints (with approval gates)
• Multi-agent research: Market analyst + security analyst + tech researcher → synthesis
• Cost-optimized AI workflows: Complex tasks route to premium models; simple tasks use cheaper models
• Agentic enterprise platforms: Orchestrate hundreds of specialized agents with governance
• Prompt engineering pipelines: Multi-turn refinement with human feedback at each stage
• AI-powered documentation generation: Input → outline → detailed sections → final polish
• LLM-based data processing: Extract → validate → enrich → export (with observability)

Architecture & Design

Why Spec-Driven?

The 4-block contract forces clarity before generation:

1. Instructions — who is the model (persona)?
2. Context — what is the background and grounding data?
3. Task — what exactly are we asking for?
4. Output — what format do we expect?

This structure aligns with industry best practices (week17 Trend 4: spec-driven development) and reduces hallucinations by making implicit assumptions explicit.

Why "Grill Me"?

Before the main generation, a lightweight model asks clarifying questions. This surfaces ambiguities early and prevents the model from inventing unspecified constraints (scale, technology, output format, etc.). Answers are then injected into the contract context before the main call.

Why Multi-Agent Orchestration?

Large fleets of AI agents (week17 Trend 1) require:

• Dependency graphs: Tasks can depend on other tasks; independent tasks run in parallel
• Meta-planning: A coordinator agent first generates an execution plan before tasks run
• Observability: Track each agent's result, status, and duration
• Token budgeting: All agents share a single budget enforced by the guard

Why Observability?

Production AI systems (week17 Trend 3) must be:

• Auditable: Every span, event, and decision is recorded
• Exportable: JSON spans can be shipped to any observability backend (Datadog, Honeycomb, etc.)
• Cost-aware: Token usage is tracked per span and aggregated
• Traceable: Span IDs link parent and child operations

Intended Use Cases

• AI orchestration frameworks
• Multi-agent platforms
• Prompt engineering systems
• LLM-powered SaaS backends
• Agentic enterprises
• Enterprise automation workflows
• Batch AI processing
• Cost-optimized AI services
• Real-time reasoning pipelines

Goals

This project aims to help developers:

• Build reliable, auditable AI pipelines with human-in-the-loop approval gates
• Orchestrate fleets of specialized agents with dependency awareness
• Route AI calls to cost-optimal models based on task complexity
• Implement structured prompt engineering (4-block contracts) at scale
• Ship observability data to any backend
• Stay within token budgets across complex workflows
• Experiment safely with premium AI models

Non-Goals

This package does NOT guarantee:

• prevention of all billing overruns (implement provider-side rate limits as well)
• perfect token estimation (use actual API response tokens only)
• prevention of all logic errors
• loop detection or prevention
• fault tolerance beyond basic retry logic
• production-grade security certification
• 100% reliability

Developers remain fully responsible for validating behavior in their own environments.

Compatibility

This package works with:

• @github/copilot-sdk (required peer dependency)
• @stackforgeai/copilot-guard (required for token budget enforcement)
• Any observability backend that accepts JSON spans (Datadog, Honeycomb, custom logging, etc.)

Development Status

This project is production-ready but may receive breaking changes in minor versions during 2026 as AI industry practices evolve.

APIs and internal logic may be refined based on real-world usage and feedback.

DISCLAIMER AND LIMITATION OF LIABILITY

IMPORTANT: THIS SOFTWARE IS PROVIDED STRICTLY ON AN "AS IS" AND "AS AVAILABLE" BASIS.

BY USING THIS SOFTWARE, YOU ACKNOWLEDGE AND AGREE THAT:

• THE SOFTWARE MAY CONTAIN BUGS, DEFECTS, DESIGN FLAWS, LOGIC ERRORS, SECURITY ISSUES, OR INCOMPLETE FEATURES
• THE SOFTWARE MAY FAIL TO LIMIT OR PREVENT TOKEN USAGE, API REQUESTS, COST OVERRUNS, OR BILLING EVENTS
• PIPELINE EXECUTION, APPROVAL GATES, RETRY LOGIC, DEPENDENCY GRAPHS, AND SAFETY FEATURES MAY BE INACCURATE, INCOMPLETE, OR NON-FUNCTIONAL
• THE SOFTWARE MAY PRODUCE UNEXPECTED RESULTS
• THE SOFTWARE MAY NOT BE SUITABLE FOR PRODUCTION ENVIRONMENTS
• THE SOFTWARE MAY NOT PREVENT EXCESSIVE CHARGES FROM AI PROVIDERS OR CLOUD SERVICES
• HUMAN APPROVAL GATES MAY FAIL OR BE BYPASSED
• MULTI-AGENT COORDINATION MAY DEADLOCK, INFINITE LOOP, OR PRODUCE INCONSISTENT RESULTS

THIS SOFTWARE DOES NOT GUARANTEE:

• COST SAVINGS
• BILLING PROTECTION
• TOKEN ACCURACY
• FINANCIAL PROTECTION
• REQUEST SAFETY
• SYSTEM STABILITY
• SECURITY
• RELIABILITY
• FITNESS FOR ANY PARTICULAR PURPOSE
• CORRECT EXECUTION OF PIPELINES
• CORRECT DEPENDENCY RESOLUTION
• CORRECT MODEL ROUTING
• CORRECT OBSERVABILITY DATA

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW:

THE AUTHORS, CONTRIBUTORS, MAINTAINERS, COPYRIGHT HOLDERS, AFFILIATES, AND DISTRIBUTORS SHALL NOT BE LIABLE FOR ANY CLAIMS, DAMAGES, LOSSES, LIABILITIES, OR EXPENSES OF ANY KIND, INCLUDING BUT NOT LIMITED TO:

• API FEES
• TOKEN CHARGES
• CLOUD COMPUTE COSTS
• INFRASTRUCTURE COSTS
• FINANCIAL LOSSES
• LOST PROFITS
• BUSINESS INTERRUPTION
• SERVICE OUTAGES
• DATA LOSS
• DATA CORRUPTION
• SECURITY INCIDENTS
• INDIRECT DAMAGES
• INCIDENTAL DAMAGES
• CONSEQUENTIAL DAMAGES
• SPECIAL DAMAGES
• PUNITIVE DAMAGES
• MISUSE OF THE SOFTWARE
• FAILURE OF SAFETY FEATURES
• FAILURE OF TOKEN LIMITS
• FAILURE OF APPROVAL GATES
• FAILURE OF RETRY LOGIC
• FAILED REQUEST BLOCKING
• ERRORS IN COST ROUTING
• ERRORS IN PIPELINE EXECUTION
• AGENT COORDINATION FAILURES
• DEADLOCKS AND INFINITE LOOPS
• EXCESSIVE BILLING EVENTS
• PRODUCTION FAILURES

USE OF THIS SOFTWARE IS ENTIRELY AT YOUR OWN RISK.

YOU ARE SOLELY RESPONSIBLE FOR:

• VERIFYING ALL PIPELINE OUTPUTS
• MONITORING API USAGE
• MONITORING TOKEN CONSUMPTION
• MONITORING BILLING
• IMPLEMENTING ADDITIONAL SAFEGUARDS
• TESTING IN YOUR OWN ENVIRONMENT
• CONFIGURING APPROPRIATE TOKEN BUDGETS
• VALIDATING ALL EXECUTION LOGIC
• IMPLEMENTING REAL HUMAN APPROVAL WORKFLOWS (not just automated handlers)
• MAINTAINING BACKUPS AND RECOVERY PROCEDURES
• IMPLEMENTING INDEPENDENT PROVIDER-SIDE RATE LIMITS

THIS PROJECT SHOULD NOT BE USED AS THE SOLE OR PRIMARY MECHANISM FOR COST CONTROL, BILLING GOVERNANCE, SECURITY, APPROVAL WORKFLOWS, OR PRODUCTION SAFETY.

ALWAYS IMPLEMENT:

• Independent provider-side billing alerts and budget caps
• Real human approval workflows (not just code callbacks)
• Request rate limits and concurrency controls at the provider level
• Observability and alerting in production systems
• Backup and recovery procedures
• Monitoring dashboards
• Incident response plans

IF YOU DO NOT AGREE WITH THESE TERMS, DO NOT USE THIS SOFTWARE.

License

MIT License

Copyright (c) 2026 StackForgeAI

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

For full license text, see the LICENSE file.

See Also

• copilot-guard — token budget enforcement
• copilot-toolkit — general-purpose toolkit
• week17 trends — AI industry trends analysis

Thank you for using @stackforgeai/copilot-pipeline — built to help you orchestrate AI agents reliably, safely, and at scale.