cli-five 0.1.5 → 0.2.1

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.5",
+  "version": "0.2.1",
   "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

@@ -49,6 +49,11 @@ export async function init(args) {
     answers.costMode = args.costMode;
   }
 
+  if (answers.presetId && answers.presetId !== 'custom') {
+    log.info(`Preset: ${answers.presetId}`);
+  }
+  if (answers.frameworks.length) log.info(`Stack:  ${answers.stack.join(', ')} + ${answers.frameworks.join(', ')}`);
+
   // 5. Scaffold
   log.step('4/6 Scaffold');
   const written = scaffold({ cwd, answers, args });
@@ -88,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

@@ -1,5 +1,69 @@
 import prompts from 'prompts';
 
+// ── Preset stacks ─────────────────────────────────────────────────────
+// Chosen for: LLM familiarity, low setup friction, minimal config,
+// copy-paste quickstart, broad hosting support.
+// 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 (TypeScript)',
+    value: 'nextjs',
+    description: 'Full-stack React. App Router, TypeScript, Tailwind. `npx create-next-app`',
+    stack: ['Node + TypeScript'],
+    frameworks: ['Next.js', 'React', 'Tailwind CSS'],
+    quickstart: 'npx create-next-app@latest . --yes && npm run dev',
+  },
+  {
+    title: 'Vite + React (TypeScript)',
+    value: 'vite-react',
+    description: 'SPA frontend. Lightning-fast HMR. `npm create vite`',
+    stack: ['Node + TypeScript'],
+    frameworks: ['Vite', 'React', 'TypeScript'],
+    quickstart: 'npm create vite@latest . -- --template react-ts && npm i && npm run dev',
+  },
+  {
+    title: 'Express API (TypeScript)',
+    value: 'express',
+    description: 'REST API server. Minimal, well-known, huge ecosystem.',
+    stack: ['Node + TypeScript'],
+    frameworks: ['Express', 'TypeScript'],
+    quickstart: 'npm init -y && npm i express typescript tsx @types/express && npx tsx src/index.ts',
+  },
+  {
+    title: 'Hono API (TypeScript)',
+    value: 'hono',
+    description: 'Ultrafast, Web Standards. Works on Node, Bun, Deno, Cloudflare.',
+    stack: ['Node + TypeScript'],
+    frameworks: ['Hono', 'TypeScript'],
+    quickstart: 'npm create hono@latest . && npm i && npm run dev',
+  },
+  {
+    title: 'Vite + Vue (TypeScript)',
+    value: 'vite-vue',
+    description: 'SPA frontend with Vue 3 + Composition API.',
+    stack: ['Node + TypeScript'],
+    frameworks: ['Vite', 'Vue', 'TypeScript'],
+    quickstart: 'npm create vite@latest . -- --template vue-ts && npm i && npm run dev',
+  },
+  {
+    title: 'Python + FastAPI',
+    value: 'fastapi',
+    description: 'Modern Python API with type hints and auto-docs.',
+    stack: ['Python'],
+    frameworks: ['FastAPI', 'Pydantic', 'Uvicorn'],
+    quickstart: 'pip install fastapi uvicorn && uvicorn main:app --reload',
+  },
+  {
+    title: 'Custom (freeform)',
+    value: 'custom',
+    description: 'Enter your own stack and frameworks manually.',
+    stack: [],
+    frameworks: [],
+    quickstart: '',
+  },
+];
+
 const COST_MODES = [
   { title: 'Premium (default)', value: 'premium', description: 'Sonnet/Opus/Codex. Best quality, real cost.' },
   { title: 'Cheap (0x)', value: 'cheap', description: 'GPT-4.1 / GPT-4o / GPT-5 mini. Free tier-friendly.' },
@@ -13,7 +77,8 @@ export async function interview(detected, args) {
     throw new Error('Interview cancelled. Nothing was written.');
   };
 
-  const answers = await prompts(
+  // ── Basic info ────────────────────────────────────────────────────
+  const basic = await prompts(
     [
       {
         type: 'text',
@@ -27,20 +92,61 @@ export async function interview(detected, args) {
         message: 'One-line description (becomes PROJECT.md vision)',
         initial: '',
       },
-      {
-        type: 'list',
-        name: 'stack',
-        message: 'Tech stack (comma separated)',
-        initial: detected.stacks.map((s) => s.label).join(', '),
-        separator: ',',
-      },
-      {
-        type: 'list',
-        name: 'frameworks',
-        message: 'Frameworks / key libraries (comma separated, optional)',
-        initial: '',
-        separator: ',',
-      },
+    ],
+    { onCancel },
+  );
+
+  // ── Stack preset or freeform ──────────────────────────────────────
+  // If detection already found a stack, show it as initial hint
+  const detectedLabel = detected.stacks.map((s) => s.label).join(', ');
+
+  const { preset } = await prompts(
+    {
+      type: 'select',
+      name: 'preset',
+      message: detectedLabel
+        ? `Stack preset (detected: ${detectedLabel})`
+        : 'Stack preset — pick one or go freeform',
+      choices: STACK_PRESETS,
+      initial: 0,
+    },
+    { onCancel },
+  );
+
+  let stackAnswers;
+  const chosenPreset = STACK_PRESETS.find((p) => p.value === preset);
+
+  if (preset === 'custom') {
+    // Freeform: user types whatever they want
+    stackAnswers = await prompts(
+      [
+        {
+          type: 'list',
+          name: 'stack',
+          message: 'Tech stack (comma separated)',
+          initial: detectedLabel,
+          separator: ',',
+        },
+        {
+          type: 'list',
+          name: 'frameworks',
+          message: 'Frameworks / key libraries (comma separated)',
+          initial: '',
+          separator: ',',
+        },
+      ],
+      { onCancel },
+    );
+  } else {
+    stackAnswers = {
+      stack: chosenPreset.stack,
+      frameworks: chosenPreset.frameworks,
+    };
+  }
+
+  // ── Remaining questions ───────────────────────────────────────────
+  const rest = await prompts(
+    [
       {
         type: 'text',
         name: 'goals',
@@ -68,19 +174,31 @@ export async function interview(detected, args) {
     { onCancel },
   );
 
-  return normalize({ ...defaults(detected), ...answers });
+  return normalize({
+    ...defaults(detected),
+    ...basic,
+    ...stackAnswers,
+    ...rest,
+    presetId: preset,
+    quickstart: chosenPreset?.quickstart || '',
+  });
 }
 
+/** Default stack is Next.js + TypeScript when nothing detected and --yes. */
 function defaults(detected) {
+  const hasDetected = detected.stacks.length > 0;
+  const fallback = STACK_PRESETS[0]; // Next.js (TypeScript)
   return {
     projectName: detected.projectName,
     oneLiner: '',
-    stack: detected.stacks.map((s) => s.label),
-    frameworks: [],
+    stack: hasDetected ? detected.stacks.map((s) => s.label) : fallback.stack,
+    frameworks: hasDetected ? [] : fallback.frameworks,
     goals: '',
     constraints: '',
     costMode: 'premium',
     snark: true,
+    presetId: hasDetected ? 'custom' : fallback.value,
+    quickstart: hasDetected ? '' : fallback.quickstart,
   };
 }
 

package/src/steps/scaffold.mjs

@@ -94,6 +94,7 @@ function buildVars(a) {
     FRAMEWORKS: a.frameworks.length ? a.frameworks.join(', ') : 'None declared.',
     GOALS: a.goals || 'TODO — declare the primary goal.',
     CONSTRAINTS: a.constraints || 'None declared.',
+    QUICKSTART: a.quickstart || 'TODO — add install + run commands here.',
     COST_MODE: a.costMode,
     DATE: new Date().toISOString().slice(0, 10),
     PERSONA_BLOCK: a.snark ? PERSONA_BLOCK : '',

package/src/steps/skills.mjs

@@ -1,11 +1,43 @@
 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
+// ── Awesome-copilot catalog (github/awesome-copilot) ──────────────────
+// Curated subset mapped by stack term → { name, description, type }
+const AWESOME_CATALOG = [
+  // Universal
+  { terms: ['*'], name: 'frontend-design', desc: 'Production-grade UI design', type: 'skill', source: 'awesome-copilot' },
+  { terms: ['*'], name: 'conventional-commit', desc: 'Commit message standards', type: 'skill', source: 'awesome-copilot' },
+  { terms: ['*'], name: 'documentation-writer', desc: 'Generate project docs', type: 'skill', source: 'awesome-copilot' },
+  { terms: ['*'], name: 'mermaid-diagrams', desc: 'Create software diagrams', type: 'skill', source: 'awesome-copilot' },
+  // JavaScript / TypeScript / React / Next
+  { terms: ['node', 'typescript', 'javascript'], name: 'typescript', desc: 'TypeScript best practices', type: 'instruction', source: 'awesome-copilot' },
+  { terms: ['react', 'next'], name: 'reactjs', desc: 'React patterns & conventions', type: 'instruction', source: 'awesome-copilot' },
+  { terms: ['next'], name: 'nextjs', desc: 'Next.js patterns', type: 'instruction', source: 'awesome-copilot' },
+  { terms: ['node', 'typescript', 'react', 'next'], name: 'playwright-tester', desc: 'E2E testing with Playwright', type: 'skill', source: 'awesome-copilot' },
+  // Python
+  { terms: ['python', 'django', 'flask', 'fastapi'], name: 'python', desc: 'Python best practices', type: 'instruction', source: 'awesome-copilot' },
+  { terms: ['django'], name: 'django', desc: 'Django conventions', type: 'instruction', source: 'awesome-copilot' },
+  { terms: ['fastapi'], name: 'fastapi', desc: 'FastAPI patterns', type: 'instruction', source: 'awesome-copilot' },
+  // .NET
+  { terms: ['dotnet', '.net', 'csharp', 'c#'], name: 'dotnet', desc: '.NET conventions', type: 'instruction', source: 'awesome-copilot' },
+  // Rust
+  { terms: ['rust'], name: 'rust', desc: 'Rust best practices', type: 'instruction', source: 'awesome-copilot' },
+  // Go
+  { terms: ['go', 'golang'], name: 'go', desc: 'Go conventions', type: 'instruction', source: 'awesome-copilot' },
+  // Mobile
+  { terms: ['swift', 'ios'], name: 'swift', desc: 'Swift/iOS patterns', type: 'instruction', source: 'awesome-copilot' },
+  { terms: ['kotlin', 'android'], name: 'kotlin', desc: 'Kotlin/Android patterns', type: 'instruction', source: 'awesome-copilot' },
+  // DevOps / Infra
+  { terms: ['docker', 'kubernetes', 'devops'], name: 'docker', desc: 'Docker best practices', type: 'instruction', source: 'awesome-copilot' },
+  { terms: ['terraform'], name: 'terraform', desc: 'Terraform conventions', type: 'instruction', source: '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 +141,8 @@ 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.');
+    // Still show awesome-copilot recs (they don't need skills CLI)
+    await showAwesomeCopilotOnly(answers);
     return;
   }
 
@@ -133,71 +167,132 @@ 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('');
-  }
+  // ── Build recommendations from BOTH sources ─────────────────────────
+  const awesomeRecs = buildAwesomeRecommendations(answers);
+  const skillsShRecs = buildRecommendations(answers);
 
-  // 2. Offer interactive search per stack term
+  // ── Display hero section ────────────────────────────────────────────
+  displayHeroRecommendations(awesomeRecs, skillsShRecs, answers);
+
+  // ── Combined picker ─────────────────────────────────────────────────
   const terms = suggestSearches(answers);
+
+  // Search skills.sh for additional results
+  const allFound = [];
   if (terms.length > 0) {
     log.dim(`Suggested searches: ${terms.map((t) => `"${t}"`).join(', ')}`);
     log.raw('');
+
+    for (const term of terms) {
+      const { go } = await prompts({
+        type: 'confirm',
+        name: 'go',
+        message: `Search skills.sh for "${term}"?`,
+        initial: true,
+      });
+      if (go) {
+        const output = await runSkillsCapture(env, ['find', term], cwd);
+        allFound.push(...parseSkillRefs(output));
+      }
+    }
   }
 
-  for (const term of terms) {
-    const { go } = await prompts({
-      type: 'confirm',
-      name: 'go',
-      message: `Search skills.sh for "${term}"?`,
-      initial: true,
+  // Build combined skill picker — awesome recs + catalog recs + search results
+  const seen = new Set();
+  const choices = [];
+
+  // Awesome-copilot recs first (hero placement)
+  for (const r of awesomeRecs) {
+    const key = `awesome:${r.name}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    choices.push({
+      title: `${kleur.cyan('⬡')} ${r.name} ${kleur.dim(`(${r.desc})`)} ${kleur.cyan('← awesome-copilot')}`,
+      value: { source: 'awesome', name: r.name, type: r.type },
+      selected: true,
+    });
+  }
+
+  // skills.sh catalog recs
+  for (const r of skillsShRecs) {
+    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: 'skillssh', ref, repo: r.repo, skill: r.skill },
+      selected: true,
+    });
+  }
+
+  // skills.sh search results
+  for (const r of allFound) {
+    if (seen.has(r.ref)) continue;
+    seen.add(r.ref);
+    choices.push({
+      title: `${kleur.yellow('◆')} ${r.ref} ${kleur.dim(`— ${r.installs}`)} ${kleur.yellow('← skills.sh')}`,
+      value: { source: 'skillssh', ref: r.ref },
+      selected: false,
     });
-    if (go) {
-      await runSkills(env, ['find', term], cwd);
-    }
   }
 
-  // 3. Offer to install from well-known repos
-  if (recs.length > 0) {
-    const { install } = await prompts({
+  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) {
-      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);
+    if (toInstall && toInstall.length > 0) {
+      // Separate awesome-copilot entries from skills.sh entries
+      const awesomeItems = toInstall.filter((i) => i.source === 'awesome');
+      const skillsShItems = toInstall.filter((i) => i.source === 'skillssh');
+
+      // Install awesome-copilot skills/instructions via npx skills (they're in the registry too)
+      if (awesomeItems.length > 0) {
+        log.raw('');
+        log.info(`${kleur.cyan('awesome-copilot')} resources selected: ${awesomeItems.map((i) => i.name).join(', ')}`);
+        log.dim('These will be installed via skills CLI from the awesome-copilot registry.');
+        for (const item of awesomeItems) {
+          log.info(`Installing ${item.name} (${item.type})...`);
+          await runSkills(env, ['add', `awesome-copilot@${item.name}`, '-a', 'github-copilot'], cwd);
+        }
       }
-      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);
+
+      // Install skills.sh entries
+      if (skillsShItems.length > 0) {
+        const byRepo = new Map();
+        const standalone = [];
+
+        for (const item of skillsShItems) {
+          if (item.repo) {
+            if (!byRepo.has(item.repo)) byRepo.set(item.repo, []);
+            byRepo.get(item.repo).push(item.skill);
+          } else {
+            standalone.push(item.ref);
+          }
+        }
+
+        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);
+        }
+
+        for (const ref of standalone) {
+          log.info(`Installing ${ref}...`);
+          await runSkills(env, ['add', ref, '-a', 'github-copilot'], cwd);
+        }
       }
 
       await relocateSkills(cwd);
     }
   }
 
-  // 4. Offer freeform catch-all
+  // Offer freeform catch-all
   const { freeform } = await prompts({
     type: 'confirm',
     name: 'freeform',
@@ -209,7 +304,100 @@ 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(awesomeRecs, skillsShRecs, 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 (awesomeRecs.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 awesomeRecs) {
+      const typeTag = kleur.dim(`[${r.type}]`);
+      log.raw(`    ${kleur.green('✓')} ${pad(r.name, 28)} ${pad(r.desc, 32)} ${typeTag}`);
+    }
+  }
+
+  if (skillsShRecs.length > 0) {
+    log.raw('');
+    log.raw(kleur.yellow('  ◆ Source: skills.sh') + kleur.dim('  (skills.sh registry)'));
+    log.raw(kleur.dim('  ─────────────────────────────────────────────────────────'));
+    for (const r of skillsShRecs) {
+      log.raw(`    ${kleur.green('✓')} ${pad(r.skill, 28)} ${kleur.dim(r.repo)}`);
+    }
+  }
+
+  log.raw('');
+}
+
+/** Fallback when skills CLI is unavailable — show awesome-copilot recs as copy-paste commands */
+async function showAwesomeCopilotOnly(answers) {
+  const recs = buildAwesomeRecommendations(answers);
+  if (recs.length === 0) return;
+
+  log.raw('');
+  log.info('Cannot install skills automatically, but here are recommendations:');
+  displayHeroRecommendations(recs, [], answers);
+  log.raw(kleur.dim('  Install manually in VS Code Chat:'));
+  for (const r of recs) {
+    log.raw(`    ${kleur.white(`copilot plugin install awesome-copilot@${r.name}`)}`);
+  }
+  log.raw('');
+  printBreadcrumbs();
+}
+
+// ── 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('  │') + '  Install the awesome-copilot suggestion skill:                   ' + kleur.bold().green('│'));
+  log.raw(kleur.bold().green('  │') + kleur.white('    copilot plugin install awesome-copilot@suggest              ') + 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('');
+}
+
+// ── Awesome-copilot recommendation builder ────────────────────────────
+
+function buildAwesomeRecommendations(a) {
+  const stackLower = (a.stack || []).map((s) => s.toLowerCase());
+  const fwLower = (a.frameworks || []).map((f) => f.toLowerCase());
+  const all = [...stackLower, ...fwLower];
+  const seen = new Set();
+  const out = [];
+
+  for (const entry of AWESOME_CATALOG) {
+    const matches = entry.terms.includes('*') || entry.terms.some((t) => all.some((s) => s.includes(t)));
+    if (!matches) continue;
+    if (seen.has(entry.name)) continue;
+    seen.add(entry.name);
+    out.push({ name: entry.name, desc: entry.desc, type: entry.type, source: entry.source });
+  }
+  return out;
 }
 
 // ── Relocation ─────────────────────────────────────────────────────────
@@ -330,3 +518,44 @@ function runInteractive(cmd, args, cwd) {
     });
   });
 }
+
+/** Run skills CLI, capture stdout/stderr while echoing to the terminal. */
+function runSkillsCapture(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', () => resolve(output));
+    proc.on('error', (err) => {
+      log.warn(`Could not launch \`${cmd} ${args.join(' ')}\`: ${err.message}`);
+      resolve('');
+    });
+  });
+}
+
+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
@@ -54,6 +63,10 @@ Before writing code, read (if they exist):
 
 Before finishing, if any implementation choice was made (library selection, pattern choice, API approach), append an entry to `decisions.md` using the format in that file. Skip silently if no decisions were made.
 
+## README.md (MANDATORY)
+
+After any session that adds, changes, or removes user-facing functionality, update `README.md` at the project root. The README must contain at minimum: project name & one-liner, **copy-paste quickstart commands** (install deps + run), usage notes, and tech stack. If `README.md` does not exist, create it as the FIRST file before any other work. A new developer must go from clone → running app in < 2 minutes.
+
 ## History (MANDATORY)
 
 Before finishing, append at least one bullet to `histories/coder.md` below the `<!-- Append entries below this line -->` marker. Record: build quirks, API gotchas, pattern preferences, file structure observations, test insights. Format: `- YYYY-MM-DD: <learning>`. Skip only if the session had zero meaningful work.

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

package/templates/.github/copilot-instructions.md.tmpl

@@ -23,6 +23,18 @@
 - Read `PROJECT.md`, `STATE.md`, and `decisions.md` on entry.
 - Before finishing: update `decisions.md` if any choice was made, update your `histories/<agent>.md` with at least one learning.
 
+# README.md (MANDATORY)
+- The project MUST have a `README.md` at the root at all times.
+- After any session that adds, changes, or removes user-facing functionality, update `README.md`.
+- The README must always contain at minimum:
+  1. **Project name & one-liner** — what this is.
+  2. **Quickstart** — exact commands to install dependencies and run the project locally (copy-paste ready, no placeholders).
+  3. **Usage** — how to use the main features.
+  4. **Tech stack** — languages, frameworks, key libraries.
+- Keep it concise and user-friendly. A new developer should go from clone → running app in under 2 minutes.
+- If the README does not exist yet, create it as the FIRST file before any other work.
+- If unsure about run commands, inspect `package.json` scripts, `Makefile`, `Dockerfile`, or equivalent.
+
 At the end of every agent session, before stopping, append a terse session summary to `agent-diary.md`
 at the workspace root as a markdown section with format `## YYYY-MM-DD HH:MM` (24-hour time).
 Include: 2-5 sentence summary of what was accomplished, include model used.

package/templates/PROJECT.md.tmpl

@@ -12,6 +12,11 @@
 ## Frameworks / Key Libraries
 - {{FRAMEWORKS}}
 
+## Quickstart
+```bash
+{{QUICKSTART}}
+```
+
 ## Hard Constraints
 {{CONSTRAINTS}}