cli-five 0.1.6 → 0.2.2

package/README.md

@@ -2,21 +2,38 @@
 
 > **Code Like I'm Five** — scaffold a 5-agent VS Code Copilot team into any repo.
 
+## Two ways to install
+
+### Full setup (recommended for teams)
+
 ```bash
 npx cli-five init
 ```
 
-That's it. Run it in any folder. It interviews you, scaffolds `.github/agents/` + project memory files, searches skills.sh for relevant skills, and tells you what to do next.
+Interviews you, scaffolds agents + memory files + stack-specific instructions, discovers skills from **awesome-copilot** and **skills.sh**, and tells you what to do next.
+
+### Quick plugin install (personal use)
+
+```
+copilot plugin install idusortus/cli-five
+```
+
+Installs the 5 agents to your Copilot profile. No project config, no interview — just the agents with sensible defaults.
 
 ## What you get
 
 ```
 your-repo/
 ├── .github/
-│   ├── agents/                  # 5 agents: Orchestrator, Planner, Coder, Designer, Reviewer
+│   ├── agents/                  # 5 agents with handoffs + subagent delegation
+│   │   ├── orchestrator.agent.md  # 📋 Plan  💻 Code  🎨 Design  🔍 Review
+│   │   ├── planner.agent.md       # 🎯 Execute  💻 Code Directly
+│   │   ├── coder.agent.md         # 🔍 Review  🎯 Back to Orchestrator
+│   │   ├── designer.agent.md      # 🔍 Review  🎯 Back to Orchestrator
+│   │   └── reviewer.agent.md      # 🎯 Back to Orchestrator  💻 Fix Issues
 │   ├── copilot-instructions.md  # Persona + project mandates from interview
-│   ├── instructions/            # Empty — populate via /agent-customization in chat
-│   └── skills/                  # Empty — populate via skills.sh
+│   ├── instructions/            # Stack-specific coding guidelines
+│   └── skills/                  # Installed skills from awesome-copilot + skills.sh
 ├── AGENTS.md                    # Tool-agnostic project context (agents.md standard)
 ├── PROJECT.md                   # Long-form vision (rarely changes)
 ├── STATE.md                     # Cross-session status (changes constantly)
@@ -25,6 +42,15 @@ your-repo/
 └── histories/                   # Per-agent accumulated learnings
 ```
 
+## Orchestration modes
+
+The Orchestrator supports **both** delegation patterns:
+
+- **Handoff buttons** — Click `📋 Plan`, `💻 Code`, `🎨 Design`, or `🔍 Review` to manually transition between agents with pre-filled context.
+- **Subagent delegation** — Ask the Orchestrator to handle a complex task and it calls Planner → Coder → Reviewer autonomously.
+
+Each specialist also has handoffs: Coder/Designer → Reviewer, Reviewer → Coder (fix loop), and everyone → back to Orchestrator.
+
 ## Commands
 
 ```bash
@@ -51,9 +77,10 @@ npx cli-five help
 2. **git init** — if needed. Asks first.
 3. **Overwrite gate** — double-confirms ("Proceed?" then "R U Sure?"). Only `--force --yes` bypasses.
 4. **Interview** — name, one-liner, stack, frameworks, goals, constraints, cost mode, persona toggle.
-5. **Scaffold** — writes 18 files. Substitutes answers into templates. Swaps `model:` per cost mode.
-6. **Skill discovery** — queries skills.sh via `npx skills find <term>` per detected stack. Recommends known-good skills, offers multiselect install, and launches interactive browser.
-7. **Next steps** — tells you to run `/agent-customization` for stack-specific instructions.
+5. **Scaffold** — writes 18 files. Substitutes answers into templates. Swaps `model:` per cost mode. Adds `handoffs:` to all agents.
+6. **Skill discovery** — the hero feature. Multi-source discovery from **awesome-copilot** (30k+ ★ community marketplace) and **skills.sh**. Color-coded recommendations, source attribution, multiselect install, and post-install breadcrumbs with copy-paste commands for the awesome-copilot suggestion skill and MCP server.
+7. **Custom instructions** — generates stack-specific `.instructions.md` files for detected languages.
+8. **Next steps** — tells you to use handoff buttons or autonomous mode, offers plugin install shortcut.
 
 ## Cost modes
 
@@ -76,6 +103,21 @@ Change anytime by editing the `model:` line in `.github/agents/*.agent.md`.
 }
 ```
 
+## Skill discovery
+
+cli-five searches **two sources** for skills matching your detected stack:
+
+| Source | What it has | Stars |
+|---|---|---|
+| **awesome-copilot** | Skills, instructions, agents, plugins from the GitHub community | 30k+ |
+| **skills.sh** | Curated skill repos (Vercel, Anthropic, Microsoft, etc.) | — |
+
+Recommendations show with source attribution and are pre-selected for one-click install. After installation, you get breadcrumbs for ongoing discovery:
+
+- **Suggest skill** — `copilot plugin install awesome-copilot@suggest` (AI-driven repo analysis)
+- **MCP server** — `awesome-copilot-mcp` for programmatic search from any agent
+- **CLI browser** — `npx skills find` for interactive search
+
 ## What this is not
 
 - **Not a runtime.** Once scaffolded, your repo doesn't depend on `cli-five`. You can uninstall the package and the agents still work.
@@ -95,8 +137,8 @@ ELI5 → CLI5. Code Like I'm Five. Five agents. Get it? Yeah, it's a stretch. Bu
 ## Local development
 
 ```bash
-git clone https://github.com/idusortus/squad-mine
-cd squad-mine
+git clone https://github.com/idusortus/cli-five
+cd cli-five
 npm install
 node bin/cli-five.mjs init --cwd /tmp/test-target
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cli-five",
-  "version": "0.1.6",
+  "version": "0.2.2",
   "description": "Code Like I'm Five — scaffold a 5-agent VS Code Copilot team into any repo.",
   "type": "module",
   "bin": {
@@ -10,6 +10,8 @@
     "bin",
     "src",
     "templates",
+    "plugin-agents",
+    "plugin.json",
     "README.md",
     "LICENSE"
   ],

package/plugin-agents/coder.agent.md

@@ -0,0 +1,33 @@
+---
+name: Coder
+description: "Writes production code following workspace conventions. Use when: implementing features, fixing bugs, writing tests."
+model: GPT-5.3-Codex (copilot)
+tools: ['vscode', 'execute', 'read', 'github/*', 'edit', 'search', 'web', 'vscode/memory', 'todo']
+agents: []
+handoffs:
+  - label: "🔍 Review"
+    agent: Reviewer
+    prompt: "Review the changes I just made for correctness and conventions."
+    send: false
+  - label: "🎯 Back to Orchestrator"
+    agent: Orchestrator
+    prompt: "Implementation complete. Coordinate next steps."
+    send: false
+---
+
+## Mandatory Coding Principles
+
+1. **Structure** — Consistent layout. Group by feature. Shared patterns over duplication.
+2. **Architecture** — Flat, explicit code. No clever patterns or unnecessary indirection.
+3. **Functions** — Linear control flow. Small-to-medium functions. Pass state explicitly.
+4. **Naming** — Descriptive-but-simple names. Comment only for invariants or assumptions.
+5. **Logging** — Detailed, structured logs at key boundaries. Explicit errors.
+6. **Regenerability** — Any file can be rewritten from scratch without breaking the system.
+7. **Platform** — Use framework conventions directly and simply.
+8. **Quality** — Deterministic, testable behavior. Simple, focused tests.
+
+## Rules
+
+- Follow existing patterns in the codebase
+- Your final message MUST list every file created or modified
+- Include build/test status if you ran them

package/plugin-agents/designer.agent.md

@@ -0,0 +1,29 @@
+---
+name: Designer
+description: "Handles all UI/UX design tasks. Use when: creating screens, layouts, theming, navigation flows, design systems."
+model: Claude Opus 4.6 (copilot)
+tools: ['read', 'edit', 'search', 'web', 'vscode/memory']
+agents: []
+handoffs:
+  - label: "🔍 Review"
+    agent: Reviewer
+    prompt: "Review the UI changes for accessibility, conventions, and design quality."
+    send: false
+  - label: "🎯 Back to Orchestrator"
+    agent: Orchestrator
+    prompt: "Design work complete. Coordinate next steps."
+    send: false
+---
+
+## Design Principles
+
+- Accessibility first: contrast ratios, touch targets, screen reader support
+- Minimal cognitive load
+- Platform conventions over custom patterns
+- Responsive/adaptive layouts
+- Use the project's designated design system and component library
+
+## Rules
+
+- Your final message MUST list every UI file created or modified
+- Include design decisions and accessibility choices applied

package/plugin-agents/orchestrator.agent.md

@@ -0,0 +1,49 @@
+---
+name: Orchestrator
+description: "Coordinates multi-agent workflows. Delegates to Planner, Coder, Designer, and Reviewer. Use when: complex multi-step tasks, cross-cutting changes, feature implementation."
+model: Claude Sonnet 4.6 (copilot)
+tools: ['read/readFile', 'agent', 'vscode/memory', 'github/*']
+agents: ['Planner', 'Coder', 'Designer', 'Reviewer']
+handoffs:
+  - label: "📋 Plan"
+    agent: Planner
+    prompt: "Research the codebase and create an implementation plan for this task."
+    send: false
+  - label: "💻 Code"
+    agent: Coder
+    prompt: "Implement the approved plan."
+    send: false
+  - label: "🎨 Design"
+    agent: Designer
+    prompt: "Design the UI components described in the plan."
+    send: false
+  - label: "🔍 Review"
+    agent: Reviewer
+    prompt: "Review the implementation for correctness, conventions, and architecture."
+    send: false
+---
+
+You are a project orchestrator. You break down complex requests into tasks and delegate to specialist subagents. You coordinate work but NEVER implement anything yourself.
+
+## Agents
+
+| Agent | Role |
+|---|---|
+| **Planner** | Research codebase, check docs, create implementation plans |
+| **Coder** | Write code, fix bugs, implement features |
+| **Designer** | UI/UX design, layouts, theming |
+| **Reviewer** | Review agent output for correctness and conventions |
+
+## Execution Model
+
+1. **Get the Plan** — Call Planner unless a plan is already in context or the task is trivial.
+2. **Parse Into Phases** — Group non-overlapping files into parallel phases. Dependencies go sequential.
+3. **Execute Each Phase** — Call appropriate agents. Never assign overlapping files to parallel tasks.
+4. **Review (MANDATORY)** — Call Reviewer. Max 2 fix-review rounds.
+5. **Report** — Summarize what was completed and the review verdict.
+
+## Rules
+
+- Delegate WHAT (outcomes), never HOW (implementation details).
+- Never assign overlapping files to agents in the same phase.
+- Never implement anything yourself — you are a router, not a worker.

package/plugin-agents/planner.agent.md

@@ -0,0 +1,41 @@
+---
+name: Planner
+description: "Creates implementation plans by researching the codebase, consulting documentation, and identifying edge cases."
+model: Claude Opus 4.6 (copilot)
+tools: ['read', 'search', 'web', 'vscode/memory']
+user-invocable: false
+handoffs:
+  - label: "🎯 Execute Plan"
+    agent: Orchestrator
+    prompt: "Plan is ready. Execute it phase by phase."
+    send: false
+  - label: "💻 Code Directly"
+    agent: Coder
+    prompt: "Implement this plan."
+    send: false
+---
+
+# Planning Agent
+
+You create plans. You do NOT write code.
+
+## Workflow
+
+1. **Research**: Search the codebase thoroughly. Read relevant files. Find existing patterns.
+2. **Verify**: Use web tools to check documentation for libraries/APIs involved.
+3. **Consider**: Identify edge cases, error states, and implicit requirements.
+4. **Plan**: Output WHAT needs to happen, not HOW to code it.
+
+## Output Format
+
+- **Summary** (one paragraph)
+- **Implementation steps** (ordered), each with file assignments and dependencies
+- **Edge cases** to handle
+- **Open questions** (if any)
+- **Suggested phase grouping** (which steps can be parallelized)
+
+## Rules
+
+- Never skip documentation checks for external APIs
+- Note uncertainties — don't hide them
+- Match existing codebase patterns

package/plugin-agents/reviewer.agent.md

@@ -0,0 +1,52 @@
+---
+name: Reviewer
+description: "Reviews code and agent output for correctness, convention compliance, and architectural alignment."
+model: Claude Opus 4.6 (copilot)
+tools: ['read', 'search', 'web', 'vscode/memory']
+agents: []
+user-invocable: true
+handoffs:
+  - label: "🎯 Back to Orchestrator"
+    agent: Orchestrator
+    prompt: "Review complete. See verdict above. Coordinate fixes or proceed."
+    send: false
+  - label: "💻 Fix Issues"
+    agent: Coder
+    prompt: "Fix the issues identified in the review above."
+    send: false
+---
+
+## Identity
+
+You are a code reviewer. You do NOT write code, fix things, or make changes. You READ, SEARCH, JUDGE, and REPORT.
+
+## Review Checklist
+
+1. **Workspace instructions** — Verify compliance with `.github/instructions/`
+2. **Architecture docs** — Verify component placement and boundaries
+3. **General quality** — OWASP Top 10, no leaked secrets, error handling, testability
+
+## Review Output Format
+
+```
+## Review Summary
+**Verdict:** PASS | PASS WITH NOTES | NEEDS CHANGES | REJECT
+
+### Critical (must fix)
+- [ ] Finding with file reference and line number
+
+### Warnings (should fix)
+- [ ] Finding with file reference and line number
+
+### Notes
+- Observations and suggestions
+
+### What was done well
+- Positive observations
+```
+
+## Rules
+
+- NEVER approve code you haven't read
+- Be specific: file path, line number, what's wrong, what should change
+- If the code is good, say so. Don't invent problems.

package/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "cli-five",
+  "description": "5-agent orchestration squad for GitHub Copilot — Orchestrator, Planner, Coder, Designer, Reviewer.",
+  "version": "0.2.0",
+  "author": {
+    "name": "idusortus"
+  },
+  "agents": "plugin-agents/",
+  "repository": "https://github.com/idusortus/cli-five"
+}

package/src/commands/init.mjs

@@ -93,11 +93,15 @@ function printNextSteps(answers) {
   log.raw(`  2. Enable Copilot subagent invocations (settings.json):`);
   log.raw(kleur.gray(`        "chat.subagents.allowInvocationsFromSubagents": true`));
   log.raw(`  3. Open Copilot Chat — select an agent from the dropdown (${kleur.bold('not')} @mention).`);
-  log.raw(`  4. Select ${kleur.bold('Orchestrator')} from the dropdown, then ask:`);
-  log.raw(kleur.gray(`        read PROJECT.md and propose Phase 1.`));
-  log.raw(`  5. Review generated instruction files in .github/instructions/.`);
+  log.raw(`  4. Select ${kleur.bold('Orchestrator')} — use handoff buttons or ask it to delegate:`);
+  log.raw(kleur.gray(`        📋 Plan  💻 Code  🎨 Design  🔍 Review`));
+  log.raw(`  5. Or go autonomous:`);
+  log.raw(kleur.gray(`        read PROJECT.md and implement Phase 1.`));
+  log.raw(`  6. Review generated instruction files in .github/instructions/.`);
   log.raw(kleur.gray(`        Edit applyTo globs and guidelines to fit your project.`));
-  log.raw(kleur.gray(`        Installed skills are in .agents/skills/ (from skills.sh).`));
+  log.raw('');
+  log.raw(kleur.dim('  Quick plugin install (personal, no project config):'));
+  log.raw(kleur.dim('    copilot plugin install idusortus/cli-five'));
   log.raw('');
   log.raw(kleur.dim('Edit cost mode anytime by changing `model:` in .github/agents/*.agent.md.'));
   log.raw('');

package/src/steps/interview.mjs

@@ -6,6 +6,14 @@ import prompts from 'prompts';
 // Research via Context7: Next.js, Vite+React, Express, Hono all score
 // 80+ benchmark with high snippet counts and well-indexed docs.
 const STACK_PRESETS = [
+  {
+    title: 'Next.js + Supabase PWA (TypeScript)',
+    value: 'nextjs-supabase',
+    description: 'Next.js 15 static export, React 19, Tailwind v4, Supabase, SWR, Vercel hosting, PWA.',
+    stack: ['Node + TypeScript'],
+    frameworks: ['Next.js', 'React', 'Tailwind CSS', 'Supabase', 'SWR'],
+    quickstart: 'npx create-next-app@latest . --yes && npm i @supabase/supabase-js swr date-fns clsx && npm run dev',
+  },
   {
     title: 'Next.js (TypeScript)',
     value: 'nextjs',

package/src/steps/skills.mjs

@@ -1,11 +1,16 @@
 import prompts from 'prompts';
+import kleur from 'kleur';
 import { spawn, execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readdirSync, renameSync, rmSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { createRequire } from 'node:module';
 import { log } from '../util/log.mjs';
 
-// Well-known skill repos matched by stack term → repo + suggested skill names
+// ── Known-good skill repos (verified working) ────────────────────────
+// awesome-copilot skills are discovered dynamically via `skills find`.
+const AWESOME_COPILOT_REPO = 'github/awesome-copilot';
+
+// Well-known skill repos matched by stack term → repo + suggested skill names (skills.sh)
 const SKILL_CATALOG = [
   { terms: ['*'], repo: 'anthropics/skills', skills: ['frontend-design', 'skill-creator'] },
   { terms: ['*'], repo: 'vercel-labs/agent-skills', skills: ['vercel-react-best-practices', 'web-design-guidelines'] },
@@ -109,6 +114,7 @@ export async function skillDiscovery({ cwd, answers, args }) {
   if (!env) {
     log.warn('Cannot run skills CLI: no bundled binary, pnpm, or npx found.');
     log.warn('Install Node.js (includes npx) or pnpm, then re-run.');
+    printBreadcrumbs();
     return;
   }
 
@@ -131,73 +137,139 @@ export async function skillDiscovery({ cwd, answers, args }) {
   }
 
   log.ok(`Running skills via ${env.label}`);
-  log.raw('');
 
-  // ── Skill discovery ─────────────────────────────────────────────────
-
-  // 1. Build recommendations from catalog based on stack
-  const recs = buildRecommendations(answers);
-  if (recs.length === 0) {
-    log.dim('No stack-specific recommendations found.');
-  } else {
-    log.raw(`  ${pad('Skill', 36)} ${pad('Repo', 36)}`);
-    log.raw(`  ${'─'.repeat(36)} ${'─'.repeat(36)}`);
-    for (const r of recs) {
-      log.raw(`  ${pad(r.skill, 36)} ${pad(r.repo, 36)}`);
-    }
-    log.raw('');
-  }
-
-  // 2. Offer interactive search per stack term
+  // ── 1. Auto-search all stack terms silently ─────────────────────────
   const terms = suggestSearches(answers);
+  const searchResults = [];
+
   if (terms.length > 0) {
-    log.dim(`Suggested searches: ${terms.map((t) => `"${t}"`).join(', ')}`);
     log.raw('');
+    log.info(`Searching skills.sh for: ${terms.map((t) => kleur.bold(t)).join(', ')} ...`);
+    for (const term of terms) {
+      const output = await runSkillsSilent(env, ['find', term], cwd);
+      searchResults.push(...parseSkillRefs(output));
+    }
+    if (searchResults.length > 0) {
+      log.ok(`Found ${searchResults.length} skill${searchResults.length > 1 ? 's' : ''} from search.`);
+    } else {
+      log.dim('No additional skills found via search.');
+    }
   }
 
-  for (const term of terms) {
-    const { go } = await prompts({
-      type: 'confirm',
-      name: 'go',
-      message: `Search skills.sh for "${term}"?`,
-      initial: true,
-    });
-    if (go) {
-      await runSkills(env, ['find', term], cwd);
+  // ── 2. Build static catalog recommendations ─────────────────────────
+  const catalogRecs = buildRecommendations(answers);
+
+  // ── 3. Categorize search results by source ──────────────────────────
+  const awesomeResults = [];
+  const otherResults = [];
+  for (const r of searchResults) {
+    const parsed = parseRef(r.ref);
+    if (parsed && parsed.repo === AWESOME_COPILOT_REPO) {
+      awesomeResults.push({ ...r, ...parsed });
+    } else {
+      otherResults.push(r);
     }
   }
 
-  // 3. Offer to install from well-known repos
-  if (recs.length > 0) {
-    const { install } = await prompts({
+  // ── 4. Display hero section ─────────────────────────────────────────
+  displayHeroRecommendations(awesomeResults, catalogRecs, answers);
+
+  // ── 5. Build unified picker ─────────────────────────────────────────
+  const seen = new Set();
+  const choices = [];
+
+  // awesome-copilot results from search (dynamic, real names)
+  for (const r of awesomeResults) {
+    const key = r.ref;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    choices.push({
+      title: `${kleur.cyan('⬡')} ${r.skill} ${kleur.dim(`(${r.installs})`)} ${kleur.cyan('← awesome-copilot')}`,
+      value: { source: 'awesome', repo: r.repo, skill: r.skill, ref: r.ref },
+      selected: true,
+    });
+  }
+
+  // Static catalog recs (verified repos)
+  for (const r of catalogRecs) {
+    const ref = `${r.repo}@${r.skill}`;
+    if (seen.has(ref)) continue;
+    seen.add(ref);
+    choices.push({
+      title: `${kleur.yellow('◆')} ${r.skill} ${kleur.dim(`(${r.repo})`)} ${kleur.yellow('← skills.sh')}`,
+      value: { source: 'catalog', ref, repo: r.repo, skill: r.skill },
+      selected: true,
+    });
+  }
+
+  // Other search results (non-awesome-copilot)
+  for (const r of otherResults) {
+    if (seen.has(r.ref)) continue;
+    seen.add(r.ref);
+    const parsed = parseRef(r.ref);
+    choices.push({
+      title: `${kleur.yellow('◆')} ${parsed ? parsed.skill : r.ref} ${kleur.dim(`(${parsed ? parsed.repo : ''} — ${r.installs})`)} ${kleur.yellow('← skills.sh')}`,
+      value: { source: 'search', ref: r.ref, repo: parsed?.repo, skill: parsed?.skill },
+      selected: false,
+    });
+  }
+
+  // ── 6. Prompt user to select skills ─────────────────────────────────
+  const installResults = [];
+
+  if (choices.length > 0) {
+    log.raw('');
+    const { toInstall } = await prompts({
       type: 'multiselect',
-      name: 'install',
-      message: 'Install recommended skills?',
-      choices: recs.map((r) => ({
-        title: `${r.skill} (${r.repo})`,
-        value: r,
-        selected: false,
-      })),
-      hint: 'Space to select, Enter to confirm',
+      name: 'toInstall',
+      message: 'Select skills to install',
+      choices,
+      hint: 'Space to toggle, Enter to confirm',
     });
 
-    if (install && install.length > 0) {
+    if (toInstall && toInstall.length > 0) {
+      log.raw('');
+
+      // Group by repo for batch install
       const byRepo = new Map();
-      for (const r of install) {
-        if (!byRepo.has(r.repo)) byRepo.set(r.repo, []);
-        byRepo.get(r.repo).push(r.skill);
+      const standalone = [];
+
+      for (const item of toInstall) {
+        if (item.repo && item.skill) {
+          if (!byRepo.has(item.repo)) byRepo.set(item.repo, []);
+          byRepo.get(item.repo).push(item.skill);
+        } else if (item.ref) {
+          standalone.push(item.ref);
+        }
       }
+
+      // Batch install per repo
       for (const [repo, skills] of byRepo) {
         const skillArgs = skills.flatMap((s) => ['--skill', s]);
-        log.info(`Installing from ${repo}: ${skills.join(', ')}`);
-        await runSkills(env, ['add', repo, ...skillArgs, '-a', 'github-copilot'], cwd);
+        log.info(`Installing from ${kleur.bold(repo)}: ${skills.join(', ')}`);
+        const result = await runSkillsTracked(env, ['add', repo, ...skillArgs, '-a', 'github-copilot'], cwd);
+        for (const s of skills) {
+          installResults.push({ name: `${repo}@${s}`, ...result });
+        }
+      }
+
+      // Standalone refs
+      for (const ref of standalone) {
+        log.info(`Installing ${ref}...`);
+        const result = await runSkillsTracked(env, ['add', ref, '-a', 'github-copilot'], cwd);
+        installResults.push({ name: ref, ...result });
       }
 
       await relocateSkills(cwd);
     }
   }
 
-  // 4. Offer freeform catch-all
+  // ── 7. Install summary ──────────────────────────────────────────────
+  if (installResults.length > 0) {
+    printInstallSummary(installResults);
+  }
+
+  // Offer freeform catch-all
   const { freeform } = await prompts({
     type: 'confirm',
     name: 'freeform',
@@ -209,10 +281,143 @@ export async function skillDiscovery({ cwd, answers, args }) {
     await relocateSkills(cwd);
   }
 
-  log.dim('Done. Run `npx skills find` anytime to discover more.');
+  // ── Post-install breadcrumbs (THE HERO FINISH) ──────────────────────
+  printBreadcrumbs();
+}
+
+// ── Hero display ──────────────────────────────────────────────────────
+
+function displayHeroRecommendations(awesomeResults, catalogRecs, answers) {
+  const stackLabel = [...(answers.stack || []), ...(answers.frameworks || [])].join(', ') || 'general';
+
+  log.raw('');
+  log.raw(kleur.bold().cyan('  ╔══════════════════════════════════════════════════════════════════╗'));
+  log.raw(kleur.bold().cyan('  ║') + kleur.bold('  📦 RECOMMENDED FOR YOUR STACK: ') + kleur.bold().white(stackLabel) + pad('', Math.max(0, 30 - stackLabel.length)) + kleur.bold().cyan(' ║'));
+  log.raw(kleur.bold().cyan('  ╚══════════════════════════════════════════════════════════════════╝'));
+
+  if (awesomeResults.length > 0) {
+    log.raw('');
+    log.raw(kleur.cyan('  ⬡ Source: awesome-copilot') + kleur.dim('  (github/awesome-copilot · 30k+ ★)'));
+    log.raw(kleur.dim('  ─────────────────────────────────────────────────────────'));
+    for (const r of awesomeResults) {
+      log.raw(`    ${kleur.green('✓')} ${pad(r.skill, 38)} ${kleur.dim(r.installs)}`);
+    }
+  }
+
+  if (catalogRecs.length > 0) {
+    log.raw('');
+    log.raw(kleur.yellow('  ◆ Source: skills.sh') + kleur.dim('  (verified repos)'));
+    log.raw(kleur.dim('  ─────────────────────────────────────────────────────────'));
+    for (const r of catalogRecs) {
+      log.raw(`    ${kleur.green('✓')} ${pad(r.skill, 38)} ${kleur.dim(r.repo)}`);
+    }
+  }
+
+  log.raw('');
 }
 
-// ── Relocation ─────────────────────────────────────────────────────────
+// ── Install summary ───────────────────────────────────────────────────
+
+function printInstallSummary(results) {
+  const succeeded = results.filter((r) => r.ok);
+  const failed = results.filter((r) => !r.ok);
+
+  log.raw('');
+  if (succeeded.length > 0) {
+    log.ok(`Installed ${succeeded.length} skill${succeeded.length > 1 ? 's' : ''} successfully.`);
+  }
+
+  if (failed.length > 0) {
+    log.raw('');
+    log.warn(`${failed.length} skill${failed.length > 1 ? 's' : ''} failed to install:`);
+    for (const f of failed) {
+      log.raw(`    ${kleur.red('✗')} ${f.name}`);
+      if (f.reason) {
+        log.raw(`      ${kleur.dim(f.reason)}`);
+      }
+    }
+    log.raw('');
+    log.dim('Install failed skills manually: npx skills add <owner/repo> --skill <name>');
+  }
+}
+
+// ── Post-install breadcrumbs ──────────────────────────────────────────
+
+function printBreadcrumbs() {
+  log.raw('');
+  log.raw(kleur.bold().green('  ┌──────────────────────────────────────────────────────────────────┐'));
+  log.raw(kleur.bold().green('  │') + kleur.bold('  🎯 KEEP DISCOVERING — paste into VS Code / Copilot Chat:       ') + kleur.bold().green('│'));
+  log.raw(kleur.bold().green('  ├──────────────────────────────────────────────────────────────────┤'));
+  log.raw(kleur.bold().green('  │') + '                                                                  ' + kleur.bold().green('│'));
+  log.raw(kleur.bold().green('  │') + '  Add awesome-copilot MCP for ongoing search:                     ' + kleur.bold().green('│'));
+  log.raw(kleur.bold().green('  │') + kleur.white('    Add to .vscode/mcp.json:                                   ') + kleur.bold().green('│'));
+  log.raw(kleur.bold().green('  │') + kleur.dim('      "awesome-copilot": {                                     ') + kleur.bold().green('│'));
+  log.raw(kleur.bold().green('  │') + kleur.dim('        "command": "npx",                                      ') + kleur.bold().green('│'));
+  log.raw(kleur.bold().green('  │') + kleur.dim('        "args": ["-y", "awesome-copilot-mcp"]                  ') + kleur.bold().green('│'));
+  log.raw(kleur.bold().green('  │') + kleur.dim('      }                                                        ') + kleur.bold().green('│'));
+  log.raw(kleur.bold().green('  │') + '                                                                  ' + kleur.bold().green('│'));
+  log.raw(kleur.bold().green('  │') + '  Browse skills anytime:                                          ' + kleur.bold().green('│'));
+  log.raw(kleur.bold().green('  │') + kleur.white('    npx skills find                                            ') + kleur.bold().green('│'));
+  log.raw(kleur.bold().green('  │') + '                                                                  ' + kleur.bold().green('│'));
+  log.raw(kleur.bold().green('  └──────────────────────────────────────────────────────────────────┘'));
+  log.raw('');
+}
+
+// ── Runner ─────────────────────────────────────────────────────────────
+
+/** Run skills CLI with stdio: inherit (visible to user). */
+function runSkills(env, skillsArgs, cwd) {
+  const { cmd, args } = env.runner(skillsArgs);
+  return runInteractive(cmd, args, cwd);
+}
+
+/** Run skills CLI, capture output, track success/failure. Returns { ok, reason }. */
+function runSkillsTracked(env, skillsArgs, cwd) {
+  const { cmd, args } = env.runner(skillsArgs);
+  return new Promise((resolve) => {
+    let output = '';
+    const proc = spawn(cmd, args, { cwd, stdio: ['inherit', 'pipe', 'pipe'] });
+    proc.stdout.on('data', (chunk) => {
+      const text = chunk.toString();
+      process.stdout.write(text);
+      output += text;
+    });
+    proc.stderr.on('data', (chunk) => {
+      const text = chunk.toString();
+      process.stderr.write(text);
+      output += text;
+    });
+    proc.on('exit', (code) => {
+      const clean = stripAnsi(output);
+      if (code !== 0 || /failed to clone|installation failed|canceled/i.test(clean)) {
+        const reason = extractFailureReason(clean);
+        resolve({ ok: false, reason });
+      } else {
+        resolve({ ok: true, reason: null });
+      }
+    });
+    proc.on('error', (err) => {
+      resolve({ ok: false, reason: err.message });
+    });
+  });
+}
+
+/** Run skills CLI silently — capture stdout/stderr without echoing. */
+function runSkillsSilent(env, skillsArgs, cwd) {
+  const { cmd, args } = env.runner(skillsArgs);
+  return new Promise((resolve) => {
+    let output = '';
+    const proc = spawn(cmd, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    proc.stdout.on('data', (chunk) => {
+      output += chunk.toString();
+    });
+    proc.stderr.on('data', (chunk) => {
+      output += chunk.toString();
+    });
+    proc.on('exit', () => resolve(output));
+    proc.on('error', () => resolve(''));
+  });
+}
 
 async function relocateSkills(cwd) {
   const src = join(cwd, '.agents', 'skills');
@@ -270,12 +475,7 @@ async function relocateSkills(cwd) {
   }
 }
 
-// ── Runner ─────────────────────────────────────────────────────────────
-
-function runSkills(env, skillsArgs, cwd) {
-  const { cmd, args } = env.runner(skillsArgs);
-  return runInteractive(cmd, args, cwd);
-}
+// ── Helpers ────────────────────────────────────────────────────────────
 
 function buildRecommendations(a) {
   const stackLower = (a.stack || []).map((s) => s.toLowerCase());
@@ -315,6 +515,24 @@ function suggestSearches(a) {
   return [...out];
 }
 
+/** Parse owner/repo@skill ref into { repo, skill }. */
+function parseRef(ref) {
+  const match = /^(.+?\/.+?)@(.+)$/.exec(ref);
+  if (!match) return null;
+  return { repo: match[1], skill: match[2] };
+}
+
+/** Extract a concise failure reason from skills CLI output. */
+function extractFailureReason(output) {
+  const cloneMatch = /Failed to clone[^:]*:\s*(.+)/i.exec(output);
+  if (cloneMatch) return cloneMatch[1].trim();
+
+  const errorMatch = /(?:error|failed)[:\s]+(.+)/im.exec(output);
+  if (errorMatch) return errorMatch[1].trim();
+
+  return 'Unknown error (check output above)';
+}
+
 function pad(s, n) {
   return (s || '').padEnd(n);
 }
@@ -330,3 +548,20 @@ function runInteractive(cmd, args, cwd) {
     });
   });
 }
+
+function stripAnsi(str) {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, '');
+}
+
+/** Extract owner/repo@skill refs from `skills find <term>` output. */
+function parseSkillRefs(output) {
+  const clean = stripAnsi(output);
+  const regex = /^(\S+\/\S+@\S+)\s+(.+?installs)/gm;
+  const results = [];
+  let match;
+  while ((match = regex.exec(clean))) {
+    results.push({ ref: match[1], installs: match[2].trim() });
+  }
+  return results;
+}

package/templates/.github/agents/coder.agent.md

@@ -4,6 +4,15 @@ description: "Writes production code following workspace conventions. Use when:
 model: GPT-5.3-Codex (copilot)
 tools: ['vscode', 'execute', 'read', 'io.github.upstash/context7/*', 'github/*', 'edit', 'search', 'web', 'vscode/memory', 'todo']
 agents: []
+handoffs:
+  - label: "🔍 Review"
+    agent: Reviewer
+    prompt: "Review the changes I just made for correctness and conventions."
+    send: false
+  - label: "🎯 Back to Orchestrator"
+    agent: Orchestrator
+    prompt: "Implementation complete. Coordinate next steps."
+    send: false
 ---
 
 ## Model Selection

package/templates/.github/agents/designer.agent.md

@@ -4,6 +4,15 @@ description: "Handles all UI/UX design tasks. Use when: creating screens, layout
 model: Claude Opus 4.6 (copilot)
 tools: ['read', 'edit', 'search', 'web', 'io.github.upstash/context7/*', 'vscode/memory']
 agents: []
+handoffs:
+  - label: "🔍 Review"
+    agent: Reviewer
+    prompt: "Review the UI changes for accessibility, conventions, and design quality."
+    send: false
+  - label: "🎯 Back to Orchestrator"
+    agent: Orchestrator
+    prompt: "Design work complete. Coordinate next steps."
+    send: false
 ---
 
 ## Model Selection

package/templates/.github/agents/orchestrator.agent.md

@@ -4,6 +4,23 @@ description: "Coordinates multi-agent workflows. Delegates to Planner, Coder, De
 model: Claude Sonnet 4.6 (copilot)
 tools: ['read/readFile', 'agent', 'vscode/memory', 'github/*']
 agents: ['Planner', 'Coder', 'Designer', 'Reviewer']
+handoffs:
+  - label: "📋 Plan"
+    agent: Planner
+    prompt: "Read PROJECT.md and STATE.md, then create an implementation plan for this task."
+    send: false
+  - label: "💻 Code"
+    agent: Coder
+    prompt: "Implement the approved plan. Read decisions.md for context."
+    send: false
+  - label: "🎨 Design"
+    agent: Designer
+    prompt: "Design the UI components described in the plan."
+    send: false
+  - label: "🔍 Review"
+    agent: Reviewer
+    prompt: "Review the implementation for correctness, conventions, and architecture."
+    send: false
 ---
 
 You are a project orchestrator. You break down complex requests into tasks and delegate to specialist subagents. You coordinate work but NEVER implement anything yourself.

package/templates/.github/agents/planner.agent.md

@@ -4,6 +4,15 @@ description: "Creates implementation plans by researching the codebase, consulti
 model: Claude Opus 4.6 (copilot)
 tools: ['read', 'search', 'web', 'io.github.upstash/context7/*', 'vscode/memory']
 user-invocable: false
+handoffs:
+  - label: "🎯 Execute Plan"
+    agent: Orchestrator
+    prompt: "Plan is ready. Execute it phase by phase."
+    send: false
+  - label: "💻 Code Directly"
+    agent: Coder
+    prompt: "Implement this plan."
+    send: false
 ---
 
 # Planning Agent

package/templates/.github/agents/reviewer.agent.md

@@ -5,6 +5,15 @@ model: Claude Opus 4.6 (copilot)
 tools: ['read', 'search', 'web', 'vscode/memory']
 agents: []
 user-invocable: true
+handoffs:
+  - label: "🎯 Back to Orchestrator"
+    agent: Orchestrator
+    prompt: "Review complete. See verdict above. Coordinate fixes or proceed."
+    send: false
+  - label: "💻 Fix Issues"
+    agent: Coder
+    prompt: "Fix the issues identified in the review above."
+    send: false
 ---
 
 ## Model Selection