superpowers/tests/subagent-driven-dev/go-fractals/plan.md

Go Fractals CLI - Implementation Plan

Execute this plan using the superpowers:subagent-driven-development skill.

Context

Building a CLI tool that generates ASCII fractals. See design.md for full specification.

Tasks

Task 1: Project Setup

Create the Go module and directory structure.

Do:

• Initialize go.mod with module name github.com/superpowers-test/fractals
• Create directory structure: cmd/fractals/, internal/sierpinski/, internal/mandelbrot/, internal/cli/
• Create minimal cmd/fractals/main.go that prints "fractals cli"
• Add github.com/spf13/cobra dependency

Verify:

• go build ./cmd/fractals succeeds
• ./fractals prints "fractals cli"

---

Task 2: CLI Framework with Help

Set up Cobra root command with help output.

Do:

• Create internal/cli/root.go with root command
• Configure help text showing available subcommands
• Wire root command into main.go

Verify:

• ./fractals --help shows usage with "sierpinski" and "mandelbrot" listed as available commands
• ./fractals (no args) shows help

---

Task 3: Sierpinski Algorithm

Implement the Sierpinski triangle generation algorithm.

Do:

• Create internal/sierpinski/sierpinski.go
• Implement Generate(size, depth int, char rune) []string that returns lines of the triangle
• Use recursive midpoint subdivision algorithm
• Create internal/sierpinski/sierpinski_test.go with tests:
  • Small triangle (size=4, depth=2) matches expected output
  • Size=1 returns single character
  • Depth=0 returns filled triangle

Verify:

• go test ./internal/sierpinski/... passes

---

Task 4: Sierpinski CLI Integration

Wire the Sierpinski algorithm to a CLI subcommand.

Do:

• Create internal/cli/sierpinski.go with sierpinski subcommand
• Add flags: --size (default 32), --depth (default 5), --char (default '*')
• Call sierpinski.Generate() and print result to stdout

Verify:

• ./fractals sierpinski outputs a triangle
• ./fractals sierpinski --size 16 --depth 3 outputs smaller triangle
• ./fractals sierpinski --help shows flag documentation

---

Task 5: Mandelbrot Algorithm

Implement the Mandelbrot set ASCII renderer.

Do:

• Create internal/mandelbrot/mandelbrot.go
• Implement Render(width, height, maxIter int, char string) []string
• Map complex plane region (-2.5 to 1.0 real, -1.0 to 1.0 imaginary) to output dimensions
• Map iteration count to character gradient " .:-=+*#%@" (or single char if provided)
• Create internal/mandelbrot/mandelbrot_test.go with tests:
  • Output dimensions match requested width/height
  • Known point inside set (0,0) maps to max-iteration character
  • Known point outside set (2,0) maps to low-iteration character

Verify:

• go test ./internal/mandelbrot/... passes

---

Task 6: Mandelbrot CLI Integration

Wire the Mandelbrot algorithm to a CLI subcommand.

Do:

• Create internal/cli/mandelbrot.go with mandelbrot subcommand
• Add flags: --width (default 80), --height (default 24), --iterations (default 100), --char (default "")
• Call mandelbrot.Render() and print result to stdout

Verify:

• ./fractals mandelbrot outputs recognizable Mandelbrot set
• ./fractals mandelbrot --width 40 --height 12 outputs smaller version
• ./fractals mandelbrot --help shows flag documentation

---

Task 7: Character Set Configuration

Ensure --char flag works consistently across both commands.

Do:

• Verify Sierpinski --char flag passes character to algorithm
• For Mandelbrot, --char should use single character instead of gradient
• Add tests for custom character output

Verify:

• ./fractals sierpinski --char '#' uses '#' character
• ./fractals mandelbrot --char '.' uses '.' for all filled points
• Tests pass

---

Task 8: Input Validation and Error Handling

Add validation for invalid inputs.

Do:

• Sierpinski: size must be > 0, depth must be >= 0
• Mandelbrot: width/height must be > 0, iterations must be > 0
• Return clear error messages for invalid inputs
• Add tests for error cases

Verify:

• ./fractals sierpinski --size 0 prints error, exits non-zero
• ./fractals mandelbrot --width -1 prints error, exits non-zero
• Error messages are clear and helpful

---

Task 9: Integration Tests

Add integration tests that invoke the CLI.

Do:

• Create cmd/fractals/main_test.go or test/integration_test.go
• Test full CLI invocation for both commands
• Verify output format and exit codes
• Test error cases return non-zero exit

Verify:

• go test ./... passes all tests including integration tests

---

Task 10: README

Document usage and examples.

Do:

• Create README.md with:
  • Project description
  • Installation: go install ./cmd/fractals
  • Usage examples for both commands
  • Example output (small samples)

Verify:

• README accurately describes the tool
• Examples in README actually work