@polymorphism-tech/morph-spec 4.10.6 → 4.10.8

package/framework/skills/level-1-workflows/morph-phase-plan/SKILL.md

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 4 (Plan). Generates a detailed implementation plan
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.10.6"
+cliVersion: "4.10.8"
 ---
 
 # MORPH Plan — Phase 4
@@ -65,6 +65,17 @@ Read: .morph/features/{feature}/1-design/spec.md
     + Read: .morph/config/config.json
 ```
 
+### 1.5 Create session tasks for visibility
+
+```
+TaskCreate: "Analyze feature for execution strategy"  → activeForm: "Analyzing feature"
+TaskCreate: "Determine execution strategy"            → activeForm: "Planning strategy"
+TaskCreate: "Generate plan.md"                        → activeForm: "Writing plan"
+TaskCreate: "Plan approval"                           → activeForm: "Awaiting plan approval"
+```
+
+Update each to `in_progress` before starting and `completed` after finishing.
+
 ---
 
 ## Workflow

package/framework/skills/level-1-workflows/morph-phase-setup/SKILL.md

@@ -1,258 +1,272 @@
----
-name: morph-phase-setup
-description: MORPH-SPEC Phase 1 (Setup). Reads project context, detects tech stack, activates relevant agents by reading agents.json, and confirms the feature environment. Use at the start of every MORPH-SPEC feature workflow after proposal approval to load standards and initialize the context.
-argument-hint: "[feature-name]"
-user-invocable: false
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.10.6"
----
-
-# MORPH Setup — Phase 1
-
-> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
-
-Initialize the context and prepare the environment for an approved feature.
-
-## Prerequisites
-
-- [ ] Feature has `proposal.md` created (Phase 0 complete)
-- [ ] Proposal was approved by the user
-- [ ] Agents were detected and registered in state
-
-## Recommended Tools
-
-> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` for full guide.
-> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` for MCP reference.
-
-| Action | Tool | Alternative |
-|--------|------|-------------|
-| Verify state | **Bash** `npx morph-spec state get` | — |
-| Detect agents + standards | **Read** `.morph/framework/agents.json` → match keywords → **Bash** `npx morph-spec state add-agent` | — |
-| Read project context | **Read** `.morph/context/README.md` | — |
-| Read config | **Read** `.morph/config/config.json` | — |
-| Detect VSA architecture | **Read** `.morph/config/config.json` → check `config.architecture.style` | — |
-| Scan project structure | **Glob** `src/**/*.{ts,tsx,cs}` | — |
-| Repository metadata | **GitHub MCP** `get_repo()` | **Bash** `gh repo view --json` |
-| Update state | **Bash** `npx morph-spec state set` | — |
-
-**MCPs for this phase:** GitHub (optional — repo metadata).
-
-**Anti-patterns:**
-- Do not call a `detect-agents` CLI command (it doesn't exist — read `.morph/framework/agents.json` directly)
-- Do not use a Task agent for inline keyword matching (fast enough to do directly)
-- Do not use WebSearch for local project info (use Read/Glob)
-
----
-
-## Workflow
-
-### ENTRY CHECKPOINT: Verify Prerequisites
-
-Before proceeding with setup:
-
-- [ ] Does `proposal.md` exist in `.morph/features/$ARGUMENTS/0-proposal/`?
-- [ ] Was the proposal presented and approved by the user?
-- [ ] Is the feature registered in state?
-
-If any checkbox is NOT checked → go back to Phase 0 (Proposal).
-
----
-
-### Step 1: Load Project Context
-
-Read these files first — they inform all subsequent decisions:
-
-```bash
-npx morph-spec state get $ARGUMENTS
-```
-
-If the feature doesn't exist in state, go back to Phase 0.
-
-Then read:
-- `.morph/context/README.md` — project overview, tech stack, architecture
-- `.morph/config/config.json` — project configuration
-
-### Step 2: Detect Agents and Load Standards
-
-#### Step 2.0: Detect Architecture Style and Activate Architect
-
-Read `.morph/config/config.json` and check `config.architecture.style`:
-
-| Value | Action |
-|-------|--------|
-| `"vertical-slice"` | `npx morph-spec state add-agent $ARGUMENTS vsa-architect` |
-| absent / any other value | `npx morph-spec state add-agent $ARGUMENTS domain-architect` |
-
-Proceed with normal keyword detection for all other agents. The architect was already added above — skip it during keyword matching to avoid duplication.
-
-#### Step 2.1: Keyword Detection
-
-Read agents.json and match keywords (except `domain-architect` and `vsa-architect` which were handled in Step 2.0):
-
-1. Read `.morph/framework/agents.json` (or `framework/agents.json` in the framework project itself)
-2. Extract the feature title and description from `0-proposal/proposal.md`
-3. For each agent in the JSON (except architects), check if any keyword from the `keywords[]` field appears in the proposal text
-4. Include all agents with `always_active: true` automatically
-5. Add matched agents to state:
-
-```bash
-npx morph-spec state add-agent $ARGUMENTS {agent-id}
-```
-
-**To load standards for detected agents:**
-- For each active agent, read the standards referenced by the `standards[]` field in `agents.json`
-- Standard files are located at `.morph/framework/standards/{path}`
-
-**Standards resolution order:**
-1. `.morph/context/*.md` — project overrides (highest priority)
-2. `.morph/framework/standards/` — standards installed by morph-spec
-3. `framework/standards/` — npm package standards (fallback)
-
-### Step 2.5: Validate MCP Connections
-
-Check that configured MCPs are working before proceeding.
-
-**1. Collect recommended MCPs:**
-- Read `framework/phases.json` → for each phase in the feature's workflow, collect `recommendedMCPs[]`
-- Read `framework/skills/level-0-meta/mcp-registry.json` → get `healthCheck` for each MCP
-
-**2. Identify configured MCPs:**
-- Read `.claude/settings.local.json` → identify which MCPs are in `mcpServers`
-
-**3. For each MCP that is CONFIGURED AND RECOMMENDED:**
-1. Search your available tools for one containing `healthCheck.toolPattern` in the name
-2. If the tool exists → execute the `healthCheck.testCall` with `healthCheck.testParams`
-3. Evaluate the result:
-
-| Result | Action |
-|--------|--------|
-| **Success** | `✓ {MCP} — connection verified` |
-| **Tool not found** | `○ {MCP} — needs restart to activate` |
-| **Error** | → Use `AskUserQuestion` with 3 options (below) |
-
-**On error — ask the user:**
-
-Use `AskUserQuestion` with header `"{MCP}"` and options:
-- **Continue without {MCP}** — show the `fallback` field from the registry and proceed
-- **Reconfigure credentials** — collect new credentials and update `.claude/settings.local.json`
-- **Stop setup** — abort and report what needs to be fixed
-
-**4. For MCPs RECOMMENDED but NOT CONFIGURED:**
-- Print `△ {MCP} — not configured (fallback: {registry.fallback})`
-- Suggestion: `Tip: configure with /morph-init refresh or npx morph-spec mcp setup`
-
-**Summary:** Show a status table for each MCP before proceeding:
-```
-MCP Readiness:
-  ✓ context7 — connection verified
-  ○ playwright — needs restart
-  △ supabase — not configured (fallback: Grep + Read for schema)
-```
-
----
-
-### Step 2.9: Check for Missing Agents
-
-Run a quick check to verify all expected agents are installed for this project's stack:
-
-```bash
-npx morph-spec doctor 2>&1 | grep -A 1 "agents completeness"
-```
-
-If the output shows **missing agents**, inform the user:
-
-> ⚠ Some agents for your stack are not installed. Run `npx morph-spec setup-infra` to install them.
-
-Use `AskUserQuestion` with header `"Agents"` and options:
-- **Install now** — run `npx morph-spec setup-infra` to reinstall with current stack tags
-- **Continue without** — proceed with available agents (may lack specialized support)
-
-If "Install now" is selected, run the command and continue.
-
----
-
-### Step 3: Confirm Stack
-
-Based on the proposal and context, confirm:
-- Tech stack (Blazor Server, Next.js, .NET API, Node.js CLI, etc.)
-- Applicable architectural patterns
-- Existing reusable components
-
-### Step 4: List Active Agents and Dispatch Preview
-
-Show the agents detected from the proposal:
-
-```bash
-npx morph-spec state get $ARGUMENTS
-```
-
-Parse the JSON and list `activeAgents` with their emojis/icons and responsibilities (look up each agent in `.morph/framework/agents.json` for the `icon` field).
-
-**If there are 2+ specialist agents active**, show the dispatch plan for the next phase:
-
-```bash
-npx morph-spec dispatch-agents $ARGUMENTS design
-```
-
-This shows which agents will be dispatched in parallel during the design phase and which tasks they'll execute.
-
-> **Important mapping:** `agents[].id` from the dispatch config = `subagent_type` in the `Agent` tool.
-> Example: `id: "nextjs-expert"` → `Agent(subagent_type=nextjs-expert, prompt=agent.taskPrompt)`.
-> Each `id` corresponds to the `name:` field in the frontmatter of the file in `.claude/agents/`.
-
-### Step 5: Update State and Determine Next Phase
-
-Update the feature state:
-
-```bash
-npx morph-spec state set $ARGUMENTS status in_progress
-```
-
-**Determine the next phase** based on active agents:
-
-| Condition | Next Phase |
-|-----------|------------|
-| `ui-designer` is in activeAgents | **uiux** (UI/UX phase) |
-| `ui-designer` is NOT in activeAgents | **design** (skip uiux) |
-
-Announce the next phase clearly to the user.
-
-## Outputs
-
-Present to the user:
-
-1. **Context loaded**:
-   - Project name
-   - Confirmed stack
-   - Applicable standards
-
-2. **Active agents**:
-   - Agent list with emojis/icons and tier
-   - Responsibilities of each agent
-
-3. **Next phase**:
-   - Which phase comes next (uiux or design)
-   - Why (ui-designer presence or absence)
-
-## Advancement Criteria
-
-- [x] Project context loaded
-- [x] Standards identified (framework + project)
-- [x] Stack confirmed
-- [x] Agents listed with icons
-- [x] State updated to in_progress
-- [x] Next phase determined
-
----
-
-## Superpowers Integration
-
-> Available when the `superpowers` plugin is installed.
-
-| Skill | When to Use | Invocation |
-|-------|-------------|-----------|
-| `using-git-worktrees` | If the feature requires workspace isolation | `Skill(superpowers:using-git-worktrees)` |
-
----
-
-Continue automatically to the next phase (UI/UX if ui-designer detected, otherwise Design).
+---
+name: morph-phase-setup
+description: MORPH-SPEC Phase 1 (Setup). Reads project context, detects tech stack, activates relevant agents by reading agents.json, and confirms the feature environment. Use at the start of every MORPH-SPEC feature workflow after proposal approval to load standards and initialize the context.
+argument-hint: "[feature-name]"
+user-invocable: false
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+cliVersion: "4.10.8"
+---
+
+# MORPH Setup — Phase 1
+
+> INTERNAL: Workflow skill used by /morph-proposal during automated phase orchestration. Not a user command.
+
+Initialize the context and prepare the environment for an approved feature.
+
+## Prerequisites
+
+- [ ] Feature has `proposal.md` created (Phase 0 complete)
+- [ ] Proposal was approved by the user
+- [ ] Agents were detected and registered in state
+
+## Recommended Tools
+
+> **Ref:** `framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md` for full guide.
+> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` for MCP reference.
+
+| Action | Tool | Alternative |
+|--------|------|-------------|
+| Verify state | **Bash** `npx morph-spec state get` | — |
+| Detect agents + standards | **Bash** `npx morph-spec detect-agents $ARGUMENTS --json` → parse → **Bash** `npx morph-spec state add-agent` | **Read** agents.json manually |
+| Read project context | **Read** `.morph/context/README.md` | — |
+| Read config | **Read** `.morph/config/config.json` | — |
+| Detect VSA architecture | **Read** `.morph/config/config.json` → check `config.architecture.style` | — |
+| Scan project structure | **Glob** `src/**/*.{ts,tsx,cs}` | — |
+| Repository metadata | **GitHub MCP** `get_repo()` | **Bash** `gh repo view --json` |
+| Update state | **Bash** `npx morph-spec state set` | — |
+
+**MCPs for this phase:** GitHub (optional — repo metadata).
+
+**Anti-patterns:**
+- Do not read agents.json manually for keyword matching — use `npx morph-spec detect-agents` CLI
+- Do not use a Task agent for agent detection (CLI is faster and consistent)
+- Do not use WebSearch for local project info (use Read/Glob)
+
+---
+
+## Workflow
+
+### ENTRY CHECKPOINT: Verify Prerequisites
+
+Before proceeding with setup:
+
+- [ ] Does `proposal.md` exist in `.morph/features/$ARGUMENTS/0-proposal/`?
+- [ ] Was the proposal presented and approved by the user?
+- [ ] Is the feature registered in state?
+
+If any checkbox is NOT checked → go back to Phase 0 (Proposal).
+
+---
+
+### Create session tasks for visibility
+
+```
+TaskCreate: "Detect agents and load standards"  → activeForm: "Detecting agents"
+TaskCreate: "Validate MCP connections"          → activeForm: "Validating MCPs"
+TaskCreate: "Confirm stack with user"           → activeForm: "Confirming stack"
+TaskCreate: "Configure feature state"           → activeForm: "Configuring state"
+```
+
+Update each task to `in_progress` before its step and `completed` after.
+
+---
+
+### Step 1: Load Project Context
+
+Read these files first — they inform all subsequent decisions:
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+If the feature doesn't exist in state, go back to Phase 0.
+
+Then read:
+- `.morph/context/README.md` — project overview, tech stack, architecture
+- `.morph/config/config.json` — project configuration
+
+### Step 2: Detect Agents and Load Standards
+
+#### Step 2.0: Detect Architecture Style and Activate Architect
+
+Read `.morph/config/config.json` and check `config.architecture.style`:
+
+| Value | Action |
+|-------|--------|
+| `"vertical-slice"` | `npx morph-spec state add-agent $ARGUMENTS vsa-architect` |
+| absent / any other value | `npx morph-spec state add-agent $ARGUMENTS domain-architect` |
+
+Proceed with normal keyword detection for all other agents. The architect was already added above — skip it during keyword matching to avoid duplication.
+
+#### Step 2.1: Keyword Detection
+
+Use the `detect-agents` CLI to match agent keywords against the proposal (excludes architects already handled in Step 2.0):
+
+```bash
+npx morph-spec detect-agents $ARGUMENTS --exclude domain-architect,vsa-architect --json
+```
+
+This reads the proposal from `.morph/features/$ARGUMENTS/0-proposal/proposal.md` and agents.json, returning JSON with `detected[]` and `skipped[]` arrays. Agents with `active_phases: ['*']` are always included.
+
+Parse the JSON output and add each detected agent to state:
+
+```bash
+npx morph-spec state add-agent $ARGUMENTS {agent-id}
+```
+
+Run `add-agent` once per detected agent ID from the `detected[]` array.
+
+**To load standards for detected agents:**
+- For each active agent, read the standards referenced by the `standards[]` field in `agents.json`
+- Standard files are located at `.morph/framework/standards/{path}`
+
+**Standards resolution order:**
+1. `.morph/context/*.md` — project overrides (highest priority)
+2. `.morph/framework/standards/` — standards installed by morph-spec
+3. `framework/standards/` — npm package standards (fallback)
+
+### Step 2.5: Validate MCP Connections
+
+Check that configured MCPs are working before proceeding.
+
+**1. Collect recommended MCPs:**
+- Read `framework/phases.json` → for each phase in the feature's workflow, collect `recommendedMCPs[]`
+- Read `framework/skills/level-0-meta/mcp-registry.json` → get `healthCheck` for each MCP
+
+**2. Identify configured MCPs:**
+- Read `.claude/settings.local.json` → identify which MCPs are in `mcpServers`
+
+**3. For each MCP that is CONFIGURED AND RECOMMENDED:**
+1. Search your available tools for one containing `healthCheck.toolPattern` in the name
+2. If the tool exists → execute the `healthCheck.testCall` with `healthCheck.testParams`
+3. Evaluate the result:
+
+| Result | Action |
+|--------|--------|
+| **Success** | `✓ {MCP} — connection verified` |
+| **Tool not found** | `○ {MCP} — needs restart to activate` |
+| **Error** | → Use `AskUserQuestion` with 3 options (below) |
+
+**On error — ask the user:**
+
+Use `AskUserQuestion` with header `"{MCP}"` and options:
+- **Continue without {MCP}** — show the `fallback` field from the registry and proceed
+- **Reconfigure credentials** — collect new credentials and update `.claude/settings.local.json`
+- **Stop setup** — abort and report what needs to be fixed
+
+**4. For MCPs RECOMMENDED but NOT CONFIGURED:**
+- Print `△ {MCP} — not configured (fallback: {registry.fallback})`
+- Suggestion: `Tip: configure with /morph-init refresh or npx morph-spec mcp setup`
+
+**Summary:** Show a status table for each MCP before proceeding:
+```
+MCP Readiness:
+  ✓ context7 — connection verified
+  ○ playwright — needs restart
+  △ supabase — not configured (fallback: Grep + Read for schema)
+```
+
+---
+
+### Step 2.9: Check for Missing Agents
+
+Run a quick check to verify all expected agents are installed for this project's stack:
+
+```bash
+npx morph-spec doctor 2>&1 | grep -A 1 "agents completeness"
+```
+
+If the output shows **missing agents**, inform the user:
+
+> ⚠ Some agents for your stack are not installed. Run `npx morph-spec setup-infra` to install them.
+
+Use `AskUserQuestion` with header `"Agents"` and options:
+- **Install now** — run `npx morph-spec setup-infra` to reinstall with current stack tags
+- **Continue without** — proceed with available agents (may lack specialized support)
+
+If "Install now" is selected, run the command and continue.
+
+---
+
+### Step 3: Confirm Stack
+
+Based on the proposal and context, confirm:
+- Tech stack (Blazor Server, Next.js, .NET API, Node.js CLI, etc.)
+- Applicable architectural patterns
+- Existing reusable components
+
+### Step 4: List Active Agents and Dispatch Preview
+
+Show the agents detected from the proposal:
+
+```bash
+npx morph-spec state get $ARGUMENTS
+```
+
+Parse the JSON and list `activeAgents` with their emojis/icons and responsibilities (look up each agent in `.morph/framework/agents.json` for the `icon` field).
+
+**If there are 2+ specialist agents active**, show the dispatch plan for the next phase:
+
+```bash
+npx morph-spec dispatch-agents $ARGUMENTS design
+```
+
+This shows which agents will be dispatched in parallel during the design phase and which tasks they'll execute.
+
+> **Important mapping:** `agents[].id` from the dispatch config = `subagent_type` in the `Agent` tool.
+> Example: `id: "nextjs-expert"` → `Agent(subagent_type=nextjs-expert, prompt=agent.taskPrompt)`.
+> Each `id` corresponds to the `name:` field in the frontmatter of the file in `.claude/agents/`.
+
+### Step 5: Update State and Determine Next Phase
+
+Update the feature state:
+
+```bash
+npx morph-spec state set $ARGUMENTS status in_progress
+```
+
+**Determine the next phase** based on active agents:
+
+| Condition | Next Phase |
+|-----------|------------|
+| `ui-designer` is in activeAgents | **uiux** (UI/UX phase) |
+| `ui-designer` is NOT in activeAgents | **design** (skip uiux) |
+
+Announce the next phase clearly to the user.
+
+## Outputs
+
+Present to the user:
+
+1. **Context loaded**:
+   - Project name
+   - Confirmed stack
+   - Applicable standards
+
+2. **Active agents**:
+   - Agent list with emojis/icons and tier
+   - Responsibilities of each agent
+
+3. **Next phase**:
+   - Which phase comes next (uiux or design)
+   - Why (ui-designer presence or absence)
+
+## Advancement Criteria
+
+- [x] Project context loaded
+- [x] Standards identified (framework + project)
+- [x] Stack confirmed
+- [x] Agents listed with icons
+- [x] State updated to in_progress
+- [x] Next phase determined
+
+---
+
+## Worktree Note
+
+Worktree isolation is handled automatically by `/morph-proposal` Step 0 and `/morph-apply` Step 0.
+If a worktree is active, all file operations MUST use the worktree path (injected in session context as `WORKTREE_PATH`).
+
+---
+
+Continue automatically to the next phase (UI/UX if ui-designer detected, otherwise Design).