Merge pull request #47 from flightctl/cursor-command-wrappers

Generate flat Cursor command wrappers during install

Author: galel12

CONTRIBUTING.md

@@ -88,10 +88,20 @@ The installer (`install.sh`) auto-discovers workflows by scanning for `*/SKILL.m
 
 **Claude Code integration**: The installer:
 1. Appends workflow references to `CLAUDE.md` (or `.claude/CLAUDE.md` for project-level) beneath the `# ai-workflows` marker
-2. Symlinks workflows into the user-level Claude skills directory (or `.claude/skills/` for project-level) for slash command discovery
-3. Removes stale references (old controller.md paths) to avoid duplicates
+2. Symlinks workflows into the Claude skills directory (or `.claude/skills/` for project-level) for slash command discovery
+3. Symlinks each workflow's `commands/` directory into `.claude/commands/` so phases are discoverable as `/{workflow}:{command}` slash commands (e.g., `/bugfix:assess`, `/cve-fix:patch`)
+4. Removes stale references (old controller.md paths) to avoid duplicates
 
-**Uninstall** (`uninstall.sh`) mirrors the install logic with removal.
+**Cursor integration**: Cursor uses two discovery mechanisms — skills (`SKILL.md` in `.cursor/skills/*/`) and commands (`.md` files in `.cursor/commands/`). The installer uses both:
+
+1. Symlinks each workflow directory into `.cursor/skills/{workflow}/` for top-level skill discovery
+2. For each `commands/{phase}.md` in a workflow, generates a command file `.cursor/commands/{workflow}-{phase}.md` — a thin dispatch prompt that reads the workflow's controller and dispatches the phase
+
+Cursor scans both project-level (`.cursor/commands/`) and user-level (`~/.cursor/commands/`) directories, so commands work at either scope. No manifest file is needed — uninstall identifies generated commands by matching `{workflow}-*.md` filenames against existing `commands/*.md` source files.
+
+**Note on symlinks**: The skill symlinks (`.cursor/skills/{workflow}/` -> `~/.ai-workflows/{workflow}`) depend on Cursor following symlinks for top-level skill discovery. There are [reported issues](https://forum.cursor.com/t/cursor-doesnt-follow-symlinks-to-discover-skills/149693) with this in some Cursor versions. The generated command files avoid this problem by using absolute paths to `$INSTALL_DIR`, so the slash commands work independently of symlink resolution.
+
+**Uninstall** (`uninstall.sh`) mirrors the install logic with removal. For Cursor, it removes generated command files by matching `{workflow}-{phase}.md` against the source workflow's `commands/` directory to avoid removing unrelated files. Selective uninstall (`--workflows`) only removes commands belonging to the specified workflows.
 
 ## Testing Your Changes
 

README.md

@@ -125,21 +125,41 @@ Use `--workflows` to install only the workflows relevant to a given project:
 ./install.sh --list                       # show available workflows
 ```
 
+For project-level Cursor installs, add the generated commands directory to `.gitignore`:
+
+```gitignore
+.cursor/commands/
+```
+
+The skill symlinks under `.cursor/skills/` may also need ignoring depending on your project's conventions.
+
 ## Scopes
 
 | Scope | Cursor | Claude Code |
 |-------|--------|-------------|
-| **User** (default) | `~/.cursor/skills/<workflow>` | `~/.claude/CLAUDE.md` |
-| **Project** (`--project`) | `.cursor/skills/<workflow>` | `.claude/CLAUDE.md` |
+| **User** (default) | `~/.cursor/skills/<workflow>` + `~/.cursor/commands/` | `~/.claude/CLAUDE.md` |
+| **Project** (`--project`) | `.cursor/skills/<workflow>` + `.cursor/commands/` | `.claude/CLAUDE.md` |
 
 ## Usage
 
-Invoke a workflow command (works in both Cursor and Claude Code):
+### Claude Code
+
+Invoke a workflow command using the colon-namespaced format:
 
 - `/bugfix:assess`, `/bugfix:diagnose`, `/bugfix:fix`, ...
 - `/code-review:start`, `/code-review:continue`, `/code-review:clean`
 - `/docs-writer:gather`, `/docs-writer:plan`, `/docs-writer:draft`, ...
 
+### Cursor
+
+The installer generates flat command files in `.cursor/commands/` so each phase appears in the Cursor slash menu:
+
+- `/bugfix-assess`, `/bugfix-diagnose`, `/bugfix-fix`, ...
+- `/code-review-start`, `/code-review-continue`, `/code-review-clean`
+- `/docs-writer-gather`, `/docs-writer-plan`, `/docs-writer-draft`, ...
+
+Cursor scans both project-level (`.cursor/commands/`) and user-level (`~/.cursor/commands/`) directories. Commands are plain `.md` files — no manifest or wrapper directories needed. They are created by `install.sh` and cleaned up by `uninstall.sh`.
+
 ## Updating
 
 ```bash

install.sh

@@ -135,19 +135,65 @@ install_shared() {
   echo "  Linked ${target_dir}/_shared -> ${INSTALL_DIR}/_shared  ($SCOPE)"
 }
 
+generate_cursor_commands() {
+  local cmds_dir="$1"
+  local generated=0
+
+  for wf in "${WORKFLOWS[@]}"; do
+    local wf_dir="${INSTALL_DIR}/${wf}"
+    [[ -d "${wf_dir}/commands" ]] || continue
+
+    for cmd_file in "${wf_dir}"/commands/*.md; do
+      [[ -f "$cmd_file" ]] || continue
+      local phase
+      phase="$(basename "$cmd_file" .md)"
+      local cmd_name="${wf}-${phase}"
+
+      local description=""
+      if head -1 "$cmd_file" | grep -q "^---"; then
+        description="$(awk '/^---/{n++; next} n==1 && /^description:/{sub(/^description:[[:space:]]*"?/, ""); sub(/"[[:space:]]*$/, ""); print; exit}' "$cmd_file")"
+      fi
+      if [[ -z "$description" ]] && [[ -f "${wf_dir}/skills/${phase}.md" ]]; then
+        description="$(awk '/^---/{n++; next} n==1 && /^description:/{sub(/^description:[[:space:]]*"?/, ""); sub(/"[[:space:]]*$/, ""); print; exit}' "${wf_dir}/skills/${phase}.md")"
+      fi
+      [[ -z "$description" ]] && description="Run the ${phase} phase of the ${wf} workflow."
+      description="${description//\"/\\\"}"
+
+      cat > "${cmds_dir}/${cmd_name}.md" <<CMD_EOF
+---
+description: "${description}"
+---
+# /${phase} (${wf})
+
+Read \`${INSTALL_DIR}/${wf}/skills/controller.md\` and follow it.
+
+Dispatch the **${phase}** phase. Context:
+
+\$ARGUMENTS
+CMD_EOF
+      generated=$((generated + 1))
+    done
+  done
+
+  [[ $generated -gt 0 ]] && echo "  Generated ${generated} command(s) in ${cmds_dir}  ($SCOPE)"
+}
+
 install_cursor() {
   if [[ "$SCOPE" == "project" ]]; then
     SKILLS_DIR="${PROJECT_ROOT}/.cursor/skills"
+    CMDS_DIR="${PROJECT_ROOT}/.cursor/commands"
   else
     SKILLS_DIR="${HOME}/.cursor/skills"
+    CMDS_DIR="${HOME}/.cursor/commands"
   fi
 
-  mkdir -p "$SKILLS_DIR"
+  mkdir -p "$SKILLS_DIR" "$CMDS_DIR"
   install_shared "$SKILLS_DIR"
   for wf in "${WORKFLOWS[@]}"; do
     ln -sfn "${INSTALL_DIR}/${wf}" "${SKILLS_DIR}/${wf}"
     echo "  Linked ${SKILLS_DIR}/${wf} -> ${INSTALL_DIR}/${wf}  ($SCOPE)"
   done
+  generate_cursor_commands "$CMDS_DIR"
 }
 
 install_claude() {

uninstall.sh

@@ -116,13 +116,38 @@ has_remaining_workflows() {
   return 1
 }
 
+remove_cursor_commands() {
+  local cmds_dir="$1"
+  local removed=0
+
+  [[ -d "$cmds_dir" ]] || return 0
+
+  for wf in "${WORKFLOWS[@]}"; do
+    for cmd_file in "${cmds_dir}/${wf}"-*.md; do
+      [[ -f "$cmd_file" ]] || continue
+      local base
+      base="$(basename "$cmd_file" .md)"
+      local suffix="${base#"${wf}-"}"
+      if [[ -f "${INSTALL_DIR}/${wf}/commands/${suffix}.md" ]]; then
+        rm -f "$cmd_file"
+        removed=$((removed + 1))
+      fi
+    done
+  done
+
+  [[ $removed -gt 0 ]] && echo "  Removed ${removed} command(s) from ${cmds_dir}  ($SCOPE)"
+}
+
 uninstall_cursor() {
   if [[ "$SCOPE" == "project" ]]; then
     SKILLS_DIR="${PROJECT_ROOT}/.cursor/skills"
+    CMDS_DIR="${PROJECT_ROOT}/.cursor/commands"
   else
     SKILLS_DIR="${HOME}/.cursor/skills"
+    CMDS_DIR="${HOME}/.cursor/commands"
   fi
 
+  remove_cursor_commands "$CMDS_DIR"
   if [[ "$SELECTIVE" == false ]]; then
     uninstall_shared "$SKILLS_DIR"
   fi