workerssuper 5.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (135) hide show
  1. package/.claude-plugin/marketplace.json +20 -0
  2. package/.claude-plugin/plugin.json +13 -0
  3. package/.codex/INSTALL.md +67 -0
  4. package/.cursor-plugin/plugin.json +18 -0
  5. package/.gitattributes +18 -0
  6. package/.github/FUNDING.yml +3 -0
  7. package/.github/ISSUE_TEMPLATE/bug_report.md +52 -0
  8. package/.github/ISSUE_TEMPLATE/config.yml +5 -0
  9. package/.github/ISSUE_TEMPLATE/feature_request.md +34 -0
  10. package/.github/ISSUE_TEMPLATE/platform_support.md +23 -0
  11. package/.github/PULL_REQUEST_TEMPLATE.md +87 -0
  12. package/.opencode/INSTALL.md +83 -0
  13. package/.opencode/plugins/superpowers.js +107 -0
  14. package/CHANGELOG.md +13 -0
  15. package/CODE_OF_CONDUCT.md +128 -0
  16. package/GEMINI.md +2 -0
  17. package/LICENSE +21 -0
  18. package/README.md +187 -0
  19. package/RELEASE-NOTES.md +1057 -0
  20. package/agents/code-reviewer.md +48 -0
  21. package/commands/brainstorm.md +5 -0
  22. package/commands/execute-plan.md +5 -0
  23. package/commands/write-plan.md +5 -0
  24. package/docs/README.codex.md +126 -0
  25. package/docs/README.opencode.md +130 -0
  26. package/docs/plans/2025-11-22-opencode-support-design.md +294 -0
  27. package/docs/plans/2025-11-22-opencode-support-implementation.md +1095 -0
  28. package/docs/plans/2025-11-28-skills-improvements-from-user-feedback.md +711 -0
  29. package/docs/plans/2026-01-17-visual-brainstorming.md +571 -0
  30. package/docs/superpowers/plans/2026-01-22-document-review-system.md +301 -0
  31. package/docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md +523 -0
  32. package/docs/superpowers/plans/2026-03-11-zero-dep-brainstorm-server.md +479 -0
  33. package/docs/superpowers/specs/2026-01-22-document-review-system-design.md +136 -0
  34. package/docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md +162 -0
  35. package/docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md +118 -0
  36. package/docs/testing.md +303 -0
  37. package/docs/windows/polyglot-hooks.md +212 -0
  38. package/gemini-extension.json +6 -0
  39. package/hooks/hooks-cursor.json +10 -0
  40. package/hooks/hooks.json +16 -0
  41. package/hooks/run-hook.cmd +46 -0
  42. package/hooks/session-start +57 -0
  43. package/package.json +5 -0
  44. package/skills/brainstorming/SKILL.md +164 -0
  45. package/skills/brainstorming/scripts/frame-template.html +214 -0
  46. package/skills/brainstorming/scripts/helper.js +88 -0
  47. package/skills/brainstorming/scripts/server.cjs +338 -0
  48. package/skills/brainstorming/scripts/start-server.sh +153 -0
  49. package/skills/brainstorming/scripts/stop-server.sh +55 -0
  50. package/skills/brainstorming/spec-document-reviewer-prompt.md +49 -0
  51. package/skills/brainstorming/visual-companion.md +286 -0
  52. package/skills/dispatching-parallel-agents/SKILL.md +182 -0
  53. package/skills/executing-plans/SKILL.md +70 -0
  54. package/skills/finishing-a-development-branch/SKILL.md +200 -0
  55. package/skills/receiving-code-review/SKILL.md +213 -0
  56. package/skills/requesting-code-review/SKILL.md +105 -0
  57. package/skills/requesting-code-review/code-reviewer.md +146 -0
  58. package/skills/subagent-driven-development/SKILL.md +277 -0
  59. package/skills/subagent-driven-development/code-quality-reviewer-prompt.md +26 -0
  60. package/skills/subagent-driven-development/implementer-prompt.md +113 -0
  61. package/skills/subagent-driven-development/spec-reviewer-prompt.md +61 -0
  62. package/skills/systematic-debugging/CREATION-LOG.md +119 -0
  63. package/skills/systematic-debugging/SKILL.md +296 -0
  64. package/skills/systematic-debugging/condition-based-waiting-example.ts +158 -0
  65. package/skills/systematic-debugging/condition-based-waiting.md +115 -0
  66. package/skills/systematic-debugging/defense-in-depth.md +122 -0
  67. package/skills/systematic-debugging/find-polluter.sh +63 -0
  68. package/skills/systematic-debugging/root-cause-tracing.md +169 -0
  69. package/skills/systematic-debugging/test-academic.md +14 -0
  70. package/skills/systematic-debugging/test-pressure-1.md +58 -0
  71. package/skills/systematic-debugging/test-pressure-2.md +68 -0
  72. package/skills/systematic-debugging/test-pressure-3.md +69 -0
  73. package/skills/test-driven-development/SKILL.md +371 -0
  74. package/skills/test-driven-development/testing-anti-patterns.md +299 -0
  75. package/skills/using-git-worktrees/SKILL.md +218 -0
  76. package/skills/using-superpowers/SKILL.md +115 -0
  77. package/skills/using-superpowers/references/codex-tools.md +25 -0
  78. package/skills/using-superpowers/references/gemini-tools.md +33 -0
  79. package/skills/verification-before-completion/SKILL.md +139 -0
  80. package/skills/writing-plans/SKILL.md +145 -0
  81. package/skills/writing-plans/plan-document-reviewer-prompt.md +49 -0
  82. package/skills/writing-skills/SKILL.md +655 -0
  83. package/skills/writing-skills/anthropic-best-practices.md +1150 -0
  84. package/skills/writing-skills/examples/CLAUDE_MD_TESTING.md +189 -0
  85. package/skills/writing-skills/graphviz-conventions.dot +172 -0
  86. package/skills/writing-skills/persuasion-principles.md +187 -0
  87. package/skills/writing-skills/render-graphs.js +168 -0
  88. package/skills/writing-skills/testing-skills-with-subagents.md +384 -0
  89. package/tests/brainstorm-server/package-lock.json +36 -0
  90. package/tests/brainstorm-server/package.json +10 -0
  91. package/tests/brainstorm-server/server.test.js +424 -0
  92. package/tests/brainstorm-server/windows-lifecycle.test.sh +351 -0
  93. package/tests/brainstorm-server/ws-protocol.test.js +392 -0
  94. package/tests/claude-code/README.md +158 -0
  95. package/tests/claude-code/analyze-token-usage.py +168 -0
  96. package/tests/claude-code/run-skill-tests.sh +187 -0
  97. package/tests/claude-code/test-document-review-system.sh +177 -0
  98. package/tests/claude-code/test-helpers.sh +202 -0
  99. package/tests/claude-code/test-subagent-driven-development-integration.sh +314 -0
  100. package/tests/claude-code/test-subagent-driven-development.sh +165 -0
  101. package/tests/explicit-skill-requests/prompts/action-oriented.txt +3 -0
  102. package/tests/explicit-skill-requests/prompts/after-planning-flow.txt +17 -0
  103. package/tests/explicit-skill-requests/prompts/claude-suggested-it.txt +11 -0
  104. package/tests/explicit-skill-requests/prompts/i-know-what-sdd-means.txt +8 -0
  105. package/tests/explicit-skill-requests/prompts/mid-conversation-execute-plan.txt +3 -0
  106. package/tests/explicit-skill-requests/prompts/please-use-brainstorming.txt +1 -0
  107. package/tests/explicit-skill-requests/prompts/skip-formalities.txt +3 -0
  108. package/tests/explicit-skill-requests/prompts/subagent-driven-development-please.txt +1 -0
  109. package/tests/explicit-skill-requests/prompts/use-systematic-debugging.txt +1 -0
  110. package/tests/explicit-skill-requests/run-all.sh +70 -0
  111. package/tests/explicit-skill-requests/run-claude-describes-sdd.sh +100 -0
  112. package/tests/explicit-skill-requests/run-extended-multiturn-test.sh +113 -0
  113. package/tests/explicit-skill-requests/run-haiku-test.sh +144 -0
  114. package/tests/explicit-skill-requests/run-multiturn-test.sh +143 -0
  115. package/tests/explicit-skill-requests/run-test.sh +136 -0
  116. package/tests/opencode/run-tests.sh +163 -0
  117. package/tests/opencode/setup.sh +73 -0
  118. package/tests/opencode/test-plugin-loading.sh +72 -0
  119. package/tests/opencode/test-priority.sh +198 -0
  120. package/tests/opencode/test-tools.sh +104 -0
  121. package/tests/skill-triggering/prompts/dispatching-parallel-agents.txt +8 -0
  122. package/tests/skill-triggering/prompts/executing-plans.txt +1 -0
  123. package/tests/skill-triggering/prompts/requesting-code-review.txt +3 -0
  124. package/tests/skill-triggering/prompts/systematic-debugging.txt +11 -0
  125. package/tests/skill-triggering/prompts/test-driven-development.txt +7 -0
  126. package/tests/skill-triggering/prompts/writing-plans.txt +10 -0
  127. package/tests/skill-triggering/run-all.sh +60 -0
  128. package/tests/skill-triggering/run-test.sh +88 -0
  129. package/tests/subagent-driven-dev/go-fractals/design.md +81 -0
  130. package/tests/subagent-driven-dev/go-fractals/plan.md +172 -0
  131. package/tests/subagent-driven-dev/go-fractals/scaffold.sh +45 -0
  132. package/tests/subagent-driven-dev/run-test.sh +106 -0
  133. package/tests/subagent-driven-dev/svelte-todo/design.md +70 -0
  134. package/tests/subagent-driven-dev/svelte-todo/plan.md +222 -0
  135. package/tests/subagent-driven-dev/svelte-todo/scaffold.sh +46 -0
@@ -0,0 +1,104 @@
1
+ #!/usr/bin/env bash
2
+ # Test: Tools Functionality
3
+ # Verifies that use_skill and find_skills tools work correctly
4
+ # NOTE: These tests require OpenCode to be installed and configured
5
+ set -euo pipefail
6
+
7
+ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
8
+
9
+ echo "=== Test: Tools Functionality ==="
10
+
11
+ # Source setup to create isolated environment
12
+ source "$SCRIPT_DIR/setup.sh"
13
+
14
+ # Trap to cleanup on exit
15
+ trap cleanup_test_env EXIT
16
+
17
+ # Check if opencode is available
18
+ if ! command -v opencode &> /dev/null; then
19
+ echo " [SKIP] OpenCode not installed - skipping integration tests"
20
+ echo " To run these tests, install OpenCode: https://opencode.ai"
21
+ exit 0
22
+ fi
23
+
24
+ # Test 1: Test find_skills tool via direct invocation
25
+ echo "Test 1: Testing find_skills tool..."
26
+ echo " Running opencode with find_skills request..."
27
+
28
+ # Use timeout to prevent hanging, capture both stdout and stderr
29
+ output=$(timeout 60s opencode run --print-logs "Use the find_skills tool to list available skills. Just call the tool and show me the raw output." 2>&1) || {
30
+ exit_code=$?
31
+ if [ $exit_code -eq 124 ]; then
32
+ echo " [FAIL] OpenCode timed out after 60s"
33
+ exit 1
34
+ fi
35
+ echo " [WARN] OpenCode returned non-zero exit code: $exit_code"
36
+ }
37
+
38
+ # Check for expected patterns in output
39
+ if echo "$output" | grep -qi "superpowers:brainstorming\|superpowers:using-superpowers\|Available skills"; then
40
+ echo " [PASS] find_skills tool discovered superpowers skills"
41
+ else
42
+ echo " [FAIL] find_skills did not return expected skills"
43
+ echo " Output was:"
44
+ echo "$output" | head -50
45
+ exit 1
46
+ fi
47
+
48
+ # Check if personal test skill was found
49
+ if echo "$output" | grep -qi "personal-test"; then
50
+ echo " [PASS] find_skills found personal test skill"
51
+ else
52
+ echo " [WARN] personal test skill not found in output (may be ok if tool returned subset)"
53
+ fi
54
+
55
+ # Test 2: Test use_skill tool
56
+ echo ""
57
+ echo "Test 2: Testing use_skill tool..."
58
+ echo " Running opencode with use_skill request..."
59
+
60
+ output=$(timeout 60s opencode run --print-logs "Use the use_skill tool to load the personal-test skill and show me what you get." 2>&1) || {
61
+ exit_code=$?
62
+ if [ $exit_code -eq 124 ]; then
63
+ echo " [FAIL] OpenCode timed out after 60s"
64
+ exit 1
65
+ fi
66
+ echo " [WARN] OpenCode returned non-zero exit code: $exit_code"
67
+ }
68
+
69
+ # Check for the skill marker we embedded
70
+ if echo "$output" | grep -qi "PERSONAL_SKILL_MARKER_12345\|Personal Test Skill\|Launching skill"; then
71
+ echo " [PASS] use_skill loaded personal-test skill content"
72
+ else
73
+ echo " [FAIL] use_skill did not load personal-test skill correctly"
74
+ echo " Output was:"
75
+ echo "$output" | head -50
76
+ exit 1
77
+ fi
78
+
79
+ # Test 3: Test use_skill with superpowers: prefix
80
+ echo ""
81
+ echo "Test 3: Testing use_skill with superpowers: prefix..."
82
+ echo " Running opencode with superpowers:brainstorming skill..."
83
+
84
+ output=$(timeout 60s opencode run --print-logs "Use the use_skill tool to load superpowers:brainstorming and tell me the first few lines of what you received." 2>&1) || {
85
+ exit_code=$?
86
+ if [ $exit_code -eq 124 ]; then
87
+ echo " [FAIL] OpenCode timed out after 60s"
88
+ exit 1
89
+ fi
90
+ echo " [WARN] OpenCode returned non-zero exit code: $exit_code"
91
+ }
92
+
93
+ # Check for expected content from brainstorming skill
94
+ if echo "$output" | grep -qi "brainstorming\|Launching skill\|skill.*loaded"; then
95
+ echo " [PASS] use_skill loaded superpowers:brainstorming skill"
96
+ else
97
+ echo " [FAIL] use_skill did not load superpowers:brainstorming correctly"
98
+ echo " Output was:"
99
+ echo "$output" | head -50
100
+ exit 1
101
+ fi
102
+
103
+ echo ""
104
+ echo "=== All tools tests passed ==="
@@ -0,0 +1,8 @@
1
+ I have 4 independent test failures happening in different modules:
2
+
3
+ 1. tests/auth/login.test.ts - "should redirect after login" is failing
4
+ 2. tests/api/users.test.ts - "should return user list" returns 500
5
+ 3. tests/components/Button.test.tsx - snapshot mismatch
6
+ 4. tests/utils/date.test.ts - timezone handling broken
7
+
8
+ These are unrelated issues in different parts of the codebase. Can you investigate all of them?
@@ -0,0 +1 @@
1
+ I have a plan document at docs/superpowers/plans/2024-01-15-auth-system.md that needs to be executed. Please implement it.
@@ -0,0 +1,3 @@
1
+ I just finished implementing the user authentication feature. All the code is committed. Can you review the changes before I merge to main?
2
+
3
+ The commits are between abc123 and def456.
@@ -0,0 +1,11 @@
1
+ The tests are failing with this error:
2
+
3
+ ```
4
+ FAIL src/utils/parser.test.ts
5
+ ● Parser › should handle nested objects
6
+ TypeError: Cannot read property 'value' of undefined
7
+ at parse (src/utils/parser.ts:42:18)
8
+ at Object.<anonymous> (src/utils/parser.test.ts:28:20)
9
+ ```
10
+
11
+ Can you figure out what's going wrong and fix it?
@@ -0,0 +1,7 @@
1
+ I need to add a new feature to validate email addresses. It should:
2
+ - Check that there's an @ symbol
3
+ - Check that there's at least one character before the @
4
+ - Check that there's a dot in the domain part
5
+ - Return true/false
6
+
7
+ Can you implement this?
@@ -0,0 +1,10 @@
1
+ Here's the spec for our new authentication system:
2
+
3
+ Requirements:
4
+ - Users can register with email/password
5
+ - Users can log in and receive a JWT token
6
+ - Protected routes require valid JWT
7
+ - Tokens expire after 24 hours
8
+ - Support password reset via email
9
+
10
+ We need to implement this. There are multiple steps involved - user model, auth routes, middleware, email service integration.
@@ -0,0 +1,60 @@
1
+ #!/usr/bin/env bash
2
+ # Run all skill triggering tests
3
+ # Usage: ./run-all.sh
4
+
5
+ set -e
6
+
7
+ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
8
+ PROMPTS_DIR="$SCRIPT_DIR/prompts"
9
+
10
+ SKILLS=(
11
+ "systematic-debugging"
12
+ "test-driven-development"
13
+ "writing-plans"
14
+ "dispatching-parallel-agents"
15
+ "executing-plans"
16
+ "requesting-code-review"
17
+ )
18
+
19
+ echo "=== Running Skill Triggering Tests ==="
20
+ echo ""
21
+
22
+ PASSED=0
23
+ FAILED=0
24
+ RESULTS=()
25
+
26
+ for skill in "${SKILLS[@]}"; do
27
+ prompt_file="$PROMPTS_DIR/${skill}.txt"
28
+
29
+ if [ ! -f "$prompt_file" ]; then
30
+ echo "⚠️ SKIP: No prompt file for $skill"
31
+ continue
32
+ fi
33
+
34
+ echo "Testing: $skill"
35
+
36
+ if "$SCRIPT_DIR/run-test.sh" "$skill" "$prompt_file" 3 2>&1 | tee /tmp/skill-test-$skill.log; then
37
+ PASSED=$((PASSED + 1))
38
+ RESULTS+=("✅ $skill")
39
+ else
40
+ FAILED=$((FAILED + 1))
41
+ RESULTS+=("❌ $skill")
42
+ fi
43
+
44
+ echo ""
45
+ echo "---"
46
+ echo ""
47
+ done
48
+
49
+ echo ""
50
+ echo "=== Summary ==="
51
+ for result in "${RESULTS[@]}"; do
52
+ echo " $result"
53
+ done
54
+ echo ""
55
+ echo "Passed: $PASSED"
56
+ echo "Failed: $FAILED"
57
+
58
+ if [ $FAILED -gt 0 ]; then
59
+ exit 1
60
+ fi
@@ -0,0 +1,88 @@
1
+ #!/usr/bin/env bash
2
+ # Test skill triggering with naive prompts
3
+ # Usage: ./run-test.sh <skill-name> <prompt-file>
4
+ #
5
+ # Tests whether Claude triggers a skill based on a natural prompt
6
+ # (without explicitly mentioning the skill)
7
+
8
+ set -e
9
+
10
+ SKILL_NAME="$1"
11
+ PROMPT_FILE="$2"
12
+ MAX_TURNS="${3:-3}"
13
+
14
+ if [ -z "$SKILL_NAME" ] || [ -z "$PROMPT_FILE" ]; then
15
+ echo "Usage: $0 <skill-name> <prompt-file> [max-turns]"
16
+ echo "Example: $0 systematic-debugging ./test-prompts/debugging.txt"
17
+ exit 1
18
+ fi
19
+
20
+ # Get the directory where this script lives (should be tests/skill-triggering)
21
+ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
22
+ # Get the superpowers plugin root (two levels up from tests/skill-triggering)
23
+ PLUGIN_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
24
+
25
+ TIMESTAMP=$(date +%s)
26
+ OUTPUT_DIR="/tmp/superpowers-tests/${TIMESTAMP}/skill-triggering/${SKILL_NAME}"
27
+ mkdir -p "$OUTPUT_DIR"
28
+
29
+ # Read prompt from file
30
+ PROMPT=$(cat "$PROMPT_FILE")
31
+
32
+ echo "=== Skill Triggering Test ==="
33
+ echo "Skill: $SKILL_NAME"
34
+ echo "Prompt file: $PROMPT_FILE"
35
+ echo "Max turns: $MAX_TURNS"
36
+ echo "Output dir: $OUTPUT_DIR"
37
+ echo ""
38
+
39
+ # Copy prompt for reference
40
+ cp "$PROMPT_FILE" "$OUTPUT_DIR/prompt.txt"
41
+
42
+ # Run Claude
43
+ LOG_FILE="$OUTPUT_DIR/claude-output.json"
44
+ cd "$OUTPUT_DIR"
45
+
46
+ echo "Plugin dir: $PLUGIN_DIR"
47
+ echo "Running claude -p with naive prompt..."
48
+ timeout 300 claude -p "$PROMPT" \
49
+ --plugin-dir "$PLUGIN_DIR" \
50
+ --dangerously-skip-permissions \
51
+ --max-turns "$MAX_TURNS" \
52
+ --output-format stream-json \
53
+ > "$LOG_FILE" 2>&1 || true
54
+
55
+ echo ""
56
+ echo "=== Results ==="
57
+
58
+ # Check if skill was triggered (look for Skill tool invocation)
59
+ # In stream-json, tool invocations have "name":"Skill" (not "tool":"Skill")
60
+ # Match either "skill":"skillname" or "skill":"namespace:skillname"
61
+ SKILL_PATTERN='"skill":"([^"]*:)?'"${SKILL_NAME}"'"'
62
+ if grep -q '"name":"Skill"' "$LOG_FILE" && grep -qE "$SKILL_PATTERN" "$LOG_FILE"; then
63
+ echo "✅ PASS: Skill '$SKILL_NAME' was triggered"
64
+ TRIGGERED=true
65
+ else
66
+ echo "❌ FAIL: Skill '$SKILL_NAME' was NOT triggered"
67
+ TRIGGERED=false
68
+ fi
69
+
70
+ # Show what skills WERE triggered
71
+ echo ""
72
+ echo "Skills triggered in this run:"
73
+ grep -o '"skill":"[^"]*"' "$LOG_FILE" 2>/dev/null | sort -u || echo " (none)"
74
+
75
+ # Show first assistant message
76
+ echo ""
77
+ echo "First assistant response (truncated):"
78
+ grep '"type":"assistant"' "$LOG_FILE" | head -1 | jq -r '.message.content[0].text // .message.content' 2>/dev/null | head -c 500 || echo " (could not extract)"
79
+
80
+ echo ""
81
+ echo "Full log: $LOG_FILE"
82
+ echo "Timestamp: $TIMESTAMP"
83
+
84
+ if [ "$TRIGGERED" = "true" ]; then
85
+ exit 0
86
+ else
87
+ exit 1
88
+ fi
@@ -0,0 +1,81 @@
1
+ # Go Fractals CLI - Design
2
+
3
+ ## Overview
4
+
5
+ A command-line tool that generates ASCII art fractals. Supports two fractal types with configurable output.
6
+
7
+ ## Usage
8
+
9
+ ```bash
10
+ # Sierpinski triangle
11
+ fractals sierpinski --size 32 --depth 5
12
+
13
+ # Mandelbrot set
14
+ fractals mandelbrot --width 80 --height 24 --iterations 100
15
+
16
+ # Custom character
17
+ fractals sierpinski --size 16 --char '#'
18
+
19
+ # Help
20
+ fractals --help
21
+ fractals sierpinski --help
22
+ ```
23
+
24
+ ## Commands
25
+
26
+ ### `sierpinski`
27
+
28
+ Generates a Sierpinski triangle using recursive subdivision.
29
+
30
+ Flags:
31
+ - `--size` (default: 32) - Width of the triangle base in characters
32
+ - `--depth` (default: 5) - Recursion depth
33
+ - `--char` (default: '*') - Character to use for filled points
34
+
35
+ Output: Triangle printed to stdout, one line per row.
36
+
37
+ ### `mandelbrot`
38
+
39
+ Renders the Mandelbrot set as ASCII art. Maps iteration count to characters.
40
+
41
+ Flags:
42
+ - `--width` (default: 80) - Output width in characters
43
+ - `--height` (default: 24) - Output height in characters
44
+ - `--iterations` (default: 100) - Maximum iterations for escape calculation
45
+ - `--char` (default: gradient) - Single character, or omit for gradient " .:-=+*#%@"
46
+
47
+ Output: Rectangle printed to stdout.
48
+
49
+ ## Architecture
50
+
51
+ ```
52
+ cmd/
53
+ fractals/
54
+ main.go # Entry point, CLI setup
55
+ internal/
56
+ sierpinski/
57
+ sierpinski.go # Algorithm
58
+ sierpinski_test.go
59
+ mandelbrot/
60
+ mandelbrot.go # Algorithm
61
+ mandelbrot_test.go
62
+ cli/
63
+ root.go # Root command, help
64
+ sierpinski.go # Sierpinski subcommand
65
+ mandelbrot.go # Mandelbrot subcommand
66
+ ```
67
+
68
+ ## Dependencies
69
+
70
+ - Go 1.21+
71
+ - `github.com/spf13/cobra` for CLI
72
+
73
+ ## Acceptance Criteria
74
+
75
+ 1. `fractals --help` shows usage
76
+ 2. `fractals sierpinski` outputs a recognizable triangle
77
+ 3. `fractals mandelbrot` outputs a recognizable Mandelbrot set
78
+ 4. `--size`, `--width`, `--height`, `--depth`, `--iterations` flags work
79
+ 5. `--char` customizes output character
80
+ 6. Invalid inputs produce clear error messages
81
+ 7. All tests pass
@@ -0,0 +1,172 @@
1
+ # Go Fractals CLI - Implementation Plan
2
+
3
+ Execute this plan using the `superpowers:subagent-driven-development` skill.
4
+
5
+ ## Context
6
+
7
+ Building a CLI tool that generates ASCII fractals. See `design.md` for full specification.
8
+
9
+ ## Tasks
10
+
11
+ ### Task 1: Project Setup
12
+
13
+ Create the Go module and directory structure.
14
+
15
+ **Do:**
16
+ - Initialize `go.mod` with module name `github.com/superpowers-test/fractals`
17
+ - Create directory structure: `cmd/fractals/`, `internal/sierpinski/`, `internal/mandelbrot/`, `internal/cli/`
18
+ - Create minimal `cmd/fractals/main.go` that prints "fractals cli"
19
+ - Add `github.com/spf13/cobra` dependency
20
+
21
+ **Verify:**
22
+ - `go build ./cmd/fractals` succeeds
23
+ - `./fractals` prints "fractals cli"
24
+
25
+ ---
26
+
27
+ ### Task 2: CLI Framework with Help
28
+
29
+ Set up Cobra root command with help output.
30
+
31
+ **Do:**
32
+ - Create `internal/cli/root.go` with root command
33
+ - Configure help text showing available subcommands
34
+ - Wire root command into `main.go`
35
+
36
+ **Verify:**
37
+ - `./fractals --help` shows usage with "sierpinski" and "mandelbrot" listed as available commands
38
+ - `./fractals` (no args) shows help
39
+
40
+ ---
41
+
42
+ ### Task 3: Sierpinski Algorithm
43
+
44
+ Implement the Sierpinski triangle generation algorithm.
45
+
46
+ **Do:**
47
+ - Create `internal/sierpinski/sierpinski.go`
48
+ - Implement `Generate(size, depth int, char rune) []string` that returns lines of the triangle
49
+ - Use recursive midpoint subdivision algorithm
50
+ - Create `internal/sierpinski/sierpinski_test.go` with tests:
51
+ - Small triangle (size=4, depth=2) matches expected output
52
+ - Size=1 returns single character
53
+ - Depth=0 returns filled triangle
54
+
55
+ **Verify:**
56
+ - `go test ./internal/sierpinski/...` passes
57
+
58
+ ---
59
+
60
+ ### Task 4: Sierpinski CLI Integration
61
+
62
+ Wire the Sierpinski algorithm to a CLI subcommand.
63
+
64
+ **Do:**
65
+ - Create `internal/cli/sierpinski.go` with `sierpinski` subcommand
66
+ - Add flags: `--size` (default 32), `--depth` (default 5), `--char` (default '*')
67
+ - Call `sierpinski.Generate()` and print result to stdout
68
+
69
+ **Verify:**
70
+ - `./fractals sierpinski` outputs a triangle
71
+ - `./fractals sierpinski --size 16 --depth 3` outputs smaller triangle
72
+ - `./fractals sierpinski --help` shows flag documentation
73
+
74
+ ---
75
+
76
+ ### Task 5: Mandelbrot Algorithm
77
+
78
+ Implement the Mandelbrot set ASCII renderer.
79
+
80
+ **Do:**
81
+ - Create `internal/mandelbrot/mandelbrot.go`
82
+ - Implement `Render(width, height, maxIter int, char string) []string`
83
+ - Map complex plane region (-2.5 to 1.0 real, -1.0 to 1.0 imaginary) to output dimensions
84
+ - Map iteration count to character gradient " .:-=+*#%@" (or single char if provided)
85
+ - Create `internal/mandelbrot/mandelbrot_test.go` with tests:
86
+ - Output dimensions match requested width/height
87
+ - Known point inside set (0,0) maps to max-iteration character
88
+ - Known point outside set (2,0) maps to low-iteration character
89
+
90
+ **Verify:**
91
+ - `go test ./internal/mandelbrot/...` passes
92
+
93
+ ---
94
+
95
+ ### Task 6: Mandelbrot CLI Integration
96
+
97
+ Wire the Mandelbrot algorithm to a CLI subcommand.
98
+
99
+ **Do:**
100
+ - Create `internal/cli/mandelbrot.go` with `mandelbrot` subcommand
101
+ - Add flags: `--width` (default 80), `--height` (default 24), `--iterations` (default 100), `--char` (default "")
102
+ - Call `mandelbrot.Render()` and print result to stdout
103
+
104
+ **Verify:**
105
+ - `./fractals mandelbrot` outputs recognizable Mandelbrot set
106
+ - `./fractals mandelbrot --width 40 --height 12` outputs smaller version
107
+ - `./fractals mandelbrot --help` shows flag documentation
108
+
109
+ ---
110
+
111
+ ### Task 7: Character Set Configuration
112
+
113
+ Ensure `--char` flag works consistently across both commands.
114
+
115
+ **Do:**
116
+ - Verify Sierpinski `--char` flag passes character to algorithm
117
+ - For Mandelbrot, `--char` should use single character instead of gradient
118
+ - Add tests for custom character output
119
+
120
+ **Verify:**
121
+ - `./fractals sierpinski --char '#'` uses '#' character
122
+ - `./fractals mandelbrot --char '.'` uses '.' for all filled points
123
+ - Tests pass
124
+
125
+ ---
126
+
127
+ ### Task 8: Input Validation and Error Handling
128
+
129
+ Add validation for invalid inputs.
130
+
131
+ **Do:**
132
+ - Sierpinski: size must be > 0, depth must be >= 0
133
+ - Mandelbrot: width/height must be > 0, iterations must be > 0
134
+ - Return clear error messages for invalid inputs
135
+ - Add tests for error cases
136
+
137
+ **Verify:**
138
+ - `./fractals sierpinski --size 0` prints error, exits non-zero
139
+ - `./fractals mandelbrot --width -1` prints error, exits non-zero
140
+ - Error messages are clear and helpful
141
+
142
+ ---
143
+
144
+ ### Task 9: Integration Tests
145
+
146
+ Add integration tests that invoke the CLI.
147
+
148
+ **Do:**
149
+ - Create `cmd/fractals/main_test.go` or `test/integration_test.go`
150
+ - Test full CLI invocation for both commands
151
+ - Verify output format and exit codes
152
+ - Test error cases return non-zero exit
153
+
154
+ **Verify:**
155
+ - `go test ./...` passes all tests including integration tests
156
+
157
+ ---
158
+
159
+ ### Task 10: README
160
+
161
+ Document usage and examples.
162
+
163
+ **Do:**
164
+ - Create `README.md` with:
165
+ - Project description
166
+ - Installation: `go install ./cmd/fractals`
167
+ - Usage examples for both commands
168
+ - Example output (small samples)
169
+
170
+ **Verify:**
171
+ - README accurately describes the tool
172
+ - Examples in README actually work
@@ -0,0 +1,45 @@
1
+ #!/usr/bin/env bash
2
+ # Scaffold the Go Fractals test project
3
+ # Usage: ./scaffold.sh /path/to/target/directory
4
+
5
+ set -e
6
+
7
+ TARGET_DIR="${1:?Usage: $0 <target-directory>}"
8
+ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
9
+
10
+ # Create target directory
11
+ mkdir -p "$TARGET_DIR"
12
+ cd "$TARGET_DIR"
13
+
14
+ # Initialize git repo
15
+ git init
16
+
17
+ # Copy design and plan
18
+ cp "$SCRIPT_DIR/design.md" .
19
+ cp "$SCRIPT_DIR/plan.md" .
20
+
21
+ # Create .claude settings to allow reads/writes in this directory
22
+ mkdir -p .claude
23
+ cat > .claude/settings.local.json << 'SETTINGS'
24
+ {
25
+ "permissions": {
26
+ "allow": [
27
+ "Read(**)",
28
+ "Edit(**)",
29
+ "Write(**)",
30
+ "Bash(go:*)",
31
+ "Bash(mkdir:*)",
32
+ "Bash(git:*)"
33
+ ]
34
+ }
35
+ }
36
+ SETTINGS
37
+
38
+ # Create initial commit
39
+ git add .
40
+ git commit -m "Initial project setup with design and plan"
41
+
42
+ echo "Scaffolded Go Fractals project at: $TARGET_DIR"
43
+ echo ""
44
+ echo "To run the test:"
45
+ echo " claude -p \"Execute this plan using superpowers:subagent-driven-development. Plan: $TARGET_DIR/plan.md\" --plugin-dir /path/to/superpowers"