Writing Plans Variant

core-commands_SKILL.md

name	core-commands
description	Core command guidelines - prohibited commands and temp file patterns. ALWAYS load this skill at session start.

Core Commands

This skill defines prohibited commands and the temp file pattern for multi-line content.

Before Running Any Command

Check if the command starts with a prohibited prefix:

1. Does it start with git? → Find jj equivalent in table below
2. Does it start with jj log? → Use jj status instead
3. Does it start with jj op? → Not allowed, ask user
4. Does it start with jj abandon? → Use jj new instead
5. Does it start with jj edit? → Not allowed, use jj new instead
6. Does it start with jj prev or jj next? → Ask user first
7. Does it have -i flag? → Not allowed (interactive)
8. Does jj new have any arguments? → Not allowed, use plain jj new only

Prohibited Commands

NEVER use git commands. This repo uses jj exclusively.

Prohibition is prefix-based: Commands matching the start of a prohibited pattern are forbidden (e.g., jj log -r 'all()' matches jj log*).

Prohibited jj Commands (Prefix Patterns)

• jj abandon* - Do not abandon changes
• jj describe before changes are ready and reviewed
• jj edit* - Moves working copy unexpectedly, use jj new instead
• jj git push without explicit user confirmation
• jj log* - Produces incoherent output
• jj new with any arguments - Only plain jj new allowed
• jj op* - Operations commands not allowed
• jj prev* / jj next* - Navigation requires user confirmation
• jj rebase* - Can break change dependencies
• jj squash* - Violates atomic commit history
• jj split* - Breaks atomicity
• Interactive commands with -i flag

Prohibited Actions

• Update git config
• Run destructive commands without explicit request
• Skip hooks without explicit request
• Commit without explicit request
• Push without explicit confirmation
• Commit secrets or credentials
• Expose or log secrets

Command Alternatives

Prohibited Pattern	Why	Use Instead
jj log*	Incoherent output	jj status or jj op log
jj op*	Not allowed	jj status or ask user
jj abandon*	Destructive	Create new change with jj new
jj prev* / jj next*	Needs confirmation	Ask user first
git status	Wrong VCS	jj status
git branch*	Wrong VCS	jj bookmark list
git checkout*	Wrong VCS	jj new
git commit*	Wrong VCS	jj describe
git push*	Wrong VCS	jj git push (with confirmation)
git pull*	Wrong VCS	jj git fetch
git merge*	Wrong VCS	jj merge or rebase approach
git rebase*	Wrong VCS	Use jj's automatic rebasing

GitHub (gh) Commands

Action	Command	Notes
Create issue	gh issue new -t '<title>' -F "$TMPFILE"	Use temp file pattern for body
Create PR (draft)	gh pr create --draft --base <base> --head <bookmark> --title "<title>" -F "$TMPFILE"	Use temp file pattern
Comment on PR	gh pr comment <number> --body-file "$TMPFILE"	Use temp file pattern
View issue	gh issue view <number>	-
View PR	gh pr view <number>	-
View PR diff	gh pr diff <number>	-
List issues	gh issue list	-
List PRs	gh pr list	-

Temp File Pattern for Multi-Line Content

NEVER use heredocs (cat <<'EOF') or echo for multi-line content. These patterns have escaping issues and produce unreliable output.

ALWAYS use the mktemp + Write tool pattern:

Each Bash tool invocation runs in an independent shell environment. Variables set in one command do NOT persist to subsequent commands. Therefore:

1. Get temp file path - Run plain mktemp without variable assignment:

   mktemp

   The tool returns a path like /tmp/tmp.XXXXXX.

2. Read existing file - Use the Read tool with the path from step 1 to check if it already contains content.

3. Write content - Use the Write tool with the path from step 1 as a literal string to write/overwrite the content.

4. Pass file to command - Use the same path as a literal string:

   <command> --option "/tmp/tmp.XXXXXX"

5. Clean up - Remove the file when done:

   rm "/tmp/tmp.XXXXXX"

Key insight: The temp file path must be captured from the tool output and used as a literal string in all subsequent commands. Do NOT use shell variables. Always read existing temp file content before overwriting.

Examples

Creating GitHub issue:

mktemp
# Tool returns: /tmp/tmp.XXXXXX
# Use Read tool to check existing content, then Write tool to write issue description
gh issue new -t 'Issue title' -F "/tmp/tmp.XXXXXX"
rm "/tmp/tmp.XXXXXX"

Describing commit with complex message:

mktemp
# Tool returns: /tmp/tmp.XXXXXX
# Use Read tool to check existing content, then Write tool to write commit message
jj describe --stdin < "/tmp/tmp.XXXXXX"
rm "/tmp/tmp.XXXXXX"

Creating PR:

mktemp
# Tool returns: /tmp/tmp.XXXXXX
# Use Read tool to check existing content, then Write tool to write PR description
gh pr create --draft --base main --head username/issue-123 --title "PR title" -F "/tmp/tmp.XXXXXX"
rm "/tmp/tmp.XXXXXX"

Why This Matters

• Heredocs fail when content contains special characters, variables, or nested quotes
• echo fails with backslashes and special characters
• Write tool handles all escaping correctly and consistently

writing-plans_plan-document-reviewer-prompt.md

Plan Document Reviewer Prompt Template

Use this template when dispatching a plan document reviewer subagent.

Purpose: Verify the plan is complete, matches the spec, and has proper task decomposition.

Dispatch after: The complete plan is written.

Task tool (general-purpose):
  description: "Review plan document"
  prompt: |
    You are a plan document reviewer. Verify this plan is complete and ready for implementation.

    **Plan to review:** [PLAN_FILE_PATH]
    **Spec for reference:** [SPEC_FILE_PATH]

    ## What to Check

    | Category | What to Look For |
    |----------|------------------|
    | Completeness | TODOs, placeholders, incomplete tasks, missing steps |
    | Spec Alignment | Plan covers spec requirements, no major scope creep |
    | Task Decomposition | Tasks have clear boundaries, steps are actionable |
    | Buildability | Could an engineer follow this plan without getting stuck? |

    ## Calibration

    **Only flag issues that would cause real problems during implementation.**
    An implementer building the wrong thing or getting stuck is an issue.
    Minor wording, stylistic preferences, and "nice to have" suggestions are not.

    Approve unless there are serious gaps — missing requirements from the spec,
    contradictory steps, placeholder content, or tasks so vague they can't be acted on.

    ## Output Format

    ## Plan Review

    **Status:** Approved | Issues Found

    **Issues (if any):**
    - [Task X, Step Y]: [specific issue] - [why it matters for implementation]

    **Recommendations (advisory, do not block approval):**
    - [suggestions for improvement]

Reviewer returns: Status, Issues (if any), Recommendations

writing-plans_SKILL.md

name	writing-plans
description	Create detailed implementation plans from specs before coding. Trigger when user provides requirements, asks for a plan, says "how should I implement X", or needs to break down a multi-step feature. Use BEFORE touching any code.

Writing Plans

Overview

Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.

Announce at start: "I'm using the writing-plans skill to create the implementation plan."

Save plans to: docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

• (User preferences for plan location override this default)

Prerequisites

REQUIRED: Load the core-commands skill for VCS operations (uses jj, not git). All commit steps in plans use the temp file pattern for multi-line content.

Scope Check

If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.

File Structure

Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.

• Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
• You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.
• Files that change together should live together. Split by responsibility, not by technical layer.
• In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.

This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.

Bite-Sized Task Granularity

Each step is one action (2-5 minutes):

• "Write the failing test" - step
• "Run it to make sure it fails" - step
• "Implement the minimal code to make the test pass" - step
• "Run the tests and make sure they pass" - step
• "Commit" - step

Plan Document Header

Every plan MUST start with this header:

# [Feature Name] Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

---

Task Structure

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`

- [ ] **Step 1: Write the failing test**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

- [ ] **Step 2: Run test to verify it fails**

Run: `pytest tests/path/test.py::test_name -v`
Expected: FAIL with "function not defined"

- [ ] **Step 3: Write minimal implementation**

```python
def function(input):
    return expected
```

- [ ] **Step 4: Run test to verify it passes**

Run: `pytest tests/path/test.py::test_name -v`
Expected: PASS

- [ ] **Step 5: Commit**

Use temp file pattern from core-commands skill for commit message:
```bash
mktemp
# Returns: /tmp/tmp.XXXXXX
```
Then use Write tool to save commit message to that path, then:
```bash
jj describe --stdin < "/tmp/tmp.XXXXXX"
rm "/tmp/tmp.XXXXXX"
jj new
```

No Placeholders

Every step must contain the actual content an engineer needs. These are plan failures — never write them:

• "TBD", "TODO", "implement later", "fill in details"
• "Add appropriate error handling" / "add validation" / "handle edge cases"
• "Write tests for the above" (without actual test code)
• "Similar to Task N" (repeat the code — the engineer may be reading tasks out of order)
• Steps that describe what to do without showing how (code blocks required for code steps)
• References to types, functions, or methods not defined in any task

Remember

• Exact file paths always
• Complete code in every step — if a step changes code, show the code
• Exact commands with expected output
• DRY, YAGNI, TDD, frequent commits

Self-Review

After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch.

Optional: For independent verification, dispatch a reviewer subagent using the template in plan-document-reviewer-prompt.md.

1. Spec coverage: Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps.

2. Placeholder scan: Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them.

3. Type consistency: Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called clearLayers() in Task 3 but clearFullLayers() in Task 7 is a bug.

If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task.

Execution Handoff

After saving the plan, offer execution choice:

"Plan complete and saved to docs/superpowers/plans/<filename>.md. Two execution options:

1. Subagent-Driven (recommended) - I dispatch a fresh subagent per task, review between tasks, fast iteration

2. Inline Execution - Execute tasks in this session, batch execution with checkpoints

Which approach?"