@zaganjade/pi-multi-skill 1.0.0 → 1.3.1

package/README.md

@@ -1,48 +1,484 @@
 # pi-multi-skill
 
-Load multiple skills at once in [pi](https://github.com/earendil-works/pi-mono) via the `/skills` command.
+Load multiple skills at once in [pi](https://github.com/earendil-works/pi-mono) via the `/skills` command — with preset bundles, token-efficient load modes, BMAD auto-routing, and Claude Code-style orchestration.
+
+**Version 1.3.0** — skill chaining, bundle presets, conflict resolution, parallel dispatch, activation stats, `/skills-last`, `/skills-setup`, and bundle attribution in pi-usage.
+
+---
+
+## 🚀 Install
+
+> ⚠️ **Use `pi install` — NOT `npm install`.**
+> Plain `npm install` only drops files in `node_modules`. Pi does **not** scan
+> that folder, so the package is **never detected** and `/skills` won't appear.
+> You must register it with `pi install` so it lands in `"packages"` in
+> `~/.pi/agent/settings.json`.
+
+```bash
+pi install npm:@zaganjade/pi-multi-skill
+```
+
+Then inside pi:
+
+```
+/reload
+```
+
+Verify it loaded:
+
+```bash
+pi list          # should show npm:@zaganjade/pi-multi-skill
+```
+
+Type `/` — `/skills` should appear in slash autocomplete.
+
+**Don't do this** (common mistake — package installs but pi ignores it):
+
+```bash
+npm install -g @zaganjade/pi-multi-skill   # ❌ pi will not detect this
+```
+
+---
 
 ## Why?
 
-Pi's built-in `/skill:name` only loads one skill at a time. When you need multiple skills working together (e.g. `frontend-design` + `motion-design` + `test-driven-development`), you'd have to invoke them one by one. This extension lets you chain them in a single command.
+Pi's built-in `/skill:name` loads one skill at a time. When you need several skills working together (e.g. `bmad-master` + `analyst` + `pm`, or `systematic-debugging` + `test-driven-development`), invoking them one by one is slow and easy to forget.
+
+This extension chains skills in a **single command** with:
+
+- Preset **bundles** (`@bmad-planning`, `@debug`, …)
+- **Smart ordering** (process → planning → implementation)
+- **Load modes** to control token cost (`--meta`, `--lazy`, `--full`)
+- **Universal discovery** including Claude Code plugin skills and Cursor skills
+- **BMAD `--auto`** phase routing from workflow status files
+
+---
+
+## Quick start
+
+```
+/skills @debug --meta Fix the failing auth tests
+/skills @bmad-planning --meta Buat PRD untuk fitur notifikasi
+/skills bmad-master,developer Implement user story US-042
+/skills bmad-master /workflow-status
+/skills @bmad-planning --auto
+/skills @cc-feature --parallel Build API | Write tests | Update docs
+/skills-stats                         → activation statistics
+/skills-last                          → repeat last activation
+/skills-setup                         → bundle install guide
+/skills                              → help + list all skills & bundles
+```
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/skills` | Chain skills/bundles — flags, embedded commands, `--auto`, `--parallel` |
+| `/skills-stats` | Activation statistics (`~/.pi/agent/multi-skill-stats.json`) |
+| `/skills-last` | Repeat last activation (optional `--meta` / `--lazy` / `--full` / `--parallel`) |
+| `/skills-setup` | Bundle readiness on this machine + BMAD/Superpowers install guide |
+
+---
+
+## Features
+
+### v1.3.0
+
+| Feature | Description |
+|---------|-------------|
+| **`/skills-last`** | Replay the previous `/skills` line; flags can override load mode |
+| **BMAD status inject** | `<bmad_status>` preloaded for `/workflow-status`, `--auto`, `bmad-master` |
+| **Bundle attribution** | Sets `bundles="@name"` on `<manually_attached_skills>` for pi-usage tracking |
+| **`/skills-setup`** | Reports which preset bundles are usable + how to install missing skills |
+
+### Skill chaining
+
+| Feature | Description |
+|---------|-------------|
+| **Comma-separated skills** | `/skills skill1,skill2,skill3 [instructions]` |
+| **Preset bundles** | `/skills @bundle-name` expands to a curated skill set |
+| **Mixed input** | Combine bundles and individual skills: `/skills @debug,frontend-design` |
+| **Inline instructions** | Text after the skill list is passed inside `<user_query>` |
+| **Legacy formats** | `/skills:a,b` (colon + comma) and `/skill:a+b` (colon + plus) still work |
+
+### Load modes (token efficiency)
+
+| Flag | What gets sent | Best for |
+|------|----------------|----------|
+| `--meta` | Name, description, available commands only | Exploration, planning, large bundles |
+| `--lazy` | Short intro + commands + “load references on demand” | Implementation workflows |
+| `--full` | Complete `SKILL.md` body (default) | Rigid skills (TDD, debugging) |
+
+Bundles can set a default mode (e.g. `@bmad-planning` defaults to `--meta`).
+
+### Smart ordering
+
+Skills are sorted automatically before injection:
+
+1. **Process** — `using-superpowers`, `brainstorming`, `systematic-debugging`, `bmad-master`, …
+2. **Planning** — `analyst`, `pm`, `architect`, `ux-designer`, …
+3. **Implementation** — domain and execution skills
+
+User instructions always take precedence over skill guidance. Skills with conflicting `conflicts_with` frontmatter are deduplicated automatically (lower-priority skill skipped).
+
+### Parallel dispatch (v1.2)
+
+When `--parallel` is used with `pi-subagents` installed, the message includes a `<parallel_dispatch>` block with a ready-to-use JSON template for the `subagent` tool:
+
+```
+/skills @cc-feature --parallel Build API | Write tests | Update docs
+```
+
+Pipe-separated tasks (`|`) become independent parallel subagent jobs. Without `pi-subagents`, a fallback notice prompts sequential execution.
+
+### Skill conflict resolution (v1.2)
+
+Skills can declare `conflicts_with` in frontmatter. After smart ordering, conflicting skills are skipped with an info notification:
+
+```
+Skipped test-driven-development (conflicts with systematic-debugging)
+```
+
+### Per-skill token budget (v1.2)
+
+Skills can set `token_budget: meta|lazy|full` in frontmatter. When a bundle uses `--lazy`, individual skills can still override to `--full` (e.g. rigid TDD/debug skills).
+
+### Activation stats (v1.2)
+
+Every `/skills` activation is recorded to `~/.pi/agent/multi-skill-stats.json`. View with:
+
+```
+/skills-stats
+```
+
+Tracks load modes, top bundles, skills-per-activation buckets, and recent history.
+
+### Command passthrough
+
+Embed a slash command after the skill list — it is wrapped in `<embedded_command>` and the agent runs that workflow after loading the skill:
+
+```
+/skills bmad-master /workflow-status
+/skills developer /dev-story STORY-042
+/skills analyst /product-brief
+```
+
+After typing the skill name and a space, autocomplete suggests commands from the skill's **Available Commands** section (e.g. `/workflow-status`, `/dev-story`).
+
+> **Note:** BMAD commands like `/workflow-status` are **skill workflows** executed by the agent — not separate Pi slash commands. You will see a notification (`Loading bmad-master → /workflow-status`) and the agent turn starts with the skill + embedded command injected.
+
+### BMAD `--auto`
+
+Reads `docs/bmm-workflow-status.yaml` (and `bmad/config.yaml` for project level) and loads skills for the current phase:
+
+| Detected phase | Skills loaded |
+|----------------|---------------|
+| Analysis | bmad-master, analyst |
+| Planning | bmad-master, analyst, pm |
+| Solutioning | bmad-master, architect, ux-designer |
+| Implementation | bmad-master, developer, scrum-master |
 
-## Usage
+```
+/skills --auto
+/skills @bmad-planning --auto
+```
+
+### Universal skill discovery
+
+Skills are found from **all** of these sources (merged, deduplicated by name):
+
+| Source | Path / mechanism |
+|--------|------------------|
+| Pi registered skills | `pi.getCommands()` (`source: "skill"`) |
+| Pi defaults | `~/.pi/agent/skills`, `.pi/skills` |
+| Settings skill paths | `"skills"` array in `~/.pi/agent/settings.json` |
+| Claude Code plugins | `~/.claude/plugins/cache/**/skills/` (Superpowers, etc.) |
+| Cursor skills | `~/.cursor/skills-cursor/` |
 
+This means bundles like `@debug` and `@cc-feature` work even when Superpowers skills live in the Claude plugin cache rather than `~/.claude/skills`.
+
+### Claude Code-style message wrapper
+
+Combined output uses a structured wrapper (similar to Cursor `manually_attached_skills`):
+
+```xml
+<manually_attached_skills count="3">
+  …priority rules…
+  <skill name="…" mode="meta">…</skill>
+  <embedded_command>/workflow-status</embedded_command>
+  <user_query>Your instructions here</user_query>
+</manually_attached_skills>
 ```
-/skills frontend-design,motion-design Create an animated landing page
-/skills test-driven-development,systematic-debugging Fix the failing tests
-/skills                              → show help + list available skills
+
+### Session hints
+
+After each user turn, the extension may suggest a relevant bundle (non-blocking `info` notification):
+
+| Keywords detected | Suggested bundle |
+|-------------------|------------------|
+| failing tests, bug, error | `@debug` |
+| PRD, tech spec | `@bmad-planning` |
+| architecture, API design | `@bmad-solutioning` |
+| implement, user story | `@bmad-build` |
+| new feature, build component | `@cc-feature` |
+
+### Skill registry
+
+On every `session_start`, rebuilds `~/.pi/agent/skill-index.json` with metadata (name, type, module, commands, location) for all discovered skills.
+
+### Deduplication
+
+When combining skills that share content (e.g. multiple skills with `<SUBAGENT-STOP>` or Superpowers skill-check rules), duplicate sections are stripped automatically.
+
+### pi-usage integration
+
+Works with [**pi-usage**](../usage/README.md):
+
+- Every skill in a multi-skill activation appears separately in **Skills**
+- Preset bundles (`@debug`, `@bmad-planning`, …) appear in **Bundles** when `bundles="@name"` is set on the wrapper
+- Tool and plugin breakdowns unchanged — independent characteristics like Claude Code
+
+---
+
+## Preset bundles
+
+Built-in bundles are **optional presets** — they require BMAD and/or Superpowers skills to be installed separately. Run `/skills-setup` to check what's available on your machine.
+
+Expand with `@name`:
+
+| Bundle | Skills | Default mode | Requires |
+|--------|--------|--------------|----------|
+| `@bmad-planning` | bmad-master, analyst, pm | `--meta` | BMAD Method |
+| `@bmad-solutioning` | bmad-master, architect, ux-designer | `--meta` | BMAD Method |
+| `@bmad-build` | bmad-master, developer, scrum-master | `--lazy` | BMAD Method |
+| `@cc-feature` | using-superpowers, brainstorming, … | `--lazy` | Superpowers |
+| `@debug` | systematic-debugging, test-driven-development | `--full` | Superpowers |
+
+Autocomplete shows coverage per bundle, e.g. `(2/3)` or `(0/3 — install required)`.
+
+### Without BMAD or Superpowers
+
+You can still use pi-multi-skill:
+
+```
+/skills frontend-design,motion-design Build landing page
+/skills-setup                    → check bundle status + install guide
 ```
 
-- **Comma-separated** skill names after `/skills`
-- **Optional instructions** after the skill list (passed to the agent alongside the skill content)
-- **Autocomplete** — typing `/skills ` shows all available skills with descriptions, and selecting one appends it with a comma for chaining
+Create your own bundles with **only skills you have**:
 
-### Legacy formats (also supported)
+```json
+{
+  "bundles": {
+    "my-stack": {
+      "description": "Skills I actually installed",
+      "skills": ["frontend-design", "create-rule"],
+      "default_mode": "meta"
+    }
+  }
+}
+```
+
+Save as `~/.pi/agent/skill-bundles.json` then use `/skills @my-stack`.
+
+---
+
+## Custom bundles
+
+Create `~/.pi/agent/skill-bundles.json`, `.pi/skill-bundles.json`, or the YAML equivalents (`skill-bundles.yaml` / `.pi/skill-bundles.yaml`):
 
+```json
+{
+  "bundles": {
+    "my-team-planning": {
+      "description": "Custom team planning workflow",
+      "skills": ["bmad-master", "analyst", "pm"],
+      "order": "process-first",
+      "default_mode": "meta"
+    }
+  }
+}
 ```
-/skills:frontend-design,motion-design [args]   (colon + comma)
-/skill:frontend-design+motion-design [args]    (colon + plus)
+
+YAML format (same fields):
+
+```yaml
+bundles:
+  my-team-planning:
+    description: Custom team planning workflow
+    skills:
+      - bmad-master
+      - analyst
+      - pm
+    order: process-first
+    default_mode: meta
 ```
 
+| Field | Values | Description |
+|-------|--------|-------------|
+| `description` | string | Shown in `/skills` help and autocomplete |
+| `skills` | string[] | Skill names to load when bundle is expanded |
+| `order` | `process-first` · `explicit` · `alpha` | Sort order (default: `process-first`) |
+| `default_mode` | `meta` · `lazy` · `full` | Applied when no `--meta`/`--lazy`/`--full` flag is passed |
+
+See [skill-bundles.example.json](./skill-bundles.example.json) and [skill-bundles.example.yaml](./skill-bundles.example.yaml).
+
+Custom bundles **merge** with built-in presets; same name overrides the preset.
+
+---
+
+## Flags reference
+
+| Flag | Description |
+|------|-------------|
+| `--meta` | Minimal content — name, description, commands |
+| `--lazy` | Summary + on-demand reference loading |
+| `--full` | Full SKILL.md body (default) |
+| `--auto` | BMAD phase detection from workflow status |
+| `--parallel` | Parallel subagent dispatch — pipe-separated tasks: `Task A \| Task B` |
+| `/skills-stats` | Show activation statistics (modes, bundles, recent history) |
+| `/skills-last` | Repeat last `/skills` activation |
+| `/skills-setup` | Bundle prerequisites and install guide |
+
+---
+
 ## Install
 
+Use **`pi install`**, not plain `npm install`. Pi registers packages in `settings.json` under `"packages"` and loads extensions from the `pi.extensions` manifest.
+
+```bash
+pi install npm:@zaganjade/pi-multi-skill
+/reload
+```
+
+Quick test without persisting to settings:
+
+```bash
+pi -e npm:@zaganjade/pi-multi-skill
+```
+
+From GitHub (monorepo):
+
 ```bash
-pi install git:github.com/ZaganJade/pi-multi-skill
+pi install git:github.com/ZaganJade/pi-extension
 ```
 
-Or from a local path:
+Local development:
 
 ```bash
 pi install ./multi-skill
+/reload
+```
+
+Verify:
+
+```bash
+pi list
+# should show: npm:@zaganjade/pi-multi-skill
 ```
 
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `/skills` not in autocomplete | Run `pi install npm:@zaganjade/pi-multi-skill`, then `/reload` |
+| `No skills found for: …` | Ensure skill exists in a discovery path (see table above). Superpowers skills are found via Claude plugin cache automatically. |
+| Bundle skill missing | Run `/skills` with no args — check skill appears in list. Add custom path to `"skills"` in settings if needed. |
+| Installed with `npm install -g` but pi ignores it | Use `pi install npm:@zaganjade/pi-multi-skill` instead |
+| Added `npm:...` to `"extensions"` in settings | Wrong key for npm packages — use `"packages"`, or run `pi install` |
+| Command shows as `/skills:2` | Two copies loaded (local + npm). Remove duplicate from `extensions` or `packages` |
+| Extension listed but disabled | Run `pi config` and enable the extension resource |
+| `--auto` loads wrong skills | Ensure `docs/bmm-workflow-status.yaml` exists and reflects current phase |
+
+---
+
 ## How it works
 
-The extension discovers all available skills via `pi.getCommands()` (covers user-level, project-level, and package-installed skills), reads each selected skill's `SKILL.md`, strips frontmatter, wraps it in `<skill>` blocks, and sends the combined content as a user message to trigger agent processing.
+```mermaid
+flowchart LR
+  CMD["/skills @bundle --meta /cmd"]
+  DISC["discover.ts"]
+  PARSE["parse-args.ts + bundles.ts"]
+  ORDER["metadata.ts sort"]
+  BUILD["build.ts"]
+  SEND["sendUserMessage()"]
 
-## Files
+  CMD --> PARSE --> DISC --> ORDER --> BUILD --> SEND
+```
+
+1. **Parse** — extract skill names, flags, embedded command, instructions
+2. **Expand** — resolve `@bundle` → skill name list; `--auto` → BMAD phase skills
+3. **Discover** — merge skills from pi, settings paths, Claude plugins, Cursor
+4. **Order** — sort by process → planning → implementation priority
+5. **Build** — render each skill in the chosen load mode; deduplicate shared sections
+6. **Send** — inject `<manually_attached_skills>` wrapper via `pi.sendUserMessage()`
+
+---
+
+## Module layout
 
 | File | Purpose |
 |------|---------|
-| `src/index.ts` | Entry point — registers `/skills` command, autocomplete, and input handler |
+| `src/index.ts` | `/skills`, `/skills-stats`, `/skills-last`, `/skills-setup`; events; orchestration |
+| `src/discover.ts` | Universal skill discovery (pi + Claude plugins + Cursor) |
+| `src/bundles.ts` | Built-in presets + user JSON/YAML bundle config |
+| `src/bundle-status.ts` | Bundle readiness assessment + setup report |
+| `src/metadata.ts` | Frontmatter parsing (via pi), priority sorting |
+| `src/build.ts` | Message builder — load modes, deduplication, parallel dispatch, `bundles=` attr |
+| `src/conflicts.ts` | `conflicts_with` resolution |
+| `src/subagents.ts` | pi-subagents detection + `<parallel_dispatch>` template |
+| `src/stats.ts` | Activation tracking → `multi-skill-stats.json` |
+| `src/yaml-bundles.ts` | Minimal YAML parser for bundle config |
+| `src/bmad-auto.ts` | BMAD `--auto` phase routing |
+| `src/bmad-status.ts` | BMAD workflow status block for status/auto/master |
+| `src/completions.ts` | Slash autocomplete for skills, bundles, embedded commands |
+| `src/parse-args.ts` | Flag parsing, embedded command extraction |
+| `src/registry.ts` | `~/.pi/agent/skill-index.json` persistence |
+| `src/suggestions.ts` | Context-aware bundle hints on `turn_end` |
+| `src/types.ts` | Shared TypeScript types |
+| `skill-bundles.example.json` | Example custom bundle config (JSON) |
+| `skill-bundles.example.yaml` | Example custom bundle config (YAML) |
+
+---
+
+## Changelog
+
+### v1.3.0
+
+- `/skills-last` — repeat last activation (optional `--meta`/`--lazy`/`--full`/`--parallel` override)
+- BMAD status pre-inject — `<bmad_status>` block for `/workflow-status`, `--auto`, and `bmad-master`
+- Bundle attribution in pi-usage — `bundles="@name"` on `<manually_attached_skills>`
+
+### v1.2.0
+
+- Skill conflict resolution via `conflicts_with` frontmatter
+- Per-skill `token_budget` override in frontmatter
+- Structured `<parallel_dispatch>` block with JSON template for `pi-subagents`
+- Pipe-separated parallel tasks: `--parallel Task A | Task B`
+- Activation stats (`/skills-stats`, `multi-skill-stats.json`)
+- YAML bundle config (`skill-bundles.yaml`)
+- Richer skill index (pairsWith, conflictsWith, tokenBudget)
+
+### v1.1.0
+
+- Preset bundles (`@bmad-planning`, `@debug`, `@cc-feature`, …)
+- Load modes: `--meta`, `--lazy`, `--full`
+- Smart skill ordering (Superpowers priority)
+- BMAD `--auto` phase routing
+- Command passthrough (`/skills bmad-master /workflow-status`)
+- Universal discovery (Claude plugin cache + Cursor skills)
+- `<manually_attached_skills>` message wrapper
+- Session bundle suggestions on `turn_end`
+- Skill registry (`skill-index.json`)
+- Content deduplication across combined skills
+- Multi-skill attribution in pi-usage
+
+### v1.0.x
+
+- Comma-separated `/skills a,b,c [instructions]`
+- Autocomplete with descriptions
+- Legacy `/skills:` and `/skill:+` formats

package/package.json

@@ -1,10 +1,14 @@
 {
 	"name": "@zaganjade/pi-multi-skill",
-	"version": "1.0.0",
-	"description": "Load multiple skills at once via /skills command. Supports comma-separated skill names with autocomplete and instructions.",
+	"version": "1.3.1",
+	"description": "Chain multiple skills via /skills — bundles (JSON/YAML), load modes, BMAD --auto, /skills-last, /skills-setup, conflict resolution, parallel dispatch, activation stats, bundle attribution for pi-usage.",
+	"type": "module",
 	"keywords": [
 		"pi-package"
 	],
+	"publishConfig": {
+		"access": "public"
+	},
 	"license": "MIT",
 	"author": "ZaganJade <tipstrik81@gmail.com>",
 	"homepage": "https://github.com/ZaganJade/pi-extension/tree/main/multi-skill",
@@ -20,7 +24,9 @@
 	"files": [
 		"src/",
 		"README.md",
-		"LICENSE"
+		"LICENSE",
+		"skill-bundles.example.json",
+		"skill-bundles.example.yaml"
 	],
 	"pi": {
 		"extensions": [

package/skill-bundles.example.json

@@ -0,0 +1,17 @@
+{
+	"bundles": {
+		"my-stack": {
+			"description": "Only skills installed on this machine — no BMAD required",
+			"skills": ["frontend-design", "create-rule"],
+			"order": "explicit",
+			"default_mode": "meta"
+		},
+		"my-team-planning": {
+			"description": "Custom team planning workflow (requires BMAD)",
+			"skills": ["bmad-master", "analyst", "pm"],
+			"order": "process-first",
+			"default_mode": "meta",
+			"requires": "BMAD Method"
+		}
+	}
+}

package/skill-bundles.example.yaml

@@ -0,0 +1,9 @@
+bundles:
+  my-team-planning:
+    description: Custom team planning workflow
+    skills:
+      - bmad-master
+      - analyst
+      - pm
+    order: process-first
+    default_mode: meta

package/src/bmad-auto.ts

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const PHASE_SKILLS: Record<string, string[]> = {
+	analysis: ["bmad-master", "analyst"],
+	planning: ["bmad-master", "analyst", "pm"],
+	solutioning: ["bmad-master", "architect", "ux-designer"],
+	implementation: ["bmad-master", "developer", "scrum-master"],
+};
+
+function readText(path: string): string | null {
+	try {
+		return readFileSync(path, "utf-8");
+	} catch {
+		return null;
+	}
+}
+
+function workflowStatus(content: string, key: string): string | null {
+	const patterns = [
+		new RegExp(`${key}:\\s*\\n[\\s\\S]*?status:\\s*([\\w-]+)`, "i"),
+		new RegExp(`${key}:[\\s\\S]*?status:\\s*([\\w\\s-]+)`, "i"),
+	];
+	for (const re of patterns) {
+		const match = content.match(re);
+		if (match) return match[1].trim().toLowerCase().replace(/\s+/g, "-");
+	}
+	return null;
+}
+
+function isIncomplete(status: string | null): boolean {
+	if (!status) return true;
+	return /not-started|not_started|pending|required|in-progress|in_progress|started/.test(
+		status,
+	);
+}
+
+function detectPhase(content: string): keyof typeof PHASE_SKILLS {
+	const checks: Array<[string, keyof typeof PHASE_SKILLS]> = [
+		["product-brief", "analysis"],
+		["brainstorm", "analysis"],
+		["research", "analysis"],
+		["prd", "planning"],
+		["tech-spec", "planning"],
+		["tech_spec", "planning"],
+		["architecture", "solutioning"],
+		["ux-design", "solutioning"],
+		["sprint-planning", "implementation"],
+		["dev-story", "implementation"],
+		["create-story", "implementation"],
+	];
+
+	for (const [key, phase] of checks) {
+		if (isIncomplete(workflowStatus(content, key))) return phase;
+	}
+
+	if (/implementation|phase:\s*4/i.test(content)) return "implementation";
+	if (/solutioning|phase:\s*3/i.test(content)) return "solutioning";
+	if (/planning|phase:\s*2/i.test(content)) return "planning";
+	return "analysis";
+}
+
+function projectLevel(cwd: string): number {
+	const configPath = join(cwd, "bmad", "config.yaml");
+	const content = readText(configPath);
+	if (!content) return 1;
+	const match = content.match(/project_level:\s*(\d)/i);
+	return match ? Number.parseInt(match[1], 10) : 1;
+}
+
+export function resolveBmadAutoSkills(cwd: string): string[] {
+	const statusPath = join(cwd, "docs", "bmm-workflow-status.yaml");
+	const content = readText(statusPath);
+
+	if (!content) {
+		const level = projectLevel(cwd);
+		if (level <= 1) return ["bmad-master", "pm"];
+		return ["bmad-master", "analyst"];
+	}
+
+	const phase = detectPhase(content);
+	const skills = [...(PHASE_SKILLS[phase] ?? ["bmad-master"])];
+
+	const level = projectLevel(cwd);
+	if (level <= 1 && phase === "planning" && !skills.includes("pm")) {
+		skills.push("pm");
+	}
+
+	return [...new Set(skills)];
+}
+
+export function bmadAutoHint(cwd: string): string | null {
+	const statusPath = join(cwd, "docs", "bmm-workflow-status.yaml");
+	if (!existsSync(statusPath)) {
+		return "BMAD status not found — loaded bmad-master with planning defaults";
+	}
+	const phase = detectPhase(readText(statusPath) ?? "");
+	return `BMAD --auto detected phase: ${phase}`;
+}