Skip to content

Comments

Add .factory directory with installation docs and scripts#519

Open
vurihuang wants to merge 1 commit intoobra:mainfrom
vurihuang:master
Open

Add .factory directory with installation docs and scripts#519
vurihuang wants to merge 1 commit intoobra:mainfrom
vurihuang:master

Conversation

@vurihuang
Copy link

@vurihuang vurihuang commented Feb 21, 2026

 ## Motivation and Context
 This change adds the `.factory/` directory containing installation documentation and setup scripts for the Superpowers workflow framework. This enables users to easily install and configure Superpowers in their Factory Droid CLI environment, providing systematic brainstorming, test-driven development, and structured planning workflows.

 ## How Has This Been Tested?
 - Verified installation scripts work locally
 - Tested symlinks creation and skill linking
 - Validated installation verification script passes

 ## Breaking Changes
 None. This is a new addition that doesn't affect existing functionality.

 ## Types of changes
 - [x] New feature (non-breaking change which adds functionality)
 - [ ] Bug fix (non-breaking change which fixes an issue)
 - [ ] Breaking change (fix or feature that would cause existing functionality to change)
 - [ ] Documentation update

 ## Checklist
 - [x] I have read the [MCP Documentation](https://modelcontextprotocol.io)
 - [x] My code follows the repository's style guidelines
 - [x] New and existing tests pass locally
 - [x] I have added appropriate error handling
 - [x] I have added or updated documentation as needed

 ## Additional context
 The `.factory/` directory includes:
 - `INSTALL.md` - Comprehensive installation guide
 - `hooks/` - Session start hooks and configuration
 - `scripts/` - Installation and verification scripts
 - `skills/superpowers/SKILL.md` - Main skill definition

Summary by CodeRabbit

Release Notes

  • Documentation

    • Added comprehensive installation and usage guide for the Superpowers workflow framework.
  • New Features

    • Introduced Superpowers workflow framework integration for Factory Droid CLI.
    • Added automatic session initialization with skill detection and context loading.
    • Added installation verification utility to validate and troubleshoot setup.

@coderabbitai
Copy link

coderabbitai bot commented Feb 21, 2026

📝 Walkthrough

Walkthrough

The PR introduces installation and integration infrastructure for the Superpowers workflow framework within Factory Droid CLI. It adds comprehensive documentation, hook configuration, session initialization logic, and shell scripts for setup validation and skill linkage management.

Changes

Cohort / File(s) Summary
Documentation
.factory/INSTALL.md, .factory/skills/superpowers/SKILL.md
Comprehensive guides detailing installation steps, skill prerequisites, usage scenarios, troubleshooting, project structure, and workflow best practices for the Superpowers framework.
Hook Configuration & Implementation
.factory/hooks/hooks.json, .factory/hooks/session-start.sh
Adds SessionStart hook configuration and bash script that constructs session context with skill content, detects legacy directory structures, and outputs JSON payload with initialization data.
Installation & Verification Scripts
.factory/scripts/init-superpowers.sh, .factory/scripts/verify-install.sh
Bash utilities that initialize Superpowers by creating symlinks for core skills and validating installation completeness with actionable remediation hints.

Sequence Diagram(s)

sequenceDiagram
    participant FC as Factory CLI
    participant ISH as init-superpowers.sh
    participant Repo as Superpowers Repo
    participant SkillDir as ~/.factory/skills

    FC->>ISH: Execute init script
    ISH->>Repo: Verify repository exists
    Repo-->>ISH: Repository found
    ISH->>SkillDir: Create skills directory
    ISH->>Repo: Read superpowers skill
    Repo-->>ISH: Skill content
    ISH->>SkillDir: Create symlink for main skill
    loop For each core skill
        ISH->>Repo: Check if skill exists
        Repo-->>ISH: Skill status
        ISH->>SkillDir: Create superpowers-{skill} symlink
    end
    ISH->>FC: Output installation summary & verification command
Loading
sequenceDiagram
    participant FC as Factory CLI
    participant SSH as session-start.sh
    participant Config as ~/.config/superpowers
    participant Repo as Superpowers Repo
    participant Context as Session Context

    FC->>SSH: Trigger SessionStart hook (startup|resume|clear|compact)
    SSH->>Config: Check for legacy directory
    Config-->>SSH: Legacy status detected or absent
    SSH->>Repo: Read using-superpowers skill markdown
    Repo-->>SSH: Skill content
    SSH->>SSH: Escape content for JSON
    SSH->>Context: Build context with intro & skill content
    Context-->>SSH: Context assembled
    SSH->>FC: Output JSON with additional_context & hookSpecificOutput
Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~28 minutes

Possibly related PRs

Poem

🐰 A warren of scripts, all snug and neat,
Skills symlinked together, a workflow complete!
Hook by hook, we initialize with care,
Superpowers ready, distributed everywhere!

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'Add .factory directory with installation docs and scripts' accurately summarizes the main change: adding a new directory with installation documentation and setup scripts.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
  • 📝 Generate docstrings (stacked PR)
  • 📝 Generate docstrings (commit on current branch)
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@vurihuang
Copy link
Author

image

it works well on my local, try to get more feedback.

Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 7

🧹 Nitpick comments (4)
.factory/hooks/session-start.sh (1)

36-44: Consider jq for JSON construction to eliminate the fragility of manual string interpolation.

The heredoc approach relies on escape_for_json to produce a safe string. If jq is available in the target environment, using it is more robust and self-documenting:

♻️ Proposed refactor using jq
-# Output context injection as JSON.
-cat <<EOF
-{
-  "additional_context": "${session_context}",
-  "hookSpecificOutput": {
-    "hookEventName": "SessionStart",
-    "additionalContext": "${session_context}"
-  }
-}
-EOF
+# Output context injection as JSON.
+jq -n \
+  --arg ctx "$session_context" \
+  '{additional_context: $ctx, hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $ctx}}'
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.factory/hooks/session-start.sh around lines 36 - 44, The heredoc in
session-start.sh builds JSON by interpolating "${session_context}" and relies on
escape_for_json, which is fragile; instead, use jq (if available) to construct
the JSON to avoid manual escaping. Modify the code in session-start.sh to pipe
or pass session_context into jq to produce the object with keys
"additional_context" and "hookSpecificOutput" (containing "hookEventName":
"SessionStart" and "additionalContext"), replacing the current heredoc; keep
references to session_context and escape_for_json so you can remove the manual
escaping once jq is used.
.factory/scripts/init-superpowers.sh (3)

54-62: Skills absent from the repo are silently skipped.

If a skill directory doesn't exist under $SUPERPOWERS_DIR/skills/, the loop skips it with no user-visible output. Users may not realise certain skills weren't linked.

♻️ Proposed fix
 for skill in "${CORE_SKILLS[@]}"; do
     if [ -d "$SUPERPOWERS_DIR/skills/$skill" ]; then
         # Remove old link if exists
         rm -f "$SKILLS_DIR/superpowers-$skill"
         # Create new link
         ln -sf "$SUPERPOWERS_DIR/skills/$skill" "$SKILLS_DIR/superpowers-$skill"
         echo "  ✅ superpowers-$skill"
+    else
+        echo "  ⚠️  superpowers-$skill (not found in repo, skipped)"
     fi
 done
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.factory/scripts/init-superpowers.sh around lines 54 - 62, The loop over
CORE_SKILLS currently skips missing skill dirs silently; update the block that
iterates CORE_SKILLS to detect when "$SUPERPOWERS_DIR/skills/$skill" is not a
directory and emit a clear warning (e.g., echo to stderr or prefixed "⚠️")
mentioning the missing skill and path so users know it wasn't linked; keep the
existing behavior for the true branch (rm -f, ln -sf, success echo) in the same
loop and reference the CORE_SKILLS variable, the checked path
"$SUPERPOWERS_DIR/skills/$skill", and the created link name
"$SKILLS_DIR/superpowers-$skill" when composing the warning.

68-68: ls | grep anti-pattern (SC2010) — use a glob instead.

ShellCheck SC2010: ls output piped to grep breaks for filenames with spaces or special characters.

♻️ Proposed fix
-ls -1 "$SKILLS_DIR" | grep -E "^superpowers" || echo "  (none found)"
+shopt -s nullglob
+skills=("$SKILLS_DIR"/superpowers*)
+if [ "${`#skills`[@]}" -eq 0 ]; then
+    echo "  (none found)"
+else
+    for s in "${skills[@]}"; do echo "  $(basename "$s")"; done
+fi
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.factory/scripts/init-superpowers.sh at line 68, Replace the unsafe `ls -1
"$SKILLS_DIR" | grep -E "^superpowers"` pipeline with shell globbing against
"$SKILLS_DIR"/superpowers* and print each match safely (e.g., iterate matches
and output basename), falling back to "  (none found)" if no matches; target the
line that uses SKILLS_DIR and the "superpowers" pattern so filenames with
spaces/special chars are handled correctly.

5-5: set -e only; missing -uo pipefail for consistency.

session-start.sh uses set -euo pipefail. -u catches unbound variable typos and -o pipefail ensures a failed command in a pipe (like line 68) propagates correctly instead of silently succeeding.

♻️ Proposed fix
-set -e
+set -euo pipefail
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.factory/scripts/init-superpowers.sh at line 5, Replace the lone "set -e"
invocation with "set -euo pipefail" (i.e., add -u and -o pipefail) to match
session-start.sh; update any commands in the script that rely on unset variables
or pipes that should propagate failures so they explicitly handle defaults or
check return codes where needed.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.factory/hooks/session-start.sh:
- Line 14: The warning_message currently begins with the string literal "\n\n"
which becomes escaped into "\\n\\n" by escape_for_json and results in literal
"\n" text in JSON; remove the leading "\n\n" from warning_message so it contains
no quoted backslash-n sequences (leave any needed newlines to session_context
which already provides them) and ensure you still pass the trimmed
warning_message through escape_for_json to produce warning_escaped used in
session_context.
- Line 18: The command substitution that sets using_superpowers_content
currently redirects stderr into stdout (using 2>&1) which concatenates cat's
error with the fallback; change the redirection to suppress cat's stderr (use
2>/dev/null) so the || fallback "Error reading using-superpowers skill" is used
cleanly; update the line that defines using_superpowers_content to use
2>/dev/null and keep the existing || echo fallback, referencing the variable
using_superpowers_content and PLUGIN_ROOT to locate the change.

In @.factory/INSTALL.md:
- Line 67: The fenced code blocks under the "Example Workflow" and "Project
Structure" sections are missing language specifiers and trigger MD040; update
each opening fence from ``` to ```text so the blocks become explicit text code
fences (e.g., change the "Example Workflow" block and the "Project Structure"
block to start with ```text).
- Around line 181-182: The uninstall step uses the command rm
~/.factory/skills/superpowers* which will error in shells like zsh when the glob
has no matches; update the uninstall command used in the INSTALL.md section (the
line containing "rm ~/.factory/skills/superpowers*") to make it idempotent by
using rm with the force option (add -f and optionally --) so the command does
not fail if no files match the glob.
- Around line 41-46: The skills loop in INSTALL.md omits two skills that
init-superpowers.sh links; update the space-separated list used by the for skill
in ...; do loop to include using-superpowers and writing-skills so the loop
checks $HOME/.factory/superpowers/skills/$skill and creates the symlink to
$HOME/.factory/skills/superpowers-$skill for those two missing entries (ensure
the exact token names "using-superpowers" and "writing-skills" are added to the
list alongside the existing skill names).

In @.factory/skills/superpowers/SKILL.md:
- Line 32: The markdown has two fenced code blocks without language specifiers
causing MD040: add language tags to the diagram block and the TodoWrite
snippet—specifically update the workflow diagram fenced block (the ASCII
flowchart) to start with ```text and update the TodoWrite example fenced block
to start with ```json (or ```text if you prefer plain text) so the blocks are
properly labeled; locate the unlabeled fences in SKILL.md around the "workflow
diagram" block and the "TodoWrite" example and add the appropriate language
identifiers.
- Line 138: Replace the compound modifier "higher quality" with the hyphenated
form "higher-quality" in the sentence beginning "By following these workflows
systematically, you produce higher quality code..." within SKILL.md so the
compound adjective before "code" is correctly hyphenated.

---

Nitpick comments:
In @.factory/hooks/session-start.sh:
- Around line 36-44: The heredoc in session-start.sh builds JSON by
interpolating "${session_context}" and relies on escape_for_json, which is
fragile; instead, use jq (if available) to construct the JSON to avoid manual
escaping. Modify the code in session-start.sh to pipe or pass session_context
into jq to produce the object with keys "additional_context" and
"hookSpecificOutput" (containing "hookEventName": "SessionStart" and
"additionalContext"), replacing the current heredoc; keep references to
session_context and escape_for_json so you can remove the manual escaping once
jq is used.

In @.factory/scripts/init-superpowers.sh:
- Around line 54-62: The loop over CORE_SKILLS currently skips missing skill
dirs silently; update the block that iterates CORE_SKILLS to detect when
"$SUPERPOWERS_DIR/skills/$skill" is not a directory and emit a clear warning
(e.g., echo to stderr or prefixed "⚠️") mentioning the missing skill and path so
users know it wasn't linked; keep the existing behavior for the true branch (rm
-f, ln -sf, success echo) in the same loop and reference the CORE_SKILLS
variable, the checked path "$SUPERPOWERS_DIR/skills/$skill", and the created
link name "$SKILLS_DIR/superpowers-$skill" when composing the warning.
- Line 68: Replace the unsafe `ls -1 "$SKILLS_DIR" | grep -E "^superpowers"`
pipeline with shell globbing against "$SKILLS_DIR"/superpowers* and print each
match safely (e.g., iterate matches and output basename), falling back to " 
(none found)" if no matches; target the line that uses SKILLS_DIR and the
"superpowers" pattern so filenames with spaces/special chars are handled
correctly.
- Line 5: Replace the lone "set -e" invocation with "set -euo pipefail" (i.e.,
add -u and -o pipefail) to match session-start.sh; update any commands in the
script that rely on unset variables or pipes that should propagate failures so
they explicitly handle defaults or check return codes where needed.

warning_message=""
legacy_skills_dir="${HOME}/.config/superpowers/skills"
if [ -d "$legacy_skills_dir" ]; then
warning_message="\n\n<important-reminder>IN YOUR FIRST REPLY AFTER SEEING THIS MESSAGE YOU MUST TELL THE USER:⚠️ **WARNING:** Superpowers now uses Droid CLI's skills system. Custom skills in ~/.config/superpowers/skills will not be read. Move custom skills to ~/.factory/skills instead. To make this message go away, remove ~/.config/superpowers/skills</important-reminder>"
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

"\n\n" in double quotes produces literal \n text, not newlines, after JSON escaping.

In bash, \n inside double quotes is a literal two-character sequence (backslash + n), not a newline. When escape_for_json runs, the step s="${s//\\/\\\\}" doubles the backslash, producing \\n in the JSON output — which decodes to the literal string \n, not a line break.

Since session_context already provides \n\n (valid JSON newlines) immediately before ${warning_escaped}, the simplest fix is to drop the leading newlines from warning_message entirely:

🐛 Proposed fix
-    warning_message="\n\n<important-reminder>IN YOUR FIRST REPLY AFTER SEEING THIS MESSAGE YOU MUST TELL THE USER:⚠️ **WARNING:** Superpowers now uses Droid CLI's skills system. Custom skills in ~/.config/superpowers/skills will not be read. Move custom skills to ~/.factory/skills instead. To make this message go away, remove ~/.config/superpowers/skills</important-reminder>"
+    warning_message="<important-reminder>IN YOUR FIRST REPLY AFTER SEEING THIS MESSAGE YOU MUST TELL THE USER:⚠️ **WARNING:** Superpowers now uses Droid CLI's skills system. Custom skills in ~/.config/superpowers/skills will not be read. Move custom skills to ~/.factory/skills instead. To make this message go away, remove ~/.config/superpowers/skills</important-reminder>"
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
warning_message="\n\n<important-reminder>IN YOUR FIRST REPLY AFTER SEEING THIS MESSAGE YOU MUST TELL THE USER:⚠️ **WARNING:** Superpowers now uses Droid CLI's skills system. Custom skills in ~/.config/superpowers/skills will not be read. Move custom skills to ~/.factory/skills instead. To make this message go away, remove ~/.config/superpowers/skills</important-reminder>"
warning_message="<important-reminder>IN YOUR FIRST REPLY AFTER SEEING THIS MESSAGE YOU MUST TELL THE USER:⚠️ **WARNING:** Superpowers now uses Droid CLI's skills system. Custom skills in ~/.config/superpowers/skills will not be read. Move custom skills to ~/.factory/skills instead. To make this message go away, remove ~/.config/superpowers/skills</important-reminder>"
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.factory/hooks/session-start.sh at line 14, The warning_message currently
begins with the string literal "\n\n" which becomes escaped into "\\n\\n" by
escape_for_json and results in literal "\n" text in JSON; remove the leading
"\n\n" from warning_message so it contains no quoted backslash-n sequences
(leave any needed newlines to session_context which already provides them) and
ensure you still pass the trimmed warning_message through escape_for_json to
produce warning_escaped used in session_context.

fi

# Read using-superpowers content
using_superpowers_content=$(cat "${PLUGIN_ROOT}/../skills/using-superpowers/SKILL.md" 2>&1 || echo "Error reading using-superpowers skill")
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

2>&1 concatenates cat's stderr error message with the || fallback, producing a mangled error string.

On a missing file, this line captures cat: <path>: No such file or directory\nError reading using-superpowers skill into using_superpowers_content, because 2>&1 redirects stderr into the command substitution's stdout before || echo appends the fallback. Use 2>/dev/null to suppress cat's error output and rely solely on the fallback.

🐛 Proposed fix
-using_superpowers_content=$(cat "${PLUGIN_ROOT}/../skills/using-superpowers/SKILL.md" 2>&1 || echo "Error reading using-superpowers skill")
+using_superpowers_content=$(cat "${PLUGIN_ROOT}/../skills/using-superpowers/SKILL.md" 2>/dev/null || echo "Error reading using-superpowers skill")
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
using_superpowers_content=$(cat "${PLUGIN_ROOT}/../skills/using-superpowers/SKILL.md" 2>&1 || echo "Error reading using-superpowers skill")
using_superpowers_content=$(cat "${PLUGIN_ROOT}/../skills/using-superpowers/SKILL.md" 2>/dev/null || echo "Error reading using-superpowers skill")
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.factory/hooks/session-start.sh at line 18, The command substitution that
sets using_superpowers_content currently redirects stderr into stdout (using
2>&1) which concatenates cat's error with the fallback; change the redirection
to suppress cat's stderr (use 2>/dev/null) so the || fallback "Error reading
using-superpowers skill" is used cleanly; update the line that defines
using_superpowers_content to use 2>/dev/null and keep the existing || echo
fallback, referencing the variable using_superpowers_content and PLUGIN_ROOT to
locate the change.

Comment on lines +41 to +46
# Core workflow skills
for skill in brainstorming writing-plans executing-plans test-driven-development systematic-debugging using-git-worktrees finishing-a-development-branch requesting-code-review receiving-code-review verification-before-completion subagent-driven-development dispatching-parallel-agents; do
if [ -d "$HOME/.factory/superpowers/skills/$skill" ]; then
ln -sf "$HOME/.factory/superpowers/skills/$skill" "$HOME/.factory/skills/superpowers-$skill"
fi
done
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Skills list in Step 3 is missing using-superpowers and writing-skills.

init-superpowers.sh links 14 skills (including using-superpowers and writing-skills) but the manual loop shown here only covers 12. Users following the manual steps will be missing two skill symlinks.

🐛 Proposed fix
-for skill in brainstorming writing-plans executing-plans test-driven-development systematic-debugging using-git-worktrees finishing-a-development-branch requesting-code-review receiving-code-review verification-before-completion subagent-driven-development dispatching-parallel-agents; do
+for skill in brainstorming writing-plans executing-plans test-driven-development systematic-debugging using-git-worktrees finishing-a-development-branch requesting-code-review receiving-code-review verification-before-completion subagent-driven-development dispatching-parallel-agents using-superpowers writing-skills; do
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
# Core workflow skills
for skill in brainstorming writing-plans executing-plans test-driven-development systematic-debugging using-git-worktrees finishing-a-development-branch requesting-code-review receiving-code-review verification-before-completion subagent-driven-development dispatching-parallel-agents; do
if [ -d "$HOME/.factory/superpowers/skills/$skill" ]; then
ln -sf "$HOME/.factory/superpowers/skills/$skill" "$HOME/.factory/skills/superpowers-$skill"
fi
done
# Core workflow skills
for skill in brainstorming writing-plans executing-plans test-driven-development systematic-debugging using-git-worktrees finishing-a-development-branch requesting-code-review receiving-code-review verification-before-completion subagent-driven-development dispatching-parallel-agents using-superpowers writing-skills; do
if [ -d "$HOME/.factory/superpowers/skills/$skill" ]; then
ln -sf "$HOME/.factory/superpowers/skills/$skill" "$HOME/.factory/skills/superpowers-$skill"
fi
done
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.factory/INSTALL.md around lines 41 - 46, The skills loop in INSTALL.md
omits two skills that init-superpowers.sh links; update the space-separated list
used by the for skill in ...; do loop to include using-superpowers and
writing-skills so the loop checks $HOME/.factory/superpowers/skills/$skill and
creates the symlink to $HOME/.factory/skills/superpowers-$skill for those two
missing entries (ensure the exact token names "using-superpowers" and
"writing-skills" are added to the list alongside the existing skill names).


### Example Workflow

```
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fenced code blocks missing language specifiers (MD040).

Both the "Example Workflow" block (line 67) and the "Project Structure" block (line 117) trigger MD040. Specifying text satisfies the linter and is semantically appropriate for both.

🐛 Proposed fix
-```
+```text
 You: I want to add a user authentication feature to my app
-```
+```text
 ~/.factory/
 ├── superpowers/

Also applies to: 117-117

🧰 Tools
🪛 markdownlint-cli2 (0.21.0)

[warning] 67-67: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.factory/INSTALL.md at line 67, The fenced code blocks under the "Example
Workflow" and "Project Structure" sections are missing language specifiers and
trigger MD040; update each opening fence from ``` to ```text so the blocks
become explicit text code fences (e.g., change the "Example Workflow" block and
the "Project Structure" block to start with ```text).

Comment on lines +181 to +182
# Remove skill symlinks
rm ~/.factory/skills/superpowers*
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

rm without -f will error if no files match the glob.

In zsh (the default shell on macOS) superpowers* with no matches causes rm to fail with "no matches found". Using -f makes the uninstall step idempotent.

🐛 Proposed fix
-rm ~/.factory/skills/superpowers*
+rm -f ~/.factory/skills/superpowers*
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.factory/INSTALL.md around lines 181 - 182, The uninstall step uses the
command rm ~/.factory/skills/superpowers* which will error in shells like zsh
when the glob has no matches; update the uninstall command used in the
INSTALL.md section (the line containing "rm ~/.factory/skills/superpowers*") to
make it idempotent by using rm with the force option (add -f and optionally --)
so the command does not fail if no files match the glob.


## Workflow Overview

```
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Two fenced code blocks missing language specifiers (MD040).

The workflow diagram (line 32) and the TodoWrite example (line 73) trigger MD040. Use text for the diagram and json (or text) for the TodoWrite snippet.

🐛 Proposed fix
-```
+```text
 ┌─────────────────┐
 │  Brainstorming  │ ← Explore requirements, create design
-```
+```json
 TodoWrite: {"todos": "1. [pending] Explore project context\n..."}

Also applies to: 73-73

🧰 Tools
🪛 markdownlint-cli2 (0.21.0)

[warning] 32-32: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.factory/skills/superpowers/SKILL.md at line 32, The markdown has two fenced
code blocks without language specifiers causing MD040: add language tags to the
diagram block and the TodoWrite snippet—specifically update the workflow diagram
fenced block (the ASCII flowchart) to start with ```text and update the
TodoWrite example fenced block to start with ```json (or ```text if you prefer
plain text) so the blocks are properly labeled; locate the unlabeled fences in
SKILL.md around the "workflow diagram" block and the "TodoWrite" example and add
the appropriate language identifiers.

3. **Implement** - Use TDD (RED-GREEN-REFACTOR)
4. **Review** - Ensure quality and specification compliance

By following these workflows systematically, you produce higher quality code with fewer bugs and better alignment with requirements.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Missing hyphen in compound modifier "higher-quality code".

As flagged by LanguageTool: "higher-quality" used as a compound adjective before "code" should be hyphenated.

🐛 Proposed fix
-By following these workflows systematically, you produce higher quality code with fewer bugs and better alignment with requirements.
+By following these workflows systematically, you produce higher-quality code with fewer bugs and better alignment with requirements.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
By following these workflows systematically, you produce higher quality code with fewer bugs and better alignment with requirements.
By following these workflows systematically, you produce higher-quality code with fewer bugs and better alignment with requirements.
🧰 Tools
🪛 LanguageTool

[grammar] ~138-~138: Use a hyphen to join words.
Context: ...flows systematically, you produce higher quality code with fewer bugs and better ...

(QB_NEW_EN_HYPHEN)

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.factory/skills/superpowers/SKILL.md at line 138, Replace the compound
modifier "higher quality" with the hyphenated form "higher-quality" in the
sentence beginning "By following these workflows systematically, you produce
higher quality code..." within SKILL.md so the compound adjective before "code"
is correctly hyphenated.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant