feat(kickstart): split agent into 4 phase-aligned sub-agents by bosesuneha · Pull Request #2189 · Azure/vscode-aks-tools

bosesuneha · 2026-06-03T06:25:23Z

Summary

Splits the monolithic kickstart agent (~1200 lines, prone to losing context mid-flow) into four phase-aligned sub-agents that hand off to each other through a shared state file.

Topology

kickstart (Phase 1-2: Discover, Configure)
   └─► kickstart-builder (Phase 3-4: Design, Generate)
          └─► kickstart-reviewer (Phase 5: Review)
                 └─► kickstart-deployer (Phase 6-7: Pre-Deploy, Deploy)

Sub-agents are hidden from the agent picker (user-invocable: false) and reached only via handoff. All handoffs are send: false so the user confirms before each transition.

Design properties

Tool surface minimized per role
- kickstart-builder writes deployment artifacts but cannot touch the live cluster
- kickstart-reviewer is read-only (no editFiles, no destructive az/kubectl)
- kickstart-deployer has destructive runtime tools but cannot write artifacts
- kickstart keeps both for early-phase work and serves as the escalation fallback
Shared state contract: every agent reads .kickstart/state.json on entry and writes on exit (new skills/kickstart-state/SKILL.md defines the schema, jq read/write helpers, and ownership table)
State file location: workspace-relative .kickstart/state.json, auto-appended to .gitignore

Files

New

agents/kickstart-builder.agent.md — Phases 3-4
agents/kickstart-deployer.agent.md — Phases 6-7 (the only destructive runtime agent)
skills/kickstart-state/SKILL.md — shared state schema + helpers

Modified

agents/kickstart.agent.md — slimmed to orchestrator owning Phases 1-2
agents/kickstart-reviewer.agent.md — handoff wiring updates
package.json — register the two new agents and the state skill
AGENTS.md, kickstart-guide.md — topology rewrites

Testing

Declarative-only change. Validated:

package.json parses
All four agent frontmatter blocks parse and reference existing skills (modulo the known missing ones tracked for Track A)
husky/lint-staged passed on commit

Splits the monolithic kickstart agent (Discover→Deploy) into four sub-agents owning distinct phases: kickstart — Welcome, Discover, Configure (orchestrator) kickstart-builder — Design, Generate kickstart-reviewer — Review kickstart-deployer — Pre-Deploy, Deploy Sub-agents are hidden from the agent picker (user-invocable: false) and reached via send:false handoffs so every transition is a user-confirmed checkpoint. Shared state lives in <workspace>/.kickstart/state.json, schema in skills/kickstart-state. Tool surface minimised per agent: only builder writes files; only deployer touches live cluster/registry.

Removes the `model: ['Claude Sonnet 4', 'GPT-4o']` line from kickstart, kickstart-builder, and kickstart-deployer (and the matching Models row in AGENTS.md). Agents now inherit whatever model the user has selected in the Copilot Chat picker, matching kickstart-reviewer and avoiding stale model pinning as new models ship.

Copilot

Pull request overview

This PR refactors the Kickstart Copilot experience by splitting the previously monolithic kickstart agent into four phase-aligned sub-agents, with cross-handoff continuity provided via a shared workspace state file (.kickstart/state.json) and a new state-contract skill.

Changes:

Added a new shared skill (kickstart-state) defining the .kickstart/state.json schema plus read/write helpers.
Introduced two new internal sub-agents (kickstart-builder, kickstart-deployer) and rewired handoffs so phases are owned by specialized agents.
Updated package.json contributions and refreshed docs (AGENTS.md, kickstart-guide.md) to reflect the new topology.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
`skills/kickstart-state/SKILL.md`	New shared state contract and jq-based merge helpers for cross-agent handoffs.
`package.json`	Registers the new agents and the new `kickstart-state` skill.
`kickstart-guide.md`	Updates the guide to describe the new 4-agent topology and shared state.
`agents/kickstart.agent.md`	Slims the orchestrator to phases 1–2 and adds handoffs to builder/reviewer/deployer.
`agents/kickstart-builder.agent.md`	New agent for phases 3–4 (design/generate) and forward handoff to reviewer.
`agents/kickstart-reviewer.agent.md`	Updates reviewer wiring to hand off forward/back based on review outcome.
`agents/kickstart-deployer.agent.md`	New agent for phases 6–7 (pre-deploy/deploy) with destructive runtime tools.
`AGENTS.md`	Documents the new agent topology and ownership model.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+For nested updates, pass an object that mirrors the schema:
+
+```bash
+jq '. * {
+  app: { name: "myapp", language: "python", port: 8000 },
+  phase: "configure",
+  lastAgent: "kickstart",
+  updatedAt: "'"$(date -u +%FT%TZ)"'"
+}' .kickstart/state.json > "$tmp" && mv "$tmp" .kickstart/state.json
+```


+
+You are the **Builder** sub-agent. Your job is to take the app profile and Azure resource decisions made by `kickstart` and produce all deployment artifacts.
+
+You own **Phase 3 (Design)** and **Phase 4 (Generate)** only. You do not run `az`, `kubectl`, or any destructive command. You write files.


+
+## Phase 3 — Design
+
+Follow `/kickstart-design`. Present the target architecture summary using `app.*` and `azure.*` from state. Reference `/kickstart-aks-automatic`, `/kickstart-gateway-api`, `/kickstart-workload-identity`, `/kickstart-aks-terminology` as needed.


+
+## Phase 4 — Generate
+
+Follow `/kickstart-generate`. Also load `/kickstart-deployment-safeguards`, `/kickstart-acr-integration`, `/kickstart-bicep-authoring`, `/kickstart-github-actions-workflow`, `/kickstart-github-actions-oidc`, `/kickstart-file-generation`, and `/kickstart-kaito-gpu` if the workload is GPU.


+### 6d. kubelogin Check
+```bash
+which kubelogin || az aks install-cli
+```
+Set `cluster.kubeloginInstalled: true`.
+
+### 6e. Control-Plane Probe
+```bash
+az aks get-credentials --resource-group <rg> --name <cluster> --overwrite-existing
+kubectl auth can-i get namespaces
+```
+On failure → user needs **Azure Kubernetes Service Cluster User Role**. Halt and provide fix.
+Set `cluster.controlPlaneOk: true`.
+
+### 6f. Data-Plane RBAC Probes
+```bash
+kubectl auth can-i create deployments --namespace <namespace>
+kubectl auth can-i create services --namespace <namespace>
+kubectl auth can-i create configmaps --namespace <namespace>
+```
+Self-remediation branching per `/kickstart-handoff`. On 403, follow `/kickstart-pim-activation`. After admin assignment, poll every 15s up to 3 min.
+Set `cluster.dataPlaneOk: true`.
+


            {
                "name": "kickstart-reviewer",
-                "description": "Internal agent: Reviews Kickstart-generated deployment artifacts for correctness, security, and AKS Automatic compliance. Invoked by kickstart only.",
+                "description": "Internal agent: Reviews Kickstart-generated deployment artifacts for correctness, security, and AKS Automatic compliance. Invoked by kickstart-builder only.",


+            },
+            {
+                "name": "kickstart-deployer",
+                "description": "Internal agent: Runs pre-deploy permission and tooling checks then deploys to AKS. Invoked by kickstart-reviewer only.",


 ## Skill Taxonomy

-All 30 skills use `disable-model-invocation: true` — they only fire when explicitly invoked via `/skill-name` by an agent.
+All 31 skills use `disable-model-invocation: true` — they only fire when explicitly invoked via `/skill-name` by an agent.
+


+│   ├── kickstart-aks-automatic/SKILL.md  # Domain skills
 │   ├── kickstart-gateway-api/SKILL.md
 │   ├── kickstart-workload-identity/SKILL.md


+31 skills in `skills/` provide domain knowledge and shared contracts to the agents. All use `disable-model-invocation: true` (only fire when explicitly invoked). Categorized as:

+- **Shared contract (1)**: `kickstart-state` — defines `.kickstart/state.json` schema and read/write helpers
 - **Phase skills (6)**: One per phase — step-by-step playbooks
- **Domain skills (19)**: AKS Automatic, Gateway API, Workload Identity, Bicep, networking, cost estimation, etc.
+- **Domain skills (19)**: AKS Automatic, Gateway API, Workload Identity, Bicep, networking, cost estimation, PIM activation, etc.
 - **Behavioral skills (4)**: Phase acceleration, teach-then-ask, collaborator voice, file generation batching
 - **Validation skill (1)**: Safeguard checklist (DS001–DS013)


bosesuneha added 2 commits June 2, 2026 21:42

Tatsinnit requested review from Copilot and davidgamero June 4, 2026 18:51

Tatsinnit assigned bosesuneha Jun 4, 2026

Tatsinnit added the enhancement 🚀 New feature or request or improvements on existing code. label Jun 4, 2026

Copilot started reviewing on behalf of Tatsinnit June 4, 2026 18:51 View session

Copilot AI reviewed Jun 4, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(kickstart): split agent into 4 phase-aligned sub-agents#2189

feat(kickstart): split agent into 4 phase-aligned sub-agents#2189
bosesuneha wants to merge 2 commits into
Azure:kickstart-agentfrom
bosesuneha:pr/kickstart-4-agent-split

bosesuneha commented Jun 3, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		You are the Builder sub-agent. Your job is to take the app profile and Azure resource decisions made by `kickstart` and produce all deployment artifacts.

		You own Phase 3 (Design) and Phase 4 (Generate) only. You do not run `az`, `kubectl`, or any destructive command. You write files.


		## Phase 3 — Design

		Follow `/kickstart-design`. Present the target architecture summary using `app.` and `azure.` from state. Reference `/kickstart-aks-automatic`, `/kickstart-gateway-api`, `/kickstart-workload-identity`, `/kickstart-aks-terminology` as needed.


		## Phase 4 — Generate

		Follow `/kickstart-generate`. Also load `/kickstart-deployment-safeguards`, `/kickstart-acr-integration`, `/kickstart-bicep-authoring`, `/kickstart-github-actions-workflow`, `/kickstart-github-actions-oidc`, `/kickstart-file-generation`, and `/kickstart-kaito-gpu` if the workload is GPU.

Conversation

bosesuneha commented Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Topology

Design properties

Files

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bosesuneha commented Jun 3, 2026 •

edited

Loading