azclaude-copilot 0.7.11 → 0.7.12

package/.claude-plugin/marketplace.json

@@ -8,8 +8,8 @@
   "plugins": [
     {
       "name": "azclaude",
-      "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 40 commands, 10 auto-invoked skills, 15 specialized agents, 5 hooks, a real-time pipeline visualizer, and a persistent memory system — in one command.\n\nKey features:\n• Memory across sessions — goals.md + checkpoints injected automatically before every session\n• Self-improving loop — /reflect fixes stale CLAUDE.md rules, /reflexes learns from tool-use patterns, /evolve creates agents from git evidence\n• Autonomous copilot mode — /copilot runs a three-tier team (orchestrator → problem-architect → milestone-builder) across sessions until the product ships\n• Spec-driven workflow — /constitute writes project rules, /spec writes structured ACs, /analyze detects plan drift and ghost milestones, /blueprint traces every milestone to a spec\n• Security layer — 111-rule environment scan (/sentinel), pre-write secret blocking, pre-ship credential audit\n• Progressive levels 0–10 — start with CLAUDE.md, grow into multi-agent pipelines and self-evolving environments\n• Zero dependencies — no npm packages, no external APIs, no vector databases. Plain markdown files and Claude Code's native architecture.\n• Smart install — npx azclaude-copilot@latest auto-detects first install vs upgrade vs verify. Context-aware onboarding shows the right next command for your project state.\n\nExample use cases:\n• /setup — scan an existing project, detect stack + domain + scale, fill CLAUDE.md, generate project-specific skills and agents automatically\n• /copilot \"Build a compliance SaaS with trilingual support\" — walk away, come back to working code across multiple sessions\n• /sentinel — run a scored security audit (0–100, grade A–F) across hooks, permissions, MCP servers, agent configs, and secrets\n• /evolve — detect gaps in the environment, generate new skills and agents from git co-change evidence, report score delta (e.g. 42/100 → 68/100)\n• /constitute — write your project's constitution (non-negotiables, architectural commitments, definition of done) — gates all future AI actions\n• /analyze — cross-artifact consistency check: ghost milestones, spec vs. code drift, unplanned commits\n• /reflect — find stale, missing, or contradicting rules in CLAUDE.md and propose exact fixes\n• /debate \"REST vs GraphQL for this project\" — adversarial evidence-based decision with order-independent scoring, logged to decisions.md",
-      "version": "0.7.11",
+      "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 42 commands, 10 auto-invoked skills, 15 specialized agents, 5 hooks, a real-time pipeline visualizer, and a persistent memory system — in one command.\n\nKey features:\n• Memory across sessions — goals.md + checkpoints injected automatically before every session\n• Self-improving loop — /reflect fixes stale CLAUDE.md rules, /reflexes learns from tool-use patterns, /evolve creates agents from git evidence\n• Autonomous copilot mode — /copilot runs a three-tier team (orchestrator → problem-architect → milestone-builder) across sessions until the product ships\n• Spec-driven workflow — /constitute writes project rules, /spec writes structured ACs, /analyze detects plan drift and ghost milestones, /blueprint traces every milestone to a spec\n• Security layer — 111-rule environment scan (/sentinel), pre-write secret blocking, pre-ship credential audit\n• Progressive levels 0–10 — start with CLAUDE.md, grow into multi-agent pipelines and self-evolving environments\n• Zero dependencies — no npm packages, no external APIs, no vector databases. Plain markdown files and Claude Code's native architecture.\n• Smart install — npx azclaude-copilot@latest auto-detects first install vs upgrade vs verify. Context-aware onboarding shows the right next command for your project state.\n\nExample use cases:\n• /setup — scan an existing project, detect stack + domain + scale, fill CLAUDE.md, generate project-specific skills and agents automatically\n• /copilot \"Build a compliance SaaS with trilingual support\" — walk away, come back to working code across multiple sessions\n• /sentinel — run a scored security audit (0–100, grade A–F) across hooks, permissions, MCP servers, agent configs, and secrets\n• /evolve — detect gaps in the environment, generate new skills and agents from git co-change evidence, report score delta (e.g. 42/100 → 68/100)\n• /constitute — write your project's constitution (non-negotiables, architectural commitments, definition of done) — gates all future AI actions\n• /analyze — cross-artifact consistency check: ghost milestones, spec vs. code drift, unplanned commits\n• /reflect — find stale, missing, or contradicting rules in CLAUDE.md and propose exact fixes\n• /debate \"REST vs GraphQL for this project\" — adversarial evidence-based decision with order-independent scoring, logged to decisions.md",
+      "version": "0.7.12",
       "source": {
         "source": "github",
         "repo": "haytamAroui/AZ-CLAUDE-COPILOT",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "azclaude",
-  "version": "0.7.11",
-  "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 40 commands, 10 auto-invoked skills, 15 specialized agents, 5 hooks, a real-time pipeline visualizer, and a persistent memory system — in one command.\n\nKey features:\n• Memory across sessions — goals.md + checkpoints injected automatically before every session\n• Self-improving loop — /reflect fixes stale CLAUDE.md rules, /reflexes learns from tool-use patterns, /evolve creates agents from git evidence\n• Autonomous copilot mode — /copilot runs a three-tier team (orchestrator → problem-architect → milestone-builder) across sessions until the product ships\n• Spec-driven workflow — /constitute writes project rules, /spec writes structured ACs, /analyze detects plan drift and ghost milestones, /blueprint traces every milestone to a spec\n• Security layer — 111-rule environment scan (/sentinel), pre-write secret blocking, pre-ship credential audit\n• Progressive levels 0–10 — start with CLAUDE.md, grow into multi-agent pipelines and self-evolving environments\n• Zero dependencies — no npm packages, no external APIs, no vector databases. Plain markdown files and Claude Code's native architecture.\n• Smart install — npx azclaude-copilot@latest auto-detects first install vs upgrade vs verify. Context-aware onboarding shows the right next command for your project state.\n\nExample use cases:\n• /setup — scan an existing project, detect stack + domain + scale, fill CLAUDE.md, generate project-specific skills and agents automatically\n• /copilot \"Build a compliance SaaS with trilingual support\" — walk away, come back to working code across multiple sessions\n• /sentinel — run a scored security audit (0–100, grade A–F) across hooks, permissions, MCP servers, agent configs, and secrets\n• /evolve — detect gaps in the environment, generate new skills and agents from git co-change evidence, report score delta (e.g. 42/100 → 68/100)\n• /constitute — write your project's constitution (non-negotiables, architectural commitments, definition of done) — gates all future AI actions\n• /analyze — cross-artifact consistency check: ghost milestones, spec vs. code drift, unplanned commits\n• /reflect — find stale, missing, or contradicting rules in CLAUDE.md and propose exact fixes\n• /debate \"REST vs GraphQL for this project\" — adversarial evidence-based decision with order-independent scoring, logged to decisions.md",
+  "version": "0.7.12",
+  "description": "AZCLAUDE is a complete AI coding environment for Claude Code. It installs 42 commands, 10 auto-invoked skills, 15 specialized agents, 5 hooks, a real-time pipeline visualizer, and a persistent memory system — in one command.\n\nKey features:\n• Memory across sessions — goals.md + checkpoints injected automatically before every session\n• Self-improving loop — /reflect fixes stale CLAUDE.md rules, /reflexes learns from tool-use patterns, /evolve creates agents from git evidence\n• Autonomous copilot mode — /copilot runs a three-tier team (orchestrator → problem-architect → milestone-builder) across sessions until the product ships\n• Spec-driven workflow — /constitute writes project rules, /spec writes structured ACs, /analyze detects plan drift and ghost milestones, /blueprint traces every milestone to a spec\n• Security layer — 111-rule environment scan (/sentinel), pre-write secret blocking, pre-ship credential audit\n• Progressive levels 0–10 — start with CLAUDE.md, grow into multi-agent pipelines and self-evolving environments\n• Zero dependencies — no npm packages, no external APIs, no vector databases. Plain markdown files and Claude Code's native architecture.\n• Smart install — npx azclaude-copilot@latest auto-detects first install vs upgrade vs verify. Context-aware onboarding shows the right next command for your project state.\n\nExample use cases:\n• /setup — scan an existing project, detect stack + domain + scale, fill CLAUDE.md, generate project-specific skills and agents automatically\n• /copilot \"Build a compliance SaaS with trilingual support\" — walk away, come back to working code across multiple sessions\n• /sentinel — run a scored security audit (0–100, grade A–F) across hooks, permissions, MCP servers, agent configs, and secrets\n• /evolve — detect gaps in the environment, generate new skills and agents from git co-change evidence, report score delta (e.g. 42/100 → 68/100)\n• /constitute — write your project's constitution (non-negotiables, architectural commitments, definition of done) — gates all future AI actions\n• /analyze — cross-artifact consistency check: ghost milestones, spec vs. code drift, unplanned commits\n• /reflect — find stale, missing, or contradicting rules in CLAUDE.md and propose exact fixes\n• /debate \"REST vs GraphQL for this project\" — adversarial evidence-based decision with order-independent scoring, logged to decisions.md",
   "author": {
     "name": "haytamAroui",
     "url": "https://github.com/haytamAroui"

package/README.md

@@ -110,7 +110,7 @@ npx azclaude-copilot@latest
 
 One command, no flags. Auto-detects whether this is a fresh install or an upgrade:
 
-- **First time** → full install (40 commands, 5 hooks, 15 agents, 10 skills, memory, reflexes). Creates folders, instructions, and hooks — **no manual setup required.**
+- **First time** → full install (42 commands, 5 hooks, 15 agents, 10 skills, memory, reflexes). Creates folders, instructions, and hooks — **no manual setup required.**
 - **Already installed, older version** → auto-upgrades everything to latest templates
 - **Already up to date** → verifies, no overwrites
 
@@ -123,7 +123,7 @@ npx azclaude-copilot@latest doctor   # 32 checks — verify everything is wired
 
 ## What You Get
 
-**40 commands** · **10 auto-invoked skills** · **15 agents** · **5 hooks** · **memory across sessions** · **learned reflexes** · **self-evolving environment**
+**42 commands** · **10 auto-invoked skills** · **15 agents** · **5 hooks** · **memory across sessions** · **learned reflexes** · **self-evolving environment**
 
 ```
 .claude/
@@ -272,7 +272,7 @@ Claude Code
   │   └── stop.js         → Session cleanup, friction logging
   │
   └── Markdown files (capability — Claude reads natively, zero overhead)
-      ├── 40 commands     → Claude reads the .md, follows instructions
+      ├── 42 commands     → Claude reads the .md, follows instructions
       ├── 15 agents       → Claude spawns as subagents with Task tool
       ├── 10 skills       → Auto-invoked when relevant context detected
       ├── 48 capabilities → Lazy-loaded via manifest.md (~100 tokens overhead)
@@ -637,11 +637,11 @@ AZCLAUDE is a lazy-loaded environment of 48 capability modules. It only loads wh
 
 ## Verified
 
-1990 tests. Every template, command, capability, agent, hook, and CLI feature verified.
+1996 tests. Every template, command, capability, agent, hook, and CLI feature verified.
 
 ```bash
 bash tests/test-features.sh
-# Results: 1990 passed, 0 failed, 1990 total
+# Results: 1996 passed, 0 failed, 1996 total
 ```
 
 ---

package/bin/cli.js

@@ -8,7 +8,7 @@ const { execSync }  = require('child_process');
 
 const TEMPLATE_DIR = path.join(__dirname, '..', 'templates');
 const CORE_COMMANDS     = ['setup', 'fix', 'add', 'audit', 'test', 'blueprint', 'ship', 'pulse', 'explain', 'snapshot', 'persist'];
-const EXTENDED_COMMANDS = ['dream', 'refactor', 'doc', 'loop', 'migrate', 'deps', 'find', 'create', 'reflect', 'hookify', 'sentinel', 'clarify', 'spec', 'analyze', 'constitute', 'tasks', 'issues', 'driven', 'mcp', 'verify', 'inoculate', 'ghost-test', 'visualize'];
+const EXTENDED_COMMANDS = ['dream', 'refactor', 'doc', 'loop', 'migrate', 'deps', 'find', 'create', 'reflect', 'hookify', 'sentinel', 'clarify', 'spec', 'analyze', 'constitute', 'tasks', 'issues', 'driven', 'mcp', 'verify', 'inoculate', 'ghost-test', 'visualize', 'kill', 'run'];
 const ADVANCED_COMMANDS = ['evolve', 'debate', 'level-up', 'copilot', 'reflexes', 'parallel'];
 const COMMANDS          = [...CORE_COMMANDS, ...EXTENDED_COMMANDS, ...ADVANCED_COMMANDS];
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "azclaude-copilot",
-  "version": "0.7.11",
-  "description": "AI coding environment — 40 commands, 10 skills, 15 agents, real-time visualizer, memory, reflexes, evolution. Install: npx azclaude-copilot@latest, then open Claude Code.",
+  "version": "0.7.12",
+  "description": "AI coding environment — 42 commands, 10 skills, 15 agents, real-time visualizer, memory, reflexes, evolution. Install: npx azclaude-copilot@latest, then open Claude Code.",
   "bin": {
     "azclaude": "bin/cli.js",
     "azclaude-copilot": "bin/copilot.js"

package/templates/agents/orchestrator.md

@@ -208,21 +208,23 @@ Load `capabilities/shared/context-relay.md` for relay protocol and role-based fi
 4. If problem-architect returned a `## Relay` section, include it in the builder prompt as-is
 5. **Skill consistency** — collect the UNION of all skills from all Team Specs in this wave. Every agent in the wave loads the SAME skill set (not just its own). This ensures consistent patterns across parallel agents.
 6. **Include Verify commands** from each Team Spec in the agent prompt — the builder uses these in its exit gate
-7. Spawn each builder via Task with `isolation: "worktree"` in the same message (true parallel)
-8. Include worktree rules + **test scope** (`Test scope: {test-dir}`) in every parallel prompt
-9. **Merge-on-complete**: as each agent reports done, merge its branch immediately (don't wait for all)
-7. After each merge: check if newly-unblocked milestones exist → dispatch them immediately
-8. If `max_parallel <= 3` or merge conflicts detected: fall back to batch-merge (wait for all, then merge)
+7. **Model routing** — read `Model Recommendation` from each Team Spec. Pass it as `model: "{value}"` on the Task/Agent call. If absent, fall back to the agent's frontmatter `model:` field. Model selection varies per milestone — always use the actual recommendation, not a hardcoded assumption.
+8. Spawn each builder via Task with `isolation: "worktree"` and `model: "{from Team Spec}"` in the same message (true parallel)
+9. Include worktree rules + **test scope** (`Test scope: {test-dir}`) in every parallel prompt
+10. **Merge-on-complete**: as each agent reports done, merge its branch immediately (don't wait for all)
+11. After each merge: check if newly-unblocked milestones exist → dispatch them immediately
+12. If `max_parallel <= 3` or merge conflicts detected: fall back to batch-merge (wait for all, then merge)
 
 **Sequential dispatch (single milestone OR overlapping files):**
 
 Load `capabilities/shared/context-inoculation.md` and prepend its Required Preamble to the agent prompt below.
 Load `capabilities/shared/context-relay.md` for relay protocol and size limits.
 
-Spawn milestone-builder via Task with fully packaged context:
+Spawn milestone-builder via Task with `model: "{Model Recommendation from Team Spec}"` and fully packaged context:
 
 ```
 Task: Implement Milestone {N} — {title}
+Model: {from Team Spec — opus|sonnet|haiku, default sonnet}
 
 Agent role: {agent-name from spec} (owns {directories})
 Skills to activate: {skill list from spec}

package/templates/agents/problem-architect.md

@@ -180,6 +180,15 @@ If YES: topic = {what orchestrator must /debate before dispatching}
 SIMPLE (< 3 files) | MEDIUM (3-8 files) | COMPLEX (8+ files)
 COMPLEX → orchestrator gives builder 3 fix attempts instead of 2
 
+### Model Recommendation
+{opus | sonnet | haiku}
+Decision logic (use the FIRST matching rule):
+1. Read-only validation, checklist matching, constitution check → **haiku**
+2. Structural Decision: YES, OR Complexity: COMPLEX + touches schemas/APIs/auth → **opus**
+3. Everything else (standard implementation, follows patterns) → **sonnet**
+The orchestrator passes this as `model:` when spawning the agent via Task.
+If omitted, the orchestrator falls back to the agent's frontmatter `model:` field.
+
 ### Verify
 Read CLAUDE.md `## Verify` field for the project's commands. Scope them to this milestone:
 - Quick: `{Tier 1 command}` — static check, MANDATORY before done

package/templates/commands/kill.md

@@ -0,0 +1,128 @@
+---
+name: kill
+description: >
+  Kill all running dev/testing servers on common development ports.
+  Triggers on: "kill servers", "kill ports", "free ports", "kill dev server",
+  "port still in use", "EADDRINUSE", "address already in use", "stop all servers",
+  "kill background processes", "clean up ports".
+  Safe by design — only kills processes bound to TCP ports, never MCP servers (stdio, no ports).
+argument-hint: "[port number | --all (default) | --ports 3000,8080]"
+disable-model-invocation: false
+allowed-tools: Bash, Read, Glob
+---
+
+# /kill — Kill Dev Servers
+
+$ARGUMENTS
+
+---
+
+## Safety guarantee
+
+Killing by TCP port is inherently MCP-safe.
+MCP servers use stdio transport — they hold **no TCP ports**.
+Any process on a TCP port is a dev/test server, not Claude infrastructure.
+
+---
+
+## Step 1 — Parse target ports
+
+**If $ARGUMENTS contains a port number** (e.g., `/kill 3000`):
+→ Kill only that specific port. Skip to Step 3.
+
+**If $ARGUMENTS is `--ports <list>`** (e.g., `/kill --ports 3000,5173`):
+→ Parse the comma-separated list. Skip to Step 3.
+
+**Default (`--all` or no argument)**:
+→ Target the full dev port list below. Continue to Step 2.
+
+### Default dev port list
+```
+3000  3001  3002  3003  4000  4200  4321
+5000  5001  5173  5174  6006  7000  8000
+8001  8080  8081  8888  9000  9001  9229
+```
+
+> Note: 9229 is Node.js debugger. Kill only if you're not actively debugging.
+
+---
+
+## Step 2 — Detect which ports are actually in use
+
+**Unix/macOS:**
+```bash
+for port in 3000 3001 3002 3003 4000 4200 4321 5000 5001 5173 5174 6006 7000 8000 8001 8080 8081 8888 9000 9001 9229; do
+  pid=$(lsof -ti tcp:$port 2>/dev/null)
+  if [ -n "$pid" ]; then
+    echo "  PORT $port → PID $pid ($(ps -p $pid -o comm= 2>/dev/null))"
+  fi
+done
+```
+
+**Windows:**
+```bash
+for port in 3000 3001 3002 3003 4000 4200 4321 5000 5001 5173 5174 6006 7000 8000 8001 8080 8081 8888 9000 9001 9229; do
+  result=$(netstat -ano 2>/dev/null | grep ":$port " | grep LISTENING | awk '{print $5}' | head -1)
+  if [ -n "$result" ]; then
+    echo "  PORT $port → PID $result"
+  fi
+done
+```
+
+Print summary of occupied ports. If none found: print `No dev servers found on standard ports.` and stop.
+
+---
+
+## Step 3 — Kill strategy
+
+### Primary (cross-platform, requires Node):
+```bash
+npx --yes kill-port <PORTS>
+```
+Example: `npx --yes kill-port 3000 5173 8080`
+
+This is safe, silent on ports that are already free, and exits 0 on success.
+
+### Fallback — Unix/macOS (if npx not available):
+```bash
+for port in <PORTS>; do
+  lsof -ti tcp:$port | xargs -r kill -9 2>/dev/null
+  echo "  Killed port $port"
+done
+```
+
+### Fallback — Windows (if npx not available):
+```bash
+for port in <PORTS>; do
+  pid=$(netstat -ano | findstr ":$port " | grep LISTENING | awk '{print $5}' | head -1)
+  if [ -n "$pid" ]; then
+    taskkill /PID $pid /F
+    echo "  Killed PID $pid on port $port"
+  fi
+done
+```
+
+---
+
+## Step 4 — Verify
+
+After killing, re-run the detection from Step 2.
+
+**Expected output:**
+```
+No dev servers found on standard ports.
+```
+
+If any port is still occupied: report it and its PID. Do not retry — report to user.
+
+---
+
+## Completion rule
+
+Print a summary:
+```
+Killed: ports 3000, 5173
+Still running: (none)
+```
+
+Never say "should be free now." Run the verification and show the output.

package/templates/commands/run.md

@@ -0,0 +1,168 @@
+---
+name: run
+description: >
+  Auto-detect the project tech stack and run the appropriate dev server.
+  Triggers on: "run the server", "start dev server", "run the app", "start the app",
+  "run project", "run dev", "how do I start this", "start this project",
+  "run my app", "launch server", "dev server".
+  Detects: Node.js, Next.js, Nuxt, Vite, Astro, SvelteKit, Remix, Angular,
+  Python (Django, FastAPI, Flask), Rust, Go, Ruby (Rails), PHP (Laravel), Java.
+argument-hint: "[stack override | --port <port> | blank for auto-detect]"
+disable-model-invocation: false
+allowed-tools: Bash, Read, Glob
+---
+
+# /run — Run Dev Server
+
+$ARGUMENTS
+
+---
+
+## Step 1 — Parse arguments
+
+**If $ARGUMENTS contains a stack name** (e.g., `/run django`):
+→ Skip detection, use the named stack's command from the table in Step 3.
+
+**If $ARGUMENTS contains `--port <number>`**:
+→ Append port override to the detected command (e.g., `--port 4000`).
+
+**Default (no arguments)**:
+→ Run auto-detection in Step 2.
+
+---
+
+## Step 2 — Auto-detect stack
+
+Run detection in this **exact priority order** — stop at the first match.
+
+Check with: `ls <file>` or `test -f <file>` (do not read file contents unless needed for sub-detection).
+
+### Priority chain
+
+| Priority | File to check | Stack detected | Step to jump to |
+|----------|--------------|----------------|-----------------|
+| 1 | `package.json` | Node-based — sub-detect framework | Step 2a |
+| 2 | `Cargo.toml` | Rust | Step 3 → Rust |
+| 3 | `go.mod` | Go | Step 3 → Go |
+| 4 | `manage.py` | Django | Step 3 → Django |
+| 5 | `pyproject.toml` | Python (FastAPI/Flask) | Step 2b |
+| 6 | `requirements.txt` | Python generic | Step 3 → Python generic |
+| 7 | `Gemfile` + `config/routes.rb` | Rails | Step 3 → Rails |
+| 8 | `composer.json` + `artisan` | Laravel | Step 3 → Laravel |
+| 9 | `pom.xml` | Maven/Spring Boot | Step 3 → Java/Maven |
+| 10 | `build.gradle` | Gradle/Spring Boot | Step 3 → Java/Gradle |
+| 11 | `pubspec.yaml` | Flutter/Dart | Step 3 → Flutter |
+
+If **no file matches**: print `Could not detect stack. Run: /run <stack>` and list available stacks. Stop.
+
+---
+
+### Step 2a — Node sub-detection (package.json found)
+
+**First: check if `"dev"` script exists in package.json:**
+```bash
+node -e "const p=require('./package.json'); console.log(p.scripts && p.scripts.dev || '')"
+```
+If non-empty → use `npm run dev` (or `yarn dev` / `pnpm dev` based on lock file presence). Jump to Step 4.
+
+**If no `"dev"` script, check dependencies for framework:**
+Read `package.json` dependencies + devDependencies and check for these keys (first match wins):
+
+| Dependency key | Framework | Command | Default port |
+|---------------|-----------|---------|--------------|
+| `"next"` | Next.js | `npm run dev` | 3000 |
+| `"nuxt"` | Nuxt | `npm run dev` | 3000 |
+| `"@astrojs/core"` or `"astro"` | Astro | `npm run dev` | 4321 |
+| `"@sveltejs/kit"` | SvelteKit | `npm run dev` | 5173 |
+| `"vite"` | Vite | `npm run dev` | 5173 |
+| `"@remix-run/react"` | Remix | `npm run dev` | 3000 |
+| `"@angular/core"` | Angular | `ng serve` | 4200 |
+| `"express"` or `"fastify"` or `"hono"` | Node server | `node index.js` or `node src/index.js` | user-defined |
+| (none of the above) | Node generic | `npm start` | 3000 |
+
+**If multiple frameworks detected** (e.g., monorepo): list all candidates and ask:
+```
+Multiple frameworks detected:
+  1. Next.js (packages/web)
+  2. Express (packages/api)
+Which would you like to run? (1/2)
+```
+
+Jump to Step 4.
+
+---
+
+### Step 2b — Python sub-detection (pyproject.toml found, no manage.py)
+
+Read `pyproject.toml` and check `[project.dependencies]` or `[tool.poetry.dependencies]`:
+
+| Dependency | Command |
+|-----------|---------|
+| `fastapi` | `uvicorn main:app --reload` |
+| `flask` | `flask run` |
+| `starlette` | `uvicorn main:app --reload` |
+| (none) | `python -m <package_name>` |
+
+Jump to Step 3.
+
+---
+
+## Step 3 — Command table
+
+| Stack | Command | Default port |
+|-------|---------|--------------|
+| Rust | `cargo run` | user-defined |
+| Go | `go run .` | user-defined |
+| Django | `python manage.py runserver` | 8000 |
+| FastAPI | `uvicorn main:app --reload` | 8000 |
+| Flask | `flask run` | 5000 |
+| Python generic | `python app.py` | user-defined |
+| Rails | `bundle exec rails server` | 3000 |
+| Laravel | `php artisan serve` | 8000 |
+| Java/Maven | `mvn spring-boot:run` | 8080 |
+| Java/Gradle | `./gradlew bootRun` | 8080 |
+| Flutter | `flutter run` | n/a |
+
+---
+
+## Step 4 — Pre-flight check
+
+Before running, check if the target port is already occupied:
+
+**Unix/macOS:** `lsof -ti tcp:<PORT>`
+**Windows:** `netstat -ano | findstr ":<PORT> " | grep LISTENING`
+
+If occupied: print
+```
+Port <PORT> is already in use. Run /kill <PORT> first, then retry.
+```
+Stop. Do not force-kill automatically — user decides.
+
+---
+
+## Step 5 — Run
+
+Print the detected stack and command before executing:
+```
+Detected: Next.js
+Command:  npm run dev
+Port:     3000
+```
+
+Then run the command. Stream output to the terminal.
+
+If the process exits with a non-zero code within 5 seconds: print the last 20 lines of output and stop. Do not retry automatically.
+
+---
+
+## Completion rule
+
+The server is running when output contains a "ready" or "listening" line (e.g., `ready on http://localhost:3000`, `Uvicorn running on http://0.0.0.0:8000`).
+
+Print:
+```
+Server running: http://localhost:<PORT>
+Stack: <detected stack>
+```
+
+Never say "it should be running." Show the actual server output line.