@gh-symphony/cli 0.2.5 → 0.4.0

package/dist/{chunk-DTPIJO6S.js → chunk-ZPS4CQZJ.js}

@@ -16,7 +16,7 @@ import {
   formatClaudePreflightText,
   resolveClaudeCommandBinary,
   runClaudePreflight
-} from "./chunk-3SKN5L3I.js";
+} from "./chunk-6OPRRC2J.js";
 
 // src/mapping/smart-defaults.ts
 var ROLE_PATTERNS = [
@@ -45,10 +45,9 @@ function inferStateRole(columnName) {
 function inferAllStateRoles(columnNames) {
   return columnNames.map(inferStateRole);
 }
-function toWorkflowLifecycleConfig(stateFieldName, mappings) {
+function toWorkflowLifecycleConfig(stateFieldName, mappings, options = {}) {
   const activeStates = [];
   const terminalStates = [];
-  const blockerCheckStates = [];
   for (const [columnName, mapping] of Object.entries(mappings)) {
     switch (mapping.role) {
       case "active":
@@ -61,14 +60,13 @@ function toWorkflowLifecycleConfig(stateFieldName, mappings) {
         break;
     }
   }
-  if (activeStates.length > 0) {
-    blockerCheckStates.push(activeStates[0]);
-  }
+  const blockerCheckStates = options.blockerCheckStates ?? [];
   return {
     stateFieldName,
     activeStates,
     terminalStates,
-    blockerCheckStates
+    blockerCheckStates,
+    planningStates: options.planningStates ?? blockerCheckStates
   };
 }
 function validateStateMapping(mappings) {
@@ -100,7 +98,7 @@ import * as p from "@clack/prompts";
 import { spawnSync } from "child_process";
 import { createHash } from "crypto";
 import { chmod, mkdir as mkdir3, readFile as readFile3, rename as rename2, writeFile as writeFile3 } from "fs/promises";
-import { basename, dirname as dirname2, join as join3, relative, resolve } from "path";
+import { dirname as dirname3, join as join3, relative, resolve } from "path";
 
 // src/prompts/runtime-claude-constraints.ts
 var CLAUDE_RUNTIME_CONSTRAINTS_SECTION = `## Runtime Constraints
@@ -361,12 +359,18 @@ function buildFrontMatter(input) {
       lines.push(`    - ${state}`);
     }
   }
-  if (input.lifecycle.blockerCheckStates.length > 0) {
-    lines.push("  blocker_check_states:");
-    for (const state of input.lifecycle.blockerCheckStates) {
-      lines.push(`    - ${state}`);
-    }
-  }
+  lines.push(
+    ...buildStringListFrontMatter(
+      "blocker_check_states",
+      input.lifecycle.blockerCheckStates
+    )
+  );
+  lines.push(
+    ...buildStringListFrontMatter(
+      "planning_states",
+      input.lifecycle.planningStates
+    )
+  );
   lines.push("polling:");
   lines.push(`  interval_ms: ${input.pollIntervalMs ?? 3e4}`);
   lines.push("workspace:");
@@ -380,6 +384,12 @@ function buildFrontMatter(input) {
   lines.push(...buildRuntimeFrontMatter(input.runtime));
   return lines.join("\n") + "\n";
 }
+function buildStringListFrontMatter(key, values) {
+  if (values.length === 0) {
+    return [`  ${key}: []`];
+  }
+  return [`  ${key}:`, ...values.map((value) => `    - ${value}`)];
+}
 function buildPriorityFrontMatter(input) {
   const lines = [];
   if (!input.priority) {
@@ -984,7 +994,8 @@ function generateReferenceWorkflow(input) {
   const terminalColumns = input.statusColumns.filter(
     (c) => c.role === "terminal"
   );
-  const firstActive = activeColumns[0];
+  const blockerCheckStates = input.lifecycle?.blockerCheckStates ?? [];
+  const planningStates = input.lifecycle?.planningStates ?? blockerCheckStates;
   if (activeColumns.length > 0) {
     lines.push("  active_states:");
     for (const col of activeColumns) {
@@ -1001,12 +1012,10 @@ function generateReferenceWorkflow(input) {
   } else {
     lines.push("  terminal_states: [{terminal column names}]");
   }
-  if (firstActive) {
-    lines.push("  blocker_check_states:");
-    lines.push(`    - ${firstActive.name}`);
-  } else {
-    lines.push("  blocker_check_states: [{first active state}]");
-  }
+  lines.push(
+    ...buildReferenceStringList("blocker_check_states", blockerCheckStates)
+  );
+  lines.push(...buildReferenceStringList("planning_states", planningStates));
   lines.push("");
   lines.push("# Linear tracker example:");
   lines.push("# tracker:");
@@ -1021,7 +1030,9 @@ function generateReferenceWorkflow(input) {
   lines.push("#     - Done");
   lines.push("#     - Canceled");
   lines.push("#     - Duplicate");
-  lines.push("# Linear uses repository-local polling; gh-symphony does not provide");
+  lines.push(
+    "# Linear uses repository-local polling; gh-symphony does not provide"
+  );
   lines.push("# a Linear webhook setup command.");
   lines.push("");
   lines.push("polling:");
@@ -1282,6 +1293,12 @@ function generateReferenceWorkflow(input) {
   lines.push("");
   return lines.join("\n");
 }
+function buildReferenceStringList(key, values) {
+  if (values.length === 0) {
+    return [`  ${key}: []`];
+  }
+  return [`  ${key}:`, ...values.map((value) => `    - ${value}`)];
+}
 function buildReferencePriorityLines(priority) {
   const lines = [];
   if (priority?.source === "project-field" || priority?.source === "labels") {
@@ -1349,7 +1366,7 @@ function resolveRoleAction(role) {
 
 // src/skills/skill-writer.ts
 import { mkdir as mkdir2, readFile as readFile2, rename, writeFile as writeFile2 } from "fs/promises";
-import { join as join2 } from "path";
+import { dirname as dirname2, join as join2 } from "path";
 function normalizeRuntimeForSkills(runtime) {
   if (isClaudeRuntime(runtime)) {
     return "claude-code";
@@ -1376,10 +1393,12 @@ function buildSkillFilePlans(repoRoot, runtime, templates, context) {
   }
   return {
     skillsDir,
-    files: templates.map((template) => ({
-      path: join2(skillsDir, template.name, template.fileName),
-      content: template.generate(context)
-    }))
+    files: templates.flatMap(
+      (template) => template.files.map((file) => ({
+        path: join2(skillsDir, template.name, file.relativePath),
+        content: file.generate(context)
+      }))
+    )
   };
 }
 
@@ -1419,8 +1438,9 @@ function generateGhSymphonySkill(ctx) {
     `- \`${ctx.contextYamlPath}\` must exist (contains GitHub Project metadata)`
   );
   lines.push(
-    `- \`${ctx.referenceWorkflowPath}\` must exist (annotated reference template)`
+    `- \`${ctx.referenceWorkflowPath}\` may exist for compatibility with older generated ecosystems`
   );
+  lines.push("- `references/README.md` must exist beside this skill");
   lines.push("- `gh` CLI must be authenticated");
   lines.push("");
   lines.push("## Repository Validation Guidance");
@@ -1445,49 +1465,70 @@ function generateGhSymphonySkill(ctx) {
   lines.push("## Design Mode");
   lines.push("");
   lines.push(
-    `1. Read \`${ctx.contextYamlPath}\` to understand the project structure`
+    "1. Read `WORKFLOW.md` if it exists and extract repository conventions:"
   );
+  lines.push("   - test / lint / build commands from the prompt body");
+  lines.push("   - lifecycle states from front matter");
   lines.push(
-    `2. Read \`${ctx.referenceWorkflowPath}\` as the annotated reference`
+    "2. Read `references/README.md` for the available reference files."
   );
-  lines.push("3. Ask the user these key questions:");
+  lines.push('3. Ask the user: "What should this orchestration accomplish?"');
+  lines.push("   - implement (default) \u2014 write features / fix bugs");
+  lines.push("   - review \u2014 review PRs and leave comments");
+  lines.push("   - maintain \u2014 dependency bumps, chores, hygiene");
+  lines.push("   - custom \u2014 describe in their own words");
+  lines.push(
+    "4. Pick the matching `references/workflow-posture-*.md` file(s); compose multiple files when the intent spans categories."
+  );
+  lines.push("5. Ask these setup questions:");
   lines.push("   - Which status columns should be **active** (agent works)?");
   lines.push("   - Which should be **wait** (agent pauses for human)?");
   lines.push("   - Which should be **terminal** (agent stops)?");
   lines.push("   - What runtime is being used? (codex / claude-code / custom)");
   lines.push("   - Any custom hooks needed? (after_create, before_run, etc.)");
+  lines.push("6. Generate WORKFLOW.md:");
+  lines.push("   - front matter from `references/workflow-schema.md`");
   lines.push(
-    "4. Generate WORKFLOW.md using the reference as a structural guide"
+    "   - prompt body from the selected posture file(s), adapted to actual repository commands"
   );
-  lines.push("5. Validate the generated file (see Validate Mode)");
+  lines.push("7. Show a diff or preview and confirm with the user.");
+  lines.push("8. Validate via `gh-symphony workflow validate`.");
   lines.push("");
   lines.push("## Refine Mode");
   lines.push("");
   lines.push("1. Read the current `WORKFLOW.md`");
-  lines.push(`2. Read \`${ctx.referenceWorkflowPath}\` for comparison`);
-  lines.push("3. Identify missing or incomplete sections:");
+  lines.push(
+    "2. Read `references/README.md` and select the relevant posture file(s)"
+  );
+  lines.push(
+    "3. Compare the current prompt body against the selected posture references"
+  );
+  lines.push("4. Identify missing or incomplete sections:");
   lines.push("   - Status Map with role annotations");
   lines.push("   - Default Posture / Agent Instructions");
   lines.push("   - Guardrails section");
   lines.push("   - Workpad Template");
   lines.push("   - Step 0 routing logic");
-  lines.push("4. Propose improvements and apply with user confirmation");
-  lines.push("5. Validate the refined file");
+  lines.push("5. Propose improvements and apply with user confirmation");
+  lines.push("6. Validate the refined file");
   lines.push("");
   lines.push("## Validate Mode");
   lines.push("");
   lines.push("Check the WORKFLOW.md for:");
   lines.push("- Front matter is valid YAML");
   lines.push(
-    "- Required fields are present (see Supported Front Matter Fields)"
+    "- Required fields are present (see `references/workflow-schema.md`)"
   );
   lines.push(
-    "- Template variables use only supported names (see Supported Template Variables)"
+    "- Template variables use only supported names (see `references/workflow-schema.md`)"
   );
   lines.push("- Status Map matches the lifecycle configuration");
   lines.push(
     "- No unsupported double-brace variable patterns (only the 8 listed below are valid)"
   );
+  lines.push(
+    "- Prompt body posture is consistent with the selected `references/workflow-posture-*.md` file(s)"
+  );
   lines.push("");
   lines.push("## Supported Front Matter Fields");
   lines.push("");
@@ -1884,22 +1925,319 @@ function generateLandSkill(_ctx) {
   });
 }
 
+// src/skills/templates/gh-symphony-references/readme.ts
+function generateGhSymphonyReferencesReadme(_ctx) {
+  return [
+    "# /gh-symphony references",
+    "",
+    "The /gh-symphony skill consults these files when designing or refining",
+    "WORKFLOW.md.",
+    "",
+    "## Schema",
+    "",
+    "| File | What it is |",
+    "| ---- | ---------- |",
+    "| `workflow-schema.md` | All supported front matter fields and their types. |",
+    "",
+    "## Workflow prompt body postures",
+    "",
+    "When the user describes what the orchestration should do, pick the matching",
+    "posture file(s) and use its prompt-body sections as the seed. Postures can be",
+    "combined when the user's intent spans multiple categories.",
+    "",
+    "| File | Use when the user wants... |",
+    "| ---- | -------------------------- |",
+    "| `workflow-posture-implement.md` | Coding agent writes features / bug fixes (default). |",
+    "| `workflow-posture-review.md` | Agent reviews PRs and leaves comments. No code writes. |",
+    "| `workflow-posture-maintain.md` | Minimal-change maintenance: deps, lint sweeps, hygiene. |",
+    "",
+    "## Adding your own reference",
+    "",
+    "Drop a markdown file here with a descriptive name. The skill discovers files",
+    "on each invocation; no code changes needed."
+  ].join("\n");
+}
+
+// src/skills/templates/gh-symphony-references/workflow-schema.ts
+function generateWorkflowSchemaReference(ctx) {
+  const reference = generateReferenceWorkflow({
+    runtime: ctx.runtime,
+    statusColumns: ctx.statusColumns.map((column) => ({
+      name: column.name,
+      role: column.role
+    })),
+    projectId: ctx.projectId,
+    priority: null,
+    detectedEnvironment: ctx.detectedEnvironment
+  });
+  return [
+    reference,
+    "",
+    "## Supported Template Variables",
+    "",
+    "Use these in the WORKFLOW.md prompt body with double-brace syntax.",
+    "",
+    "| Variable | Description |",
+    "| -------- | ----------- |",
+    "| `issue.identifier` | Issue identifier, for example `acme/platform#42`. |",
+    "| `issue.title` | Issue title. |",
+    "| `issue.state` | Current tracker state. |",
+    "| `issue.description` | Issue body. |",
+    "| `issue.url` | Issue URL. |",
+    "| `issue.repository` | Repository in `owner/name` form. |",
+    "| `issue.number` | Issue number. |",
+    "| `attempt` | Retry attempt number, or null on the first run. |",
+    "",
+    "Only these variables are supported by strict-mode prompt rendering."
+  ].join("\n");
+}
+
+// src/skills/templates/gh-symphony-references/workflow-posture-implement.ts
+function generateWorkflowPostureImplementReference(ctx) {
+  const validationGuidance = buildRepositoryValidationGuidance(
+    ctx.detectedEnvironment
+  );
+  return [
+    "# Workflow posture: implement",
+    "",
+    "Use this prompt-body posture when the agent should write features or fix bugs.",
+    "This is the default posture and preserves the current generated WORKFLOW.md",
+    "prompt-body behavior.",
+    "",
+    "## Agent Instructions",
+    "",
+    'You are an AI coding agent working on issue `{issue.identifier}`: "`{issue.title}`".',
+    "",
+    "**Repository:** `{issue.repository}`",
+    "**Current state:** `{issue.state}`",
+    "",
+    "### Task",
+    "",
+    "`{issue.description}`",
+    "",
+    "### Default Posture",
+    "",
+    "1. This is an unattended orchestration session. Do not ask humans for follow-up actions.",
+    "2. Only abort early if there is a genuine blocker (missing required credentials or secrets).",
+    '3. In your final message, report only what was completed and any blockers. Do not include "next steps".',
+    "",
+    "### Repository Validation Guidance",
+    "",
+    ...validationGuidance.map((line, index) => `${index + 1}. ${line}`),
+    "",
+    "### Workflow",
+    "",
+    "1. Read the issue description and understand the requirements.",
+    "2. Explore the codebase to understand the relevant code structure.",
+    "3. Implement the changes following the project's coding conventions.",
+    "4. Write or update tests to cover the changes.",
+    "5. Verify that all existing tests pass.",
+    "6. Create a PR with a clear description of the changes.",
+    "",
+    "### Guardrails",
+    "",
+    "- Do not edit the issue body for planning or progress tracking.",
+    "- If the issue is in a terminal state, do nothing and exit.",
+    "- If you find out-of-scope improvements, open a separate issue rather than expanding the current scope.",
+    "",
+    "### Workpad Template",
+    "",
+    "Create a workpad comment on the issue with the following structure to track progress:",
+    "",
+    "```md",
+    "## Workpad",
+    "",
+    "### Plan",
+    "",
+    "- [ ] 1. Task item",
+    "",
+    "### Acceptance Criteria",
+    "",
+    "- [ ] Criterion 1",
+    "",
+    "### Validation",
+    "",
+    "- [ ] Test: `command`",
+    "",
+    "### Notes",
+    "",
+    "- Progress notes",
+    "```"
+  ].join("\n");
+}
+
+// src/skills/templates/gh-symphony-references/workflow-posture-review.ts
+function generateWorkflowPostureReviewReference(ctx) {
+  const validationGuidance = buildRepositoryValidationGuidance(
+    ctx.detectedEnvironment
+  );
+  return [
+    "# Workflow posture: review",
+    "",
+    "Use this prompt-body posture when the agent should review PRs and leave",
+    "comments. This posture is read-only for repository code.",
+    "",
+    "## Agent Instructions",
+    "",
+    'You are an AI code-review agent working on issue `{issue.identifier}`: "`{issue.title}`".',
+    "",
+    "**Repository:** `{issue.repository}`",
+    "**Current state:** `{issue.state}`",
+    "",
+    "### Task",
+    "",
+    "`{issue.description}`",
+    "",
+    "### Default Posture",
+    "",
+    "1. Review linked pull requests. Do NOT write code, push commits, or open new PRs.",
+    "2. Treat failing required tests as grounds to request changes unless the failure is clearly unrelated and documented.",
+    "3. In your final message, report only the review outcome and any blockers. Do not include follow-up work for the human unless it is required to unblock review.",
+    "",
+    "### Repository Validation Guidance",
+    "",
+    ...validationGuidance.map((line, index) => `${index + 1}. ${line}`),
+    "",
+    "### Workflow",
+    "",
+    "1. Find the PR linked from the issue, project item, or issue timeline.",
+    "2. Read the PR title, body, diff, linked issue, existing reviews, inline comments, and check status.",
+    "3. Run the repository's relevant tests, lint, typecheck, or build commands when available and practical.",
+    "4. Leave inline review comments for concrete, actionable findings.",
+    "5. Submit a summary review: approve only when the change is correct and validation is acceptable; otherwise request changes.",
+    "",
+    "### Guardrails",
+    "",
+    "- Never push code from this posture.",
+    "- Never approve PRs that introduce new dependencies without explicitly noting the dependency risk and why it is acceptable.",
+    "- If relevant tests fail and the failure is not proven unrelated, request changes.",
+    "- Keep comments specific to correctness, maintainability, tests, security, and issue fit.",
+    "- Do not create a workpad; the review threads on the PR are the audit trail."
+  ].join("\n");
+}
+
+// src/skills/templates/gh-symphony-references/workflow-posture-maintain.ts
+function generateWorkflowPostureMaintainReference(ctx) {
+  const validationGuidance = buildRepositoryValidationGuidance(
+    ctx.detectedEnvironment
+  );
+  return [
+    "# Workflow posture: maintain",
+    "",
+    "Use this prompt-body posture for low-risk maintenance such as dependency",
+    "bumps, lint sweeps, small chores, and repository hygiene.",
+    "",
+    "## Agent Instructions",
+    "",
+    'You are a maintenance coding agent working on issue `{issue.identifier}`: "`{issue.title}`".',
+    "",
+    "**Repository:** `{issue.repository}`",
+    "**Current state:** `{issue.state}`",
+    "",
+    "### Task",
+    "",
+    "`{issue.description}`",
+    "",
+    "### Default Posture",
+    "",
+    "1. Make the smallest possible change that satisfies the maintenance request.",
+    "2. Defer human-judgment calls instead of broadening scope.",
+    "3. In your final message, report only what was completed and any blockers. Do not include optional next steps.",
+    "",
+    "### Repository Validation Guidance",
+    "",
+    ...validationGuidance.map((line, index) => `${index + 1}. ${line}`),
+    "",
+    "### Workflow",
+    "",
+    "1. Identify the exact maintenance task and affected files.",
+    "2. Make the minimal change needed; avoid drive-by refactors.",
+    "3. Run the relevant tests, lint, typecheck, or build commands for the affected area.",
+    "4. Create a PR when the change is complete, or exit with a blocker note if approval is required.",
+    "",
+    "### Guardrails",
+    "",
+    "- Do not perform major dependency bumps without explicit approval.",
+    "- Do not delete files without confirmation unless the issue explicitly requests it.",
+    "- If the implementation exceeds 50 lines of non-generated code, stop and ask for human confirmation before continuing.",
+    "- Do not mix unrelated cleanup into the maintenance change.",
+    "",
+    "### Workpad Template",
+    "",
+    "Create a compact workpad comment on the issue with the following structure:",
+    "",
+    "```md",
+    "## Workpad",
+    "",
+    "### Plan",
+    "",
+    "- [ ] Minimal maintenance change",
+    "- [ ] Validation and PR handoff",
+    "",
+    "### Validation",
+    "",
+    "- [ ] Test/lint/typecheck/build command",
+    "",
+    "### Blockers",
+    "",
+    "None",
+    "```"
+  ].join("\n");
+}
+
+// src/skills/templates/gh-symphony-references/index.ts
+var GH_SYMPHONY_REFERENCE_FILES = [
+  {
+    relativePath: "references/README.md",
+    generate: generateGhSymphonyReferencesReadme
+  },
+  {
+    relativePath: "references/workflow-schema.md",
+    generate: generateWorkflowSchemaReference
+  },
+  {
+    relativePath: "references/workflow-posture-implement.md",
+    generate: generateWorkflowPostureImplementReference
+  },
+  {
+    relativePath: "references/workflow-posture-review.md",
+    generate: generateWorkflowPostureReviewReference
+  },
+  {
+    relativePath: "references/workflow-posture-maintain.md",
+    generate: generateWorkflowPostureMaintainReference
+  }
+];
+
 // src/skills/templates/index.ts
 var ALL_SKILL_TEMPLATES = [
   {
     name: "gh-symphony",
-    fileName: "SKILL.md",
-    generate: generateGhSymphonySkill
+    files: [
+      { relativePath: "SKILL.md", generate: generateGhSymphonySkill },
+      ...GH_SYMPHONY_REFERENCE_FILES
+    ]
   },
   {
     name: "gh-project",
-    fileName: "SKILL.md",
-    generate: generateGhProjectSkill
+    files: [{ relativePath: "SKILL.md", generate: generateGhProjectSkill }]
+  },
+  {
+    name: "commit",
+    files: [{ relativePath: "SKILL.md", generate: generateCommitSkill }]
+  },
+  {
+    name: "push",
+    files: [{ relativePath: "SKILL.md", generate: generatePushSkill }]
+  },
+  {
+    name: "pull",
+    files: [{ relativePath: "SKILL.md", generate: generatePullSkill }]
   },
-  { name: "commit", fileName: "SKILL.md", generate: generateCommitSkill },
-  { name: "push", fileName: "SKILL.md", generate: generatePushSkill },
-  { name: "pull", fileName: "SKILL.md", generate: generatePullSkill },
-  { name: "land", fileName: "SKILL.md", generate: generateLandSkill }
+  {
+    name: "land",
+    files: [{ relativePath: "SKILL.md", generate: generateLandSkill }]
+  }
 ];
 
 // src/commands/workflow-init.ts
@@ -2017,7 +2355,7 @@ function validateInitRuntime(runtime) {
 async function promptRuntimeSelection() {
   return abortIfCancelled(
     p.select({
-      message: "Step 1/3 \u2014 Select the agent runtime:",
+      message: "Step 1/5 \u2014 Select the agent runtime:",
       options: [
         {
           value: "codex-app-server",
@@ -2095,7 +2433,7 @@ async function writePlannedFile(file) {
   if (file.status === "unchanged") {
     return false;
   }
-  await mkdir3(dirname2(file.path), { recursive: true });
+  await mkdir3(dirname3(file.path), { recursive: true });
   const temporaryPath = `${file.path}.tmp`;
   await writeFile3(temporaryPath, file.content, "utf8");
   await rename2(temporaryPath, file.path);
@@ -2104,6 +2442,9 @@ async function writePlannedFile(file) {
   }
   return true;
 }
+function skillNameForPath(skillsDir, filePath) {
+  return relative(skillsDir, filePath).split(/[\\/]/)[0] ?? "";
+}
 function resolveStatusField(projectDetail) {
   return projectDetail.statusFields.find((f) => f.name.toLowerCase() === "status") ?? projectDetail.statusFields[0] ?? null;
 }
@@ -2318,16 +2659,68 @@ async function promptStateMappings(statusField, options) {
   }
   return mappings;
 }
+function getDefaultBlockerCheckStates(lifecycle) {
+  const firstActive = lifecycle.activeStates[0];
+  return firstActive ? [firstActive] : [];
+}
+async function promptBlockerCheck(lifecycle, options) {
+  const stepLabel = options?.stepLabel ?? "Step 3/5";
+  const activeStates = lifecycle.activeStates;
+  const defaultStates = getDefaultBlockerCheckStates(lifecycle);
+  if (activeStates.length === 0) {
+    p.log.warn("No active states; blocker check cannot be enabled.");
+    p.log.info("Blocker check: disabled");
+    return [];
+  }
+  const activeStateSummary = activeStates.length === 1 ? `"${activeStates[0]}"` : "selected active states";
+  const enabled = await abortIfCancelled(
+    p.confirm({
+      message: `${stepLabel} \u2014 Enable blocker check? Issues with unresolved "blocked by" dependencies will be held back from dispatch on ${activeStateSummary}.`,
+      initialValue: true
+    })
+  );
+  if (!enabled) {
+    p.log.info("Blocker check: disabled");
+    return [];
+  }
+  if (activeStates.length === 1) {
+    p.log.info(`Blocker check applies to: ${activeStates[0]}`);
+    return [activeStates[0]];
+  }
+  const selectedStates = await abortIfCancelled(
+    p.multiselect({
+      message: `${stepLabel} \u2014 Which active states should be blocker-checked?`,
+      options: activeStates.map((state) => ({
+        value: state,
+        label: state,
+        hint: defaultStates.includes(state) ? "default" : void 0
+      })),
+      initialValues: defaultStates,
+      required: true
+    })
+  );
+  p.log.info(`Blocker check applies to: ${selectedStates.join(", ")}`);
+  return [...selectedStates];
+}
 async function planWorkflowArtifacts(opts) {
   const environment = opts.environment ?? await detectEnvironment(opts.cwd);
   const priority = opts.priority ?? (opts.priorityField ? buildProjectFieldPriority(opts.priorityField) : buildDisabledPriority());
+  const defaultLifecycle = toWorkflowLifecycleConfig(
+    opts.statusField.name,
+    opts.mappings
+  );
+  const defaultBlockerCheckStates = getDefaultBlockerCheckStates(defaultLifecycle);
+  const lifecycle = opts.lifecycle ?? toWorkflowLifecycleConfig(opts.statusField.name, opts.mappings, {
+    blockerCheckStates: defaultBlockerCheckStates,
+    planningStates: defaultBlockerCheckStates
+  });
   const workflowMd = generateWorkflowMarkdown({
     projectId: opts.projectDetail.id,
     stateFieldName: opts.statusField.name,
     priority,
     includePriorityTemplates: opts.includePriorityTemplates ?? priority.source === "disabled",
     mappings: opts.mappings,
-    lifecycle: toWorkflowLifecycleConfig(opts.statusField.name, opts.mappings),
+    lifecycle,
     runtime: opts.runtime,
     detectedEnvironment: environment
   });
@@ -2343,6 +2736,7 @@ async function planWorkflowArtifacts(opts) {
     statusField: opts.statusField,
     priorityField: opts.priorityField,
     priority,
+    lifecycle,
     includePriorityTemplates: opts.includePriorityTemplates ?? priority.source === "disabled",
     runtime: opts.runtime,
     skipSkills: opts.skipSkills,
@@ -2368,6 +2762,11 @@ function summarizeEnvironment(env) {
     `Existing skills   ${env.existingSkills.length === 0 ? "none" : env.existingSkills.join(", ")}`
   ];
 }
+function deriveWaitStates(statusField, lifecycle) {
+  const active = new Set(lifecycle.activeStates);
+  const terminal = new Set(lifecycle.terminalStates);
+  return statusField.options.map((option) => option.name).filter((state) => !active.has(state) && !terminal.has(state));
+}
 async function planEcosystem(opts) {
   const {
     cwd,
@@ -2379,6 +2778,19 @@ async function planEcosystem(opts) {
     skipContext
   } = opts;
   const priority = opts.priority ?? (priorityField ? buildProjectFieldPriority(priorityField) : buildDisabledPriority());
+  const automaticLifecycle = toWorkflowLifecycleConfig(
+    statusField.name,
+    buildAutomaticStateMappings(statusField)
+  );
+  const defaultBlockerCheckStates = getDefaultBlockerCheckStates(automaticLifecycle);
+  const lifecycle = opts.lifecycle ?? toWorkflowLifecycleConfig(
+    statusField.name,
+    buildAutomaticStateMappings(statusField),
+    {
+      blockerCheckStates: defaultBlockerCheckStates,
+      planningStates: defaultBlockerCheckStates
+    }
+  );
   const ghSymphonyDir = join3(cwd, ".gh-symphony");
   const environment = opts.environment ?? await detectEnvironment(cwd);
   const files = [];
@@ -2418,6 +2830,7 @@ async function planEcosystem(opts) {
     })),
     projectId: projectDetail.id,
     priority,
+    lifecycle,
     detectedEnvironment: environment
   });
   files.push(
@@ -2454,10 +2867,11 @@ async function planEcosystem(opts) {
       }
     );
     for (const plannedSkill of plannedSkills) {
+      const skillName = skillNameForPath(skillsDir, plannedSkill.path);
       files.push(
         await planFileChange({
           path: plannedSkill.path,
-          label: `Skill ${basename(dirname2(plannedSkill.path))}`,
+          label: `Skill ${skillName}`,
           content: plannedSkill.content,
           mode: "create-only"
         })
@@ -2469,6 +2883,8 @@ async function planEcosystem(opts) {
     githubProjectTitle: projectDetail.title,
     runtime,
     priority,
+    lifecycle,
+    waitStates: deriveWaitStates(statusField, lifecycle),
     skillsDir,
     skipSkills,
     environment,
@@ -2505,7 +2921,7 @@ async function writeEcosystem(opts) {
       continue;
     }
     if (file.label.startsWith("Skill ")) {
-      const skillName = basename(dirname2(file.path));
+      const skillName = file.label.slice("Skill ".length);
       if (written) {
         skillsWritten.push(skillName);
       } else {
@@ -2518,13 +2934,15 @@ async function writeEcosystem(opts) {
     githubProjectTitle: plan.githubProjectTitle,
     runtime: plan.runtime,
     priority: plan.priority,
+    lifecycle: plan.lifecycle,
+    waitStates: plan.waitStates,
     skillsDir: plan.skillsDir,
     skipSkills: plan.skipSkills,
     afterCreateHookWritten,
     contextYamlWritten,
     referenceWorkflowWritten,
-    skillsWritten: skillsWritten.sort(),
-    skillsSkipped: skillsSkipped.sort()
+    skillsWritten: [...new Set(skillsWritten)].sort(),
+    skillsSkipped: [...new Set(skillsSkipped)].sort()
   };
 }
 function formatPrioritySummaryLines(priority) {
@@ -2539,9 +2957,20 @@ function formatPrioritySummaryLines(priority) {
     ];
   }
   const mapping = Object.entries(priority.labels).map(([name, value]) => `${name}=${value}`).join(", ");
+  return ["Priority source   labels", `Priority mapping  ${mapping || "none"}`];
+}
+function formatLifecycleValue(states) {
+  return states.length > 0 ? states.join(", ") : "disabled";
+}
+function formatLifecycleSummaryLines(lifecycle, waitStates) {
   return [
-    "Priority source   labels",
-    `Priority mapping  ${mapping || "none"}`
+    "Lifecycle",
+    `  Status field   ${lifecycle.stateFieldName}`,
+    `  Active         ${lifecycle.activeStates.join(", ") || "(none)"}`,
+    `  Wait           ${waitStates.join(", ") || "(none)"}`,
+    `  Terminal       ${lifecycle.terminalStates.join(", ") || "(none)"}`,
+    `  Blocker check  ${formatLifecycleValue(lifecycle.blockerCheckStates)}`,
+    `  Planning       ${formatLifecycleValue(lifecycle.planningStates)}`
   ];
 }
 function printEcosystemSummary(result, workflowPath, opts) {
@@ -2554,6 +2983,10 @@ function printEcosystemSummary(result, workflowPath, opts) {
   lines.push(`Runtime   ${result.runtime}`);
   lines.push(...formatPrioritySummaryLines(result.priority));
   lines.push("");
+  lines.push(
+    ...formatLifecycleSummaryLines(result.lifecycle, result.waitStates)
+  );
+  lines.push("");
   lines.push("Generated files");
   lines.push(`  \u2713 WORKFLOW.md                          ${relWorkflow}`);
   if (result.afterCreateHookWritten) {
@@ -2608,6 +3041,13 @@ function renderDryRunPreview(workflowPath, workflowPlan, ecosystemPlan) {
   lines.push(`Runtime   ${ecosystemPlan.runtime}`);
   lines.push(...formatPrioritySummaryLines(ecosystemPlan.priority));
   lines.push("");
+  lines.push(
+    ...formatLifecycleSummaryLines(
+      ecosystemPlan.lifecycle,
+      ecosystemPlan.waitStates
+    )
+  );
+  lines.push("");
   lines.push("Planned file changes");
   lines.push(
     `  ${statusIcon[workflowPlan.status]} ${workflowPlan.status.padEnd(9)} WORKFLOW.md                          ${relWorkflow}`
@@ -2737,6 +3177,13 @@ Run without --non-interactive for manual mapping.
     process.exitCode = 1;
     return;
   }
+  const defaultBlockerCheckStates = getDefaultBlockerCheckStates(
+    toWorkflowLifecycleConfig(statusField.name, mappings)
+  );
+  const lifecycle = toWorkflowLifecycleConfig(statusField.name, mappings, {
+    blockerCheckStates: defaultBlockerCheckStates,
+    planningStates: defaultBlockerCheckStates
+  });
   const outputPath = resolve(flags.output ?? "WORKFLOW.md");
   const { workflowPlan, ecosystemPlan } = await planWorkflowArtifacts({
     cwd: process.cwd(),
@@ -2747,6 +3194,7 @@ Run without --non-interactive for manual mapping.
     priority,
     includePriorityTemplates: !autoPriorityField,
     mappings,
+    lifecycle,
     runtime,
     skipSkills: flags.skipSkills,
     skipContext: flags.skipContext
@@ -2771,6 +3219,7 @@ Run without --non-interactive for manual mapping.
     priorityField: autoPriorityField,
     priority,
     includePriorityTemplates: !autoPriorityField,
+    lifecycle,
     runtime,
     skipSkills: flags.skipSkills,
     skipContext: flags.skipContext
@@ -2847,7 +3296,7 @@ async function runInteractiveStandalone(flags, _options) {
   }
   const selectedGithubProjectId = await abortIfCancelled(
     p.select({
-      message: "Step 2/3 \u2014 Select a GitHub Project board:",
+      message: "Step 2/5 \u2014 Select a GitHub Project board:",
       options: projects.map((proj) => ({
         value: proj.id,
         label: `${proj.owner.login}/${proj.title}`,
@@ -2882,12 +3331,7 @@ async function runInteractiveStandalone(flags, _options) {
     projectDetail.linkedRepositories
   );
   const mappings = await promptStateMappings(statusField, {
-    stepLabel: "Step 3/4"
-  });
-  const { priority, priorityField } = await promptPriorityConfig({
-    priorityResolution,
-    labelNames: priorityLabelNames,
-    stepLabel: "Step 4/4"
+    stepLabel: "Step 3/5"
   });
   const validation = validateStateMapping(mappings);
   if (!validation.valid) {
@@ -2901,6 +3345,19 @@ async function runInteractiveStandalone(flags, _options) {
   for (const warn of validation.warnings) {
     p.log.warn(`  \u26A0 ${warn}`);
   }
+  const lifecycleBase = toWorkflowLifecycleConfig(statusField.name, mappings);
+  const blockerCheckStates = await promptBlockerCheck(lifecycleBase, {
+    stepLabel: "Step 4/5"
+  });
+  const lifecycle = toWorkflowLifecycleConfig(statusField.name, mappings, {
+    blockerCheckStates,
+    planningStates: blockerCheckStates
+  });
+  const { priority, priorityField } = await promptPriorityConfig({
+    priorityResolution,
+    labelNames: priorityLabelNames,
+    stepLabel: "Step 5/5"
+  });
   const outputPath = resolve(flags.output ?? "WORKFLOW.md");
   const { workflowPlan, ecosystemPlan } = await planWorkflowArtifacts({
     cwd: process.cwd(),
@@ -2911,6 +3368,7 @@ async function runInteractiveStandalone(flags, _options) {
     priority,
     includePriorityTemplates: priority.source === "disabled",
     mappings,
+    lifecycle,
     runtime,
     skipSkills: flags.skipSkills,
     skipContext: flags.skipContext
@@ -2927,6 +3385,7 @@ async function runInteractiveStandalone(flags, _options) {
     priorityField,
     priority,
     includePriorityTemplates: priority.source === "disabled",
+    lifecycle,
     runtime,
     skipSkills: flags.skipSkills,
     skipContext: flags.skipContext
@@ -2938,6 +3397,7 @@ async function runInteractiveStandalone(flags, _options) {
 }
 
 export {
+  toWorkflowLifecycleConfig,
   validateStateMapping,
   abortIfCancelled,
   workflow_init_default,
@@ -2947,6 +3407,7 @@ export {
   collectPriorityLabelNames,
   promptPriorityConfig,
   promptStateMappings,
+  promptBlockerCheck,
   planWorkflowArtifacts,
   writeWorkflowPlan,
   writeEcosystem,