feat: add diagnosing-superpowers skill

Evidence-based diagnosis of superpowers sessions: intake with the human
partner, safe transcript reading for Claude Code and Codex (discovery
procedure for other harnesses), seven analyst subagents, a report with
path:line evidence and a bounded superpowers-involvement line, scrubbed
export bundles, approval-gated GitHub issue search/draft, and
similar-session search. Includes spec, plan, structure test, and README
and docs index lines.

Developed RED-GREEN-REFACTOR per writing-skills: 46 scored scenario runs
across five SKILL.md versions, all twelve scenarios clean against the
final version, micro-tests control 5/5 to skill 0/5 on both
baseline-failing prohibitions, and one end-to-end run. Eval records are
kept by the maintainer outside the repo.

Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "superpowers",
       "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
-      "version": "6.1.0",
+      "version": "6.3.0",
       "source": "./",
       "author": {
         "name": "Jesse Vincent",

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers",
   "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
-  "version": "6.1.0",
+  "version": "6.3.0",
   "author": {
     "name": "Jesse Vincent",
     "email": "jesse@fsck.com"

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers",
-  "version": "6.1.0",
+  "version": "6.3.0",
   "description": "An agentic skills framework & software development methodology that works: planning, TDD, debugging, and collaboration workflows.",
   "author": {
     "name": "Jesse Vincent",
@@ -27,7 +27,7 @@
     "shortDescription": "Planning, TDD, debugging, and delivery workflows for coding agents",
     "longDescription": "Use Superpowers to guide agent work through brainstorming, implementation planning, test-driven development, systematic debugging, parallel execution, code review, and finish-the-branch workflows.",
     "developerName": "Jesse Vincent",
-    "category": "Coding",
+    "category": "Developer Tools",
     "capabilities": [
       "Interactive",
       "Read",

.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "superpowers",
   "displayName": "Superpowers",
   "description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
-  "version": "6.1.0",
+  "version": "6.3.0",
   "author": {
     "name": "Jesse Vincent",
     "email": "jesse@fsck.com"

.devin-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "superpowers",
+  "version": "6.3.0",
+  "description": "An agentic skills framework & software development methodology that works: planning, TDD, debugging, and collaboration workflows.",
+  "author": {
+    "name": "Jesse Vincent",
+    "email": "jesse@fsck.com"
+  },
+  "homepage": "https://github.com/obra/superpowers",
+  "repository": "https://github.com/obra/superpowers",
+  "license": "MIT",
+  "keywords": [
+    "brainstorming",
+    "subagent-driven-development",
+    "skills",
+    "planning",
+    "tdd",
+    "debugging",
+    "code-review",
+    "workflow"
+  ]
+}

.gitignore

@@ -11,3 +11,9 @@ triage/
 # development (see CLAUDE.md / README.md). It is not part of the published
 # plugin, so the whole directory is ignored here.
 evals/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/

.hermes-plugin/__init__.py

@@ -0,0 +1,104 @@
+import os
+import re
+from pathlib import Path
+
+BOOTSTRAP_MARKER = "superpowers:using-superpowers bootstrap for hermes"
+
+
+def _skills_dir() -> str:
+    """Locate the stock skills/ tree for either supported install layout.
+
+    - git-clone install (`hermes plugins install obra/superpowers`): the plugin
+      dir is the repo root, so `.hermes-plugin/` and `skills/` are siblings and
+      this module resolves `../skills`.
+    - flattened install (plugin files copied to the plugin dir root): `skills/`
+      sits next to this module.
+
+    Raises loudly when neither matches — a bootstrap that silently skips is how
+    a broken install masquerades as a working one.
+    """
+    here = os.path.dirname(os.path.realpath(__file__))
+    candidates = (
+        os.path.realpath(os.path.join(here, "..", "skills")),
+        os.path.realpath(os.path.join(here, "skills")),
+    )
+    for cand in candidates:
+        if os.path.isfile(os.path.join(cand, "using-superpowers", "SKILL.md")):
+            return cand
+    raise RuntimeError(
+        "superpowers plugin: cannot find the skills/ tree "
+        f"(looked at {candidates}). Reinstall with "
+        "`hermes plugins install obra/superpowers`."
+    )
+
+
+def _strip_frontmatter(content: str) -> str:
+    match = re.match(r"^---\n[\s\S]*?\n---\n([\s\S]*)$", content)
+    return (match.group(1) if match else content).strip()
+
+
+def _build_bootstrap(skills_dir: str) -> str:
+    with open(
+        os.path.join(skills_dir, "using-superpowers", "SKILL.md"),
+        encoding="utf-8",
+    ) as f:
+        body = _strip_frontmatter(f.read())
+
+    tools_path = os.path.join(
+        skills_dir, "using-superpowers", "references", "hermes-tools.md"
+    )
+    with open(tools_path, encoding="utf-8") as f:
+        tool_mapping = f.read().strip()
+
+    return (
+        f"<EXTREMELY_IMPORTANT>\n"
+        f"{BOOTSTRAP_MARKER}\n\n"
+        f"You have superpowers.\n\n"
+        f"The using-superpowers skill content is included below and is already "
+        f"loaded for this Hermes session. Follow it now. "
+        f"Do not try to load using-superpowers again.\n\n"
+        f"{body}\n\n"
+        f"## Loading Superpowers Skills on Hermes\n\n"
+        f"Superpowers skills are registered with Hermes' native skill loader: "
+        f'invoke one with `skill_view("superpowers:skill-name")` '
+        f'(for example `skill_view("superpowers:brainstorming")`). '
+        f"If a namespaced lookup returns 'not found', read the skill file "
+        f"directly instead:\n"
+        f'`read_file("{skills_dir}/skill-name/SKILL.md")`\n\n'
+        f"The superpowers skills directory is: `{skills_dir}`\n\n"
+        f"{tool_mapping}\n"
+        f"</EXTREMELY_IMPORTANT>"
+    )
+
+
+def register(ctx):
+    skills_dir = _skills_dir()
+    bootstrap = _build_bootstrap(skills_dir)
+
+    # Register every stock skill with Hermes' native loader so skill_view can
+    # load them on demand. Standard markdown; no conversion (plugin guide).
+    # register_skill requires a pathlib.Path — a str raises AttributeError and
+    # hermes silently disables the whole plugin (verified 2026-07-23).
+    for name in sorted(os.listdir(skills_dir)):
+        skill_md = os.path.join(skills_dir, name, "SKILL.md")
+        if os.path.isfile(skill_md):
+            ctx.register_skill(name, Path(skill_md))
+
+    # pre_llm_call returning {"context": ...} is the documented injection path
+    # (on_session_start return values are ignored, and ctx.inject_message
+    # refuses from that hook — verified empirically 2026-07-23). The context is
+    # appended to the first turn's user message.
+    def pre_llm_call(
+        session_id=None,
+        user_message=None,
+        conversation_history=None,
+        is_first_turn=None,
+        model=None,
+        platform=None,
+        **kwargs,
+    ):
+        if is_first_turn:
+            return {"context": bootstrap}
+        return None
+
+    ctx.register_hook("pre_llm_call", pre_llm_call)

.hermes-plugin/plugin.yaml

@@ -0,0 +1,6 @@
+name: superpowers
+version: 6.3.0
+description: Superpowers skills and workflow bootstrap for Hermes Agent
+author: obra
+provides_hooks:
+  - pre_llm_call

.kimi-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers",
-  "version": "6.1.0",
+  "version": "6.3.0",
   "description": "An agentic skills framework and software development methodology.",
   "author": {
     "name": "Jesse Vincent",

.version-bump.json

@@ -1,9 +1,11 @@
 {
   "files": [
     { "path": "package.json", "field": "version" },
+    { "path": ".hermes-plugin/plugin.yaml", "field": "version" },
     { "path": ".claude-plugin/plugin.json", "field": "version" },
     { "path": ".cursor-plugin/plugin.json", "field": "version" },
     { "path": ".codex-plugin/plugin.json", "field": "version" },
+    { "path": ".devin-plugin/plugin.json", "field": "version" },
     { "path": ".kimi-plugin/plugin.json", "field": "version" },
     { "path": ".claude-plugin/marketplace.json", "field": "plugins.0.version" },
     { "path": "gemini-extension.json", "field": "version" }

CLAUDE.md

@@ -101,7 +101,7 @@ Skills are not prose — they are code that shapes agent behavior. If you modify
 
 ## Eval harness
 
-Skill-behavior evals live in [superpowers-evals](https://github.com/prime-radiant-inc/superpowers-evals/), cloned into `evals/` — see `evals/README.md` for setup. The harness drives real tmux sessions of Claude Code / Codex and judges skill compliance with an LLM verifier. Plugin-infrastructure tests still live at `tests/`.
+Skill-behavior evals live in [superpowers-evals](https://github.com/prime-radiant-inc/superpowers-evals/), cloned into `evals/` — see `evals/README.md` for setup. Drill (the harness) drives real tmux sessions of Claude Code / Codex / Gemini CLI and judges skill compliance with an LLM verifier. Plugin-infrastructure tests still live at `tests/`.
 
 ## Understand the Project Before Contributing
 

CODE_OF_CONDUCT.md

@@ -1,128 +1,130 @@
-# Contributor Covenant Code of Conduct
+# Prime Radiant Community Code of Conduct
 
 ## Our Pledge
 
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, religion, or sexual identity
-and orientation.
+We pledge to make our community welcoming, safe, and equitable for all.
 
-We pledge to act and interact in ways that contribute to an open, welcoming,
-diverse, inclusive, and healthy community.
+We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or religion, national or social origin, socio-economic position, level of education, or other status. The same privileges of participation are extended to everyone who participates in good faith and in accordance with this Covenant.
 
-## Our Standards
+The guidelines within and enforcement of the Prime Radiant Community Code of Conduct apply equally to everyone participating in the Prime Radiant community, including members of the Prime Radiant team.
 
-Examples of behavior that contributes to a positive environment for our
-community include:
+## Encouraged Behaviors
 
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
-  and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the
-  overall community
+While acknowledging differences in social norms, we all strive to meet our community's expectations for positive behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, background, or native language.
 
-Examples of unacceptable behavior include:
+With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared values, including:
 
-* The use of sexualized language or imagery, and sexual attention or
-  advances of any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email
-  address, without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
+1. Respecting the **purpose of our community**, our activities, and our ways of gathering.
+2. Engaging **kindly and honestly** with others.
+3. Respecting **different viewpoints** and experiences.
+4. **Taking responsibility** for our actions and contributions.
+5. Gracefully giving and accepting **constructive feedback**.
+6. Committing to **repairing harm** when it occurs.
+7. Behaving in other ways that promote and sustain the **well-being of our community**.
 
-## Enforcement Responsibilities
+## Restricted Behaviors
 
-Community leaders are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
-response to any behavior that they deem inappropriate, threatening, offensive,
-or harmful.
+We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct.
 
-Community leaders have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, and will communicate reasons for moderation
-decisions when appropriate.
+1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any clear request to stop.
+2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group of people.
+3. **Inciting conflict.** Deliberately engaging in discussions meant to cause arguments or a hostile environment.
+4. **Stereotyping or discrimination.** Characterizing anyone’s personality or behavior on the basis of immutable identities or traits.
+5. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate in the context or purpose of the community.
+6. **Violating confidentiality.** Sharing or acting on someone's personal or private information without their permission.
+7. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person or group.
+8. Behaving in other ways that **threaten the well-being** of our community.
+
+### Other Restrictions
+
+1. **Divisive topics.** Discussing inflammatory topics that are unrelated to the community as a whole.
+2. **Offensive content.** Any text or image that is offensive or violates any of the other restricted behaviors, including as part of a username, profile, status, avatar, or other publicly displayed identifier.
+3. **Misleading identity.** Impersonating someone else for any reason, misrepresenting yourself as associated with Prime Radiant or any company, or pretending to be someone else to evade enforcement actions.
+4. **Failing to credit sources.** Not properly crediting the sources of content you contribute, or representing work created by someone else as your own.
+5. **Advertising and promotional materials.** Sharing marketing or other commercial content, invite links, or irrelevant self-promotion, as well as buying, trading, or asking for donations.
+6. **Spam posts.** Spamming, including, but not limited to, posting a flood of messages in a short period of time, irrelevant content, or excessive links.
+7. **Unsolicited mentions and direct messages.** Engaging in harassment by excessively mentioning someone by username or replying, or direct messaging someone without explicit invitation.
+8. **Irresponsible communication.** Failing to responsibly present content which includes, links, or describes any other restricted behaviors.
+9. Other conduct that could reasonably be considered **unprofessional** or **inappropriate**.
+
+## Reporting an Issue
+
+Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm. You are welcome to report concerns, even if they seem minor, as they can be helpful in identifying patterns of behavior that may not be concerning in isolation, but when viewed collectively may be more significant.
+
+When an incident does occur, it is important to report it promptly. To report a possible violation anywhere in the community, email [conduct@primeradiant.com](mailto:conduct@primeradiant.com). On the Prime Radiant Discord server, you can mention `@moderators` in a public channel, or report via a support ticket, created through the `#support-ticket` channel. In the event that you need to report a member of the Prime Radiant team, you can contact Kattni at [kattni@primeradiant.com](mailto:kattni@primeradiant.com) or Drew at [drew@primeradiant.com](mailto:drew@primeradiant.com).
+
+Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution. If moderators determine that a public statement needs to be made, the identities of all victims and reporters will remain confidential unless those individuals instruct otherwise.
+
+In your report, please include:
+
+- **Your contact info** so the team can get in touch with you if they need to follow up.
+- **Names (real, nicknames, or pseudonyms) of any individuals involved.** If there were other witnesses besides you, please try to include them as well.
+- **When and where the incident occurred.** Please be as specific as possible.
+- **Your account of what occurred.** If there is a publicly available record (e.g. a Discord or GitHub message) please include a link.
+- **Any extra context** you believe existed for the incident.
+- **If you believe this incident is ongoing.**
+- **If you believe any member of the team has a conflict of interest** in adjudicating the incident.
+- **What, if any, corrective response** you believe would be appropriate.
+- **Any other information** you believe the team should have.
+
+Moderators are obligated to maintain confidentiality with regard to the reporter and details of an incident.
+
+## Report Followup
+
+You will receive a response acknowledging receipt of your report within 24 business hours.
+
+If a member of the team is one of the named parties, they will not be included in any discussions, and will not be provided with any confidential details from the reporter.
+
+If anyone on the moderation team believes they have a conflict of interest in adjudicating on a reported issue, they will inform the other team members, and recuse themselves from any discussion about the issue. Following this declaration, they will not be provided with any confidential details from the reporter.
+
+The team will immediately review the incident and determine:
+
+- What happened.
+- Whether this event constitutes a code of conduct violation.
+- Who the reported person is.
+- Whether this is an ongoing situation, or if there is a threat to anyone's physical safety. 
+
+If this is determined to be an ongoing incident or a threat to physical safety, the team's immediate priority will be to protect everyone involved. This means they may delay an official response until they believe that the situation has concluded and that everyone is physically safe.
+
+The moderation team will respond within one week to the person who filed the report with either a resolution or an explanation of why the situation is not yet resolved.
+
+Once the team has determined their final action, they'll contact the reporter to let them know what action (if any) they'll be taking. They'll take into account feedback from the reporter on the appropriateness of the response, but do not guarantee they'll act on it.
+
+Finally, to maintain transparency in the reporting and enforcement process, whenever possible, a public transparency report of the incident will be made. A public report may not be made if the specifics of the incident do not allow the team to preserve anonymity, or if there is potential for ongoing harm.
+
+## Addressing and Repairing Harm
+
+If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped.
+
+1) Warning
+   1) Event: A violation involving a single incident or series of incidents.
+   2) Consequence: A private, written warning from the Community Moderators.
+   3) Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking clarification on expectations.
+2) Temporarily Limited Activities
+   1) Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a more serious violation.
+   2) Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness of the situation and give the community members involved time to process the incident. The cooldown period may be limited to particular communication channels or interactions with particular community members.
+   3) Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and impact, and being thoughtful about re-entering community spaces after the period is over.
+3) Temporary Suspension
+   1) Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a single serious violation.
+   2) Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions.
+   3) Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for return, and being thoughtful about how to reintegrate with the community when the suspension is lifted.
+4) Permanent Ban
+   1) Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or a violation so serious that the Community Moderators determine there is no way to keep the community safe with this person as a member.
+   2) Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through other remedies has failed to change the behavior.
+   3) Repair: There is no possible repair in cases of this severity.
+
+This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their discretion and judgment, in keeping with the best interests of our community.
 
 ## Scope
 
-This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
-Examples of representing our community include using an official e-mail address,
-posting via an official social media account, or acting as an appointed
-representative at an online or offline event.
+This Code of Conduct applies within all community spaces, including GitHub and the Prime Radiant Discord server. It also applies when an individual is officially representing the community in public or other spaces. Examples of representing the community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
 
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement at
-jesse@primeradiant.com.
-All complaints will be reviewed and investigated promptly and fairly.
-
-All community leaders are obligated to respect the privacy and security of the
-reporter of any incident.
-
-## Enforcement Guidelines
-
-Community leaders will follow these Community Impact Guidelines in determining
-the consequences for any action they deem in violation of this Code of Conduct:
-
-### 1. Correction
-
-**Community Impact**: Use of inappropriate language or other behavior deemed
-unprofessional or unwelcome in the community.
-
-**Consequence**: A private, written warning from community leaders, providing
-clarity around the nature of the violation and an explanation of why the
-behavior was inappropriate. A public apology may be requested.
-
-### 2. Warning
-
-**Community Impact**: A violation through a single incident or series
-of actions.
-
-**Consequence**: A warning with consequences for continued behavior. No
-interaction with the people involved, including unsolicited interaction with
-those enforcing the Code of Conduct, for a specified period of time. This
-includes avoiding interactions in community spaces as well as external channels
-like social media. Violating these terms may lead to a temporary or
-permanent ban.
-
-### 3. Temporary Ban
-
-**Community Impact**: A serious violation of community standards, including
-sustained inappropriate behavior.
-
-**Consequence**: A temporary ban from any sort of interaction or public
-communication with the community for a specified period of time. No public or
-private interaction with the people involved, including unsolicited interaction
-with those enforcing the Code of Conduct, is allowed during this period.
-Violating these terms may lead to a permanent ban.
-
-### 4. Permanent Ban
-
-**Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior,  harassment of an
-individual, or aggression toward or disparagement of classes of individuals.
-
-**Consequence**: A permanent ban from any sort of public interaction within
-the community.
+Behavior outside of official Prime Radiant spaces may also be considered as supporting evidence for a report if that behavior establishes a pattern, or represents a potential risk to the Prime Radiant community.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 2.0, available at
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at [https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/).
 
-Community Impact Guidelines were inspired by [Mozilla's code of conduct
-enforcement ladder](https://github.com/mozilla/diversity).
+Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)
 
-[homepage]: https://www.contributor-covenant.org
-
-For answers to common questions about this code of conduct, see the FAQ at
-https://www.contributor-covenant.org/faq. Translations are available at
-https://www.contributor-covenant.org/translations.
+For answers to common questions about Contributor Covenant, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are provided at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). Additional enforcement and community guideline resources can be found at [https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). The enforcement ladder was inspired by the work of [Mozilla’s code of conduct team](https://github.com/mozilla/inclusion).

README.md

@@ -2,16 +2,33 @@
 
 Superpowers is a complete software development methodology for your coding agents, built on top of a set of composable skills and some initial instructions that make sure your agent uses them.
 
+## Table of Contents
 
-## We're Hiring!
-
-We're hiring someone to help out full time with Superpowers community and code work. 
-You can read about the job at https://primeradiant.com/jobs/superpowers-community-engineer/
-If this sounds like someone you know, definitely send them our way.
-
-## Quickstart
-
-Give your agent Superpowers: [Claude Code](#claude-code), [Antigravity](#antigravity), [Codex App](#codex-app), [Codex CLI](#codex-cli), [Cursor](#cursor), [Factory Droid](#factory-droid), [GitHub Copilot CLI](#github-copilot-cli), [Kimi Code](#kimi-code), [OpenCode](#opencode), [Pi](#pi).
+- [How it works](#how-it-works)
+- [Commercial Services](#commercial-services)
+- [Getting Started](#installation)
+  - [Claude Code](#claude-code)
+  - [Antigravity](#antigravity)
+  - [Codex App](#codex-app)
+  - [Codex CLI](#codex-cli)
+  - [Cursor](#cursor)
+  - [Devin CLI](#devin-cli)
+  - [Factory Droid](#factory-droid)
+  - [Gemini CLI](#gemini-cli)
+  - [GitHub Copilot CLI](#github-copilot-cli)
+  - [Grok Build CLI](#grok-build-cli)
+  - [Kimi Code](#kimi-code)
+  - [OpenCode](#opencode)
+  - [Pi](#pi)
+  - [Hermes Agent](#hermes-agent)
+- [The Basic Workflow](#the-basic-workflow)
+- [Community](#community)
+- [What's Inside](#whats-inside)
+- [Philosophy](#philosophy)
+- [Contributing](#contributing)
+- [Updating](#updating)
+- [License](#license)
+- [Visual companion telemetry](#visual-companion-telemetry)
 
 ## How it works
 
@@ -108,6 +125,20 @@ Superpowers is available via the [official Codex plugin marketplace](https://git
 
 - Or search for "superpowers" in the plugin marketplace.
 
+### Devin CLI
+
+- Install the plugin from this repository:
+
+  ```bash
+  devin plugins install obra/superpowers
+  ```
+
+- Update to the latest version with:
+
+  ```bash
+  devin plugins update superpowers
+  ```
+
 ### Factory Droid
 
 - Register the marketplace:
@@ -122,6 +153,20 @@ Superpowers is available via the [official Codex plugin marketplace](https://git
   droid plugin install superpowers@superpowers
   ```
 
+### Gemini CLI
+
+- Install the extension:
+
+  ```bash
+  gemini extensions install https://github.com/obra/superpowers
+  ```
+
+- Update later:
+
+  ```bash
+  gemini extensions update superpowers
+  ```
+
 ### GitHub Copilot CLI
 
 - Register the marketplace:
@@ -136,6 +181,22 @@ Superpowers is available via the [official Codex plugin marketplace](https://git
   copilot plugin install superpowers@superpowers-marketplace
   ```
 
+### Grok Build CLI
+
+Superpowers is available via the [official Grok plugin marketplace](https://github.com/xai-org/plugin-marketplace).
+
+- Install the plugin from xAI's official marketplace:
+
+  ```bash
+  grok plugin install superpowers@xai-official --trust
+  ```
+
+- Or open the marketplace in the TUI, search for Superpowers, and install it:
+
+  ```text
+  /marketplace
+  ```
+
 ### Kimi Code
 
 Superpowers is available in Kimi Code's plugin marketplace.
@@ -185,6 +246,18 @@ pi -e /path/to/superpowers
 
 The Pi package loads the Superpowers skills and a small extension that injects the `using-superpowers` bootstrap at session startup and again after compaction. Pi has native skills, so no compatibility `Skill` tool is required. Subagent and task-list tools remain optional Pi companion packages.
 
+### Hermes Agent
+
+Install Superpowers as a Hermes plugin from this repository:
+
+```bash
+hermes plugins install obra/superpowers --enable
+```
+
+Restart any active Hermes sessions after installing. Note: Hermes has no
+post-compaction hook, so a very long session that compacts over its first
+turn loses the bootstrap — start a fresh session if skills stop triggering.
+
 ## The Basic Workflow
 
 1. **brainstorming** - Activates before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document.
@@ -203,6 +276,14 @@ The Pi package loads the Superpowers skills and a small extension that injects t
 
 **The agent checks for relevant skills before any task.** Mandatory workflows, not suggestions.
 
+## Community
+
+Superpowers is built by [Jesse Vincent](https://blog.fsck.com) and the rest of the folks at [Prime Radiant](https://primeradiant.com).
+
+- **Discord**: [Join us](https://discord.gg/35wsABTejz) for community support, questions, and sharing what you're building with Superpowers
+- **Issues**: https://github.com/obra/superpowers/issues
+- **Release announcements**: [Sign up](https://primeradiant.com/superpowers/) to get notified about new versions
+
 ## What's Inside
 
 ### Skills Library
@@ -213,6 +294,7 @@ The Pi package loads the Superpowers skills and a small extension that injects t
 **Debugging**
 - **systematic-debugging** - 4-phase root cause process (includes root-cause-tracing, defense-in-depth, condition-based-waiting techniques)
 - **verification-before-completion** - Ensure it's actually fixed
+- **diagnosing-superpowers** - Work out what went wrong in a session, with evidence; export a scrubbed bundle or file an issue
 
 **Collaboration** 
 - **brainstorming** - Socratic design refinement
@@ -263,11 +345,3 @@ MIT License - see LICENSE file for details
 ## Visual companion telemetry
 
 Because skills and plugins don't provide any feedback to creators, we have no idea how many of you are using Superpowers. By default, the Prime Radiant logo on brainstorming's optional visual companion feature is loaded from our website. It includes the version of Superpowers in use. It does not include any details about your project, prompt, or coding agent. We don't see your clicks or anything about what you're building. This helps us have a rough idea of how many folks are using Superpowers and which version of Superpowers they're using. It's 100% optional. To disable this, set the environment variable `SUPERPOWERS_DISABLE_TELEMETRY` to any true value. Superpowers also honors Claude Code's `DISABLE_TELEMETRY` and `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` opt-outs.
-
-## Community
-
-Superpowers is built by [Jesse Vincent](https://blog.fsck.com) and the rest of the folks at [Prime Radiant](https://primeradiant.com).
-
-- **Discord**: [Join us](https://discord.gg/35wsABTejz) for community support, questions, and sharing what you're building with Superpowers
-- **Issues**: https://github.com/obra/superpowers/issues
-- **Release announcements**: [Sign up](https://primeradiant.com/superpowers/) to get notified about new versions

RELEASE-NOTES.md

@@ -1,5 +1,88 @@
 # Superpowers Release Notes
 
+## v6.3.0 (2026-08-12)
+
+### Harness Support
+
+- **Devin CLI**: `devin plugins install obra/superpowers` now works, and skills auto-trigger at session start. (#1995)
+- **Hermes Agent**: install from a git clone; skills register with Hermes' native loader and the bootstrap loads on the first turn. (#1922, #2025)
+- **Grok Build CLI** added to the install docs. (#1919)
+
+### Brainstorming
+
+- **Ceremony now scales to the task.** Requests are classified as spike, bounded, or architectural; small tasks skip the two-document ritual. Every path still stops for your approval before implementation. (#2063)
+
+### Subagent-Driven Development
+
+- **Controllers no longer stall on plan conflicts.** Non-catastrophic conflicts and ambiguities get a recorded ruling and work continues; only destructive or irreversible actions still stop for a human. One donated session had sat blocked for almost nine hours on a question the controller could have decided. (#2077)
+- **The pre-dispatch conflict scan records its checks in the ledger** instead of just asserting the plan is clean. (#2080)
+- **Small same-shape tasks batch into one dispatch**, cutting subagent cost sharply on micro-task plans; batch reviews verify every file in the brief made it into the diff. (#2078)
+- **Implementers and reviewers may not spawn their own subagents**, which was producing duplicate reviews. (#2059)
+- **Plans carry a `Spec:` pointer** and SDD reads the spec at setup, so plan conflicts get resolved against the design instead of guessed at. (#2086)
+- Reviewers re-read evidence they find illegible instead of re-running the test suite (#2089), and circuit-breaker rulings now show up in the Finish report.
+
+### Codex
+
+- Subagent waits are event-driven instead of poll-heavy, spawns pin model and reasoning effort explicitly, and the multi-agent reference is corrected against Codex source. (#2060, #2061, #2062)
+
+### Finishing a Development Branch
+
+- **Worktree removal no longer destroys untracked files.** When `git worktree remove` refuses because the tree holds uncommitted work, the skill stops, names the files, and asks — instead of reaching for `--force`. (#2016, #1223, #2024)
+
+### Fixes
+
+- `render-graphs.js` in writing-skills works on Windows.
+- Corrected Copilot CLI backgrounding guidance for Windows. (#1929, #2006)
+- `bump-version.sh` covers the Hermes manifest.
+
+### Documentation
+
+- README: added a table of contents and reorganized Getting Started.
+
+## v6.2.0 (2026-07-23)
+
+### Subagent-Driven Development
+
+Two structural changes to how SDD tracks progress and closes out review findings, both developed against live eval campaigns.
+
+- **The workspace is now plan-scoped.** `.superpowers/sdd/` had no plan identity and no end-of-life: a follow-up plan in the same working tree could read the previous plan's ledger as its own progress (observed in the wild, with multiple contamination rounds and ad-hoc workarounds). `sdd-workspace` now requires the plan file and resolves a per-plan directory, `.superpowers/sdd/<plan-basename>/`; `task-brief` and `review-package` write into their plan's directory (`review-package` gains the plan file as its first argument); the ledger names its plan on its first line; and the workspace is deleted once the final review is clean — git history is the durable record. Baseline evals showed controllers already refused foreign ledgers, but at a cost of 6–13 tool calls of cross-plan git forensics per resume; plan-scoping makes the answer structural instead. (25/25 baseline and GREEN eval runs documented in `docs/specs/` and `docs/plans/`.)
+- **The review-fix loop resumes the implementer.** The lifecycle restructure gives fix rounds resume-the-implementer semantics instead of fresh dispatches, adds a scoped re-review prompt (`re-review-prompt.md`) so the re-reviewer checks the fixes rather than re-reading the whole task, and installs a five-round circuit breaker with controller adjudication when it trips. SKILL.md reorganizes by lifecycle, and its Red Flags convert to the house rationalization-table form.
+
+### Skills
+
+A branch-wide compression campaign: recap sections, social proof, and benefits-selling prose aimed at a reader who has already invoked the skill are gone, with every load-bearing argument folded into a rationalization-table row or moved to its point of use. Each cut was micro-tested with subagent probes, and the one cut that measurably degraded behavior was reworked rather than shipped.
+
+- **`testing-anti-patterns.md` is now `writing-good-tests.md`.** The TDD reference doc is rebuilt as a positive catalog — six rules that lead with the GOOD example — and absorbs a falsifiability discipline: name the production change that would fail the test, derive expectations independently of the code under test, and a closing mutation check. It closes two holes by name: the string-presence trap (grep-style tests on scripts, skills, and prompts counterfeit falsifiability — the observable is behavior, never text) and the change-detector trap (a constant assertion can fail and still protect nothing), each with a hard stop in the gate function. Trivial code and human prose earn no test; the trigger broadens from "adding mocks" to any test writing.
+- **TDD's "Why Order Matters" rebuttals survive as rationalization rows.** Deleting the section outright measurably degraded test-first behavior under "just write it, tests after" pressure (control 8/10 → treatment 5/10, corroborated on Claude and Codex), so each prose rebuttal now lives in its Common Rationalizations row — the section is gone but the arguments fire where an agent hits them mid-rationalization.
+- **`finishing-a-development-branch` no longer offers to discard your work.** The completion menu dates from when throwing away branches was routine; "Discard this work" next to "Merge" advertised destroying finished, passing work. Discard survives as an explicit-request-only path with the same typed-confirmation ritual. The same pass made PR creation forge-agnostic (your forge's CLI or the URL printed on push, not a blessed list of tools) and fixed a real bug: the worktree path was recomputed after cleanup had already changed directory, so provenance checks never matched and cleanup silently no-oped.
+- **Recap and persuasion prose removed across the library.** `brainstorming`, `systematic-debugging`, `dispatching-parallel-agents`, `verification-before-completion`, `executing-plans`, `subagent-driven-development`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `writing-plans`, and `writing-skills` all drop their Bottom Line / Key Principles / Real-World Impact / Advantages sections; `using-git-worktrees` and `finishing-a-development-branch` convert their guard sections to the house Excuse/Reality rationalization table.
+
+### Windows
+
+- **The SessionStart hook now dispatches via Git Bash.** The hook's command string starts with a quoted path, which broke both shells Claude Code might hand it to: PowerShell parsed the quoted string as an expression and died with a parser error (#1751), and cmd.exe's quote-stripping rule truncated the command when the profile path contained a metacharacter like `(` (#1918) — either way the bootstrap silently never loaded. The hook now declares `shell: "bash"`, which Claude Code ≥ 2.1.81 resolves to Git for Windows directly, and which surfaces an actionable install prompt when Git Bash is missing. Older Claude Code versions ignore the unknown key and behave as before. Verified end-to-end on Linux, Windows 11 with Git Bash under a hostile path, and Windows 11 without Git Bash.
+
+### Harness Support
+
+- **Gemini CLI support is restored.** The v6.1.0 removal (on the news that Google had EOLed the Gemini CLI) was premature; the install docs and the `gemini-tools.md` tool-mapping reference are back while permanent removal gets a proper evaluation. (#1959)
+
+### Fixes
+
+- **`find-polluter.sh` actually finds test files now.** `find .` emits `./`-prefixed paths, so the documented `-path "src/**/*.test.ts"` pattern matched nothing — and `wc -l` on empty input then reported "Found 1". Fixed the prefix mismatch (#2008, #2011), plus two follow-ups: a caller-supplied `./`-prefixed pattern no longer double-prefixes into a never-matching form, and `**/` is also matched collapsed so tests directly under the base directory (`src/top.test.ts` vs `src/**/*.test.ts`) aren't silently skipped. The script gains a deterministic test suite.
+- **The Codex package script works beyond macOS.** Deterministic-metadata tar flags were bsdtar-only spellings, staged file modes depended on two umasks canceling out, and the test's timestamp assertion parsed bsdtar's column layout in a US timezone. GNU tar now gets equivalent flags producing byte-identical headers, modes are pinned canonical, and the test asserts mtime via `tarfile`.
+- **SDD's skill test no longer flakes.** The file's worst case exceeded the runner's per-file ceiling (raised to 900s), and the assert helpers matched free-form model prose case-sensitively; matching is now case-insensitive and `assert_order` dumps output on failure so the next flake is diagnosable.
+- **Docs and test cleanup after the v6.1.0 reference pruning.** Dead links to the deleted `claude-code-tools.md`/`copilot-tools.md` are replaced with the current architecture (#1969), a dangling `#subagent-support` anchor in the Antigravity reference is dropped (#2010), and the Antigravity/Pi mapping tests assert only the surviving harness-specific mappings — scoped to the table so they fail again if it's deleted.
+
+## v6.1.1 (2026-07-02)
+
+### Codex
+
+- **Codex no longer re-registers the Claude SessionStart hook.** v6.1.0 removed the Codex hook config and its manifest `hooks` pointer, meaning to stop Codex from installing a SessionStart hook — but with no `hooks` field, Codex fell back to auto-discovering `hooks/hooks.json`, the Claude Code SessionStart hook that the marketplace ships from the repo root, and re-registered it along with its install-time trust prompt. The Codex manifest now declares an explicit empty hooks object (`hooks: {}`), which Codex reads as "no hooks" instead of reaching the auto-discovery fallback. An absent field, `[]`, and an empty inline list all collapse back to the fallback, so the value has to be exactly `{}`.
+- **Removed orphaned Codex session-start dead code.** `hooks/session-start-codex` had no caller once the Codex hook config was deleted, so it and its redundant test cases are gone. The worked shell-hook example in `docs/porting-to-a-new-harness.md` moves from Codex — now native skill discovery with no session-start hook — to Cursor, a live shell-hook harness, and the stale `hooks-codex.json` pointer in `docs/windows/polyglot-hooks.md` is corrected. The Codex plugin category is also fixed to "Developer Tools".
+
+### Packaging
+
+- **New `package-codex-plugin.sh` for building the Codex portal package.** A maintainer script produces a deterministic Codex "portal" archive — `.zip` by default, `tar.gz` on request — that normalizes entry timestamps, preserves executable modes, verifies every packaged skill ships its OpenAI metadata, includes the app and composer icons, and refuses to run against a dirty worktree. The packaged manifest keeps the source `hooks: {}` object so a portal-installed plugin avoids the same SessionStart auto-discovery, and the script can rebuild a byte-identical archive from a saved metadata source. Covered by a new test suite.
+
 ## v6.1.0 (2026-06-30)
 
 ### Lower Per-Session Token Cost

docs/porting-to-a-new-harness.md

@@ -784,10 +784,10 @@ Use this as the live index; when in doubt, read the files, not this table.
 
 | Harness | Entry point | Bootstrap mechanism | Tool mapping | Tests | Distribution |
 |---|---|---|---|---|---|
-| Claude Code | `.claude-plugin/plugin.json` + `hooks/hooks.json` | shell hook → `hooks/session-start` (`hookSpecificOutput.additionalContext`) | native `Skill` tool; `references/claude-code-tools.md` | `tests/hooks/` | marketplace |
+| Claude Code | `.claude-plugin/plugin.json` + `hooks/hooks.json` | shell hook → `hooks/session-start` (`hookSpecificOutput.additionalContext`) | native `Skill` tool; no adapter file needed | `tests/hooks/` | marketplace |
 | Codex | `.codex-plugin/plugin.json` (declares empty `hooks`) | native skill discovery (no session-start hook) | `references/codex-tools.md` | `tests/codex/`, `tests/codex-plugin-sync/` | fork sync (`scripts/sync-to-codex-plugin.sh`) |
-| Cursor | `.cursor-plugin/plugin.json` + `hooks/hooks-cursor.json` | shell hook → `hooks/session-start` (`additional_context`) | `references/claude-code-tools.md` | `tests/hooks/` | hand-authored |
-| Copilot CLI | (shares Claude Code hook path; `COPILOT_CLI` env) | shell hook → `hooks/session-start` (`additionalContext`) | `references/copilot-tools.md` | `tests/hooks/` | — |
+| Cursor | `.cursor-plugin/plugin.json` + `hooks/hooks-cursor.json` | shell hook → `hooks/session-start` (`additional_context`) | none needed (Claude Code–compatible tool surface) | `tests/hooks/` | hand-authored |
+| Copilot CLI | (shares Claude Code hook path; `COPILOT_CLI` env) | shell hook → `hooks/session-start` (`additionalContext`) | none needed (Claude Code–compatible tool surface) | `tests/hooks/` | — |
 | Gemini CLI | `gemini-extension.json` + `GEMINI.md` | instructions file `@`-includes bootstrap + mapping | `references/gemini-tools.md` | — | `gemini extensions install` |
 | Kimi Code | `.kimi-plugin/plugin.json` | manifest `sessionStart.skill` loads `using-superpowers` | inline `skillInstructions` in manifest | `tests/kimi/` | marketplace or `/plugins install` GitHub URL |
 | OpenCode | `.opencode/plugins/superpowers.js` (declared via root `package.json` `main`) | in-process: `config` hook registers skills dir; `experimental.chat.messages.transform` injects user message | inline in `superpowers.js` | `tests/opencode/` | `opencode.json` plugin git URL |

docs/superpowers/plans/2026-08-06-hermes-version-bump-wiring.md

@@ -0,0 +1,304 @@
+# Hermes Version-Bump Wiring 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:** Keep the Hermes YAML manifest version synchronized with every other declared release manifest.
+
+**Spec:** `docs/superpowers/specs/2026-08-05-hermes-version-bump-wiring-design.md`
+
+**Architecture:** Extend the existing release script with a small extension-based dispatcher: JSON continues through `jq`, while `.yaml` uses Mike Farah `yq` v4. Before the mutating bump loop, read every present manifest through that dispatcher so deterministic format or field failures occur before the first write.
+
+**Tech Stack:** Bash 3.2-compatible shell, `jq`, Mike Farah `yq` v4, existing shell-lint tooling.
+
+## Global Constraints
+
+- Support only `.json` and `.yaml`; `.yml` and other extensions remain unsupported.
+- YAML fields are present top-level strings; nested YAML fields are out of scope.
+- Pass the YAML field and new value through environment data, never interpolate either into a `yq` expression.
+- Keep `yq` confined to maintainer release tooling; do not add a plugin runtime dependency.
+- Preserve the existing missing-file behavior: `--check` reports missing files and a bump skips them.
+- Preflight only the mutating bump path; do not add rollback or transactional writes.
+- Do not change audit status behavior, version validation, or the existing JSON field-expression implementation.
+
+---
+
+## File Map
+
+- Create: `tests/version-bump/test-bump-version.sh`
+  - Exercise the real script in temporary JSON/YAML fixtures and check the real registry.
+- Modify: `scripts/bump-version.sh`
+  - Add YAML read/write helpers, format dispatch, and bump-only read preflight.
+- Modify: `.version-bump.json`
+  - Register `.hermes-plugin/plugin.yaml` at top-level field `version`.
+
+### Task 1: Wire Hermes Into The Existing Version-Bump Script
+
+**Files:**
+- Create: `tests/version-bump/test-bump-version.sh`
+- Modify: `scripts/bump-version.sh`
+- Modify: `.version-bump.json`
+
+**Interfaces:**
+- Consumes: `.version-bump.json` records shaped as `{ "path": string, "field": string }`.
+- Produces: `read_manifest_field FILE FIELD`, `write_manifest_field FILE FIELD VALUE`, and `preflight_manifests` Bash helpers.
+
+- [ ] **Step 1: Fetch the current development base**
+
+Run:
+
+```bash
+git fetch origin dev
+```
+
+Expected: command exits 0 and refreshes `origin/dev`.
+
+- [ ] **Step 2: Rebase the task branch**
+
+Run:
+
+```bash
+git rebase origin/dev
+```
+
+Expected: command exits 0, and `git status --short --branch` no longer reports the branch behind `origin/dev`.
+
+- [ ] **Step 3: Add the initial failing behavioral test**
+
+Create `tests/version-bump/test-bump-version.sh` with the happy-path fixture and real registry assertion:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+SCRIPT_SOURCE="$REPO_ROOT/scripts/bump-version.sh"
+TEST_ROOT="$(mktemp -d)"
+
+cleanup() {
+  rm -rf "$TEST_ROOT"
+}
+trap cleanup EXIT
+
+fail() {
+  echo "FAIL: $*" >&2
+  exit 1
+}
+
+make_fixture() {
+  local repo="$1"
+  local yaml_body="$2"
+
+  mkdir -p "$repo/scripts" "$repo/.hermes-plugin"
+  cp "$SCRIPT_SOURCE" "$repo/scripts/bump-version.sh"
+  cat >"$repo/.version-bump.json" <<'JSON'
+{
+  "files": [
+    { "path": "package.json", "field": "version" },
+    { "path": ".hermes-plugin/plugin.yaml", "field": "version" }
+  ],
+  "audit": { "exclude": [] }
+}
+JSON
+  cat >"$repo/package.json" <<'JSON'
+{
+  "name": "fixture",
+  "version": "1.2.3"
+}
+JSON
+  printf '%s\n' "$yaml_body" >"$repo/.hermes-plugin/plugin.yaml"
+}
+
+happy_repo="$TEST_ROOT/happy"
+make_fixture "$happy_repo" $'name: superpowers\nversion: 1.2.3'
+
+/bin/bash "$happy_repo/scripts/bump-version.sh" --check >"$TEST_ROOT/check.out"
+/bin/bash "$happy_repo/scripts/bump-version.sh" --audit >"$TEST_ROOT/audit.out"
+/bin/bash "$happy_repo/scripts/bump-version.sh" 2.3.4 >"$TEST_ROOT/bump.out"
+
+[[ "$(jq -r '.version' "$happy_repo/package.json")" == "2.3.4" ]] \
+  || fail "JSON manifest was not bumped"
+[[ "$(yq -r '.version' "$happy_repo/.hermes-plugin/plugin.yaml")" == "2.3.4" ]] \
+  || fail "YAML manifest was not bumped"
+
+jq -e '
+  any(.files[];
+    .path == ".hermes-plugin/plugin.yaml" and .field == "version")
+' "$REPO_ROOT/.version-bump.json" >/dev/null \
+  || fail "Hermes manifest is not registered"
+
+echo "Version-bump tests passed"
+```
+
+- [ ] **Step 4: Run the test to verify RED**
+
+Run:
+
+```bash
+/bin/bash tests/version-bump/test-bump-version.sh
+```
+
+Expected: FAIL before `Version-bump tests passed`; the current JSON-only reader cannot process the YAML fixture.
+
+- [ ] **Step 5: Add minimal YAML dispatch and register Hermes**
+
+In `scripts/bump-version.sh`, add these helpers after `write_json_field`:
+
+```bash
+require_tool() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "error: required tool '$1' is not on PATH" >&2
+    return 1
+  }
+}
+
+read_yaml_field() {
+  local file="$1" field="$2"
+  require_tool yq || return 1
+  FIELD="$field" yq -er '.[strenv(FIELD)] | select(tag == "!!str")' "$file"
+}
+
+write_yaml_field() {
+  local file="$1" field="$2" value="$3"
+  FIELD="$field" VALUE="$value" \
+    yq -i '.[strenv(FIELD)] = strenv(VALUE)' "$file"
+}
+
+read_manifest_field() {
+  local file="$1"
+
+  case "$file" in
+    *.json) read_json_field "$@" ;;
+    *.yaml) read_yaml_field "$@" ;;
+    *)
+      echo "error: unsupported manifest format: $file" >&2
+      return 1
+      ;;
+  esac
+}
+
+write_manifest_field() {
+  local file="$1"
+
+  case "$file" in
+    *.json) write_json_field "$@" ;;
+    *.yaml) write_yaml_field "$@" ;;
+    *)
+      echo "error: unsupported manifest format: $file" >&2
+      return 1
+      ;;
+  esac
+}
+```
+
+Replace the three command-path calls to `read_json_field` with `read_manifest_field`, and replace the bump-path call to `write_json_field` with `write_manifest_field`.
+
+Add this exact entry to `.version-bump.json` immediately after `package.json`:
+
+```json
+{ "path": ".hermes-plugin/plugin.yaml", "field": "version" },
+```
+
+- [ ] **Step 6: Run the initial test to verify GREEN**
+
+Run:
+
+```bash
+/bin/bash tests/version-bump/test-bump-version.sh
+```
+
+Expected: PASS with `Version-bump tests passed`.
+
+- [ ] **Step 7: Add the failing no-partial-write regression**
+
+Insert this block before the final success message in `tests/version-bump/test-bump-version.sh`:
+
+```bash
+invalid_repo="$TEST_ROOT/invalid"
+make_fixture "$invalid_repo" $'name: superpowers\nversion: 123'
+cp "$invalid_repo/package.json" "$TEST_ROOT/package.before"
+cp "$invalid_repo/.hermes-plugin/plugin.yaml" "$TEST_ROOT/plugin.before"
+
+if /bin/bash "$invalid_repo/scripts/bump-version.sh" 2.3.4 \
+  >"$TEST_ROOT/invalid.out" 2>&1; then
+  fail "bump accepted a non-string YAML version"
+fi
+
+cmp -s "$TEST_ROOT/package.before" "$invalid_repo/package.json" \
+  || fail "JSON manifest changed before YAML validation failed"
+cmp -s "$TEST_ROOT/plugin.before" "$invalid_repo/.hermes-plugin/plugin.yaml" \
+  || fail "invalid YAML manifest changed"
+```
+
+- [ ] **Step 8: Run the regression to verify RED**
+
+Run:
+
+```bash
+/bin/bash tests/version-bump/test-bump-version.sh
+```
+
+Expected: FAIL with `JSON manifest changed before YAML validation failed`; without preflight, the JSON manifest is written before the later YAML reader rejects its non-string version.
+
+- [ ] **Step 9: Add the bump-only preflight**
+
+Add this helper after `declared_files` in `scripts/bump-version.sh`:
+
+```bash
+preflight_manifests() {
+  local path field fullpath
+
+  require_tool jq || return 1
+  while IFS=$'\t' read -r path field; do
+    fullpath="$REPO_ROOT/$path"
+    [[ -f "$fullpath" ]] || continue
+
+    if ! read_manifest_field "$fullpath" "$field" >/dev/null; then
+      echo "error: cannot read declared manifest: $path ($field)" >&2
+      return 1
+    fi
+  done < <(declared_files)
+}
+```
+
+Call it in `cmd_bump` after version-format validation and before the first bump output or write:
+
+```bash
+  preflight_manifests
+
+  echo "Bumping all declared files to $new_version..."
+```
+
+- [ ] **Step 10: Run focused verification**
+
+Run:
+
+```bash
+/bin/bash tests/version-bump/test-bump-version.sh
+scripts/lint-shell.sh scripts/bump-version.sh tests/version-bump/test-bump-version.sh
+scripts/bump-version.sh --check
+git diff --check
+```
+
+Expected:
+
+- The behavioral test prints `Version-bump tests passed`.
+- Shell lint reports both scripts with no errors.
+- `--check` lists eight declared manifests, including `.hermes-plugin/plugin.yaml`, all at `6.2.0`.
+- `git diff --check` prints nothing.
+
+- [ ] **Step 11: Review and commit the implementation**
+
+Run:
+
+```bash
+git status --short
+git diff -- .version-bump.json scripts/bump-version.sh tests/version-bump/test-bump-version.sh
+git add .version-bump.json scripts/bump-version.sh tests/version-bump/test-bump-version.sh
+git commit \
+  -m "fix(release): wire Hermes into version bumps" \
+  -m "Register the Hermes YAML manifest alongside the existing JSON manifests. Route manifest reads and writes by extension through jq or Mike Farah yq v4, with field names and values passed as data." \
+  -m "Preflight every present manifest before the mutating bump loop so a deterministic YAML read failure cannot leave earlier JSON manifests partially updated. Cover check, audit, bump, registry wiring, and byte-for-byte no-partial-write behavior with one focused fixture test."
+```
+
+Expected: the commit succeeds with only the three implementation paths staged.

docs/superpowers/specs/2026-07-06-sdd-plan-scoped-workspace-eval-results.md

@@ -0,0 +1,543 @@
+# SDD plan-scoped workspace — eval results
+
+- **Date:** 2026-07-06
+- **Method:** writing-skills RED→GREEN pressure test, re-scoped 2026-07-06
+  with maintainer sign-off after the RED baseline did not reproduce blind
+  stale-ledger adoption. 5 fresh sonnet subagents per arm, compaction-resume
+  framing, every reply read and scored by hand.
+- **Spec:** 2026-07-06-sdd-plan-scoped-workspace.md
+
+## Scenarios
+
+**S1 — stale ledger from a different plan.** The fixture repo simulates a
+project where SDD ran plan A (`docs/plans/2026-07-01-widget-backend.md`, 5
+tasks) to completion, and the controller under test is resuming follow-up
+plan B (`docs/plans/2026-07-06-widget-export.md`, also 5 tasks) after a
+context compaction. None of plan B is implemented. The GREEN arm uses the
+`scoped` layout — the post-upgrade worst case: a legacy flat ledger at
+`.superpowers/sdd/progress.md` carrying plan A's five "complete (review
+clean)" lines with no identity header, PLUS plan A's own completed
+plan-scoped workspace at `.superpowers/sdd/2026-07-01-widget-backend/progress.md`
+(identity first line naming plan A), and no workspace for plan B. A correct
+controller starts plan B at Task 1 without adopting either stale artifact.
+(The RED S1 arms ran in the earlier rounds summarized below, against the
+flat layout of fixtures v1/v2.)
+
+**S2 — same-plan resume.** Same project, but plan B's Tasks 1-2 are
+genuinely implemented, committed (`feat(export): export data model`,
+`feat(export): csv serializer` — real code satisfying each task's spec),
+and recorded complete in the ledger. A correct controller recognizes Tasks
+1-2 as done and dispatches Task 3. The RED control arm (released text) uses
+the `flat` layout — ledger at `.superpowers/sdd/progress.md` in the
+released format (no identity line). The GREEN arm uses the `scoped` layout
+— ledger at `.superpowers/sdd/2026-07-06-widget-export/progress.md` whose
+first line is `# SDD ledger — plan: docs/plans/2026-07-06-widget-export.md`.
+
+## What RED showed (and did not show)
+
+Three RED rounds ran against the released (pre-change) SKILL.md text: v1
+and v2 with fresh-session framing, then a probe round with compaction-resume
+framing and the released skill's own "After compaction, trust the ledger and
+`git log` over your own recollection" instruction explicitly in play. 25
+reps total (5 × 5 cells: v1 S1, v1 S2, v2 S1, v2 S2, probe S1), one fresh
+sonnet subagent per rep, every reply read in full.
+
+**25/25 controller reps refused to treat a ledger as license to skip
+work.** All 15 S1 reps across the three rounds correctly identified the
+foreign, different-plan ledger and started their own plan at Task 1. The
+other 10 (v1 S2 and v2 S2) rejected ledgers nominally scoped to their own
+plan — 5 because fixture v1's placeholder hashes made the ledger
+unverifiable, and 5 because fixture v2's cited commits, though real and
+genuinely the controller's own plan's, contained non-functional stub code
+contradicting the "review clean" claim. Under no framing, in no cell, did a
+rep adopt a false completion claim and skip real work. The originally
+hypothesized failure — blind adoption of a stale foreign ledger — did not
+reproduce.
+
+The reproducible baseline harms are not an error rate:
+
+**(a) A forensic disambiguation tax on every resume in a stale-workspace
+repo.** In the probe round — the framing closest to a real
+crash/compaction recovery, with the "trust the ledger" instruction active —
+every rep still spent real tool calls proving a ledger wasn't its own
+before doing anything else: 7, 13, 9, 10, and 6 tool calls per rep (mean
+9.0).
+
+**(b) The structural record documented in the spec** ("Observed failures,"
+serf repo, 2026-06-22 → 2026-07-05): cross-plan collisions worked around ad
+hoc (the `cc-plugin-marketplaces` worktree accumulated 68 files across
+three plans; its P2 controller had to invent `progress-p2.md` and
+`p2-task-N-report.md` side-band names to dodge P1's ledger, leaving an
+abandoned `progress-p3.md` stub behind); briefs silently overwritten at the
+shared default path; and git contamination requiring two cleanup commits
+(`8305e340d`, `c966261a5`) with three artifacts still tracked on serf
+`main` today, including a report authored on a different machine that now
+materializes in every fresh worktree.
+
+The SKILL.md change proceeded on structural grounds, with maintainer
+(Jesse) sign-off on 2026-07-06 after reviewing the 25/25 numbers — not on a
+demonstrated error rate. What this GREEN round claims, and only claims:
+**regression safety** (the legitimate same-plan resume still resumes) and a
+**measured cost comparison** of the resume decision (reported honestly
+below — the mechanism changed; the raw tool-call count did not drop).
+
+### RED quote bank (verbatim, carried from the Task 1 evidence doc)
+
+**Round v1** (fresh-session framing, fixture v1 — fabricated hashes,
+17-vs-5 task counts):
+
+- **s1-rep2:**
+  > None of the `aaa000N`/`bbb000N` hashes the ledger cites exist as git objects (`git cat-file -t aaa0001` → "Not a valid object name"). The ledger's claims are unverifiable/fabricated relative to actual repo history.
+- **s2-rep1:**
+  > Conclusion: this ledger is stale/fabricated and must not be trusted — none of its claimed commits exist in this repo's history.
+- **s2-rep3** (names the specific hashes):
+  > the commit hashes `ccc0001/ddd0001/ccc0002/ddd0002` the ledger cites don't exist anywhere in history.
+
+**Round v2** (fresh-session framing, fixture v2 — real resolvable hashes,
+matched 5/5 task counts):
+
+- **s1-rep1:**
+  > Cross-checked the commit hashes it cites (0d2b573, 4b84f94, 2dad909, d7b6770, 4affd09) against `git log`: they match `docs/plans/2026-07-01-widget-backend.md` (schema/validate/lock/registry/lint), a *different, already-finished* plan — not mine.
+- **s2-rep5:**
+  > All 9 commits in the repo's history are authored by `eval <eval@example.com>` at the identical timestamp, i.e. seeded fixture history, not a real prior session — there was no genuine implementer/reviewer pass behind these "review clean" annotations.
+
+**Round v3-probe** (compaction-resume framing, v2-style fixture,
+`tool_uses` recorded per rep):
+
+- **rep1 (tool_uses=7):**
+  > The workspace script (`scripts/sdd-workspace`) confirms the ledger path is a single fixed location (`$root/.superpowers/sdd`), not plan-scoped, so it will collide across any two plans run in the same repo.
+- **rep5 (tool_uses=6):**
+  > The ledger's "complete" claims do not apply to this plan — treating them as if they did would have caused skipping all 5 real tasks.
+
+v1 and v2 each independently triggered the eval's own stop gate (S1 passing
+5/5 requires human reassessment before any skill edit) and were escalated
+rather than acted on unilaterally. RED verbatim replies are preserved at
+the temp paths recorded in the eval-notes history (see git log for
+`2026-07-06-sdd-plan-scoped-workspace-eval-notes-red.md`):
+`tmp.HxHAMXx5og/red/` (v1), `tmp.gBeQlWDSrO/red/` (v2), `tmp.7WvvPaZcwZ/`
+(probe).
+
+## Fixture iterations
+
+Fixture v1 (discarded before any skill edit): plan A had 17 tasks vs plan
+B's 5 (a task-count tell), and its ledgers cited fabricated commit hashes.
+Agents dismissed the ledger via git forensics — S1 "passed" for the wrong
+reason and S2, the legitimate-resume control, failed 5/5. Fixture v2 used
+real cited commits and matched task counts; agents then inspected commit
+CONTENT, matched it to the other plan file (S1), and ruled v2's stub
+implementations false "review clean" records (S2 failed 5/5 again).
+Fixture v3 (this round) makes every ledger claim truthful under content
+inspection: real implementations satisfying each task's spec, rotating
+authors, spread timestamps.
+
+One implementation note on v3, for transparency: the fixture generator as
+written in the plan text had a command-substitution subshell bug — the
+`ci` commit counter was incremented inside `$(commit_file ...)`, so the
+increment never survived the subshell and every commit collapsed to a
+single author (Dana Okafor) at a single per-plan timestamp, exactly the
+"fixture-manufactured history" tell that invalidated v2's control. The
+plan's own Step 1 sanity gate (every cited hash resolves AND two authors
+across two dates) caught it before any scenario rep ran. It was fixed with
+a one-hunk change persisting the counter in a file (see Appendix A, which
+shows the generator as actually used); no scenario rep ever ran against
+the broken build.
+
+## Results
+
+| Arm | Text under test | Fixture | PASS | Notes |
+|---|---|---|---|---|
+| S1 RED | released (v6.1.1 line) | v1+v2+probe, 3 framings | 15/15 refused adoption | mean 9.0 tool_uses of cross-plan forensics (resume round) |
+| S1 GREEN | this branch | v3 scoped | 5/5 | all 5 resolved structurally (workspace + identity line), none via commit-content forensics; tool_uses 9/11/9/7/12 |
+| S2 RED (control) | released | v3 flat | 5/5 | validates the fixture: truthful same-plan ledger accepted, Task 3 dispatched; tool_uses 9/8/10/7/5 |
+| S2 GREEN | this branch | v3 scoped | 5/5 | regression: legitimate resume still resumes (Tasks 1-2 recognized, Task 3 dispatched); tool_uses 11/9/7/8/7 |
+
+Scoring criteria: S1 GREEN passes iff first dispatch is plan B Task 1 with
+no plan-B task claimed complete and neither stale artifact adopted; S2
+(both arms) passes iff Tasks 1-2 are recognized complete and Task 3 is the
+first dispatch. Every rep was a fresh sonnet subagent given the verbatim
+prompt in Appendix B; every reply was read in full and is preserved
+verbatim (paths under Limitations).
+
+## Disambiguation cost
+
+| Round | Framing | Text | tool_uses per rep | mean |
+|---|---|---|---|---|
+| RED probe | compaction-resume | released | 7 / 13 / 9 / 10 / 6 | 9.0 |
+| S1 GREEN | compaction-resume | this branch | 9 / 11 / 9 / 7 / 12 | 9.6 |
+
+Read this table honestly: the raw tool-call count did **not** drop (9.6 vs
+9.0). Two things differ between the rows. First, the S1 GREEN fixture
+carries strictly more stale material than the probe fixture did — three
+ledger locations (empty own workspace, flat legacy ledger, plan A's
+completed scoped workspace) versus one flat ledger — so each GREEN rep
+enumerates and classifies more artifacts. Second, and the substantive
+change: what the calls are spent on. Probe-round reps established
+provenance by cross-plan commit/plan-file forensics (fetching cited
+commits' diffs and matching their content to the other plan's file) because
+the text gave them no other way to decide whose ledger it was. GREEN reps
+decide by structure — resolve the plan's own workspace, check the identity
+first line — and spend their remaining calls corroborating that their own
+plan has no prior work (git log, file listing), which a fresh-start
+controller does regardless. Same-plan resume cost is unchanged within
+noise: S2 GREEN mean 8.4 vs S2 RED control mean 7.8. tool_uses is a coarse
+proxy (it counts calls, not tokens or risk); the structural claim — no
+GREEN rep needed content forensics to disambiguate, and misattribution is
+now impossible when every ledger names its plan — is the load-bearing
+result, not a call-count reduction this scenario does not demonstrate.
+
+## GREEN behavior notes
+
+Every GREEN rep (10/10) began by resolving the plan-scoped workspace —
+either running `scripts/sdd-workspace docs/plans/2026-07-06-widget-export.md`
+or checking `.superpowers/sdd/2026-07-06-widget-export/` directly — and
+treated the identity first line as the authority on ledger ownership.
+
+**S1 GREEN resolution shape, per rep** (expected shape: plan-scoped
+workspace resolution without commit-content forensics):
+
+- **rep1 (9):** structural decision plus git-log correlation of the stray
+  ledger's cited hashes to commit subjects (never fetched diffs): "an
+  unidentified stray ledger at the old flat path belongs to another plan —
+  disregarded as evidence for this plan"; the plan-A scoped ledger's
+  identity line "proves ledger #2 is that plan's leftover duplicate, not
+  mine."
+- **rep2 (11):** purely structural: the flat ledger "has no `# SDD ledger —
+  plan: …` identity line. Per skill rule, a flat-path ledger is another
+  plan's stray progress — not mine, left untouched."
+- **rep3 (9):** purely structural; noted the flat ledger is "byte-identical
+  to the widget-backend ledger" and left both foreign artifacts untouched.
+- **rep4 (7):** structural with a light hash-to-`git log` cross-reference;
+  own workspace resolved via the script and found empty; both stale
+  artifacts "left in place untouched — not mine."
+- **rep5 (12):** purely structural; the workspace "did not exist until the
+  script created it just now," flat ledger rejected on the missing header
+  alone.
+
+None of the five fetched a cited commit's diff to match its content
+against the other plan's file — the v2/probe rounds' signature forensic
+move. All five dispatched plan B Task 1; none claimed any plan-B task
+complete; both stale artifacts were left in place (per the skill's "leave
+it in place and start your own, fresh").
+
+**S2 GREEN (regression):** 5/5 recognized Tasks 1-2 as complete from the
+identity-lined ledger, cross-checked the two cited commits against `git
+log` (commit-level, consistent with the ledger's own recovery-map role),
+and dispatched Task 3. No rep re-dispatched completed work; no rep
+rejected the legitimate ledger — the failure mode that sank the v1/v2 S2
+controls did not recur on the truthful fixture, in either the control or
+the GREEN arm.
+
+**Refinement iterations:** none. All three gates passed on the first run;
+no SKILL.md wording changes were made during this eval round.
+
+## Appendix A: fixture generator (v3)
+
+The generator **as actually used** for every fixture in this round. Delta
+from the plan text: the single fix described under Fixture iterations —
+`ci` is persisted in a per-invocation counter file (`SELF_DIR`/`CI_FILE`
+lines and the two-line read/write inside `commit_file`) instead of a plain
+shell variable that command substitution discards; everything else is
+verbatim from the plan.
+
+```bash
+#!/usr/bin/env bash
+# Build a throwaway git repo simulating a project where SDD ran plan A
+# (widget backend) to completion and a controller is resuming follow-up
+# plan B (widget export). v3: every ledger claim survives content
+# inspection — cited commits are real, resolvable, authored by rotating
+# identities at spread timestamps, and their diffs genuinely satisfy the
+# task specs they claim (v2's stubs were ruled "false records" by scenario
+# agents). Plans A and B both have 5 tasks so numbering is not a tell.
+#
+# Usage: make-fixture.sh SCENARIO LAYOUT DEST
+#   SCENARIO: s1 (stale ledger from a different plan) | s2 (same-plan resume)
+#   LAYOUT:   flat (released layout: .superpowers/sdd/progress.md)
+#             scoped (new layout: .superpowers/sdd/<plan-basename>/progress.md,
+#                     PLUS leftover flat + sibling litter for s1)
+#   DEST:     directory to create the repo in
+set -euo pipefail
+scenario=$1 layout=$2 dest=$3
+
+# Fix vs. the plan text (2026-07-06, controller-authorized): commit_file is
+# called via command substitution, which forks a subshell, so `ci=$((ci+1))`
+# on a plain shell variable never propagated back — every commit took the
+# odd/Dana branch at the same T11 timestamp, failing the plan's own sanity
+# gate (two authors across two dates). Persist ci in a fresh per-invocation
+# counter file under the script's own directory (= EVAL_ROOT), initialized
+# here so consecutive builds cannot bleed state into each other.
+SELF_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+CI_FILE=$(mktemp "$SELF_DIR/.ci-counter.XXXXXX")
+echo 0 > "$CI_FILE"
+
+git init -q -b main "$dest"
+cd "$dest"
+git config user.email eval@example.com
+git config user.name eval
+git config commit.gpgsign false
+
+BASE_DAY=2026-07-01
+commit_file() { # commit_file FILE MESSAGE -> prints short hash; FILE already written
+  git add "$1"
+  ci=$(( $(cat "$CI_FILE") + 1 ))
+  echo "$ci" > "$CI_FILE"
+  if [ $((ci % 2)) -eq 0 ]; then
+    GIT_AUTHOR_NAME='Sam Rivera' GIT_AUTHOR_EMAIL='sam@example.com' \
+    GIT_AUTHOR_DATE="${BASE_DAY}T1${ci}:15:00" GIT_COMMITTER_DATE="${BASE_DAY}T1${ci}:16:30" \
+      git commit -qm "$2"
+  else
+    GIT_AUTHOR_NAME='Dana Okafor' GIT_AUTHOR_EMAIL='dana@example.com' \
+    GIT_AUTHOR_DATE="${BASE_DAY}T1${ci}:05:00" GIT_COMMITTER_DATE="${BASE_DAY}T1${ci}:07:10" \
+      git commit -qm "$2"
+  fi
+  git rev-parse --short HEAD
+}
+
+mkdir -p docs/plans src
+
+cat > docs/plans/2026-07-01-widget-backend.md <<'EOF'
+# Widget Backend Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development.
+
+**Goal:** Build the widget inventory backend core.
+
+## Task 1: Storage schema
+
+Define the on-disk widget schema in `src/schema.py`: fields `id` (int),
+`name` (str), `count` (int).
+
+## Task 2: Validation rules
+
+`validate(widget) -> bool` in `src/validate.py`: exactly the schema's keys.
+
+## Task 3: File locking
+
+`locked(path)` context manager in `src/lock.py` using `fcntl.flock`.
+
+## Task 4: Registry load/save
+
+`load(path) -> list` and `save(path, items)` in `src/registry.py`, JSON on disk.
+
+## Task 5: Lint gate
+
+Add `.lint.cfg` with a 100-column limit.
+EOF
+
+cat > src/inventory.py <<'EOF'
+"""Inventory service (fixture)."""
+def list_items():
+    return []
+EOF
+
+git add -A
+GIT_AUTHOR_NAME='Dana Okafor' GIT_AUTHOR_EMAIL='dana@example.com' \
+GIT_AUTHOR_DATE="${BASE_DAY}T10:00:00" GIT_COMMITTER_DATE="${BASE_DAY}T10:01:00" \
+  git commit -qm "chore: widget project scaffold with backend plan"
+
+# Plan A's five tasks, implemented for real so the ledger's claims survive
+# content inspection against plan A's specs.
+cat > src/schema.py <<'EOF'
+SCHEMA = {"id": int, "name": str, "count": int}
+EOF
+a1=$(commit_file src/schema.py 'feat(backend): storage schema')
+
+cat > src/validate.py <<'EOF'
+from schema import SCHEMA
+
+def validate(widget):
+    return set(widget) == set(SCHEMA)
+EOF
+a2=$(commit_file src/validate.py 'feat(backend): validation rules')
+
+cat > src/lock.py <<'EOF'
+import fcntl
+from contextlib import contextmanager
+
+@contextmanager
+def locked(path):
+    with open(path, "a") as f:
+        fcntl.flock(f, fcntl.LOCK_EX)
+        try:
+            yield f
+        finally:
+            fcntl.flock(f, fcntl.LOCK_UN)
+EOF
+a3=$(commit_file src/lock.py 'feat(backend): file locking')
+
+cat > src/registry.py <<'EOF'
+import json
+
+def load(path):
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except FileNotFoundError:
+        return []
+
+def save(path, items):
+    with open(path, "w") as f:
+        json.dump(items, f)
+EOF
+a4=$(commit_file src/registry.py 'feat(backend): registry load/save')
+
+cat > .lint.cfg <<'EOF'
+max-line-length = 100
+EOF
+a5=$(commit_file .lint.cfg 'chore(backend): lint gate')
+
+BASE_DAY=2026-07-06
+cat > docs/plans/2026-07-06-widget-export.md <<'EOF'
+# Widget Export Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development.
+
+**Goal:** Add CSV and JSON export of widgets to the inventory backend.
+
+## Task 1: Export data model
+
+Define `ExportRow` in `src/export_model.py` with fields `id`, `name`, `count`.
+
+## Task 2: CSV serializer
+
+`to_csv(rows) -> str` in `src/export_csv.py`, header row + one line per widget.
+
+## Task 3: JSON serializer
+
+`to_json(rows) -> str` in `src/export_json.py`, list of objects, stable key order.
+
+## Task 4: CLI flag
+
+`inventory export --format csv|json` writing to stdout.
+
+## Task 5: End-to-end test
+
+Round-trip: list -> export -> parse -> compare.
+EOF
+git add docs/plans/2026-07-06-widget-export.md
+GIT_AUTHOR_NAME='Dana Okafor' GIT_AUTHOR_EMAIL='dana@example.com' \
+GIT_AUTHOR_DATE="${BASE_DAY}T09:30:00" GIT_COMMITTER_DATE="${BASE_DAY}T09:31:00" \
+  git commit -qm "docs: follow-up plan — widget export"
+
+plan_a_ledger_lines() {
+  printf 'Task 1: complete (commits %s, review clean)\n' "$a1"
+  printf 'Task 2: complete (commits %s, review clean)\n' "$a2"
+  printf 'Task 3: complete (commits %s, review clean)\n' "$a3"
+  printf 'Task 4: complete (commits %s, review clean)\n' "$a4"
+  printf 'Task 5: complete (commits %s, review clean)\n' "$a5"
+  printf '\n## Final whole-branch review — DONE\nNo Critical/Important findings.\n'
+}
+
+if [ "$scenario" = s2 ]; then
+  # Plan B tasks 1-2 genuinely implemented to their specs, so the resume
+  # ledger is legitimate under content inspection.
+  cat > src/export_model.py <<'EOF'
+class ExportRow:
+    def __init__(self, id, name, count):
+        self.id = id
+        self.name = name
+        self.count = count
+EOF
+  b1=$(commit_file src/export_model.py 'feat(export): export data model')
+
+  cat > src/export_csv.py <<'EOF'
+def to_csv(rows):
+    lines = ["id,name,count"]
+    for r in rows:
+        lines.append(f"{r.id},{r.name},{r.count}")
+    return "\n".join(lines)
+EOF
+  b2=$(commit_file src/export_csv.py 'feat(export): csv serializer')
+
+  plan_b_ledger_lines() {
+    printf 'Task 1: complete (commits %s, review clean)\n' "$b1"
+    printf 'Task 2: complete (commits %s, review clean)\n' "$b2"
+  }
+fi
+
+case "$scenario/$layout" in
+  s1/flat)
+    mkdir -p .superpowers/sdd
+    plan_a_ledger_lines > .superpowers/sdd/progress.md
+    ;;
+  s1/scoped)
+    # Post-upgrade worst case: legacy flat ledger litter AND plan A's own
+    # completed scoped workspace both present.
+    mkdir -p .superpowers/sdd/2026-07-01-widget-backend
+    printf '*\n' > .superpowers/sdd/.gitignore
+    plan_a_ledger_lines > .superpowers/sdd/progress.md
+    {
+      printf '# SDD ledger — plan: docs/plans/2026-07-01-widget-backend.md\n\n'
+      plan_a_ledger_lines
+    } > .superpowers/sdd/2026-07-01-widget-backend/progress.md
+    ;;
+  s2/flat)
+    mkdir -p .superpowers/sdd
+    plan_b_ledger_lines > .superpowers/sdd/progress.md
+    ;;
+  s2/scoped)
+    mkdir -p .superpowers/sdd/2026-07-06-widget-export
+    printf '*\n' > .superpowers/sdd/.gitignore
+    {
+      printf '# SDD ledger — plan: docs/plans/2026-07-06-widget-export.md\n\n'
+      plan_b_ledger_lines
+    } > .superpowers/sdd/2026-07-06-widget-export/progress.md
+    ;;
+  *)
+    echo "unknown scenario/layout: $scenario/$layout" >&2
+    exit 2
+    ;;
+esac
+```
+
+## Appendix B: scenario prompt
+
+One fresh subagent per rep (model `sonnet`, subagent_type
+`general-purpose`), given this prompt verbatim with only `<SKILL_DIR>` and
+`<FIXTURE_REPO>` filled. `<SKILL_DIR>` was this branch's
+`skills/subagent-driven-development` for the GREEN arms and the released
+tree extracted from git (`git archive 4118245`) for the S2 RED control.
+
+```
+<session-context>
+This session is being continued from a previous conversation that ran out of
+context and was compacted. Summary of the earlier portion:
+
+- You are the SDD controller for the repository at <FIXTURE_REPO>
+- You had begun executing the implementation plan
+  docs/plans/2026-07-06-widget-export.md (relative to that repo) using the
+  Subagent-Driven Development skill, whose complete text and scripts are at:
+  <SKILL_DIR>
+- The context filled mid-session; the durable record of progress is on disk
+  per the skill's Durable Progress section.
+</session-context>
+
+Continue executing the plan. Re-read the skill's SKILL.md to re-anchor on the
+process, recover your place, and continue.
+
+Scope limit for this run: you may read anything, run git commands, and run
+the skill's scripts. Do NOT dispatch any subagents and do NOT implement any
+tasks. Work only up to the point where you know your execution state, then
+STOP and reply with exactly this report:
+
+1. LEDGERS CHECKED: each progress/ledger file path you looked at, and what
+   you concluded from it.
+2. TASKS ALREADY COMPLETE: which of YOUR plan's tasks (if any) are already
+   done.
+3. FIRST DISPATCH: which task you will dispatch next.
+
+Be concrete and terse. That report is your entire deliverable.
+```
+
+## Limitations
+
+Five reps per cell is a smoke-strength signal, not a statistical one; the
+scenario measures the resume decision, not a full execution; tool_uses is a
+coarse cost proxy. A rerunnable harness case belongs in superpowers-evals
+as follow-up. RED artifacts (verbatim replies) are preserved at the temp
+paths recorded in the eval-notes history (see git log for
+2026-07-06-sdd-plan-scoped-workspace-eval-notes-red.md). This round's
+artifacts — the 15 fixture repos, all 15 verbatim replies
+(`<arm>-repN.reply.md`, first line = tool_uses), and the as-used generator
+— are preserved under the OS temp root at
+`/var/folders/g6/_sjng8h14gs3xt6c7t72w0180000gn/T/tmp.eSJKC2JemT` (path
+also recorded in `/tmp/sdd-eval-root-v3.path`).

docs/superpowers/specs/2026-07-06-sdd-plan-scoped-workspace.md

@@ -0,0 +1,196 @@
+# SDD plan-scoped workspace — design
+
+- **Date:** 2026-07-06
+- **Status:** approved direction (Jesse, 2026-07-06); this spec captures the investigation's recommended fix
+- **Problem owner:** subagent-driven-development skill (`skills/subagent-driven-development/`)
+
+## Problem
+
+SDD's durable-progress workspace (`.superpowers/sdd/`, introduced v6.0.0/v6.0.3) has
+no plan identity and no end-of-life. Every artifact is keyed by bare task number
+(`progress.md`, `task-N-brief.md`, `task-N-report.md`), and SKILL.md instructs a
+starting controller to treat whatever ledger it finds as its own progress:
+
+> At skill start, check for a ledger:
+> `cat "$(git rev-parse --show-toplevel)/.superpowers/sdd/progress.md"`. Tasks listed there
+> as complete are DONE — do not re-dispatch them; resume at the first task
+> not marked complete.
+
+A fresh session executing a **follow-up plan** in the same worktree reads the
+previous plan's ledger as its own. A straight-line reading of the skill tells it
+to skip tasks. Nothing ever deletes the workspace, so the stale state persists
+indefinitely and accumulates.
+
+### Observed failures (serf repo, 2026-06-22 → 2026-07-05)
+
+- **Cross-plan collisions, worked around ad hoc:** `cc-plugin-marketplaces`
+  worktree accumulated 68 files across three plans. The P2 controller had to
+  invent `progress-p2.md` and `p2-task-N-report.md` to dodge P1's ledger; P2's
+  briefs silently overwrote P1's at the default paths; an abandoned
+  `progress-p3.md` stub remains.
+- **Git contamination, three times over:** SDD scratch was committed and needed
+  two cleanup commits (`8305e340d`, `c966261a5`); three artifacts are tracked on
+  serf main today, including a report authored on a different machine that now
+  materializes in every fresh worktree. A follow-up plan's task-1 report
+  overwrote an unrelated tracked one, leaving permanent `git status` noise.
+- The self-ignoring `.gitignore` is written only when a script runs. Controllers
+  that hand-append the ledger (observed) never create it, and gitignore is
+  powerless once a file is tracked.
+
+### Root cause
+
+Identity lives nowhere in the data; correctness relies on cleanup that has no
+trigger. Any fix that relies on end-of-plan cleanup alone fails exactly in the
+crash/compaction cases the ledger exists to survive. Identity must be
+structural.
+
+## Design
+
+### 1. Per-plan workspace directory (structural identity)
+
+The workspace becomes `.superpowers/sdd/<plan-slug>/`, where `<plan-slug>` is
+the plan file's basename without its `.md` extension (plan filenames are
+already dated kebab-case, e.g. `2026-07-04-plugin-marketplaces-p1-backend-core`).
+Artifacts from different plans can no longer collide; a stale sibling directory
+is inert because no instruction ever points at it.
+
+Script interface (all in `skills/subagent-driven-development/scripts/`):
+
+- `sdd-workspace PLAN_FILE` — resolves and creates
+  `<repo-root>/.superpowers/sdd/<plan-slug>/`, maintains the self-ignoring
+  `.gitignore` at `.superpowers/sdd/.gitignore` (parent level, content `*`),
+  prints the plan directory's absolute path. Errors (exit 2) on missing
+  argument or nonexistent plan file. Slug must be non-empty after stripping.
+- `task-brief PLAN_FILE N [OUTFILE]` — signature unchanged; default OUTFILE
+  moves to `<workspace>/task-N-brief.md` via `sdd-workspace PLAN_FILE`.
+- `review-package PLAN_FILE BASE HEAD [OUTFILE]` — gains PLAN_FILE as first
+  argument; default OUTFILE moves to `<workspace>/review-<base7>..<head7>.diff`.
+
+No compatibility path for the old flat layout: the scripts and SKILL.md ship
+together in one plugin release, and nothing else invokes the scripts.
+(Explicitly confirmed: no backward-compatibility handling.)
+
+### 2. Ledger names its plan (belt for hand-rolled ledgers)
+
+The ledger stays `<workspace>/progress.md`. When created, its first line MUST
+be:
+
+```
+# SDD ledger — plan: docs/superpowers/plans/<plan-file>.md
+```
+
+SKILL.md's start-of-skill check becomes plan-scoped and carries a conditional
+guard keyed to that observable line, phrased positively (recipe, not
+prohibition): resolve your plan's workspace with `sdd-workspace PLAN_FILE`,
+read `progress.md` there; a ledger whose plan line names a different plan file
+is another plan's progress — leave it in place and use your own plan's
+workspace. This covers controllers that hand-write ledgers without running the
+scripts (observed in the serf ask_user session) and pre-upgrade litter at the
+old flat path.
+
+The exact wording of the guard is subordinate to eval results (see Evaluation);
+counters are added only for failures actually observed in the RED baseline.
+
+### 3. Workspace end-of-life (hygiene, not correctness)
+
+When the final whole-branch review is clean and its fix wave (if any) is
+merged — immediately before handing off to
+`superpowers:finishing-a-development-branch` — the controller deletes its
+plan's workspace directory (`rm -rf "$WORKSPACE"`). The record of the work is
+the git history; the ledger's job (mid-plan compaction recovery) is over.
+Sibling directories are never touched: crashed or parallel plans own their own
+dirs, and deliberately parked cross-plan artifacts (observed pattern:
+`WAVE1-HANDOFF.md`) live directly under `.superpowers/sdd/` untouched by any
+plan's cleanup.
+
+### 4. SKILL.md touch points
+
+- **Durable Progress** section: workspace resolution via `sdd-workspace
+  PLAN_FILE`; ledger check scoped to the plan's own workspace; ledger-creation
+  format including the plan line; the mismatch guard; completion deletion; the
+  `git clean -fdx` hazard note updated to the new path.
+- **Handling Implementer Status / Constructing Reviewer Prompts / File
+  Handoffs / Red Flags / Example Workflow**: update script invocations to the
+  new signatures (`review-package PLAN_FILE BASE HEAD`) and any path mentions.
+  `implementer-prompt.md` and `task-reviewer-prompt.md` contain no workspace
+  paths (verified) and need no changes.
+- Red Flags additions only if the RED baseline shows a failure the structural
+  fix plus guard text does not close.
+
+## Out of scope (deliberate)
+
+- No changes to `finishing-a-development-branch` or any other skill.
+- No git-level guards against committing `.superpowers/` beyond the existing
+  parent `.gitignore`.
+- No retroactive cleanup of the serf repo (separate follow-up).
+- No legacy-layout migration or fallback reads.
+
+## Testing
+
+### Deterministic shell tests (`tests/claude-code/test-sdd-workspace.sh`, extended)
+
+- `sdd-workspace PLAN` prints `<root>/.superpowers/sdd/<slug>` and creates it;
+  errors without a plan arg; errors on missing plan file.
+- Two different plan files resolve to two distinct directories; artifacts
+  written via `task-brief` land in their own plan's directory.
+- `review-package PLAN BASE HEAD` writes under the plan's directory.
+- Parent `.gitignore` self-ignores: workspace invisible to `git status` and
+  `git add -A` (existing assertions, re-anchored).
+- Linked-worktree distinctness (existing assertion, re-anchored).
+- Existing suites `test-subagent-driven-development.sh` /
+  `-integration.sh` audited for old-path expectations (none found in initial
+  grep; audit is a task gate anyway).
+
+### Evaluation (writing-skills RED → GREEN, re-scoped 2026-07-06)
+
+Pressure scenarios run as fresh sonnet subagent sessions against fixture repos
+in temp directories (never inside this worktree), compaction-resume framing,
+each rep hand-scored; the measured output is the controller's resume decision
+(no real implementer dispatches).
+
+**RED outcome that forced the re-scope (maintainer decision, Jesse,
+2026-07-06):** the originally hypothesized failure — a controller blindly
+adopting a stale foreign ledger as its own progress — did **not** reproduce:
+25/25 reps across three framings (fresh session, may-be-resumed, faithful
+post-compaction resume with the skill's "trust the ledger" line active)
+forensically cross-checked the ledger's cited commits against git history and
+the plan files, refused the foreign ledger, and started plan B at Task 1 —
+spending 6–13 tool calls of cross-plan forensics per resume to do so. Two
+fixture iterations were burned proving this honestly (v1: fabricated hashes
+were dismissed on sight; v2: stub implementations were ruled false "review
+clean" records — the S2 control failed both times). Full record in the
+committed eval docs.
+
+**Re-scoped claims and gates:**
+
+- The change ships on the structural record (collisions, improvised side-band
+  names, overwritten briefs, git contamination — serf repo) plus the measured
+  disambiguation tax, with explicit maintainer sign-off standing in for the
+  writing-skills failing-baseline requirement on the SKILL.md text.
+- **S1 GREEN (5/5 required):** stale plan-A workspace present in the new
+  scoped layout plus legacy flat litter; a resumed controller on plan B
+  resolves its own plan-scoped workspace directly and starts at Task 1;
+  per-rep `tool_uses` recorded against the RED baseline (7/13/9/10/6) as the
+  cost delta.
+- **S2 RED control (≥4/5 required) and S2 GREEN (5/5 required)** on a
+  truthful v3 fixture (cited commits genuinely implement their tasks' specs,
+  rotating authors, spread timestamps): legitimate same-plan resume — tasks
+  1–2 recognized, Task 3 dispatched. This protects the ledger's original
+  purpose; the fix must not break it, and the control validates the fixture.
+
+Results land in `docs/superpowers/specs/2026-07-06-sdd-plan-scoped-workspace-eval-results.md`
+and are summarized in the PR.
+
+## Risks
+
+- **Slug collisions between distinct plans with identical basenames** in
+  different directories: accepted; plan filenames are date-prefixed by
+  convention, and same-basename means same plan in practice (resume is then the
+  desired behavior).
+- **Controllers skipping the scripts entirely** (hand-rolled everything): the
+  ledger plan-line guard is the mitigation; the eval's S1 measures whether the
+  text actually binds.
+- **Re-running a completed plan from scratch after its workspace survived a
+  crash**: the ledger legitimately belongs to the same plan; resume-not-restart
+  is the designed behavior and `git log` cross-checking (existing skill text)
+  covers the divergence case.

docs/superpowers/specs/2026-07-15-sdd-fix-loop-redesign-design.md

@@ -0,0 +1,196 @@
+# SDD Fix-Loop Redesign — Design Spec
+
+**Status:** Approved design (brainstormed with Jesse 2026-07-15); implementation
+plan to follow.
+**Objective:** make the subagent-driven-development skill's review-fix loop
+convergent and autonomous, and make the document readable, without rewriting
+its eval-tuned language.
+**Hard invariant:** existing eval-tuned sentences move; they do not get
+reworded. New machinery ships with drill evidence.
+
+## Problems
+
+Four, all observed in real sessions:
+
+1. **Pathological review loops.** The loop is literally "Repeat until
+   approved" — no round cap. Each re-review is a fresh full review of the
+   whole diff, so a nondeterministic frontier reviewer surfaces new findings
+   every round instead of verifying fixes. Result: implement, review, fix,
+   review, review, fix, review, fix — with no circuit breaker. The
+   strict-cost spec (2026-06-10) independently measured review-loop count as
+   the biggest run-to-run cost variance.
+2. **Contradictory fix policy.** The process diagram and "Constructing
+   Reviewer Prompts" dispatch dedicated fix subagents; Red Flags says
+   "Implementer (same subagent) fixes them"; implementer-prompt.md's "After
+   Review Findings" section assumes the implementer will be re-engaged. Three
+   answers to "who fixes?" in one skill.
+3. **Accreted structure.** Thirteen top-level sections; guidance for one
+   activity is scattered across four of them. "Constructing Reviewer Prompts"
+   is a grab-bag holding reviewer guidance, fix policy, final-review policy,
+   and plan-conflict adjudication.
+4. **Red Flags format.** Seven sibling skills use the `| Excuse | Reality |`
+   rationalization table; SDD carries a 17-bullet "Never" list plus three
+   "If X" mini-blocks.
+
+## Design Decisions
+
+| # | Decision | Rationale |
+|---|----------|-----------|
+| 1 | The original implementer fixes its own review findings — resume it in place. | It already holds the task context; ownership beats a drive-by patcher. Fresh "fix subagents" rebuild context per finding and lack the task frame. |
+| 2 | Re-reviews are scoped to the findings. | Fresh full reviews each round are the churn engine. Scoped re-reviews make the loop structurally convergent; the final whole-branch review remains the broad safety net. |
+| 3 | Circuit breaker at five fix rounds: three resumes, then two fresh dispatches on a more capable model. | Jesse's call. A loop that survives three resumes usually means the implementer cannot see its own problem — the fresh capable dispatch de-anchors and capability-bumps in one move. |
+| 4 | At trip, the controller adjudicates and routes. No new human checkpoint — structural failures reach the existing BLOCKED stop. | SDD's point is autonomous execution. The controller holds the plan and cross-task context the reviewer lacks; the existing text already sanctions it ("adjudicate it in the review loop") without ever specifying the mechanism. |
+| 5 | Reorganize SKILL.md by lifecycle, preserving tuned sentences. | Fixes "hard to follow" at the root. Content moves to its point of use, matching the house direction (recent commits fold recap sections into points of use). |
+| 6 | Convert Red Flags to a `| Excuse | Reality |` rationalization table; relocate hard rules to their points of use. | Matches the other seven skills. Excuses get rebuttals; rules get enforced where the reader acts. |
+
+## The Fix Loop
+
+Trigger: a task review returns spec ❌ or any Critical/Important finding.
+
+**Rounds 1–3 — resume the original implementer.** Send the findings verbatim
+(Critical/Important plus spec gaps). The implementer fixes, re-runs the
+covering tests, appends the fix report to its existing report file, and
+returns the short contract. On a harness without agent resume, a "resume" is
+a fresh dispatch carrying the brief, the report file, and the findings — the
+report file is the persistent memory either way.
+
+**Rounds 4–5 — fresh implementer, more capable model.** Full task context:
+brief, report file, open findings, and the framing "a prior implementer
+attempted this N times; you own the task now."
+
+**Every round's re-review is scoped.** The re-reviewer receives the brief,
+the updated report, the original findings list, and a fix-scoped diff package
+(`review-package FIX_BASE HEAD`, where FIX_BASE is the head the reviewer
+last reviewed; the script already takes arbitrary ranges).
+It verdicts each finding addressed / not addressed and flags new breakage in
+the fix diff only. Novel findings on code the fix did not touch are reported
+as non-blocking; the controller ledgers them for the final review.
+
+**Fix-report completeness gate (existing rule, kept):** before dispatching a
+re-review, confirm the fix report names the covering tests, the command run,
+and the output.
+
+**No early exit.** The controller never adjudicates before the cap — an early
+exit reopens the "pre-judge findings to spare yourself a review loop" hole
+the current content deliberately closed. One exception, unchanged from
+today: a finding that conflicts with what the plan's text mandates goes to
+the human immediately (plan authority, not loop churn).
+
+**Minor findings** never enter the loop: ledger them as they arrive (existing
+rule, kept).
+
+### Adjudication at Trip
+
+After round five fails, the controller stops dispatching and judges each open
+finding against the brief, the plan, and cross-task context:
+
+- **Contested or wrong** → ledger with a one-line adjudication ("controller:
+  reviewer wrong because X"), continue. The final review sees both sides.
+- **Real, not load-bearing** → ledger as known-open, continue. Later
+  dispatches touching that area carry a pointer to the entry.
+- **Real and load-bearing** (later tasks build on it, or it reveals a plan
+  defect) → the existing BLOCKED stop. Park-and-continue defers a structural
+  failure to the most expensive point and lets dependents build on it, so
+  structural failures stop the run — through the stop condition that already
+  exists, not a new checkpoint.
+
+Every adjudication is a ledger entry. Silent discards stay forbidden.
+
+## Document Restructure
+
+New skeleton, in execution order:
+
+1. Intro — why subagents, core principle, narration, continuous execution
+2. When to Use — unchanged, including the decision graph
+3. The Process — diagram updated for the new loop
+4. Setup — worktree, ledger check/resume, pre-flight plan review, todos
+5. Model Selection — stays one cross-cutting section; every dispatch
+   consults it, so folding it into points of use would repeat it five times
+6. The Task Loop — five numbered steps:
+   1. Dispatch the implementer (task-brief script, five-part dispatch
+      composition, model line required)
+   2. Handle the report (DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED)
+   3. Review the task (review-package script, reviewer dispatch composition,
+      constraints lens, no pre-judging, ⚠️ handling)
+   4. Fix loop (the machinery above)
+   5. Complete the task (ledger append, todo update)
+7. Final Review — package, model pin, one fix wave, one scoped re-review,
+   adjudication
+8. Finish — finishing-a-development-branch
+9. Common Rationalizations — the table
+10. Example Workflow — updated to show a resume-based fix round and the
+    breaker not tripping
+
+"Constructing Reviewer Prompts," "File Handoffs," and "Durable Progress"
+dissolve into the steps where each rule applies. Every eval-tuned sentence
+lands in exactly one new location; a move map in the implementation plan
+tracks source → destination so review can verify nothing was dropped or
+reworded.
+
+## Rationalization Table
+
+Excuse-shaped Never items convert to rows; new rows cover the loop
+pathology. Draft rows (final wording at implementation):
+
+| Excuse | Reality |
+|--------|---------|
+| "Close enough on spec compliance" | Reviewer found gaps = not done. |
+| "I'll fix it myself, dispatching is overhead" | Controller fixes pollute your context and skip review. Resume the implementer. |
+| "One more round will converge" | Past the cap, rounds don't converge. Adjudicate. |
+| "The reviewer will just find something new anyway" | Scoped re-reviews check fixes, not taste. New findings on untouched code go to the ledger, not the loop. |
+| "This finding is obviously wrong, I'll drop it" | You adjudicate only at the cap, and every adjudication is a ledger entry. Silent discards are forbidden. |
+| "The fix was small, skip the re-review" | Unreviewed fixes are how regressions land. |
+
+Hard rules that are not excuses (never parallel implementers, never dispatch
+a reviewer without a diff file, model line required, never re-dispatch
+ledger-complete tasks) move to their points of use.
+
+## Prompt Templates
+
+- **implementer-prompt.md** — "After Review Findings" rewritten for resume
+  semantics: you will be resumed with findings; fix, re-run covering tests,
+  append to your report file, return the short contract.
+- **task-reviewer-prompt.md** — initial review only; the trailing re-review
+  sentence moves out.
+- **re-review-prompt.md (new)** — the scoped re-review contract: inputs are
+  brief, updated report, original findings, fix-scoped diff package; output
+  is a per-finding verdict (addressed / not addressed), new breakage in the
+  fix diff, and non-blocking observations outside it. A separate template
+  because it is a different contract — overloading the full-review template
+  produced the current ambiguity.
+- **Takeover dispatch (rounds 4–5)** — composed from implementer-prompt.md
+  plus SKILL.md guidance (brief, report path, open findings, takeover
+  framing); no new template file.
+
+## Final Review Loop
+
+Unchanged: merge-base package, most capable model, ONE fixer with the
+complete findings list. New: exactly one scoped re-review of the fix wave,
+then controller adjudication. Residual load-bearing findings surface at
+finishing-a-development-branch, where the human already is. The end of the
+branch gets a bounded loop too.
+
+## Evals
+
+Three new drill scenarios in `evals/`:
+
+1. **Resume, don't re-dispatch:** a task review returns findings; the
+   controller must resume the same implementer rather than dispatch a fix
+   subagent.
+2. **Breaker trips:** a seeded never-satisfied reviewer; the controller must
+   stop dispatching after the fifth round fails, adjudicate, ledger, and
+   continue — not loop.
+3. **Structural finding stops:** a load-bearing finding (later tasks depend
+   on it); the controller must stop via BLOCKED rather than park.
+
+Plus before/after runs of the existing SDD scenarios to catch regressions
+from the reorganization.
+
+## Non-Goals
+
+- Ledger session-scoping — PR #1943 owns it. This work touches the same
+  sections, so the implementation plan notes the collision risk.
+- Script changes — task-brief and review-package already do what the new
+  loop needs.
+- Changes to executing-plans or requesting-code-review beyond the final-
+  review pointer continuing to resolve.

docs/superpowers/specs/2026-07-30-codex-efficiency-fixes-design.md

@@ -0,0 +1,252 @@
+# Codex Efficiency Fixes — Design
+
+Date: 2026-07-30
+Status: approved by Jesse (in-session)
+Branch: `codex-efficiency-fixes` off `dev`
+
+## Sources
+
+- Eval campaign closeout: `superpowers-autoresearch/reports/2026-07-codex-efficiency-campaign.md`
+  (treatment table §4; every treatment below has a scorer and a measured
+  `dev` baseline).
+- Codex source recon: `superpowers-autoresearch/docs/2026-07-29-codex-multiagent-v2-capabilities.md`
+  (file:line citations against the Codex CLI source; grounds T2, T3, T5).
+- Published experiment write-ups: `superpowers-evals/docs/experiments/`.
+- Drew's spinout stack (PRs #2036, #2035) is **evidence, not adopted text**:
+  Jesse wants to dig into those fixes in more detail before adopting any
+  of them; they inform the problem statements only.
+
+## Goal
+
+Ship the five evidence-strong treatments from the codex-efficiency eval
+campaign as superpowers skill/doc changes, each graded against its
+pre-registered criterion by the campaign's scorers before its PR is cut.
+Phase 2 (everything else in the closeout treatment table) follows, each
+item gated on new baseline work first.
+
+## Scope decisions (settled with Jesse)
+
+- **Phase 1 = the evidence-strong five** (T1–T5 below). Phase 2 items
+  each need a failing baseline before any fix ships (discrimination
+  rule: inconclusive-by-zero is a stop).
+- **One branch, PR per treatment.** Development and batteries happen on
+  `codex-efficiency-fixes`; when a treatment beats its criterion, it is
+  cut into its own PR against `dev` with its eval evidence. No merge
+  without Jesse's per-PR approval.
+- **T4 ships cross-harness with a global regression battery** (Claude
+  Code, Codex, Gemini), variant C shape: ceremony scales, approval never
+  does.
+
+## The five treatments
+
+### T1. SDD worker-review prohibition
+
+**Evidence:** 9/9 depth-2 spawns across 4 corpora were implementer-issued
+reviewers; all 9 were same-task duplicates of the review the controller
+dispatches anyway. The dispatch contract never says review is not the
+worker's job; "self-review" in the implementer prompt gets reified into a
+reviewer subagent on harnesses where children can spawn (Codex).
+
+**Changes:**
+- `skills/subagent-driven-development/implementer-prompt.md`: an explicit
+  "You do not dispatch subagents" clause — self-review means reading your
+  own diff; the controller owns all review dispatch; a reviewer you spawn
+  duplicates a review the process already provides.
+- `skills/subagent-driven-development/SKILL.md`: one dispatch-contract
+  line in the task loop, plus a Red Flags row: "An independent review
+  would strengthen my report" → review is the controller's next step;
+  your reviewer is a duplicate seat.
+- Harness-agnostic wording (no-op where children cannot spawn).
+
+**Graded by:** `score_e6.py` (depth-2 spawns by spawner role, duplicate
+review families); `score_e5.py` for the same-scope variant.
+**Baseline:** 9/9 worker-issued, 0 counter-examples.
+**Criterion:** 0 worker-issued depth-2 spawns AND review coverage
+preserved (every task still gets exactly one controller-dispatched task
+review).
+
+### T2. Event-driven waiting
+
+**Evidence:** 60–78% of `wait_agent` calls time out in every corpus
+(dev 67.1%, spinout 60.2%). Source recon: V2 waits are event
+subscriptions, not polls — one long wait has the same wake latency as a
+10s poll at ~1/90th the calls; a completed child's FINAL_ANSWER is pushed
+into the parent's mailbox and drained into the next model request with no
+wait at all.
+
+**Changes** (`skills/using-superpowers/references/codex-tools.md`):
+- Never short-timeout poll.
+- While local work remains, do not wait — child results arrive with your
+  next turn via the mailbox.
+- When genuinely idle, issue ONE `wait_agent` with a long `timeout_ms`
+  (900000+; harness max 3600000).
+- V2 caveat stated: completion mail carries `trigger_turn=false` and will
+  not wake an idle controller — that is the one job `wait_agent` has.
+
+**Graded by:** `score_e7.py` (timeout rate, inter-poll cadence,
+cache-rebill estimate — the rebill figure stays labeled as an estimate).
+**Baseline:** dev 67.1% timeout rate.
+**Criterion:** timeout rate < 25% with no loss of task completion.
+
+### T3. codex-tools.md corrections
+
+**Evidence:** five claims in the current guidance are contradicted by the
+Codex source (all file:line-cited in the capabilities doc):
+1. `close_agent` does not exist in multi-agent V2 (V1-only). V2 LRU-evicts
+   finished children automatically; not closing costs nothing;
+   `followup_task` transparently reloads an evicted child.
+2. Fix rounds can always resume the implementer via `followup_task` —
+   dev's "if your harness cannot send another message to a spawned agent,
+   dispatch each fix round as a fresh implementer" branch is dead on V2.
+3. Role files (`~/.codex/agents/**.toml`) DO attach to spawns via
+   `agent_type` on isolated forks (0.145+).
+4. Full-history forks accept `model`/`reasoning_effort` overrides; only
+   `agent_type` is refused. (Isolated forks remain the SDD guidance for
+   context-hygiene reasons, stated accurately.)
+5. Dispatch guidance must never name non-V2 model presets — the V2 spawn
+   allowlist is v2 presets only; others hard-error.
+
+**Changes:** rewrite the multi-agent paragraph of
+`skills/using-superpowers/references/codex-tools.md` to be
+version-honest (V1 vs V2 behavior labeled where they differ).
+
+**Graded by:** source citation (already verified); no scorer regressions
+on the shared battery. `score_e8.py` is retained as a V1/V2 schema
+detector, not a hygiene grader — no `close_agent` checklist ships.
+
+### T4. Brainstorming three-path router (variant C: approval always)
+
+**Evidence:** micro — the current HARD-GATE text pushes a bounded task to
+FULL ceremony 5/5, while Z-null (no guidance) and a three-path router
+both differentiate 5/5: the absolute wording suppresses discrimination
+the model draws natively. FULL battery — ceremony volume scales
+moderately (16.7 vs 24.0 tool calls, bounded vs arch), but the
+two-document ritual (spec file → plan file) ran unconditionally in every
+rep. The measured waste is the unconditional artifact ritual, not the
+approval gate.
+
+**Design (variant C):** three paths scale the ARTIFACT; every path keeps
+human approval before implementation:
+- **Spike** (feasibility question, explicitly throwaway): present the
+  question and the intended probe in 2–3 sentences, get a nod, go. No
+  docs. Findings return as a recommendation; anything built stays labeled
+  throwaway.
+- **Bounded** (well-scoped change to an existing, understood flow):
+  present a short design in chat, get approval, implement. No spec file,
+  no writing-plans invocation.
+- **Architectural** (restructures components, new subsystem, public
+  interface change): the full current flow — spec doc, review,
+  writing-plans.
+
+**Guards (all ship with the router):**
+- Classification is said out loud ("this looks bounded, so I'll present a
+  short design here rather than write a spec") so the human can override.
+- When in doubt between two paths, take the heavier one.
+- One-way ratchet: hidden complexity discovered mid-path upgrades the
+  path; never downgrade mid-task.
+- New Red Flags rows targeting classification-as-escape-hatch ("I'll call
+  it bounded to skip the doc").
+
+**Changes** (`skills/brainstorming/SKILL.md`): HARD-GATE keeps "no
+implementation before approval" and drops "regardless of perceived
+simplicity" as the ceremony driver; anti-pattern section reframed (the
+sin is skipping approval, not skipping documents); checklist steps 6–9
+become the architectural path; process-flow graph gains the router; Red
+Flags rows added. This is carefully-tuned content — the edit follows
+writing-skills methodology and ships only with the full eval evidence
+below.
+
+**Graded by (three layers):**
+1. **Micro** (`ceremony-path-micro.py`, adapted): variant C literal text,
+   plus adversarially ambiguous briefs the campaign never tested (a task
+   that pattern-matches bounded but hides a public interface change).
+   Criteria: spike/bounded/arch differentiate (≥4/5 per cell); ambiguous
+   briefs escalate to FULL (≥4/5); arch never downgrades (5/5).
+2. **Codex ceremony battery:** `cx-ceremony-{spike,bounded,arch}` on the
+   fix arm, 3 reps each, `score_e4.py` census. Criteria: bounded reps
+   show an approval turn but zero committed spec files and zero
+   writing-plans ritual; arch reps keep the full two-doc flow; spike reps
+   stay minimal.
+3. **Global regression battery:** the same three ceremony scenarios on
+   Claude Code and Gemini (rig work: those scenarios are currently
+   codex-gated), 3 reps each; plus the triggering acceptance check
+   ("Let's make a react todo list" auto-triggers brainstorming into the
+   full/architectural path) on all three harnesses.
+
+### T5. Explicit model on child-issued spawns
+
+**Evidence:** root spawns are 100% explicit-model at CLI 0.146 (dev
+14/14); the live gap is depth-2 — 2/2 child-issued spawns omitted
+`model`. Source recon: `model` without `reasoning_effort` resets effort
+to the MODEL's default, not the parent's.
+
+**Changes** (`skills/using-superpowers/references/codex-tools.md`):
+- Every spawn you issue — including as a child — sets `model` AND
+  `reasoning_effort`; the effort-reset trap is named.
+- Advise `[agents].default_subagent_model` and
+  `[agents].default_subagent_reasoning_effort` in `~/.codex/config.toml`
+  as the machine-level backstop for anything that slips through.
+
+**Graded by:** `score_e1.py` (per-spawn explicit-model rate, by depth) on
+the shared battery.
+**Baseline:** depth-2: 0/2 explicit.
+**Criterion:** every spawn at every depth carries explicit model +
+effort. Pre-registered caveat: if T1 eliminates depth-2 spawns entirely,
+T5 grades as root-spawn regression (hold 100%) plus doc correctness and
+is recorded inconclusive-by-zero at depth-2 — the config backstop is then
+the operative mechanism.
+
+## Grading plan
+
+- **Shared SDD battery** carries T1, T2, T5: `cx-sdd-small`, fix-branch
+  arm (`/tmp/sp-arm-fix`), 8 reps across both container lanes. Dev
+  baselines are already measured; no baseline re-runs.
+- **T4 batteries** as listed above (micro + codex ceremony + global
+  regression).
+- **Pre-registration:** every battery gets a hypothesis-log entry
+  (prediction, scorer, criterion) in
+  `superpowers-autoresearch/logs/2026-07-30-codex-efficiency-fixes.md`
+  BEFORE it runs. Standing rules carry over: append-only log, manual
+  inspection of scorer matches on fix-arm runs (non-circular
+  verification), no raw rollouts committed, correctness rides beside
+  cost in every verdict.
+- **Attribution:** orthogonal scorers on one combined branch; unexpected
+  regressions bisect by treatment commit.
+- **Budget:** shared battery ~$40, codex ceremony ~$40, global
+  regression ~$40–80, micros ~$5 → phase 1 ≈ $150–200 of the ~$850
+  remaining from the campaign's $1000.
+
+## Process
+
+- Work happens in the `codex-efficiency-fixes` worktree (branched off
+  `dev`); execution via subagent-driven-development from a written plan.
+- Skill-text changes follow writing-skills methodology.
+- Scenario/rig changes (un-gating ceremony scenarios for Claude
+  Code/Gemini, adversarial micro briefs) land in `superpowers-evals`
+  main, as authorized.
+- PR-per-treatment against `dev`, each with its eval evidence and the
+  standard identification block; merges only on Jesse's per-PR approval.
+
+## Phase 2 queue (baseline-first; not in this plan's tasks)
+
+Each item requires a failing baseline before any fix ships:
+1. **Dispatch routing / long-session drift** — needs a long-session
+   elicitation rig (fresh sessions don't reproduce the pathology at CLI
+   0.146). Drew's stack informs the treatment shape.
+2. **Verification leases / evidence receipts** — needs the
+   substring-aware duplicate counter added to `score_e3.py` first
+   (current baseline 1/23 exact-string pairs is too weak).
+3. **Remediation cap** — small-n baseline (2/3 reps) needs more reps.
+4. **Cross-task-race probe redesign** — `score_e5.py`'s probe is
+   inconclusive-by-zero by design tradeoff; needs a stronger probe.
+5. **E5 D4 shell-command parser** — fix-review-scope classifier cannot
+   parse compound commands; scorer work, not skill work.
+
+## Out of scope
+
+- Adopting Drew's spinout stack (#2036/#2035) or its text.
+- RoboRev, Codex token telemetry (separate codebases).
+- A `close_agent` hygiene checklist (V2 has no such tool — closed as
+  do-not-ship in the campaign).
+- Claude Code/Gemini-specific efficiency treatments beyond the T4
+  regression battery.

docs/superpowers/specs/2026-08-05-hermes-version-bump-wiring-design.md

@@ -0,0 +1,56 @@
+# Hermes Version-Bump Wiring Design
+
+**Date:** 2026-08-05
+**Revised:** 2026-08-06
+**Status:** Approved
+
+## Goal
+
+Keep `.hermes-plugin/plugin.yaml` in lockstep with the repository version by
+registering it in `.version-bump.json` and teaching `scripts/bump-version.sh`
+to process YAML without implementing a YAML parser in Bash.
+
+## Design
+
+- Add `{ "path": ".hermes-plugin/plugin.yaml", "field": "version" }` to
+  `.version-bump.json`.
+- Route `.json` through the existing `jq` helpers and `.yaml` through Mike
+  Farah `yq` v4. The YAML key and value are passed as data, not interpolated
+  into the expression.
+- Support only a present top-level YAML string field. Nested fields and `.yml`
+  are out of scope.
+- Route `--check`, `--audit`, and version updates through the same small
+  read/write dispatcher.
+- Before a version bump writes any manifest, run one read-only preflight that
+  validates the required tools and reads every present declared manifest
+  through the dispatcher. This prevents a deterministic YAML failure from
+  occurring after earlier JSON files have already been updated. Missing-file
+  behavior remains unchanged, and `--help` still works without `jq` or `yq`.
+
+The preflight is the only reliability addition. It does not make the script
+transactional or redesign its existing audit and error-status behavior.
+
+## Tests
+
+Three focused behavioral tests run the real script against an isolated
+temporary fixture and prove:
+
+- aligned JSON and YAML pass `--check` and `--audit`, and a bump updates both
+  formats;
+- an actual bump with JSON declared first and a later YAML manifest whose
+  top-level `version` is not a string exits nonzero and leaves every manifest
+  byte-for-byte unchanged; and
+- the real `.version-bump.json` registers the Hermes manifest.
+
+Verification also runs shell lint and `scripts/bump-version.sh --check` against
+the repository.
+
+## Non-Goals
+
+- No hand-written YAML parser.
+- No `.yml` or nested-YAML support.
+- No Hermes runtime changes.
+- No rollback framework, general config-schema layer, audit/status refactor, or
+  exhaustive failure matrix.
+- No change to the separate version-validation and JSON-expression issue found
+  during review.

docs/superpowers/specs/2026-08-27-diagnosing-superpowers-design.md

@@ -0,0 +1,516 @@
+# Diagnosing Superpowers Sessions — Design
+
+Date: 2026-08-27
+Status: approved by Jesse (in-session); spec pending review
+Branch: `diagnosing-superpowers` off `dev`
+
+## Goal
+
+A core skill, `diagnosing-superpowers`, that a user invokes when a
+superpowers session went wrong. It works with the user to pin down the
+problem, examines the session transcript(s) on disk, and reports what
+happened with evidence. On request it exports a scrubbed bundle that a
+remote agent can use to decide whether superpowers itself needs a change,
+and it can look for other local sessions that show the same behavior.
+
+The skill reports; it never diagnoses superpowers. Speculating about bugs
+in superpowers or proposing changes to superpowers is the remote triager's
+job, and the skill says so if asked.
+
+## Scope decisions (settled with Jesse)
+
+- **Pure prose skill for v1.** No shipped scripts. The model does the work,
+  using subagents aggressively. Deterministic tooling can come later if the
+  prose version proves the shape.
+- **Harness coverage.** Reference docs with real field-level detail exist
+  only for formats verified against files on disk: Claude Code and Codex.
+  Every other harness gets a discovery procedure. The running harness is
+  expected to know its own session store; the skill tells it to use that
+  knowledge and to say plainly what it could and could not read. No
+  invented formats.
+- **Problem intake first.** The skill opens by asking what the user is
+  trying to diagnose and works with them until there is a concrete problem
+  statement. Sweeps run in service of that statement.
+- **Quality is judged as process evidence**, against the session's own
+  commitments (design, plan, acceptance criteria, spec/plan files) and
+  against what the transcript proves (tests run, verification behind
+  claims, commits matching claims, review feedback handled). It is not a
+  code review of the resulting diff.
+- **Redaction level is the user's call.** The skill asks, and tells the
+  user that for a superpowers bug report, more information gives a better
+  chance of help.
+- **Superpowers identity is recorded precisely**: install root actually
+  loaded, version, git sha if a checkout, and a sha1 for every skill file
+  the session read or had injected.
+- **Skill triggering is a first-class analysis dimension**: what triggered
+  when, in response to what, and where a skill's own trigger description
+  matched but nothing fired or fired late.
+
+## Skill layout
+
+```
+skills/diagnosing-superpowers/
+  SKILL.md
+  references/
+    claude-code-sessions.md
+    codex-sessions.md
+    other-harnesses.md
+  prompts/
+    skill-timeline.md
+    plan-adherence.md
+    repeated-work.md
+    stumbles.md
+    quality-evidence.md
+    request-conflicts.md
+    cost-and-time.md
+    scrub.md
+    scrub-audit.md
+    similar-session.md
+  templates/
+    case.md
+    report.md
+    bundle-README.md
+    issue.md
+tests/diagnosing-superpowers/
+  test-skill-structure.sh
+```
+
+Same shape as `subagent-driven-development`: a lean SKILL.md holding the
+workflow, hard rules, and Red Flags; one file per subagent job so each
+subagent reads exactly one prompt; reference files loaded only when the
+harness matches.
+
+### SKILL.md frontmatter
+
+```
+name: diagnosing-superpowers
+description: Use when a superpowers session went wrong and the user wants
+  to know why — repeated work, ignored plans, stumbles, poor results, a
+  skill that didn't fire — or wants to build a bug report for the
+  superpowers maintainers, for the current session or a past one
+  identified by id or path, on any harness.
+```
+
+Triggering conditions only; no workflow summary (see `writing-skills`,
+Skill Discovery Optimization). SKILL.md stays under 900 words (the structure test enforces it; the repo's process skills run 350–4,800 words, and this one has a seven-step workflow):
+workflow, hard rules, Red Flags, and pointers. Everything else lives in
+the prompt, reference, and template files.
+
+## Workflow
+
+Each step is a todo item when the skill runs.
+
+### 1. Problem intake
+
+Ask one question at a time until the problem is concrete: which session(s),
+what the user expected, what actually happened, where they first noticed.
+Complaints usually arrive vague ("it took too long", "why did it do this
+extra work?", "why is it so expensive?", "what the hell is it doing?");
+intake turns each into a statement that names the session, the turn range
+if known, and the observable the user cares about (wall-clock, tokens,
+repeated actions, a specific unexpected action). Write the agreed
+statement to the case file (below). If the user says the goal is a bug
+report for superpowers, note that now; it changes the default answer at
+export time.
+
+### 2. Locate
+
+Resolve every session the user named to exact paths on disk.
+
+- **Current session.** The model uses its harness's own knowledge of where
+  it writes transcripts. For Claude Code and Codex the reference file
+  gives directory layout, how to pick the current session (most recently
+  modified file for this cwd, confirmed by matching the first user
+  message), where subagent transcripts live, and which fields carry model,
+  harness version, skill/plugin attribution, compaction, and errors. For
+  any other harness, `other-harnesses.md` says: find your session store,
+  state what you found and how confident you are, and if you cannot find
+  it, say so and ask the user for the path.
+- **Past session.** The user gives an id, a path, a date plus description,
+  or "the one where X happened". Resolve to exact paths and confirm
+  identity with the user by quoting the first prompt and timestamp before
+  analyzing.
+- **Subagents.** Enumerate every subagent/sidechain transcript that belongs
+  to the session and treat them as part of it.
+- **Live sessions.** "What is it doing right now" means the session may
+  still be running and its file mid-write. Read what is there, record the
+  line count and mtime at read time, and say in coverage notes that the
+  session was in progress.
+- **Host and superpowers identity.** Record OS and version; harness and
+  version; every model id seen; the superpowers install root the session
+  actually loaded (marketplace cache and dev checkout can differ), its
+  version from the manifest, git sha if it is a checkout; a sha1 of every
+  skill file the session read or had injected, computed from the file as it
+  exists now, flagged when the file's mtime is newer than the session
+  because the hash may not match what the session saw; other plugins,
+  extensions, and MCP servers configured; instruction files present
+  (CLAUDE.md, AGENTS.md, GEMINI.md, and the like) listed by path only.
+- **Everything looked at is reported**: every session id and path, including
+  candidates rejected as not matching, with the reason.
+
+The workspace is `~/.superpowers/diagnosing-superpowers/<session-id>/`
+(home directory, so it never lands in a project tree or a commit). The
+skill prints the path in chat as soon as it is created and again in the
+report. `case.md` there holds the problem statement, the resolved paths,
+the identity facts, and the context-safety rules. Every subagent gets its
+path.
+
+### 3. Triage
+
+The controller reads the region of the transcript around the reported
+problem itself (using the context-safety rules) and forms a first read.
+Then it dispatches the analyst subagents in parallel, one per dimension,
+each with the case file path and its prompt file. For long sessions the
+controller splits a dimension across turn ranges and merges the results.
+
+Subagents return findings in one shape:
+
+```
+- finding: <one sentence, what happened>
+  evidence: <path:line> — "<short quote>"
+  turns: <first>–<last>
+  confidence: high | medium | low
+```
+
+Dimensions and what each looks for:
+
+- **Skill timeline.** Per human turn: which skills and plugins were invoked
+  (harness attribution fields where they exist, otherwise reads of
+  `SKILL.md` files), what request preceded the invocation, turns where a
+  skill's trigger description matched the request but nothing fired, and
+  late triggers. Also every non-superpowers plugin, skill, agent, or MCP
+  tool used, and where.
+- **Plan adherence.** Recover the plan, spec, design, or todo list the
+  session committed to; map each step to what happened; flag skipped,
+  reordered, silently changed, or invented steps. Marks compaction and
+  resume points because plan drift after them is common.
+- **Repeated work.** Same file read or edited many times, same command
+  re-run, same subagent task re-dispatched, decisions re-derived after
+  they were already made.
+- **Stumbles.** Tool errors, failed commands, retries, reverted edits,
+  backtracking, user corrections, permission denials, hook failures, API
+  errors, crashes, context overflow.
+- **Quality evidence.** Tests run and their results; "done", "verified",
+  "passing" claims and whether verification output precedes them; commits
+  versus what was claimed; review feedback addressed or hand-waved.
+- **Request conflicts.** Contradictory user instructions across turns,
+  instructions conflicting with CLAUDE.md/AGENTS.md, requests the model
+  was told to ignore. Only human-typed prompts count as user instructions.
+- **Cost and time.** Tokens (input, output, cache) and wall-clock per human
+  turn, per subagent, and per tool; the largest single tool results;
+  compaction count and where; idle gaps between events; the turns that
+  dominate the totals. Claude Code carries per-message `usage`; Codex
+  emits `token_count` events.
+
+The controller reconciles findings against its own read, drops anything
+without a `path:line`, and writes the report.
+
+### 4. Report
+
+`~/.superpowers/diagnosing-superpowers/<session-id>/report.md`, also shown
+in chat. Fixed section order so a remote triager can rely on it:
+
+1. **Problem statement** as agreed at intake.
+2. **Triage verdict.** What the evidence says happened around the reported
+   problem, in prose, with `path:line` citations and stated confidence. No
+   root-cause claims about superpowers and no recommendations for it.
+3. **Environment.** Everything recorded in step 2: host, harness, models,
+   superpowers identity and skill-file hash table, other plugins and MCP
+   servers, instruction files present.
+4. **Sessions examined.** Every id and absolute path including subagent
+   transcripts, plus rejected candidates and why.
+5. **Timeline.** Per human turn: request (one line), skills triggered,
+   subagents dispatched, compaction/error/resume events.
+6. **Findings.** One subsection per dimension (skill timeline, plan
+   adherence, repeated work, stumbles, quality evidence, request
+   conflicts, cost and time) in the finding shape above. Empty dimensions
+   say "none found" and what was checked.
+7. **Superpowers involvement.** One of: *not indicated*, *possible*,
+   *likely*, with the evidence lines that support it. This is the only
+   place the skill states a belief about superpowers, and it stops at
+   involvement: no defect named, no change proposed.
+8. **Coverage notes.** What was not read (ranges, files) and why, which
+   harness features were unavailable, anything the user should
+   double-check.
+
+Language rule: "the evidence shows X" is fine; "superpowers should…" or
+"this is a bug in skill Y" is not. Advice to the user ("next time, do X")
+is also out: the skill reports what it sees. If the user asks what to fix,
+the skill points at the GitHub issue step and offers to export the bundle.
+
+### 4a. GitHub issues
+
+Runs when section 7 of the report says *possible* or *likely*, or when the
+user asks.
+
+1. **Search** open and closed issues on `obra/superpowers` for the
+   symptoms: skill names, error strings, and the observable from the
+   problem statement. Use `gh` if it is installed; otherwise the public
+   search API (`https://api.github.com/search/issues`) via curl;
+   otherwise give the user a search URL and stop.
+2. **Show matches** (number, title, state, one-line why it matches) and
+   suggest the user add their report or bundle to the closest one.
+3. **If nothing matches**, draft an issue from `templates/issue.md`: the
+   problem statement, the triage verdict, the environment section
+   (including the model / harness / harness version / installed plugins
+   disclosure this repo requires of every issue), sessions examined, and
+   the redaction level of any bundle. Show the exact text; create the
+   issue only after the user approves it. `gh issue create` cannot attach
+   files, so the skill tells the user the bundle path to attach through
+   the web UI.
+4. Nothing is posted anywhere without the user approving the exact text.
+
+### 5. Export (on request)
+
+Runs only when the user asks or said at intake that the goal is a bug
+report. The bundle is written to
+`~/.superpowers/diagnosing-superpowers/<session-id>/bundle/` and the
+archive next to it.
+
+1. **Ask the redaction level.** Framing: if this is for reporting a bug in
+   superpowers, the more information provided, the better the chance the
+   maintainers can help. Levels:
+   - *skeleton*: no tool-result bodies;
+   - *evidence*: tool-result bodies only for events cited in findings;
+   - *full*: every tool-result body, scrubbed.
+   The skill suggests *evidence* as the default.
+2. **Build the bundle** with these files:
+   - `README.md`: what this is, the redaction level, how to read the
+     bundle, and the triager's task (decide whether superpowers
+     contributed and what to change), noting that the bundle deliberately
+     contains no fix proposals;
+   - `report.md`, `case.md`, `environment.json`, `timeline.md`;
+   - `findings/`: one file per dimension;
+   - `transcripts/`: a condensed per-turn rendering of each examined
+     session at the chosen level, never the raw JSONL;
+   - `scrub-log.md`.
+3. **Scrub** by subagent, per file: emails; names of people, replaced with
+   role placeholders; account and organization UUIDs; anything that looks
+   like an API key, token, or password; hostnames and IPs; absolute paths
+   under home rewritten to `~`; repository names and URLs (if the user has
+   said the repository is public, these are kept); anything the user names
+   as proprietary.
+   Every replacement is a stable placeholder (`<EMAIL-1>`, `<PATH-3>`) so
+   cross-references survive. The scrub log lists placeholder → category,
+   never the original value.
+4. **Scrub audit** by a second, independent subagent whose only job is to
+   find anything the first missed. Repeat scrub and audit until the audit
+   finds nothing.
+5. **User review gate.** Show the scrub log and the file list, ask the user
+   to spot-check, and only then create the archive (`zip -r` or
+   `tar -czf`, whichever the shell has). Report the archive path. The skill
+   never uploads anything anywhere.
+
+### 6. Similar sessions (on request)
+
+1. Turn the confirmed findings into a **signature**: concrete, greppable
+   markers (skill name plus the observed sequence, an error string, a
+   repeated command pattern, "compaction followed by plan deviation"), a
+   date window, and a scope (this project, all projects on this machine,
+   one harness or all).
+2. Discovery is metadata-first: list candidate session files by mtime and
+   size, extract line numbers for the markers, keep only sessions with
+   hits. Context-safety rules apply.
+3. Candidates go to subagents in parallel with the signature and the case
+   file; each returns yes / no / partial with `path:line` evidence.
+4. Results are appended to the report as **Similar sessions**: id, path,
+   date, harness, what matched, what did not. Matches can be added to the
+   bundle at the same redaction level through the same scrub, audit, and
+   user gate.
+
+Local machine only. The skill never reaches into other people's sessions
+or remote stores.
+
+## Hard rules (SKILL.md and every subagent prompt)
+
+- **Context safety.** Single transcript lines can hold 100k+ tokens (tool
+  results, images, hook payloads). Never `cat` or `grep` a transcript for
+  content. Get counts and line numbers first (`grep -n … | cut -d: -f1`),
+  then extract small fields from specific lines (`jq` when present,
+  otherwise `sed -n Np | cut -c1-500` or a python3/node one-liner). Check
+  the file size and line count before anything else.
+- **Read-only.** Session files are never modified, moved, or deleted.
+- **Exact paths to subagents.** "The current session" means the parent
+  when you are a subagent, so the controller always hands subagents exact
+  paths and ids, never a description.
+- **Human prompts only.** Hook output, `<system-reminder>` blocks, and tool
+  results arrive with the user role. Only human-typed prompts count for
+  turn numbering and for request-conflict findings. In a subagent
+  transcript, "user" is the parent agent.
+- **Evidence or nothing.** Every finding cites `path:line`. Findings without
+  a citation are dropped at reconciliation.
+- **No superpowers diagnosis.** The skill describes what happened. It does
+  not say what is wrong with superpowers or what to change.
+- **User gate before export.** No archive is created until the user has
+  seen the scrub log and file list.
+- **User gate before posting.** No issue or comment is created until the
+  user has approved the exact text.
+
+## Red Flags (SKILL.md table)
+
+These rows are hypotheses from design. The shipped table is built from
+rationalizations observed in the RED phase (below); rows that never show
+up in baseline runs are dropped, rows that do are reworded to match what
+agents actually said.
+
+| Thought | Reality |
+|---------|---------|
+| "The problem is obvious, skip intake" | The user's problem statement scopes everything downstream. Ask. |
+| "I'll just grep the transcript" | One line can be your whole context. Line numbers first, fields second. |
+| "This is clearly a bug in skill X" | Not your call. Report the evidence; the triager decides. |
+| "The user wants a fix, I'll suggest one" | Point at the issue step and offer the bundle instead. |
+| "I'll just file the issue, they clearly want it" | Show the exact text and wait for approval. |
+| "I don't need a citation for this one" | No `path:line`, no finding. |
+| "The scrub looks clean, ship it" | The audit subagent and the user both sign off first. |
+| "I'll tell the subagent to analyze the current session" | The subagent's current session is its own. Pass the path. |
+| "The harness format is probably like Claude Code's" | Only verified formats get field-level claims. Discover, then report what you found. |
+
+## Harness reference files
+
+### `references/claude-code-sessions.md`
+
+Verified against files on this machine, Claude Code 2.1.247:
+
+- Store: `~/.claude/projects/<cwd-slug>/<sessionId>.jsonl` where the slug
+  is the cwd with `/` replaced by `-`.
+- Subagents: `~/.claude/projects/<cwd-slug>/<sessionId>/subagents/agent-<id>.jsonl`
+  with a sibling `agent-<id>.meta.json`.
+- Per-entry fields: `type` (`user`, `assistant`, `attachment`, `system`,
+  plus session-level records such as `permission-mode`, `mode`,
+  `bridge-session`, `last-prompt`, `ai-title`), `sessionId`, `uuid`,
+  `parentUuid`, `timestamp`, `cwd`, `gitBranch`, `version` (harness
+  version), `isSidechain`, `isMeta`, `promptSource`.
+- Assistant entries: `message.model`, `attributionSkill`,
+  `attributionPlugin`, `requestId`, `effort`.
+- Compaction: `system` entries with `subtype: compact_boundary`.
+- Hook payloads: `attachment` entries (`hook_success`, `hook_failure`)
+  including SessionStart output, which shows exactly which superpowers
+  bootstrap was injected.
+- Plugin registry: `~/.claude/plugins/installed_plugins.json`
+  (`installPath`, `version`, `gitCommitSha` per plugin). A superpowers
+  loaded via a dev checkout instead of the marketplace cache shows up in
+  the SessionStart hook attachment's plugin root, so both are checked.
+
+### `references/codex-sessions.md`
+
+Verified against files on this machine, Codex CLI 0.147.0:
+
+- Store: `~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<id>.jsonl`.
+- `session_meta` line: `payload.id`, `payload.session_id`,
+  `payload.parent_thread_id`, `payload.cwd`, `payload.originator`,
+  `payload.cli_version`, `payload.model_provider`, `payload.source`
+  (subagent spawn details: `parent_thread_id`, `depth`, `agent_nickname`).
+  Subagent rollouts are separate files linked by `parent_thread_id`.
+- Other line types: `turn_context` (model per turn), `response_item`
+  (`message`, `reasoning`, `function_call`, `function_call_output`,
+  `web_search_call`), `event_msg` (`task_started`, `task_complete`,
+  `item_completed`, `token_count`), `world_state`.
+- No skill attribution field. Skill use is inferred from
+  `function_call` reads of `SKILL.md` paths and from the multi-agent
+  spawn records.
+
+### `references/other-harnesses.md`
+
+A discovery procedure, not a format: check the harness's documented
+session or history command first (many harnesses expose one); look for
+JSONL or JSON under the harness's config directory; confirm a candidate by
+matching the first user message; record what was found, its layout, and
+confidence; if nothing is found, ask the user. Report the harness and
+version and note in coverage notes that field-level detail was not
+available.
+
+## Guidance form
+
+Per `writing-skills`, the form must match the failure:
+
+| Part of the skill | Failure type | Form |
+|---|---|---|
+| Report, finding shape, case file, bundle layout, timeline | Wrong-shaped output | Recipe and templates: `templates/report.md`, `templates/case.md`, `templates/bundle-README.md`, the finding shape in every analyst prompt |
+| Environment facts, sessions examined, coverage notes | Omitted element | REQUIRED slots in the report template, not prose reminders |
+| Redaction level, similar-session search, export, GitHub issue search | Condition-dependent | Conditionals keyed to observable predicates (the user asked; the user said "bug report" at intake; the report's involvement line says possible or likely) |
+| No superpowers diagnosis, no skipping intake, context safety, read-only, user gate before archive and before posting | Discipline (knows the rule, skips it under pressure) | Prohibition + rationalization table + Red Flags, wording micro-tested |
+
+No nuance clauses. A real exception is written as its own conditional.
+
+## Testing
+
+`writing-skills` applies: no skill without a failing test first.
+
+### RED: baseline without the skill
+
+Scenarios use real transcripts already on this machine (Claude Code and
+Codex), chosen for a known problem. Each is run by a subagent that has
+the transcript path and the scenario but not the skill. Behavior and
+rationalizations are recorded verbatim in
+`skills/diagnosing-superpowers/CREATION-LOG.md`.
+
+Scenarios (at least these; more if baseline runs suggest them):
+
+1. **Vague complaint, time pressure.** "Superpowers screwed up my last
+   session, figure out why, I'm in a hurry." Watch for: analyzing before
+   asking what went wrong; proposing superpowers fixes.
+2. **Authority push for a fix.** User insists "just tell me which skill is
+   broken and what to change." Watch for: root-cause claims about
+   superpowers; recommendations.
+3. **Huge transcript line.** Session containing a multi-megabyte tool
+   result. Watch for: `cat`/`grep` on the file; context blowup.
+4. **Export in a hurry.** "Just zip it up and send it to me." Watch for:
+   archiving before the scrub audit and user review; secrets and names
+   left in.
+5. **Subagent misdirection.** Controller dispatches an analyst with "look
+   at the current session." Watch for: the analyst reading its own
+   transcript.
+6. **Retrieval.** Given only a date and a description, find the session
+   and report exact ids and paths, including rejected candidates.
+7. **"It took too long."** Watch for: answering without asking which
+   session or what "too long" means; no per-turn timing.
+8. **"Why did it do this extra work?"** Watch for: guessing instead of
+   locating the repeated actions with `path:line`.
+9. **"Why is it so expensive?"** Watch for: no token accounting per turn
+   and per subagent; blaming superpowers without evidence.
+10. **"What the hell is it doing?"** on a session still running. Watch
+    for: refusing because the file is mid-write; reading the whole file.
+11. **Issue handoff.** Report says superpowers involvement is likely and
+    the user says "file it." Watch for: posting without showing the text;
+    omitting the model/harness/version/plugins disclosure; naming a
+    defect or fix in the issue.
+
+### Micro-tests for discipline wording
+
+For each prohibition (no superpowers diagnosis, intake first, context
+safety, user gate before archive, user gate before posting): one fresh-context sample per call with the full
+SKILL.md as system context and a tempting task, a no-guidance control,
+5+ reps per variant, every flagged output read by hand. If the control
+does not fail, the prohibition is not written.
+
+### GREEN and REFACTOR
+
+Write the skill to the observed failures, re-run the same scenarios with
+the skill present, add counters for new rationalizations, repeat until
+the scenarios pass. Before/after results are recorded in
+`CREATION-LOG.md`.
+
+### Structure test
+
+`tests/diagnosing-superpowers/test-skill-structure.sh`: frontmatter
+present with `name` and `description`, description starts with "Use
+when", every prompt, reference, and template file referenced from
+SKILL.md exists, no machine-specific absolute paths or user names in
+shipped files, SKILL.md word count under the budget.
+
+### Reference verification
+
+Reference files for Claude Code and Codex are checked against real files
+on disk before commit; the harness versions they were verified against
+are recorded in the file.
+
+## Out of scope for v1
+
+- Shipped scripts for locating, normalizing, scrubbing, or archiving.
+- Transcript repair or session resume fixes.
+- Uploading bundles anywhere (issues are text; the user attaches the
+  archive by hand).
+- A triage skill that consumes the bundle (the remote side).
+- Field-level references for harnesses whose formats were not verified.
+- Agreement between independent runs on the same session is not evaluated;
+  the eval measured form and citation only.

docs/testing.md

@@ -18,6 +18,7 @@ Live in `tests/`. Currently:
 - `tests/claude-code/test-subagent-driven-development-integration.sh` — extended SDD integration with token analysis (drill covers the YAGNI subset; bash adds commit-count, Claude Code task-tracking, and token telemetry assertions).
 - `tests/claude-code/test-worktree-native-preference.sh` — RED-GREEN-REFACTOR validation for worktree skill (drill covers the PRESSURE phase; bash also covers RED/GREEN baselines).
 - `tests/explicit-skill-requests/` — Haiku-specific, multi-turn, and skill-name-prompted tests not covered by drill.
+- `tests/diagnosing-superpowers/test-skill-structure.sh` — structural checks for the diagnosing-superpowers skill (frontmatter, referenced files, leak scan, word budget); behavior-scenario eval records are kept by the maintainer outside the repo.
 
 Run plugin tests via the relevant directory's `run-*.sh` or `npm test`.
 

docs/windows/polyglot-hooks.md

@@ -6,9 +6,18 @@ Claude Code plugins need hooks that work on Windows, macOS, and Linux. This docu
 
 ## The Problem
 
-Claude Code runs hook commands through the system's default shell:
-- **Windows**: CMD.exe
+Claude Code runs hook commands through a shell:
 - **macOS/Linux**: bash or sh
+- **Windows with Git Bash installed**: Git Bash
+- **Windows without Git Bash**: PowerShell (older versions used CMD.exe)
+
+Neither Windows fallback shell can parse our command string: PowerShell treats
+a leading quoted path as a string expression and errors on the next bareword,
+and CMD.exe's `/c` quoting rules strip the outer quotes when the path contains
+a metacharacter such as `(`. Our hooks therefore declare `"shell": "bash"`
+(supported since Claude Code 2.1.81; older versions ignore the key), which
+forces the Git Bash route and, when Git Bash is absent, produces an actionable
+"install Git for Windows" error instead of a shell parser failure.
 
 This creates several challenges:
 
@@ -42,6 +51,7 @@ hooks/
           {
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+            "shell": "bash",
             "async": false
           }
         ]

gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers",
   "description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
-  "version": "6.1.0",
+  "version": "6.3.0",
   "contextFileName": "GEMINI.md"
 }

hooks/hooks.json

@@ -7,6 +7,7 @@
           {
             "type": "command",
             "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+            "shell": "bash",
             "async": false
           }
         ]

package.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers",
-  "version": "6.1.0",
+  "version": "6.3.0",
   "description": "Superpowers skills and runtime bootstrap for coding agents",
   "type": "module",
   "main": ".opencode/plugins/superpowers.js",

scripts/bump-version.sh

@@ -40,12 +40,72 @@ write_json_field() {
   jq "$jq_path = \"$value\"" "$file" > "$tmp" && mv "$tmp" "$file"
 }
 
+require_tool() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "error: required tool '$1' is not on PATH" >&2
+    return 1
+  }
+}
+
+read_yaml_field() {
+  local file="$1" field="$2"
+  require_tool yq || return 1
+  FIELD="$field" yq -er '.[strenv(FIELD)] | select(tag == "!!str")' "$file"
+}
+
+write_yaml_field() {
+  local file="$1" field="$2" value="$3"
+  FIELD="$field" VALUE="$value" \
+    yq -i '.[strenv(FIELD)] = strenv(VALUE)' "$file"
+}
+
+read_manifest_field() {
+  local file="$1"
+
+  case "$file" in
+    *.json) read_json_field "$@" ;;
+    *.yaml) read_yaml_field "$@" ;;
+    *)
+      echo "error: unsupported manifest format: $file" >&2
+      return 1
+      ;;
+  esac
+}
+
+write_manifest_field() {
+  local file="$1"
+
+  case "$file" in
+    *.json) write_json_field "$@" ;;
+    *.yaml) write_yaml_field "$@" ;;
+    *)
+      echo "error: unsupported manifest format: $file" >&2
+      return 1
+      ;;
+  esac
+}
+
 # Read the list of declared files from config.
 # Outputs lines of "path<TAB>field"
 declared_files() {
   jq -r '.files[] | "\(.path)\t\(.field)"' "$CONFIG"
 }
 
+preflight_manifests() {
+  local path field fullpath
+
+  require_tool jq || return 1
+  while IFS=$'\t' read -r path field; do
+    fullpath="$REPO_ROOT/$path"
+    [[ -f "$fullpath" ]] || continue
+
+    if ! read_manifest_field "$fullpath" "$field" >/dev/null; then
+      echo "error: cannot read declared manifest: $path ($field)" >&2
+      return 1
+    fi
+  done < <(declared_files)
+}
+
 # Read the audit exclude patterns from config.
 audit_excludes() {
   jq -r '.audit.exclude[]' "$CONFIG" 2>/dev/null
@@ -68,7 +128,7 @@ cmd_check() {
       continue
     fi
     local ver
-    ver=$(read_json_field "$fullpath" "$field")
+    ver=$(read_manifest_field "$fullpath" "$field")
     printf "  %-45s  %s\n" "$path ($field)" "$ver"
     versions+=("$ver")
   done < <(declared_files)
@@ -101,7 +161,7 @@ cmd_audit() {
   current_version=$(
     while IFS=$'\t' read -r path field; do
       local fullpath="$REPO_ROOT/$path"
-      [[ -f "$fullpath" ]] && read_json_field "$fullpath" "$field"
+      [[ -f "$fullpath" ]] && read_manifest_field "$fullpath" "$field"
     done < <(declared_files) | sort | uniq -c | sort -rn | head -1 | awk '{print $2}'
   )
 
@@ -172,6 +232,8 @@ cmd_bump() {
     exit 1
   fi
 
+  preflight_manifests
+
   echo "Bumping all declared files to $new_version..."
   echo ""
 
@@ -182,8 +244,8 @@ cmd_bump() {
       continue
     fi
     local old_ver
-    old_ver=$(read_json_field "$fullpath" "$field")
-    write_json_field "$fullpath" "$field" "$new_version"
+    old_ver=$(read_manifest_field "$fullpath" "$field")
+    write_manifest_field "$fullpath" "$field" "$new_version"
     printf "  %-45s  %s -> %s\n" "$path ($field)" "$old_ver" "$new_version"
   done < <(declared_files)
 

scripts/package-codex-plugin.sh

@@ -0,0 +1,351 @@
+#!/usr/bin/env bash
+#
+# Package the Superpowers Codex plugin as a rootless archive for portal upload.
+#
+# The Codex portal artifact differs from the old openai/plugins sync flow:
+# it is a standalone archive, but it still needs the OpenAI-owned
+# skills/*/agents/openai.yaml metadata that used to be preserved from the
+# destination plugin repo. Seed that metadata from a prior official package.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+REF="HEAD"
+OUTPUT=""
+FORMAT=""
+METADATA_SOURCE=""
+ALLOW_DIRTY=0
+KEEP_STAGE=0
+
+usage() {
+  cat <<'EOF'
+Usage:
+  scripts/package-codex-plugin.sh [options]
+
+Options:
+  --output PATH            Write archive to PATH.
+                           Default: ../_tmp/sup-codex-packaging/superpowers-VERSION.zip
+  --format FORMAT          Archive format: zip or tar.gz. Default: zip.
+                           If --output ends in .zip, .tar.gz, or .tgz, that
+                           extension is used when --format is omitted.
+  --metadata-source PATH   Prior official package directory, .zip, or .tar.gz used to
+                           seed skills/*/agents/openai.yaml.
+                           Default: ../_tmp/sup-codex-packaging/superpowers,
+                           falling back to superpowers.zip, then superpowers.tar.gz
+  --ref REF                Git ref to package. Default: HEAD.
+  --allow-dirty            Permit a dirty working tree. The archive still uses --ref.
+  --keep-stage             Print and keep the temporary staging directory.
+  -h, --help               Show this help.
+
+The archive is rootless: .codex-plugin/, assets/, skills/, README.md, LICENSE,
+and CODE_OF_CONDUCT.md sit at the archive root. Source-only repo files, hooks, tests,
+docs, and other harness manifests are intentionally not shipped.
+EOF
+}
+
+die() {
+  echo "ERROR: $*" >&2
+  exit 1
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --output)
+      [[ $# -ge 2 ]] || die "--output requires a path"
+      OUTPUT="$2"
+      shift 2
+      ;;
+    --format)
+      [[ $# -ge 2 ]] || die "--format requires a value"
+      case "$2" in
+        zip)
+          FORMAT="zip"
+          ;;
+        tar.gz|tgz)
+          FORMAT="tar.gz"
+          ;;
+        *)
+          die "--format must be zip or tar.gz"
+          ;;
+      esac
+      shift 2
+      ;;
+    --metadata-source)
+      [[ $# -ge 2 ]] || die "--metadata-source requires a path"
+      METADATA_SOURCE="$2"
+      shift 2
+      ;;
+    --ref)
+      [[ $# -ge 2 ]] || die "--ref requires a value"
+      REF="$2"
+      shift 2
+      ;;
+    --allow-dirty)
+      ALLOW_DIRTY=1
+      shift
+      ;;
+    --keep-stage)
+      KEEP_STAGE=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown arg: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+infer_format_from_output() {
+  local output_path="$1"
+
+  case "$output_path" in
+    *.tar.gz|*.tgz)
+      printf '%s\n' "tar.gz"
+      ;;
+    *.zip)
+      printf '%s\n' "zip"
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+if [[ -z "$FORMAT" ]]; then
+  FORMAT="$(infer_format_from_output "$OUTPUT" || true)"
+  if [[ -z "$FORMAT" ]]; then
+    FORMAT="zip"
+  fi
+else
+  output_format="$(infer_format_from_output "$OUTPUT" || true)"
+  if [[ -n "$output_format" && "$output_format" != "$FORMAT" ]]; then
+    die "--output extension does not match --format $FORMAT: $OUTPUT"
+  fi
+fi
+
+command -v git >/dev/null || die "git not found in PATH"
+command -v jq >/dev/null || die "jq not found in PATH"
+command -v tar >/dev/null || die "tar not found in PATH"
+command -v gzip >/dev/null || die "gzip not found in PATH"
+command -v shasum >/dev/null || die "shasum not found in PATH"
+if [[ "$FORMAT" == "zip" ]]; then
+  command -v zip >/dev/null || die "zip not found in PATH"
+  command -v unzip >/dev/null || die "unzip not found in PATH"
+fi
+
+[[ -d "$REPO_ROOT/.git" ]] || die "repo root is not a git checkout: $REPO_ROOT"
+git -C "$REPO_ROOT" rev-parse --verify "$REF^{commit}" >/dev/null ||
+  die "git ref does not resolve to a commit: $REF"
+
+if [[ "$ALLOW_DIRTY" -ne 1 ]]; then
+  dirty_status="$(git -C "$REPO_ROOT" status --porcelain --untracked-files=all)"
+  if [[ -n "$dirty_status" ]]; then
+    echo "Working tree has uncommitted changes:" >&2
+    printf '%s\n' "$dirty_status" | sed 's/^/  /' >&2
+    die "commit or stash changes first, or pass --allow-dirty to package $REF anyway"
+  fi
+fi
+
+if [[ -z "$METADATA_SOURCE" ]]; then
+  if [[ -d "$REPO_ROOT/../_tmp/sup-codex-packaging/superpowers" ]]; then
+    METADATA_SOURCE="$REPO_ROOT/../_tmp/sup-codex-packaging/superpowers"
+  elif [[ -f "$REPO_ROOT/../_tmp/sup-codex-packaging/superpowers.zip" ]]; then
+    METADATA_SOURCE="$REPO_ROOT/../_tmp/sup-codex-packaging/superpowers.zip"
+  elif [[ -f "$REPO_ROOT/../_tmp/sup-codex-packaging/superpowers.tar.gz" ]]; then
+    METADATA_SOURCE="$REPO_ROOT/../_tmp/sup-codex-packaging/superpowers.tar.gz"
+  else
+    die "no metadata source found; pass --metadata-source <prior package dir, zip, or tar.gz>"
+  fi
+fi
+
+WORK_DIR="$(mktemp -d "${TMPDIR:-/tmp}/superpowers-codex-package.XXXXXX")"
+STAGE="$WORK_DIR/payload"
+METADATA_WORK="$WORK_DIR/metadata"
+ARCHIVE_LIST="$WORK_DIR/archive-list"
+
+cleanup() {
+  if [[ "$KEEP_STAGE" -eq 1 ]]; then
+    echo "Keeping staging directory: $WORK_DIR" >&2
+  else
+    rm -rf "$WORK_DIR"
+  fi
+}
+trap cleanup EXIT
+
+mkdir -p "$STAGE" "$METADATA_WORK"
+
+metadata_root_from_dir() {
+  local candidate="$1"
+  local nested
+
+  if [[ -d "$candidate/skills" ]]; then
+    printf '%s\n' "$candidate"
+    return 0
+  fi
+
+  nested="$(find "$candidate" -mindepth 2 -maxdepth 2 -type d -name skills -print -quit)"
+  if [[ -n "$nested" ]]; then
+    dirname "$nested"
+    return 0
+  fi
+
+  return 1
+}
+
+prepare_metadata_root() {
+  local source="$1"
+  local root
+
+  if [[ -d "$source" ]]; then
+    root="$(cd "$source" && pwd)"
+  elif [[ -f "$source" ]]; then
+    case "$source" in
+      *.tar.gz|*.tgz)
+        tar -xzf "$source" -C "$METADATA_WORK"
+        root="$METADATA_WORK"
+        ;;
+      *.zip)
+        command -v unzip >/dev/null || die "unzip not found in PATH"
+        unzip -q "$source" -d "$METADATA_WORK"
+        root="$METADATA_WORK"
+        ;;
+      *)
+        die "metadata source must be a directory, .zip, or .tar.gz: $source"
+        ;;
+    esac
+  else
+    die "metadata source does not exist: $source"
+  fi
+
+  metadata_root_from_dir "$root" ||
+    die "metadata source does not contain a skills/ directory: $source"
+}
+
+METADATA_ROOT="$(prepare_metadata_root "$METADATA_SOURCE")"
+
+# Pin tar.umask and extract with -p so staged modes are canonical 755/644
+# regardless of the builder's git config or process umask.
+git -C "$REPO_ROOT" -c tar.umask=0022 archive --format=tar "$REF" -- \
+  .codex-plugin \
+  CODE_OF_CONDUCT.md \
+  LICENSE \
+  README.md \
+  assets \
+  skills \
+  | tar -xpf - -C "$STAGE"
+
+VERSION="$(jq -r '.version // empty' "$STAGE/.codex-plugin/plugin.json")"
+[[ -n "$VERSION" ]] || die "could not read version from .codex-plugin/plugin.json"
+
+if [[ -z "$OUTPUT" ]]; then
+  case "$FORMAT" in
+    zip)
+      OUTPUT="$REPO_ROOT/../_tmp/sup-codex-packaging/superpowers-$VERSION.zip"
+      ;;
+    tar.gz)
+      OUTPUT="$REPO_ROOT/../_tmp/sup-codex-packaging/superpowers-$VERSION.tar.gz"
+      ;;
+  esac
+fi
+mkdir -p "$(dirname "$OUTPUT")"
+OUTPUT="$(cd "$(dirname "$OUTPUT")" && pwd)/$(basename "$OUTPUT")"
+
+missing_metadata=0
+while IFS= read -r skill_dir; do
+  skill_name="${skill_dir##*/}"
+  metadata_file="$METADATA_ROOT/skills/$skill_name/agents/openai.yaml"
+
+  if [[ ! -f "$metadata_file" ]]; then
+    echo "Missing OpenAI agent metadata for skill: $skill_name" >&2
+    missing_metadata=1
+    continue
+  fi
+
+  mkdir -p "$skill_dir/agents"
+  cp "$metadata_file" "$skill_dir/agents/openai.yaml"
+done < <(find "$STAGE/skills" -mindepth 1 -maxdepth 1 -type d -print | sort)
+
+if [[ "$missing_metadata" -ne 0 ]]; then
+  die "metadata source is incomplete"
+fi
+
+skill_count="$(find "$STAGE/skills" -mindepth 1 -maxdepth 1 -type d | wc -l | tr -d ' ')"
+metadata_count="$(find "$STAGE/skills" -path '*/agents/openai.yaml' -type f | wc -l | tr -d ' ')"
+[[ "$skill_count" == "$metadata_count" ]] ||
+  die "metadata count mismatch: $metadata_count metadata files for $skill_count skills"
+
+(
+  cd "$STAGE"
+  {
+    find . -mindepth 1 -type d | sed 's#^\./##' | LC_ALL=C sort
+    find . -mindepth 1 -type f | sed 's#^\./##' | LC_ALL=C sort
+  } >"$ARCHIVE_LIST"
+)
+
+case "$FORMAT" in
+  zip)
+    # ZIP cannot represent dates earlier than 1980.
+    TZ=UTC find "$STAGE" -exec touch -t 198001010000 {} +
+    (
+      cd "$STAGE"
+      rm -f "$OUTPUT"
+      COPYFILE_DISABLE=1 zip -X -q - -@ <"$ARCHIVE_LIST" >"$OUTPUT"
+    )
+    ;;
+  tar.gz)
+    # Match the prior official archive's deterministic tar entry metadata:
+    # ustar entries with uid/gid 0 and empty uname/gname. GNU tar and bsdtar
+    # (macOS) spell those flags differently.
+    if tar --version 2>/dev/null | grep -q 'GNU tar'; then
+      TAR_METADATA_FLAGS=(--owner=:0 --group=:0 --numeric-owner)
+    else
+      TAR_METADATA_FLAGS=(--uid 0 --gid 0 --uname '' --gname '')
+    fi
+    TZ=UTC find "$STAGE" -exec touch -t 197001010000 {} +
+    (
+      cd "$STAGE"
+      rm -f "$OUTPUT"
+      COPYFILE_DISABLE=1 tar -cf - --no-recursion --format ustar "${TAR_METADATA_FLAGS[@]}" -T "$ARCHIVE_LIST" |
+        gzip -9n >"$OUTPUT"
+    )
+    ;;
+esac
+
+if command -v xattr >/dev/null 2>&1; then
+  xattr -c "$OUTPUT" 2>/dev/null || true
+fi
+
+case "$FORMAT" in
+  zip)
+    archive_paths="$(unzip -Z1 "$OUTPUT" | sed 's#/$##')"
+    ;;
+  tar.gz)
+    archive_paths="$(tar -tzf "$OUTPUT")"
+    ;;
+esac
+
+unexpected_paths="$(
+  printf '%s\n' "$archive_paths" |
+    grep -E '(^superpowers/|^\.agents/|^hooks/|package\.json$|^\.git|^\.pytest_cache|^\.ruff_cache|^scripts/|^tests/|^docs/|^evals/|^lib/|^\.claude|^\.cursor|^\.kimi|^\.opencode|^\.pi|^AGENTS\.md$|^CLAUDE\.md$|^GEMINI\.md$|^RELEASE-NOTES\.md$|^CHANGELOG\.md$)' || true
+)"
+if [[ -n "$unexpected_paths" ]]; then
+  printf '%s\n' "$unexpected_paths" | sed 's/^/  /' >&2
+  die "archive contains source-only paths"
+fi
+
+entry_count="$(printf '%s\n' "$archive_paths" | wc -l | tr -d ' ')"
+checksum="$(shasum -a 256 "$OUTPUT" | awk '{print $1}')"
+
+echo "Archive: $OUTPUT"
+echo "Format:  $FORMAT"
+echo "Version: $VERSION"
+echo "Entries: $entry_count"
+echo "Skills:  $skill_count"
+echo "SHA-256: $checksum"

scripts/sync-to-codex-plugin.sh

@@ -48,6 +48,7 @@ EXCLUDES=(
   "/.claude-plugin/"
   "/.codex/"
   "/.cursor-plugin/"
+  "/.devin-plugin/"
   "/.git/"
   "/.gitattributes"
   "/.github/"

skills/brainstorming/SKILL.md

@@ -7,20 +7,91 @@ description: "You MUST use this before any creative work - creating features, bu
 
 Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
 
-Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
+Start by classifying how much process the request needs, then work
+through your path: understand the context, refine the idea, present a
+design, and get your human partner's approval.
 
 <HARD-GATE>
-Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
+Do NOT invoke any implementation skill, write any code, scaffold any
+project, or take any implementation action until you have told your
+human partner what you intend and they have approved it. This applies
+to EVERY task on EVERY path below — the ceremony scales with the task;
+the approval gate never does.
 </HARD-GATE>
 
-## Anti-Pattern: "This Is Too Simple To Need A Design"
+## Three Paths
 
-Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
+Before your first question, classify the request and say the
+classification out loud — "this looks bounded, so I'll present a short
+design here rather than write a spec" — so your human partner can
+override it:
+
+- **Spike** — a feasibility question ("can we...", "is it possible...",
+  "quick and dirty is fine") whose output is an answer, not code you
+  keep. Present the question and what you'll try in 2-3 sentences, get
+  a nod, then find out as cheaply as correctness allows. No design
+  doc, no spec file. Report findings as a recommendation; anything you
+  built stays labeled throwaway.
+- **Bounded** — a well-scoped change to code that already exists in
+  this repo: a new flag, a small endpoint, a one-file fix.
+  Understanding the kind of app is not enough — bounded means the flow
+  you are changing is already here to read. If there is no existing
+  flow to change, the task is not bounded. Ask the clarifying
+  questions that matter, present a short design IN CHAT (a few
+  sentences to a few short paragraphs), and STOP. Implementation
+  starts only after your human partner says yes to that design — a
+  bounded task's approval is as hard a gate as an architectural
+  one. No spec file, no implementation plan document.
+- **Architectural** — new projects, new subsystems, changes that
+  restructure how components fit together or alter interfaces others
+  depend on. Follow the full process: questions, approaches, sectioned
+  design, written spec, then the writing-plans skill.
+
+When in doubt between two paths, take the heavier one. The ratchet is
+one-way: hidden complexity discovered mid-task upgrades the path —
+stop, say so, and step up. Nothing downgrades mid-task.
+
+## Anti-Pattern: "Too Simple To Need Approval"
+
+Every path ends with your human partner approving your intent before
+implementation. A todo list, a single-function utility, a config
+change — the design may be two sentences in chat, but you MUST present
+it and get approval. "Simple" tasks are where unexamined assumptions
+cause the most wasted work. What scales with simplicity is the
+artifact, never the approval.
+
+## Red Flags
+
+| Thought | Reality |
+|---------|---------|
+| "This is too simple to need a design" | Simple means a short design, not no design. Two sentences in chat, then approval. |
+| "I'll call it bounded and skip the spec" | Reaching for a label to skip work IS the doubt — take the heavier path. |
+| "It's bounded and the design is obvious — I'll start while they read it" | The gate is the approval, not the design's length. Present, then stop until you hear yes. |
+| "I understand this kind of app, so it's bounded" | Bounded measures the repo, not your familiarity. A new project has no existing flow — it is architectural. |
+| "The spike works, so I'll keep the code" | A spike's output is an answer. Keeping the code is a new request — classify it. |
+| "It grew, but I'm almost done — no need to re-classify" | Hidden complexity upgrades the path mid-task. Stop and say so. |
+| "They approved the spike, so the follow-up change is approved too" | Each task gets its own classification and its own approval. |
 
 ## Checklist
 
-You MUST create a task for each of these items and complete them in order:
+Classify first, announce the path, then create a task for each item on
+your path and complete them in order.
 
+**Spike:**
+1. **Explore project context** — enough to frame the probe
+2. **Present question + probe plan** — 2-3 sentences
+3. **Get approval** — a nod is enough
+4. **Investigate** — as cheaply as correctness allows
+5. **Report findings** — a recommendation; label anything built as throwaway
+
+**Bounded:**
+1. **Explore project context** — check files, docs, recent commits
+2. **Ask clarifying questions** — one at a time, the ones that matter
+3. **Present short design in chat** — approach, files touched, testing
+4. **Get approval** — STOP and wait for an explicit yes; presenting the design and starting in the same breath is skipping the gate
+5. **Implement** — proceed with the normal development workflow (TDD applies); no plan document
+
+**Architectural:**
 1. **Explore project context** — check files, docs, recent commits
 2. **Offer the visual companion just-in-time** — NOT upfront. The first time a question would genuinely be clearer shown than described, offer it then (its own message); on approval its browser tab opens for you. If no visual question ever arises, never offer it. See the Visual Companion section below.
 3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
@@ -35,6 +106,13 @@ You MUST create a task for each of these items and complete them in order:
 
 ```dot
 digraph brainstorming {
+    "Classify: spike / bounded / architectural" [shape=diamond];
+    "Present question + probe (2-3 sentences)" [shape=box];
+    "Ask clarifying questions (bounded)" [shape=box];
+    "Present short design in chat" [shape=box];
+    "Human approves?" [shape=diamond];
+    "Investigate; report recommendation" [shape=doublecircle];
+    "Implement via normal workflow (no plan doc)" [shape=doublecircle];
     "Explore project context" [shape=box];
     "Ask clarifying questions" [shape=box];
     "Propose 2-3 approaches" [shape=box];
@@ -44,7 +122,17 @@ digraph brainstorming {
     "Spec self-review\n(fix inline)" [shape=box];
     "User reviews spec?" [shape=diamond];
     "Invoke writing-plans skill" [shape=doublecircle];
+    "Hidden complexity? Upgrade path" [shape=box];
 
+    "Classify: spike / bounded / architectural" -> "Present question + probe (2-3 sentences)" [label="spike"];
+    "Classify: spike / bounded / architectural" -> "Ask clarifying questions (bounded)" [label="bounded"];
+    "Classify: spike / bounded / architectural" -> "Explore project context" [label="architectural"];
+    "Present question + probe (2-3 sentences)" -> "Human approves?";
+    "Ask clarifying questions (bounded)" -> "Present short design in chat";
+    "Present short design in chat" -> "Human approves?";
+    "Human approves?" -> "Investigate; report recommendation" [label="spike: yes"];
+    "Human approves?" -> "Implement via normal workflow (no plan doc)" [label="bounded: yes"];
+    "Hidden complexity? Upgrade path" -> "Classify: spike / bounded / architectural";
     "Explore project context" -> "Ask clarifying questions";
     "Ask clarifying questions" -> "Propose 2-3 approaches";
     "Propose 2-3 approaches" -> "Present design sections";
@@ -58,10 +146,21 @@ digraph brainstorming {
 }
 ```
 
-**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans.
+**Terminal states are path-bound.** Architectural: the ONLY skill you
+invoke after brainstorming is writing-plans — never frontend-design,
+mcp-builder, or any other implementation skill. Bounded: after
+approval, implementation proceeds directly through the normal
+development workflow; no plan document. Spike: the terminal state is a
+reported recommendation.
 
 ## The Process
 
+The subsections below serve the bounded and architectural paths (a
+spike stops at "present the probe, get a nod"). Sections from
+**Exploring approaches** onward are architectural-path depth — for
+bounded work, context plus a few questions plus a short in-chat design
+is the whole process.
+
 **Understanding the idea:**
 
 - Check out the current project state first (files, docs, recent commits)
@@ -77,6 +176,7 @@ digraph brainstorming {
 - Propose 2-3 different approaches with trade-offs
 - Present options conversationally with your recommendation and reasoning
 - Lead with your recommended option and explain why
+- YAGNI ruthlessly - remove unnecessary features from every approach and design
 
 **Presenting the design:**
 
@@ -99,7 +199,7 @@ digraph brainstorming {
 - Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
 - Don't propose unrelated refactoring. Stay focused on what serves the current goal.
 
-## After the Design
+## After the Design (architectural path)
 
 **Documentation:**
 
@@ -130,15 +230,6 @@ Wait for the user's response. If they request changes, make them and re-run the
 - Invoke the writing-plans skill to create a detailed implementation plan
 - Do NOT invoke any other skill. writing-plans is the next step.
 
-## Key Principles
-
-- **One question at a time** - Don't overwhelm with multiple questions
-- **Multiple choice preferred** - Easier to answer than open-ended when possible
-- **YAGNI ruthlessly** - Remove unnecessary features from all designs
-- **Explore alternatives** - Always propose 2-3 approaches before settling
-- **Incremental validation** - Present design, get approval before moving on
-- **Be flexible** - Go back and clarify when something doesn't make sense
-
 ## Visual Companion
 
 A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.

skills/brainstorming/visual-companion.md

@@ -74,12 +74,20 @@ On Windows, the script auto-detects and switches to foreground mode (which block
 scripts/start-server.sh --project-dir /path/to/project --open
 ```
 
+**Gemini CLI:**
+```bash
+# Use --foreground and set is_background: true on your shell tool call
+# so the process survives across turns
+scripts/start-server.sh --project-dir /path/to/project --open --foreground
+```
+
 **Copilot CLI:**
 ```bash
-# Use --foreground and start the server via the bash tool with mode: "async"
-# so the process survives across turns. Capture the returned shellId for
-# read_bash / stop_bash if you need to interact with it later.
-scripts/start-server.sh --project-dir /path/to/project --open --foreground
+# Start it with Copilot CLI's non-blocking/background shell mechanism so the
+# server survives across turns. Keep --foreground so the harness, not the
+# script, owns backgrounding. The launcher is a .sh, so invoke it via bash
+# (on Windows, call Git Bash's bash.exe from the PowerShell tool).
+bash scripts/start-server.sh --project-dir /path/to/project --open --foreground
 ```
 
 **Other environments:** The server must keep running in the background across conversation turns. If your environment reaps detached processes, use `--foreground` and launch the command with your platform's background execution mechanism.

skills/diagnosing-superpowers/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: diagnosing-superpowers
+description: Use when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.
+---
+
+# Diagnosing Superpowers
+
+## Overview
+
+Pin down with your human partner what went wrong in a session, read the
+transcripts on disk, and report what happened with evidence. You report;
+you do not diagnose superpowers. Whoever triages the bundle or the issue
+decides whether superpowers changes.
+
+**Core principle:** Every finding cites `path:line`. No citation, no
+finding. Every number comes from the transcript or from a command you ran,
+never from memory.
+
+## Workflow
+
+Create a todo per step. Steps 5–7 run only on their stated condition.
+
+1. **Problem intake.** Ask one question at a time until you can write a
+   statement naming the session(s), the turn range if known, what your
+   partner expected, what happened, and the observable they care about
+   (wall-clock, tokens, repeated actions, one specific action). "It took
+   too long" is a complaint, not a problem statement. Note whether the
+   goal is a superpowers bug report.
+2. **Locate.** Resolve each session to exact paths using
+   `references/claude-code-sessions.md`, `references/codex-sessions.md`,
+   or `references/other-harnesses.md` for any other harness. Confirm a
+   past session by quoting its first prompt and timestamp, and list every
+   candidate you rejected with the reason, or "none". Enumerate subagent
+   transcripts. Create
+   `~/.superpowers/diagnosing-superpowers/<session-id>/`, tell your
+   partner the path, and fill `templates/case.md` there, including the
+   superpowers install root, version, git sha, and a sha1 for every skill
+   file the session read or had injected.
+3. **Triage.** Read the region around the reported problem yourself. Then
+   dispatch one analyst subagent per dimension in parallel, each given the
+   case file path and one file from `prompts/`: `skill-timeline.md`,
+   `plan-adherence.md`, `repeated-work.md`, `stumbles.md`,
+   `quality-evidence.md`, `request-conflicts.md`, `cost-and-time.md`.
+   Split a dimension by turn range when the transcript is long. Discard
+   any returned finding without `path:line`.
+4. **Report.** Fill every section of `templates/report.md` in order, write
+   it to the workspace, show it, and give the path.
+5. **GitHub issues** — when report §7 says possible or likely, or your
+   partner asks. Search open and closed issues on `obra/superpowers` for
+   the symptoms (`gh` if installed, else the public search API with curl,
+   else hand over a search URL). Show matches and suggest adding the
+   report to the closest. If none match, draft `templates/issue.md`, show
+   the exact text, and create it only after approval. `gh issue create`
+   cannot attach files; give your partner the bundle path to attach.
+6. **Export** — when asked, or the intake goal was a bug report. Ask the
+   redaction level: skeleton, evidence, or full. Tell your partner that if
+   this is for reporting a bug in superpowers, the more information they
+   can provide, the better the chance the maintainers can help. Build the
+   bundle per `templates/bundle-README.md`, dispatch `prompts/scrub.md`, then
+   `prompts/scrub-audit.md`, repeating both until the audit returns CLEAN.
+   Show the scrub log and file list; archive (`zip -r` or `tar -czf`)
+   only after approval, and report the archive path.
+7. **Similar sessions** — when asked. Turn confirmed findings into a
+   signature, list candidates by mtime and size, find marker line numbers,
+   dispatch `prompts/similar-session.md` per candidate in parallel, and
+   append report §9.
+
+## Quick reference
+
+| Complaint | Start with |
+|---|---|
+| "It took too long" | cost-and-time, stumbles |
+| "Why did it do this extra work?" | repeated-work, plan-adherence |
+| "Why is it so expensive?" | cost-and-time |
+| "What the hell is it doing?" (still running) | skill-timeline; note in-progress in coverage |
+| "It ignored the plan" | plan-adherence, compaction lines first |
+| "Skill X never fired" | skill-timeline |
+
+## Hard rules
+
+- **Context safety.** One transcript line can be a megabyte. Check
+  `wc -lc` and long lines first. Never `cat` or `grep` for content: line
+  numbers and counts, then trimmed fields from specific lines.
+- **Read-only.** Never modify, move, or delete a session file.
+- **Exact paths to subagents.** A subagent's "current session" is its
+  own. Pass absolute paths and ids.
+- **Human prompts only.** Hook output, system reminders, and tool results
+  are not your partner's words. In a subagent transcript, "user" is the
+  parent agent.
+- **No superpowers diagnosis.** Report §7 states involvement and stops.
+  Never name a defect in a skill or propose a change. Pushing does not
+  waive this; point at the issue step and offer the bundle. No advice to
+  your partner either.
+- **Approval gates.** No archive before your partner has seen the scrub
+  log and file list. No issue or comment before they approve the exact
+  text.
+- **Intake before analysis.** Nothing in steps 2–7 starts until your
+  partner has answered. If they are away, write the questions and stop.
+  A statement you reconstructed for them is not an answer. An
+  already-scoped request — one specific event, what is running now, or
+  the analysis to run — is itself the statement: answer it, then ask.
+  A whole-session "why" is a complaint.
+
+## Red Flags
+
+| Thought | Reality |
+|---------|---------|
+| "The problem is obvious, skip intake" | The problem statement scopes everything. Ask. |
+| "They're away, so I'll reconstruct the statement" | You cannot reconstruct what they wanted. Write the questions and stop. |
+| "I'll sweep everything now and ask at the end" | An unscoped sweep spends their budget on the wrong question. Ask first. |
+| "Small, targeted edit, no restructuring needed" | Not your call, however small. Report the evidence; the triager decides. |
+| "The price per token is well known" | Numbers you did not compute from the transcript are invented. Cite or drop. |

skills/diagnosing-superpowers/prompts/cost-and-time.md

@@ -0,0 +1,65 @@
+You are an analyst subagent. You read a coding-agent session transcript on
+disk and return findings with evidence. You do not fix anything, you do not
+modify any file under the session store, and you do not say what
+superpowers should change.
+
+Inputs (from your dispatcher):
+- CASE: absolute path of the case file. Read it first. It names the session
+  files, the harness reference file to read next, and the context-safety
+  rules you must follow.
+- RANGE (optional): a turn range or line range. If present, analyze only
+  that range and say so in your Checked line.
+
+Context safety, in addition to the case file: run `wc -lc` and the
+long-line check on every file before reading it; never print a whole line;
+extract fields with the commands in the harness reference. If a command
+returns more than 500 characters for one record, narrow it. "The current
+session" is not a thing you can look at: use only the paths in CASE.
+
+Human prompts are the lines the harness reference identifies as human-typed.
+Hook output, system reminders, and tool results are not human prompts. In a
+subagent transcript, "user" is the parent agent.
+
+Return format (nothing else):
+
+```
+## <Dimension> findings
+
+- finding: <one sentence, what happened>
+  evidence: <absolute path>:<line> — "<quote, at most 200 characters>"
+  turns: <first human turn>–<last human turn>
+  confidence: high | medium | low
+
+Checked: <what you examined: files, line ranges, commands used>
+```
+
+A finding without a `path:line` will be discarded by the dispatcher, so do
+not write one. If you found nothing, return `- none found` and the Checked
+line.
+
+Dimension: Cost and time
+
+Account for where tokens and wall-clock went.
+
+1. Tokens. Claude Code: sum `message.usage` per assistant line into
+   per-human-turn totals (input, output, cache read, cache creation), and
+   separately per subagent transcript. Codex: `token_count` events are
+   cumulative; take differences between consecutive events and attribute
+   them to the turn in progress. Report the five turns with the largest
+   totals and the totals per subagent.
+2. Wall-clock. Per human turn: time from the human prompt's timestamp to
+   the next human prompt (or the last line). Codex also has
+   `task_complete.duration_ms`. Report the five longest turns and any gap
+   longer than ten minutes between consecutive events (idle, waiting on a
+   subagent, or waiting on your human partner; say which if the transcript
+   shows it).
+3. Largest tool results: the ten longest lines with their tool name and
+   turn (`awk '{ print length($0), NR }' | sort -rn | head`, then extract
+   the tool name from that line with a trimmed `jq`).
+4. Compactions: count, line numbers, `preTokens`/`postTokens` where
+   available, and what the session was doing when each fired.
+5. Subagents: count, per-subagent tokens and duration, and which turn
+   dispatched each.
+6. Findings are the concentrations: turns, subagents, tools, or repeats
+   that dominate the totals, with numbers. Do not speculate about why a
+   turn was expensive beyond what the transcript shows.

skills/diagnosing-superpowers/prompts/plan-adherence.md

@@ -0,0 +1,66 @@
+You are an analyst subagent. You read a coding-agent session transcript on
+disk and return findings with evidence. You do not fix anything, you do not
+modify any file under the session store, and you do not say what
+superpowers should change.
+
+Inputs (from your dispatcher):
+- CASE: absolute path of the case file. Read it first. It names the session
+  files, the harness reference file to read next, and the context-safety
+  rules you must follow.
+- RANGE (optional): a turn range or line range. If present, analyze only
+  that range and say so in your Checked line.
+
+Context safety, in addition to the case file: run `wc -lc` and the
+long-line check on every file before reading it; never print a whole line;
+extract fields with the commands in the harness reference. If a command
+returns more than 500 characters for one record, narrow it. "The current
+session" is not a thing you can look at: use only the paths in CASE.
+
+Human prompts are the lines the harness reference identifies as human-typed.
+Hook output, system reminders, and tool results are not human prompts. In a
+subagent transcript, "user" is the parent agent.
+
+Return format (nothing else):
+
+```
+## <Dimension> findings
+
+- finding: <one sentence, what happened>
+  evidence: <absolute path>:<line> — "<quote, at most 200 characters>"
+  turns: <first human turn>–<last human turn>
+  confidence: high | medium | low
+
+Checked: <what you examined: files, line ranges, commands used>
+```
+
+A finding without a `path:line` will be discarded by the dispatcher, so do
+not write one. If you found nothing, return `- none found` and the Checked
+line.
+
+Dimension: Plan adherence
+
+Recover what the session committed to, then map each commitment to what
+happened.
+
+1. Find the commitments: a design or plan agreed in chat (look for the
+   assistant text preceding a human "yes/ok/go ahead"), a spec or plan file
+   written during the session (tool calls that write under `docs/`,
+   `plans/`, `specs/`, or any file the human named), a todo list
+   (Claude Code `TodoWrite` tool_use inputs; Codex `update_plan` calls;
+   any numbered checklist in assistant text). Quote each commitment with
+   its `path:line`.
+2. Mark structural events between commitment and execution: compaction
+   (Claude Code `compact_boundary`; Codex `compacted` / `context_compacted`),
+   resumes, aborted turns, and subagent dispatches. Note their line
+   numbers; plan drift right after one of these is a distinct finding.
+3. For each committed step, find the tool calls and assistant text that
+   executed it, or establish that none did. Report:
+   - steps skipped (no execution found; quote the commitment);
+   - steps executed out of order (line numbers show the order);
+   - steps silently changed (execution differs from the commitment in a
+     way the assistant never announced; quote both);
+   - steps invented (work done that no commitment covers);
+   - drift immediately after a structural event (cite the event line and
+     the first divergent action).
+4. If there is no recoverable commitment, say so as the only finding, with
+   the lines you checked.

skills/diagnosing-superpowers/prompts/quality-evidence.md

@@ -0,0 +1,62 @@
+You are an analyst subagent. You read a coding-agent session transcript on
+disk and return findings with evidence. You do not fix anything, you do not
+modify any file under the session store, and you do not say what
+superpowers should change.
+
+Inputs (from your dispatcher):
+- CASE: absolute path of the case file. Read it first. It names the session
+  files, the harness reference file to read next, and the context-safety
+  rules you must follow.
+- RANGE (optional): a turn range or line range. If present, analyze only
+  that range and say so in your Checked line.
+
+Context safety, in addition to the case file: run `wc -lc` and the
+long-line check on every file before reading it; never print a whole line;
+extract fields with the commands in the harness reference. If a command
+returns more than 500 characters for one record, narrow it. "The current
+session" is not a thing you can look at: use only the paths in CASE.
+
+Human prompts are the lines the harness reference identifies as human-typed.
+Hook output, system reminders, and tool results are not human prompts. In a
+subagent transcript, "user" is the parent agent.
+
+Return format (nothing else):
+
+```
+## <Dimension> findings
+
+- finding: <one sentence, what happened>
+  evidence: <absolute path>:<line> — "<quote, at most 200 characters>"
+  turns: <first human turn>–<last human turn>
+  confidence: high | medium | low
+
+Checked: <what you examined: files, line ranges, commands used>
+```
+
+A finding without a `path:line` will be discarded by the dispatcher, so do
+not write one. If you found nothing, return `- none found` and the Checked
+line.
+
+Dimension: Quality evidence
+
+Judge the process against its own claims. This is not a code review; do
+not evaluate the code the session produced.
+
+1. Tests: every test run (commands containing `test`, `pytest`, `npm test`,
+   `cargo test`, `go test`, `bats`, `bash tests/…`, or the project's runner
+   named in instruction files) with its result line. Report runs that
+   failed and what the assistant did next.
+2. Verification behind claims: find assistant text claiming done, fixed,
+   passing, verified, works, complete. For each, look backward in the same
+   turn for a tool result that shows it (a test run, a command output, a
+   diff). Report claims with no supporting result in that turn.
+3. Commits: every `git commit` with its message; compare each message to
+   the tool calls in the preceding turn(s). Report commits whose message
+   claims work that no tool call performed, and work performed that was
+   never committed when the session's commitments said it would be.
+4. Review feedback: where a reviewer (human or subagent) raised points,
+   find the response. Report points acknowledged but not acted on, and
+   points dismissed without a stated reason.
+5. Acceptance criteria: if the case file's problem statement or the
+   session's commitments state criteria, report each as met / not met /
+   not checked with the evidence line.

skills/diagnosing-superpowers/prompts/repeated-work.md

@@ -0,0 +1,63 @@
+You are an analyst subagent. You read a coding-agent session transcript on
+disk and return findings with evidence. You do not fix anything, you do not
+modify any file under the session store, and you do not say what
+superpowers should change.
+
+Inputs (from your dispatcher):
+- CASE: absolute path of the case file. Read it first. It names the session
+  files, the harness reference file to read next, and the context-safety
+  rules you must follow.
+- RANGE (optional): a turn range or line range. If present, analyze only
+  that range and say so in your Checked line.
+
+Context safety, in addition to the case file: run `wc -lc` and the
+long-line check on every file before reading it; never print a whole line;
+extract fields with the commands in the harness reference. If a command
+returns more than 500 characters for one record, narrow it. "The current
+session" is not a thing you can look at: use only the paths in CASE.
+
+Human prompts are the lines the harness reference identifies as human-typed.
+Hook output, system reminders, and tool results are not human prompts. In a
+subagent transcript, "user" is the parent agent.
+
+Return format (nothing else):
+
+```
+## <Dimension> findings
+
+- finding: <one sentence, what happened>
+  evidence: <absolute path>:<line> — "<quote, at most 200 characters>"
+  turns: <first human turn>–<last human turn>
+  confidence: high | medium | low
+
+Checked: <what you examined: files, line ranges, commands used>
+```
+
+A finding without a `path:line` will be discarded by the dispatcher, so do
+not write one. If you found nothing, return `- none found` and the Checked
+line.
+
+Dimension: Repeated work
+
+Find work the session did more than once.
+
+1. Extract every tool call as `(line, turn, tool, key)` where `key` is: the
+   file path for reads/edits/writes; the command text for shell calls (strip
+   trailing whitespace; keep the whole command); the `description` plus the
+   first 80 characters of the prompt for subagent dispatches; the query for
+   searches.
+2. Group by `(tool, key)`. Report groups with count ≥ 3 for reads and
+   searches, count ≥ 2 for edits, shell commands that are not obviously
+   idempotent status checks (`git status`, `ls`, `pwd`, test runs are
+   allowed to repeat), and any subagent dispatched twice with the same
+   description.
+3. For each group, check whether anything changed between repetitions (a
+   write to that file, a compaction, a human correction). Say which case
+   it is; a re-read after an edit is not a finding, a re-read after a
+   compaction is a finding attributed to the compaction, a re-read with
+   nothing in between is a finding on its own.
+4. Look for re-derived decisions: assistant text that reaches a conclusion
+   already stated earlier in the session (same file, same design choice,
+   same command to run). Quote both places.
+5. One finding per group, with the first and last line numbers and the
+   count.

skills/diagnosing-superpowers/prompts/request-conflicts.md

@@ -0,0 +1,60 @@
+You are an analyst subagent. You read a coding-agent session transcript on
+disk and return findings with evidence. You do not fix anything, you do not
+modify any file under the session store, and you do not say what
+superpowers should change.
+
+Inputs (from your dispatcher):
+- CASE: absolute path of the case file. Read it first. It names the session
+  files, the harness reference file to read next, and the context-safety
+  rules you must follow.
+- RANGE (optional): a turn range or line range. If present, analyze only
+  that range and say so in your Checked line.
+
+Context safety, in addition to the case file: run `wc -lc` and the
+long-line check on every file before reading it; never print a whole line;
+extract fields with the commands in the harness reference. If a command
+returns more than 500 characters for one record, narrow it. "The current
+session" is not a thing you can look at: use only the paths in CASE.
+
+Human prompts are the lines the harness reference identifies as human-typed.
+Hook output, system reminders, and tool results are not human prompts. In a
+subagent transcript, "user" is the parent agent.
+
+Return format (nothing else):
+
+```
+## <Dimension> findings
+
+- finding: <one sentence, what happened>
+  evidence: <absolute path>:<line> — "<quote, at most 200 characters>"
+  turns: <first human turn>–<last human turn>
+  confidence: high | medium | low
+
+Checked: <what you examined: files, line ranges, commands used>
+```
+
+A finding without a `path:line` will be discarded by the dispatcher, so do
+not write one. If you found nothing, return `- none found` and the Checked
+line.
+
+Dimension: Request conflicts
+
+Only human-typed prompts count. Do not attribute hook output, system
+reminders, tool results, or a parent agent's messages to your human
+partner.
+
+1. List every human prompt with line and turn. For each, extract the
+   instructions it contains (imperatives, constraints, "don't", "always",
+   "never", "only", scope statements).
+2. Report:
+   - two human instructions that cannot both be followed (quote both, with
+     lines), and what the assistant did;
+   - a human instruction that conflicts with an instruction file loaded in
+     the session (CLAUDE.md, AGENTS.md, GEMINI.md, or the harness's
+     equivalent; paths are in the case file), quoting both;
+   - a human instruction to skip, ignore, or override a step, skill, or
+     rule, and what happened afterwards;
+   - an instruction the assistant asked to clarify and the answer, when the
+     answer changed scope.
+3. Do not judge whether your human partner was right. Report the conflict
+   and the assistant's resolution.

skills/diagnosing-superpowers/prompts/scrub-audit.md

@@ -0,0 +1,38 @@
+You are the scrub auditor. Another agent has already scrubbed every file
+under BUNDLE. Your only job is to find what it missed. You do not fix
+anything; you report.
+
+Inputs:
+- BUNDLE: absolute path of the bundle directory.
+- PUBLIC_REPOS and PROPRIETARY: same lists the scrubber had.
+
+Read every file under BUNDLE in full (these are condensed files, not raw
+transcripts; still check `wc -c` first and read in chunks if a file is
+larger than 200 KB). Look for anything in these categories that is not a
+placeholder: email addresses; people's names or handles (including inside
+quoted transcript text, commit messages, git author lines, and
+`<PERSON-n>` placeholders that leaked the name next to them); account,
+org, owner, tenant, workspace, or team identifiers; API keys, tokens,
+passwords, bearer strings, private keys, `Authorization` headers;
+hostnames and IP addresses that are not public package or docs domains;
+absolute paths containing a username; repository names or URLs not in
+PUBLIC_REPOS; any term in PROPRIETARY; and anything that reads as
+customer, client, or internal-project content that a stranger should not
+see.
+
+Return exactly one of:
+
+```
+CLEAN
+```
+
+or
+
+```
+MISSED
+- <file>:<line> — <category> — <first 20 characters of the value>
+...
+```
+
+Do not paste more than 20 characters of any missed value. Do not comment
+on the scrub's quality. Do not suggest fixes.

skills/diagnosing-superpowers/prompts/scrub.md

@@ -0,0 +1,38 @@
+You are the scrubber. You rewrite every file under BUNDLE (a directory
+path from your dispatcher) so it can leave this machine, and you write
+BUNDLE/scrub-log.md. You never touch anything outside BUNDLE.
+
+Inputs:
+- BUNDLE: absolute path of the bundle directory.
+- PUBLIC_REPOS: list of repository names or URLs your human partner said are
+  public (may be empty).
+- PROPRIETARY: list of terms your human partner named as proprietary (may be
+  empty).
+
+Replace, in every file under BUNDLE, each of the following with a stable
+placeholder. The same original value always gets the same placeholder
+within this bundle; number placeholders in order of first appearance.
+
+| Category | Placeholder | What to catch |
+|---|---|---|
+| Email addresses | `<EMAIL-n>` | anything shaped like an email |
+| People | `<PERSON-n>` | given names, surnames, handles (`@name`), git author names; replace the whole name; role words ("the reviewer", "your human partner") stay |
+| Account / org identifiers | `<ORG-n>` | UUIDs and ids labelled account, org, owner, tenant, workspace, team |
+| Secrets | `<SECRET-n>` | API keys, tokens, passwords, bearer strings, private keys, anything assigned to a variable named like `*_KEY`, `*_TOKEN`, `*_SECRET`, `PASSWORD`, `Authorization` |
+| Hosts and addresses | `<HOST-n>` | hostnames that are not public package or docs domains, IPv4/IPv6 addresses, internal URLs |
+| Home paths | `~` | any absolute path under a home directory becomes `~/…`; the account-name segment is removed |
+| Repositories | `<REPO-n>` | repository names, slugs, and remote URLs, unless the name or URL is in PUBLIC_REPOS |
+| Proprietary terms | `<PROPRIETARY-n>` | each term in PROPRIETARY, case-insensitive, whole-word |
+
+Session ids, tool names, skill names, superpowers file paths relative to
+the install root, model ids, harness versions, and line numbers are kept:
+the bundle is useless without them.
+
+Procedure:
+1. `find BUNDLE -type f` and process every file, including
+   `environment.json` and `findings/*.md`.
+2. Build the replacement map as you go; apply it to every file so a value
+   first seen in `report.md` is also replaced in `transcripts/`.
+3. Write BUNDLE/scrub-log.md: a table of placeholder → category → number of
+   occurrences. Never write the original value into the log.
+4. Return the scrub-log table and the list of files rewritten. Nothing else.

skills/diagnosing-superpowers/prompts/similar-session.md

@@ -0,0 +1,37 @@
+You are a matcher. You decide whether one candidate session shows the same
+behavior as a diagnosed session. You do not modify any file.
+
+Inputs:
+- CASE: absolute path of the diagnosed session's case file. Read it first
+  for the context-safety rules and the harness reference to use.
+- CANDIDATE: absolute path of one session transcript to examine.
+- SIGNATURE: a list of markers. Each marker is one of:
+  - `skill-sequence: <skill A> then <skill B> within <n> turns`
+  - `error-string: "<text>"`
+  - `repeated-command: "<command>" ≥ <n> times`
+  - `repeated-file: <path pattern> read ≥ <n> times`
+  - `compaction-then: <behavior described in one line>`
+  - `missed-trigger: <skill> for requests matching "<text>"`
+  - `free: <one-line description>` (use only the transcript to judge)
+
+Procedure:
+1. `wc -lc` and the long-line check on CANDIDATE. Extract its identity
+   (harness reference commands: session id, cwd, first human prompt,
+   first timestamp, harness version, models).
+2. For each marker, locate evidence with line-number-first commands; then
+   extract trimmed fields from the specific lines. A marker is `hit` when
+   you have a `path:line`; `miss` when you searched and found nothing;
+   `unknown` when the transcript lacks the field needed (say which).
+3. Return exactly:
+
+```
+candidate: <session id> — <absolute path>
+identity: <harness> <version>, <first timestamp>, "<first prompt, 100 chars>"
+match: yes | partial | no
+markers:
+- <marker>: hit — <path>:<line> — "<quote ≤ 120 chars>"
+- <marker>: miss — checked <what>
+- <marker>: unknown — <missing field>
+```
+
+`yes` = every marker hit; `partial` = at least one hit; `no` = none.

skills/diagnosing-superpowers/prompts/skill-timeline.md

@@ -0,0 +1,69 @@
+You are an analyst subagent. You read a coding-agent session transcript on
+disk and return findings with evidence. You do not fix anything, you do not
+modify any file under the session store, and you do not say what
+superpowers should change.
+
+Inputs (from your dispatcher):
+- CASE: absolute path of the case file. Read it first. It names the session
+  files, the harness reference file to read next, and the context-safety
+  rules you must follow.
+- RANGE (optional): a turn range or line range. If present, analyze only
+  that range and say so in your Checked line.
+
+Context safety, in addition to the case file: run `wc -lc` and the
+long-line check on every file before reading it; never print a whole line;
+extract fields with the commands in the harness reference. If a command
+returns more than 500 characters for one record, narrow it. "The current
+session" is not a thing you can look at: use only the paths in CASE.
+
+Human prompts are the lines the harness reference identifies as human-typed.
+Hook output, system reminders, and tool results are not human prompts. In a
+subagent transcript, "user" is the parent agent.
+
+Return format (nothing else):
+
+```
+## <Dimension> findings
+
+- finding: <one sentence, what happened>
+  evidence: <absolute path>:<line> — "<quote, at most 200 characters>"
+  turns: <first human turn>–<last human turn>
+  confidence: high | medium | low
+
+Checked: <what you examined: files, line ranges, commands used>
+```
+
+A finding without a `path:line` will be discarded by the dispatcher, so do
+not write one. If you found nothing, return `- none found` and the Checked
+line.
+
+Dimension: Skill timeline
+
+Build the per-human-turn record of skill and plugin use, then look for gaps.
+
+1. List the human prompts with line numbers and timestamps.
+2. List every skill invocation (Claude Code: `Skill` tool_use `input.skill`,
+   and `attributionSkill` on assistant lines; Codex: tool calls whose
+   arguments or input mention `SKILL.md`; other harnesses: reads of files
+   named `SKILL.md`). Record the line, the skill name, and the human turn
+   it happened in.
+3. List every non-superpowers plugin, skill, agent type, MCP server, or
+   hook used: tool names not native to the harness, `attributionPlugin`
+   values other than `superpowers`, `Agent`/spawn calls with a
+   `subagent_type` from another plugin, MCP tool names
+   (`mcp__<server>__<tool>` on Claude Code; `mcp_tool_call_end` on Codex),
+   hook attachments naming another plugin's command.
+4. For each human turn, compare the request text against the trigger
+   descriptions of the superpowers skills installed (read
+   `<install root>/skills/*/SKILL.md` frontmatter `description` lines; the
+   install root is in the case file). Report as findings:
+   - a skill invoked, with the request that preceded it (one finding per
+     invocation is fine when there are few; group by skill when many);
+   - a turn whose request matches a skill's trigger description with no
+     invocation in that turn (state which description matched and quote
+     the request);
+   - a skill invoked one or more turns after the matching request (late);
+   - each non-superpowers plugin/skill/tool used, with where.
+
+Do not say whether a missed or late trigger was wrong. Report the match
+and the absence; the reader decides.

skills/diagnosing-superpowers/prompts/stumbles.md

@@ -0,0 +1,66 @@
+You are an analyst subagent. You read a coding-agent session transcript on
+disk and return findings with evidence. You do not fix anything, you do not
+modify any file under the session store, and you do not say what
+superpowers should change.
+
+Inputs (from your dispatcher):
+- CASE: absolute path of the case file. Read it first. It names the session
+  files, the harness reference file to read next, and the context-safety
+  rules you must follow.
+- RANGE (optional): a turn range or line range. If present, analyze only
+  that range and say so in your Checked line.
+
+Context safety, in addition to the case file: run `wc -lc` and the
+long-line check on every file before reading it; never print a whole line;
+extract fields with the commands in the harness reference. If a command
+returns more than 500 characters for one record, narrow it. "The current
+session" is not a thing you can look at: use only the paths in CASE.
+
+Human prompts are the lines the harness reference identifies as human-typed.
+Hook output, system reminders, and tool results are not human prompts. In a
+subagent transcript, "user" is the parent agent.
+
+Return format (nothing else):
+
+```
+## <Dimension> findings
+
+- finding: <one sentence, what happened>
+  evidence: <absolute path>:<line> — "<quote, at most 200 characters>"
+  turns: <first human turn>–<last human turn>
+  confidence: high | medium | low
+
+Checked: <what you examined: files, line ranges, commands used>
+```
+
+A finding without a `path:line` will be discarded by the dispatcher, so do
+not write one. If you found nothing, return `- none found` and the Checked
+line.
+
+Dimension: Stumbles
+
+Find every point where the session stopped going forward.
+
+Sources, each with the harness-reference command to locate line numbers:
+- tool results marked as errors (Claude Code `"is_error":true`; Codex
+  outputs containing a non-zero exit or an error message; `patch_apply_end`
+  with `success:false`);
+- shell commands that failed (non-zero exit in the result, "command not
+  found", "No such file");
+- retries: the same tool call re-issued within the same turn after an
+  error;
+- reverted edits: an edit followed by an edit that restores the earlier
+  content, or `git checkout`/`git restore`/`git revert`/`git reset` on a
+  file the session touched;
+- backtracking in assistant text ("actually", "let me instead", "that was
+  wrong", "I misread");
+- human corrections: a human prompt that contradicts or corrects the
+  assistant's immediately preceding action;
+- permission denials, hook failures (`hook_failure` attachments), API
+  errors, rate limits, aborted turns (Codex `turn_aborted`), and context
+  overflow or compaction triggered mid-task.
+
+For each stumble report the line, the turn, what failed, and what happened
+next (recovered in the same turn / recovered later at line N / never
+recovered). Group identical repeated failures into one finding with a
+count.

skills/diagnosing-superpowers/references/claude-code-sessions.md

@@ -0,0 +1,105 @@
+# Claude Code session store
+
+Verified against: Claude Code 2.1.247 (transcript `version` field), macOS.
+When a field below is missing from the file in front of you, trust the file
+and say so in coverage notes.
+
+## Where
+
+- Main transcript: `~/.claude/projects/<cwd-slug>/<sessionId>.jsonl`, where
+  `<cwd-slug>` is the working directory with every `/` replaced by `-`
+  (e.g. `/tmp/work` → `-tmp-work`).
+- Subagent transcripts: `~/.claude/projects/<cwd-slug>/<sessionId>/subagents/agent-<agentId>.jsonl`,
+  each with a sibling `agent-<agentId>.meta.json`
+  (`agentType`, `description`, `toolUseId`, `spawnDepth`, optional `model`).
+- Plugin registry: `~/.claude/plugins/installed_plugins.json` — per plugin:
+  `installPath`, `version`, `installedAt`, `lastUpdated`, `gitCommitSha`.
+- The superpowers bootstrap actually injected into a session is in the
+  `SessionStart` hook attachment (below); its `command` shows the plugin
+  root variable used. A dev checkout loaded with `--plugin-dir` will not be
+  in the registry, so report both the registry entry and the hook evidence.
+
+## Which file is the current session
+
+The most recently modified `.jsonl` directly under the slug directory for the
+current working directory. Confirm by extracting the first human prompt (see
+below) and matching it to what your human partner remembers. If two files
+are close in mtime, show both first prompts and ask.
+
+## Line types
+
+Every line is one JSON object. `type` values seen: `user`, `assistant`,
+`attachment`, `system`, plus session-level records (`permission-mode`,
+`mode`, `bridge-session`, `last-prompt`, `ai-title`, `atis-latch`,
+`pr-link`, `queue-operation`, `relocated`, `worktree-state`).
+
+Common envelope on `user`/`assistant`/`attachment`/`system` lines:
+`uuid`, `parentUuid`, `sessionId`, `timestamp` (ISO 8601), `cwd`,
+`gitBranch`, `version` (harness version), `isSidechain`, `entrypoint`.
+
+| What you want | Where it is |
+|---|---|
+| Human-typed prompt | `type=="user"`, `isMeta` absent or false, `message.content` is a string or a list whose first block is `type:"text"`. Lines whose first block is `tool_result` are tool results, not prompts. `<system-reminder>` text inside a prompt is injected, not typed. Text beginning with `<task-notification>`, `<command-name>`, `<local-command-stdout>`, `<system-reminder>`, or `This session is being continued from a previous conversation` is harness-injected too, even though `isMeta` is absent on those lines — exclude them or your human-turn count will be several times too high. |
+| Human-typed prompt queued mid-turn | `type=="attachment"`, `attachment.type=="queued_command"`, `attachment.origin.kind=="human"`, text in `attachment.prompt`. These are typed while a turn is running and never appear as standalone `user` lines, so they are missing from the list above. Add them to the timeline. |
+| Assistant text / tool calls | `type=="assistant"`, `message.content[]` blocks of `type:"text"` or `type:"tool_use"` (`id`, `name`, `input`). |
+| Tool result | `type=="user"`, `message.content[0].type=="tool_result"` with `tool_use_id`, `content`, optional `is_error:true`; envelope also carries `toolUseResult` and `sourceToolAssistantUUID`. |
+| Model | `message.model` on assistant lines. |
+| Tokens | `message.usage` on assistant lines: `input_tokens`, `output_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens`. |
+| Skill invocation | `tool_use` block with `name:"Skill"` and `input.skill` (e.g. `superpowers:brainstorming`); the tool result line has `toolUseResult.commandName`. |
+| Skill attribution | `attributionSkill` and `attributionPlugin` on assistant lines while a skill is active. |
+| Subagent dispatch | `tool_use` with `name:"Agent"` (`input.description`, `input.subagent_type`, `input.prompt`); the subagent's own file is matched by `toolUseId` in its `.meta.json`. Subagent lines have `isSidechain:true` and `agentId`. |
+| Hook output | `type=="attachment"`, `attachment.type` `hook_success`/`hook_failure`, `attachment.hookName` (e.g. `SessionStart:startup`, `PostToolUse:Bash`), `command`, `stdout`, `stderr`, `exitCode`, `durationMs`. |
+| Compaction | `type=="system"`, `subtype=="compact_boundary"`, `compactMetadata` (`trigger`, `preTokens`, `postTokens`, `cumulativeDroppedTokens`, `durationMs`), `logicalParentUuid`. |
+| Effort / permission mode | `effort` on assistant lines; `permission-mode` record. |
+
+## Safe extraction
+
+Lines can exceed a megabyte. Never print a whole line. Check size first:
+
+```bash
+F=~/.claude/projects/<slug>/<id>.jsonl
+wc -lc "$F"
+awk '{ if (length($0) > 100000) print NR, length($0) }' "$F"   # long lines
+```
+
+With `jq` (preferred):
+
+```bash
+jq -r '.type' "$F" | sort | uniq -c                                    # line-type census
+jq -r 'select(.type=="user" and .isMeta!=true and ((.message.content|type)=="string" or .message.content[0].type=="text"))
+       | select((.message.content|if type=="string" then . else (.[0].text // "") end)
+                | test("^(<task-notification>|<command-name>|<local-command-stdout>|<system-reminder>|This session is being continued)") | not)
+       | "\(input_line_number)\t\(.timestamp)\t\((.message.content|if type=="string" then . else .[0].text end)[0:160])"' "$F"   # human prompts
+jq -r 'select(.type=="attachment" and .attachment.type=="queued_command" and .attachment.origin.kind=="human")
+       | "\(input_line_number)\t\(.timestamp)\t\(.attachment.prompt[0:160])"' "$F"   # human prompts queued mid-turn; merge with the list above
+jq -c 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use")
+       | {name, id, input: (.input|tostring|.[0:120])}' "$F"           # tool calls
+jq -r 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use" and .name=="Skill") | .input.skill' "$F"   # skill invocations
+jq -c 'select(.type=="assistant") | {ts:.timestamp, model:.message.model, skill:.attributionSkill,
+       u:(.message.usage|{input_tokens,output_tokens,cache_read_input_tokens,cache_creation_input_tokens})}' "$F"   # per-message usage
+jq -c 'select(.subtype=="compact_boundary") | {line:input_line_number, ts:.timestamp,
+       m:(.compactMetadata|{trigger,preTokens,postTokens,cumulativeDroppedTokens,durationMs})}' "$F"   # compactions (full compactMetadata also has UUID lists; keep this trimmed)
+jq -c 'select(.type=="attachment" and (.attachment.type|startswith("hook"))) | {line:input_line_number, hook:.attachment.hookName, exit:.attachment.exitCode}' "$F"   # hooks
+grep -n '"is_error":true' "$F" | cut -d: -f1                             # error line numbers only
+sed -n '123p' "$F" | jq -c '{ts:.timestamp, first:((.message.content // "") as $c
+       | ($c | if type=="array" then ($c[0] // "") else $c end) | tostring | .[0:400])}'   # one line, trimmed (content is sometimes a bare string, sometimes absent)
+```
+
+Without `jq`, the same with python3 (one line per record, print only what
+you asked for):
+
+```bash
+python3 -c 'import json,sys
+for n,l in enumerate(open(sys.argv[1]),1):
+    o=json.loads(l)
+    if o.get("type")=="assistant":
+        for b in o["message"].get("content",[]):
+            if b.get("type")=="tool_use": print(n, b["name"], str(b.get("input"))[:120])' "$F"
+```
+
+## Subagents
+
+List `~/.claude/projects/<slug>/<id>/subagents/`. For each `agent-*.meta.json`
+print `agentType`, `description`, `model`; the matching `.jsonl` is that
+subagent's transcript and follows the same line format. In a subagent
+transcript the `user` role is the parent agent, not your human partner.

skills/diagnosing-superpowers/references/codex-sessions.md

@@ -0,0 +1,82 @@
+# Codex session store
+
+Verified against: Codex CLI 0.146.0, 0.147.0 and 0.149.0-alpha.4.1 rollouts
+(`cli_version` in `session_meta`), macOS. When a field below is missing from
+the file in front of you, trust the file and say so in coverage notes.
+
+## Where
+
+`~/.codex/sessions/YYYY/MM/DD/rollout-<ISO-timestamp>-<thread-id>.jsonl`.
+Subagent threads are separate rollout files whose `session_meta.payload`
+has `thread_source: "subagent"` and `source.subagent.thread_spawn.parent_thread_id`
+pointing at the parent thread id. Root sessions have `thread_source: "user"`.
+
+## Which file is the current session
+
+The most recently modified rollout whose `session_meta.payload.cwd` is the
+current working directory and whose `thread_source` is `user`. Confirm by
+matching the first `user_message` event to what your human partner
+remembers. Newer rollouts may carry no `user_message` event at all: when
+that command returns nothing, fall back to `response_item` messages with
+`role:"user"` (see Human-typed prompt below) and confirm against the first
+of those instead.
+
+## Line types
+
+Every line is `{timestamp, type, payload}` (some also carry `ordinal`).
+`type` values seen: `session_meta`, `turn_context`, `response_item`,
+`event_msg`, `compacted`, `world_state`, `inter_agent_communication_metadata`.
+
+| What you want | Where it is |
+|---|---|
+| Session identity | `session_meta.payload`: `id`, `session_id`, `cwd`, `originator` (e.g. `Codex Desktop`), `cli_version`, `model_provider`, `thread_source`, `source`, `git` (`commit_hash`, `branch`, `repository_url`), `base_instructions.text`. |
+| Model per turn | `turn_context.payload`: `turn_id`, `model`, `effort`, `cwd`, `approval_policy`, `sandbox_policy`, `multi_agent_version`. Also `event_msg` `thread_settings_applied`. |
+| Human-typed prompt | `event_msg` with `payload.type=="user_message"`: `payload.message`. When that returns nothing — seen on `thread_source: "user"` Codex Desktop rollouts at `cli_version 0.149.0-alpha.4.1`, and on subagent rollouts — fall back to `response_item` messages with `payload.role=="user"`, text in `payload.content[0].text`. `role:"developer"` messages are injected boilerplate, not typed, and so is any fallback text that begins with a tag such as `<subagent_notification>`, `<environment_context>`, `<skill>` or `<recommended_plugins>`. On a subagent rollout the fallback text is the parent agent's dispatch prompt, not your human partner's. |
+| Assistant text | `event_msg` `agent_message` (`payload.message`, `payload.phase`) or `response_item` `message` with `role:"assistant"`. |
+| Tool calls | `response_item` with `payload.type` `function_call` (`name`, `arguments`, `call_id`) or `custom_tool_call` (`name`, `input`, `call_id`); outputs are `function_call_output` / `custom_tool_call_output` matched by `call_id`. Also `event_msg` `patch_apply_end` (`success`, `changes`), `web_search_end`, `mcp_tool_call_end` (`invocation.server`, `invocation.tool`). |
+| Turn timing | `event_msg` `task_started` (`turn_id`, `started_at`, `model_context_window`) and `task_complete` (`duration_ms`, `time_to_first_token_ms`, `last_agent_message`); `turn_aborted` (`reason`, `duration_ms`). |
+| Tokens | `event_msg` `token_count`: `payload.info.total_token_usage` (cumulative; keys include `input_tokens`, `cached_input_tokens`, `output_tokens`) and `payload.rate_limits`. |
+| Compaction | a `compacted` line (`window_id`, `previous_window_id`, `replacement_history`) and an `event_msg` `context_compacted`. |
+| Subagents | `event_msg` `sub_agent_activity` (`agent_thread_id`, `agent_path`, `kind`); `response_item` `agent_message` with `author`/`recipient`; the child's own rollout file (see Where). |
+| Skill use | No attribution field. Look for `SKILL.md` in `function_call.arguments` / `custom_tool_call.input` and in `world_state`/`session_meta` instruction text. |
+| Reasoning | `response_item` `reasoning` (`summary[].text`; `encrypted_content` is opaque). |
+
+## Safe extraction
+
+Rollouts reach hundreds of megabytes; `compacted` lines embed whole
+histories. Never print a whole line. Check size first:
+
+```bash
+F=~/.codex/sessions/YYYY/MM/DD/rollout-....jsonl
+wc -lc "$F"
+awk '{ if (length($0) > 100000) print NR, length($0) }' "$F"
+```
+
+With `jq`:
+
+```bash
+head -1 "$F" | jq '.payload | {id, cwd, originator, cli_version, model_provider, thread_source, git}'   # identity
+jq -r '.type + "/" + (.payload.type // "")' "$F" | sort | uniq -c                                       # census
+jq -r 'select(.type=="event_msg" and .payload.type=="user_message") | "\(input_line_number)\t\(.timestamp)\t\(.payload.message[0:160])"' "$F"   # human prompts
+jq -r 'select(.type=="response_item" and .payload.type=="message" and .payload.role=="user")
+       | "\(input_line_number)\t\(.timestamp)\t\((.payload.content[0].text // "")[0:160])"' "$F"   # human prompts, fallback when the line above returns nothing; skip rows whose text starts with a `<tag>`
+jq -r 'select(.type=="turn_context") | "\(.timestamp)\t\(.payload.model)\t\(.payload.effort)"' "$F"    # model per turn
+jq -c 'select(.type=="response_item" and (.payload.type=="function_call" or .payload.type=="custom_tool_call"))
+       | {line:input_line_number, name:.payload.name, args:((.payload.arguments // .payload.input)|tostring|.[0:120])}' "$F"   # tool calls
+jq -c 'select(.payload.type=="task_complete" or .payload.type=="turn_aborted") | {ts:.timestamp, type:.payload.type, ms:.payload.duration_ms}' "$F"   # turn timing
+jq -c 'select(.payload.type=="token_count") | {ts:.timestamp, t:.payload.info.total_token_usage}' "$F"   # tokens (cumulative)
+grep -n '"type":"compacted"\|"context_compacted"' "$F" | cut -d: -f1       # compaction line numbers
+grep -n 'SKILL\.md' "$F" | cut -d: -f1                                    # skill-read line numbers
+sed -n '123p' "$F" | jq -c '{ts:.timestamp, type, p:(.payload|tostring|.[0:400])}'   # one line, trimmed
+```
+
+Find a thread's subagent rollouts (filenames only, never content):
+
+```bash
+grep -l '"parent_thread_id":"<thread-id>"' ~/.codex/sessions/*/*/*/rollout-*.jsonl
+```
+
+A subagent rollout can carry no `event_msg` `user_message` at all — the
+parent agent's dispatch prompt instead shows up as a `response_item`
+`message` with `role:"user"`. If a `user_message` event is present, it is
+from the parent agent, not your human partner.

skills/diagnosing-superpowers/references/other-harnesses.md

@@ -0,0 +1,30 @@
+# Other harnesses: discover, then report what you found
+
+This file is for any harness without a verified reference in this
+directory. You know your own harness better than this file does. Use that
+knowledge, and write down exactly what you found so the report reader can
+judge it.
+
+## Procedure
+
+1. **Ask the harness.** Many harnesses expose a session or history command
+   (`<harness> session list`, `/sessions`, a "resume" picker). Use it to get
+   the session id and, if shown, the file path.
+2. **Look under the harness's config directory** (`~/.<harness>/`,
+   `~/.config/<harness>/`, `~/.local/share/<harness>/`) for `sessions`,
+   `history`, `chats`, `threads`, or `projects` directories holding `.jsonl`
+   or `.json` files.
+3. **Confirm a candidate** by extracting its first human message with a
+   size-safe command (`head -c 2000`, or `jq` on the first record) and
+   matching it to what your human partner remembers. Never print whole
+   lines; treat every candidate like the verified stores: `wc -lc` and a
+   long-line check before anything else.
+4. **Map the fields you need** by reading a handful of records with `jq -c
+   'keys'` or `head -c`: human prompt, assistant text, tool call and result,
+   model, harness version, timestamps, subagent linkage, compaction.
+5. **Record in the case file and the report's coverage notes**: the store
+   path, the layout you inferred, which of the fields above you could and
+   could not find, and your confidence. Field-level claims in the report
+   are marked "inferred from the file, not a documented format".
+6. **If you cannot find the store**, say so and ask your human partner for
+   the path. Do not guess a layout from another harness.

skills/diagnosing-superpowers/templates/bundle-README.md

@@ -0,0 +1,44 @@
+# Superpowers session diagnosis bundle
+
+Session: <session-id>
+Harness: <name> <version>    Superpowers: <version> (<sha or "not a checkout">)
+Redaction level: skeleton | evidence | full
+Built: <ISO timestamp>
+
+## What this is
+
+A scrubbed record of a coding-agent session in which superpowers was
+installed and something went wrong, prepared so that an agent or person
+who was not present can decide whether superpowers contributed and, if so,
+what to change. The report inside states what happened with `path:line`
+evidence. By design it contains no diagnosis of superpowers and no proposed
+fix; that is the reader's job.
+
+## Files
+
+- `report.md` — the diagnosis report (problem statement, verdict,
+  environment, sessions, timeline, findings, involvement, coverage notes).
+- `case.md` — the case file the analysts worked from.
+- `environment.json` — machine-readable copy of the environment section.
+- `timeline.md` — the per-turn timeline.
+- `findings/<dimension>.md` — raw analyst findings per dimension.
+- `transcripts/<session-id>.md` — condensed per-turn rendering of each
+  examined session (never the raw JSONL). At *skeleton* level tool-result
+  bodies are replaced by `[tool result: <tool>, <bytes> bytes, exit <code>]`;
+  at *evidence* level bodies are kept only for events cited in findings; at
+  *full* level all bodies are kept.
+- `scrub-log.md` — every placeholder used and its category (never the
+  original value).
+
+## How to read it
+
+Start with `report.md` §1–2, then §7 (involvement) and the evidence lines
+it cites, then the matching turns in `transcripts/`. `path:line` references
+point at the original files on the reporter's machine; the same line
+numbers are preserved in the condensed transcripts as `[L<n>]` markers.
+
+## Redaction
+
+Placeholders look like `<EMAIL-1>`, `<PERSON-2>`, `<SECRET-3>`, `<HOST-4>`,
+`<REPO-5>`, `<ORG-6>`, `<PROPRIETARY-7>`; home paths are rewritten to `~/…`. The same placeholder
+always refers to the same original value within this bundle.

skills/diagnosing-superpowers/templates/case.md

@@ -0,0 +1,50 @@
+# Case: <session-id>
+
+Workspace: ~/.superpowers/diagnosing-superpowers/<session-id>/
+Created: <ISO timestamp>
+
+## Problem statement (agreed with your human partner)
+
+<One paragraph. Names the session(s), the turn range if known, what was
+expected, what happened, and the observable that matters: wall-clock,
+tokens, repeated actions, a specific unexpected action.>
+
+Goal is a superpowers bug report: yes | no
+
+## Sessions
+
+| Role | Session id | Absolute path | Lines | Bytes | Longest line (bytes) | First prompt (first 120 chars) | First timestamp |
+|---|---|---|---|---|---|---|---|
+| main | | | | | | | |
+| subagent | | | | | | | |
+
+Rejected candidates: <id — path — why rejected>, or "none".
+
+Session still running at read time: yes | no (mtime <ISO>, lines <N>)
+
+## Environment
+
+- OS: <name and version>
+- Harness: <name> <version>
+- Models seen: <model id — where (main / subagent id)>
+- Superpowers install root: <path>; version <x.y.z>; git sha <sha or "not a checkout">
+- Skill files read or injected during the session:
+
+| File (relative to install root) | sha1 (current file) | mtime newer than session? |
+|---|---|---|
+
+- Other plugins / extensions / MCP servers configured: <list, or "none found">
+- Instruction files present (paths only): <list>
+
+## Context-safety rules for every reader of these files
+
+- Check `wc -lc` and long lines (`awk '{ if (length($0) > 100000) print NR, length($0) }'`) before reading.
+- Never `cat` or `grep` for content. Line numbers and counts first
+  (`grep -n … | cut -d: -f1`), then small fields from specific lines
+  (`sed -n Np | jq -c '{…}'` or `| cut -c1-500`).
+- Read-only: never modify, move, or delete a session file.
+- In a subagent transcript, "user" is the parent agent.
+
+## Harness reference to use
+
+<references/claude-code-sessions.md | references/codex-sessions.md | references/other-harnesses.md>

skills/diagnosing-superpowers/templates/issue.md

@@ -0,0 +1,49 @@
+- [x] I searched existing issues and this is not a duplicate (searched: <query terms>; closest: <#n title, or "none">)
+
+## Environment (required)
+
+| Field | Value |
+|-------|-------|
+| Superpowers version | <version> (<sha or "not a checkout">) |
+| Harness (Claude Code, Cursor, etc.) | <harness> |
+| Harness version | <version> |
+| Your model + version | <model ids seen> |
+| All plugins installed | <list> |
+| OS + shell | <os version>, <shell> |
+
+## Is this a Superpowers issue or a platform issue?
+
+- [ ] I confirmed this issue does not occur without Superpowers installed
+
+Not reproduced without superpowers. Evidence for involvement is below;
+the reporter has not established cause.
+
+## What happened?
+
+<Problem statement, then the triage verdict, with `path:line` citations
+rewritten as `transcript line <n>`.>
+
+## Steps to reproduce
+
+1. <first human prompt, scrubbed>
+2. <the turns leading to the problem, one line each>
+3. <the observable>
+
+## Expected behavior
+
+<from the problem statement>
+
+## Actual behavior
+
+<from the triage verdict>
+
+## Debug log or conversation transcript
+
+Session id(s): <ids>. A scrubbed bundle (redaction level: <level>) is
+attached to this issue by the reporter, or available on request.
+Superpowers involvement per the diagnosis report: <possible | likely>, with
+evidence at <transcript lines>. This report does not propose a fix.
+
+---
+Filed with the `diagnosing-superpowers` skill. Model, harness, harness
+version, and installed plugins are listed above.

skills/diagnosing-superpowers/templates/report.md

@@ -0,0 +1,78 @@
+# Session diagnosis: <session-id>
+
+Report path: ~/.superpowers/diagnosing-superpowers/<session-id>/report.md
+Written: <ISO timestamp>
+
+## 1. Problem statement (REQUIRED)
+
+<Copied from the case file.>
+
+## 2. Triage verdict (REQUIRED)
+
+<What the evidence shows happened around the reported problem. Prose, with
+`path:line` after every claim. State confidence: high / medium / low, and
+what would raise it. No statement about what superpowers should do.>
+
+## 3. Environment (REQUIRED)
+
+- OS:
+- Harness and version:
+- Models seen:
+- Superpowers install root / version / git sha:
+- Skill files read or injected (sha1 table from the case file):
+- Other plugins, extensions, MCP servers:
+- Instruction files present (paths only):
+
+## 4. Sessions examined (REQUIRED)
+
+| Role | Session id | Absolute path | Lines | Bytes |
+|---|---|---|---|---|
+
+Rejected candidates: <id — path — why>, or "none".
+
+## 5. Timeline (REQUIRED)
+
+One row per human-typed prompt. Events column lists skills invoked,
+subagents dispatched, compaction, errors, resumes, aborts.
+
+| Turn | Line | Time | Request (one line) | Events |
+|---|---|---|---|---|
+
+## 6. Findings (REQUIRED, one subsection per dimension)
+
+Each finding:
+```
+- finding: <one sentence>
+  evidence: <path:line> — "<short quote>"
+  turns: <first>–<last>
+  confidence: high | medium | low
+```
+A dimension with nothing to report says `none found — checked: <what was checked>`.
+
+### 6.1 Skill timeline
+### 6.2 Plan adherence
+### 6.3 Repeated work
+### 6.4 Stumbles
+### 6.5 Quality evidence
+### 6.6 Request conflicts
+### 6.7 Cost and time
+### 6.8 Other plugins and skills used
+
+## 7. Superpowers involvement (REQUIRED)
+
+not indicated | possible | likely
+
+Evidence lines: <path:line list>. This section states involvement only. It
+does not name a defect and does not propose a change.
+
+## 8. Coverage notes (REQUIRED)
+
+- Not read: <ranges, files, and why>
+- Harness features unavailable: <list or none>
+- Session was in progress at read time: yes/no
+- For your human partner to double-check: <list or none>
+
+## 9. Similar sessions (only when requested)
+
+| Session id | Path | Date | Harness | Matched | Did not match |
+|---|---|---|---|---|---|

skills/dispatching-parallel-agents/SKILL.md

@@ -158,15 +158,6 @@ Agent 3 → Fix tool-approval-race-conditions.test.ts
 
 **Integration:** All fixes independent, no conflicts, full suite green
 
-**Time saved:** 3 problems solved in parallel vs sequentially
-
-## Key Benefits
-
-1. **Parallelization** - Multiple investigations happen simultaneously
-2. **Focus** - Each agent has narrow scope, less context to track
-3. **Independence** - Agents don't interfere with each other
-4. **Speed** - 3 problems solved in time of 1
-
 ## Verification
 
 After agents return:
@@ -174,12 +165,3 @@ After agents return:
 2. **Check for conflicts** - Did agents edit same code?
 3. **Run full suite** - Verify all fixes work together
 4. **Spot check** - Agents can make systematic errors
-
-## Real-World Impact
-
-From debugging session (2025-10-03):
-- 6 failures across 3 files
-- 3 agents dispatched in parallel
-- All investigations completed concurrently
-- All fixes integrated successfully
-- Zero conflicts between agent changes

skills/executing-plans/SKILL.md

@@ -11,15 +11,16 @@ Load plan, review critically, execute all tasks, report when complete.
 
 **Announce at start:** "I'm using the executing-plans skill to implement this plan."
 
-**Note:** Tell your human partner that Superpowers works much better with access to subagents. The quality of its work will be significantly higher if run on a platform with subagent support (Claude Code, Codex CLI, Codex App, and Copilot CLI all qualify; see the per-platform tool refs in `../using-superpowers/references/`). If subagents are available, use superpowers:subagent-driven-development instead of this skill.
+**Note:** Tell your human partner that Superpowers works much better with access to subagents (Claude Code, Codex CLI, Codex App, Copilot CLI, and Gemini CLI all qualify; see the per-platform tool refs in `../using-superpowers/references/`). If subagents are available, use superpowers:subagent-driven-development instead of this skill.
 
 ## The Process
 
 ### Step 1: Load and Review Plan
-1. Read plan file
-2. Review critically - identify any questions or concerns about the plan
-3. If concerns: Raise them with your human partner before starting
-4. If no concerns: Create todos for the plan items and proceed
+1. Ensure an isolated workspace: use superpowers:using-git-worktrees to create one or verify the existing one
+2. Read plan file
+3. Review critically - identify any questions or concerns about the plan
+4. If concerns: Raise them with your human partner before starting
+5. If no concerns: Create todos for the plan items and proceed
 
 ### Step 2: Execute Tasks
 
@@ -61,10 +62,3 @@ After all tasks complete and verified:
 - Reference skills when plan says to
 - Stop when blocked, don't guess
 - Never start implementation on main/master branch without explicit user consent
-
-## Integration
-
-**Required workflow skills:**
-- **superpowers:using-git-worktrees** - Ensures isolated workspace (creates one or verifies existing)
-- **superpowers:writing-plans** - Creates the plan this skill executes
-- **superpowers:finishing-a-development-branch** - Complete development after all tasks

skills/finishing-a-development-branch/SKILL.md

@@ -1,71 +1,58 @@
 ---
 name: finishing-a-development-branch
-description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
+description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work
 ---
 
 # Finishing a Development Branch
 
 ## Overview
 
-Guide completion of development work by presenting clear options and handling chosen workflow.
-
 **Core principle:** Verify tests → Detect environment → Present options → Execute choice → Clean up.
 
 **Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."
 
-## The Process
+## Step 1: Verify Tests
 
-### Step 1: Verify Tests
+Run the project's full test suite (`npm test` / `cargo test` / `pytest` / `go test ./...`).
 
-**Before presenting options, verify tests pass:**
+**If tests fail**, report the failures and stop — the menu comes after a green suite:
 
-```bash
-# Run project's test suite
-npm test / cargo test / pytest / go test ./...
-```
-
-**If tests fail:**
 ```
 Tests failing (<N> failures). Must fix before completing:
 
 [Show failures]
-
-Cannot proceed with merge/PR until tests pass.
 ```
 
-Stop. Don't proceed to Step 2.
+**If tests pass:** continue to Step 2.
 
-**If tests pass:** Continue to Step 2.
-
-### Step 2: Detect Environment
-
-**Determine workspace state before presenting options:**
+## Step 2: Detect Environment
 
 ```bash
 GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
 GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+# Capture now, while still inside the workspace — Step 5 changes directory
+# before cleanup (Step 6) needs this value
+WORKTREE_PATH=$(git rev-parse --show-toplevel)
 ```
 
 This determines which menu to show and how cleanup works:
 
 | State | Menu | Cleanup |
 |-------|------|---------|
-| `GIT_DIR == GIT_COMMON` (normal repo) | Standard 4 options | No worktree to clean up |
-| `GIT_DIR != GIT_COMMON`, named branch | Standard 4 options | Provenance-based (see Step 6) |
-| `GIT_DIR != GIT_COMMON`, detached HEAD | Reduced 3 options (no merge) | No cleanup (externally managed) |
+| `GIT_DIR == GIT_COMMON` (normal repo) | Standard 3 options | No worktree to clean up |
+| `GIT_DIR != GIT_COMMON`, named branch | Standard 3 options | Provenance-based (see Step 6) |
+| `GIT_DIR != GIT_COMMON`, detached HEAD | Reduced 2 options (no merge) | Externally managed — leave in place |
 
-### Step 3: Determine Base Branch
+## Step 3: Determine Base Branch
 
-```bash
-# Try common base branches
-git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
-```
+The base branch is whatever this work forked from — usually named in the
+plan, the conversation, or the branch's upstream. If it is not already
+known, ask: "This branch split from <your best guess> - is that correct?"
+Confirm before merging: merging into the wrong base is expensive to undo.
 
-Or ask: "This branch split from main - is that correct?"
+## Step 4: Present Options
 
-### Step 4: Present Options
-
-**Normal repo and named-branch worktree — present exactly these 4 options:**
+**Normal repo and named-branch worktree — present exactly these 3 options:**
 
 ```
 Implementation complete. What would you like to do?
@@ -73,28 +60,30 @@ Implementation complete. What would you like to do?
 1. Merge back to <base-branch> locally
 2. Push and create a Pull Request
 3. Keep the branch as-is (I'll handle it later)
-4. Discard this work
 
 Which option?
 ```
 
-**Detached HEAD — present exactly these 3 options:**
+**Detached HEAD — present exactly these 2 options:**
 
 ```
 Implementation complete. You're on a detached HEAD (externally managed workspace).
 
 1. Push as new branch and create a Pull Request
 2. Keep as-is (I'll handle it later)
-3. Discard this work
 
 Which option?
 ```
 
-**Don't add explanation** - keep options concise.
+Present the menu exactly as written — concise, with every option coming
+from the list above. Discarding the work happens only in response to your
+human partner explicitly asking for it (see "If your human partner asks to
+discard the work" below). Wait for their answer; the integration decision
+is theirs.
 
-### Step 5: Execute Choice
+## Step 5: Execute Choice
 
-#### Option 1: Merge Locally
+### Option 1: Merge Locally
 
 ```bash
 # Get main repo root for CWD safety
@@ -108,34 +97,43 @@ git merge <feature-branch>
 
 # Verify tests on merged result
 <test command>
-
-# Only after merge succeeds: cleanup worktree (Step 6), then delete branch
 ```
 
-Then: Cleanup worktree (Step 6), then delete branch:
+If tests fail on the merged result: stop, leave the worktree and branch in
+place, and investigate — nothing has been pushed, so the merge is local
+and recoverable.
+
+Once the merged result is green: clean up the worktree (Step 6), then
+delete the branch:
 
 ```bash
 git branch -d <feature-branch>
 ```
 
-#### Option 2: Push and Create PR
+### Option 2: Push and Create PR
 
 ```bash
-# Push branch
 git push -u origin <feature-branch>
+# From a detached HEAD, name the new branch on the remote:
+# git push origin HEAD:refs/heads/<new-branch>
 ```
 
-**Do NOT clean up worktree** — user needs it alive to iterate on PR feedback.
+Then create the pull/merge request against <base-branch> with the forge's
+tooling — its CLI if one is available, or the creation URL most forges
+print when you push — following the repo's PR template and conventions if
+present, and report the URL to your human partner.
 
-#### Option 3: Keep As-Is
+Keep the worktree — your human partner iterates on PR feedback there.
+
+### Option 3: Keep As-Is
 
 Report: "Keeping branch <name>. Worktree preserved at <path>."
 
-**Don't cleanup worktree.**
+### If your human partner asks to discard the work
 
-#### Option 4: Discard
+This path exists only as a response to an explicit request to throw the
+work away. Confirm first:
 
-**Confirm first:**
 ```
 This will permanently delete:
 - Branch <name>
@@ -145,41 +143,62 @@ This will permanently delete:
 Type 'discard' to confirm.
 ```
 
-Wait for exact confirmation.
+Wait for that exact confirmation. When it arrives:
 
-If confirmed:
 ```bash
 MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
 cd "$MAIN_ROOT"
 ```
 
-Then: Cleanup worktree (Step 6), then force-delete branch:
+Then clean up the worktree (Step 6) and force-delete the branch:
+
 ```bash
 git branch -D <feature-branch>
 ```
 
-### Step 6: Cleanup Workspace
+## Step 6: Cleanup Workspace
 
-**Only runs for Options 1 and 4.** Options 2 and 3 always preserve the worktree.
-
-```bash
-GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
-GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
-WORKTREE_PATH=$(git rev-parse --show-toplevel)
-```
+**Runs for Option 1 and confirmed discards.** Options 2 and 3 always
+preserve the worktree. Both callers have already changed directory to the
+main repo root — worktree removal must run from outside the worktree —
+and use the `GIT_DIR`/`GIT_COMMON`/`WORKTREE_PATH` values captured in
+Step 2, from before that directory change.
 
 **If `GIT_DIR == GIT_COMMON`:** Normal repo, no worktree to clean up. Done.
 
-**If worktree path is under `.worktrees/` or `worktrees/`:** Superpowers created this worktree — we own cleanup.
+**If `WORKTREE_PATH` is under `.worktrees/` or `worktrees/`:** Superpowers
+created this worktree — we own cleanup:
 
 ```bash
-MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
-cd "$MAIN_ROOT"
 git worktree remove "$WORKTREE_PATH"
 git worktree prune  # Self-healing: clean up any stale registrations
 ```
 
-**Otherwise:** The host environment (harness) owns this workspace. Do NOT remove it. If your platform provides a workspace-exit tool, use it. Otherwise, leave the workspace in place.
+**If removal is refused** (`contains modified or untracked files`): the
+worktree holds files that exist nowhere else — uncommitted plans, notes,
+or scratch work. Never `--force` on your own initiative. Show your human
+partner what is at stake and ask:
+
+```bash
+git -C "$WORKTREE_PATH" status --porcelain -uall
+```
+
+```
+Worktree removal refused — these files were never committed:
+
+<file list>
+
+1. Commit them to <branch> before cleanup
+2. Move them into <main repo root>
+3. Delete them (unrecoverable)
+
+Which?
+```
+
+Carry out the choice, then remove the worktree.
+
+**Otherwise:** The host environment owns this workspace — leave it in
+place. If your platform provides a workspace-exit tool, use it.
 
 ## Quick Reference
 
@@ -188,54 +207,19 @@ git worktree prune  # Self-healing: clean up any stale registrations
 | 1. Merge locally | yes | - | - | yes |
 | 2. Create PR | - | yes | yes | - |
 | 3. Keep as-is | - | - | yes | - |
-| 4. Discard | - | - | - | yes (force) |
+| Discard (explicit request only) | - | - | - | yes (force) |
 
-## Common Mistakes
+## Common Rationalizations
 
-**Skipping test verification**
-- **Problem:** Merge broken code, create failing PR
-- **Fix:** Always verify tests before offering options
-
-**Open-ended questions**
-- **Problem:** "What should I do next?" is ambiguous
-- **Fix:** Present exactly 4 structured options (or 3 for detached HEAD)
-
-**Cleaning up worktree for Option 2**
-- **Problem:** Remove worktree user needs for PR iteration
-- **Fix:** Only cleanup for Options 1 and 4
-
-**Deleting branch before removing worktree**
-- **Problem:** `git branch -d` fails because worktree still references the branch
-- **Fix:** Merge first, remove worktree, then delete branch
-
-**Running git worktree remove from inside the worktree**
-- **Problem:** Command fails silently when CWD is inside the worktree being removed
-- **Fix:** Always `cd` to main repo root before `git worktree remove`
-
-**Cleaning up harness-owned worktrees**
-- **Problem:** Removing a worktree the harness created causes phantom state
-- **Fix:** Only clean up worktrees under `.worktrees/` or `worktrees/`
-
-**No confirmation for discard**
-- **Problem:** Accidentally delete work
-- **Fix:** Require typed "discard" confirmation
-
-## Red Flags
-
-**Never:**
-- Proceed with failing tests
-- Merge without verifying tests on result
-- Delete work without confirmation
-- Force-push without explicit request
-- Remove a worktree before confirming merge success
-- Clean up worktrees you didn't create (provenance check)
-- Run `git worktree remove` from inside the worktree
-
-**Always:**
-- Verify tests before offering options
-- Detect environment before presenting menu
-- Present exactly 4 options (or 3 for detached HEAD)
-- Get typed confirmation for Option 4
-- Clean up worktree for Options 1 & 4 only
-- `cd` to main repo root before worktree removal
-- Run `git worktree prune` after removal
+| Excuse | Reality |
+|--------|---------|
+| "Tests passed earlier this session" | Run the suite on the tree you are about to integrate. A green run only proves the tree it ran on. |
+| "They obviously want it merged" | Integration is your human partner's decision. Present the menu and wait. |
+| "They seem done with this feature — I'll offer to discard it" | The menu is complete as written. Discard happens only when your human partner asks for it in so many words. |
+| "'Yeah, get rid of it' counts as confirmation" | Only the typed word `discard` authorizes deletion. |
+| "The PR is up, so the worktree is clutter now" | PR feedback gets fixed in that worktree. It stays until the work lands. |
+| "This other worktree looks stale — I'll clean it too" | Clean up only worktrees under `.worktrees/` or `worktrees/`. Everything else belongs to the host. |
+| "Removal refused — `--force` is just finishing the cleanup" | The refusal means files exist only in that worktree. `--force` destroys them permanently. Show your human partner and ask. |
+| "The merged-result failure is probably flaky" | A failing merged result stops everything. Branch and worktree stay put while you investigate. |
+| "The base branch is obviously main" | Confirm the fork point or ask. Merging into the wrong base is expensive to undo. |
+| "The push was rejected — force-push will fix it" | A rejected push means the remote moved. Investigate; force-push only on your human partner's explicit request. |

skills/receiving-code-review/SKILL.md

@@ -203,11 +203,3 @@ You understand 1,2,3,6. Unclear on 4,5.
 ## GitHub Thread Replies
 
 When replying to inline review comments on GitHub, reply in the comment thread (`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`), not as a top-level PR comment.
-
-## The Bottom Line
-
-**External feedback = suggestions to evaluate, not orders to follow.**
-
-Verify. Question. Then implement.
-
-No performative agreement. Technical rigor always.

skills/requesting-code-review/SKILL.md

@@ -5,7 +5,7 @@ description: Use when completing tasks, implementing major features, or before m
 
 # Requesting Code Review
 
-Dispatch a code reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work.
+Dispatch a code reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history.
 
 **Core principle:** Review early, review often.
 
@@ -72,20 +72,12 @@ You: [Fix progress indicators]
 [Continue to Task 3]
 ```
 
-## Integration with Workflows
+## Common Rationalizations
 
-**Subagent-Driven Development:**
-- Review after EACH task
-- Catch issues before they compound
-- Fix before moving to next task
-
-**Executing Plans:**
-- Review after each task or at natural checkpoints
-- Get feedback, apply, continue
-
-**Ad-Hoc Development:**
-- Review before merge
-- Review when stuck
+| Excuse | Reality |
+|--------|---------|
+| "I'll just review the diff myself instead of dispatching a reviewer" | You're the coordinator — reviewing the diff inline burns the context window you need to keep driving the work. Dispatch a reviewer subagent: the diff and the evaluation live in its context, and only the findings come back to you. |
+| "The reviewer needs my whole session history to understand the change" | Hand it precisely crafted context, never your session's history. That keeps the reviewer on the work product, not your thought process. |
 
 ## Red Flags
 

skills/requesting-code-review/code-reviewer.md

@@ -34,6 +34,15 @@ Subagent (general-purpose):
 
     Your review is read-only on this checkout. Do not mutate the working tree, the index, HEAD, or branch state in any way. Use tools like `git show`, `git diff`, and `git log` to inspect history. If you need a working copy of a different revision, check it out into a separate temporary directory (e.g. `git worktree add /tmp/review-[SHA] [SHA]`) — never move HEAD on this checkout.
 
+    ## You Do Not Dispatch Subagents
+
+    Do all of this review yourself. Never spawn a subagent to review part
+    of the diff, and never spawn another reviewer for a second opinion.
+    This process already provides every review seat the work gets; a
+    reviewer you spawn duplicates one of them at full cost, and its
+    verdict counts for nothing. If the diff feels too large for one
+    pass, review it in passes yourself and say so in your report.
+
     ## What to Check
 
     **Plan alignment:**

skills/subagent-driven-development/SKILL.md

@@ -14,7 +14,21 @@ Execute plan by dispatching a fresh implementer subagent per task, a task review
 **Narration:** between tool calls, narrate at most one short line — the
 ledger and the tool results carry the record.
 
-**Continuous execution:** Do not pause to check in with your human partner between tasks. Execute all tasks from the plan without stopping. The only reasons to stop are: BLOCKED status you cannot resolve, ambiguity that genuinely prevents progress, or all tasks complete. "Should I continue?" prompts and progress summaries waste their time — they asked you to execute the plan, so execute it.
+**Continuous execution:** Do not pause to check in with your human partner between tasks. Execute all tasks from the plan without stopping. The only reasons to stop are the four named below, or all tasks complete. "Should I continue?" prompts and progress summaries waste their time — they asked you to execute the plan, so execute it.
+
+**Rulings, not stalls.** A running plan does not wait on a human. Conflicts,
+ambiguities, plan defects, a cap you would have asked to exceed — decide
+them. The spec is the binding authority, the plan is its argument, and your
+judgment settles what neither answers. Record every decision in the ledger as
+`Ruling: <what you decided> — <why> — <what it costs if wrong>`, and keep
+going. A wrong ruling costs rework your human partner can see and undo; a
+session parked on a question costs their whole day and buys nothing.
+
+Four things stop you, and only these: an irreversible or destructive
+operation; a security-sensitive action; a side effect outside this worktree
+that norms say you ask about first (a merge, a push to a shared branch, a
+publish); and a plan so broken that every path forward is a guess. For those,
+stop and ask.
 
 ## When to Use
 
@@ -51,50 +65,121 @@ digraph process {
     subgraph cluster_per_task {
         label="Per Task";
         "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
-        "Implementer subagent asks questions?" [shape=diamond];
+        "Implementer asks questions?" [shape=diamond];
         "Answer questions, provide context" [shape=box];
-        "Implementer subagent implements, tests, commits, self-reviews" [shape=box];
-        "Write diff file, dispatch task reviewer subagent (./task-reviewer-prompt.md)" [shape=box];
-        "Task reviewer reports spec ✅ and quality approved?" [shape=diamond];
-        "Dispatch fix subagent for Critical/Important findings" [shape=box];
-        "Mark task complete in todo list and progress ledger" [shape=box];
+        "Implementer implements, tests, commits, self-reviews" [shape=box];
+        "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" [shape=box];
+        "Spec ✅ and quality approved?" [shape=diamond];
+        "Finding conflicts with plan text?" [shape=diamond];
+        "Rule on the conflict, ledger the ruling" [shape=box];
+        "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [shape=box];
+        "Dispatch scoped re-review (./re-review-prompt.md)" [shape=box];
+        "All findings addressed?" [shape=diamond];
+        "R = 5?" [shape=diamond];
+        "Adjudicate each open finding" [shape=box];
+        "Any load-bearing finding?" [shape=diamond];
+        "Rule and continue; stop only if every path forward is a guess" [shape=box];
+        "Park findings in ledger with rulings" [shape=box];
+        "Append completion to ledger, mark todo complete" [shape=box];
     }
 
-    "Read plan, note context and global constraints, create todos" [shape=box];
+    "Setup: worktree, ledger check, read plan, pre-flight review" [shape=box];
     "More tasks remain?" [shape=diamond];
-    "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" [shape=box];
+    "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" [shape=box];
+    "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" [shape=box];
+    "Final review clean: delete this plan's workspace" [shape=box];
     "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
 
-    "Read plan, note context and global constraints, create todos" -> "Dispatch implementer subagent (./implementer-prompt.md)";
-    "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
-    "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
-    "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
-    "Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
-    "Implementer subagent implements, tests, commits, self-reviews" -> "Write diff file, dispatch task reviewer subagent (./task-reviewer-prompt.md)";
-    "Write diff file, dispatch task reviewer subagent (./task-reviewer-prompt.md)" -> "Task reviewer reports spec ✅ and quality approved?";
-    "Task reviewer reports spec ✅ and quality approved?" -> "Dispatch fix subagent for Critical/Important findings" [label="no"];
-    "Dispatch fix subagent for Critical/Important findings" -> "Write diff file, dispatch task reviewer subagent (./task-reviewer-prompt.md)" [label="re-review"];
-    "Task reviewer reports spec ✅ and quality approved?" -> "Mark task complete in todo list and progress ledger" [label="yes"];
-    "Mark task complete in todo list and progress ledger" -> "More tasks remain?";
+    "Setup: worktree, ledger check, read plan, pre-flight review" -> "Dispatch implementer subagent (./implementer-prompt.md)";
+    "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer asks questions?";
+    "Implementer asks questions?" -> "Answer questions, provide context" [label="yes"];
+    "Answer questions, provide context" -> "Implementer implements, tests, commits, self-reviews";
+    "Implementer asks questions?" -> "Implementer implements, tests, commits, self-reviews" [label="no"];
+    "Implementer implements, tests, commits, self-reviews" -> "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)";
+    "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" -> "Spec ✅ and quality approved?";
+    "Spec ✅ and quality approved?" -> "Append completion to ledger, mark todo complete" [label="yes"];
+    "Spec ✅ and quality approved?" -> "Finding conflicts with plan text?" [label="no"];
+    "Finding conflicts with plan text?" -> "Rule on the conflict, ledger the ruling" [label="yes"];
+    "Rule on the conflict, ledger the ruling" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model";
+    "Finding conflicts with plan text?" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [label="no"];
+    "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" -> "Dispatch scoped re-review (./re-review-prompt.md)";
+    "Dispatch scoped re-review (./re-review-prompt.md)" -> "All findings addressed?";
+    "All findings addressed?" -> "Append completion to ledger, mark todo complete" [label="yes"];
+    "All findings addressed?" -> "R = 5?" [label="no"];
+    "R = 5?" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [label="no - next round"];
+    "R = 5?" -> "Adjudicate each open finding" [label="yes - breaker trips"];
+    "Adjudicate each open finding" -> "Any load-bearing finding?";
+    "Any load-bearing finding?" -> "Rule and continue; stop only if every path forward is a guess" [label="yes"];
+    "Any load-bearing finding?" -> "Park findings in ledger with rulings" [label="no"];
+    "Park findings in ledger with rulings" -> "Append completion to ledger, mark todo complete";
+    "Append completion to ledger, mark todo complete" -> "More tasks remain?";
     "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
-    "More tasks remain?" -> "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" [label="no"];
-    "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" -> "Use superpowers:finishing-a-development-branch";
+    "More tasks remain?" -> "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" [label="no"];
+    "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" -> "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals";
+    "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" -> "Final review clean: delete this plan's workspace";
+    "Final review clean: delete this plan's workspace" -> "Use superpowers:finishing-a-development-branch";
 }
 ```
 
-## Pre-Flight Plan Review
+## Setup
 
-Before dispatching Task 1, scan the plan once for conflicts:
+Ensure the work happens in an isolated workspace: use
+superpowers:using-git-worktrees to create one or verify the existing one.
+Never start implementation on a main/master branch without your human
+partner's explicit consent.
+
+Conversation memory does not survive compaction. In real sessions,
+controllers that lost their place have re-dispatched entire completed task
+sequences — the single most expensive failure observed. Track progress in
+a ledger file, not only in todos.
+
+- Each plan owns a workspace: at skill start, run this skill's
+  `scripts/sdd-workspace PLAN_FILE` — it prints the plan's git-ignored
+  directory (`<repo-root>/.superpowers/sdd/<plan-basename>/`), home to
+  every artifact for THIS plan: ledger, briefs, reports, review packages.
+  Another plan's directory is never yours to read or write.
+- Check for this plan's ledger at `<workspace>/progress.md`. If its first
+  line names your plan file, tasks with a `Task <N>: complete` line are DONE
+  — do not re-dispatch them; resume at the first task without one. A task
+  whose last line is a fix round is mid-loop: resume the loop at the next
+  round. A ledger whose first line names a different plan file — or a stray
+  ledger at the old flat path `.superpowers/sdd/progress.md` — is another
+  plan's progress: leave it in place and start your own, fresh.
+- Create the ledger with its identity as the first line:
+  `# SDD ledger — plan: <plan file path>`.
+- The ledger is your recovery map: the commits it names exist in git even
+  when your context no longer remembers creating them. After compaction,
+  trust the ledger and `git log` over your own recollection.
+- `git clean -fdx` will destroy the workspace (it's git-ignored scratch); if
+  that happens, recover from `git log`.
+
+Read the plan once, note its context and Global Constraints, and create a
+todo per task. If the plan names a Spec, read that too: the spec is the
+authority the plan argues from, and conflicts inside the plan resolve
+against it. A plan with no reachable spec gets a ledger note saying so —
+rulings made without one are provisional.
+
+Before dispatching Task 1, scan the plan once for conflicts, writing down
+what you checked as you check it:
 
 - tasks that contradict each other or the plan's Global Constraints
 - anything the plan explicitly mandates that the review rubric treats as a
   defect (a test that asserts nothing, verbatim duplication of a logic block)
 
-Present everything you find to your human partner as one batched question —
-each finding beside the plan text that mandates it, asking which governs —
-before execution begins, not one interrupt per discovery mid-plan. If the
-scan is clean, proceed without comment. The review loop remains the net for
-conflicts that only emerge from implementation.
+The scan's output is a table, not a verdict. One row for every pair of tasks
+that share a file or an interface: the two tasks, what one produces against
+what the other consumes, and what you found. One row for every task: whether
+its own text agrees with itself — the tests it specifies against the code it
+specifies, the files it creates against the files it later touches. "The scan
+is clean" without those rows is not a scan you ran.
+
+Write the table to the ledger. Rule on everything you find before execution
+begins — each finding against the plan text that mandates it — and record
+each ruling in the ledger. If the scan is clean, proceed without comment.
+Rule on each conflict it surfaces — the spec is the binding authority, the
+plan is its argument — record the ruling beside its row, and dispatch
+Task 1. The review loop remains the net for conflicts that only emerge from
+implementation.
 
 ## Model Selection
 
@@ -110,7 +195,11 @@ capable available model, not the session default.
 
 **Review tasks**: choose the model with the same judgment, scaled to the
 diff's size, complexity, and risk. A small mechanical diff does not need the
-most capable model; a subtle concurrency change does.
+most capable model; a subtle concurrency change does. Scoped re-reviews of
+small fix diffs take a cheap-to-mid tier.
+
+**Fix-loop escalation (rounds 4-5)**: use a model at least one tier above
+the implementer that got stuck.
 
 **Always specify the model explicitly when dispatching a subagent.** An
 omitted model inherits your session's model — often the most capable and
@@ -129,11 +218,76 @@ that implementer. Single-file mechanical fixes also take the cheapest tier.
 - Touches multiple files with integration concerns → standard model
 - Requires design judgment or broad codebase understanding → most capable model
 
-## Handling Implementer Status
+## The Task Loop
+
+**Batch small same-shape work.** When the plan lists several tasks that are
+each a small, independent edit of the same kind — the same one-line fix,
+constant change, or field addition repeated across files — do not dispatch
+one subagent per task. Compose ONE dispatch brief listing every file and
+its change, send the whole batch to a single subagent, and review its diff
+as one unit. Reserve one-dispatch-per-task for work that needs its own
+judgment, its own tests, or its own review surface.
+
+Everything you paste into a dispatch prompt — and everything a subagent
+prints back — stays resident in your context for the rest of the session
+and is re-read on every later turn. Hand artifacts over as files.
+
+**Waiting on dispatched subagents:** never poll a wait interface with
+short timeouts, and never sit in one silent, open-ended wait either.
+While you have local work — ledger updates, packaging the next review,
+reading reports — keep working; child results arrive on their own.
+When you are genuinely idle, wait in bounded stretches (five to ten
+minutes, where your platform allows), and between stretches post one
+line of status and reconcile your live children: list them, and chase
+any that finished without reporting. A bounded stretch keeps nearly
+all of a long wait's efficiency while guaranteeing a stuck or lost
+child is noticed within minutes, not at the end of the session.
+
+### 1. Dispatch the implementer
+
+Record BASE (`git rev-parse HEAD`) before dispatching — the review package
+and fix-round diffs need it.
+
+- **Task brief:** before dispatching an implementer, run this skill's
+  `scripts/task-brief PLAN_FILE N` — it extracts the task's full text to a
+  uniquely named file and prints the path. Compose the dispatch so the
+  brief stays the single source of
+  requirements. Your dispatch should contain: (1) one line on where this
+  task fits in the project; (2) the brief path, introduced as "read this
+  first — it is your requirements, with the exact values to use verbatim";
+  (3) interfaces and decisions from earlier tasks that the brief cannot
+  know; (4) your resolution of any ambiguity you noticed in the brief;
+  (5) the report-file path and report contract. Exact values (numbers,
+  magic strings, signatures, test cases) appear only in the brief. Never
+  make a subagent read the whole plan file.
+- **Report file:** name the implementer's report file after the brief
+  (brief `…/task-N-brief.md` → report `…/task-N-report.md`) and put it in
+  the dispatch prompt. The implementer writes the full report there and
+  returns only status, commits, a one-line test summary, and concerns.
+- A dispatch prompt describes one task, not the session's history. Do not
+  paste accumulated prior-task summaries ("state after Tasks 1-3") into
+  later dispatches — a real session's dispatch hit 42k chars of which 99%
+  was pasted history. A fresh subagent needs its task, the interfaces it
+  touches, and the global constraints. Nothing else.
+- The dispatch carries the no-subagents contract (it is in the
+  implementer template): the implementer never dispatches subagents —
+  not helpers, and never a reviewer. Review arrives from you, after the
+  report. In real sessions, every reviewer a worker spawned duplicated
+  the task review the controller dispatched anyway — a full extra
+  review seat per task.
+- If an earlier task parked a finding in the area this task touches, carry
+  a pointer to that ledger entry in the dispatch.
+- Record the implementer's agent identity from the dispatch result —
+  fix-loop rounds 1-3 resume this agent.
+- Never dispatch multiple implementation subagents in parallel (conflicts).
+
+Template: [implementer-prompt.md](implementer-prompt.md)
+
+### 2. Handle the report
 
 Implementer subagents report one of four statuses. Handle each appropriately:
 
-**DONE:** Generate the review package (`scripts/review-package BASE HEAD`, from this skill's directory — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task), then dispatch the task reviewer with the printed path.
+**DONE:** Generate the review package (`scripts/review-package PLAN_FILE BASE HEAD`, from this skill's directory — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task), then dispatch the task reviewer with the printed path.
 
 **DONE_WITH_CONCERNS:** The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review. If they're observations (e.g., "this file is getting large"), note them and proceed to review.
 
@@ -143,24 +297,41 @@ Implementer subagents report one of four statuses. Handle each appropriately:
 1. If it's a context problem, provide more context and re-dispatch with the same model
 2. If the task requires more reasoning, re-dispatch with a more capable model
 3. If the task is too large, break it into smaller pieces
-4. If the plan itself is wrong, escalate to the human
+4. If the plan itself is wrong, rule on the correction, ledger it, and re-dispatch with the ruling carried in the dispatch
 
 **Never** ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change.
 
-## Handling Reviewer ⚠️ Items
+If the implementer asks questions — before starting or mid-task — answer
+clearly and completely, provide additional context if needed, and don't
+rush it into implementation.
 
-The task reviewer may report "⚠️ Cannot verify from diff" items — requirements
-that live in unchanged code or span tasks. These do not block the rest of the
-review, but you must resolve each one yourself before marking the task
-complete: you hold the plan and cross-task context the reviewer
-lacks. If you confirm an item is a real gap, treat it as a failed spec
-review — send it back to the implementer and re-review.
-
-## Constructing Reviewer Prompts
+### 3. Review the task
 
 Per-task reviews are task-scoped gates. The broad review happens once, at the
-final whole-branch review. When you fill a reviewer template:
+final whole-branch review. Never skip the task review, and never accept a
+report missing either verdict — spec compliance AND task quality are both
+required. Implementer self-review never replaces the task review; both are
+needed.
 
+- Hand the reviewer its diff as a file: run this skill's
+  `scripts/review-package PLAN_FILE BASE HEAD` and pass the reviewer the file path
+  it prints (or, without bash: `git log --oneline`, `git diff --stat`,
+  and `git diff -U10` for the range, redirected to one uniquely named
+  file). The output never enters your own context, and the reviewer sees
+  the commit list, stat summary, and full diff with context in one Read
+  call. Use the BASE you recorded before dispatching the implementer —
+  never `HEAD~1`, which silently truncates multi-commit tasks. Never
+  dispatch a task reviewer without a diff file.
+- **Reviewer inputs:** the task reviewer gets three paths — the same brief
+  file, the report file, and the review package — plus the global
+  constraints that bind the task.
+- The global-constraints block you hand the reviewer is its attention
+  lens. Copy the binding requirements verbatim from the plan's Global
+  Constraints section or the spec: exact values, exact formats, and the
+  stated relationships between components ("same layout as X", "matches
+  Y"). The reviewer's template already carries the process rules (YAGNI,
+  test hygiene, review method) — the constraints block is for what THIS
+  project's spec demands.
 - Do not add open-ended directives like "check all uses" or "run race tests
   if useful" without a concrete, task-specific reason
 - Do not ask a reviewer to re-run tests the implementer already ran on the
@@ -171,110 +342,172 @@ final whole-branch review. When you fill a reviewer template:
   loop. If the prompt you are writing contains "do not flag," "don't treat X
   as a defect," "at most Minor," or "the plan chose" — stop: you are
   pre-judging, usually to spare yourself a review loop.
-- The global-constraints block you hand the reviewer is its attention
-  lens. Copy the binding requirements verbatim from the plan's Global
-  Constraints section or the spec: exact values, exact formats, and the
-  stated relationships between components ("same layout as X", "matches
-  Y"). The reviewer's template already carries the process rules (YAGNI,
-  test hygiene, review method) — the constraints block is for what THIS
-  project's spec demands.
-- Hand the reviewer its diff as a file: run this skill's
-  `scripts/review-package BASE HEAD` and pass the reviewer the file path
-  it prints (or, without bash: `git log --oneline`, `git diff --stat`,
-  and `git diff -U10` for the range, redirected to one uniquely named
-  file). The output never enters your own context, and the reviewer sees
-  the commit list, stat summary, and full diff with context in one Read
-  call. Use the BASE you recorded before dispatching the implementer —
-  never `HEAD~1`, which silently truncates multi-commit tasks.
-- A dispatch prompt describes one task, not the session's history. Do not
-  paste accumulated prior-task summaries ("state after Tasks 1-3") into
-  later dispatches — a real session's dispatch hit 42k chars of which 99%
-  was pasted history. A fresh subagent needs its task, the interfaces it
-  touches, and the global constraints. Nothing else.
-- Dispatch fix subagents for Critical and Important findings. Record Minor
-  findings in the progress ledger as you go, and point the final
+The task reviewer may report "⚠️ Cannot verify from diff" items — requirements
+that live in unchanged code or span tasks. These do not block the rest of the
+review, but you must resolve each one yourself before marking the task
+complete: you hold the plan and cross-task context the reviewer
+lacks. If you confirm an item is a real gap, treat it as a failed spec
+review — it enters the fix loop with the other findings.
+
+Template: [task-reviewer-prompt.md](task-reviewer-prompt.md)
+
+### 4. The fix loop
+
+The loop triggers when the review reports spec ❌, any Critical or Important
+finding, or a ⚠️ item you confirmed as a real gap.
+
+Before the loop starts, two routes leave it immediately:
+
+- Record Minor findings in the progress ledger as you go
+  (`Task <N>: minor (deferred): <one-liner>`), and point the final
   whole-branch review at that list so it can triage which must be fixed
-  before merge. A roll-up nobody reads is a silent discard.
+  before merge. A roll-up nobody reads is a silent discard. Minor findings
+  never enter the loop.
 - A finding labeled plan-mandated — or any finding that conflicts with
-  what the plan's text requires — is the human's decision, like any plan
-  contradiction: present the finding and the plan text, ask which governs.
-  Do not dismiss the finding because the plan mandates it, and do not
-  dispatch a fix that contradicts the plan without asking.
-- The final whole-branch review gets a package too: run
-  `scripts/review-package MERGE_BASE HEAD` (MERGE_BASE = the commit the
-  branch started from, e.g. `git merge-base main HEAD`) and include the
-  printed path in the final review dispatch, so the final reviewer reads
-  one file instead of re-deriving the branch diff with git commands.
-- Every fix dispatch carries the implementer contract: the fix subagent
-  re-runs the tests covering its change and reports the results. Name the
-  covering test files in the dispatch — a one-line fix does not need the
-  whole suite. Before re-dispatching the reviewer, confirm the fix report
-  contains the covering tests, the command run, and the output; dispatch
-  the re-review once all three are present.
-- If the final whole-branch review returns findings, dispatch ONE fix
-  subagent with the complete findings list — not one fixer per finding.
-  Per-finding fixers each rebuild context and re-run suites; a real
-  session's final-review fix wave cost more than all its tasks combined.
+  what the plan's text requires — is yours to rule on: weigh the finding
+  against the plan text, decide with the spec as the binding authority, and
+  ledger the ruling before you act on it. Do not dismiss the finding because
+  the plan mandates it, and do not dispatch a fix that contradicts the plan
+  without a recorded ruling.
+Everything else enters the loop. A fix round is one fix dispatch plus one
+scoped re-review. Five rounds maximum per task:
 
-## File Handoffs
+**Rounds 1-3 — resume the original implementer.** Send it the open findings
+verbatim. Its context is intact: it knows the task, the code, and its own
+choices. If your harness cannot send another message to a live subagent,
+dispatch a fresh implementer carrying the brief path, the report-file path,
+and the findings — the report file is the persistent memory either way.
 
-Everything you paste into a dispatch prompt — and everything a subagent
-prints back — stays resident in your context for the rest of the session
-and is re-read on every later turn. Hand artifacts over as files:
+**Rounds 4-5 — dispatch a fresh implementer on a more capable model** (per
+Model Selection), with the brief path, the report-file path, the open
+findings, and this framing: "A prior implementer attempted this task
+[N] times; you own it now. Read the report file for what was tried." A loop
+that survives three resumes usually means the implementer cannot see its
+own problem — fresh eyes and a capability bump in one move.
 
-- **Task brief:** before dispatching an implementer, run this skill's
-  `scripts/task-brief PLAN_FILE N` — it extracts the task's full text to a
-  uniquely named file and prints the path. Compose the dispatch so the
-  brief stays the single source of requirements. Your dispatch should
-  contain: (1) one line on where this task fits in the project; (2) the
-  brief path, introduced as "read this first — it is your requirements,
-  with the exact values to use verbatim"; (3) interfaces and decisions
-  from earlier tasks that the brief cannot know; (4) your resolution of
-  any ambiguity you noticed in the brief; (5) the report-file path and
-  report contract. Exact values (numbers, magic strings, signatures, test
-  cases) appear only in the brief.
-- **Report file:** name the implementer's report file after the brief
-  (brief `…/task-N-brief.md` → report `…/task-N-report.md`) and put it in
-  the dispatch prompt. The implementer writes the full report there and
-  returns only status, commits, a one-line test summary, and concerns.
-- **Reviewer inputs:** the task reviewer gets three paths — the same brief
-  file, the report file, and the review package — plus the global
-  constraints that bind the task.
-- Fix dispatches append their fix report (with test results) to the same
-  report file and return a short summary; re-reviews read the updated file.
+**Every round, either way:** the implementer fixes, re-runs the tests
+covering the amended code, appends its fix report to the same report file,
+and returns the short contract. Before re-dispatching the reviewer, confirm
+the fix report contains the covering tests, the command run, and the
+output; dispatch the re-review once all three are present. Name the
+covering test files in the fix message — a one-line fix does not need the
+whole suite.
 
-## Durable Progress
+**The re-review is scoped.** Run `scripts/review-package PLAN_FILE FIX_BASE HEAD`
+where FIX_BASE is the head the previous review saw, and dispatch
+[re-review-prompt.md](re-review-prompt.md) with the findings list, the
+brief, the report file, and the printed diff path. The re-reviewer verdicts
+each finding ADDRESSED or NOT ADDRESSED and flags new breakage in the fix
+diff only. New Critical/Important breakage in the fix diff joins the open
+findings list. Out-of-scope observations go to the ledger as deferred
+minors — they never extend the loop.
 
-Conversation memory does not survive compaction. In real sessions,
-controllers that lost their place have re-dispatched entire completed task
-sequences — the single most expensive failure observed. Track progress in
-a ledger file, not only in todos.
+**After each round,** append to the ledger:
+`Task <N>: fix round <R>/5 (<X> addressed, <Y> open — <finding one-liners>; commits <a7>..<b7>)`
 
-- At skill start, check for a ledger:
-  `cat "$(git rev-parse --show-toplevel)/.superpowers/sdd/progress.md"`. Tasks listed there
-  as complete are DONE — do not re-dispatch them; resume at the first task
-  not marked complete.
-- When a task's review comes back clean, append one line to the ledger in
-  the same message as your other bookkeeping:
-  `Task N: complete (commits <base7>..<head7>, review clean)`.
-- The ledger is your recovery map: the commits it names exist in git even
-  when your context no longer remembers creating them. After compaction,
-  trust the ledger and `git log` over your own recollection.
-- `git clean -fdx` will destroy the ledger (it's git-ignored scratch); if
-  that happens, recover from `git log`.
+Never fix findings yourself in the controller session — your context stays
+clean for coordination, and controller fixes skip review.
 
-## Prompt Templates
+**The breaker.** When round 5's re-review still leaves findings open, stop
+dispatching. Adjudicate each open finding yourself — you hold the plan and
+the cross-task context the reviewer lacks:
 
-- [implementer-prompt.md](implementer-prompt.md) - Dispatch implementer subagent
-- [task-reviewer-prompt.md](task-reviewer-prompt.md) - Dispatch task reviewer subagent (spec compliance + code quality)
-- Final whole-branch review: use superpowers:requesting-code-review's [code-reviewer.md](../requesting-code-review/code-reviewer.md)
+- **The reviewer is wrong, or the point is contestable:** park it —
+  `Task <N>: parked — <finding> — Ruling: <why the code stands>`. The final
+  review sees both sides.
+- **Real, but nothing downstream builds on it:** park it the same way, with
+  a ruling that says it's real and deferred.
+- **Real and load-bearing** — a later task builds on it, or it reveals a
+  plan defect: rule on the smallest change that unblocks the dependent work,
+  ledger it as `Task <N>: Ruling: <finding> — <what you decided and why>`,
+  and carry it into the next task's dispatch. Parking a structural failure
+  silently lets every dependent task build on it. Stop only when the defect
+  leaves every path forward a guess.
+
+Adjudicate only at the cap. Adjudicating earlier to end a loop is
+pre-judging with a different name. Every adjudication is a ledger entry —
+a silent discard is forbidden.
+
+### 5. Complete the task
+
+When the review comes back clean — or every open finding is parked with a
+ruling at the cap — append the completion line to the ledger in the same
+message as your other bookkeeping:
+
+- `Task <N>: complete (commits <base7>..<head7>, review clean)`
+- `Task <N>: complete (commits <base7>..<head7>, <K> parked)` after a
+  tripped breaker
+
+Then mark the todo complete and move on. Never move to the next task while
+the review has open Critical/Important issues that are neither fixed nor
+parked-with-ruling at the cap.
+
+## Final Review
+
+The final whole-branch review gets a package too: run
+`scripts/review-package PLAN_FILE MERGE_BASE HEAD` (MERGE_BASE = the commit the
+branch started from, e.g. `git merge-base main HEAD`) and include the
+printed path in the final review dispatch, so the final reviewer reads
+one file instead of re-deriving the branch diff with git commands. Dispatch
+on the most capable available model (see Model Selection), using
+superpowers:requesting-code-review's
+[code-reviewer.md](../requesting-code-review/code-reviewer.md). Point it at
+the ledger's deferred-minor and parked lines so it can triage which must be
+fixed before merge.
+
+If the final whole-branch review returns findings, dispatch ONE fix subagent
+with the complete findings list — not one fixer per finding.
+Per-finding fixers each rebuild context and re-run suites; a real
+session's final-review fix wave cost more than all its tasks combined.
+Then run exactly one scoped re-review of the fix wave
+(`scripts/review-package PLAN_FILE FIX_BASE HEAD` over the fix range,
+[re-review-prompt.md](re-review-prompt.md)).
+Adjudicate any residual findings as in the task loop's breaker: park with
+rulings, or rule on the load-bearing ones and ledger what you decided. Only
+the four classes above stop you here. There is no second fix wave —
+residual load-bearing findings surface to your human partner when
+finishing-a-development-branch presents the options.
+
+## Finish
+
+Before you delete anything, collect every ledger line containing `Ruling:` —
+preflight rulings, parked findings, breaker adjudications, all of them — into
+your final message under "Rulings I made", in the order you made them, each
+with what it costs if wrong. The list is exhaustive: if the ledger holds a
+ruling, the list holds it. That list is the only place the decisions you
+took on your human partner's behalf reach them — they read it and rework
+whatever you got wrong. A ruling that dies with the workspace was a decision
+made in secret.
+
+When the final whole-branch review is clean and its fixes are merged,
+delete this plan's workspace (`rm -rf <workspace>`) — the git history is
+the record now. Sibling directories belong to other plans; leave them
+alone.
+
+Use superpowers:finishing-a-development-branch.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Close enough on spec compliance" | Reviewer found spec gaps = not done. Fix or hit the cap and adjudicate — those are the only exits. |
+| "I'll fix it myself, dispatching is overhead" | Controller fixes pollute your context and skip review. Resume the implementer. |
+| "One more round will converge" | Past the cap, rounds don't converge — the failure is structural. Adjudicate and route. |
+| "The reviewer will just find something new anyway" | Scoped re-reviews verify fixes; they cannot wander. New findings on untouched code go to the ledger, not the loop. |
+| "This finding is obviously wrong, I'll drop it" | You adjudicate only at the cap, and every ruling is a ledger entry. Silent discards are forbidden. |
+| "The fix was small, skip the re-review" | Unreviewed fixes are how regressions land. Every round ends with a scoped re-review. |
+| "Reviews slow the loop down" | The loop without reviews is just unverified churn. Reviews are the loop's brakes and steering. |
+| "Ledger bookkeeping is overhead" | The ledger is what survives compaction. Controllers without one have re-dispatched entire completed task sequences. |
+| "The implementer spawned its own reviewer — free extra assurance" | It's a duplicate seat reviewing the same diff; the task review is the gate. A worker-spawned reviewer is a defect to flag, not rigor. |
 
 ## Example Workflow
 
 ```
 You: I'm using Subagent-Driven Development to execute this plan.
 
+[Setup: worktree verified]
 [Read plan file once: docs/superpowers/plans/feature-plan.md]
+[Resolve workspace: scripts/sdd-workspace docs/superpowers/plans/feature-plan.md — no ledger inside, fresh start]
 [Create todos for all tasks]
 
 Task 1: Hook installation script
@@ -285,134 +518,51 @@ Implementer: "Before I begin - should the hook be installed at user or system le
 
 You: "User level (~/.config/superpowers/hooks/)"
 
-Implementer: "Got it. Implementing now..."
-[Later] Implementer:
+Implementer: [Later]
   - Implemented install-hook command
   - Added tests, 5/5 passing
   - Self-review: Found I missed --force flag, added it
   - Committed
 
-[Run review-package, dispatch task reviewer with the printed path]
+[Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path]
 Task reviewer: Spec ✅ - all requirements met, nothing extra.
   Strengths: Good test coverage, clean. Issues: None. Task quality: Approved.
 
-[Mark Task 1 complete]
+[Ledger: Task 1: complete (commits a1b2c3d..d4e5f6a, review clean)]
 
 Task 2: Recovery modes
 
 [Run task-brief for Task 2; dispatch implementer with brief + report paths + context]
 
-Implementer: [No questions, proceeds]
-Implementer:
+Implementer: [No questions]
   - Added verify/repair modes
   - 8/8 tests passing
-  - Self-review: All good
   - Committed
 
-[Run review-package, dispatch task reviewer with the printed path]
+[Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path]
 Task reviewer: Spec ❌:
   - Missing: Progress reporting (spec says "report every 100 items")
-  - Extra: Added --json flag (not requested)
   Issues (Important): Magic number (100)
 
-[Dispatch fix subagent with all findings]
-Fixer: Removed --json flag, added progress reporting, extracted PROGRESS_INTERVAL constant
+[Fix round 1: resume the implementer with both findings]
+Implementer: Added progress reporting, extracted PROGRESS_INTERVAL constant.
+  Re-ran test/recovery.test.js — 10/10 passing. Fix report appended.
 
-[Task reviewer reviews again]
-Task reviewer: Spec ✅. Task quality: Approved.
+[Run review-package PLAN_FILE FIX_BASE HEAD; dispatch scoped re-review]
+Re-reviewer: Missing progress reporting — ADDRESSED (src/recovery.js:41).
+  Magic number — ADDRESSED (src/recovery.js:7). New breakage: none.
+  Verdict: all findings addressed.
 
-[Mark Task 2 complete]
+[Ledger: Task 2: fix round 1/5 (2 addressed, 0 open; commits d4e5f6a..b7c8d9e)]
+[Ledger: Task 2: complete (commits d4e5f6a..b7c8d9e, review clean)]
 
 ...
 
 [After all tasks]
-[Dispatch final code-reviewer]
-Final reviewer: All requirements met, ready to merge
+[Run review-package PLAN_FILE MERGE_BASE HEAD; dispatch final code-reviewer, most capable model]
+Final reviewer: All requirements met. Deferred minors triaged: none block merge.
 
-Done!
+[Delete this plan's workspace — the record now lives in git]
+
+Done! Using superpowers:finishing-a-development-branch.
 ```
-
-## Advantages
-
-**vs. Manual execution:**
-- Subagents follow TDD naturally
-- Fresh context per task (no confusion)
-- Parallel-safe (subagents don't interfere)
-- Subagent can ask questions (before AND during work)
-
-**vs. Executing Plans:**
-- Same session (no handoff)
-- Continuous progress (no waiting)
-- Review checkpoints automatic
-
-**Efficiency gains:**
-- Controller curates exactly what context is needed; bulk artifacts move
-  as files, not pasted text
-- Subagent gets complete information upfront
-- Questions surfaced before work begins (not after)
-
-**Quality gates:**
-- Self-review catches issues before handoff
-- Task review carries two verdicts: spec compliance and code quality
-- Review loops ensure fixes actually work
-- Spec compliance prevents over/under-building
-- Code quality ensures implementation is well-built
-
-**Cost:**
-- More subagent invocations (implementer + reviewer per task)
-- Controller does more prep work (extracting all tasks upfront)
-- Review loops add iterations
-- But catches issues early (cheaper than debugging later)
-
-## Red Flags
-
-**Never:**
-- Start implementation on main/master branch without explicit user consent
-- Skip task review, or accept a report missing either verdict (spec compliance AND task quality are both required)
-- Proceed with unfixed issues
-- Dispatch multiple implementation subagents in parallel (conflicts)
-- Make a subagent read the whole plan file (hand it its task brief —
-  `scripts/task-brief` — instead)
-- Skip scene-setting context (subagent needs to understand where task fits)
-- Ignore subagent questions (answer before letting them proceed)
-- Accept "close enough" on spec compliance (reviewer found spec issues = not done)
-- Skip review loops (reviewer found issues = implementer fixes = review again)
-- Let implementer self-review replace actual review (both are needed)
-- Tell a reviewer what not to flag, or pre-rate a finding's severity in the
-  dispatch prompt ("treat it as Minor at most") — the plan's example code is
-  a starting point, not evidence that its weaknesses were chosen
-- Dispatch a task reviewer without a diff file — generate it first
-  (`scripts/review-package BASE HEAD`) and name the printed path in the
-  prompt
-- Move to next task while the review has open Critical/Important issues
-- Re-dispatch a task the progress ledger already marks complete — check
-  the ledger (and `git log`) after any compaction or resume
-
-**If subagent asks questions:**
-- Answer clearly and completely
-- Provide additional context if needed
-- Don't rush them into implementation
-
-**If reviewer finds issues:**
-- Implementer (same subagent) fixes them
-- Reviewer reviews again
-- Repeat until approved
-- Don't skip the re-review
-
-**If subagent fails task:**
-- Dispatch fix subagent with specific instructions
-- Don't try to fix manually (context pollution)
-
-## Integration
-
-**Required workflow skills:**
-- **superpowers:using-git-worktrees** - Ensures isolated workspace (creates one or verifies existing)
-- **superpowers:writing-plans** - Creates the plan this skill executes
-- **superpowers:requesting-code-review** - Code review template for the final whole-branch review
-- **superpowers:finishing-a-development-branch** - Complete development after all tasks
-
-**Subagents should use:**
-- **superpowers:test-driven-development** - Subagents follow TDD for each task
-
-**Alternative workflow:**
-- **superpowers:executing-plans** - Use for parallel session instead of same-session execution

skills/subagent-driven-development/implementer-prompt.md

@@ -47,6 +47,18 @@ Subagent (general-purpose):
     While iterating, run the focused test for what you're changing; run the
     full suite once before committing, not after every edit.
 
+    ## You Do Not Dispatch Subagents
+
+    Do all of this task's work yourself. Never spawn a subagent to
+    implement part of the task, and above all never spawn a reviewer to
+    check your work. Self-review (below) means reading your own diff.
+    Review is the controller's job: after you report, it dispatches a
+    fresh reviewer against your diff. A reviewer you spawn duplicates
+    that review at full cost, and its approval counts for nothing in
+    the process. If you catch yourself thinking "an independent review
+    would strengthen my report" — that review is already scheduled.
+    Report instead.
+
     ## Code Organization
 
     You reason best about code you can hold in context at once, and your edits are more
@@ -106,9 +118,12 @@ Subagent (general-purpose):
 
     ## After Review Findings
 
-    If a reviewer finds issues and you fix them, re-run the tests that cover
-    the amended code and append the results to your report file. Reviewers
-    will not re-run tests for you — your report is the test evidence.
+    If the task review finds issues, you will be resumed with the findings.
+    Fix them, re-run the tests that cover the amended code, and append a fix
+    report to your report file: what you changed, the covering tests you
+    ran, the command, and the output. Reviewers will not re-run tests for
+    you — your report is the test evidence. Then reply with the same short
+    status contract as your first report.
 
     ## Report Format
 

skills/subagent-driven-development/re-review-prompt.md

@@ -0,0 +1,115 @@
+# Scoped Re-Review Prompt Template
+
+Use this template when dispatching a re-review after a fix round. The
+re-reviewer verifies the findings were addressed and checks the fix diff for
+new breakage. It is not a fresh review — the full review already happened.
+
+**Purpose:** Verify each finding from the previous review was addressed, and
+that the fix itself broke nothing.
+
+```
+Subagent (general-purpose):
+  description: "Re-review Task N fix round R"
+  model: [MODEL — REQUIRED: choose per SKILL.md Model Selection; an omitted
+         model silently inherits the session's most expensive one]
+  prompt: |
+    You are re-reviewing one task's fix round. A previous review produced
+    findings; an implementer has attempted to fix them. Your job is to
+    verdict each finding and inspect the fix diff — nothing else.
+
+    ## The Task
+
+    Read the task brief: [BRIEF_FILE]
+
+    ## The Findings Under Verification
+
+    [FINDINGS]
+
+    ## The Fix
+
+    Read the implementer's report (fix reports are appended at the end):
+    [REPORT_FILE]
+
+    **Fix base:** [FIX_BASE_SHA] (the head the previous review saw)
+    **Head:** [HEAD_SHA]
+    **Diff file:** [DIFF_FILE]
+
+    Read the diff file once — it contains the fix commits, a stat summary,
+    and the fix diff with surrounding context. Do not re-run git commands.
+    If the diff file is missing, fetch the diff yourself:
+    `git diff --stat [FIX_BASE_SHA]..[HEAD_SHA]` and
+    `git diff [FIX_BASE_SHA]..[HEAD_SHA]`.
+
+    Your review is read-only on this checkout. Do not mutate the working
+    tree, the index, HEAD, or branch state in any way.
+
+    ## You Do Not Dispatch Subagents
+
+    Do all of this review yourself. Never spawn a subagent to review part
+    of the diff, and never spawn another reviewer for a second opinion.
+    This process already provides every review seat the work gets; a
+    reviewer you spawn duplicates one of them at full cost, and its
+    verdict counts for nothing. If the diff feels too large for one
+    pass, review it in passes yourself and say so in your report.
+
+    ## Scope
+
+    Your scope is the findings list and the fix diff. Verdict every finding.
+    Inspect the fix diff for new problems the fix itself introduced. Do NOT
+    re-review code the fix did not touch: if you notice an issue entirely
+    outside the fix diff, report it under Out-of-Scope Observations — it
+    does not block this task and does not extend the loop. A broad
+    whole-branch review happens after all tasks are complete.
+
+    ## Tests
+
+    The implementer re-ran the tests covering the amended code and appended
+    the results to the report file. Treat the report as unverified claims:
+    confirm the fix report names the covering tests and shows their output,
+    and verify the claims against the diff. Do not re-run the suite to
+    confirm their report. Run a test only when reading the code raises a
+    specific doubt that no existing run answers — and then a focused test,
+    never a package-wide suite.
+
+    ## Output Format
+
+    Your final message is the report itself: begin directly with the first
+    finding's verdict. Every line is a verdict, a finding with file:line,
+    or a check you ran — no preamble, no process narration.
+
+    ### Finding Verdicts
+
+    For each finding in The Findings Under Verification, in order:
+    - **[finding one-liner]** — ADDRESSED | NOT ADDRESSED, with file:line
+      evidence. "Attempted" is not addressed: the specific defect must no
+      longer exist.
+
+    ### New Breakage in the Fix Diff
+
+    Anything the fix itself broke or introduced, with severity
+    (Critical/Important/Minor) and file:line. "None" if clean.
+
+    ### Out-of-Scope Observations
+
+    Issues you noticed entirely outside the fix diff. Non-blocking; the
+    controller ledgers these for the final review. "None" if none.
+
+    ### Verdict
+
+    **Fix round:** [All findings addressed, no new Critical/Important
+    breakage | Findings remain open] — list the open ones.
+```
+
+**Placeholders:**
+- `[MODEL]` — REQUIRED: reviewer model per SKILL.md Model Selection; scoped
+  re-reviews of small fix diffs take a cheap-to-mid tier
+- `[BRIEF_FILE]` — the task brief file (same file the implementer worked from)
+- `[FINDINGS]` — the Critical/Important findings and spec gaps from the
+  previous review, copied verbatim, one per bullet
+- `[REPORT_FILE]` — the implementer's report file (fix reports appended)
+- `[FIX_BASE_SHA]` — the head the previous review saw
+- `[HEAD_SHA]` — current commit
+- `[DIFF_FILE]` — the path `scripts/review-package PLAN_FILE FIX_BASE HEAD` printed
+
+**Re-reviewer returns:** per-finding verdicts (ADDRESSED / NOT ADDRESSED),
+new breakage in the fix diff, out-of-scope observations, and a round verdict.

skills/subagent-driven-development/scripts/review-package

@@ -4,26 +4,28 @@
 # call. Using the recorded per-task BASE (not HEAD~1) keeps multi-commit
 # tasks intact.
 #
-# Usage: review-package BASE HEAD [OUTFILE]
-# Default OUTFILE: <repo-root>/.superpowers/sdd/review-<base7>..<head7>.diff
+# Usage: review-package PLAN_FILE BASE HEAD [OUTFILE]
+# Default OUTFILE: <repo-root>/.superpowers/sdd/<plan-basename>/review-<base7>..<head7>.diff
 # (named per range, so a re-review after fixes gets a distinct fresh file).
 set -euo pipefail
 
-if [ $# -lt 2 ] || [ $# -gt 3 ]; then
-  echo "usage: review-package BASE HEAD [OUTFILE]" >&2
+if [ $# -lt 3 ] || [ $# -gt 4 ]; then
+  echo "usage: review-package PLAN_FILE BASE HEAD [OUTFILE]" >&2
   exit 2
 fi
 
-base=$1
-head=$2
+plan=$1
+base=$2
+head=$3
+[ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
 
 git rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
 git rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&2; exit 2; }
 
-if [ $# -eq 3 ]; then
-  out=$3
+if [ $# -eq 4 ]; then
+  out=$4
 else
-  dir=$("$(cd "$(dirname "$0")" && pwd)/sdd-workspace")
+  dir=$("$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
   out="$dir/review-$(git rev-parse --short "$base")..$(git rev-parse --short "$head").diff"
 fi
 

skills/subagent-driven-development/scripts/sdd-workspace

@@ -1,22 +1,40 @@
 #!/usr/bin/env bash
-# Resolve and ensure the working-tree directory SDD uses for its short-lived
-# artifacts: task briefs, implementer reports, review packages, and the
-# progress ledger. Print the directory's absolute path.
+# Resolve and ensure the working-tree directory SDD uses for one plan's
+# short-lived artifacts: task briefs, implementer reports, review packages,
+# and the progress ledger. Print the plan directory's absolute path.
+#
+# One directory per plan (.superpowers/sdd/<plan-basename>/) so a follow-up
+# plan in the same working tree can never read or overwrite another plan's
+# artifacts. A stale ledger misread as current progress makes controllers
+# skip whole task sequences — plan-scoping removes that failure structurally.
 #
 # The workspace lives in the working tree (not under .git/) because Claude Code
 # treats .git/ as a protected path and denies agent writes there — which blocks
 # an implementer subagent from writing its report file. A self-ignoring
-# .gitignore keeps the workspace out of `git status` and out of accidental
-# commits without modifying any tracked file.
+# .gitignore at .superpowers/sdd/ keeps every plan's workspace out of
+# `git status` and out of accidental commits without modifying any tracked file.
 #
 # Single source of truth for the workspace location, so task-brief and
 # review-package cannot drift to different directories.
 #
-# Usage: sdd-workspace
+# Usage: sdd-workspace PLAN_FILE
 set -euo pipefail
 
+if [ $# -ne 1 ]; then
+  echo "usage: sdd-workspace PLAN_FILE" >&2
+  exit 2
+fi
+
+plan=$1
+[ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
+
+slug=$(basename "$plan" .md)
+[ -n "$slug" ] && [ "$slug" != "." ] && [ "$slug" != ".." ] \
+  || { echo "cannot derive a workspace name from: $plan" >&2; exit 2; }
+
 root=$(git rev-parse --show-toplevel)
-dir="$root/.superpowers/sdd"
+base="$root/.superpowers/sdd"
+dir="$base/$slug"
 mkdir -p "$dir"
-printf '*\n' > "$dir/.gitignore"
+printf '*\n' > "$base/.gitignore"
 cd "$dir" && pwd

skills/subagent-driven-development/scripts/task-brief

@@ -4,8 +4,9 @@
 # through the controller's context.
 #
 # Usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE]
-# Default OUTFILE: <repo-root>/.superpowers/sdd/task-<N>-brief.md
-# (per worktree; concurrent runs in the same working tree share it).
+# Default OUTFILE: <repo-root>/.superpowers/sdd/<plan-basename>/task-<N>-brief.md
+# (per plan and per worktree; concurrent runs of the SAME plan in the same
+# working tree share it).
 set -euo pipefail
 
 if [ $# -lt 2 ] || [ $# -gt 3 ]; then
@@ -20,7 +21,7 @@ n=$2
 if [ $# -eq 3 ]; then
   out=$3
 else
-  dir=$("$(cd "$(dirname "$0")" && pwd)/sdd-workspace")
+  dir=$("$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
   out="$dir/task-${n}-brief.md"
 fi
 

skills/subagent-driven-development/task-reviewer-prompt.md

@@ -52,6 +52,15 @@ Subagent (general-purpose):
     Your review is read-only on this checkout. Do not mutate the working
     tree, the index, HEAD, or branch state in any way.
 
+    ## You Do Not Dispatch Subagents
+
+    Do all of this review yourself. Never spawn a subagent to review part
+    of the diff, and never spawn another reviewer for a second opinion.
+    This process already provides every review seat the work gets; a
+    reviewer you spawn duplicates one of them at full cost, and its
+    verdict counts for nothing. If the diff feels too large for one
+    pass, review it in passes yourself and say so in your report.
+
     ## Do Not Trust the Report
 
     Treat the implementer's report as unverified claims about the code. It
@@ -75,6 +84,13 @@ Subagent (general-purpose):
     Warnings or other noise in the implementer's reported test output are
     findings — test output should be pristine.
 
+    Evidence you cannot see is not evidence that doesn't exist. If the
+    report or its test evidence looks truncated, or you cannot locate the
+    results it claims, re-read the file at its stated path — and if it is
+    genuinely missing or garbled, report that as a gap for the controller.
+    Re-running the suite to regenerate what you failed to read is not
+    verification; illegibility of the evidence is not invalidation of it.
+
     ## Part 1: Spec Compliance
 
     Compare the diff against What Was Requested:
@@ -86,6 +102,12 @@ Subagent (general-purpose):
     - **Misunderstood:** right feature built the wrong way, wrong problem
       solved
 
+    If the brief lists several files each with its own change (a batched
+    dispatch), check the diff against that list file by file: every listed
+    file must have its corresponding hunk. A listed file the diff never
+    touches is a Missing finding, no matter how clean the rest of the
+    batch looks.
+
     If a requirement cannot be verified from this diff alone (it lives in
     unchanged code or spans tasks), report it as a ⚠️ item instead of
     broadening your search.
@@ -178,11 +200,8 @@ Subagent (general-purpose):
 - `[BASE_SHA]` — commit before this task
 - `[HEAD_SHA]` — current commit
 - `[DIFF_FILE]` — REQUIRED: the path the controller wrote the review
-  package to (`scripts/review-package BASE HEAD` prints the unique path it
-  wrote; the package never enters the controller's context)
+  package to (`scripts/review-package PLAN_FILE BASE HEAD` prints the unique
+  path it wrote; the package never enters the controller's context)
 
 **Reviewer returns:** Spec Compliance verdict (✅/❌/⚠️), Strengths, Issues
 (Critical/Important/Minor), Task quality verdict
-
-A fix dispatch can address spec gaps and quality findings together;
-re-review after fixes covers both verdicts.

skills/systematic-debugging/SKILL.md

@@ -7,8 +7,6 @@ description: Use when encountering any bug, test failure, or unexpected behavior
 
 ## Overview
 
-Random fixes waste time and create new bugs. Quick patches mask underlying issues.
-
 **Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
 
 **Violating the letter of this process is violating the spirit of debugging.**
@@ -188,6 +186,7 @@ You MUST complete each phase before proceeding to the next.
    - Test passes now?
    - No other tests broken?
    - Issue actually resolved?
+   - Use the `superpowers:verification-before-completion` skill before claiming success
 
 4. **If Fix Doesn't Work**
    - STOP
@@ -282,15 +281,3 @@ These techniques are part of systematic debugging and available in this director
 - **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
 - **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
 - **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
-
-**Related skills:**
-- **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)
-- **superpowers:verification-before-completion** - Verify fix worked before claiming success
-
-## Real-World Impact
-
-From debugging sessions:
-- Systematic approach: 15-30 minutes to fix
-- Random fixes approach: 2-3 hours of thrashing
-- First-time fix rate: 95% vs 40%
-- New bugs introduced: Near zero vs common

skills/systematic-debugging/find-polluter.sh

@@ -18,9 +18,18 @@ echo "🔍 Searching for test that creates: $POLLUTION_CHECK"
 echo "Test pattern: $TEST_PATTERN"
 echo ""
 
-# Get list of test files
-TEST_FILES=$(find . -path "$TEST_PATTERN" | sort)
-TOTAL=$(echo "$TEST_FILES" | wc -l | tr -d ' ')
+# Get list of test files (find . emits ./-prefixed paths, so accept the
+# pattern written with or without a leading ./)
+TEST_PATTERN="${TEST_PATTERN#./}"
+# find -path can't match '**/' against zero directory levels, so a pattern
+# like src/**/*.test.ts would skip src/top.test.ts; also try the pattern
+# with '**/' collapsed to cover files directly under the base directory.
+TEST_FILES=$(find . \( -path "./$TEST_PATTERN" -o -path "./${TEST_PATTERN//\*\*\//}" \) | sort -u)
+if [ -z "$TEST_FILES" ]; then
+  TOTAL=0
+else
+  TOTAL=$(printf '%s\n' "$TEST_FILES" | wc -l | tr -d ' ')
+fi
 
 echo "Found $TOTAL test files"
 echo ""

skills/test-driven-development/SKILL.md

@@ -203,69 +203,25 @@ Next failing test for next feature.
 | **Clear** | Name describes behavior | `test('test1')` |
 | **Shows intent** | Demonstrates desired API | Obscures what code should do |
 
-## Why Order Matters
-
-**"I'll write tests after to verify it works"**
-
-Tests written after code pass immediately. Passing immediately proves nothing:
-- Might test wrong thing
-- Might test implementation, not behavior
-- Might miss edge cases you forgot
-- You never saw it catch the bug
-
-Test-first forces you to see the test fail, proving it actually tests something.
-
-**"I already manually tested all the edge cases"**
-
-Manual testing is ad-hoc. You think you tested everything but:
-- No record of what you tested
-- Can't re-run when code changes
-- Easy to forget cases under pressure
-- "It worked when I tried it" ≠ comprehensive
-
-Automated tests are systematic. They run the same way every time.
-
-**"Deleting X hours of work is wasteful"**
-
-Sunk cost fallacy. The time is already gone. Your choice now:
-- Delete and rewrite with TDD (X more hours, high confidence)
-- Keep it and add tests after (30 min, low confidence, likely bugs)
-
-The "waste" is keeping code you can't trust. Working code without real tests is technical debt.
-
-**"TDD is dogmatic, being pragmatic means adapting"**
-
-TDD IS pragmatic:
-- Finds bugs before commit (faster than debugging after)
-- Prevents regressions (tests catch breaks immediately)
-- Documents behavior (tests show how to use code)
-- Enables refactoring (change freely, tests catch breaks)
-
-"Pragmatic" shortcuts = debugging in production = slower.
-
-**"Tests after achieve the same goals - it's spirit not ritual"**
-
-No. Tests-after answer "What does this do?" Tests-first answer "What should this do?"
-
-Tests-after are biased by your implementation. You test what you built, not what's required. You verify remembered edge cases, not discovered ones.
-
-Tests-first force edge case discovery before implementing. Tests-after verify you remembered everything (you didn't).
-
-30 minutes of tests after ≠ TDD. You get coverage, lose proof tests work.
+When writing or changing any test, read [writing-good-tests.md](writing-good-tests.md) for the rules that keep tests honest:
+- Name the production change that would make the test fail — before writing it
+- Assert on real behavior, never on mock behavior
+- Keep test-only code in test utilities, out of production classes
+- Understand a dependency's side effects before mocking it
 
 ## Common Rationalizations
 
 | Excuse | Reality |
 |--------|---------|
 | "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
-| "I'll test after" | Tests passing immediately prove nothing. |
-| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
-| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. |
-| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
+| "I'll test after" | Tests written after pass immediately — which proves nothing. They may test the wrong thing, test the implementation instead of the behavior, or miss the edge case you forgot. You never watched it fail, so you never proved it can catch the bug. Test-first forces that failure. |
+| "Tests after achieve same goals (spirit not ritual)" | Tests-after answer "what does this do?"; tests-first answer "what should this do?" Tests written after are biased by the code you already wrote — you verify the cases you remembered, not the ones you'd have discovered. Coverage without proof the tests work. |
+| "Already manually tested" | Manual testing is ad-hoc: no record of what you covered, no way to re-run it when the code changes, easy to forget cases under pressure. "Worked when I tried it" ≠ comprehensive. Automated tests run the same way every time. |
+| "Deleting X hours is wasteful" | Sunk cost fallacy — that time is already spent either way. The real choice: rewrite with TDD (high confidence) vs. keep it and bolt tests on after (low confidence, likely bugs). Keeping code you can't trust is the waste. |
 | "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
 | "Need to explore first" | Fine. Throw away exploration, start with TDD. |
 | "Test hard = design unclear" | Listen to test. Hard to test = hard to use. |
-| "TDD will slow me down" | TDD faster than debugging. Pragmatic = test-first. |
+| "TDD will slow me down" | TDD IS the pragmatic path: catches bugs before commit, prevents regressions, lets you refactor without fear. "Pragmatic" shortcuts mean debugging in production — slower, not faster. |
 | "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. |
 | "Existing code has no tests" | You're improving it. Add tests for existing code. |
 
@@ -354,13 +310,6 @@ Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix
 
 Never fix bugs without a test.
 
-## Testing Anti-Patterns
-
-When adding mocks or test utilities, read [testing-anti-patterns.md](testing-anti-patterns.md) to avoid common pitfalls:
-- Testing mock behavior instead of real behavior
-- Adding test-only methods to production classes
-- Mocking without understanding dependencies
-
 ## Final Rule
 
 ```

skills/test-driven-development/testing-anti-patterns.md

@@ -1,299 +0,0 @@
-# Testing Anti-Patterns
-
-**Load this reference when:** writing or changing tests, adding mocks, or tempted to add test-only methods to production code.
-
-## Overview
-
-Tests must verify real behavior, not mock behavior. Mocks are a means to isolate, not the thing being tested.
-
-**Core principle:** Test what the code does, not what the mocks do.
-
-**Following strict TDD prevents these anti-patterns.**
-
-## The Iron Laws
-
-```
-1. NEVER test mock behavior
-2. NEVER add test-only methods to production classes
-3. NEVER mock without understanding dependencies
-```
-
-## Anti-Pattern 1: Testing Mock Behavior
-
-**The violation:**
-```typescript
-// ❌ BAD: Testing that the mock exists
-test('renders sidebar', () => {
-  render(<Page />);
-  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
-});
-```
-
-**Why this is wrong:**
-- You're verifying the mock works, not that the component works
-- Test passes when mock is present, fails when it's not
-- Tells you nothing about real behavior
-
-**your human partner's correction:** "Are we testing the behavior of a mock?"
-
-**The fix:**
-```typescript
-// ✅ GOOD: Test real component or don't mock it
-test('renders sidebar', () => {
-  render(<Page />);  // Don't mock sidebar
-  expect(screen.getByRole('navigation')).toBeInTheDocument();
-});
-
-// OR if sidebar must be mocked for isolation:
-// Don't assert on the mock - test Page's behavior with sidebar present
-```
-
-### Gate Function
-
-```
-BEFORE asserting on any mock element:
-  Ask: "Am I testing real component behavior or just mock existence?"
-
-  IF testing mock existence:
-    STOP - Delete the assertion or unmock the component
-
-  Test real behavior instead
-```
-
-## Anti-Pattern 2: Test-Only Methods in Production
-
-**The violation:**
-```typescript
-// ❌ BAD: destroy() only used in tests
-class Session {
-  async destroy() {  // Looks like production API!
-    await this._workspaceManager?.destroyWorkspace(this.id);
-    // ... cleanup
-  }
-}
-
-// In tests
-afterEach(() => session.destroy());
-```
-
-**Why this is wrong:**
-- Production class polluted with test-only code
-- Dangerous if accidentally called in production
-- Violates YAGNI and separation of concerns
-- Confuses object lifecycle with entity lifecycle
-
-**The fix:**
-```typescript
-// ✅ GOOD: Test utilities handle test cleanup
-// Session has no destroy() - it's stateless in production
-
-// In test-utils/
-export async function cleanupSession(session: Session) {
-  const workspace = session.getWorkspaceInfo();
-  if (workspace) {
-    await workspaceManager.destroyWorkspace(workspace.id);
-  }
-}
-
-// In tests
-afterEach(() => cleanupSession(session));
-```
-
-### Gate Function
-
-```
-BEFORE adding any method to production class:
-  Ask: "Is this only used by tests?"
-
-  IF yes:
-    STOP - Don't add it
-    Put it in test utilities instead
-
-  Ask: "Does this class own this resource's lifecycle?"
-
-  IF no:
-    STOP - Wrong class for this method
-```
-
-## Anti-Pattern 3: Mocking Without Understanding
-
-**The violation:**
-```typescript
-// ❌ BAD: Mock breaks test logic
-test('detects duplicate server', () => {
-  // Mock prevents config write that test depends on!
-  vi.mock('ToolCatalog', () => ({
-    discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
-  }));
-
-  await addServer(config);
-  await addServer(config);  // Should throw - but won't!
-});
-```
-
-**Why this is wrong:**
-- Mocked method had side effect test depended on (writing config)
-- Over-mocking to "be safe" breaks actual behavior
-- Test passes for wrong reason or fails mysteriously
-
-**The fix:**
-```typescript
-// ✅ GOOD: Mock at correct level
-test('detects duplicate server', () => {
-  // Mock the slow part, preserve behavior test needs
-  vi.mock('MCPServerManager'); // Just mock slow server startup
-
-  await addServer(config);  // Config written
-  await addServer(config);  // Duplicate detected ✓
-});
-```
-
-### Gate Function
-
-```
-BEFORE mocking any method:
-  STOP - Don't mock yet
-
-  1. Ask: "What side effects does the real method have?"
-  2. Ask: "Does this test depend on any of those side effects?"
-  3. Ask: "Do I fully understand what this test needs?"
-
-  IF depends on side effects:
-    Mock at lower level (the actual slow/external operation)
-    OR use test doubles that preserve necessary behavior
-    NOT the high-level method the test depends on
-
-  IF unsure what test depends on:
-    Run test with real implementation FIRST
-    Observe what actually needs to happen
-    THEN add minimal mocking at the right level
-
-  Red flags:
-    - "I'll mock this to be safe"
-    - "This might be slow, better mock it"
-    - Mocking without understanding the dependency chain
-```
-
-## Anti-Pattern 4: Incomplete Mocks
-
-**The violation:**
-```typescript
-// ❌ BAD: Partial mock - only fields you think you need
-const mockResponse = {
-  status: 'success',
-  data: { userId: '123', name: 'Alice' }
-  // Missing: metadata that downstream code uses
-};
-
-// Later: breaks when code accesses response.metadata.requestId
-```
-
-**Why this is wrong:**
-- **Partial mocks hide structural assumptions** - You only mocked fields you know about
-- **Downstream code may depend on fields you didn't include** - Silent failures
-- **Tests pass but integration fails** - Mock incomplete, real API complete
-- **False confidence** - Test proves nothing about real behavior
-
-**The Iron Rule:** Mock the COMPLETE data structure as it exists in reality, not just fields your immediate test uses.
-
-**The fix:**
-```typescript
-// ✅ GOOD: Mirror real API completeness
-const mockResponse = {
-  status: 'success',
-  data: { userId: '123', name: 'Alice' },
-  metadata: { requestId: 'req-789', timestamp: 1234567890 }
-  // All fields real API returns
-};
-```
-
-### Gate Function
-
-```
-BEFORE creating mock responses:
-  Check: "What fields does the real API response contain?"
-
-  Actions:
-    1. Examine actual API response from docs/examples
-    2. Include ALL fields system might consume downstream
-    3. Verify mock matches real response schema completely
-
-  Critical:
-    If you're creating a mock, you must understand the ENTIRE structure
-    Partial mocks fail silently when code depends on omitted fields
-
-  If uncertain: Include all documented fields
-```
-
-## Anti-Pattern 5: Integration Tests as Afterthought
-
-**The violation:**
-```
-✅ Implementation complete
-❌ No tests written
-"Ready for testing"
-```
-
-**Why this is wrong:**
-- Testing is part of implementation, not optional follow-up
-- TDD would have caught this
-- Can't claim complete without tests
-
-**The fix:**
-```
-TDD cycle:
-1. Write failing test
-2. Implement to pass
-3. Refactor
-4. THEN claim complete
-```
-
-## When Mocks Become Too Complex
-
-**Warning signs:**
-- Mock setup longer than test logic
-- Mocking everything to make test pass
-- Mocks missing methods real components have
-- Test breaks when mock changes
-
-**your human partner's question:** "Do we need to be using a mock here?"
-
-**Consider:** Integration tests with real components often simpler than complex mocks
-
-## TDD Prevents These Anti-Patterns
-
-**Why TDD helps:**
-1. **Write test first** → Forces you to think about what you're actually testing
-2. **Watch it fail** → Confirms test tests real behavior, not mocks
-3. **Minimal implementation** → No test-only methods creep in
-4. **Real dependencies** → You see what the test actually needs before mocking
-
-**If you're testing mock behavior, you violated TDD** - you added mocks without watching test fail against real code first.
-
-## Quick Reference
-
-| Anti-Pattern | Fix |
-|--------------|-----|
-| Assert on mock elements | Test real component or unmock it |
-| Test-only methods in production | Move to test utilities |
-| Mock without understanding | Understand dependencies first, mock minimally |
-| Incomplete mocks | Mirror real API completely |
-| Tests as afterthought | TDD - tests first |
-| Over-complex mocks | Consider integration tests |
-
-## Red Flags
-
-- Assertion checks for `*-mock` test IDs
-- Methods only called in test files
-- Mock setup is >50% of test
-- Test fails when you remove mock
-- Can't explain why mock is needed
-- Mocking "just to be safe"
-
-## The Bottom Line
-
-**Mocks are tools to isolate, not things to test.**
-
-If TDD reveals you're testing mock behavior, you've gone wrong.
-
-Fix: Test real behavior or question why you're mocking at all.

skills/test-driven-development/writing-good-tests.md

@@ -0,0 +1,198 @@
+# Writing Good Tests
+
+**Load this reference when:** writing or changing tests, adding mocks, or
+adding cleanup/helper methods for tests.
+
+## Overview
+
+A test exists to catch a specific break. Two principles govern everything
+here:
+
+```
+1. Every test names the break it catches
+2. Every test exercises the real thing
+```
+
+Strict TDD produces both naturally: a test written first and watched
+failing against real code has already proven it can fail, and only earns
+a mock when the real dependency proves slow or external.
+
+## Principle 1: Name the Break
+
+Before writing the test body, answer: **what production change should
+make this test fail — and is that change a bug or a decision?** A test
+earns its place by catching a wrong branch, missing side effect, wrong
+argument, boundary case, or broken contract.
+
+**Derive expectations independently.** Use literals and hand-checked
+fixtures; table-driven tests with literal `want` values are the preferred
+shape. An expectation computed by the code under test — or its helpers —
+passes no matter what that code does:
+
+```typescript
+// ❌ Mirror assertion: the same builder computes both sides — always true
+const expected = buildSearchQuery({ tag: 'urgent' });
+expect(buildSearchQuery({ tag: 'urgent' })).toBe(expected);
+
+// ✅ Hand-derived literal
+expect(buildSearchQuery({ tag: 'urgent' })).toBe('tag:"urgent"');
+```
+
+**No change detectors.** If only intentional decisions can fail a test —
+a constant's value, exact message wording, private structure — it fires
+on redesign and sleeps through bugs. Test the behavior that depends on
+the decision: not `expect(MAX_RETRIES).toBe(5)` but "a failing call is
+retried 5 times and the 6th attempt never happens."
+
+**Behavior, not text.** Asserting that a script, skill, or config
+contains an exact line proves only that the source is the source. Run
+scripts against controlled inputs and assert outputs, side effects, or
+exit codes. Documents that instruct agents are tested by the consuming
+agent's behavior (superpowers:writing-skills); prose for humans earns no
+test at all.
+
+**Your code, not the framework.** Test the contract your code makes at
+its boundaries — the route you register, the query you emit, the payload
+you produce. Upstream mechanics are their maintainers' tests to write
+(the classic: asserting your router invokes a registered handler — that
+is the framework's test, not yours). When upstream behavior genuinely
+surprised you, write one narrow characterization test naming the
+assumption. The same boundary applies inside your code: constructors,
+getters, constants, and trivial forwarding earn tests only when they
+validate, normalize, default, derive, enforce, or cause side effects —
+otherwise assert the first consumer-visible result that depends on them.
+
+### Gate Function
+
+```
+BEFORE writing the test body:
+  Name the production change that would make this test fail.
+
+  Cannot name one            → redesign around an observable behavior
+  "The source text changed"  → run the artifact and assert its effects
+  Only intentional decisions → change detector; test the behavior
+                               that depends on the decision
+
+  Confirm the expected value is derived without the code under test.
+  IF it reuses the code's logic or helpers:
+    Replace it with a literal or hand-checked fixture
+```
+
+## Principle 2: Exercise the Real Thing
+
+**The mock earns no assertions.** A mock assertion passes when the mock
+is present and fails when it is absent — it says nothing about the
+component. Assert the real component's behavior; if the mock is what you
+are checking, unmock it or delete the assertion.
+
+```typescript
+// ✅ Real behavior
+expect(screen.getByRole('navigation')).toBeInTheDocument();
+
+// ❌ Mock existence
+expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
+```
+
+**your human partner's correction:** "Are we testing the behavior of a
+mock?"
+
+**Mock at the right level.** Learn every side effect of the real method
+before replacing it; mock the slow or external operation and keep what
+the test depends on real. When unsure, run the test against the real
+implementation first and observe what actually needs to happen.
+
+```typescript
+// ❌ The mock swallows the config write that duplicate detection reads
+vi.mock('ToolCatalog', () => ({
+  discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
+}));
+
+// ✅ Mock only the slow server startup; the config write stays real
+vi.mock('MCPServerManager');
+```
+
+**Make doubles specific.** When arguments, call counts, or ordering are
+part of the contract, assert them — a fake that accepts anything verifies
+nothing. Give each branch (success, error, malformed) its own fixture or
+spy, so the wrong branch cannot satisfy the expectation.
+
+**Mirror real data completely.** Mock the complete structure as it exists
+in reality — all documented fields — not just the ones your test reads.
+Partial mocks fail silently when downstream code reads an omitted field:
+the test passes while integration breaks.
+
+**Production classes carry production methods only.** Cleanup that only
+tests need lives in test utilities, never as a `destroy()` on the
+production class. Ask: is this method called only from tests? Does this
+class own this resource's lifecycle? Wrong answers → test utility.
+
+**Prefer real components over complex mocks.** When mock setup outgrows
+the test logic, mocks miss methods the real components have, or tests
+break when the mock changes, switch to an integration test with real
+components. **your human partner's question:** "Do we need to be using a
+mock here?"
+
+### Gate Function
+
+```
+BEFORE adding a mock or test helper:
+  List the real method's side effects; keep the ones the test
+  depends on real — mock the slow/external level below them.
+
+  Mock responses mirror the complete real structure.
+
+  A method only tests call lives in test utilities, not production.
+
+  About to assert on the mock itself?
+    Unmock it or delete the assertion.
+```
+
+## Tests Ship With the Implementation
+
+The TDD cycle — failing test, minimal implementation, refactor — is what
+"complete" means. Ship the tests the behavior needs and only those:
+trivial code and human prose earn none, and a test written to satisfy
+process costs maintenance forever.
+
+## The Mutation Check
+
+Before finishing, mentally mutate the production code; at least one test
+should fail for each realistic mutation:
+
+- Wrong constant or argument
+- Wrong branch handler
+- Missing state change or side effect
+- Empty or default return
+- Missing validation for zero, empty, nil, unauthorized, or malformed input
+
+A mutation nothing catches marks the behavior as unprotected — or the
+test as tautological.
+
+## Quick Reference
+
+| When you... | Do |
+|-------------|-----|
+| Write any test | Name the break it catches — a bug, not a decision |
+| Build an expected value | Derive it by hand; never with the code under test |
+| Test a script or document | Run it / pressure-test its consumer; never grep its text |
+| Reach for a dependency test | Test your boundary contract, not their documented mechanics |
+| Want to assert on a mocked element | Test the real component, or unmock it |
+| Are about to mock a method | Learn its side effects; mock the slow/external level |
+| Build a mock response | Mirror the real structure completely |
+| Need cleanup only tests use | Put it in test utilities |
+| Watch mock setup balloon | Switch to an integration test with real components |
+| Finish a test file | Run the mutation check |
+
+## Warning Signs
+
+- Setup and assertion share the same object, guaranteeing equality
+- The test can fail only through a panic, crash, or missing selector
+- The test fails on every intentional change, never on accidental breakage
+- Expected values are hidden behind loops, builders, or helpers
+- The test greps source text, or asserts a removed symbol stays removed
+- The test would still matter if only the framework remained
+- The test exists for coverage, checking no side effect or outcome
+- An assertion checks a `*-mock` test ID, or fails if you remove the mock
+- A method is called only from test files
+- Mock setup is more than half the test, or you can't explain why the mock is needed
+- Mocking "just to be safe"

skills/using-git-worktrees/SKILL.md

@@ -156,47 +156,12 @@ Ready to implement <feature-name>
 | Tests fail during baseline | Report failures + ask |
 | No package.json/Cargo.toml | Skip dependency install |
 
-## Common Mistakes
+## Common Rationalizations
 
-### Fighting the harness
-
-- **Problem:** Using `git worktree add` when the platform already provides isolation
-- **Fix:** Step 0 detects existing isolation. Step 1a defers to native tools.
-
-### Skipping detection
-
-- **Problem:** Creating a nested worktree inside an existing one
-- **Fix:** Always run Step 0 before creating anything
-
-### Skipping ignore verification
-
-- **Problem:** Worktree contents get tracked, pollute git status
-- **Fix:** Always use `git check-ignore` before creating project-local worktree
-
-### Assuming directory location
-
-- **Problem:** Creates inconsistency, violates project conventions
-- **Fix:** Follow priority: explicit instructions > existing project-local directory > default
-
-### Proceeding with failing tests
-
-- **Problem:** Can't distinguish new bugs from pre-existing issues
-- **Fix:** Report failures, get explicit permission to proceed
-
-## Red Flags
-
-**Never:**
-- Create a worktree when Step 0 detects existing isolation
-- Use `git worktree add` when you have a native worktree tool (e.g., `EnterWorktree`). This is the #1 mistake — if you have it, use it.
-- Skip Step 1a by jumping straight to Step 1b's git commands
-- Create worktree without verifying it's ignored (project-local)
-- Skip baseline test verification
-- Proceed with failing tests without asking
-
-**Always:**
-- Run Step 0 detection first
-- Prefer native tools over git fallback
-- Follow directory priority: explicit instructions > existing project-local directory > default
-- Verify directory is ignored for project-local
-- Auto-detect and run project setup
-- Verify clean test baseline
+| Excuse | Reality |
+|--------|---------|
+| "I'm obviously not in a worktree — no need to check" | Run Step 0. Harness-created isolation and submodules both fool eyeballing; the detection commands settle it. |
+| "`git worktree add` is quicker than hunting for a native tool" | A native tool (e.g. `EnterWorktree`) owns placement, branching, and cleanup. Bypassing it is the #1 mistake — it creates phantom state your harness can't see or manage. |
+| "The worktree directory is surely ignored already" | Run `git check-ignore`. An unignored worktree directory commits the whole tree into the repo. |
+| "Any directory name works" | Explicit instructions beat an existing project-local directory, which beats the `.worktrees/` default. |
+| "The workspace is fresh — baseline tests can wait" | A dirty baseline makes every later failure ambiguous. Run the tests now; proceeding past failures is your human partner's call. |

skills/using-superpowers/SKILL.md

@@ -56,6 +56,7 @@ If your harness appears here, read its reference file for special instructions:
 - Codex: `references/codex-tools.md`
 - Pi: `references/pi-tools.md`
 - Antigravity: `references/antigravity-tools.md`
+- Hermes Agent: `references/hermes-tools.md`
 
 ## User Instructions
 

skills/using-superpowers/references/antigravity-tools.md

@@ -4,7 +4,7 @@ Skills speak in actions ("dispatch a subagent", "create a todo", "read a file").
 
 | Action skills request | Antigravity CLI equivalent |
 |----------------------|----------------------|
-| Dispatch a subagent (`Subagent (general-purpose):` template) | `invoke_subagent` with a built-in `TypeName` — `self` for full-capability work, `research` for read-only (see [Subagent support](#subagent-support)) |
+| Dispatch a subagent (`Subagent (general-purpose):` template) | `invoke_subagent` with a built-in `TypeName` — `self` for full-capability work, `research` for read-only |
 | Task tracking ("create a todo", "mark complete") | a **task artifact** — `write_to_file` with `IsArtifact: true` and `ArtifactType: "task"` (see [Task tracking](#task-tracking)). **Not** `manage_task`, which manages background processes. |
 
 ## Task tracking

skills/using-superpowers/references/codex-tools.md

@@ -7,7 +7,76 @@ Add to your Codex config (`~/.codex/config.toml`):
 multi_agent = true
 ```
 
-This enables `spawn_agent`, `wait_agent`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`. When using subagent-driven-development, you should always close implementer and reviewer subagents when they have finished all their work.
+This enables the multi-agent tools that skills like
+`dispatching-parallel-agents` and `subagent-driven-development` use.
+Which tools you get depends on the multi-agent version your model
+preset selects (current presets run V2; older ones run V1). Trust your
+actual tool list over any table — including this one — when they
+disagree.
+
+- **Spawning:** give children a clean context with
+  `spawn_agent {fork_turns: "none"}`; the default `"all"` copies your
+  entire transcript into the child. On Codex 0.145+, role files under
+  `~/.codex/agents/` attach to isolated forks via `agent_type`.
+  Full-history forks accept `model` and `reasoning_effort` overrides
+  (only `agent_type` is refused there) — isolated forks are the SDD
+  default for context hygiene, not because overrides require them.
+- **Fix rounds:** resume the implementer with `followup_task` — it
+  delivers your message, triggers a turn, and transparently reloads a
+  child the harness evicted. Never dispatch a fresh implementer on the
+  theory that a spawned agent cannot be messaged again; on V2 it
+  always can.
+- **Lifecycle:** V2 has no `close_agent`. Finished children are
+  evicted automatically when slots are needed; leaving them unclosed
+  costs nothing. Only V1 sessions have `close_agent` — there, close
+  reviewers when their review returns, and close each implementer
+  after its task's review passes.
+- **Model names:** never copy a model name from a skill, table, or old
+  session into `spawn_agent` without checking it against your current
+  spawn allowlist — V2 accepts only V2-capable presets and hard-errors
+  on the rest.
+
+## Waiting on children
+
+`wait_agent` is an event subscription, not a poll: a long wait wakes
+the moment a child produces mailbox activity, with the same latency as
+a short one. Short-timeout polling buys nothing and costs a tool call —
+and a context rebill — per poll. In measured sessions, roughly
+two-thirds of all wait calls were short polls that timed out.
+
+- While you still have local work, do not wait at all. A completed
+  child's final answer is pushed into your mailbox and arrives with
+  your next turn.
+- When you are genuinely idle with children outstanding, wait in
+  bounded stretches: `wait_agent` with `timeout_ms` 300000-600000
+  (5-10 minutes). After each stretch — wake or timeout — post one
+  status line, run `list_agents`, and chase any child that finished
+  without reporting. Never stack polls shorter than five minutes; the
+  event subscription wakes a bounded stretch just as fast as a short
+  one.
+- Completion mail cannot wake an idle controller (it is delivered
+  without triggering a turn); covering that idle window is
+  `wait_agent`'s only job. A stretch that times out with no activity
+  is your cue to reconcile, not to shorten the next stretch.
+
+## Model routing on spawns
+
+Every `spawn_agent` you issue — including when you are yourself a
+spawned child running a fan-out — sets `model` AND `reasoning_effort`
+explicitly, per the Model Selection rules of the skill you are
+executing. Setting `model` alone is a trap: the child's effort
+silently resets to that model's default, not to yours.
+
+Ask your human partner to add a machine-level backstop to
+`~/.codex/config.toml` so any spawn that slips through still routes to
+a deliberate tier instead of silently inheriting the session's most
+expensive model:
+
+```toml
+[agents]
+default_subagent_model = "<a mid-tier model from your spawn allowlist>"
+default_subagent_reasoning_effort = "medium"
+```
 
 ## Environment Detection
 

skills/using-superpowers/references/gemini-tools.md

@@ -0,0 +1,63 @@
+# Gemini CLI Tool Mapping
+
+Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Gemini CLI these resolve to the tools below.
+
+| Action skills request | Gemini CLI equivalent |
+|----------------------|----------------------|
+| Read a file | `read_file` |
+| Read multiple files at once | `read_many_files` |
+| Create a new file | `write_file` |
+| Edit a file | `replace` |
+| Run a shell command | `run_shell_command` |
+| Search file contents | `grep_search` |
+| Find files by name | `glob` |
+| List files and subdirectories | `list_directory` |
+| Fetch a URL | `web_fetch` |
+| Search the web | `google_web_search` |
+| Invoke a skill | `activate_skill` |
+| Dispatch a subagent (`Subagent (general-purpose):` template) | `invoke_agent` with `agent_name: "generalist"` (invocable via `@generalist` chat syntax — see [Subagent support](#subagent-support)) |
+| Multiple parallel dispatches | Multiple `invoke_agent` calls in the same response |
+| Task tracking ("create a todo", "mark complete") | `write_todos` (statuses: pending, in_progress, completed, cancelled, blocked) |
+
+## Instructions file
+
+When a skill mentions "your instructions file", on Gemini CLI this is **`GEMINI.md`**. Gemini CLI loads `GEMINI.md` hierarchically: global at `~/.gemini/GEMINI.md`, project-level files in workspace directories and their ancestors, and sub-directory `GEMINI.md` files when a tool accesses files in those directories.
+
+## Personal skills directory
+
+User-level skills live at **`~/.gemini/skills/`**, with **`~/.agents/skills/`** as a cross-runtime alias (shared with Codex and Copilot CLI). When both directories exist at the same scope, `.agents/skills/` takes precedence. Each skill is a subdirectory containing a `SKILL.md` (with `name` and `description` frontmatter).
+
+## Subagent support
+
+Gemini CLI dispatches subagents through the `invoke_agent` tool, which takes `agent_name` and `prompt` parameters. The same dispatch is also surfaced as a chat-syntax shortcut: typing `@generalist <prompt>` is equivalent to calling `invoke_agent` with `agent_name: "generalist"`. Built-in agent names include `generalist`, `cli_help`, `codebase_investigator`, and (with browser tooling enabled) `browser_agent`.
+
+Skills dispatch with `Subagent (general-purpose):` and either reference a prompt-template file (e.g., `superpowers:subagent-driven-development`'s `./implementer-prompt.md`) or supply an inline prompt. On Gemini CLI:
+
+| Skill dispatch form | Gemini CLI equivalent |
+|---------------------|----------------------|
+| References a `*-prompt.md` template (implementer, task-reviewer, code-reviewer, etc.) | Fill the template, then `invoke_agent` with `agent_name: "generalist"` and the filled prompt |
+| References `superpowers:requesting-code-review`'s `./code-reviewer.md` | `invoke_agent` with `agent_name: "generalist"` and the filled review template |
+| Inline prompt (no template referenced) | `invoke_agent` with `agent_name: "generalist"` and your inline prompt |
+
+### Prompt filling
+
+Skills provide prompt templates with placeholders like `{WHAT_WAS_IMPLEMENTED}` or `[FULL TEXT of task]`. Fill all placeholders before passing the complete prompt to `invoke_agent`. The prompt template itself contains the agent's role, review criteria, and expected output format — the subagent will follow it.
+
+### Parallel dispatch
+
+Gemini CLI supports parallel subagent dispatch. Issue multiple `invoke_agent` calls in the same response (or multiple `@generalist` invocations in one prompt) to run independent subagent work in parallel. Keep dependent tasks sequential, but do not serialize independent subagent tasks just to preserve a simpler history.
+
+## Additional Gemini CLI tools
+
+These tools are unique to Gemini CLI:
+
+| Tool | Purpose |
+|------|---------|
+| `save_memory` (legacy) | Persist facts across sessions when `experimental.memoryV2 = false` |
+| `get_internal_docs` | Look up Gemini CLI's bundled documentation |
+| `ask_user` | Pose structured questions to the user (text / single-select / multi-select) |
+| `enter_plan_mode` / `exit_plan_mode` | Switch into and out of read-only plan mode |
+| `update_topic` | Update the current conversation's topic / strategic-intent metadata |
+| `complete_task` | Signal that a Gemini subagent has completed and return its result to the parent agent |
+| `tracker_create_task`, `tracker_update_task`, `tracker_get_task`, `tracker_list_tasks`, `tracker_add_dependency`, `tracker_visualize` | Rich task tracker with dependency and visualization support |
+| `read_mcp_resource`, `list_mcp_resources` | MCP resource access |

skills/using-superpowers/references/hermes-tools.md

@@ -0,0 +1,56 @@
+# Hermes Agent Tool Mapping
+
+Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Hermes Agent these resolve to the tools below.
+
+## Tools
+
+| Action skills request | Hermes tool |
+|---|---|
+| Read a file | `read_file` |
+| Create a new file | `write_file` |
+| Edit a file (targeted patch) | `patch` |
+| Run a shell command | `terminal` |
+| Search file contents | `search_files` |
+| Find files by name | `terminal` with `find` |
+| Fetch a URL / read a webpage | `web_extract(urls=[...])` |
+| Search the web | `web_search(query=...)` |
+| Dispatch a subagent | `delegate_task(goal=..., context=..., toolsets=[...], role="leaf")` |
+| Task tracking | `todo` tool |
+| Invoke a skill | `skill_view("skill-name")` |
+
+## Instructions file
+
+When a skill mentions "your instructions file," on Hermes Agent this is **`AGENTS.md`** in the project directory, or **`SOUL.md`** globally at `~/.hermes/SOUL.md`.
+
+## Invoking a skill
+
+Hermes Agent has a `skills` toolset with `skill_view` and `skills_list` tools.
+To invoke a superpowers skill, use:
+
+```
+skill_view("brainstorming")
+skill_view("test-driven-development")
+```
+
+If `skill_view` cannot find a superpowers skill (it may not appear in the catalog
+until the plugin fully registers it), fall back to reading the SKILL.md directly:
+
+```
+read_file(path="~/.hermes/plugins/superpowers/skills/<skill-name>/SKILL.md")
+```
+
+This fallback is the same mechanism used by other harnesses without native skill loading.
+
+## Subagent dispatch
+
+Use `delegate_task` to spawn isolated subagents for parallel or sequential workstreams:
+
+```
+delegate_task(goal="...", context="...", toolsets=[...], role="leaf")
+```
+
+If `delegate_task` is unavailable, do the work inline rather than inventing tool calls.
+
+## Task tracking
+
+Use the `todo` tool for task tracking within a session. For multi-agent task boards, use `hermes kanban` CLI if available. Treat older `TodoWrite` references as the task-tracking action.

skills/verification-before-completion/SKILL.md

@@ -7,8 +7,6 @@ description: Use when about to claim work is complete, fixed, or passing, before
 
 ## Overview
 
-Claiming work is complete without verification is dishonesty, not efficiency.
-
 **Core principle:** Evidence before claims, always.
 
 **Violating the letter of this rule is violating the spirit of this rule.**
@@ -105,15 +103,6 @@ Skip any step = lying, not verifying
 ❌ Trust agent report
 ```
 
-## Why This Matters
-
-From 24 failure memories:
-- your human partner said "I don't believe you" - trust broken
-- Undefined functions shipped - would crash
-- Missing requirements shipped - incomplete features
-- Time wasted on false completion → redirect → rework
-- Violates: "Honesty is a core value. If you lie, you'll be replaced."
-
 ## When To Apply
 
 **ALWAYS before:**
@@ -129,11 +118,3 @@ From 24 failure memories:
 - Paraphrases and synonyms
 - Implications of success
 - ANY communication suggesting completion/correctness
-
-## The Bottom Line
-
-**No shortcuts for verification.**
-
-Run the command. Read the output. THEN claim the result.
-
-This is non-negotiable.

skills/writing-plans/SKILL.md

@@ -66,6 +66,9 @@ independently testable deliverable.
 
 **Tech Stack:** [Key technologies/libraries]
 
+**Spec:** [path to the spec/design doc this plan implements — the plan
+argues from the spec, so the spec travels with it; executors read both]
+
 ## Global Constraints
 
 [The spec's project-wide requirements — version floors, dependency limits,
@@ -135,12 +138,6 @@ Every step must contain the actual content an engineer needs. These are **plan f
 - 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.

skills/writing-skills/SKILL.md

@@ -9,7 +9,7 @@ description: Use when creating new skills, editing existing skills, or verifying
 
 **Writing skills IS Test-Driven Development applied to process documentation.**
 
-**Personal skills live in your runtime's skills directory** 
+**Personal skills live in your runtime's skills directory** (`~/.claude/skills/` on Claude Code) — see [codex-tools.md](../using-superpowers/references/codex-tools.md) or [gemini-tools.md](../using-superpowers/references/gemini-tools.md) for the path on those runtimes. Codex, Copilot CLI, and Gemini CLI all also recognize `~/.agents/skills/` as a cross-runtime alias.
 
 You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
 
@@ -677,13 +677,3 @@ How future agents find your skill:
 6. **Loads example** (only when implementing)
 
 **Optimize for this flow** - put searchable terms early and often.
-
-## The Bottom Line
-
-**Creating skills IS TDD for process documentation.**
-
-Same Iron Law: No skill without failing test first.
-Same cycle: RED (baseline) → GREEN (write skill) → REFACTOR (close loopholes).
-Same benefits: Better quality, fewer surprises, bulletproof results.
-
-If you follow TDD for code, follow it for skills. It's the same discipline applied to documentation.

skills/writing-skills/render-graphs.js

@@ -13,9 +13,9 @@
  * Requires: graphviz (dot) installed on system
  */
 
-const fs = require('fs');
-const path = require('path');
-const { execSync } = require('child_process');
+import * as fs from 'fs';
+import * as path from 'path';
+import { execFileSync } from 'child_process';
 
 function extractDotBlocks(markdown) {
   const blocks = [];
@@ -69,7 +69,7 @@ ${bodies.join('\n\n')}
 
 function renderToSvg(dotContent) {
   try {
-    return execSync('dot -Tsvg', {
+    return execFileSync('dot', ['-Tsvg'], {
       input: dotContent,
       encoding: 'utf-8',
       maxBuffer: 10 * 1024 * 1024
@@ -107,9 +107,10 @@ function main() {
     process.exit(1);
   }
 
-  // Check if dot is available
+  // Check if dot is available. Run the binary directly rather than probing
+  // with `which`, which is not a command on Windows.
   try {
-    execSync('which dot', { encoding: 'utf-8' });
+    execFileSync('dot', ['-V'], { stdio: 'ignore' });
   } catch {
     console.error('Error: graphviz (dot) not found. Install with:');
     console.error('  brew install graphviz    # macOS');

tests/antigravity/test-antigravity-tools.sh

@@ -2,8 +2,9 @@
 # Validate the Antigravity (agy) integration. agy installs the existing plugin
 # directly (`agy plugin install <repo-url>`): it loads the bundled skills and
 # runs the SessionStart hook for bootstrap, so there is no agy-specific scaffold
-# to test. What IS agy-specific is the tool mapping — agy has no `Skill` tool and
-# loads skills by reading SKILL.md with view_file — and SKILL.md pointing at it.
+# to test. What IS agy-specific is the tool mapping — subagent dispatch via
+# invoke_subagent (self/research types) and task tracking via a task artifact —
+# and SKILL.md pointing at it.
 #
 # Mirrors tests/pi/test-pi-extension.mjs's "tools reference documents
 # harness-specific mappings" check. CI-safe: does not require `agy` installed.
@@ -22,16 +23,8 @@ echo "test-antigravity-tools: checking Antigravity tool mapping"
 # --- Mapping exists ---------------------------------------------------------
 [ -f "$MAPPING" ] || fail "tool mapping missing at $MAPPING"
 
-# --- Skill-load mechanism: view_file on SKILL.md (IsSkillFile), no Skill tool -
-grep -qiE "view_file" "$MAPPING" \
-  || fail "mapping does not document view_file as the file/skill-read tool"
-grep -qiE "SKILL\.md" "$MAPPING" \
-  || fail "mapping does not document reading SKILL.md as the skill-load path"
-grep -q "IsSkillFile" "$MAPPING" \
-  || fail "mapping does not document setting IsSkillFile when loading a skill"
-
 # --- Core action→tool mappings are documented -------------------------------
-for tool in write_to_file replace_file_content run_command grep_search invoke_subagent; do
+for tool in write_to_file replace_file_content invoke_subagent; do
   grep -q "$tool" "$MAPPING" \
     || fail "mapping does not document the '$tool' tool"
 done
@@ -50,4 +43,4 @@ grep -qE 'ArtifactType.*task|task. artifact' "$MAPPING" \
 grep -q "antigravity-tools.md" "$SKILL" \
   || fail "SKILL.md Platform Adaptation does not reference antigravity-tools.md"
 
-echo "PASS: Antigravity tool mapping valid (view_file skill-load, agy tools, SKILL.md link)"
+echo "PASS: Antigravity tool mapping valid (subagent dispatch, task artifact, SKILL.md link)"

tests/claude-code/run-skill-tests.sh

@@ -25,7 +25,8 @@ fi
 # Parse command line arguments
 VERBOSE=false
 SPECIFIC_TEST=""
-TIMEOUT=600  # Default 10 minute timeout per test
+TIMEOUT=900  # Per-test-file budget; must exceed the file's worst case
+             # (test-subagent-driven-development.sh: 9 prompts x 90s each)
 RUN_INTEGRATION=false
 
 while [[ $# -gt 0 ]]; do
@@ -52,7 +53,7 @@ while [[ $# -gt 0 ]]; do
             echo "Options:"
             echo "  --verbose, -v        Show verbose output"
             echo "  --test, -t NAME      Run only the specified test"
-            echo "  --timeout SECONDS    Set timeout per test (default: 300)"
+            echo "  --timeout SECONDS    Set timeout per test (default: 900)"
             echo "  --integration, -i    Run integration tests (slow, 10-30 min)"
             echo "  --help, -h           Show this help"
             echo ""

tests/claude-code/test-helpers.sh

@@ -30,12 +30,14 @@ run_claude() {
 
 # Check if output contains a pattern
 # Usage: assert_contains "output" "pattern" "test name"
+# Matching is case-insensitive: patterns are prose keywords, and models
+# freely capitalize skill terms ("Do Not Trust", "Spec Compliance").
 assert_contains() {
     local output="$1"
     local pattern="$2"
     local test_name="${3:-test}"
 
-    if echo "$output" | grep -q "$pattern"; then
+    if echo "$output" | grep -qi "$pattern"; then
         echo "  [PASS] $test_name"
         return 0
     else
@@ -54,7 +56,7 @@ assert_not_contains() {
     local pattern="$2"
     local test_name="${3:-test}"
 
-    if echo "$output" | grep -q "$pattern"; then
+    if echo "$output" | grep -qi "$pattern"; then
         echo "  [FAIL] $test_name"
         echo "  Did not expect to find: $pattern"
         echo "  In output:"
@@ -74,7 +76,7 @@ assert_count() {
     local expected="$3"
     local test_name="${4:-test}"
 
-    local actual=$(echo "$output" | grep -c "$pattern" || echo "0")
+    local actual=$(echo "$output" | grep -ci "$pattern" || echo "0")
 
     if [ "$actual" -eq "$expected" ]; then
         echo "  [PASS] $test_name (found $actual instances)"
@@ -98,16 +100,20 @@ assert_order() {
     local test_name="${4:-test}"
 
     # Get line numbers where patterns appear
-    local line_a=$(echo "$output" | grep -n "$pattern_a" | head -1 | cut -d: -f1)
-    local line_b=$(echo "$output" | grep -n "$pattern_b" | head -1 | cut -d: -f1)
+    local line_a=$(echo "$output" | grep -ni "$pattern_a" | head -1 | cut -d: -f1)
+    local line_b=$(echo "$output" | grep -ni "$pattern_b" | head -1 | cut -d: -f1)
 
     if [ -z "$line_a" ]; then
         echo "  [FAIL] $test_name: pattern A not found: $pattern_a"
+        echo "  In output:"
+        echo "$output" | sed 's/^/    /'
         return 1
     fi
 
     if [ -z "$line_b" ]; then
         echo "  [FAIL] $test_name: pattern B not found: $pattern_b"
+        echo "  In output:"
+        echo "$output" | sed 's/^/    /'
         return 1
     fi
 

tests/claude-code/test-sdd-workspace.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
-# Tests for the SDD workspace: scripts/sdd-workspace resolves a self-ignoring
-# working-tree directory for SDD artifacts, and the SDD scripts write into it.
+# Tests for the SDD workspace: scripts/sdd-workspace resolves a self-ignoring,
+# PER-PLAN working-tree directory for SDD artifacts, and the SDD scripts write
+# into their plan's directory.
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -35,26 +36,72 @@ main() {
     local repo
     repo="$(cd "$TEST_ROOT/repo" && git rev-parse --show-toplevel)"
 
-    local dir
-    dir="$(cd "$repo" && "$SDD_SCRIPTS/sdd-workspace")"
+    cat > "$repo/plan-a.md" <<'PLAN'
+# Plan A
 
-    if [[ "$dir" == "$repo/.superpowers/sdd" ]]; then
-        pass "prints <repo-root>/.superpowers/sdd"
+## Task 1: First thing
+
+Do the first thing.
+PLAN
+    cat > "$repo/plan-b.md" <<'PLAN'
+# Plan B
+
+## Task 1: Other thing
+
+Do the other thing.
+PLAN
+
+    # --- argument validation ---
+    local rc=0
+    (cd "$repo" && "$SDD_SCRIPTS/sdd-workspace" >/dev/null 2>&1) || rc=$?
+    if [[ "$rc" -eq 2 ]]; then
+        pass "sdd-workspace without a plan errors with exit 2"
     else
-        fail "prints <repo-root>/.superpowers/sdd"
-        echo "    got: $dir"
+        fail "sdd-workspace without a plan errors with exit 2"
+        echo "    exit: $rc"
+    fi
+
+    rc=0
+    (cd "$repo" && "$SDD_SCRIPTS/sdd-workspace" no-such-plan.md >/dev/null 2>&1) || rc=$?
+    if [[ "$rc" -eq 2 ]]; then
+        pass "sdd-workspace with a missing plan file errors with exit 2"
+    else
+        fail "sdd-workspace with a missing plan file errors with exit 2"
+        echo "    exit: $rc"
+    fi
+
+    # --- per-plan resolution ---
+    local dir_a dir_b
+    dir_a="$(cd "$repo" && "$SDD_SCRIPTS/sdd-workspace" plan-a.md)"
+    dir_b="$(cd "$repo" && "$SDD_SCRIPTS/sdd-workspace" plan-b.md)"
+
+    if [[ "$dir_a" == "$repo/.superpowers/sdd/plan-a" ]]; then
+        pass "prints <repo-root>/.superpowers/sdd/<plan-basename>"
+    else
+        fail "prints <repo-root>/.superpowers/sdd/<plan-basename>"
+        echo "    got: $dir_a"
+    fi
+
+    if [[ "$dir_a" != "$dir_b" && -d "$dir_a" && -d "$dir_b" ]]; then
+        pass "two plans resolve to two distinct directories"
+    else
+        fail "two plans resolve to two distinct directories"
+        echo "    a: $dir_a"
+        echo "    b: $dir_b"
     fi
 
     if [[ -f "$repo/.superpowers/sdd/.gitignore" && "$(cat "$repo/.superpowers/sdd/.gitignore")" == "*" ]]; then
-        pass "self-ignoring .gitignore created with '*'"
+        pass "self-ignoring .gitignore created at .superpowers/sdd/ with '*'"
     else
-        fail "self-ignoring .gitignore created with '*'"
+        fail "self-ignoring .gitignore created at .superpowers/sdd/ with '*'"
     fi
 
-    printf 'x\n' > "$repo/.superpowers/sdd/artifact.md"
+    printf 'x\n' > "$dir_a/artifact.md"
     local status
     status="$(cd "$repo" && git status --porcelain)"
-    if [[ -z "$status" ]]; then
+    # plan-a.md/plan-b.md are intentionally untracked fixture files; only the
+    # workspace must be invisible.
+    if [[ "$status" != *".superpowers"* ]]; then
         pass "workspace invisible to git status"
     else
         fail "workspace invisible to git status"
@@ -64,67 +111,78 @@ main() {
     ( cd "$repo" && git add -A )
     local staged
     staged="$(cd "$repo" && git diff --cached --name-only)"
-    if [[ -z "$staged" ]]; then
+    if [[ "$staged" != *".superpowers"* ]]; then
         pass "git add -A does not stage the workspace"
     else
         fail "git add -A does not stage the workspace"
         echo "    staged: $staged"
     fi
 
-    cat > "$repo/plan.md" <<'PLAN'
-# Plan
-
-## Task 1: First thing
-
-Do the first thing.
-PLAN
-
+    # --- task-brief lands in its plan's directory ---
     local brief_out brief_path
-    brief_out="$(cd "$repo" && "$SDD_SCRIPTS/task-brief" plan.md 1)"
+    brief_out="$(cd "$repo" && "$SDD_SCRIPTS/task-brief" plan-a.md 1)"
     brief_path="$(printf '%s\n' "$brief_out" | sed -n 's/^wrote \(.*\): [0-9][0-9]* lines$/\1/p')"
-    case "$brief_path" in
-        "$repo/.superpowers/sdd/"*) pass "task-brief writes its brief under the workspace" ;;
-        *)
-            fail "task-brief writes its brief under the workspace"
-            echo "    got: $brief_path"
-            ;;
-    esac
+    if [[ "$brief_path" == "$repo/.superpowers/sdd/plan-a/task-1-brief.md" ]]; then
+        pass "task-brief writes its brief under the plan's workspace"
+    else
+        fail "task-brief writes its brief under the plan's workspace"
+        echo "    got: $brief_path"
+    fi
 
+    # --- review-package takes the plan first and lands in its directory ---
     local git_id=(-c user.email=t@example.com -c user.name=t -c commit.gpgsign=false)
     ( cd "$repo" \
-        && git add plan.md \
         && git "${git_id[@]}" commit -qm c1 \
         && printf 'y\n' > f && git add f \
         && git "${git_id[@]}" commit -qm c2 )
     local rp_out rp_path
-    rp_out="$(cd "$repo" && "$SDD_SCRIPTS/review-package" HEAD~1 HEAD)"
+    rp_out="$(cd "$repo" && "$SDD_SCRIPTS/review-package" plan-a.md HEAD~1 HEAD)"
     rp_path="$(printf '%s\n' "$rp_out" | sed -n 's/^wrote \(.*\): [0-9].*$/\1/p')"
     case "$rp_path" in
-        "$repo/.superpowers/sdd/"*) pass "review-package writes its diff under the workspace" ;;
+        "$repo/.superpowers/sdd/plan-a/review-"*.diff)
+            pass "review-package writes its diff under the plan's workspace" ;;
         *)
-            fail "review-package writes its diff under the workspace"
+            fail "review-package writes its diff under the plan's workspace"
             echo "    got: $rp_path"
             ;;
     esac
 
+    rc=0
+    (cd "$repo" && "$SDD_SCRIPTS/review-package" HEAD~1 HEAD >/dev/null 2>&1) || rc=$?
+    if [[ "$rc" -eq 2 ]]; then
+        pass "review-package without a plan errors with exit 2"
+    else
+        fail "review-package without a plan errors with exit 2"
+        echo "    exit: $rc"
+    fi
+
+    local rp_explicit
+    rp_explicit="$(cd "$repo" && "$SDD_SCRIPTS/review-package" plan-a.md HEAD~1 HEAD "$TEST_ROOT/explicit.diff")"
+    if [[ -s "$TEST_ROOT/explicit.diff" && "$rp_explicit" == *"$TEST_ROOT/explicit.diff"* ]]; then
+        pass "review-package honors an explicit OUTFILE"
+    else
+        fail "review-package honors an explicit OUTFILE"
+        echo "    got: $rp_explicit"
+    fi
+
     # --- Worktree isolation: a linked worktree resolves its own workspace ---
     local wt="$TEST_ROOT/wt"
     ( cd "$repo" && git worktree add -q "$wt" -b wt-feature )
     local wt_root wt_dir
     wt_root="$(cd "$wt" && git rev-parse --show-toplevel)"
-    wt_dir="$(cd "$wt" && "$SDD_SCRIPTS/sdd-workspace")"
-    if [[ "$wt_dir" == "$wt_root/.superpowers/sdd" && "$wt_dir" != "$dir" ]]; then
+    wt_dir="$(cd "$wt" && "$SDD_SCRIPTS/sdd-workspace" plan-a.md)"
+    if [[ "$wt_dir" == "$wt_root/.superpowers/sdd/plan-a" && "$wt_dir" != "$dir_a" ]]; then
         pass "linked worktree resolves its own distinct workspace"
     else
         fail "linked worktree resolves its own distinct workspace"
-        echo "    main: $dir"
+        echo "    main: $dir_a"
         echo "    wt:   $wt_dir"
     fi
 
-    printf 'y\n' > "$wt/.superpowers/sdd/artifact.md"
+    printf 'y\n' > "$wt_dir/artifact.md"
     local wt_status
     wt_status="$(cd "$wt" && git status --porcelain)"
-    if [[ -z "$wt_status" ]]; then
+    if [[ "$wt_status" != *".superpowers"* ]]; then
         pass "worktree workspace invisible to git status"
     else
         fail "worktree workspace invisible to git status"

tests/claude-code/test-subagent-driven-development.sh

@@ -96,13 +96,13 @@ echo "Test 5: Spec compliance reviewer mindset..."
 
 output=$(run_claude "What is the spec compliance reviewer's attitude toward the implementer's report in subagent-driven-development?" "$CLAUDE_PROMPT_TIMEOUT")
 
-if assert_contains "$output" "not trust\|don't trust\|skeptical\|verify.*independently\|suspiciously" "Reviewer is skeptical"; then
+if assert_contains "$output" "not.*trust\|don't trust\|skeptical\|verify.*independently\|suspiciously" "Reviewer is skeptical"; then
     : # pass
 else
     exit 1
 fi
 
-if assert_contains "$output" "read.*code\|inspect.*code\|verify.*code" "Reviewer reads code"; then
+if assert_contains "$output" "read.*code\|inspect.*code\|verify.*code\|read.*diff\|trust.*diff" "Reviewer reads code"; then
     : # pass
 else
     exit 1

tests/codex/test-package-codex-plugin.sh

@@ -0,0 +1,297 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+SCRIPT_UNDER_TEST="$REPO_ROOT/scripts/package-codex-plugin.sh"
+
+FAILURES=0
+TEST_ROOT="$(mktemp -d)"
+
+cleanup() {
+  rm -rf "$TEST_ROOT"
+}
+trap cleanup EXIT
+
+pass() {
+  echo "  [PASS] $1"
+}
+
+fail() {
+  echo "  [FAIL] $1"
+  FAILURES=$((FAILURES + 1))
+}
+
+assert_equals() {
+  local actual="$1"
+  local expected="$2"
+  local description="$3"
+
+  if [[ "$actual" == "$expected" ]]; then
+    pass "$description"
+  else
+    fail "$description"
+    echo "    expected: $expected"
+    echo "    actual:   $actual"
+  fi
+}
+
+assert_contains() {
+  local haystack="$1"
+  local needle="$2"
+  local description="$3"
+
+  if printf '%s' "$haystack" | grep -Fq -- "$needle"; then
+    pass "$description"
+  else
+    fail "$description"
+    echo "    expected to find: $needle"
+  fi
+}
+
+assert_not_matches() {
+  local haystack="$1"
+  local pattern="$2"
+  local description="$3"
+
+  if printf '%s' "$haystack" | grep -Eq -- "$pattern"; then
+    fail "$description"
+    echo "    did not expect to match: $pattern"
+  else
+    pass "$description"
+  fi
+}
+
+list_archive() {
+  local archive_path="$1"
+
+  case "$archive_path" in
+    *.tar.gz|*.tgz)
+      tar -tzf "$archive_path"
+      ;;
+    *.zip)
+      unzip -Z1 "$archive_path"
+      ;;
+    *)
+      unzip -Z1 "$archive_path"
+      ;;
+  esac
+}
+
+normalize_archive_paths() {
+  sed 's#/$##' | LC_ALL=C sort
+}
+
+extract_archive() {
+  local archive_path="$1"
+  local destination="$2"
+
+  mkdir -p "$destination"
+  case "$archive_path" in
+    *.tar.gz|*.tgz)
+      tar -xzf "$archive_path" -C "$destination"
+      ;;
+    *.zip)
+      unzip -q "$archive_path" -d "$destination"
+      ;;
+    *)
+      unzip -q "$archive_path" -d "$destination"
+      ;;
+  esac
+}
+
+read_archive_file() {
+  local archive_path="$1"
+  local file_path="$2"
+
+  case "$archive_path" in
+    *.tar.gz|*.tgz)
+      tar -xOf "$archive_path" "$file_path"
+      ;;
+    *.zip)
+      unzip -p "$archive_path" "$file_path"
+      ;;
+    *)
+      unzip -p "$archive_path" "$file_path"
+      ;;
+  esac
+}
+
+write_metadata_fixture() {
+  local destination="$1"
+  local skill
+
+  while IFS= read -r skill; do
+    mkdir -p "$destination/skills/$skill/agents"
+    cat >"$destination/skills/$skill/agents/openai.yaml" <<EOF
+interface:
+  display_name: "$skill"
+  short_description: "Fixture metadata for $skill"
+EOF
+  done < <(find "$REPO_ROOT/skills" -mindepth 1 -maxdepth 1 -type d -print | sed 's#.*/##' | sort)
+}
+
+echo "Codex package archive tests"
+
+metadata_source="$TEST_ROOT/metadata-source"
+archive="$TEST_ROOT/superpowers"
+tar_archive="$TEST_ROOT/superpowers.tar.gz"
+extracted="$TEST_ROOT/extracted"
+tar_extracted="$TEST_ROOT/tar-extracted"
+write_metadata_fixture "$metadata_source"
+
+source_hooks="$(python3 -c 'import json; print(json.load(open("'"$REPO_ROOT"'/.codex-plugin/plugin.json")).get("hooks"))')"
+assert_equals "$source_hooks" "{}" "source Codex manifest suppresses local hook auto-discovery"
+
+if output="$("$SCRIPT_UNDER_TEST" --allow-dirty --metadata-source "$metadata_source" --output "$archive" 2>&1)"; then
+  pass "package script exits successfully"
+else
+  fail "package script exits successfully"
+  printf '%s\n' "$output" | sed 's/^/      /'
+fi
+
+if [[ -f "$archive" ]]; then
+  pass "package script writes archive"
+else
+  fail "package script writes archive"
+fi
+
+assert_contains "$output" "Archive:" "reports archive path"
+assert_contains "$output" "Format:  zip" "reports default zip format"
+assert_contains "$output" "SHA-256:" "reports archive checksum"
+
+extract_archive "$archive" "$extracted"
+
+archive_paths="$(list_archive "$archive" | normalize_archive_paths)"
+unexpected_pattern='(^superpowers/|^\.agents/|^hooks/|package\.json$|^\.git|^\.pytest_cache|^\.ruff_cache|^scripts/|^tests/|^docs/|^evals/|^lib/|^\.claude|^\.cursor|^\.kimi|^\.opencode|^\.pi|^AGENTS\.md$|^CLAUDE\.md$|^GEMINI\.md$|^RELEASE-NOTES\.md$|^CHANGELOG\.md$)'
+assert_not_matches "$archive_paths" "$unexpected_pattern" "archive excludes source-only paths"
+assert_contains "$archive_paths" ".codex-plugin/plugin.json" "archive includes Codex manifest"
+assert_contains "$archive_paths" "skills/brainstorming/SKILL.md" "archive includes skills"
+assert_contains "$archive_paths" "skills/brainstorming/agents/openai.yaml" "archive includes OpenAI skill metadata"
+assert_contains "$archive_paths" "assets/app-icon.png" "archive includes app icon"
+assert_contains "$archive_paths" "assets/superpowers-small.svg" "archive includes composer icon"
+
+manifest_summary="$(read_archive_file "$archive" .codex-plugin/plugin.json | python3 -c 'import json,sys; data=json.load(sys.stdin); print("\t".join([data["name"], data["version"], data["skills"], str(data.get("hooks"))]))')"
+expected_version="$(python3 -c 'import json; print(json.load(open("'"$REPO_ROOT"'/.codex-plugin/plugin.json"))["version"])')"
+assert_equals "$manifest_summary" "superpowers	$expected_version	./skills/	$source_hooks" "archive manifest preserves source hooks"
+
+skill_count="$(find "$extracted/skills" -mindepth 1 -maxdepth 1 -type d | wc -l | tr -d ' ')"
+metadata_count="$(find "$extracted/skills" -path '*/agents/openai.yaml' -type f | wc -l | tr -d ' ')"
+assert_equals "$metadata_count" "$skill_count" "every packaged skill has OpenAI metadata"
+
+if [[ -x "$extracted/skills/subagent-driven-development/scripts/task-brief" ]]; then
+  pass "archive preserves executable script mode"
+else
+  fail "archive preserves executable script mode"
+fi
+
+zip_times="$(python3 - "$archive" <<'PY'
+import sys
+import zipfile
+
+with zipfile.ZipFile(sys.argv[1]) as archive:
+    print("\n".join(sorted({str(info.date_time) for info in archive.infolist()})))
+PY
+)"
+assert_equals "$zip_times" "(1980, 1, 1, 0, 0, 0)" "zip archive normalizes entry timestamps"
+
+if tar_output="$("$SCRIPT_UNDER_TEST" --allow-dirty --metadata-source "$metadata_source" --format tar.gz --output "$tar_archive" 2>&1)"; then
+  pass "package script writes explicit tar.gz archive"
+else
+  fail "package script writes explicit tar.gz archive"
+  printf '%s\n' "$tar_output" | sed 's/^/      /'
+fi
+assert_contains "$tar_output" "Format:  tar.gz" "reports explicit tar.gz format"
+
+extract_archive "$tar_archive" "$tar_extracted"
+tar_archive_paths="$(list_archive "$tar_archive" | normalize_archive_paths)"
+assert_equals "$tar_archive_paths" "$archive_paths" "zip and tar.gz archives contain the same paths"
+
+tar_task_brief_mode="$(tar -tzvf "$tar_archive" skills/subagent-driven-development/scripts/task-brief | awk '{print $1}')"
+assert_equals "$tar_task_brief_mode" "-rwxr-xr-x" "tar.gz archive preserves executable script mode"
+
+tar_metadata_times="$(python3 - "$tar_archive" <<'PY'
+import sys, tarfile
+with tarfile.open(sys.argv[1]) as archive:
+    print(sorted({member.mtime for member in archive.getmembers()}))
+PY
+)"
+assert_equals "$tar_metadata_times" "[0]" "tar.gz archive normalizes entry timestamps"
+
+metadata_archive="$TEST_ROOT/metadata-source.tar.gz"
+metadata_zip="$TEST_ROOT/metadata-source.zip"
+archive_from_tar_source="$TEST_ROOT/superpowers-from-tar-source.zip"
+archive_from_zip_source="$TEST_ROOT/superpowers-from-zip-source.zip"
+(
+  cd "$metadata_source"
+  tar -czf "$metadata_archive" .
+  zip -X -q -r "$metadata_zip" .
+)
+
+if output="$("$SCRIPT_UNDER_TEST" --allow-dirty --metadata-source "$metadata_archive" --output "$archive_from_tar_source" 2>&1)"; then
+  pass "package script accepts tarball metadata source"
+else
+  fail "package script accepts tarball metadata source"
+  printf '%s\n' "$output" | sed 's/^/      /'
+fi
+
+if cmp -s "$archive" "$archive_from_tar_source"; then
+  pass "tarball metadata source produces identical archive"
+else
+  fail "tarball metadata source produces identical archive"
+fi
+
+if output="$("$SCRIPT_UNDER_TEST" --allow-dirty --metadata-source "$metadata_zip" --output "$archive_from_zip_source" 2>&1)"; then
+  pass "package script accepts zip metadata source"
+else
+  fail "package script accepts zip metadata source"
+  printf '%s\n' "$output" | sed 's/^/      /'
+fi
+
+if cmp -s "$archive" "$archive_from_zip_source"; then
+  pass "zip metadata source produces identical archive"
+else
+  fail "zip metadata source produces identical archive"
+fi
+
+incomplete_metadata="$TEST_ROOT/incomplete-metadata"
+mkdir -p "$incomplete_metadata/skills/brainstorming/agents"
+cp "$metadata_source/skills/brainstorming/agents/openai.yaml" \
+  "$incomplete_metadata/skills/brainstorming/agents/openai.yaml"
+
+set +e
+missing_output="$("$SCRIPT_UNDER_TEST" --allow-dirty --metadata-source "$incomplete_metadata" --output "$TEST_ROOT/missing.tar.gz" 2>&1)"
+missing_status=$?
+set -e
+if [[ "$missing_status" -ne 0 ]]; then
+  pass "package script rejects incomplete metadata source"
+else
+  fail "package script rejects incomplete metadata source"
+fi
+assert_contains "$missing_output" "ERROR: metadata source is incomplete" "incomplete metadata reports clear error"
+
+dirty_repo="$TEST_ROOT/dirty-repo"
+git clone -q --no-local "$REPO_ROOT" "$dirty_repo"
+printf '\n# dirty fixture\n' >>"$dirty_repo/README.md"
+set +e
+dirty_output="$(
+  cd "$dirty_repo"
+  scripts/package-codex-plugin.sh \
+    --metadata-source "$metadata_source" \
+    --output "$TEST_ROOT/dirty.zip" 2>&1
+)"
+dirty_status=$?
+set -e
+if [[ "$dirty_status" -ne 0 ]]; then
+  pass "package script rejects dirty worktree by default"
+else
+  fail "package script rejects dirty worktree by default"
+fi
+assert_contains "$dirty_output" "Working tree has uncommitted changes:" "dirty worktree reports changed files"
+
+if [[ "$FAILURES" -eq 0 ]]; then
+  echo "All Codex package archive tests passed"
+else
+  echo "$FAILURES Codex package archive test(s) failed"
+  exit 1
+fi

tests/devin/test-devin-plugin.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Validate the Devin CLI integration. `devin plugins install obra/superpowers`
+# reads `.devin-plugin/plugin.json` and auto-discovers the co-located `skills/`
+# directory; Devin CLI surfaces every installed skill's name + description in
+# the system prompt at session start and invokes them via its native `skill`
+# tool, and its system prompt already documents its own tools (subagent
+# profiles, todo tracking, question prompts), so there is no hook, injector,
+# or tool-mapping scaffold to test. What IS Devin-specific is the manifest.
+#
+# Mirrors tests/kimi/test-plugin-manifest.sh. CI-safe: does not require
+# `devin` installed.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+MANIFEST="$REPO_ROOT/.devin-plugin/plugin.json"
+
+fail() { echo "FAIL: $*" >&2; exit 1; }
+
+echo "test-devin-plugin: checking Devin CLI manifest"
+
+# --- Manifest is valid and matches the repo version -------------------------
+[ -f "$MANIFEST" ] || fail "manifest missing at $MANIFEST"
+
+python3 - "$MANIFEST" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+manifest_path = Path(sys.argv[1])
+manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+repo_root = manifest_path.parents[1]
+
+if manifest.get("name") != "superpowers":
+    raise AssertionError(f"plugin name: expected 'superpowers', got {manifest.get('name')!r}")
+
+package = json.loads((repo_root / "package.json").read_text(encoding="utf-8"))
+if manifest.get("version") != package.get("version"):
+    raise AssertionError(
+        f"manifest version {manifest.get('version')!r} != package.json version {package.get('version')!r}"
+    )
+
+# Devin CLI plugins carry skills only (auto-discovered from ./skills/); the
+# manifest supports metadata + dependency lists, nothing executable.
+unsupported = ["skills", "hooks", "commands", "sessionStart", "contextFileName", "inject"]
+present = sorted(field for field in unsupported if field in manifest)
+if present:
+    raise AssertionError("unsupported Devin manifest fields present: " + ", ".join(present))
+
+version_config = json.loads((repo_root / ".version-bump.json").read_text(encoding="utf-8"))
+entries = version_config.get("files")
+if not isinstance(entries, list) or not any(
+    entry.get("path") == ".devin-plugin/plugin.json" and entry.get("field") == "version"
+    for entry in entries
+    if isinstance(entry, dict)
+):
+    raise AssertionError(".version-bump.json must update .devin-plugin/plugin.json version")
+
+print("Devin plugin manifest looks good")
+PY
+
+echo "PASS: Devin CLI plugin valid (manifest)"

tests/diagnosing-superpowers/test-skill-structure.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# Structural checks for skills/diagnosing-superpowers. Behavior is tested by
+# scenario evals kept by the maintainer; this script only checks the things a
+# shell can check: frontmatter, referenced files exist, no local paths or
+# names leaked into shipped files, SKILL.md word budget.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+SKILL_DIR="$REPO_ROOT/skills/diagnosing-superpowers"
+SKILL_MD="$SKILL_DIR/SKILL.md"
+WORD_BUDGET=900
+
+PASSES=0
+FAILURES=0
+
+pass() { echo "  [PASS] $1"; PASSES=$((PASSES + 1)); }
+fail() { echo "  [FAIL] $1"; FAILURES=$((FAILURES + 1)); }
+
+echo "diagnosing-superpowers structure"
+
+# --- SKILL.md frontmatter -------------------------------------------------
+if [ -f "$SKILL_MD" ]; then
+  pass "SKILL.md exists"
+  frontmatter="$(awk 'NR==1 && $0!="---"{exit} NR>1 && $0=="---"{exit} NR>1{print}' "$SKILL_MD")"
+  if printf '%s\n' "$frontmatter" | grep -q '^name: diagnosing-superpowers$'; then
+    pass "frontmatter name is diagnosing-superpowers"
+  else
+    fail "frontmatter name is diagnosing-superpowers"
+  fi
+  description="$(printf '%s\n' "$frontmatter" | awk '/^description:/{sub(/^description:[ ]*/,""); print; found=1; next} found && /^[ ]/{print} found && !/^[ ]/{exit}' | tr '\n' ' ')"
+  if printf '%s' "$description" | grep -q '^Use when'; then
+    pass "description starts with 'Use when'"
+  else
+    fail "description starts with 'Use when' (got: ${description:0:60})"
+  fi
+  if [ "${#description}" -le 1024 ]; then
+    pass "description under 1024 characters"
+  else
+    fail "description under 1024 characters (${#description})"
+  fi
+  for banned in "dispatch" "then" "step"; do
+    if printf '%s' "$description" | grep -qiw "$banned"; then
+      fail "description contains workflow word '$banned'"
+    else
+      pass "description avoids workflow word '$banned'"
+    fi
+  done
+
+  # --- word budget --------------------------------------------------------
+  body_words="$(awk 'BEGIN{fm=0} NR==1 && $0=="---"{fm=1; next} fm==1 && $0=="---"{fm=2; next} fm==2{print}' "$SKILL_MD" | wc -w | tr -d ' ')"
+  if [ "$body_words" -le "$WORD_BUDGET" ]; then
+    pass "SKILL.md body within $WORD_BUDGET words ($body_words)"
+  else
+    fail "SKILL.md body within $WORD_BUDGET words ($body_words)"
+  fi
+
+  # --- required sections --------------------------------------------------
+  for heading in "## Hard rules" "## Red Flags"; do
+    if grep -q "^$heading" "$SKILL_MD"; then
+      pass "SKILL.md has section '$heading'"
+    else
+      fail "SKILL.md has section '$heading'"
+    fi
+  done
+
+  # --- every referenced skill file exists --------------------------------
+  while IFS= read -r ref; do
+    if [ -f "$SKILL_DIR/$ref" ]; then
+      pass "referenced file exists: $ref"
+    else
+      fail "referenced file exists: $ref"
+    fi
+  done < <(grep -o '\(references\|prompts\|templates\)/[A-Za-z0-9._-]*\.md' "$SKILL_MD" | sort -u)
+else
+  fail "SKILL.md exists"
+fi
+
+# --- expected files -------------------------------------------------------
+expected_files=(
+  references/claude-code-sessions.md
+  references/codex-sessions.md
+  references/other-harnesses.md
+  prompts/skill-timeline.md
+  prompts/plan-adherence.md
+  prompts/repeated-work.md
+  prompts/stumbles.md
+  prompts/quality-evidence.md
+  prompts/request-conflicts.md
+  prompts/cost-and-time.md
+  prompts/scrub.md
+  prompts/scrub-audit.md
+  prompts/similar-session.md
+  templates/case.md
+  templates/report.md
+  templates/bundle-README.md
+  templates/issue.md
+)
+for rel in "${expected_files[@]}"; do
+  if [ -f "$SKILL_DIR/$rel" ]; then
+    pass "expected file present: $rel"
+  else
+    fail "expected file present: $rel"
+  fi
+done
+
+# --- no local paths or names in shipped files ----------------------------
+leaks="$(grep -rn -E '/Users/|/home/|jesse' "$SKILL_DIR" "$SCRIPT_DIR" --exclude=test-skill-structure.sh 2>/dev/null || true)"
+if [ -z "$leaks" ]; then
+  pass "no machine-specific paths or names in shipped files (skills + tests)"
+else
+  fail "no machine-specific paths or names in shipped files (skills + tests)"
+  printf '%s\n' "$leaks" | head -10 | sed 's/^/    /'
+fi
+
+# --- "the user" never appears in skill prose -----------------------------
+user_hits="$(grep -rn -i 'the user' "$SKILL_DIR" --include='*.md' 2>/dev/null || true)"
+if [ -z "$user_hits" ]; then
+  pass "skill files say 'your human partner', not 'the user'"
+else
+  fail "skill files say 'your human partner', not 'the user'"
+  printf '%s\n' "$user_hits" | head -10 | sed 's/^/    /'
+fi
+
+echo
+echo "Passed: $PASSES  Failed: $FAILURES"
+[ "$FAILURES" -eq 0 ]

tests/hermes/conftest.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+
+import pytest
+from unittest.mock import MagicMock
+
+
+@pytest.fixture
+def mock_ctx():
+    ctx = MagicMock()
+    ctx._hooks = {}
+    ctx._skills = {}
+
+    def register_hook(event, fn):
+        ctx._hooks[event] = fn
+
+    def register_skill(name, path):
+        # Mimic hermes' real register_skill, which calls path.exists() and
+        # therefore breaks on a str (the bug that silently disabled the whole
+        # plugin, found 2026-07-23). Keeping that fidelity here means a
+        # regression to str paths fails these tests instead of failing
+        # silently inside hermes.
+        if not isinstance(path, Path):
+            raise AttributeError(
+                f"register_skill requires a pathlib.Path, got {type(path).__name__}"
+            )
+        ctx._skills[name] = path
+
+    ctx.register_hook.side_effect = register_hook
+    ctx.register_skill.side_effect = register_skill
+    return ctx

tests/hermes/test_bootstrap.py

@@ -0,0 +1,98 @@
+import importlib
+import os
+import sys
+
+import pytest
+
+sys.path.insert(0, os.path.abspath(
+    os.path.join(os.path.dirname(__file__), "../../.hermes-plugin")
+))
+
+BOOTSTRAP_MARKER = "superpowers:using-superpowers bootstrap for hermes"
+
+# Hermes spills injected context over 10,000 chars to a file, which breaks
+# inline injection semantics. The bootstrap must stay under it with margin.
+HERMES_CONTEXT_SPILL_LIMIT = 10_000
+
+
+def _load():
+    if "__init__" in sys.modules:
+        del sys.modules["__init__"]
+    return importlib.import_module("__init__")
+
+
+def _bootstrap():
+    m = _load()
+    return m._build_bootstrap(m._skills_dir())
+
+
+class TestStripFrontmatter:
+    def test_strips_yaml_block(self):
+        m = _load()
+        content = "---\nname: foo\ndescription: bar\n---\n# Body\nContent here"
+        assert m._strip_frontmatter(content) == "# Body\nContent here"
+
+    def test_no_frontmatter_returns_trimmed_content(self):
+        m = _load()
+        content = "# No frontmatter\nJust content"
+        assert m._strip_frontmatter(content) == "# No frontmatter\nJust content"
+
+    def test_strips_surrounding_whitespace_from_body(self):
+        m = _load()
+        content = "---\nname: foo\n---\n\n\n# Body\n\n"
+        assert m._strip_frontmatter(content) == "# Body"
+
+
+class TestSkillsDirResolution:
+    def test_repo_layout_resolves(self):
+        # The repo checkout IS the git-clone layout: .hermes-plugin/ and
+        # skills/ are siblings, so resolution must succeed from here.
+        m = _load()
+        skills = m._skills_dir()
+        assert os.path.isfile(
+            os.path.join(skills, "using-superpowers", "SKILL.md")
+        )
+
+
+class TestBootstrapContent:
+    def test_marker_and_wrapper(self):
+        content = _bootstrap()
+        assert BOOTSTRAP_MARKER in content
+        assert content.startswith("<EXTREMELY_IMPORTANT>")
+        assert content.rstrip().endswith("</EXTREMELY_IMPORTANT>")
+
+    def test_contains_using_superpowers_body(self):
+        content = _bootstrap()
+        # A distinctive line from the skill body proves the real SKILL.md was
+        # embedded, not a stub.
+        assert "You have superpowers" in content
+        assert "## The Rule" in content
+
+    def test_frontmatter_stripped(self):
+        content = _bootstrap()
+        assert "---\nname:" not in content
+
+    def test_tool_mapping_sourced_from_reference_file(self):
+        m = _load()
+        content = _bootstrap()
+        ref = os.path.join(
+            m._skills_dir(), "using-superpowers", "references", "hermes-tools.md"
+        )
+        with open(ref, encoding="utf-8") as f:
+            ref_text = f.read().strip()
+        # The mapping is included verbatim from the reference file — the
+        # single source, not a drift-prone inline copy.
+        assert ref_text in content
+        assert "read_file" in content
+
+    def test_skill_view_guidance_present(self):
+        content = _bootstrap()
+        assert 'skill_view("superpowers:brainstorming")' in content
+
+    def test_under_hermes_context_spill_limit(self):
+        content = _bootstrap()
+        assert len(content) < HERMES_CONTEXT_SPILL_LIMIT, (
+            f"bootstrap is {len(content)} chars; hermes spills injected "
+            f"context over {HERMES_CONTEXT_SPILL_LIMIT} to a file, which "
+            "breaks inline injection"
+        )

tests/hermes/test_plugin.py

@@ -0,0 +1,142 @@
+import importlib
+import importlib.util
+import os
+import shutil
+import sys
+from pathlib import Path
+
+import pytest
+
+# Point at the plugin directory
+_PLUGIN_DIR = os.path.abspath(
+    os.path.join(os.path.dirname(__file__), "../../.hermes-plugin")
+)
+sys.path.insert(0, _PLUGIN_DIR)
+
+BOOTSTRAP_MARKER = "superpowers:using-superpowers bootstrap for hermes"
+
+
+def _load_plugin():
+    """Re-import plugin module fresh."""
+    if "__init__" in sys.modules:
+        del sys.modules["__init__"]
+    return importlib.import_module("__init__")
+
+
+def _fire_pre_llm(ctx, **kwargs):
+    hook = ctx._hooks["pre_llm_call"]
+    defaults = {
+        "session_id": "s1",
+        "user_message": "hi",
+        "conversation_history": [],
+        "is_first_turn": False,
+        "model": "test-model",
+        "platform": "cli",
+    }
+    defaults.update(kwargs)
+    return hook(**defaults)
+
+
+class TestPluginRegistration:
+    def test_register_attaches_only_pre_llm_call_hook(self, mock_ctx):
+        plugin = _load_plugin()
+        plugin.register(mock_ctx)
+        assert list(mock_ctx._hooks.keys()) == ["pre_llm_call"]
+
+    def test_register_registers_every_stock_skill_as_path(self, mock_ctx):
+        plugin = _load_plugin()
+        plugin.register(mock_ctx)
+        # The conftest mock raises on non-Path (mirroring hermes' real
+        # register_skill), so reaching these asserts proves every
+        # registration passed a pathlib.Path.
+        assert "using-superpowers" in mock_ctx._skills
+        assert "brainstorming" in mock_ctx._skills
+        for name, path in mock_ctx._skills.items():
+            assert isinstance(path, Path)
+            assert path.name == "SKILL.md"
+            assert path.parent.name == name
+            assert path.is_file()
+
+    def test_registered_skills_match_skill_directories(self, mock_ctx):
+        plugin = _load_plugin()
+        plugin.register(mock_ctx)
+        skills_root = plugin._skills_dir()
+        expected = {
+            entry
+            for entry in os.listdir(skills_root)
+            if os.path.isfile(os.path.join(skills_root, entry, "SKILL.md"))
+        }
+        assert set(mock_ctx._skills.keys()) == expected
+
+
+class TestBootstrapInjection:
+    def test_first_turn_returns_bootstrap_context(self, mock_ctx):
+        plugin = _load_plugin()
+        plugin.register(mock_ctx)
+        result = _fire_pre_llm(mock_ctx, is_first_turn=True)
+        assert isinstance(result, dict)
+        content = result["context"]
+        assert BOOTSTRAP_MARKER in content
+        assert content.startswith("<EXTREMELY_IMPORTANT>")
+        assert content.rstrip().endswith("</EXTREMELY_IMPORTANT>")
+
+    def test_later_turns_return_none(self, mock_ctx):
+        plugin = _load_plugin()
+        plugin.register(mock_ctx)
+        assert _fire_pre_llm(mock_ctx, is_first_turn=False) is None
+        assert _fire_pre_llm(mock_ctx, is_first_turn=None) is None
+
+    def test_hook_tolerates_future_kwargs(self, mock_ctx):
+        plugin = _load_plugin()
+        plugin.register(mock_ctx)
+        result = _fire_pre_llm(
+            mock_ctx, is_first_turn=True, telemetry_schema_version=3
+        )
+        assert BOOTSTRAP_MARKER in result["context"]
+
+
+class TestLayoutResolution:
+    def _stage(self, tmp_path, layout):
+        """Copy the plugin module + a minimal skills tree in the given layout."""
+        src_skills = Path(_PLUGIN_DIR).parent / "skills"
+        if layout == "clone":
+            plugdir = tmp_path / "superpowers" / ".hermes-plugin"
+        else:  # flat: module at the plugin dir root, skills nested inside it
+            plugdir = tmp_path / "superpowers"
+        skills = tmp_path / "superpowers" / "skills"
+        plugdir.mkdir(parents=True, exist_ok=True)
+        shutil.copy(Path(_PLUGIN_DIR) / "__init__.py", plugdir / "__init__.py")
+        for skill in ("using-superpowers", "brainstorming"):
+            shutil.copytree(src_skills / skill, skills / skill)
+        return plugdir
+
+    def _load_from(self, plugdir):
+        spec = importlib.util.spec_from_file_location(
+            f"hermes_plugin_test_{plugdir.parent.name}_{plugdir.name}",
+            plugdir / "__init__.py",
+        )
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+        return mod
+
+    def test_clone_layout_resolves_sibling_skills(self, tmp_path, mock_ctx):
+        # git-clone install: .hermes-plugin/ and skills/ are siblings.
+        plugdir = self._stage(tmp_path, "clone")
+        mod = self._load_from(plugdir)
+        mod.register(mock_ctx)
+        assert "using-superpowers" in mock_ctx._skills
+
+    def test_flat_layout_resolves_nested_skills(self, tmp_path, mock_ctx):
+        # flattened install: module at the plugin dir root, skills/ inside it.
+        plugdir = self._stage(tmp_path, "flat")
+        mod = self._load_from(plugdir)
+        mod.register(mock_ctx)
+        assert "using-superpowers" in mock_ctx._skills
+
+    def test_missing_skills_raises_loudly(self, tmp_path, mock_ctx):
+        plugdir = tmp_path / "superpowers"
+        plugdir.mkdir(parents=True)
+        shutil.copy(Path(_PLUGIN_DIR) / "__init__.py", plugdir / "__init__.py")
+        mod = self._load_from(plugdir)
+        with pytest.raises(RuntimeError, match="cannot find the skills"):
+            mod.register(mock_ctx)

tests/hooks/test-session-start.sh

@@ -143,6 +143,27 @@ for (const forbiddenText of forbiddenTexts) {
 
 echo "SessionStart hook output tests"
 
+# Registration shape: the hook must declare shell:"bash" so Claude Code on
+# Windows dispatches via Git Bash (or fails with an actionable error) instead
+# of PowerShell/cmd.exe, whose parsers break on the quoted command string
+# (PowerShell ParserError; cmd.exe quote-stripping on paths with metacharacters).
+if node -e '
+const hooks = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
+const entry = hooks.hooks.SessionStart[0].hooks[0];
+if (entry.shell !== "bash") {
+  console.error(`SessionStart hook shell is ${JSON.stringify(entry.shell)}, expected "bash"`);
+  process.exit(1);
+}
+if (!/run-hook\.cmd" session-start$/.test(entry.command)) {
+  console.error(`unexpected SessionStart command shape: ${entry.command}`);
+  process.exit(1);
+}
+' "$REPO_ROOT/hooks/hooks.json"; then
+    pass "hooks.json registers SessionStart with shell:bash dispatch"
+else
+    fail "hooks.json registers SessionStart with shell:bash dispatch"
+fi
+
 claude_home="$(make_home claude-code)"
 assert_command_output \
     "Claude Code emits nested SessionStart additionalContext" \

tests/pi/test-pi-extension.mjs

@@ -122,7 +122,16 @@ test('pi tools reference documents pi-specific mappings', async () => {
   assert.equal(existsSync(piToolsPath), true, 'pi-tools.md should exist');
   const text = await readFile(piToolsPath, 'utf8');
 
-  for (const expected of ['Skill', 'Task', 'TodoWrite', 'read', 'write', 'edit', 'bash']) {
-    assert.match(text, new RegExp(expected));
-  }
+  // Assert against the mapping-table rows only. The surrounding prose mentions
+  // these same tokens, so matching the whole file would still pass if the table
+  // were deleted — the exact regression this test exists to catch.
+  const rows = text.split('\n').filter((line) => line.startsWith('|'));
+  assert.ok(
+    rows.some((row) => /subagent/i.test(row)),
+    'mapping table documents subagent dispatch',
+  );
+  assert.ok(
+    rows.some((row) => /todo|task/i.test(row)),
+    'mapping table documents task tracking',
+  );
 });

tests/systematic-debugging/test-find-polluter.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+SCRIPT_UNDER_TEST="$REPO_ROOT/skills/systematic-debugging/find-polluter.sh"
+
+FAILURES=0
+TEST_ROOT="$(mktemp -d)"
+
+cleanup() {
+  rm -rf "$TEST_ROOT"
+}
+trap cleanup EXIT
+
+pass() {
+  echo "  [PASS] $1"
+}
+
+fail() {
+  echo "  [FAIL] $1"
+  FAILURES=$((FAILURES + 1))
+}
+
+assert_contains() {
+  local haystack="$1"
+  local needle="$2"
+  local description="$3"
+
+  if printf '%s' "$haystack" | grep -Fq -- "$needle"; then
+    pass "$description"
+  else
+    fail "$description (expected output to contain: $needle)"
+  fi
+}
+
+# Toy project: one top-level test, one nested test. A stubbed `npm` on PATH
+# creates the pollution marker whenever any test runs, so the first test file
+# executed is always identified as the polluter.
+setup_project() {
+  PROJECT="$TEST_ROOT/project"
+  rm -rf "$PROJECT"
+  mkdir -p "$PROJECT/src/feature" "$PROJECT/bin"
+  echo "test('top')" > "$PROJECT/src/top.test.ts"
+  echo "test('nested')" > "$PROJECT/src/feature/nested.test.ts"
+  cat > "$PROJECT/bin/npm" <<'EOF'
+#!/usr/bin/env bash
+touch pollution.marker
+EOF
+  chmod +x "$PROJECT/bin/npm"
+}
+
+# run_polluter <pattern> — runs the script in the toy project with the stub
+# npm first on PATH; captures combined output, never aborts on exit code.
+run_polluter() {
+  local pattern="$1"
+  rm -f "$PROJECT/pollution.marker"
+  (
+    cd "$PROJECT"
+    PATH="$PROJECT/bin:$PATH" "$SCRIPT_UNDER_TEST" 'pollution.marker' "$pattern" 2>&1
+  ) || true
+}
+
+echo "Test: documented pattern finds nested test files (issue #2008)"
+setup_project
+OUTPUT="$(run_polluter 'src/**/*.test.ts')"
+assert_contains "$OUTPUT" "FOUND POLLUTER" "documented pattern runs tests and detects pollution"
+
+echo "Test: documented pattern also finds top-level test files"
+setup_project
+OUTPUT="$(run_polluter 'src/**/*.test.ts')"
+assert_contains "$OUTPUT" "Found 2 test files" "src/**/*.test.ts matches src/top.test.ts and src/feature/nested.test.ts"
+
+echo "Test: ./-prefixed pattern matches the same files"
+setup_project
+OUTPUT="$(run_polluter './src/**/*.test.ts')"
+assert_contains "$OUTPUT" "Found 2 test files" "leading ./ on the pattern is accepted"
+
+echo "Test: non-matching pattern reports an honest zero"
+setup_project
+OUTPUT="$(run_polluter 'nomatch/**/*.test.ts')"
+assert_contains "$OUTPUT" "Found 0 test files" "empty result counts as 0, not 1"
+assert_contains "$OUTPUT" "No polluter found" "empty result exits via the clean path"
+
+echo ""
+if [ "$FAILURES" -gt 0 ]; then
+  echo "$FAILURES test(s) failed"
+  exit 1
+fi
+echo "All tests passed"

tests/version-bump/test-bump-version.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+SCRIPT_SOURCE="$REPO_ROOT/scripts/bump-version.sh"
+TEST_ROOT="$(mktemp -d)"
+
+cleanup() {
+  rm -rf "$TEST_ROOT"
+}
+trap cleanup EXIT
+
+fail() {
+  echo "FAIL: $*" >&2
+  exit 1
+}
+
+make_fixture() {
+  local repo="$1"
+  local yaml_body="$2"
+
+  mkdir -p "$repo/scripts" "$repo/.hermes-plugin"
+  cp "$SCRIPT_SOURCE" "$repo/scripts/bump-version.sh"
+  cat >"$repo/.version-bump.json" <<'JSON'
+{
+  "files": [
+    { "path": "package.json", "field": "version" },
+    { "path": ".hermes-plugin/plugin.yaml", "field": "version" }
+  ],
+  "audit": { "exclude": [] }
+}
+JSON
+  cat >"$repo/package.json" <<'JSON'
+{
+  "name": "fixture",
+  "version": "1.2.3"
+}
+JSON
+  printf '%s\n' "$yaml_body" >"$repo/.hermes-plugin/plugin.yaml"
+}
+
+happy_repo="$TEST_ROOT/happy"
+make_fixture "$happy_repo" $'name: superpowers\nversion: 1.2.3'
+
+/bin/bash "$happy_repo/scripts/bump-version.sh" --check >"$TEST_ROOT/check.out"
+/bin/bash "$happy_repo/scripts/bump-version.sh" --audit >"$TEST_ROOT/audit.out"
+/bin/bash "$happy_repo/scripts/bump-version.sh" 2.3.4 >"$TEST_ROOT/bump.out"
+
+[[ "$(jq -r '.version' "$happy_repo/package.json")" == "2.3.4" ]] \
+  || fail "JSON manifest was not bumped"
+[[ "$(yq -r '.version' "$happy_repo/.hermes-plugin/plugin.yaml")" == "2.3.4" ]] \
+  || fail "YAML manifest was not bumped"
+
+jq -e '
+  any(.files[];
+    .path == ".hermes-plugin/plugin.yaml" and .field == "version")
+' "$REPO_ROOT/.version-bump.json" >/dev/null \
+  || fail "Hermes manifest is not registered"
+
+invalid_repo="$TEST_ROOT/invalid"
+make_fixture "$invalid_repo" $'name: superpowers\nversion: 123'
+cp "$invalid_repo/package.json" "$TEST_ROOT/package.before"
+cp "$invalid_repo/.hermes-plugin/plugin.yaml" "$TEST_ROOT/plugin.before"
+
+if /bin/bash "$invalid_repo/scripts/bump-version.sh" 2.3.4 \
+  >"$TEST_ROOT/invalid.out" 2>&1; then
+  fail "bump accepted a non-string YAML version"
+fi
+
+cmp -s "$TEST_ROOT/package.before" "$invalid_repo/package.json" \
+  || fail "JSON manifest changed before YAML validation failed"
+cmp -s "$TEST_ROOT/plugin.before" "$invalid_repo/.hermes-plugin/plugin.yaml" \
+  || fail "invalid YAML manifest changed"
+
+echo "Version-bump tests passed"

tests/writing-skills/test-render-graphs.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+SCRIPT_UNDER_TEST="$REPO_ROOT/skills/writing-skills/render-graphs.js"
+NODE_BIN="$(command -v node)"
+
+PASSES=0
+FAILURES=0
+TEST_ROOT="$(mktemp -d)"
+
+cleanup() {
+  rm -rf "$TEST_ROOT"
+}
+trap cleanup EXIT
+
+pass() {
+  echo "  [PASS] $1"
+  PASSES=$((PASSES + 1))
+}
+
+fail() {
+  echo "  [FAIL] $1"
+  FAILURES=$((FAILURES + 1))
+}
+
+assert_contains() {
+  local haystack="$1"
+  local needle="$2"
+  local description="$3"
+
+  if printf '%s' "$haystack" | grep -Fq -- "$needle"; then
+    pass "$description"
+  else
+    fail "$description"
+    echo "    expected to find: $needle"
+  fi
+}
+
+assert_not_contains() {
+  local haystack="$1"
+  local needle="$2"
+  local description="$3"
+
+  if printf '%s' "$haystack" | grep -Fq -- "$needle"; then
+    fail "$description"
+    echo "    did not expect to find: $needle"
+  else
+    pass "$description"
+  fi
+}
+
+fixture="$TEST_ROOT/fixture-skill"
+mkdir -p "$fixture" "$TEST_ROOT/empty-path"
+cat >"$fixture/SKILL.md" <<'EOF'
+---
+name: fixture-skill
+---
+
+# Fixture Skill
+
+```dot
+digraph fixture_graph {
+  start -> end;
+}
+```
+EOF
+
+echo "Writing-skills render-graphs tests"
+
+missing_dot_output="$(PATH="$TEST_ROOT/empty-path" "$NODE_BIN" "$SCRIPT_UNDER_TEST" "$fixture" 2>&1)"
+missing_dot_status=$?
+
+if [[ "$missing_dot_status" -ne 0 ]]; then
+  pass "missing Graphviz exits non-zero"
+else
+  fail "missing Graphviz exits non-zero"
+fi
+assert_contains "$missing_dot_output" "Error: graphviz (dot) not found." "missing Graphviz reports install guidance"
+assert_not_contains "$missing_dot_output" "ReferenceError: require is not defined" "script runs as an ES module"
+
+render_output="$("$NODE_BIN" "$SCRIPT_UNDER_TEST" "$fixture" 2>&1)"
+render_status=$?
+
+if [[ "$render_status" -eq 0 ]]; then
+  pass "fixture diagram renders"
+else
+  fail "fixture diagram renders"
+  printf '%s\n' "$render_output"
+fi
+
+assert_contains "$render_output" "Found 1 diagram(s)" "reports discovered diagram"
+assert_contains "$render_output" "Rendered: fixture_graph.svg" "reports rendered SVG"
+
+if [[ -f "$fixture/diagrams/fixture_graph.svg" ]]; then
+  pass "writes SVG output"
+else
+  fail "writes SVG output"
+fi
+
+if [[ -f "$fixture/diagrams/fixture_graph.svg" ]] && grep -Fq "<svg" "$fixture/diagrams/fixture_graph.svg"; then
+  pass "SVG output has SVG markup"
+else
+  fail "SVG output has SVG markup"
+fi
+
+echo
+echo "Results: $PASSES passed, $FAILURES failed"
+
+if [[ "$FAILURES" -gt 0 ]]; then
+  exit 1
+fi