junai Pipeline MCP
Agentic pipeline orchestration MCP server for AI-driven development workflows.
Ask AI about junai Pipeline MCP
Powered by Claude Β· Grounded in docs
I know everything about junai Pipeline MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
junai β Let AI Think. Let Code Route.
25 specialised AI agents. A 9-stage deterministic pipeline. Zero hallucinated routing.
"Trust the LLM to pick the right agent" β worked great, right up until it didn't.
junai is Un-AI routing with full AI power.
Your agents stay smart. Your pipeline stays predictable.
- No hallucinated routing β a Python state machine owns all transitions; git-blameable, auditable
- Deterministic gates β key decisions require explicit approval; the pipeline cannot guess past them
- Predictable output β 9 stages, 23 agents, 0 surprises
What It Is
junai is a portable agent framework for VS Code + GitHub Copilot. It gives you:
- 25 specialised agents β Architect, Implement, Tester, Code Reviewer, Debug, Security Analyst, Anchor, and more
- A deterministic pipeline β a Python state machine owns all routing logic; the LLM cannot hallucinate the wrong next step
- Three pipeline modes β supervised (you approve everything), assisted (agents route, you approve gates), and autopilot β οΈ (beta β agents route, smart gates, only intent requires approval)
- 121 reusable skills, 30 prompts, 24 instruction files β loaded dynamically by agents as needed
- Chat-first UX β init, reset, mode switch, gate approval all from the Copilot chat window
Prerequisites
| Requirement | Notes |
|---|---|
| VS Code | Any recent version |
| GitHub Copilot | Agent mode must be enabled in Copilot Chat settings |
| Python 3.11+ | Must be on PATH |
| Git | For pipeline commits |
| PowerShell 5.1+ | Windows built-in; required for sync.ps1 |
Setup β Path A: New Project (Fastest) β‘
Fastest of all: Install the junai β Agent Pipeline VS Code extension, open any project, run
junai: Initialize Agent Pipelinefrom the command palette, and skip straight to step 3 below. No cloning, no PowerShell needed.
- Click "Use this template" β "Create a new repository" on this page
- Clone your new repo, open it in VS Code
- One-time venv setup (30 seconds β we timed it):
python -m venv .venv .venv\Scripts\pip install -r .github/tools/mcp-server/requirements.txt -r .github/tools/pipeline-runner/requirements.txt - Reload VS Code β the 8 junai MCP tools appear in the Copilot Chat tools icon (β)
- Edit
.github/project-config.mdβ set your project name and stack - Edit
.github/copilot-instructions.mdβ the extension creates this with a managed section; add your architecture overview, DB names, and key file paths outside the<!-- junai:start -->markers - Open Copilot Chat β select Orchestrator from the agent dropdown β describe what you want to build
VS Code note: Custom agents aren't invoked via
@AgentNamementions in chat. Click the agent icon in Copilot Chat and select Orchestrator from the list to activate it.
Setup β Path B: Existing Project
- Clone junai anywhere on your machine:
git clone https://github.com/saajunaid/junai - Add to your PowerShell
$PROFILE(once per machine):. 'C:\Path\To\junai\sync.ps1' - From your existing project root:
Deploysjunai-pull.github/(agents, skills, prompts, instructions, diagrams, tools) into your project. - Create venv (same as Path A step 3), reload VS Code
- Configure
project-config.mdand add your project context tocopilot-instructions.md(outside the<!-- junai:start -->managed section), then open Copilot Chat β select Orchestrator from the agent dropdown
Your First Pipeline β Chat Commands
No terminal needed after setup. Everything runs from Copilot Chat (with Orchestrator selected):
| Say this | What happens |
|---|---|
| "Start a new pipeline for feature: dark mode" | pipeline_init creates state, Orchestrator classifies and routes |
| "Switch to assisted mode" | Agents route automatically, gates still require your approval |
| "Switch to autopilot mode" | Agents route + gates auto-satisfied (beta) |
| "Approve plan_approved" | Satisfies a gate β gates are never bypassed in any mode |
| "What stage are we at?" | Returns current stage, mode, blocked_by |
| "Reset pipeline for next feature: X" | Wipes state and starts fresh |
Pipeline stages
intent β prd β architect β plan β implement β tester β review β closed
Hotfix fast-track: intent β implement β tester β closed
Pipeline Modes
| Mode | Handoffs | Gates | Notes |
|---|---|---|---|
supervised (default) | You click every handoff button | You approve every gate | Maximum control |
assisted | Orchestrator routes automatically | You approve every gate | Recommended for most work |
autopilot | Orchestrator routes automatically | Only intent_approved requires your approval β all others auto-satisfied, with smart review gate | β οΈ Beta β not fully tested. Monitor PIPELINE_HALT.md for silent halts. |
autopilotcaveats:
- If a blocking escalation occurs, the pipeline writes
PIPELINE_HALT.mdto your project root and fires a desktop notification β but only if youβre watching VS Code. Check the file after long runs.- Architecture decisions (
adr_approved) are auto-approved: a poor architecture is silently accepted and built on. Usesupervisedorassistedfor complex or unfamiliar features.
Switch at any time in chat (Orchestrator selected): "Switch to assisted mode" / "Switch to autopilot mode" / "Switch to supervised mode"
Agents at a Glance
| Layer | Agents |
|---|---|
| Deep Reasoning | Architect, Plan, Debug, Security Analyst |
| Structured Thinking | PRD, Code Reviewer, Data Engineer, Tester, SQL Expert, UI/UX Designer, UX Designer, Prompt Engineer, Accessibility, Mentor |
| Execution | Implement, Streamlit Developer, Frontend Developer, DevOps, Janitor |
| Specialist | Mermaid Diagram, SVG Diagram, Project Manager |
MCP Tools (9 total)
Available via natural language in Copilot Chat β or directly in the tools panel:
| Tool | Purpose |
|---|---|
pipeline_init | Start a new pipeline (confirm=true required) |
pipeline_reset | Reset for next feature (confirm=true required) |
set_pipeline_mode | Switch between supervised / assisted / autopilot |
satisfy_gate | Approve a supervision gate |
skip_stage | Skip the current stage with auto-gate satisfaction (blocked on implement, anchor, tester) |
get_pipeline_status | Current stage, mode, blocked_by, next transition, and formatted progress_line |
notify_orchestrator | Record stage completion + compute next transition |
validate_deferred_paths | Verify deferred item file paths before pipeline close |
run_command | Execute any shell command (tests, lint, format) β enables hands-free test runs |
Keeping Your Pool Updated
junai-pull # pull latest agents/skills/prompts β your project
junai-push # push improvements from your project β junai pool (+ auto-publishes if keys exist)
junai-release # publish MCP to PyPI + extension to VS Code marketplace
junai-export # bundle to folder or .zip (offline/air-gapped)
junai-import <path> # restore from export bundle
Store
pypimcp.key(PyPI token) in the junai repo root andvscode.pat(Azure DevOps PAT) in the junai-vscode repo root to enablejunai-pushauto-publish. Both files are gitignored.
project-config.md,copilot-instructions.md,pipeline-state.json, andagent-docs/are never synced β project-specific. The extension manages only a sentinel-delimited section incopilot-instructions.md; your content is never touched.
Pipeline CLI (terminal / scripting)
python .github/tools/pipeline-runner/pipeline_runner.py status
python .github/tools/pipeline-runner/pipeline_runner.py init --project <name> --feature <slug> --type feature|hotfix --force
python .github/tools/pipeline-runner/pipeline_runner.py mode --value supervised|assisted|autopilot
python .github/tools/pipeline-runner/pipeline_runner.py gate --name <gate_name>
python .github/tools/pipeline-runner/pipeline_runner.py next
python .github/tools/pipeline-runner/pipeline_runner.py transitions
See .github/pipeline/cheatsheet.md for the full reference.
Extending the Pipeline With Your Own Agents
The pipeline is plug-and-play β no Python changes, no restarts. There are two kinds of extension:
Pipeline-integrated agent (routed by the Orchestrator)
Your agent becomes a first-class pipeline citizen: the state machine routes to it, tracks its completion, and advances to the next stage automatically.
3 steps:
1. Add a stages entry in agents.registry.json
"my_stage": {
"agent": "my-agent",
"agent_file": ".github/agents/my-agent.agent.md",
"description": "Does the thing",
"required_artefacts": ["agent-docs/my-stage/"],
"completion_event": "my_stage_complete"
}
2. Add transitions entries pointing to/from your stage
{ "id": "T-28", "from": "plan", "to": "my_stage", "event": "plan_approved", "guard": null },
{ "id": "T-29", "from": "my_stage", "to": "implement", "event": "my_stage_complete", "guard": null }
3. Write your .agent.md with the Β§8 Completion Reporting Protocol
Every pipeline-integrated agent must end its work by calling notify_orchestrator and then HARD STOP β this is how the state machine knows the stage is done.
Copy the Β§8 block from any existing agent (e.g., .github/agents/implement.agent.md) and adapt the stage_completed and artefact_path values. The critical lines:
notify_orchestrator(stage_completed="my_stage", result_status="success", artefact_path="agent-docs/my-stage/")
HARD STOP β do not continue after calling notify_orchestrator.
That's it. Run pipeline transitions to verify your new T-28 and T-29 appear correctly.
Ad-hoc agent (called by you, not the Orchestrator)
No registry. No transitions. Just create a .github/agents/my-agent.agent.md and call it directly by selecting it from the agent dropdown in Copilot Chat.
Use this for specialist work that doesn't belong in the main pipeline sequence β a SQL Expert you call on demand, a diagram generator, a one-off security scan. The Β§8 protocol is optional for ad-hoc agents (but worth including if you ever want to pipeline-promote the agent later).
Distribution
Three ways to get junai β pick the one that fits your workflow:
Option 1 β VS Code Extension (zero setup) β‘
Install junai β Agent Pipeline from the VS Code Marketplace, then run junai: Initialize Agent Pipeline from the command palette.
That's it. The extension:
- Deploys all 1322 pool files (
.github/agents/,.github/skills/,.github/tools/, etc.) into your workspace - Scaffolds
pipeline-state.json - Automatically writes
.vscode/mcp.jsonwith theuvx junai-mcpentry
VS Code will prompt to start the MCP server β accept it, and the 8 pipeline tools appear in the Copilot Chat tools panel (β) immediately. No terminal, no venv, no manual config required. Requires uv on your PATH (winget install astral-sh.uv / brew install uv / pip install uv).
Option 2 β Manual MCP config (if you already have pool files)
If you deployed pool files via junai-pull or the GitHub template, add this to .vscode/mcp.json manually:
{
"servers": {
"junai": {
"type": "stdio",
"command": "uvx",
"args": ["junai-mcp"]
}
}
}
PyPI package:
junai-mcpΒ· MCP Registry:io.github.saajunaid/junai-mcp
Option 3 β Local venv (no uv, air-gapped, or offline)
After deploying pool files, create a venv and point .vscode/mcp.json at the local server:
python -m venv .venv
.venv\Scripts\pip install -r .github/tools/mcp-server/requirements.txt -r .github/tools/pipeline-runner/requirements.txt
{
"servers": {
"junai": {
"type": "stdio",
"command": "${workspaceFolder}\\.venv\\Scripts\\python",
"args": ["${workspaceFolder}\\.github\\tools\\mcp-server\\server.py"]
}
}
}
What's Coming
junai is a living project. Things on the near-term roadmap:
VS Code Extensionβ Shipped βjunai-labs.junaion the VS Code Marketplace. One-click pool install, nosync.ps1needed.MCP Server registry listingβ Shipped βjunai-mcp 0.2.0on PyPI; registered asio.github.saajunaid/junai-mcponregistry.modelcontextprotocol.io.skip_stage MCP toolβ Shipped β skip any non-critical stage with auto-gate satisfaction and safety guards.Anchor agent + adversarial review skillβ Shipped β 3-lens adversarial review (correctness, security, performance) with confidence scoring.Cross-artifact drift protectionβ Shipped β scope change declarations in Plan/Architect, handoff reconciliation in Implement/Anchor.- IDE agnostic β
.github/is universal; Cursor, JetBrains, and CLI support planned - And more β autopilot mode hardening, a proper user guide, and potentially a self-contained binary for the pipeline runner
Credits & Inspiration
junai's agents, skills, prompts, and instruction files were built from scratch, battle-tested, and adapted over months. The following open resources were genuinely useful along the way β if junai helps you, these deserve credit too:
| Resource | What we took from it |
|---|---|
| github/awesome-copilot | Copilot instruction patterns and .github/copilot-instructions.md conventions |
| anthropics/skills | Claude-style skill composition and context injection patterns |
| VoltAgent/awesome-agent-skills | Agent skill structure and capability registry approach |
| affaan-m/everything-claude-code | Comprehensive agent patterns and tool-use examples |
The Origin Story
This wasn't built in a weekend.
Months of trial and error, dead-end architectures, broken routing logic, and a painful number of "why did it just skip straight to implement?!" moments went into making junai feel boring and predictable β which is exactly the point. Every design decision you see here (deterministic state machine, confirm=True safeguards, gate-first approvals, pool-based portability) came from real pain building real projects.
If you find it useful, give it a star. If you find a bug, open an issue. If you build something with it, we'd genuinely love to hear about it.
What's Inside
.github/
βββ agents/ 23 specialised AI agents (Architect, Implement, Debug, etc.)
βββ skills/ 70+ reusable skills (coding, data, frontend, workflow, devops)
βββ prompts/ 30 prompt templates (advisory-hub, plan, code-review, etc.)
βββ instructions/ 23 instruction files (python, fastapi, streamlit, security, etc.)
βββ diagrams/ Agent workflow reference cards and design docs
βββ tools/
β βββ mcp-server/ 8 MCP tools (pipeline_init, pipeline_reset, status, etc.)
β βββ pipeline-runner/ Python state machine β the deterministic routing engine
βββ project-config.md β The only file you edit per project
License
MIT β free to use, fork, and adapt. See LICENSE for the full text.
If you build something cool on top of junai, attribution is appreciated but not required. A shoutout would make our day though.
Agents read project-config.md for brand/stack config and copilot-instructions.md for project architecture context. The extension manages a small sentinel block in copilot-instructions.md β your content outside the <!-- junai:start --> / <!-- junai:end --> markers is never modified.
Agent Overview
| Layer | Agents | Model |
|---|---|---|
| Deep Reasoning | Architect, Security Analyst, Plan, Debug | Claude Opus 4.6 |
| Structured Thinking | PRD, Code Reviewer, Data Engineer, Tester, SQL Expert, UI/UX Designer, UX Designer, Prompt Engineer, Accessibility, Mentor, Mermaid, SVG | Claude Sonnet 4.6 |
| Orchestration | Orchestrator, Anchor | Claude Sonnet 4.6 |
| Execution | Implement, Streamlit Developer, Frontend Developer, DevOps, Janitor | Claude Sonnet 4.6 |
Pipeline Methodology
JUNAI uses a deterministic 9-stage pipeline with a state machine runner:
intent β prd β architect β plan β implement β tester β review β deploy β closed
Hotfix fast-track: intent β implement β tester β closed
junai CLI (agent-sandbox projects)
junai pipeline status # current stage, mode, blocked_by
junai pipeline next # dry-run: what would advance?
junai pipeline advance --event <stage>_complete
junai pipeline mode --value supervised|assisted|autopilot # supervised=gated, assisted=auto-route+gates, autopilot=fully autonomous
junai pipeline gate --name <gate_name> # satisfy a supervision gate
junai agent list # compliance table for all agents
junai agent make --name <xyz> [--role executing|advisory]
junai agent validate --name <xyz>
junai agent onboard --name <xyz> [--yes]
See .github/pipeline/cheatsheet.md for the full reference.
For the Advisory Hub flow (non-pipeline projects), load .github/skills/workflow/agent-orchestration/SKILL.md and start with .github/prompts/advisory-hub.prompt.md.
Syncing Updates
All sync operations are handled by sync.ps1. Dot-source it once in your $PROFILE:
. 'E:\Projects\junai\sync.ps1'
| Command | What it does |
|---|---|
junai-pull | Pool β project: copies agents, skills, prompts, instructions, diagrams into .github/ |
junai-push | Project β pool: commits improvements from a project back into this repo; auto-publishes MCP + extension when key files are present |
junai-release | Publish junai-mcp to PyPI and the VS Code extension to the marketplace in one command |
junai-export | Creates a self-contained folder or .zip for offline/air-gapped machines |
junai-import | Restores a pool from an export folder or zip on a machine without GitHub access |
project-config.mdandcopilot-instructions.mdare intentionally never synced β they are project-specific. The extension manages only a<!-- junai:start -->β¦<!-- junai:end -->section incopilot-instructions.md.
What Stays in Your Project (Not in This Pool)
| File/Folder | Why It Stays |
|---|---|
.github/copilot-instructions.md | Project architecture, DB names, stack details (extension manages only sentinel section) |
.github/project-config.md | Your filled-in profile and project values |
.github/plans/ | Phased execution plans for active features |
.github/handoffs/ | Emergency context handoffs |
.github/agent-docs/ | PRDs, architecture docs, artefact manifests |
Built by Junaid β because copy-pasting agent prompts between projects was getting old.
