claudster

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 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):

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