@gh-symphony/cli 0.3.0 → 0.4.1

package/dist/{chunk-GL55AKBI.js → chunk-RU5GQG6A.js}

@@ -16,7 +16,7 @@ import {
   formatClaudePreflightText,
   resolveClaudeCommandBinary,
   runClaudePreflight
-} from "./chunk-5HQLPZR5.js";
+} from "./chunk-YKC6CGD6.js";
 
 // src/mapping/smart-defaults.ts
 var ROLE_PATTERNS = [
@@ -97,8 +97,17 @@ function validateStateMapping(mappings) {
 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 {
+  chmod,
+  mkdir as mkdir2,
+  readFile as readFile3,
+  readdir as readdir2,
+  rename as rename2,
+  rm,
+  rmdir,
+  writeFile as writeFile2
+} from "fs/promises";
+import { dirname as dirname2, join as join3, relative, resolve } from "path";
 
 // src/prompts/runtime-claude-constraints.ts
 var CLAUDE_RUNTIME_CONSTRAINTS_SECTION = `## Runtime Constraints
@@ -209,7 +218,6 @@ function buildRepositoryValidationGuidance(input) {
 // src/workflow/workflow-runtime.ts
 var CODEX_RUNTIME_TOKENS = ["codex-app-server", "codex"];
 var CLAUDE_RUNTIME_TOKENS = ["claude-print", "claude-code"];
-var DEFAULT_CODEX_APP_SERVER_ARGS = ["app-server"];
 var DEFAULT_CLAUDE_PRINT_ARGS = [
   "-p",
   "--output-format",
@@ -258,31 +266,6 @@ function resolveRuntimeCommand(runtime) {
   }
   return runtime;
 }
-function resolveRuntimeArgs(runtime) {
-  const normalized = normalizeInitRuntime(runtime);
-  if (normalized === "codex-app-server") {
-    return DEFAULT_CODEX_APP_SERVER_ARGS;
-  }
-  if (normalized === "claude-print") {
-    return DEFAULT_CLAUDE_PRINT_ARGS;
-  }
-  return [];
-}
-function resolveRuntimeAgentCommand(runtime) {
-  const command = resolveRuntimeCommand(runtime);
-  const args = resolveRuntimeArgs(runtime);
-  return args.length === 0 ? command : [command, ...args].join(" ");
-}
-function resolveShellAgentCommand(runtime) {
-  if (/^\s*bash\s+-lc\s+/.test(runtime)) {
-    return runtime;
-  }
-  const normalized = normalizeInitRuntime(runtime);
-  if (normalized === "codex-app-server" || normalized === "claude-print") {
-    return `bash -lc ${resolveRuntimeAgentCommand(normalized)}`;
-  }
-  return runtime;
-}
 function buildRuntimeFrontMatter(runtime) {
   const normalized = normalizeInitRuntime(runtime);
   if (normalized === "codex-app-server") {
@@ -833,1090 +816,1273 @@ async function detectEnvironment(cwd) {
   };
 }
 
-// src/context/generate-context-yaml.ts
-import { mkdir, writeFile } from "fs/promises";
-import { dirname } from "path";
-function yamlQuote(value) {
-  const specialChars = /[:#{'"\]{}()\\[]|\n/;
-  if (specialChars.test(value)) {
-    return `"${value.replace(/"/g, '\\"')}"`;
+// src/skills/skill-writer.ts
+import { mkdir, readFile as readFile2, rename, writeFile } from "fs/promises";
+import { dirname, join as join2 } from "path";
+function normalizeRuntimeForSkills(runtime) {
+  if (isClaudeRuntime(runtime)) {
+    return "claude-code";
+  }
+  if (isCodexRuntime(runtime)) {
+    return "codex";
   }
-  return value;
+  return null;
 }
-function generateContextYamlString(context) {
-  const lines = [];
-  lines.push("schema_version: 1");
-  lines.push(`collected_at: ${context.collected_at}`);
-  lines.push("");
-  lines.push("project:");
-  lines.push(`  id: ${context.project.id}`);
-  lines.push(`  title: ${yamlQuote(context.project.title)}`);
-  lines.push(`  url: ${context.project.url}`);
-  lines.push("");
-  lines.push("status_field:");
-  lines.push(`  id: ${context.status_field.id}`);
-  lines.push(`  name: ${yamlQuote(context.status_field.name)}`);
-  lines.push("  columns:");
-  for (const column of context.status_field.columns) {
-    lines.push(`    - id: ${column.id}`);
-    lines.push(`      name: ${yamlQuote(column.name)}`);
-    lines.push(
-      `      color: ${column.color === null ? "null" : yamlQuote(column.color)}`
-    );
-    lines.push(
-      `      inferred_role: ${column.inferred_role === null ? "null" : column.inferred_role}`
-    );
-    lines.push(`      confidence: ${column.confidence}`);
+function resolveSkillsDir(repoRoot, runtime) {
+  const normalizedRuntime = normalizeRuntimeForSkills(runtime);
+  if (normalizedRuntime === "claude-code") {
+    return join2(repoRoot, ".claude", "skills");
   }
-  lines.push("");
-  lines.push("text_fields:");
-  if (context.text_fields.length === 0) {
-    lines.push("  []");
-  } else {
-    for (const field of context.text_fields) {
-      lines.push(`  - id: ${field.id}`);
-      lines.push(`    name: ${yamlQuote(field.name)}`);
-      lines.push(`    data_type: ${field.data_type}`);
-    }
+  if (normalizedRuntime === "codex") {
+    return join2(repoRoot, ".codex", "skills");
   }
-  lines.push("");
-  lines.push("repositories:");
-  if (context.repositories.length === 0) {
-    lines.push("  []");
-  } else {
-    for (const repo of context.repositories) {
-      lines.push(`  - owner: ${repo.owner}`);
-      lines.push(`    name: ${repo.name}`);
-      lines.push(`    clone_url: ${repo.clone_url}`);
-    }
+  return null;
+}
+function buildSkillFilePlans(repoRoot, runtime, templates, context) {
+  const skillsDir = resolveSkillsDir(repoRoot, runtime);
+  if (!skillsDir) {
+    return { skillsDir: null, files: [] };
   }
+  return {
+    skillsDir,
+    files: templates.flatMap(
+      (template) => template.files.map((file) => ({
+        path: join2(skillsDir, template.name, file.relativePath),
+        content: file.generate(context)
+      }))
+    )
+  };
+}
+
+// src/skills/templates/document.ts
+function renderSkillDocument(options) {
+  const { name, description, bodyLines } = options;
+  return [
+    "---",
+    `name: ${name}`,
+    `description: ${description}`,
+    "license: MIT",
+    "metadata:",
+    "  author: gh-symphony",
+    '  version: "1.0"',
+    '  generatedBy: "gh-symphony"',
+    "---",
+    "",
+    ...bodyLines
+  ].join("\n");
+}
+
+// src/skills/templates/gh-symphony.ts
+function generateGhSymphonySkill(ctx) {
+  const lines = [];
+  lines.push("# /gh-symphony \u2014 WORKFLOW.md Design & Refinement");
+  lines.push("");
+  lines.push("## Trigger");
+  lines.push("");
+  lines.push("Use this skill when you want to:");
+  lines.push("- Create a new WORKFLOW.md for a GitHub Symphony project");
+  lines.push("- Refine or improve an existing WORKFLOW.md");
+  lines.push("- Validate that a WORKFLOW.md is correctly structured");
+  lines.push("");
+  lines.push("## Prerequisites");
+  lines.push("");
+  lines.push("- `WORKFLOW.md` is the repository policy and config source");
+  lines.push("- `references/README.md` must exist beside this skill");
+  lines.push("- `gh` CLI must be authenticated");
+  lines.push("");
+  lines.push("## Repository Validation Guidance");
   lines.push("");
-  lines.push("detected_environment:");
   lines.push(
-    `  packageManager: ${context.detected_environment.packageManager === null ? "null" : yamlQuote(context.detected_environment.packageManager)}`
+    "Carry the detected repository validation posture into any new or refined `WORKFLOW.md` instead of falling back to generic instructions."
   );
+  for (const line of buildRepositoryValidationGuidance(
+    ctx.detectedEnvironment
+  )) {
+    lines.push(`- ${line}`);
+  }
+  lines.push("");
+  lines.push("## Mode Detection");
+  lines.push("");
+  lines.push("Check if `WORKFLOW.md` exists in the current directory:");
+  lines.push("- **Not found** \u2192 enter **Design Mode** (create from scratch)");
+  lines.push("- **Found** \u2192 ask user: refine existing or validate only?");
+  lines.push("  - Refine \u2192 enter **Refine Mode**");
+  lines.push("  - Validate \u2192 enter **Validate Mode**");
+  lines.push("");
+  lines.push("## Design Mode");
+  lines.push("");
   lines.push(
-    `  lockfile: ${context.detected_environment.lockfile === null ? "null" : yamlQuote(context.detected_environment.lockfile)}`
+    "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(
-    `  testCommand: ${context.detected_environment.testCommand === null ? "null" : yamlQuote(context.detected_environment.testCommand)}`
+    "2. Read `references/README.md` for the available reference files."
   );
+  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(
-    `  buildCommand: ${context.detected_environment.buildCommand === null ? "null" : yamlQuote(context.detected_environment.buildCommand)}`
+    "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(
-    `  lintCommand: ${context.detected_environment.lintCommand === null ? "null" : yamlQuote(context.detected_environment.lintCommand)}`
+    "   - prompt body from the selected posture file(s), adapted to actual repository commands"
   );
+  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(
-    `  ciPlatform: ${context.detected_environment.ciPlatform === null ? "null" : yamlQuote(context.detected_environment.ciPlatform)}`
+    "2. Read `references/README.md` and select the relevant posture file(s)"
   );
-  lines.push(`  monorepo: ${context.detected_environment.monorepo}`);
-  lines.push("  existingSkills:");
-  if (context.detected_environment.existingSkills.length === 0) {
-    lines.push("    []");
-  } else {
-    for (const skill of context.detected_environment.existingSkills) {
-      lines.push(`    - ${yamlQuote(skill)}`);
-    }
-  }
-  lines.push("");
-  lines.push("runtime:");
-  lines.push(`  agent: ${yamlQuote(context.runtime.agent)}`);
-  lines.push(`  agent_command: ${yamlQuote(context.runtime.agent_command)}`);
-  return lines.join("\n") + "\n";
-}
-function buildContextYaml(params) {
-  const columns = params.statusField.options.map((option) => {
-    const roleMapping = inferStateRole(option.name);
-    return {
-      id: option.id,
-      name: option.name,
-      color: option.color,
-      inferred_role: roleMapping.role,
-      confidence: roleMapping.confidence
-    };
-  });
-  const textFields = params.projectDetail.textFields.map((field) => ({
-    id: field.id,
-    name: field.name,
-    data_type: field.dataType
-  }));
-  const repositories = params.projectDetail.linkedRepositories.map((repo) => ({
-    owner: repo.owner,
-    name: repo.name,
-    clone_url: repo.cloneUrl
-  }));
-  return {
-    schema_version: 1,
-    collected_at: (/* @__PURE__ */ new Date()).toISOString(),
-    project: {
-      id: params.projectDetail.id,
-      title: params.projectDetail.title,
-      url: params.projectDetail.url
-    },
-    status_field: {
-      id: params.statusField.id,
-      name: params.statusField.name,
-      columns
-    },
-    text_fields: textFields,
-    repositories,
-    detected_environment: params.detectedEnvironment,
-    runtime: params.runtime
-  };
-}
-
-// src/workflow/generate-reference-workflow.ts
-function generateReferenceWorkflow(input) {
-  const lines = [];
-  lines.push("# Reference WORKFLOW.md \u2014 gh-symphony");
-  lines.push("# This file is a reference template for authoring WORKFLOW.md.");
   lines.push(
-    "# AI agents reference this file (via the /gh-symphony skill) when designing WORKFLOW.md."
+    "3. Compare the current prompt body against the selected posture references"
   );
-  lines.push("# Do not edit this file directly.");
+  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("5. Propose improvements and apply with user confirmation");
+  lines.push("6. Validate the refined file");
   lines.push("");
-  lines.push("---");
+  lines.push("## Validate Mode");
   lines.push("");
-  lines.push("# \u2550\u2550\u2550 FRONT MATTER FIELD REFERENCE \u2550\u2550\u2550");
+  lines.push("Check the WORKFLOW.md for:");
+  lines.push("- Front matter is valid YAML");
   lines.push(
-    "# All front matter fields supported by the gh-symphony parser are listed below."
+    "- Required fields are present (see `references/workflow-schema.md`)"
   );
-  lines.push("");
-  lines.push("tracker:");
-  lines.push("  kind: github-project");
-  lines.push(`  project_id: ${input.projectId}`);
-  lines.push("  state_field: Status");
-  lines.push(...buildReferencePriorityLines(input.priority));
-  lines.push("");
-  const activeColumns = input.statusColumns.filter((c) => c.role === "active");
-  const waitColumns = input.statusColumns.filter((c) => c.role === "wait");
-  const terminalColumns = input.statusColumns.filter(
-    (c) => c.role === "terminal"
+  lines.push(
+    "- Template variables use only supported names (see `references/workflow-schema.md`)"
   );
-  const blockerCheckStates = input.lifecycle?.blockerCheckStates ?? [];
-  const planningStates = input.lifecycle?.planningStates ?? blockerCheckStates;
-  if (activeColumns.length > 0) {
-    lines.push("  active_states:");
-    for (const col of activeColumns) {
-      lines.push(`    - ${col.name}`);
-    }
-  } else {
-    lines.push("  active_states: [{active column names}]");
-  }
-  if (terminalColumns.length > 0) {
-    lines.push("  terminal_states:");
-    for (const col of terminalColumns) {
-      lines.push(`    - ${col.name}`);
-    }
-  } else {
-    lines.push("  terminal_states: [{terminal column names}]");
-  }
+  lines.push("- Status Map matches the lifecycle configuration");
   lines.push(
-    ...buildReferenceStringList("blocker_check_states", blockerCheckStates)
+    "- No unsupported double-brace variable patterns (only the 8 listed below are valid)"
   );
-  lines.push(...buildReferenceStringList("planning_states", planningStates));
-  lines.push("");
-  lines.push("# Linear tracker example:");
-  lines.push("# tracker:");
-  lines.push("#   kind: linear");
-  lines.push("#   endpoint: https://api.linear.app/graphql");
-  lines.push("#   api_key: $LINEAR_API_KEY");
-  lines.push("#   project_slug: symphony-0c79b11b75ea");
-  lines.push("#   active_states:");
-  lines.push("#     - Todo");
-  lines.push("#     - In Progress");
-  lines.push("#   terminal_states:");
-  lines.push("#     - Done");
-  lines.push("#     - Canceled");
-  lines.push("#     - Duplicate");
   lines.push(
-    "# Linear uses repository-local polling; gh-symphony does not provide"
+    "- Prompt body posture is consistent with the selected `references/workflow-posture-*.md` file(s)"
   );
-  lines.push("# a Linear webhook setup command.");
   lines.push("");
+  lines.push("## Supported Front Matter Fields");
+  lines.push("");
+  lines.push("```yaml");
+  lines.push("tracker:");
+  lines.push("  kind: github-project");
+  lines.push("  project_id: PVT_xxx");
+  lines.push("  state_field: Status");
+  lines.push("  active_states: [Todo, In Progress]");
+  lines.push("  terminal_states: [Done, Cancelled]");
+  lines.push("  blocker_check_states: [Blocked]");
   lines.push("polling:");
   lines.push("  interval_ms: 30000");
-  lines.push("");
   lines.push("workspace:");
   lines.push("  root: .runtime/symphony-workspaces");
-  lines.push("");
   lines.push("hooks:");
-  lines.push(
-    `  after_create: ${DEFAULT_AFTER_CREATE_HOOK_PATH}  # ${DEFAULT_AFTER_CREATE_HOOK_COMMENT}`
-  );
+  lines.push("  after_create: |");
+  lines.push("    git clone --depth 1 https://github.com/owner/repo .");
   lines.push("  before_run: null");
   lines.push("  after_run: null");
   lines.push("  before_remove: null");
   lines.push("  timeout_ms: 60000");
-  lines.push("");
   lines.push("agent:");
   lines.push("  max_concurrent_agents: 10");
   lines.push("  max_retry_backoff_ms: 30000");
   lines.push("  retry_base_delay_ms: 10000");
   lines.push("  max_turns: 20");
+  lines.push("codex:");
+  lines.push("  command: codex app-server");
+  lines.push("  read_timeout_ms: 5000");
+  lines.push("  turn_timeout_ms: 3600000");
+  lines.push("  stall_timeout_ms: 300000");
+  lines.push("```");
   lines.push("");
-  lines.push(...buildRuntimeFrontMatter(input.runtime));
+  lines.push("## Supported Template Variables");
   lines.push("");
-  lines.push("---");
+  lines.push("Use these in the WORKFLOW.md prompt body (double-brace syntax):");
+  lines.push("");
+  lines.push("| Variable | Description |");
+  lines.push("|----------|-------------|");
+  lines.push("| `issue.identifier` | e.g. `acme/platform#42` |");
+  lines.push("| `issue.title` | Issue title |");
+  lines.push("| `issue.state` | Current tracker state |");
+  lines.push("| `issue.description` | Issue body |");
+  lines.push("| `issue.url` | Issue URL |");
+  lines.push("| `issue.repository` | `owner/name` |");
+  lines.push("| `issue.number` | Issue number |");
+  lines.push("| `attempt` | Retry attempt number (null on first run) |");
   lines.push("");
-  lines.push("# \u2550\u2550\u2550 PROMPT BODY REFERENCE \u2550\u2550\u2550");
   lines.push(
-    "# GitHub Project adaptation of the Elixir Symphony reference prompt."
+    "**Important**: Only these 8 variables are supported. Using any other variable"
   );
+  lines.push("will cause a runtime error (strict mode validation).");
   lines.push("");
-  lines.push("## Status Map");
-  lines.push("");
-  lines.push("| Status | Role | Agent Action |");
-  lines.push("| ------ | ---- | ------------ |");
-  for (const col of input.statusColumns) {
-    const roleLabel = col.role ?? "unset";
-    const action = resolveRoleAction(col.role);
-    lines.push(`| ${col.name} | ${roleLabel} | ${action} |`);
-  }
-  if (waitColumns.length > 0) {
-    lines.push("");
-    lines.push("**Wait States (awaiting PR review):**");
-    for (const col of waitColumns) {
-      lines.push(
-        `- **${col.name}**: PR created. Awaiting human review. Agent is idle.`
-      );
-    }
-  }
+  lines.push("## Related Skills");
   lines.push("");
-  lines.push("## Repository Validation Guidance");
-  lines.push("");
-  for (const line of buildRepositoryValidationGuidance(
-    input.detectedEnvironment
-  )) {
-    lines.push(`- ${line}`);
-  }
-  lines.push("");
-  lines.push("## Default Posture");
-  lines.push("");
-  lines.push(
-    "1. This is an unattended orchestration session. Do not ask humans for follow-up tasks."
-  );
-  lines.push(
-    "2. Exit early only for genuine blockers (missing required credentials or secrets)."
-  );
-  lines.push(
-    '3. In your final message, report only completed work and blockers. Do not include "next steps".'
-  );
-  lines.push(
-    "4. Do not modify the issue body for planning or progress-tracking purposes."
-  );
-  lines.push(
-    "5. If the issue is in a terminal state, do nothing and exit immediately."
-  );
-  lines.push(
-    "6. If you discover out-of-scope improvements, open a separate issue rather than expanding the current scope."
-  );
-  lines.push(
-    "7. Keep all commits as logical units and follow conventional commit format."
-  );
-  lines.push("8. Do not make commits that break existing tests.");
-  lines.push("9. Verify all existing tests pass before creating a PR.");
-  lines.push("10. Create a workpad as an issue comment to track progress.");
-  lines.push("11. Use the gh-project skill to manage issue status.");
   lines.push(
-    "12. When a blocker is found, record it in an issue comment and transition the status appropriately."
+    "- `/gh-project` \u2014 interact with GitHub Project v2 board (status transitions, workpad comments)"
   );
   lines.push(
-    "13. Once your work is complete and the PR is merged, transition the issue to the Done state."
+    "- `/commit` \u2014 produce clean, logical commits during implementation"
   );
+  lines.push("- `/push` \u2014 keep remote branch current and publish updates");
+  lines.push("- `/pull` \u2014 sync branch with latest origin/main before handoff");
+  lines.push("- `/land` \u2014 merge approved PR and transition issue to Done");
+  return renderSkillDocument({
+    name: "gh-symphony",
+    description: "Design, refine, and validate repository WORKFLOW.md files for GitHub Symphony projects.",
+    bodyLines: lines
+  });
+}
+
+// src/skills/templates/gh-project.ts
+function generateGhProjectSkill(ctx) {
+  const lines = [];
+  lines.push("# /gh-project \u2014 GitHub Project v2 Status Management");
   lines.push("");
-  lines.push("## Related Skills");
+  lines.push("## Purpose");
   lines.push("");
   lines.push(
-    "- **gh-project**: Manage GitHub Project v2 issue status and update fields"
-  );
-  lines.push(
-    "- **commit**: Create logical-unit commits (conventional commit format)"
+    "Interact with the GitHub Project v2 board to manage issue status,"
   );
-  lines.push("- **push**: Push branch and sync with the remote repository");
-  lines.push("- **pull**: Fetch latest changes and resolve conflicts");
-  lines.push("- **land**: Create PR, request review, and handle merge");
-  lines.push("");
-  lines.push("## Step 0: Determine current state and route");
+  lines.push("create workpad comments, and handle follow-up issues.");
   lines.push("");
-  lines.push(
-    "Check the current issue state and route to the appropriate step:"
-  );
+  lines.push("## Prerequisites");
   lines.push("");
-  if (terminalColumns.length > 0) {
-    const terminalNames = terminalColumns.map((c) => c.name).join(", ");
-    lines.push(`- **${terminalNames}** \u2192 Exit immediately. Do nothing.`);
-  }
-  if (waitColumns.length > 0) {
-    const waitNames = waitColumns.map((c) => c.name).join(", ");
-    lines.push(`- **${waitNames}** \u2192 Go to Step 3 (handle awaiting review).`);
-  }
-  if (activeColumns.length > 0) {
-    const activeNames = activeColumns.map((c) => c.name).join(", ");
-    lines.push(
-      `- **${activeNames}** \u2192 Go to Step 1 (start or continue execution).`
-    );
-  }
+  lines.push("- `gh` CLI is authenticated (`gh auth status`)");
   lines.push(
-    "- **Other states** \u2192 Log the unclear state in an issue comment and exit."
+    "- This generated skill contains the status field and option IDs below"
   );
   lines.push("");
-  lines.push("## Step 1: Start/continue execution");
+  lines.push("## Column ID Quick Reference");
   lines.push("");
-  lines.push(
-    "1. Read the issue body and comments to understand current progress."
-  );
-  lines.push(
-    "2. If an existing workpad comment is found, continue from it; otherwise create a new workpad."
-  );
-  lines.push(
-    "3. See the 'Workpad Template' section below for the workpad format."
-  );
-  lines.push(
-    "4. If no branch exists, create a feature branch based on `{issue.repository}`."
-  );
-  lines.push("5. Proceed to Step 2.");
+  lines.push(`Status Field ID: \`${ctx.statusFieldId}\``);
   lines.push("");
-  lines.push("## Step 2: Execution phase");
+  lines.push("| Column Name | Role | Option ID |");
+  lines.push("|-------------|------|-----------|");
+  for (const col of ctx.statusColumns) {
+    const role = col.role ?? "unknown";
+    lines.push(`| ${col.name} | ${role} | \`${col.id}\` |`);
+  }
   lines.push("");
-  lines.push("1. Implement according to the issue description.");
-  lines.push(
-    "2. Commit changes in logical units (conventional commit format)."
-  );
-  lines.push("3. Verify all existing tests pass.");
-  lines.push("4. Write tests for new functionality.");
-  lines.push("5. Once all Completion Bar criteria are met, create a PR.");
-  lines.push(
-    "6. After creating the PR, transition the issue status to the Human Review state."
-  );
-  lines.push("7. Proceed to Step 3.");
+  lines.push("## Operations");
   lines.push("");
-  lines.push("## Step 3: Human Review and merge handling");
+  lines.push("### Change Issue Status");
   lines.push("");
-  lines.push("1. If a PR already exists, check for review comments.");
-  lines.push(
-    "2. If no review comments are present, remain in the waiting state."
-  );
   lines.push(
-    "3. If the PR is merged, transition the issue to a terminal state."
+    "Use `gh project item-edit` with the field ID and option ID from the table above:"
   );
-  lines.push("4. If review changes are requested, proceed to Step 4.");
-  lines.push("");
-  lines.push("## Step 4: Rework handling");
   lines.push("");
+  lines.push("```bash");
+  lines.push("# Get the project item ID for an issue");
   lines.push(
-    "1. Read all PR review comments and identify the requested changes."
+    "gh project item-list <project-number> --owner <owner> --format json \\"
   );
   lines.push(
-    "2. Process the changes following the PR Feedback Sweep Protocol."
+    "  | jq '.items[] | select(.content.number == <issue-number>) | .id'"
   );
-  lines.push("3. After implementing changes, commit and update the PR.");
-  lines.push("4. Transition the issue status back to the Human Review state.");
-  lines.push("5. Return to Step 3.");
   lines.push("");
-  lines.push("## PR Feedback Sweep Protocol");
+  lines.push("# Update the status field");
+  lines.push(`gh project item-edit \\`);
+  lines.push(`  --project-id ${ctx.projectId} \\`);
+  lines.push(`  --id <item-id> \\`);
+  lines.push(`  --field-id ${ctx.statusFieldId} \\`);
+  lines.push(`  --single-select-option-id <option-id-from-table-above>`);
+  lines.push("```");
   lines.push("");
-  lines.push("Order for processing PR review feedback:");
+  lines.push("### Create Workpad Comment");
   lines.push("");
+  lines.push("```bash");
   lines.push(
-    "1. **Collect all comments**: List all unresolved review comments."
-  );
-  lines.push(
-    "2. **Triage by priority**: Handle blocking comments before non-blocking ones."
-  );
-  lines.push(
-    "3. **Implement changes**: Make the code changes corresponding to each comment."
-  );
-  lines.push(
-    "4. **Reply to comments**: Respond to each review comment with a description of what was done."
+    'gh issue comment <issue-number> --repo <owner>/<repo> --body "## Workpad\\n\\n### Plan\\n- [ ] Task 1"'
   );
+  lines.push("```");
+  lines.push("");
+  lines.push("### Update Existing Comment");
+  lines.push("");
+  lines.push("```bash");
   lines.push(
-    "5. **Commit**: Commit changes in `fix: address PR review feedback` format."
+    "gh api -X PATCH /repos/<owner>/<repo>/issues/comments/<comment-id> \\"
   );
-  lines.push("6. **Request re-review**: Ask the reviewer for a re-review.");
+  lines.push('  -f body="## Workpad\\n\\n### Plan\\n- [x] Task 1 (done)"');
+  lines.push("```");
   lines.push("");
-  lines.push("## Completion Bar");
+  lines.push("### Create Follow-up Issue");
   lines.push("");
-  lines.push("All of the following must be satisfied before creating a PR:");
+  lines.push("```bash");
+  lines.push("gh issue create --repo <owner>/<repo> \\");
+  lines.push('  --title "Follow-up: <title>" \\');
+  lines.push('  --body "<description>" \\');
+  lines.push('  --label "backlog"');
+  lines.push("```");
+  lines.push("");
+  lines.push("### Add Label");
   lines.push("");
+  lines.push("```bash");
   lines.push(
-    "- [ ] All requirements from the issue description are implemented."
+    'gh issue edit <issue-number> --repo <owner>/<repo> --add-label "<label>"'
   );
-  lines.push("- [ ] All existing tests pass.");
-  lines.push("- [ ] Tests are written for new functionality.");
-  lines.push("- [ ] Code style follows project conventions.");
-  lines.push("- [ ] The PR description clearly explains the changes.");
-  lines.push("- [ ] Related documentation is updated (if applicable).");
+  lines.push("```");
   lines.push("");
-  lines.push("## Guardrails");
+  lines.push("## Rules");
   lines.push("");
-  lines.push("- **Scope**: Never make changes outside the scope of the issue.");
   lines.push(
-    "- **Secrets**: Never hardcode tokens, passwords, or API keys in code."
+    "- Always follow the WORKFLOW.md status map flow for state transitions"
   );
   lines.push(
-    "- **Breaking changes**: Do not modify existing APIs or interfaces without explicit authorization."
+    "- Before transitioning to a terminal state, verify the Completion Bar is satisfied:"
   );
-  lines.push("- **Force push**: Do not force-push to the main/master branch.");
+  lines.push("  - All acceptance criteria checked");
+  lines.push("  - All tests passing");
+  lines.push("  - PR merged (if applicable)");
   lines.push(
-    "- **Issue body**: Do not modify the issue body for progress tracking."
+    "- Use the Column ID Quick Reference table above for all status transitions"
   );
   lines.push(
-    "- **Infinite loops**: If the same task fails 3 or more consecutive times, log it as a blocker and exit."
+    "- Do not transition issues to terminal states without explicit completion verification"
   );
+  return renderSkillDocument({
+    name: "gh-project",
+    description: "Manage GitHub Project v2 issue states, workpad comments, and related follow-up actions.",
+    bodyLines: lines
+  });
+}
+
+// src/skills/templates/commit.ts
+function generateCommitSkill(_ctx) {
+  const lines = [];
+  lines.push("# /commit \u2014 Clean Commit Workflow");
   lines.push("");
-  lines.push("## Workpad Template");
-  lines.push("");
-  lines.push("Workpad format to create as an issue comment:");
+  lines.push("## Trigger");
   lines.push("");
-  lines.push("```markdown");
-  lines.push("## Workpad \u2014 {issue.identifier}");
+  lines.push("Use this skill when creating commits during implementation.");
   lines.push("");
-  lines.push("**Status**: {current phase}");
-  lines.push("**Branch**: {branch name}");
-  lines.push("**PR**: {PR URL or not created}");
+  lines.push("## Rules");
   lines.push("");
-  lines.push("### Plan");
+  lines.push("- Commit in logical units \u2014 one concern per commit");
+  lines.push("- Never commit a broken intermediate state (tests must pass)");
+  lines.push("- Never commit temporary debug code or commented-out blocks");
+  lines.push("- Run tests before every commit");
   lines.push("");
-  lines.push("- [ ] {task 1}");
-  lines.push("- [ ] {task 2}");
+  lines.push("## Format");
   lines.push("");
-  lines.push("### Progress Log");
+  lines.push("Use Conventional Commit format:");
   lines.push("");
-  lines.push("- {timestamp}: {action taken}");
+  lines.push("```");
+  lines.push("<type>(<scope>): <description>");
   lines.push("");
-  lines.push("### Blockers");
+  lines.push("[optional body \u2014 explain WHY, not WHAT, 72 chars/line]");
   lines.push("");
-  lines.push("None");
+  lines.push("[optional footer: Closes #N]");
   lines.push("```");
   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") {
-    lines.push(
-      "  # Priority is explicit. Numbers below are editable policy (lower = higher priority)."
-    );
-  } else {
-    lines.push(
-      "  # Priority dispatch is disabled until an operator chooses one explicit source."
-    );
-  }
+  lines.push("**Types**: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`");
+  lines.push("");
   lines.push(
-    "  # See docs/adr/2026-05-18_explicit-dispatch-priority-mappings.md"
+    "**Description**: imperative mood, 50 chars max, no period at end"
   );
-  if (priority?.source === "project-field") {
-    lines.push("  priority:");
-    lines.push("    source: project-field");
-    lines.push(`    field: ${JSON.stringify(priority.field)}`);
-    lines.push("    values:");
-    for (const [name, value] of Object.entries(priority.values)) {
-      lines.push(`      ${JSON.stringify(name)}: ${value}`);
-    }
-    return lines;
-  }
-  if (priority?.source === "labels") {
-    lines.push("  priority:");
-    lines.push("    source: labels");
-    lines.push("    labels:");
-    for (const [name, value] of Object.entries(priority.labels)) {
-      lines.push(`      ${JSON.stringify(name)}: ${value}`);
-    }
-    return lines;
-  }
-  lines.push("  priority:");
-  lines.push("    source: disabled");
   lines.push("");
-  lines.push("  # Optional template: project-field priority source.");
-  lines.push("  # priority:");
-  lines.push("  #   source: project-field");
-  lines.push("  #   field: Priority");
-  lines.push("  #   values:");
-  lines.push("  #     Urgent: 0");
-  lines.push("  #     High: 1");
+  lines.push("## Examples");
   lines.push("");
-  lines.push("  # Optional template: labels priority source.");
-  lines.push("  # priority:");
-  lines.push("  #   source: labels");
-  lines.push("  #   labels:");
-  lines.push("  #     P0: 0");
-  lines.push("  #     P1: 1");
-  return lines;
-}
-function resolveRoleAction(role) {
-  switch (role) {
-    case "active":
-      return "Agent starts work immediately. Creates workpad and proceeds with implementation.";
-    case "wait":
-      return "PR created. Awaiting human review. Agent is idle.";
-    case "terminal":
-      return "Completed state. Agent exits.";
-    case null:
-      return "Role unset. Must be explicitly configured in WORKFLOW.md.";
-  }
-}
-
-// 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";
-function normalizeRuntimeForSkills(runtime) {
-  if (isClaudeRuntime(runtime)) {
-    return "claude-code";
-  }
-  if (isCodexRuntime(runtime)) {
-    return "codex";
-  }
-  return null;
-}
-function resolveSkillsDir(repoRoot, runtime) {
-  const normalizedRuntime = normalizeRuntimeForSkills(runtime);
-  if (normalizedRuntime === "claude-code") {
-    return join2(repoRoot, ".claude", "skills");
-  }
-  if (normalizedRuntime === "codex") {
-    return join2(repoRoot, ".codex", "skills");
-  }
-  return null;
-}
-function buildSkillFilePlans(repoRoot, runtime, templates, context) {
-  const skillsDir = resolveSkillsDir(repoRoot, runtime);
-  if (!skillsDir) {
-    return { skillsDir: null, files: [] };
-  }
-  return {
-    skillsDir,
-    files: templates.map((template) => ({
-      path: join2(skillsDir, template.name, template.fileName),
-      content: template.generate(context)
-    }))
-  };
+  lines.push("```");
+  lines.push("feat(auth): add OAuth2 token refresh");
+  lines.push("fix(api): handle null response from upstream");
+  lines.push("test(worker): add retry exhaustion coverage");
+  lines.push("```");
+  return renderSkillDocument({
+    name: "commit",
+    description: "Create clean, logically scoped commits that keep the repository in a shippable state.",
+    bodyLines: lines
+  });
 }
 
-// src/skills/templates/document.ts
-function renderSkillDocument(options) {
-  const { name, description, bodyLines } = options;
-  return [
-    "---",
-    `name: ${name}`,
-    `description: ${description}`,
-    "license: MIT",
-    "metadata:",
-    "  author: gh-symphony",
-    '  version: "1.0"',
-    '  generatedBy: "gh-symphony"',
-    "---",
-    "",
-    ...bodyLines
-  ].join("\n");
+// src/skills/templates/push.ts
+function generatePushSkill(_ctx) {
+  const lines = [];
+  lines.push("# /push \u2014 Git Push Workflow");
+  lines.push("");
+  lines.push("## Trigger");
+  lines.push("");
+  lines.push(
+    "Use this skill when publishing local commits to the remote branch."
+  );
+  lines.push("");
+  lines.push("## Flow");
+  lines.push("");
+  lines.push("1. Run local tests and lint \u2014 ensure they pass before pushing");
+  lines.push("2. Push to remote:");
+  lines.push("   ```bash");
+  lines.push("   git push origin <branch>        # subsequent pushes");
+  lines.push("   git push -u origin <branch>     # first push (sets upstream)");
+  lines.push("   ```");
+  lines.push("3. If push is rejected (non-fast-forward):");
+  lines.push("   - Run `git fetch origin && git merge origin/main`");
+  lines.push("   - Resolve any conflicts");
+  lines.push("   - Re-run tests");
+  lines.push("   - Push again");
+  lines.push("4. Record push result in workpad Notes");
+  lines.push("");
+  lines.push("## Rules");
+  lines.push("");
+  lines.push("- Never use `--force` (destructive)");
+  lines.push(
+    "- Only use `--force-with-lease` if absolutely necessary \u2014 record the reason in workpad"
+  );
+  lines.push("- Verify CI starts after push (check GitHub Actions tab)");
+  lines.push("- Do not push directly to `main` or `master`");
+  return renderSkillDocument({
+    name: "push",
+    description: "Publish verified local commits to the remote branch without unsafe force pushes.",
+    bodyLines: lines
+  });
 }
 
-// src/skills/templates/gh-symphony.ts
-function generateGhSymphonySkill(ctx) {
+// src/skills/templates/pull.ts
+function generatePullSkill(_ctx) {
   const lines = [];
-  lines.push("# /gh-symphony \u2014 WORKFLOW.md Design & Refinement");
+  lines.push("# /pull \u2014 Git Pull / Sync Workflow");
   lines.push("");
   lines.push("## Trigger");
   lines.push("");
-  lines.push("Use this skill when you want to:");
-  lines.push("- Create a new WORKFLOW.md for a GitHub Symphony project");
-  lines.push("- Refine or improve an existing WORKFLOW.md");
-  lines.push("- Validate that a WORKFLOW.md is correctly structured");
+  lines.push(
+    "Use this skill to sync the current branch with the latest `origin/main`"
+  );
+  lines.push("before starting work or before creating a PR.");
   lines.push("");
-  lines.push("## Prerequisites");
+  lines.push("## Flow");
   lines.push("");
+  lines.push("1. Fetch latest from remote:");
+  lines.push("   ```bash");
+  lines.push("   git fetch origin");
+  lines.push("   ```");
+  lines.push("2. Merge into current branch:");
+  lines.push("   ```bash");
+  lines.push("   git merge origin/main");
+  lines.push("   ```");
+  lines.push("3. If conflicts arise:");
+  lines.push("   - Resolve each conflict file");
+  lines.push("   - Run tests to confirm nothing broke");
   lines.push(
-    `- \`${ctx.contextYamlPath}\` must exist (contains GitHub Project metadata)`
+    "   - Commit the merge: `git commit` (merge commit message is auto-generated)"
   );
   lines.push(
-    `- \`${ctx.referenceWorkflowPath}\` must exist (annotated reference template)`
+    "4. Re-run tests after merge to confirm the integrated state is clean"
   );
-  lines.push("- `gh` CLI must be authenticated");
+  lines.push("5. Record pull skill evidence in workpad Notes:");
+  lines.push("   - merge source (e.g. `origin/main`)");
+  lines.push("   - result: `clean` or `conflicts resolved`");
+  lines.push("   - resulting HEAD short SHA: `git rev-parse --short HEAD`");
   lines.push("");
-  lines.push("## Repository Validation Guidance");
+  lines.push("## Rules");
+  lines.push("");
+  lines.push("- Always pull before creating a PR");
+  lines.push("- Always pull at the start of a new work session");
+  lines.push("- Record the pull evidence in the workpad before proceeding");
+  return renderSkillDocument({
+    name: "pull",
+    description: "Sync the current branch with the latest remote base before implementation or review handoff.",
+    bodyLines: lines
+  });
+}
+
+// src/skills/templates/land.ts
+function generateLandSkill(_ctx) {
+  const lines = [];
+  lines.push("# /land \u2014 PR Merge Workflow");
+  lines.push("");
+  lines.push("## Trigger");
   lines.push("");
   lines.push(
-    "Carry the detected repository validation posture into any new or refined `WORKFLOW.md` instead of falling back to generic instructions."
+    "Use this skill when the issue is in the Merging state (PR approved by human)."
+  );
+  lines.push(
+    "Do NOT call `gh pr merge` directly \u2014 always go through this flow."
   );
-  for (const line of buildRepositoryValidationGuidance(
-    ctx.detectedEnvironment
-  )) {
-    lines.push(`- ${line}`);
-  }
   lines.push("");
-  lines.push("## Mode Detection");
+  lines.push("## Pre-flight Checks");
   lines.push("");
-  lines.push("Check if `WORKFLOW.md` exists in the current directory:");
-  lines.push("- **Not found** \u2192 enter **Design Mode** (create from scratch)");
-  lines.push("- **Found** \u2192 ask user: refine existing or validate only?");
-  lines.push("  - Refine \u2192 enter **Refine Mode**");
-  lines.push("  - Validate \u2192 enter **Validate Mode**");
+  lines.push("Before merging, verify ALL of the following:");
   lines.push("");
-  lines.push("## Design Mode");
+  lines.push("1. **PR is approved**:");
+  lines.push("   ```bash");
+  lines.push(
+    `   gh pr view --json reviews --jq '.reviews[] | select(.state == "APPROVED")'`
+  );
+  lines.push("   ```");
+  lines.push("2. **All CI checks are green**:");
+  lines.push("   ```bash");
+  lines.push("   gh pr checks");
+  lines.push("   ```");
+  lines.push("3. **Branch is up-to-date with base**:");
+  lines.push("   ```bash");
+  lines.push(
+    "   git fetch origin && git merge-base --is-ancestor origin/main HEAD"
+  );
+  lines.push("   ```");
+  lines.push("   If not up-to-date, run the `/pull` skill first.");
   lines.push("");
+  lines.push("## Flow");
+  lines.push("");
+  lines.push("1. Run all pre-flight checks above");
+  lines.push("2. If all checks pass, merge the PR:");
+  lines.push("   ```bash");
+  lines.push("   gh pr merge --squash    # squash merge (default)");
+  lines.push("   # or: gh pr merge --merge   # merge commit");
+  lines.push("   # or: gh pr merge --rebase  # rebase merge");
+  lines.push("   ```");
+  lines.push("   Choose the merge strategy per project policy.");
+  lines.push("3. On merge success:");
   lines.push(
-    `1. Read \`${ctx.contextYamlPath}\` to understand the project structure`
+    "   - Use the **gh-project skill** to transition the issue status to Done"
   );
+  lines.push("   - Do NOT call status APIs directly \u2014 delegate to gh-project");
+  lines.push("4. On merge failure:");
+  lines.push("   - Record the failure reason in workpad Notes");
+  lines.push("   - Resolve the blocking issue (re-run pre-flight checks)");
+  lines.push("   - Retry the merge");
+  lines.push("5. Loop until merged or blocked by an unresolvable issue");
+  lines.push("");
+  lines.push("## Rules");
+  lines.push("");
+  lines.push("- Never call `gh pr merge` without completing pre-flight checks");
   lines.push(
-    `2. Read \`${ctx.referenceWorkflowPath}\` as the annotated reference`
+    "- Status transition to Done MUST go through the gh-project skill"
   );
-  lines.push("3. Ask the user these key 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(
-    "4. Generate WORKFLOW.md using the reference as a structural guide"
+    "- If any pre-flight check fails, do not merge \u2014 fix the issue first"
+  );
+  lines.push("- Record all merge attempts and outcomes in the workpad");
+  return renderSkillDocument({
+    name: "land",
+    description: "Merge approved pull requests safely after verifying approvals, CI, and branch freshness.",
+    bodyLines: lines
+  });
+}
+
+// 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/workflow/generate-reference-workflow.ts
+function generateReferenceWorkflow(input) {
+  const lines = [];
+  lines.push("# Reference WORKFLOW.md \u2014 gh-symphony");
+  lines.push("# This file is a reference template for authoring WORKFLOW.md.");
+  lines.push(
+    "# AI agents reference this file (via the /gh-symphony skill) when designing WORKFLOW.md."
   );
-  lines.push("5. Validate the generated file (see Validate Mode)");
+  lines.push("# Do not edit this file directly.");
   lines.push("");
-  lines.push("## Refine Mode");
+  lines.push("---");
   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("   - 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("# \u2550\u2550\u2550 FRONT MATTER FIELD REFERENCE \u2550\u2550\u2550");
+  lines.push(
+    "# All front matter fields supported by the gh-symphony parser are listed below."
+  );
   lines.push("");
-  lines.push("## Validate Mode");
+  lines.push("tracker:");
+  lines.push("  kind: github-project");
+  lines.push(`  project_id: ${input.projectId}`);
+  lines.push("  state_field: Status");
+  lines.push(...buildReferencePriorityLines(input.priority));
   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)"
+  const activeColumns = input.statusColumns.filter((c) => c.role === "active");
+  const waitColumns = input.statusColumns.filter((c) => c.role === "wait");
+  const terminalColumns = input.statusColumns.filter(
+    (c) => c.role === "terminal"
   );
+  const blockerCheckStates = input.lifecycle?.blockerCheckStates ?? [];
+  const planningStates = input.lifecycle?.planningStates ?? blockerCheckStates;
+  if (activeColumns.length > 0) {
+    lines.push("  active_states:");
+    for (const col of activeColumns) {
+      lines.push(`    - ${col.name}`);
+    }
+  } else {
+    lines.push("  active_states: [{active column names}]");
+  }
+  if (terminalColumns.length > 0) {
+    lines.push("  terminal_states:");
+    for (const col of terminalColumns) {
+      lines.push(`    - ${col.name}`);
+    }
+  } else {
+    lines.push("  terminal_states: [{terminal column names}]");
+  }
   lines.push(
-    "- Template variables use only supported names (see Supported Template Variables)"
+    ...buildReferenceStringList("blocker_check_states", blockerCheckStates)
   );
-  lines.push("- Status Map matches the lifecycle configuration");
+  lines.push(...buildReferenceStringList("planning_states", planningStates));
+  lines.push("");
+  lines.push("# Linear tracker example:");
+  lines.push("# tracker:");
+  lines.push("#   kind: linear");
+  lines.push("#   endpoint: https://api.linear.app/graphql");
+  lines.push("#   api_key: $LINEAR_API_KEY");
+  lines.push("#   project_slug: symphony-0c79b11b75ea");
+  lines.push("#   active_states:");
+  lines.push("#     - Todo");
+  lines.push("#     - In Progress");
+  lines.push("#   terminal_states:");
+  lines.push("#     - Done");
+  lines.push("#     - Canceled");
+  lines.push("#     - Duplicate");
   lines.push(
-    "- No unsupported double-brace variable patterns (only the 8 listed below are valid)"
+    "# Linear uses repository-local polling; gh-symphony does not provide"
   );
+  lines.push("# a Linear webhook setup command.");
   lines.push("");
-  lines.push("## Supported Front Matter Fields");
-  lines.push("");
-  lines.push("```yaml");
-  lines.push("tracker:");
-  lines.push("  kind: github-project");
-  lines.push("  project_id: PVT_xxx");
-  lines.push("  state_field: Status");
-  lines.push("  active_states: [Todo, In Progress]");
-  lines.push("  terminal_states: [Done, Cancelled]");
-  lines.push("  blocker_check_states: [Blocked]");
   lines.push("polling:");
   lines.push("  interval_ms: 30000");
+  lines.push("");
   lines.push("workspace:");
   lines.push("  root: .runtime/symphony-workspaces");
+  lines.push("");
   lines.push("hooks:");
-  lines.push("  after_create: |");
-  lines.push("    git clone --depth 1 https://github.com/owner/repo .");
+  lines.push(
+    `  after_create: ${DEFAULT_AFTER_CREATE_HOOK_PATH}  # ${DEFAULT_AFTER_CREATE_HOOK_COMMENT}`
+  );
   lines.push("  before_run: null");
   lines.push("  after_run: null");
   lines.push("  before_remove: null");
   lines.push("  timeout_ms: 60000");
+  lines.push("");
   lines.push("agent:");
   lines.push("  max_concurrent_agents: 10");
   lines.push("  max_retry_backoff_ms: 30000");
   lines.push("  retry_base_delay_ms: 10000");
   lines.push("  max_turns: 20");
-  lines.push("codex:");
-  lines.push("  command: codex app-server");
-  lines.push("  read_timeout_ms: 5000");
-  lines.push("  turn_timeout_ms: 3600000");
-  lines.push("  stall_timeout_ms: 300000");
-  lines.push("```");
-  lines.push("");
-  lines.push("## Supported Template Variables");
   lines.push("");
-  lines.push("Use these in the WORKFLOW.md prompt body (double-brace syntax):");
+  lines.push(...buildRuntimeFrontMatter(input.runtime));
   lines.push("");
-  lines.push("| Variable | Description |");
-  lines.push("|----------|-------------|");
-  lines.push("| `issue.identifier` | e.g. `acme/platform#42` |");
-  lines.push("| `issue.title` | Issue title |");
-  lines.push("| `issue.state` | Current tracker state |");
-  lines.push("| `issue.description` | Issue body |");
-  lines.push("| `issue.url` | Issue URL |");
-  lines.push("| `issue.repository` | `owner/name` |");
-  lines.push("| `issue.number` | Issue number |");
-  lines.push("| `attempt` | Retry attempt number (null on first run) |");
+  lines.push("---");
   lines.push("");
+  lines.push("# \u2550\u2550\u2550 PROMPT BODY REFERENCE \u2550\u2550\u2550");
   lines.push(
-    "**Important**: Only these 8 variables are supported. Using any other variable"
+    "# GitHub Project adaptation of the Elixir Symphony reference prompt."
   );
-  lines.push("will cause a runtime error (strict mode validation).");
   lines.push("");
-  lines.push("## Related Skills");
+  lines.push("## Status Map");
+  lines.push("");
+  lines.push("| Status | Role | Agent Action |");
+  lines.push("| ------ | ---- | ------------ |");
+  for (const col of input.statusColumns) {
+    const roleLabel = col.role ?? "unset";
+    const action = resolveRoleAction(col.role);
+    lines.push(`| ${col.name} | ${roleLabel} | ${action} |`);
+  }
+  if (waitColumns.length > 0) {
+    lines.push("");
+    lines.push("**Wait States (awaiting PR review):**");
+    for (const col of waitColumns) {
+      lines.push(
+        `- **${col.name}**: PR created. Awaiting human review. Agent is idle.`
+      );
+    }
+  }
+  lines.push("");
+  lines.push("## Repository Validation Guidance");
+  lines.push("");
+  for (const line of buildRepositoryValidationGuidance(
+    input.detectedEnvironment
+  )) {
+    lines.push(`- ${line}`);
+  }
+  lines.push("");
+  lines.push("## Default Posture");
   lines.push("");
   lines.push(
-    "- `/gh-project` \u2014 interact with GitHub Project v2 board (status transitions, workpad comments)"
+    "1. This is an unattended orchestration session. Do not ask humans for follow-up tasks."
   );
   lines.push(
-    "- `/commit` \u2014 produce clean, logical commits during implementation"
+    "2. Exit early only for genuine blockers (missing required credentials or secrets)."
   );
-  lines.push("- `/push` \u2014 keep remote branch current and publish updates");
-  lines.push("- `/pull` \u2014 sync branch with latest origin/main before handoff");
-  lines.push("- `/land` \u2014 merge approved PR and transition issue to Done");
-  return renderSkillDocument({
-    name: "gh-symphony",
-    description: "Design, refine, and validate repository WORKFLOW.md files for GitHub Symphony projects.",
-    bodyLines: lines
-  });
-}
-
-// src/skills/templates/gh-project.ts
-function generateGhProjectSkill(ctx) {
-  const lines = [];
-  lines.push("# /gh-project \u2014 GitHub Project v2 Status Management");
-  lines.push("");
-  lines.push("## Purpose");
-  lines.push("");
   lines.push(
-    "Interact with the GitHub Project v2 board to manage issue status,"
+    '3. In your final message, report only completed work and blockers. Do not include "next steps".'
   );
-  lines.push("create workpad comments, and handle follow-up issues.");
-  lines.push("");
-  lines.push("## Prerequisites");
-  lines.push("");
-  lines.push("- `gh` CLI is authenticated (`gh auth status`)");
   lines.push(
-    `- \`${ctx.contextYamlPath}\` exists with field IDs and option IDs`
+    "4. Do not modify the issue body for planning or progress-tracking purposes."
   );
-  lines.push("");
-  lines.push("## Column ID Quick Reference");
-  lines.push("");
-  lines.push(`Status Field ID: \`${ctx.statusFieldId}\``);
-  lines.push("");
-  lines.push("| Column Name | Role | Option ID |");
-  lines.push("|-------------|------|-----------|");
-  for (const col of ctx.statusColumns) {
-    const role = col.role ?? "unknown";
-    lines.push(`| ${col.name} | ${role} | \`${col.id}\` |`);
-  }
-  lines.push("");
-  lines.push("## Operations");
-  lines.push("");
-  lines.push("### Change Issue Status");
-  lines.push("");
   lines.push(
-    "Use `gh project item-edit` with the field ID and option ID from the table above:"
+    "5. If the issue is in a terminal state, do nothing and exit immediately."
   );
-  lines.push("");
-  lines.push("```bash");
-  lines.push("# Get the project item ID for an issue");
   lines.push(
-    "gh project item-list <project-number> --owner <owner> --format json \\"
+    "6. If you discover out-of-scope improvements, open a separate issue rather than expanding the current scope."
   );
   lines.push(
-    "  | jq '.items[] | select(.content.number == <issue-number>) | .id'"
+    "7. Keep all commits as logical units and follow conventional commit format."
   );
-  lines.push("");
-  lines.push("# Update the status field");
-  lines.push(`gh project item-edit \\`);
-  lines.push(`  --project-id ${ctx.projectId} \\`);
-  lines.push(`  --id <item-id> \\`);
-  lines.push(`  --field-id ${ctx.statusFieldId} \\`);
-  lines.push(`  --single-select-option-id <option-id-from-table-above>`);
-  lines.push("```");
-  lines.push("");
-  lines.push("### Create Workpad Comment");
-  lines.push("");
-  lines.push("```bash");
+  lines.push("8. Do not make commits that break existing tests.");
+  lines.push("9. Verify all existing tests pass before creating a PR.");
+  lines.push("10. Create a workpad as an issue comment to track progress.");
+  lines.push("11. Use the gh-project skill to manage issue status.");
   lines.push(
-    'gh issue comment <issue-number> --repo <owner>/<repo> --body "## Workpad\\n\\n### Plan\\n- [ ] Task 1"'
+    "12. When a blocker is found, record it in an issue comment and transition the status appropriately."
+  );
+  lines.push(
+    "13. Once your work is complete and the PR is merged, transition the issue to the Done state."
   );
-  lines.push("```");
   lines.push("");
-  lines.push("### Update Existing Comment");
+  lines.push("## Related Skills");
   lines.push("");
-  lines.push("```bash");
   lines.push(
-    "gh api -X PATCH /repos/<owner>/<repo>/issues/comments/<comment-id> \\"
+    "- **gh-project**: Manage GitHub Project v2 issue status and update fields"
   );
-  lines.push('  -f body="## Workpad\\n\\n### Plan\\n- [x] Task 1 (done)"');
-  lines.push("```");
-  lines.push("");
-  lines.push("### Create Follow-up Issue");
+  lines.push(
+    "- **commit**: Create logical-unit commits (conventional commit format)"
+  );
+  lines.push("- **push**: Push branch and sync with the remote repository");
+  lines.push("- **pull**: Fetch latest changes and resolve conflicts");
+  lines.push("- **land**: Create PR, request review, and handle merge");
   lines.push("");
-  lines.push("```bash");
-  lines.push("gh issue create --repo <owner>/<repo> \\");
-  lines.push('  --title "Follow-up: <title>" \\');
-  lines.push('  --body "<description>" \\');
-  lines.push('  --label "backlog"');
-  lines.push("```");
+  lines.push("## Step 0: Determine current state and route");
   lines.push("");
-  lines.push("### Add Label");
+  lines.push(
+    "Check the current issue state and route to the appropriate step:"
+  );
   lines.push("");
-  lines.push("```bash");
+  if (terminalColumns.length > 0) {
+    const terminalNames = terminalColumns.map((c) => c.name).join(", ");
+    lines.push(`- **${terminalNames}** \u2192 Exit immediately. Do nothing.`);
+  }
+  if (waitColumns.length > 0) {
+    const waitNames = waitColumns.map((c) => c.name).join(", ");
+    lines.push(`- **${waitNames}** \u2192 Go to Step 3 (handle awaiting review).`);
+  }
+  if (activeColumns.length > 0) {
+    const activeNames = activeColumns.map((c) => c.name).join(", ");
+    lines.push(
+      `- **${activeNames}** \u2192 Go to Step 1 (start or continue execution).`
+    );
+  }
   lines.push(
-    'gh issue edit <issue-number> --repo <owner>/<repo> --add-label "<label>"'
+    "- **Other states** \u2192 Log the unclear state in an issue comment and exit."
   );
-  lines.push("```");
   lines.push("");
-  lines.push("## Rules");
+  lines.push("## Step 1: Start/continue execution");
   lines.push("");
   lines.push(
-    "- Always follow the WORKFLOW.md status map flow for state transitions"
+    "1. Read the issue body and comments to understand current progress."
   );
   lines.push(
-    "- Before transitioning to a terminal state, verify the Completion Bar is satisfied:"
+    "2. If an existing workpad comment is found, continue from it; otherwise create a new workpad."
   );
-  lines.push("  - All acceptance criteria checked");
-  lines.push("  - All tests passing");
-  lines.push("  - PR merged (if applicable)");
   lines.push(
-    "- Use the Column ID Quick Reference table above for all status transitions"
+    "3. See the 'Workpad Template' section below for the workpad format."
   );
   lines.push(
-    "- Do not transition issues to terminal states without explicit completion verification"
+    "4. If no branch exists, create a feature branch based on `{issue.repository}`."
   );
-  return renderSkillDocument({
-    name: "gh-project",
-    description: "Manage GitHub Project v2 issue states, workpad comments, and related follow-up actions.",
-    bodyLines: lines
-  });
-}
-
-// src/skills/templates/commit.ts
-function generateCommitSkill(_ctx) {
-  const lines = [];
-  lines.push("# /commit \u2014 Clean Commit Workflow");
-  lines.push("");
-  lines.push("## Trigger");
-  lines.push("");
-  lines.push("Use this skill when creating commits during implementation.");
-  lines.push("");
-  lines.push("## Rules");
-  lines.push("");
-  lines.push("- Commit in logical units \u2014 one concern per commit");
-  lines.push("- Never commit a broken intermediate state (tests must pass)");
-  lines.push("- Never commit temporary debug code or commented-out blocks");
-  lines.push("- Run tests before every commit");
-  lines.push("");
-  lines.push("## Format");
+  lines.push("5. Proceed to Step 2.");
   lines.push("");
-  lines.push("Use Conventional Commit format:");
+  lines.push("## Step 2: Execution phase");
   lines.push("");
-  lines.push("```");
-  lines.push("<type>(<scope>): <description>");
+  lines.push("1. Implement according to the issue description.");
+  lines.push(
+    "2. Commit changes in logical units (conventional commit format)."
+  );
+  lines.push("3. Verify all existing tests pass.");
+  lines.push("4. Write tests for new functionality.");
+  lines.push("5. Once all Completion Bar criteria are met, create a PR.");
+  lines.push(
+    "6. After creating the PR, transition the issue status to the Human Review state."
+  );
+  lines.push("7. Proceed to Step 3.");
   lines.push("");
-  lines.push("[optional body \u2014 explain WHY, not WHAT, 72 chars/line]");
+  lines.push("## Step 3: Human Review and merge handling");
   lines.push("");
-  lines.push("[optional footer: Closes #N]");
-  lines.push("```");
+  lines.push("1. If a PR already exists, check for review comments.");
+  lines.push(
+    "2. If no review comments are present, remain in the waiting state."
+  );
+  lines.push(
+    "3. If the PR is merged, transition the issue to a terminal state."
+  );
+  lines.push("4. If review changes are requested, proceed to Step 4.");
   lines.push("");
-  lines.push("**Types**: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`");
+  lines.push("## Step 4: Rework handling");
   lines.push("");
   lines.push(
-    "**Description**: imperative mood, 50 chars max, no period at end"
+    "1. Read all PR review comments and identify the requested changes."
   );
+  lines.push(
+    "2. Process the changes following the PR Feedback Sweep Protocol."
+  );
+  lines.push("3. After implementing changes, commit and update the PR.");
+  lines.push("4. Transition the issue status back to the Human Review state.");
+  lines.push("5. Return to Step 3.");
   lines.push("");
-  lines.push("## Examples");
-  lines.push("");
-  lines.push("```");
-  lines.push("feat(auth): add OAuth2 token refresh");
-  lines.push("fix(api): handle null response from upstream");
-  lines.push("test(worker): add retry exhaustion coverage");
-  lines.push("```");
-  return renderSkillDocument({
-    name: "commit",
-    description: "Create clean, logically scoped commits that keep the repository in a shippable state.",
-    bodyLines: lines
-  });
-}
-
-// src/skills/templates/push.ts
-function generatePushSkill(_ctx) {
-  const lines = [];
-  lines.push("# /push \u2014 Git Push Workflow");
+  lines.push("## PR Feedback Sweep Protocol");
   lines.push("");
-  lines.push("## Trigger");
+  lines.push("Order for processing PR review feedback:");
   lines.push("");
   lines.push(
-    "Use this skill when publishing local commits to the remote branch."
+    "1. **Collect all comments**: List all unresolved review comments."
   );
+  lines.push(
+    "2. **Triage by priority**: Handle blocking comments before non-blocking ones."
+  );
+  lines.push(
+    "3. **Implement changes**: Make the code changes corresponding to each comment."
+  );
+  lines.push(
+    "4. **Reply to comments**: Respond to each review comment with a description of what was done."
+  );
+  lines.push(
+    "5. **Commit**: Commit changes in `fix: address PR review feedback` format."
+  );
+  lines.push("6. **Request re-review**: Ask the reviewer for a re-review.");
   lines.push("");
-  lines.push("## Flow");
-  lines.push("");
-  lines.push("1. Run local tests and lint \u2014 ensure they pass before pushing");
-  lines.push("2. Push to remote:");
-  lines.push("   ```bash");
-  lines.push("   git push origin <branch>        # subsequent pushes");
-  lines.push("   git push -u origin <branch>     # first push (sets upstream)");
-  lines.push("   ```");
-  lines.push("3. If push is rejected (non-fast-forward):");
-  lines.push("   - Run `git fetch origin && git merge origin/main`");
-  lines.push("   - Resolve any conflicts");
-  lines.push("   - Re-run tests");
-  lines.push("   - Push again");
-  lines.push("4. Record push result in workpad Notes");
+  lines.push("## Completion Bar");
   lines.push("");
-  lines.push("## Rules");
+  lines.push("All of the following must be satisfied before creating a PR:");
   lines.push("");
-  lines.push("- Never use `--force` (destructive)");
   lines.push(
-    "- Only use `--force-with-lease` if absolutely necessary \u2014 record the reason in workpad"
+    "- [ ] All requirements from the issue description are implemented."
   );
-  lines.push("- Verify CI starts after push (check GitHub Actions tab)");
-  lines.push("- Do not push directly to `main` or `master`");
-  return renderSkillDocument({
-    name: "push",
-    description: "Publish verified local commits to the remote branch without unsafe force pushes.",
-    bodyLines: lines
-  });
-}
-
-// src/skills/templates/pull.ts
-function generatePullSkill(_ctx) {
-  const lines = [];
-  lines.push("# /pull \u2014 Git Pull / Sync Workflow");
+  lines.push("- [ ] All existing tests pass.");
+  lines.push("- [ ] Tests are written for new functionality.");
+  lines.push("- [ ] Code style follows project conventions.");
+  lines.push("- [ ] The PR description clearly explains the changes.");
+  lines.push("- [ ] Related documentation is updated (if applicable).");
   lines.push("");
-  lines.push("## Trigger");
+  lines.push("## Guardrails");
   lines.push("");
+  lines.push("- **Scope**: Never make changes outside the scope of the issue.");
   lines.push(
-    "Use this skill to sync the current branch with the latest `origin/main`"
+    "- **Secrets**: Never hardcode tokens, passwords, or API keys in code."
   );
-  lines.push("before starting work or before creating a PR.");
-  lines.push("");
-  lines.push("## Flow");
-  lines.push("");
-  lines.push("1. Fetch latest from remote:");
-  lines.push("   ```bash");
-  lines.push("   git fetch origin");
-  lines.push("   ```");
-  lines.push("2. Merge into current branch:");
-  lines.push("   ```bash");
-  lines.push("   git merge origin/main");
-  lines.push("   ```");
-  lines.push("3. If conflicts arise:");
-  lines.push("   - Resolve each conflict file");
-  lines.push("   - Run tests to confirm nothing broke");
   lines.push(
-    "   - Commit the merge: `git commit` (merge commit message is auto-generated)"
+    "- **Breaking changes**: Do not modify existing APIs or interfaces without explicit authorization."
   );
+  lines.push("- **Force push**: Do not force-push to the main/master branch.");
   lines.push(
-    "4. Re-run tests after merge to confirm the integrated state is clean"
+    "- **Issue body**: Do not modify the issue body for progress tracking."
+  );
+  lines.push(
+    "- **Infinite loops**: If the same task fails 3 or more consecutive times, log it as a blocker and exit."
   );
-  lines.push("5. Record pull skill evidence in workpad Notes:");
-  lines.push("   - merge source (e.g. `origin/main`)");
-  lines.push("   - result: `clean` or `conflicts resolved`");
-  lines.push("   - resulting HEAD short SHA: `git rev-parse --short HEAD`");
   lines.push("");
-  lines.push("## Rules");
+  lines.push("## Workpad Template");
   lines.push("");
-  lines.push("- Always pull before creating a PR");
-  lines.push("- Always pull at the start of a new work session");
-  lines.push("- Record the pull evidence in the workpad before proceeding");
-  return renderSkillDocument({
-    name: "pull",
-    description: "Sync the current branch with the latest remote base before implementation or review handoff.",
-    bodyLines: lines
-  });
-}
-
-// src/skills/templates/land.ts
-function generateLandSkill(_ctx) {
-  const lines = [];
-  lines.push("# /land \u2014 PR Merge Workflow");
+  lines.push("Workpad format to create as an issue comment:");
   lines.push("");
-  lines.push("## Trigger");
+  lines.push("```markdown");
+  lines.push("## Workpad \u2014 {issue.identifier}");
   lines.push("");
-  lines.push(
-    "Use this skill when the issue is in the Merging state (PR approved by human)."
-  );
-  lines.push(
-    "Do NOT call `gh pr merge` directly \u2014 always go through this flow."
-  );
+  lines.push("**Status**: {current phase}");
+  lines.push("**Branch**: {branch name}");
+  lines.push("**PR**: {PR URL or not created}");
   lines.push("");
-  lines.push("## Pre-flight Checks");
+  lines.push("### Plan");
   lines.push("");
-  lines.push("Before merging, verify ALL of the following:");
+  lines.push("- [ ] {task 1}");
+  lines.push("- [ ] {task 2}");
   lines.push("");
-  lines.push("1. **PR is approved**:");
-  lines.push("   ```bash");
-  lines.push(
-    `   gh pr view --json reviews --jq '.reviews[] | select(.state == "APPROVED")'`
-  );
-  lines.push("   ```");
-  lines.push("2. **All CI checks are green**:");
-  lines.push("   ```bash");
-  lines.push("   gh pr checks");
-  lines.push("   ```");
-  lines.push("3. **Branch is up-to-date with base**:");
-  lines.push("   ```bash");
+  lines.push("### Progress Log");
+  lines.push("");
+  lines.push("- {timestamp}: {action taken}");
+  lines.push("");
+  lines.push("### Blockers");
+  lines.push("");
+  lines.push("None");
+  lines.push("```");
+  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") {
+    lines.push(
+      "  # Priority is explicit. Numbers below are editable policy (lower = higher priority)."
+    );
+  } else {
+    lines.push(
+      "  # Priority dispatch is disabled until an operator chooses one explicit source."
+    );
+  }
   lines.push(
-    "   git fetch origin && git merge-base --is-ancestor origin/main HEAD"
+    "  # See docs/adr/2026-05-18_explicit-dispatch-priority-mappings.md"
   );
-  lines.push("   ```");
-  lines.push("   If not up-to-date, run the `/pull` skill first.");
+  if (priority?.source === "project-field") {
+    lines.push("  priority:");
+    lines.push("    source: project-field");
+    lines.push(`    field: ${JSON.stringify(priority.field)}`);
+    lines.push("    values:");
+    for (const [name, value] of Object.entries(priority.values)) {
+      lines.push(`      ${JSON.stringify(name)}: ${value}`);
+    }
+    return lines;
+  }
+  if (priority?.source === "labels") {
+    lines.push("  priority:");
+    lines.push("    source: labels");
+    lines.push("    labels:");
+    for (const [name, value] of Object.entries(priority.labels)) {
+      lines.push(`      ${JSON.stringify(name)}: ${value}`);
+    }
+    return lines;
+  }
+  lines.push("  priority:");
+  lines.push("    source: disabled");
   lines.push("");
-  lines.push("## Flow");
+  lines.push("  # Optional template: project-field priority source.");
+  lines.push("  # priority:");
+  lines.push("  #   source: project-field");
+  lines.push("  #   field: Priority");
+  lines.push("  #   values:");
+  lines.push("  #     Urgent: 0");
+  lines.push("  #     High: 1");
   lines.push("");
-  lines.push("1. Run all pre-flight checks above");
-  lines.push("2. If all checks pass, merge the PR:");
-  lines.push("   ```bash");
-  lines.push("   gh pr merge --squash    # squash merge (default)");
-  lines.push("   # or: gh pr merge --merge   # merge commit");
-  lines.push("   # or: gh pr merge --rebase  # rebase merge");
-  lines.push("   ```");
-  lines.push("   Choose the merge strategy per project policy.");
-  lines.push("3. On merge success:");
-  lines.push(
-    "   - Use the **gh-project skill** to transition the issue status to Done"
+  lines.push("  # Optional template: labels priority source.");
+  lines.push("  # priority:");
+  lines.push("  #   source: labels");
+  lines.push("  #   labels:");
+  lines.push("  #     P0: 0");
+  lines.push("  #     P1: 1");
+  return lines;
+}
+function resolveRoleAction(role) {
+  switch (role) {
+    case "active":
+      return "Agent starts work immediately. Creates workpad and proceeds with implementation.";
+    case "wait":
+      return "PR created. Awaiting human review. Agent is idle.";
+    case "terminal":
+      return "Completed state. Agent exits.";
+    case null:
+      return "Role unset. Must be explicitly configured in WORKFLOW.md.";
+  }
+}
+
+// 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
   );
-  lines.push("   - Do NOT call status APIs directly \u2014 delegate to gh-project");
-  lines.push("4. On merge failure:");
-  lines.push("   - Record the failure reason in workpad Notes");
-  lines.push("   - Resolve the blocking issue (re-run pre-flight checks)");
-  lines.push("   - Retry the merge");
-  lines.push("5. Loop until merged or blocked by an unresolvable issue");
-  lines.push("");
-  lines.push("## Rules");
-  lines.push("");
-  lines.push("- Never call `gh pr merge` without completing pre-flight checks");
-  lines.push(
-    "- Status transition to Done MUST go through the gh-project skill"
+  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
   );
-  lines.push(
-    "- If any pre-flight check fails, do not merge \u2014 fix the issue first"
+  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
   );
-  lines.push("- Record all merge attempts and outcomes in the workpad");
-  return renderSkillDocument({
-    name: "land",
-    description: "Merge approved pull requests safely after verifying approvals, CI, and branch freshness.",
-    bodyLines: lines
-  });
+  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
@@ -1953,6 +2119,17 @@ async function abortIfCancelled(input) {
   }
   return result;
 }
+var SKIP_CONTEXT_DEPRECATION = "--skip-context is deprecated and is now a no-op. Repo-local .gh-symphony/context.yaml is no longer generated.";
+var LEGACY_GH_SYMPHONY_FILES = [
+  {
+    relativePath: ".gh-symphony/context.yaml",
+    reason: "replaced by skill-local references/"
+  },
+  {
+    relativePath: ".gh-symphony/reference-workflow.md",
+    reason: null
+  }
+];
 function parseInitFlags(args) {
   const flags = {
     dryRun: false,
@@ -1993,6 +2170,9 @@ function parseInitFlags(args) {
   }
   return flags;
 }
+function warnDeprecatedSkipContext() {
+  p.log.warn(SKIP_CONTEXT_DEPRECATION);
+}
 async function runInitRuntimePreflight(runtime) {
   if (!isClaudeRuntime(runtime)) {
     return true;
@@ -2015,6 +2195,9 @@ async function runInitRuntimePreflight(runtime) {
 }
 var handler = async (args, options) => {
   const flags = parseInitFlags(args);
+  if (flags.skipContext) {
+    warnDeprecatedSkipContext();
+  }
   if (flags.nonInteractive) {
     await runNonInteractive(flags, options);
     return;
@@ -2087,6 +2270,62 @@ function runRuntimePreflight(runtime) {
     );
   }
 }
+async function findLegacyGhSymphonyFiles(cwd) {
+  const found = [];
+  for (const legacyFile of LEGACY_GH_SYMPHONY_FILES) {
+    try {
+      await readFile3(join3(cwd, legacyFile.relativePath), "utf8");
+      found.push(legacyFile.relativePath);
+    } catch {
+    }
+  }
+  return found;
+}
+async function removeLegacyGhSymphonyFiles(cwd, legacyFiles) {
+  const removed = [];
+  for (const relativePath of legacyFiles) {
+    await rm(join3(cwd, relativePath), { force: true });
+    removed.push(relativePath);
+  }
+  const legacyDir = join3(cwd, ".gh-symphony");
+  try {
+    const remaining = await readdir2(legacyDir);
+    if (remaining.length === 0) {
+      await rmdir(legacyDir);
+    }
+  } catch {
+  }
+  return removed;
+}
+async function promptLegacyGhSymphonyCleanup(cwd) {
+  const legacyFiles = await findLegacyGhSymphonyFiles(cwd);
+  if (legacyFiles.length === 0) {
+    return [];
+  }
+  const lines = [
+    "Found legacy .gh-symphony/ directory.",
+    "These files are no longer used:"
+  ];
+  for (const legacyFile of LEGACY_GH_SYMPHONY_FILES) {
+    if (!legacyFiles.includes(legacyFile.relativePath)) {
+      continue;
+    }
+    const suffix = legacyFile.reason ? ` (${legacyFile.reason})` : "";
+    lines.push(`  \u2022 ${legacyFile.relativePath}${suffix}`);
+  }
+  lines.push("Safe to delete.");
+  p.log.info(lines.join("\n"));
+  const removeFiles = await abortIfCancelled(
+    p.confirm({
+      message: "Remove legacy .gh-symphony/ files?",
+      initialValue: false
+    })
+  );
+  if (!removeFiles) {
+    return [];
+  }
+  return removeLegacyGhSymphonyFiles(cwd, legacyFiles);
+}
 async function resolveChangeStatus(path, content, mode) {
   try {
     const existing = await readFile3(path, "utf8");
@@ -2112,15 +2351,18 @@ async function writePlannedFile(file) {
   if (file.status === "unchanged") {
     return false;
   }
-  await mkdir3(dirname2(file.path), { recursive: true });
+  await mkdir2(dirname2(file.path), { recursive: true });
   const temporaryPath = `${file.path}.tmp`;
-  await writeFile3(temporaryPath, file.content, "utf8");
+  await writeFile2(temporaryPath, file.content, "utf8");
   await rename2(temporaryPath, file.path);
   if (file.executable) {
     await chmod(file.path, 493);
   }
   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;
 }
@@ -2450,8 +2692,7 @@ async function planEcosystem(opts) {
     statusField,
     priorityField,
     runtime,
-    skipSkills,
-    skipContext
+    skipSkills
   } = opts;
   const priority = opts.priority ?? (priorityField ? buildProjectFieldPriority(priorityField) : buildDisabledPriority());
   const automaticLifecycle = toWorkflowLifecycleConfig(
@@ -2467,7 +2708,6 @@ async function planEcosystem(opts) {
       planningStates: defaultBlockerCheckStates
     }
   );
-  const ghSymphonyDir = join3(cwd, ".gh-symphony");
   const environment = opts.environment ?? await detectEnvironment(cwd);
   const files = [];
   files.push(
@@ -2479,44 +2719,6 @@ async function planEcosystem(opts) {
       executable: true
     })
   );
-  if (!skipContext) {
-    const contextYaml = buildContextYaml({
-      projectDetail,
-      statusField,
-      detectedEnvironment: environment,
-      runtime: {
-        agent: runtime,
-        agent_command: resolveShellAgentCommand(runtime)
-      }
-    });
-    files.push(
-      await planFileChange({
-        path: join3(ghSymphonyDir, "context.yaml"),
-        label: "Context metadata",
-        content: generateContextYamlString(contextYaml),
-        mode: "overwrite"
-      })
-    );
-  }
-  const referenceWorkflow = generateReferenceWorkflow({
-    runtime,
-    statusColumns: statusField.options.map((o) => ({
-      name: o.name,
-      role: null
-    })),
-    projectId: projectDetail.id,
-    priority,
-    lifecycle,
-    detectedEnvironment: environment
-  });
-  files.push(
-    await planFileChange({
-      path: join3(ghSymphonyDir, "reference-workflow.md"),
-      label: "Reference workflow",
-      content: referenceWorkflow,
-      mode: "overwrite"
-    })
-  );
   const skillsDir = skipSkills ? null : resolveSkillsDir(cwd, runtime);
   if (!skipSkills && skillsDir) {
     const { files: plannedSkills } = buildSkillFilePlans(
@@ -2537,16 +2739,15 @@ async function planEcosystem(opts) {
           role: null
         })),
         statusFieldId: statusField.id,
-        contextYamlPath: ".gh-symphony/context.yaml",
-        referenceWorkflowPath: ".gh-symphony/reference-workflow.md",
         detectedEnvironment: environment
       }
     );
     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"
         })
@@ -2568,17 +2769,8 @@ async function planEcosystem(opts) {
 }
 async function writeEcosystem(opts) {
   const plan = await planEcosystem(opts);
-  await mkdir3(join3(opts.cwd, ".gh-symphony"), { recursive: true });
   const afterCreateHookPath = join3(opts.cwd, DEFAULT_AFTER_CREATE_HOOK_PATH);
-  const contextYamlPath = join3(opts.cwd, ".gh-symphony", "context.yaml");
-  const referenceWorkflowPath = join3(
-    opts.cwd,
-    ".gh-symphony",
-    "reference-workflow.md"
-  );
   let afterCreateHookWritten = false;
-  let contextYamlWritten = false;
-  let referenceWorkflowWritten = false;
   const skillsWritten = [];
   const skillsSkipped = [];
   for (const file of plan.files) {
@@ -2587,16 +2779,8 @@ async function writeEcosystem(opts) {
       afterCreateHookWritten = written;
       continue;
     }
-    if (file.path === contextYamlPath) {
-      contextYamlWritten = written;
-      continue;
-    }
-    if (file.path === referenceWorkflowPath) {
-      referenceWorkflowWritten = written;
-      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 {
@@ -2614,10 +2798,11 @@ async function writeEcosystem(opts) {
     skillsDir: plan.skillsDir,
     skipSkills: plan.skipSkills,
     afterCreateHookWritten,
-    contextYamlWritten,
-    referenceWorkflowWritten,
-    skillsWritten: skillsWritten.sort(),
-    skillsSkipped: skillsSkipped.sort()
+    contextYamlWritten: false,
+    referenceWorkflowWritten: false,
+    skillsWritten: [...new Set(skillsWritten)].sort(),
+    skillsSkipped: [...new Set(skillsSkipped)].sort(),
+    legacyFilesRemoved: []
   };
 }
 function formatPrioritySummaryLines(priority) {
@@ -2669,16 +2854,6 @@ function printEcosystemSummary(result, workflowPath, opts) {
       `  \u2713 ${DEFAULT_AFTER_CREATE_HOOK_LABEL.padEnd(36)} ${DEFAULT_AFTER_CREATE_HOOK_PATH}`
     );
   }
-  if (result.contextYamlWritten) {
-    lines.push(
-      "  \u2713 Context metadata                     .gh-symphony/context.yaml"
-    );
-  }
-  if (result.referenceWorkflowWritten) {
-    lines.push(
-      "  \u2713 Reference workflow                   .gh-symphony/reference-workflow.md"
-    );
-  }
   if (result.skillsDir) {
     const relSkillsDir = relative(cwd, result.skillsDir);
     lines.push("");
@@ -3052,6 +3227,7 @@ async function runInteractiveStandalone(flags, _options) {
     printDryRunPreview(outputPath, workflowPlan, ecosystemPlan);
     return;
   }
+  await promptLegacyGhSymphonyCleanup(process.cwd());
   await writeWorkflowPlan(workflowPlan);
   const ecosystemResult = await writeEcosystem({
     cwd: process.cwd(),
@@ -3075,7 +3251,9 @@ export {
   toWorkflowLifecycleConfig,
   validateStateMapping,
   abortIfCancelled,
+  warnDeprecatedSkipContext,
   workflow_init_default,
+  promptLegacyGhSymphonyCleanup,
   resolveStatusField,
   buildAutomaticStateMappings,
   resolvePriorityField,