Planning Superpowers Pro

Advanced task planning and developer toolkit. Integrates TDD (Test-Driven Development) workflows, systematic debugging protocols, and file-driven task tracki...

Security Scan

The skill generally matches its stated planning/TDD purpose, but its runtime guidance explicitly encourages persisting potentially sensitive data (API keys, URLs, raw browser outputs) to disk and includes a script that reads local agent session stores — behaviors that are disproportionate to a planner and raise privacy/security concerns.

Purpose & Capability

Name/description (TDD + file-based planning) match the included templates and scripts. However, the skill's guidance explicitly instructs storing API keys, URLs, and other discovered data into findings.md and to capture 'multimodal data' as text on disk — asking to persist secrets is not necessary for a planning/TDD tool and is disproportionate to the stated purpose.

Instruction Scope

SKILL.md and templates direct the agent to (a) run scripts/session-catchup.py which reads local agent session stores and prints unsynced messages, and (b) persist many kinds of context (including API keys and full browser outputs) to findings.md under the 2‑Action Rule. These instructions expand scope to reading and materializing potentially sensitive conversational and web data beyond the immediate project files.

Install Mechanism

No install spec (instruction-only) and included scripts are local. There is no network download/install step. Risk from install mechanism is low because nothing is fetched or installed automatically.

Credentials

The skill declares no required credentials or env vars, yet templates explicitly tell agents to record 'API keys' and other sensitive data in findings.md. That mismatch (no declared secrets but instructions to persist secrets) is disproportionate and risky — it encourages local storage of credentials without safeguards.

Persistence & Privilege

always:false and no global installation privileges. However, scripts read the user's home session directories (~/.claude, ~/.codex) to reconstruct prior agent messages and may print user messages and tool outputs. The skill also writes persistent planning files into the project directory. Combined, this grants broad local read access (session logs) and write access (project files), which is reasonable for a catchup/planning tool but requires caution.

What to consider before installing

This skill looks like a coherent TDD + planning toolkit, but it instructs agents to persist wide-ranging context — including API keys, URLs, browser outputs, and previous agent messages — to plaintext files and includes a script that reads local agent session stores and prints user/assistant content. Before installing or running it: - Inspect and sanitize templates (findings.md) to remove any instruction to store secrets. Never save API keys, passwords, or tokens in plaintext files. - Review scripts/session-catchup.py and consider removing or modifying the parts that read ~/.claude or ~/.codex if you don't want local agent session logs parsed/printed. - Run the scripts in an isolated environment (sandbox or non-sensitive project) first to observe behavior. - If you plan to capture external info, add explicit rules to redact secrets and avoid persisting sensitive multimodal content unencrypted. - If you are not comfortable with local session logs being read or with automated storing of discovered credentials, do not enable this skill for sensitive projects. If the template guidance to store API keys is removed and the catchup script is limited to only project-local files (no home agent sessions), the skill would be much less risky and more clearly proportionate to its purpose.

Combined file-based planning (Planning with Files) and spec-first TDD development (Superpowers).

The Core Mandate

1. Plan First: Never start a task without task_plan.md.
2. TDD Required: No production code without a failing test first.
3. Systematic Debugging: No fixes without root cause investigation.
4. Persistent Memory: Use markdown files (task_plan.md, findings.md, progress.md) as your "working memory on disk."

---

1. Initialization (Start of Task)

Before doing anything else, initialize the planning files.

Recovery Check

If task_plan.md already exists, read it along with progress.md and findings.md to restore context. Run catchup:

python3 scripts/session-catchup.py "$(pwd)"

New Project Setup

Create the holy trinity of planning:

• task_plan.md: The roadmap and state.
• findings.md: Research, decisions, and discovered data.
• progress.md: Detailed session log and test results.

Use scripts/init-session.sh to scaffold these.

---

2. Planning Phase (TDD Planning)

Every task must be broken down into "TDD-sized" chunks (2-10 minutes each). A valid task in task_plan.md must follow this micro-loop:

1. Write a failing test.
2. Watch it fail.
3. Write minimal code to pass.
4. Watch it pass.
5. Refactor.
6. Commit.

Hard Gate: Do not write production code until a failing test is verified in progress.md.

---

3. Execution & Subagents

For complex tasks, use sessions_spawn to delegate to subagents.

Implementer Subagent Prompt Pattern:

Goal: [Target behavior]
Context: [Link to task_plan.md / design docs]
TDD Requirement: Write test first -> watch fail -> implement -> watch pass.
Verification: Run [test command].

---

4. Systematic Debugging

When a test fails or an error occurs, do not "just try a fix." Follow the Systematic Debugging Protocol:

1. Investigate: Read full stack traces. Trace data flow to the source.
2. Reproduce: Ensure the failure is consistent.
3. Hypothesize: State "I think [cause] because [evidence]" before editing.
4. Test Hypothesis: Prove/disprove the hypothesis with a minimal test.
5. Fix at Root: Fix the cause, not the symptom. Log in task_plan.md.

---

5. File Management Rules

File	Update Frequency	Content
task_plan.md	After each phase	Status, Decisions, Error Log
findings.md	Every 2 tool calls	Research, API keys, URLs, Data
progress.md	Every action	Test outputs, CLI logs, small wins

The 2-Action Rule

After every 2 search or browser operations, move data from context to findings.md. Multimodal data (images/PDFs) must be summarized as text immediately.

---

6. Finishing

1. Verify all tests pass.
2. Update task_plan.md to complete.
3. Provide final summary and clean up temporary files.

Templates & References

• Templates: templates/task_plan.md, templates/findings.md, templates/progress.md
• Reference Docs: references/tdd.md, references/systematic-debugging.md, references/brainstorming.md