fix: address remaining PR #516 review comments

- Add python3 availability check before using in symlink fallback
- Suppress macOS/BSD sed errors with proper fallback handling
- Add feedback when no prompt templates found in glob
- Clarify hub pattern is correct (symlinks TO ~/.qwen, not into repo)
- Align QWEN.md Task mapping with install.sh context block
- Fix README.qwen.md table structure (note was interrupting rows)
- Add agent symlink cleanup to uninstall instructions
- Document YAML frontmatter format in agent files

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

Author: mhenke

.qwen/INSTALL.md

@@ -106,10 +106,16 @@ Skills update instantly through the symlinks.
    find ~/.qwen/skills -type l -lname '*/superpowers/skills/*' -delete
    ```
 
-2. **Clean up QWEN.md:** Edit `~/.qwen/QWEN.md` and remove the block between
+2. **Remove the agent symlinks:**
+
+   ```bash
+   find ~/.qwen/agents -type l -lname '*/superpowers/agents/*' -delete
+   ```
+
+3. **Clean up QWEN.md:** Edit `~/.qwen/QWEN.md` and remove the block between
    `<!-- SUPERPOWERS-CONTEXT-START -->` and `<!-- SUPERPOWERS-CONTEXT-END -->`.
 
-3. **Remove the repo:**
+4. **Remove the repo:**
 
    ```bash
    rm -rf ~/.qwen/superpowers

.qwen/agents/code-reviewer.md

@@ -1,3 +1,6 @@
+# Qwen Code CLI Subagent Definition
+# Format: YAML frontmatter + Markdown system prompt
+# See: https://qwenlm.github.io/qwen-code-docs/en/users/features/sub-agents/
 ---
 name: code-reviewer
 description: A subagent focused on reviewing code for quality, best practices, and maintainability.

.qwen/agents/implementer.md

@@ -1,3 +1,6 @@
+# Qwen Code CLI Subagent Definition
+# Format: YAML frontmatter + Markdown system prompt
+# See: https://qwenlm.github.io/qwen-code-docs/en/users/features/sub-agents/
 ---
 name: implementer
 description: A subagent specialized in implementing tasks, writing tests, and self-reviewing code.

.qwen/agents/spec-reviewer.md

@@ -1,3 +1,6 @@
+# Qwen Code CLI Subagent Definition
+# Format: YAML frontmatter + Markdown system prompt
+# See: https://qwenlm.github.io/qwen-code-docs/en/users/features/sub-agents/
 ---
 name: spec-reviewer
 description: A subagent that verifies an implementation matches its specification exactly.

.qwen/install.sh

@@ -54,10 +54,13 @@ for skill_path in "$REPO_SKILLS_DIR"/*/; do
         # Use relative path for portability (repo relocation doesn't break links)
         if ln -sr "$skill_path" "$target_path" 2>/dev/null; then
             : # GNU ln with -r support
-        else
+        elif command -v python3 >/dev/null 2>&1; then
             # Fallback: compute relative path with Python
             rel_path="$(python3 -c "import os,sys; print(os.path.relpath(sys.argv[1], sys.argv[2]))" "$skill_path" "$SKILLS_DIR")"
             ln -s "$rel_path" "$target_path"
+        else
+            echo "  ⚠ Warning: Neither GNU ln -sr nor python3 available. Using absolute path (less portable)."
+            ln -s "$skill_path" "$target_path"
         fi
         echo "  ✓ $skill_name"
     fi
@@ -88,9 +91,12 @@ if [ -d "$REPO_AGENTS_DIR" ]; then
             # Use relative path for portability
             if ln -sr "$agent_path" "$target_path" 2>/dev/null; then
                 : # GNU ln with -r support
-            else
+            elif command -v python3 >/dev/null 2>&1; then
                 rel_path="$(python3 -c "import os,sys; print(os.path.relpath(sys.argv[1], sys.argv[2]))" "$agent_path" "$AGENTS_DIR")"
                 ln -s "$rel_path" "$target_path"
+            else
+                echo "  ⚠ Warning: Neither GNU ln -sr nor python3 available. Using absolute path (less portable)."
+                ln -s "$agent_path" "$target_path"
             fi
             echo "  ✓ $agent_name"
         fi
@@ -104,8 +110,10 @@ PROMPT_TEMPLATES_DIR="$REPO_AGENTS_DIR"
 
 if [ -d "$PROMPT_TEMPLATES_DIR" ]; then
     echo "Linking Qwen prompt templates to subagent skills..."
+    templates_linked=0
     for template in "$PROMPT_TEMPLATES_DIR"/*-prompt-template.md; do
         if [ -f "$template" ]; then
+            templates_linked=$((templates_linked + 1))
             template_name=$(basename "$template")
             # Map template names to skill directories
             if [[ "$template_name" == "implementer-prompt-template.md" ]]; then
@@ -125,13 +133,21 @@ if [ -d "$PROMPT_TEMPLATES_DIR" ]; then
             # Use relative path for portability
             if ln -sr "$template" "$target_skill" 2>/dev/null; then
                 : # GNU ln with -r support
-            else
+            elif command -v python3 >/dev/null 2>&1; then
                 rel_path="$(python3 -c "import os,sys; print(os.path.relpath(sys.argv[1], sys.argv[2]))" "$template" "$(dirname "$target_skill")")"
                 ln -s "$rel_path" "$target_skill"
+            else
+                echo "  ⚠ Warning: Neither GNU ln -sr nor python3 available. Using absolute path (less portable)."
+                ln -s "$template" "$target_skill"
             fi
             echo "  ✓ $(basename "$target_skill")"
         fi
     done
+    if [ "$templates_linked" -eq 0 ]; then
+        echo "  ℹ No prompt template files found in $PROMPT_TEMPLATES_DIR"
+    fi
+else
+    echo "No agents directory found at $REPO_AGENTS_DIR, skipping agent linking."
 fi
 
 
@@ -181,9 +197,11 @@ fi
 # Trim trailing blank lines (prevents accumulation on repeated runs)
 if sed -i.bak -e :a -e '/^\n*$/{$d;N;ba' -e '}' "$QWEN_MD" 2>/dev/null; then
     rm -f "${QWEN_MD}.bak"
+elif awk '{print; n=0} /^$/{n++} END{for(i=0;i<n-1;i++)print ""}' "$QWEN_MD" > "${QWEN_MD}.tmp" 2>/dev/null; then
+    # Fallback: awk version for systems without GNU sed (macOS/BSD)
+    mv "${QWEN_MD}.tmp" "$QWEN_MD"
 else
-    # Fallback: awk version for systems without GNU sed
-    awk '{print; n=0} /^$/{n++} END{for(i=0;i<n-1;i++)print ""}' "$QWEN_MD" > "${QWEN_MD}.tmp" && mv "${QWEN_MD}.tmp" "$QWEN_MD"
+    echo "Warning: Could not trim blank lines from $QWEN_MD" >&2
 fi
 
 # Append context block with single newline separator

QWEN.md

@@ -7,7 +7,7 @@ To use a skill, read its `SKILL.md` file and follow the instructions. Start with
 ## Terminology Mapping
 
 Skills reference Claude Code tools. Use these Qwen equivalents:
-- **"Task" tool** → Sequential execution (perform tasks yourself)
+- **"Task" tool** → Use your native `task()` tool with `subagent_type` parameter. Subagents (`implementer`, `spec-reviewer`, `code-reviewer`) are available in `~/.qwen/agents/`.
 - **"Skill" tool** → Read the file at `~/.qwen/skills/<skill-name>/SKILL.md`
 - **"TodoWrite"** → Write/update a plan file (e.g., `plan.md`)
 - File operations → `read_file`, `write_file`, `replace`

docs/README.qwen.md

@@ -57,9 +57,6 @@ Skills reference Claude Code tools. Qwen equivalents:
 | `Task` (subagents) | `task()` tool |
 | `Skill` tool | `read_file` on `~/.qwen/skills/<skill>/SKILL.md` |
 | `TodoWrite` | Write/update `plan.md` |
-
-**Note on Qwen Subagent Configuration:**
-Qwen Code CLI supports native subagent delegation via its `task()` tool. To enable Superpowers' subagent workflows (like `subagent-driven-development` or `dispatching-parallel-agents`), you will need to define corresponding subagents in `~/.qwen/agents/` using Markdown+YAML configuration files (e.g., `implementer.md`, `code-reviewer.md`). These files define the subagent's role, system prompt, and allowed tools.
 | `read_file` | `read_file` |
 | `write_file` | `write_file` |
 | `Edit` / `replace` | `replace` |
@@ -68,6 +65,8 @@ Qwen Code CLI supports native subagent delegation via its `task()` tool. To enab
 | `Shell` | `run_shell_command` |
 | `WebFetch` | `web_fetch` |
 
+**Note on Subagent Configuration:** Qwen Code CLI supports native subagent delegation via its `task()` tool. To enable Superpowers' subagent workflows (like `subagent-driven-development` or `dispatching-parallel-agents`), you will need to define corresponding subagents in `~/.qwen/agents/` using Markdown+YAML configuration files (e.g., `implementer.md`, `code-reviewer.md`). These files define the subagent's role, system prompt, and allowed tools. The installer automatically links the required subagents.
+
 ## Updating
 
 ```bash
@@ -83,9 +82,14 @@ Skills update instantly through the symlinks.
    find ~/.qwen/skills -type l -lname '*/superpowers/skills/*' -delete
    ```
 
-2. Edit `~/.qwen/QWEN.md` and remove the block between `<!-- SUPERPOWERS-CONTEXT-START -->` and `<!-- SUPERPOWERS-CONTEXT-END -->`.
+2. Remove agent symlinks:
+   ```bash
+   find ~/.qwen/agents -type l -lname '*/superpowers/agents/*' -delete
+   ```
+
+3. Edit `~/.qwen/QWEN.md` and remove the block between `<!-- SUPERPOWERS-CONTEXT-START -->` and `<!-- SUPERPOWERS-CONTEXT-END -->`.
 
-3. Remove the repo:
+4. Remove the repo:
    ```bash
    rm -rf ~/.qwen/superpowers
    ```