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

---

Setup — Path A: New Project (Fastest) ⚡

Fastest of all: Install the junai — Agent Pipeline VS Code extension, open any project, run junai: Initialize Agent Pipeline from the command palette, and skip straight to step 3 below. No cloning, no PowerShell needed.

1. Click "Use this template" → "Create a new repository" on this page
2. Clone your new repo, open it in VS Code
3. 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
   

4. Reload VS Code — the 8 junai MCP tools appear in the Copilot Chat tools icon (⚙)
5. Edit .github/project-config.md — set your project name and stack
6. 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
7. Open Copilot Chat → select Orchestrator from the agent dropdown → describe what you want to build

VS Code note: Custom agents aren't invoked via @AgentName mentions in chat. Click the agent icon in Copilot Chat and select Orchestrator from the list to activate it.

---

Setup — Path B: Existing Project

1. Clone junai anywhere on your machine:

   git clone https://github.com/saajunaid/junai
   

2. Add to your PowerShell $PROFILE (once per machine):

   . 'C:\Path\To\junai\sync.ps1'
   

3. From your existing project root:

   junai-pull
   

   Deploys .github/ (agents, skills, prompts, instructions, diagrams, tools) into your project.
4. Create venv (same as Path A step 3), reload VS Code
5. Configure project-config.md and add your project context to copilot-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):

Pipeline stages

intent → prd → architect → plan → implement → tester → review → closed

Hotfix fast-track: intent → implement → tester → closed

---

Pipeline Modes

autopilot caveats:

1. If a blocking escalation occurs, the pipeline writes PIPELINE_HALT.md to your project root and fires a desktop notification — but only if you’re watching VS Code. Check the file after long runs.
2. Architecture decisions (adr_approved) are auto-approved: a poor architecture is silently accepted and built on. Use supervised or assisted for 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

---

MCP Tools (9 total)

Available via natural language in Copilot Chat — or directly in the tools panel:

---

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 and vscode.pat (Azure DevOps PAT) in the junai-vscode repo root to enable junai-push auto-publish. Both files are gitignored.

project-config.md, copilot-instructions.md, pipeline-state.json, and agent-docs/ are never synced — project-specific. The extension manages only a sentinel-delimited section in copilot-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.json with the uvx junai-mcp entry

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.junai on the VS Code Marketplace. One-click pool install, no sync.ps1 needed.
• MCP Server registry listing ✅ Shipped — junai-mcp 0.2.0 on PyPI; registered as io.github.saajunaid/junai-mcp on registry.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:

---

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

---

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'

project-config.md and copilot-instructions.md are intentionally never synced — they are project-specific. The extension manages only a <!-- junai:start --> … <!-- junai:end --> section in copilot-instructions.md.

---

What Stays in Your Project (Not in This Pool)

---

Built by Junaid — because copy-pasting agent prompts between projects was getting old.