summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--.antigravity-plugin/plugin.json2
-rw-r--r--.claude-plugin/marketplace.json2
-rw-r--r--.claude-plugin/plugin.json2
-rw-r--r--.codex-plugin/plugin.json2
-rw-r--r--.cursor-plugin/plugin.json2
-rw-r--r--.devin-plugin/plugin.json2
-rw-r--r--.hermes-plugin/__init__.py6
-rw-r--r--.hermes-plugin/plugin.yaml2
-rw-r--r--.kimi-plugin/plugin.json2
-rw-r--r--.muse-plugin/marketplace.json2
-rw-r--r--.muse-plugin/plugin.json4
-rw-r--r--.opencode/INSTALL.md2
-rw-r--r--.opencode/plugins/superpowers.js100
-rw-r--r--.pi/extensions/superpowers.ts11
-rw-r--r--RELEASE-NOTES.md56
-rw-r--r--docs/README.opencode.md10
-rw-r--r--docs/porting-to-a-new-harness.md23
-rw-r--r--docs/windows/polyglot-hooks.md10
-rw-r--r--gemini-extension.json2
-rw-r--r--hooks/hooks.json1
-rwxr-xr-xhooks/run-hook.cmd23
-rwxr-xr-xhooks/session-start53
-rw-r--r--package.json2
-rwxr-xr-xscripts/package-codex-plugin.sh2
-rwxr-xr-xscripts/sync-to-codex-plugin.sh4
-rw-r--r--skills/brainstorming/SKILL.md98
-rwxr-xr-xskills/brainstorming/scripts/start-server.sh7
-rw-r--r--skills/executing-plans/SKILL.md10
-rwxr-xr-xskills/executing-plans/scripts/task-done7
-rwxr-xr-xskills/executing-plans/scripts/task-start6
-rw-r--r--skills/subagent-driven-development/SKILL.md11
-rw-r--r--skills/subagent-driven-development/re-review-prompt.md1
-rw-r--r--skills/subagent-driven-development/references/final-review.md6
-rw-r--r--skills/subagent-driven-development/references/fix-loop.md2
-rwxr-xr-xskills/subagent-driven-development/scripts/review-package39
-rwxr-xr-xskills/subagent-driven-development/scripts/sdd-repo54
-rwxr-xr-xskills/subagent-driven-development/scripts/sdd-workspace33
-rwxr-xr-xskills/subagent-driven-development/scripts/task-brief85
-rw-r--r--skills/subagent-driven-development/task-reviewer-prompt.md6
-rw-r--r--tests/brainstorm-server/server.test.js13
-rw-r--r--tests/brainstorm-server/start-server.test.sh46
-rwxr-xr-xtests/claude-code/test-executing-plans-scripts.sh76
-rwxr-xr-xtests/claude-code/test-sdd-workspace.sh467
-rwxr-xr-xtests/codex-plugin-sync/test-sync-to-codex-plugin.sh28
-rwxr-xr-xtests/codex/test-package-codex-plugin.sh22
-rw-r--r--tests/hermes/test_plugin.py18
-rwxr-xr-xtests/hooks/test-run-hook-cmd-windows.sh18
-rwxr-xr-xtests/hooks/test-session-start.sh127
-rwxr-xr-xtests/opencode/run-tests.sh2
-rw-r--r--tests/opencode/test-bootstrap-caching.mjs22
-rw-r--r--tests/opencode/test-hook-registration.mjs98
-rwxr-xr-xtests/opencode/test-hook-registration.sh4
-rw-r--r--tests/opencode/test-session-bootstrap.mjs10
-rw-r--r--tests/pi/test-pi-extension.mjs61
-rwxr-xr-xtests/sdd-helper-paths/test-sdd-helper-paths.sh49
-rwxr-xr-xtests/skill-layout/test-no-dev-files-in-skills.sh25
-rw-r--r--tests/systematic-debugging/pressure-scenarios/CREATION-LOG.md (renamed from skills/systematic-debugging/CREATION-LOG.md)0
-rw-r--r--tests/systematic-debugging/pressure-scenarios/test-academic.md (renamed from skills/systematic-debugging/test-academic.md)0
-rw-r--r--tests/systematic-debugging/pressure-scenarios/test-pressure-1.md (renamed from skills/systematic-debugging/test-pressure-1.md)0
-rw-r--r--tests/systematic-debugging/pressure-scenarios/test-pressure-2.md (renamed from skills/systematic-debugging/test-pressure-2.md)0
-rw-r--r--tests/systematic-debugging/pressure-scenarios/test-pressure-3.md (renamed from skills/systematic-debugging/test-pressure-3.md)0
61 files changed, 1538 insertions, 240 deletions
diff --git a/.antigravity-plugin/plugin.json b/.antigravity-plugin/plugin.json
index 840fd04..4bcf9e6 100644
--- a/.antigravity-plugin/plugin.json
+++ b/.antigravity-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "superpowers",
"displayName": "Superpowers",
- "version": "7.0.1",
+ "version": "7.0.2",
"description": "Make your coding agent a better engineer",
"logo": "assets/antigravity-logo.png",
"suggestedPrompts": [
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 86e715c..214374d 100644
--- a/.claude-plugin/marketplace.json
+++ b/.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": "7.0.1",
+ "version": "7.0.2",
"source": "./",
"author": {
"name": "Jesse Vincent",
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 64b99c9..c3d4e53 100644
--- a/.claude-plugin/plugin.json
+++ b/.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": "7.0.1",
+ "version": "7.0.2",
"author": {
"name": "Jesse Vincent",
"email": "jesse@fsck.com"
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index faeb41f..b0bc130 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "superpowers",
- "version": "7.0.1",
+ "version": "7.0.2",
"description": "An agentic skills framework & software development methodology that works: planning, TDD, debugging, and collaboration workflows.",
"author": {
"name": "Jesse Vincent",
diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json
index 6ec43b4..2d2ebe9 100644
--- a/.cursor-plugin/plugin.json
+++ b/.cursor-plugin/plugin.json
@@ -2,7 +2,7 @@
"name": "superpowers",
"displayName": "Superpowers",
"description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
- "version": "7.0.1",
+ "version": "7.0.2",
"author": {
"name": "Jesse Vincent",
"email": "jesse@fsck.com"
diff --git a/.devin-plugin/plugin.json b/.devin-plugin/plugin.json
index cadbebd..dc98aa6 100644
--- a/.devin-plugin/plugin.json
+++ b/.devin-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "superpowers",
- "version": "7.0.1",
+ "version": "7.0.2",
"description": "An agentic skills framework & software development methodology that works: planning, TDD, debugging, and collaboration workflows.",
"author": {
"name": "Jesse Vincent",
diff --git a/.hermes-plugin/__init__.py b/.hermes-plugin/__init__.py
index 7d4e1f5..3c5a207 100644
--- a/.hermes-plugin/__init__.py
+++ b/.hermes-plugin/__init__.py
@@ -108,7 +108,9 @@ def register(ctx):
# 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.
+ # appended to the first turn's user message. delegate_task children run
+ # with platform="subagent" and an empty history, so every child's first
+ # turn would otherwise get the controller bootstrap too.
def pre_llm_call(
session_id=None,
user_message=None,
@@ -118,7 +120,7 @@ def register(ctx):
platform=None,
**kwargs,
):
- if is_first_turn:
+ if is_first_turn and platform != "subagent":
return {"context": bootstrap}
return None
diff --git a/.hermes-plugin/plugin.yaml b/.hermes-plugin/plugin.yaml
index cb8ae9a..1439624 100644
--- a/.hermes-plugin/plugin.yaml
+++ b/.hermes-plugin/plugin.yaml
@@ -1,5 +1,5 @@
name: superpowers
-version: 7.0.1
+version: 7.0.2
description: Superpowers skills and workflow bootstrap for Hermes Agent
author: obra
provides_hooks:
diff --git a/.kimi-plugin/plugin.json b/.kimi-plugin/plugin.json
index 379a3bd..412a82e 100644
--- a/.kimi-plugin/plugin.json
+++ b/.kimi-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "superpowers",
- "version": "7.0.1",
+ "version": "7.0.2",
"description": "An agentic skills framework and software development methodology.",
"author": {
"name": "Jesse Vincent",
diff --git a/.muse-plugin/marketplace.json b/.muse-plugin/marketplace.json
index 3531bc3..bb546f9 100644
--- a/.muse-plugin/marketplace.json
+++ b/.muse-plugin/marketplace.json
@@ -9,7 +9,7 @@
{
"name": "superpowers",
"description": "Core skills library for Muse: TDD, debugging, collaboration patterns, and proven techniques",
- "version": "7.0.1",
+ "version": "7.0.2",
"source": "./",
"author": {
"name": "Jesse Vincent",
diff --git a/.muse-plugin/plugin.json b/.muse-plugin/plugin.json
index c77b116..7399a92 100644
--- a/.muse-plugin/plugin.json
+++ b/.muse-plugin/plugin.json
@@ -2,7 +2,7 @@
"schemaVersion": 1,
"name": "superpowers",
"displayName": "Superpowers",
- "version": "7.0.1",
+ "version": "7.0.2",
"description": "Core skills library for Muse: TDD, debugging, collaboration patterns, and proven techniques",
"compat": {
"source": "native",
@@ -77,7 +77,7 @@
"id": "session-start",
"event": "SessionStart",
"command": [
- "sh",
+ "bash",
"hooks/session-start"
],
"timeoutMs": 5000
diff --git a/.opencode/INSTALL.md b/.opencode/INSTALL.md
index c60682f..e3f5fd7 100644
--- a/.opencode/INSTALL.md
+++ b/.opencode/INSTALL.md
@@ -79,7 +79,7 @@ V1 `plugin` key and the V2 `plugins` key):
```json
{
- "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v7.0.1"]
+ "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v7.0.2"]
}
```
diff --git a/.opencode/plugins/superpowers.js b/.opencode/plugins/superpowers.js
index 9eff811..d39c1ec 100644
--- a/.opencode/plugins/superpowers.js
+++ b/.opencode/plugins/superpowers.js
@@ -9,7 +9,8 @@
*
* V2 (opencode2): loaded via default export { id, setup } by PluginSupervisor.
* setup() registers skills natively via ctx.skill.transform(), and injects
- * bootstrap context via ctx.session.hook("context").
+ * bootstrap context via ctx.session.hook on `context`, `compaction`, and
+ * `generate` so every request shape carries the same cached prefix.
*
* No external dependencies — pure JavaScript works in both V1 and V2 without
* installing @opencode-ai/plugin or effect.
@@ -78,7 +79,7 @@ export const V1_MAPPING = `**Tool Mapping for OpenCode:**
When skills request actions, substitute OpenCode equivalents:
- Create or update todos → \`todowrite\`
- \`Subagent (general-purpose):\` → \`task\` with \`subagent_type: "general"\`
-- Invoke a skill → OpenCode's native \`skill\` tool
+- Invoke a skill → OpenCode's native \`skill\` tool. Skill ids are bare names, so drop the \`superpowers:\` prefix skills use when they name each other (\`superpowers:brainstorming\` → \`skill\` with \`name: "brainstorming"\`)
- Read files → \`read\`
- Create, edit, or delete files → \`apply_patch\`
- Run shell commands → \`bash\`
@@ -96,7 +97,7 @@ export const V2_MAPPING = `**Tool Mapping for OpenCode:**
When skills request actions, substitute OpenCode equivalents:
- Create or update todos → OpenCode v2 has no todo tool; track the plan in a markdown file (or the harness's plan facility) instead
- \`Subagent (general-purpose):\` → \`subagent\` with \`agent: "general"\` (give it \`description\` and \`prompt\`, optionally \`background\`; pass \`sessionID\` to continue a previous subagent)
-- Invoke a skill → OpenCode's native \`skill\` tool
+- Invoke a skill → OpenCode's native \`skill\` tool. Skill ids are bare names, so drop the \`superpowers:\` prefix skills use when they name each other (\`superpowers:brainstorming\` → \`skill\` with \`id: "brainstorming"\`)
- Read files → \`read\`
- Create, edit, or delete files → use \`patch\` with \`patchText\` when available; otherwise use \`write\` to create or overwrite files, \`edit\` for targeted changes, and \`shell\` for deletion
- Run shell commands → \`shell\` (\`command\`, \`workdir\`, \`timeout\`, \`background\`)
@@ -112,6 +113,11 @@ Use OpenCode's native \`skill\` tool to list and load skills.`;
// regex work on every agent step. See #1202 for the full analysis.
const _bootstrapCache = new Map(); // mapping -> bootstrap (null = file missing)
+// Opening of every injected bootstrap part. The already-injected guards match
+// it at the start of a part, so a prompt that merely mentions the tag (#2197)
+// is not mistaken for the bootstrap.
+const BOOTSTRAP_MARKER = '<EXTREMELY_IMPORTANT>\nYou have superpowers.';
+
// Helper to generate bootstrap content (cached after first call per mapping)
const getBootstrapContent = (toolMapping) => {
// Return cached result on subsequent calls
@@ -127,8 +133,7 @@ const getBootstrapContent = (toolMapping) => {
const fullContent = fs.readFileSync(skillPath, 'utf8');
const { content } = extractAndStripFrontmatter(fullContent);
- _bootstrapCache.set(toolMapping, `<EXTREMELY_IMPORTANT>
-You have superpowers.
+ _bootstrapCache.set(toolMapping, `${BOOTSTRAP_MARKER}
**IMPORTANT: The using-superpowers skill content is included below. It is ALREADY LOADED - you are currently following it. Do NOT use the skill tool to load "using-superpowers" again - that would be redundant.**
@@ -248,7 +253,7 @@ export const SuperpowersPlugin = async ({ client, directory }) => {
if (!firstUser || !firstUser.parts.length) return;
// Guard: skip if first user message already contains bootstrap.
- if (firstUser.parts.some(p => p.type === 'text' && p.text.includes('EXTREMELY_IMPORTANT'))) return;
+ if (firstUser.parts.some(p => p.type === 'text' && p.text.startsWith(BOOTSTRAP_MARKER))) return;
// #2160: never restart the controller workflow inside task subagent
// (child) sessions. V1 passes no input to this hook (verified in the
@@ -280,8 +285,12 @@ export const SuperpowersPlugin = async ({ client, directory }) => {
* is `path` — renamed from `location` in upstream commit 199aabe9e2,
* first released in v2.0.4.
* See packages/core/src/plugin/skill.ts and packages/schema/src/skill.ts.
- * 2. Injects bootstrap context via ctx.session.hook("context"), the V2
- * equivalent of V1's experimental.chat.messages.transform.
+ * 2. Injects bootstrap context via ctx.session.hook on `context`,
+ * `compaction`, and `generate` — the V2 equivalents of V1's
+ * experimental.chat.messages.transform. OpenCode's built-in plugins
+ * register on all three; skipping any one makes that request's prompt
+ * diverge from the cached prefix at the first user message, which for a
+ * large session forces a cold re-prefill. See issue #2391.
*/
async function setup(ctx) {
// V1 (observed on opencode 1.18.18) also invokes default.setup, but with a
@@ -334,38 +343,51 @@ async function setup(ctx) {
console.error('[superpowers] skill registration failed:', err);
}
- // 2. Inject bootstrap into first user message via V2 session context hook
- try {
- await ctx.session.hook('context', async (event) => {
- try {
- const bootstrap = getBootstrapContent(V2_MAPPING);
- if (!bootstrap || !event.messages || !event.messages.length) return;
- const firstUser = event.messages.find(m => m.role === 'user');
- if (firstUser && (!firstUser.content || !firstUser.content.length)) return;
- if (firstUser?.content.some(p => p.type === 'text' && p.text && p.text.includes('EXTREMELY_IMPORTANT'))) return;
-
- // #2160: the context event carries the sessionID directly. Skip the
- // controller bootstrap when this prompt belongs to a task subagent
- // (child) session. Skills registered above stay available to workers.
- if (typeof ctx.session.get === 'function' && await isChildSession(
- (id) => ctx.session.get({ sessionID: id }),
- event.sessionID,
- )) return;
-
- // Native compaction can leave only an opaque checkpoint. Keep it
- // intact and append the transient bootstrap as a user message.
- if (firstUser) {
- firstUser.content.unshift({ type: 'text', text: bootstrap });
- } else {
- event.messages.push({ role: 'user', content: [{ type: 'text', text: bootstrap }] });
- }
- } catch (err) {
- // Never let hook callback errors break the request pipeline.
- console.error('[superpowers] context hook failed:', err);
+ // 2. Inject bootstrap into first user message via V2 session hooks.
+ // OpenCode V2 dispatches three request shapes — context (normal turn),
+ // compaction (auto-summary), and generate (explicit generation). The
+ // compaction payload is the same `{ sessionID, messages, ... }` shape as
+ // context (observed on 2.1.2/2.1.3); generate's is taken from upstream
+ // source and the built-in plugins, not observed. OpenCode's
+ // own built-in plugins register on all three; if superpowers only covers
+ // `context`, the other two requests diverge from the cached prefix at
+ // exactly the position the bootstrap would have occupied, forcing a cold
+ // re-prefill of the whole session on the largest request of its lifetime.
+ // See issue #2391.
+ const injectBootstrap = async (event) => {
+ try {
+ const bootstrap = getBootstrapContent(V2_MAPPING);
+ if (!bootstrap || !event.messages || !event.messages.length) return;
+ const firstUser = event.messages.find(m => m.role === 'user');
+ if (firstUser && (!firstUser.content || !firstUser.content.length)) return;
+ if (firstUser?.content.some(p => p.type === 'text' && p.text && p.text.startsWith(BOOTSTRAP_MARKER))) return;
+
+ // #2160: the request event carries the sessionID directly. Skip the
+ // controller bootstrap when this prompt belongs to a task subagent
+ // (child) session. Skills registered above stay available to workers.
+ if (typeof ctx.session.get === 'function' && await isChildSession(
+ (id) => ctx.session.get({ sessionID: id }),
+ event.sessionID,
+ )) return;
+
+ // Native compaction can leave only an opaque checkpoint. Keep it
+ // intact and append the transient bootstrap as a user message.
+ if (firstUser) {
+ firstUser.content.unshift({ type: 'text', text: bootstrap });
+ } else {
+ event.messages.push({ role: 'user', content: [{ type: 'text', text: bootstrap }] });
}
- });
- } catch (err) {
- console.error('[superpowers] session hook registration failed:', err);
+ } catch (err) {
+ // Never let hook callback errors break the request pipeline.
+ console.error('[superpowers] session hook failed:', err);
+ }
+ };
+ for (const hookName of ['context', 'compaction', 'generate']) {
+ try {
+ await ctx.session.hook(hookName, injectBootstrap);
+ } catch (err) {
+ console.error(`[superpowers] session hook registration failed (${hookName}):`, err);
+ }
}
}
diff --git a/.pi/extensions/superpowers.ts b/.pi/extensions/superpowers.ts
index a978e80..3b38adf 100644
--- a/.pi/extensions/superpowers.ts
+++ b/.pi/extensions/superpowers.ts
@@ -16,10 +16,6 @@ let cachedBootstrap: string | null | undefined;
export default function superpowersPiExtension(pi: ExtensionAPI) {
let injectBootstrap = true;
- pi.on("resources_discover", async () => ({
- skillPaths: [skillsDir],
- }));
-
pi.on("session_start", async () => {
injectBootstrap = true;
});
@@ -28,10 +24,9 @@ export default function superpowersPiExtension(pi: ExtensionAPI) {
injectBootstrap = true;
});
- pi.on("agent_end", async () => {
- injectBootstrap = false;
- });
-
+ // Messages returned from a context handler are sent to the provider but never
+ // written to session history, so the bootstrap has to be injected into every
+ // provider request, on every prompt, for the whole session.
pi.on("context", async (event) => {
if (!injectBootstrap) return;
if (event.messages.some(messageContainsBootstrap)) return;
diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md
index f63b820..67397fd 100644
--- a/RELEASE-NOTES.md
+++ b/RELEASE-NOTES.md
@@ -1,5 +1,61 @@
# Superpowers Release Notes
+## v7.0.2 (2026-11-03)
+
+This release further tunes brainstorming's questions. It asks fewer of them, starts by asking why, and when there's a choice to make it gives you options to pick from. It also fixes bootstrap problems on six harnesses, and makes the SDD and executing-plans helper scripts much harder to point at the wrong repository or the wrong task.
+
+### Brainstorming
+
+- **It asks a question only when the answer would change what gets built and nothing already answers it.** Otherwise it states its call as a proposal you can correct. It also stops asking about process: writing things up, where files go, whether to look further, and how to show you something are its own calls, and it tells you what it decided. (#2644)
+- **When you haven't said why you want something, that's the first thing it asks.** It asks openly, with no example answers to pick from. (#2644)
+- **When there's a choice it can name, it shows you the options with a recommendation.** In one of our test scenarios, where a spec gives Ctrl+K to two features, 7.0.1 found the conflict every time but asked a bare "which one?" in 8 of 8 runs. This release laid out the options and recommended one in 8 of 8. (#2644)
+- **It reads from how you talk whether you want to discuss the technical choices,** and when your request leaves nothing open, its first message is a short design for you to approve. (#2644)
+- In blind-graded test conversations, filler questions dropped from 41 with 7.0.1 to 23, the reason behind the request came out before any approach in 33 of 33 conversations (28 of 33 before), and nothing got built before approval (4 times before). Against 6.4.2's brainstorming in the same scenarios, it had fewer filler questions (23 against 34), drew out the why far more often (33 of 33 against 19 of 33), and matched it at building nothing before approval. (#2644)
+- **`start-server.sh --project-dir .` now works.** The script `cd`s into its own directory before starting the server, so every path it derived from a relative `--project-dir` pointed to the wrong place, and the server never started. It now resolves the directory first. Thanks @anchore-jesset for the report. (#2524, #2608)
+
+Thanks to @mbcrawfo and everyone on #2530 who sent transcripts and tested 7.0.1. If brainstorming still asks you something it shouldn't, please tell us there, with what you asked and what it asked back.
+
+### Hooks
+
+- **Copilot on Windows now gets the bootstrap.** Copilot CLI and VS Code Copilot run hook commands through PowerShell, which rejected the SessionStart command with a ParserError. `hooks.json` now has a `powershell` form of the command. Thanks @ronpieper-engcp and @orty for the reports. (#2189, #1225, #2592)
+- **The SessionStart hook starts no child processes.** On Git Bash, each one costs tens of milliseconds, and the hook started six of them on every startup, `/clear` and compaction. Thanks @midirectiekade14-debug for the report and measurements. (#2081, #2593)
+- **On a Unix system without bash, `run-hook.cmd` falls back to zsh, or exits quietly.** It used to exit 127 with `bash: not found`, and the bootstrap was lost. (#2503, #2594)
+
+### Pi
+
+- **Every prompt now gets the bootstrap.** The extension turned the bootstrap off after the first prompt of a session, so every later prompt went without it. Because the first message of the request changed, Anthropic prompt caching also rewrote the whole conversation's cache on the second prompt. Over a day of sessions, @sjawhar measured 83% of first-to-second-prompt transitions rewriting the cache. Thanks @DKnight927 for the report. (#2083, #2595)
+- **The `skills` filter on the Superpowers package entry works.** The extension re-added the whole `skills/` directory after pi applied the filter, so `"skills": []` still loaded all 15 skills. Thanks @adrian-85 for the report and @m2dumpling for the fix. (#2394, #2402, #2598)
+
+### Hermes Agent
+
+- **`delegate_task` subagents no longer get the controller's bootstrap.** Every child started with an empty history, so each one looked like a new session and got the full bootstrap, and some started by loading `using-superpowers` instead of doing their task. Thanks @thealps01-netizen for the report. (#2536, #2596)
+
+### OpenCode
+
+- **The bootstrap tells the model to use bare skill ids.** OpenCode registers skills as `brainstorming`, not `superpowers:brainstorming`, so a model that copied the namespaced form from the bootstrap got "skill not found" and went on without the skill. Thanks @shiluoluo16 for the report. (#2583, #2597)
+- **A prompt that mentions `EXTREMELY_IMPORTANT` no longer turns the bootstrap off.** The plugin decided the bootstrap was already there if the first message contained that word, so asking "is there an EXTREMELY_IMPORTANT block in your context?" was enough to drop it. It now looks for the bootstrap's own first line. Thanks @Swift22 for the report. (#2197, #2600)
+- **OpenCode 2's compaction and generate requests carry the bootstrap.** Without it, the compaction request, the largest of the session, missed the prompt cache. Thanks @tpischke for the report and measurements. (#2391, #2601)
+
+### Muse
+
+- **The SessionStart hook now runs on Debian and Ubuntu.** Muse's manifest ran `hooks/session-start`, a bash script, with `sh`. Where `sh` is dash, the hook failed with exit 2 and the bootstrap never loaded. It now runs with `bash`. Thanks @rahul05ranjan for the report and @twotnguyen for the fix. (#2528, #2533)
+
+### Subagent-Driven Development and Executing Plans
+
+- **The helpers act on the repository of the current directory, as `git` does, and take `-C DIR` to point at another.** Outside a repository, `sdd-workspace` used to write its workspace into whatever directory the agent was in, often the plugin cache. All five helpers now stop with exit 2 and a message that tells your agent what to do. In a new project with no commits yet, your agent will need to run `git init` and make a first commit before it can start. `-C` also lets a controller review a worktree without a `cd … ;` prefix that Claude Code can't allowlist. Thanks @abat-kek, @rz1989s, and @jiyimeta for the reports. (#2429, #2242, #1799, #2606)
+- **The skills say to run the helpers by absolute path from your working tree.** They used to say "from this skill's directory", and agents that `cd`'d there ran the helpers against the plugin's own files. A test now fails if a skill names a helper by a relative path. Thanks @anchore-jesset for the report. (#2525, #2607)
+- **`task-brief` finds tasks with IDs like `A1`, `6b`, and `2.1`.** It used to reject letter-first IDs entirely, and asking for Task 6 also picked up Task 6b. When a plan's task headings aren't in English, it now says they must use the word "Task" and shows the headings it found. Thanks @rhuthik, @jnrod03-rgb, @christopherpconway, and @ferrous26 for the reports. (#2459, #2496, #2175, #2405, #2604)
+- **`task-brief` refuses a brief that an unclosed code fence ran to the end of the plan.** One missing closing fence hid every later task heading, and the reporter's 177-line task came back as a 1,159-line brief holding five tasks. Thanks @bobbykim89 for the report. (#2436, #2605)
+- **On Windows, the helpers print paths PowerShell can open.** They printed `/c/Users/…`, which PowerShell reads as `C:\c\Users\…`. Thanks @sean-parent for the report. (#2307, #2602)
+
+### Systematic Debugging
+
+- **The skill no longer installs its own test scenarios.** `CREATION-LOG.md` and four pressure-test prompts, which open with "This is a real scenario. You must choose and act", installed next to `SKILL.md` and could be found by an agent mid-task. They now live under `tests/`, and a test keeps files like these out of every skill. Thanks @Caarles00 for the report. (#2277, #2654)
+
+### Maintenance
+
+- `scripts/package-codex-plugin.sh` and `scripts/sync-to-codex-plugin.sh` work from a linked git worktree. (#2609)
+
## v7.0.1 (2026-10-21)
This release retunes brainstorming after its rebuild in v7.0.0. Many of you told us, rightly, that the new default questions got annoying fast and felt formulaic. Brainstorming now digs for context before it asks anything, and tries to ask better questions. We expect to keep tuning it, but we think it's better than it was.
diff --git a/docs/README.opencode.md b/docs/README.opencode.md
index 3ffdd81..6509d84 100644
--- a/docs/README.opencode.md
+++ b/docs/README.opencode.md
@@ -111,7 +111,7 @@ V1 `plugin` key and the V2 `plugins` key):
```json
{
- "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v7.0.1"]
+ "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v7.0.2"]
}
```
@@ -126,7 +126,7 @@ The plugin does two things, using host-flavor-specific APIs:
- **V2:** via the `setup()` function using `ctx.skill.transform()` (V2 native API, confirmed active at runtime)
2. **Injects bootstrap context** with a flavor-specific tool mapping: V1 sessions get the V1 tool names below, and V2 sessions get the V2 names.
- **V1:** via `experimental.chat.messages.transform` hook
- - **V2:** via `ctx.session.hook("context")` — the V2 equivalent (confirmed active at runtime)
+ - **V2:** via `ctx.session.hook()` on `context`, `compaction`, and `generate` — the V2 equivalent (confirmed active at runtime). Registering on all three keeps compaction requests on the same cached prompt prefix as normal turns.
Controller sessions receive the using-superpowers bootstrap in transient model
context. Delegated child sessions keep access to native skills but do not receive
@@ -148,7 +148,7 @@ Skills speak in actions rather than naming any one runtime's tools. The bootstra
- "Create a todo" / "mark complete in todo list" → `todowrite`
- `Subagent (general-purpose):` template → OpenCode's `task` tool with `subagent_type: "general"` (or `"explore"` for codebase exploration)
-- "Invoke a skill" → OpenCode's native `skill` tool
+- "Invoke a skill" → OpenCode's native `skill` tool with the bare skill name (`superpowers:brainstorming` → `name: "brainstorming"`)
- "Read a file" → `read`
- "Create a file" / "edit a file" / "delete a file" → `apply_patch`
- "Run a shell command" → `bash`
@@ -159,7 +159,7 @@ Skills speak in actions rather than naming any one runtime's tools. The bootstra
- "Create a todo" → V2 has no todo tool of any kind; the mapping tells the model to track the plan in a markdown file (or the harness's plan facility) instead
- `Subagent (general-purpose):` template → OpenCode's `subagent` tool with `agent: "general"` (or `"explore"`); pass `sessionID` to continue a previous subagent
-- "Invoke a skill" → OpenCode's native `skill` tool
+- "Invoke a skill" → OpenCode's native `skill` tool with the bare skill id (`superpowers:brainstorming` → `id: "brainstorming"`)
- "Read a file" → `read`
- "Create, edit, or delete files" → use `patch` with `patchText` when available; otherwise use `write` to create or overwrite files, `edit` for targeted changes, and `shell` for deletion
- "Run a shell command" → `shell` (`command`, `workdir`, `timeout`, `background`)
@@ -234,7 +234,7 @@ package name, not a local directory.
### Bootstrap not appearing
- **V1:** Check OpenCode version supports `experimental.chat.messages.transform` hook. Restart OpenCode after config changes.
-- **V2:** The plugin uses `ctx.session.hook("context")` for bootstrap injection. Verify the plugin loaded via `opencode api get /api/plugin`. Restart with `opencode service restart` after config changes. The `opencode2` command may be available as an alias.
+- **V2:** The plugin uses `ctx.session.hook()` on `context`, `compaction`, and `generate` for bootstrap injection. Verify the plugin loaded via `opencode api get /api/plugin`. Restart with `opencode service restart` after config changes. The `opencode2` command may be available as an alias.
## Getting Help
diff --git a/docs/porting-to-a-new-harness.md b/docs/porting-to-a-new-harness.md
index f52cd70..a48ecdf 100644
--- a/docs/porting-to-a-new-harness.md
+++ b/docs/porting-to-a-new-harness.md
@@ -428,10 +428,9 @@ messages break some models (#894). Three things you must replicate:
harness-specific constant.) Cache the bootstrap content at module level so
you're not re-reading and re-parsing `SKILL.md` on every call (#1202).
- **Compaction.** If the harness compacts/summarizes history, re-inject
- afterward. pi sets an `injectBootstrap` flag on `session_start` and
- `session_compact`, clears it on `agent_end`, and inserts the message *after*
- any leading compaction-summary messages. OpenCode relies on its per-step
- re-injection plus the dedup guard.
+ afterward. pi re-injects on every `context` call and inserts the message
+ *after* any leading compaction-summary messages. OpenCode relies on its
+ per-step re-injection plus the dedup guard.
- **Message-object shape is per-harness — discover yours, don't copy a literal.**
The two references use *incompatible* shapes: pi builds
`{ role, content: [{ type, text }], timestamp }`; OpenCode manipulates
@@ -519,8 +518,8 @@ honors the rule rather than breaking it. Distinguish three cases:
`activate_skill`): point the mapping at that tool.
2. **Native skill *discovery* but no `Skill` tool** (pi, Antigravity): the harness
can find and list skills, but the model can't call a tool to load one. Get the
- skills installed where the harness scans (pi registers via `resources_discover`
- → `skillPaths`; OpenCode via its `config` hook; `agy plugin install` copies
+ skills installed where the harness scans (pi declares them in the package
+ manifest's `pi.skills`; OpenCode via its `config` hook; `agy plugin install` copies
them in), and tell the model to load a skill by **reading its `SKILL.md` with
the file-read tool when the skill applies** — the sanctioned mechanism here,
the way `references/pi-tools.md` states it.
@@ -810,8 +809,8 @@ Use this as the live index; when in doubt, read the files, not this table.
| 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` (root `package.json` `main` for package installs; root `index.js` re-export for the V2 directory form) | in-process: `config` hook registers skills dir; `experimental.chat.messages.transform` (V1) / `session.hook("context")` (V2) injects user message | inline in `superpowers.js` | `tests/opencode/` | `opencode.json` `plugin` (V1) / `plugins` (V2) git URL |
-| pi | `.pi/extensions/superpowers.ts` | in-process: `resources_discover` registers skills; `context` event injects user message; lifecycle-flag + compaction-aware | `piToolMapping()` inline **and** `references/pi-tools.md` | `tests/pi/` | repo-root `package.json` fields |
+| OpenCode | `.opencode/plugins/superpowers.js` (root `package.json` `main` for package installs; root `index.js` re-export for the V2 directory form) | in-process: `config` hook registers skills dir; `experimental.chat.messages.transform` (V1) / `session.hook` on `context`/`compaction`/`generate` (V2) injects user message | inline in `superpowers.js` | `tests/opencode/` | `opencode.json` `plugin` (V1) / `plugins` (V2) git URL |
+| pi | `.pi/extensions/superpowers.ts` | in-process: package manifest registers skills; `context` event injects user message; lifecycle-flag + compaction-aware | `piToolMapping()` inline **and** `references/pi-tools.md` | `tests/pi/` | repo-root `package.json` fields |
## Appendix B — Gotchas that have bitten porters
@@ -827,9 +826,11 @@ Use this as the live index; when in doubt, read the files, not this table.
(Cursor). Use what your harness exports; the script re-derives the root itself.
- **System-message injection.** Shape B injects a *user* message on purpose
(#750, #894). Don't "fix" it to a system message.
-- **Per-step vs per-turn callbacks.** OpenCode fires every step (per-call dedup
- guard); pi fires per turn (lifecycle flag + `agent_end` reset). Copying one
- harness's dedup strategy onto the other's callback frequency breaks injection.
+- **Disarming injection after the first prompt.** If your harness's transform
+ output is not saved to session history (pi's `context` result is not), the
+ bootstrap must be injected into every provider request. A flag cleared on a
+ per-prompt event such as pi's `agent_end` drops the bootstrap after the first
+ prompt (#2083).
- **Message-object shape is per-harness.** Shape B. pi and OpenCode use
incompatible shapes; discover yours, don't copy a reference's object literal.
- **Hunting for a skill-registration API that doesn't exist.** A harness with no
diff --git a/docs/windows/polyglot-hooks.md b/docs/windows/polyglot-hooks.md
index 3da01ae..d753d90 100644
--- a/docs/windows/polyglot-hooks.md
+++ b/docs/windows/polyglot-hooks.md
@@ -51,6 +51,7 @@ hooks/
{
"type": "command",
"command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+ "powershell": "& \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
"shell": "bash",
"async": false
}
@@ -63,6 +64,15 @@ hooks/
The path is quoted because `${CLAUDE_PLUGIN_ROOT}` may contain spaces.
+### The `powershell` key
+
+GitHub Copilot (the CLI and VS Code) on Windows runs hook commands through
+PowerShell regardless of the `shell` key (#2189), where a leading quoted path
+parses as a string expression and the trailing bareword is an error
+("Unexpected token 'session-start'"). Copilot uses the `powershell` key
+instead of `command` when it is present, and it gives the same dispatch with
+the `&` call operator. Claude Code ignores the key.
+
## How `run-hook.cmd` Works at a High Level
`run-hook.cmd` is a polyglot script: Windows treats the first block as batch
diff --git a/gemini-extension.json b/gemini-extension.json
index 18e983b..1274bf5 100644
--- a/gemini-extension.json
+++ b/gemini-extension.json
@@ -1,6 +1,6 @@
{
"name": "superpowers",
"description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
- "version": "7.0.1",
+ "version": "7.0.2",
"contextFileName": "GEMINI.md"
}
diff --git a/hooks/hooks.json b/hooks/hooks.json
index 6797513..8b33bbe 100644
--- a/hooks/hooks.json
+++ b/hooks/hooks.json
@@ -7,6 +7,7 @@
{
"type": "command",
"command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+ "powershell": "& \"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
"shell": "bash",
"async": false
}
diff --git a/hooks/run-hook.cmd b/hooks/run-hook.cmd
index a2f7c48..4501021 100755
--- a/hooks/run-hook.cmd
+++ b/hooks/run-hook.cmd
@@ -53,10 +53,27 @@ CMDBLOCK
# running) instead of a PATH lookup for bash, so this keeps working when
# Claude Code spawns the SessionStart hook with a broken/empty PATH
# (anthropics/claude-code#43127).
+# No $(cd ... && pwd) subshell: a fork costs tens of milliseconds under Git
+# Bash on Windows, and a relative directory is enough for the exec below.
case "$0" in
- */*|*\\*) SCRIPT_DIR="$(cd "${0%[/\\]*}" && pwd)" ;;
- *) SCRIPT_DIR="$(pwd)" ;;
+ */*|*\\*) SCRIPT_DIR="${0%[/\\]*}" ;;
+ *) SCRIPT_DIR="." ;;
esac
SCRIPT_NAME="$1"
shift
-exec "${BASH:-bash}" "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
+
+# Without bash installed, the harness runs this file with zsh or sh and $BASH
+# is unset (#2503). session-start runs unchanged under zsh, so fall back to
+# it, and otherwise exit quietly like the Windows half: the plugin still
+# works, just without SessionStart context injection.
+if [ -n "${BASH:-}" ]; then
+ shell="$BASH"
+elif command -v bash >/dev/null 2>&1; then
+ shell="bash"
+elif command -v zsh >/dev/null 2>&1; then
+ shell="zsh"
+else
+ exit 0
+fi
+
+exec "$shell" "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
diff --git a/hooks/session-start b/hooks/session-start
index 63f82a6..d88e50f 100755
--- a/hooks/session-start
+++ b/hooks/session-start
@@ -9,24 +9,32 @@ set -euo pipefail
# dirname because a SessionStart:startup hook can run with a broken/empty
# PATH (anthropics/claude-code#43127) before any PATH-repairing sibling hook
# in the same startup batch takes effect.
+#
+# No command substitution or pipe runs in this script: each one forks, and a
+# fork costs tens of milliseconds under Git Bash on Windows. The paths stay
+# relative to the current directory, which is all the file read below needs.
case "$0" in
- */*|*\\*) SCRIPT_DIR="$(cd "${0%[/\\]*}" && pwd)" ;;
- *) SCRIPT_DIR="$(pwd)" ;;
+ */*|*\\*) SCRIPT_DIR="${0%[/\\]*}" ;;
+ *) SCRIPT_DIR="." ;;
esac
-PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+PLUGIN_ROOT="${SCRIPT_DIR}/.."
-# Read using-superpowers content via bash's builtin $(< file) instead of
-# cat, for the same PATH-independence reason.
+# Read using-superpowers content with the read builtin (no cat, for the same
+# PATH-independence reason, and no $(< file) subshell). read returns 1 at end
+# of file, hence || true; the loop drops trailing newlines as $(< file) did.
skill_md="${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md"
+using_superpowers_content="Error reading using-superpowers skill"
if [ -r "$skill_md" ]; then
- using_superpowers_content="$(<"$skill_md")"
-else
- using_superpowers_content="Error reading using-superpowers skill"
+ IFS= read -r -d '' using_superpowers_content < "$skill_md" || true
+ while [[ $using_superpowers_content == *$'\n' ]]; do
+ using_superpowers_content="${using_superpowers_content%$'\n'}"
+ done
fi
# Escape string for JSON embedding using bash parameter substitution.
# Each ${s//old/new} is a single C-level pass - orders of magnitude
-# faster than the character-by-character loop this replaces.
+# faster than the character-by-character loop this replaces. The result
+# goes to a variable instead of stdout, so no $(...) subshell is needed.
escape_for_json() {
local s="$1"
s="${s//\\/\\\\}"
@@ -34,10 +42,10 @@ escape_for_json() {
s="${s//$'\n'/\\n}"
s="${s//$'\r'/\\r}"
s="${s//$'\t'/\\t}"
- printf '%s' "$s"
+ using_superpowers_escaped="$s"
}
-using_superpowers_escaped=$(escape_for_json "$using_superpowers_content")
+escape_for_json "$using_superpowers_content"
session_context="<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**\n\n${using_superpowers_escaped}\n</EXTREMELY_IMPORTANT>"
# Output context injection as JSON.
@@ -51,21 +59,18 @@ session_context="<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the
# Uses printf instead of heredoc to work around bash 5.3+ heredoc hang.
# See: https://github.com/obra/superpowers/issues/571
#
-# emit_json pipes printf through `cat` when cat is on PATH, to absorb EPIPE
-# on Windows. On Windows + Git Bash, the harness can close the hook's stdout
-# before printf finishes, and Git Bash's printf reports that EPIPE as
-# "printf: write error: Permission denied", which `set -euo pipefail` lets
-# escape as a startup diagnostic every session. Letting cat receive the EPIPE
-# keeps it out of the hook's error path (#1612). When PATH is broken and cat
-# can't be found (#2310), it falls back to printf alone so context still
-# gets injected.
+# emit_json absorbs EPIPE without a pipe through `cat`. On Windows + Git
+# Bash, the harness can close the hook's stdout before printf finishes, and
+# Git Bash's printf reports that EPIPE as "printf: write error: Permission
+# denied", which `set -euo pipefail` would let escape as a startup diagnostic
+# every session (#1612). SIGPIPE is ignored so other platforms see the same
+# EPIPE error instead of a signal; the error message is dropped and the
+# status ignored. No external command is involved, so a broken PATH (#2310)
+# changes nothing.
emit_json() {
+ trap '' PIPE
# shellcheck disable=SC2059 # every caller passes a literal format string
- if command -v cat >/dev/null 2>&1; then
- printf "$@" | cat
- else
- printf "$@"
- fi
+ printf "$@" 2>/dev/null || true
}
if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
diff --git a/package.json b/package.json
index acc6562..b853495 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "superpowers",
- "version": "7.0.1",
+ "version": "7.0.2",
"description": "Superpowers skills and runtime bootstrap for coding agents",
"type": "module",
"main": ".opencode/plugins/superpowers.js",
diff --git a/scripts/package-codex-plugin.sh b/scripts/package-codex-plugin.sh
index 5308e28..fe90862 100755
--- a/scripts/package-codex-plugin.sh
+++ b/scripts/package-codex-plugin.sh
@@ -140,7 +140,7 @@ if [[ "$FORMAT" == "zip" ]]; then
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"
+[[ -e "$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"
diff --git a/scripts/sync-to-codex-plugin.sh b/scripts/sync-to-codex-plugin.sh
index fc80ab2..d1c65ca 100755
--- a/scripts/sync-to-codex-plugin.sh
+++ b/scripts/sync-to-codex-plugin.sh
@@ -179,7 +179,7 @@ command -v python3 >/dev/null || die "python3 not found in PATH"
gh auth status >/dev/null 2>&1 || die "gh not authenticated — run 'gh auth login'"
-[[ -d "$UPSTREAM/.git" ]] || die "upstream '$UPSTREAM' is not a git checkout"
+[[ -e "$UPSTREAM/.git" ]] || die "upstream '$UPSTREAM' is not a git checkout"
[[ -f "$UPSTREAM/.codex-plugin/plugin.json" ]] || die "committed Codex manifest missing at $UPSTREAM/.codex-plugin/plugin.json"
# Read the upstream version from the committed Codex manifest.
@@ -223,7 +223,7 @@ trap cleanup EXIT
if [[ -n "$LOCAL_CHECKOUT" ]]; then
DEST_REPO="$(cd "$LOCAL_CHECKOUT" && pwd)"
- [[ -d "$DEST_REPO/.git" ]] || die "--local path '$DEST_REPO' is not a git checkout"
+ [[ -e "$DEST_REPO/.git" ]] || die "--local path '$DEST_REPO' is not a git checkout"
else
echo "Cloning $FORK..."
CLEANUP_DIR="$(mktemp -d)"
diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md
index 7f5eef0..9eb0edc 100644
--- a/skills/brainstorming/SKILL.md
+++ b/skills/brainstorming/SKILL.md
@@ -31,6 +31,10 @@ Before you start implementing, you must, in order:
3. Get their approval of that doc.
4. Invoke the superpowers:writing-plans skill.
+If nothing is open when you write your first message and there's one
+sensible way, steps 1 to 3 happen in that message (see Your First
+Message).
+
Two things aren't implementing: a spike they said yes to (see Spike to
feel things out), and doing what they asked once they've opted out of
the questions.
@@ -42,7 +46,8 @@ a handoff, files they pointed at, earlier conversation), dig in before your
first message. Read what they referred to and the code or material it
connects to, and keep reading until you can explain how the relevant
parts work today and what this change would touch. Never ask what the
-project or their context already answers.
+project or their context already answers, or reopen what they've
+already decided.
## Your First Message
@@ -58,8 +63,17 @@ Move the work forward, with one of these:
has to be built, like a constraint, a conflict, or a cheaper path, say
so plainly. How to build it comes later, once you understand what they
want (see Lay out the approaches). End with one line inviting
- corrections, then one question about what they want: the thing their
- request leaves open whose answer would most change what gets built.
+ corrections. Then, if they haven't told you why they want it, even if
+ you can guess, ask about that: one open question in their own terms,
+ with nothing to pick from. If they have told you, and their request
+ and the project leave open something whose answer would change what
+ gets built, ask about the one that would change it most; when its
+ choices can be named, sketch each concretely, with what it trades off
+ and which you'd pick. If nothing like that is open, there's one
+ sensible way: end with the short design itself (the approach, a line on
+ why the others don't fit, and the design in a few lines) and ask them
+ to approve it. Their approval covers the approach and the design: write
+ the short design doc as approved and go on to the plan.
Specs are often incomplete, so confirm before you build on one.
- **They haven't:** one open question, in their own terms, about the
biggest thing their request leaves unsettled. Say why you're asking:
@@ -72,10 +86,9 @@ How the message ends depends on whether their message asked for
brainstorming:
- **They asked for it** (by name, by invoking it, or by asking for a
- design discussion): end with your question. They want this
- conversation.
-- **They didn't:** they may not want a conversation at all. After your
- question, add a light, one-line offer to just get going instead, like
+ design discussion): end there. They want this conversation.
+- **They didn't:** they may not want a conversation at all. End with a
+ light, one-line offer to just get going instead, like
"Or if you'd rather I just dive in, say so." If they take you up on
it, this skill is done: state any significant how-it-gets-made choice
(platform, language, medium) in one plain line, then do what they
@@ -85,28 +98,33 @@ That's the whole message.
## The Conversation
-Each message ends with one question: a single sentence with no list of
-example answers hanging off it. Use plain language, pitched just a little
-above where your human partner is. Match their vocabulary; never use
-process jargon. You never need to quote this skill to your human
-partner.
+Ask a question only when the answer would change what gets built and
+neither the request nor the project answers it. Otherwise, state your
+call and your reason as a proposal they can correct, and move the work
+forward. Process steps are always your calls: writing things up, where
+files go, looking further, how to show something. Do them and say so.
+Ask one at a time. Use plain language, pitched just a little above where
+your human partner is. Match their vocabulary; never use process jargon.
+You never need to quote this skill to your human partner.
Be clear and concise. Lead with what matters. Avoid jargon. When you
report what you found, give them the most important findings and offer
the rest.
-**Get them describing.** Open questions come first. Their own words carry
-intent that your options can't. Offer a short menu only when they're
-stuck. When they say "just guess" or "what do you think?", propose
-something concrete.
+**Get them describing.** Until you know why they want it, ask open
+questions, with no example answers attached. Their own words carry
+intent that your options can't. Once you know why, when a decision has
+choices you can name, sketch each concretely, with what it trades off
+and which you'd pick. When they say "just guess" or "what do you think?",
+propose something concrete.
**How it gets made.** Every project rests on choices about medium, tools,
materials, and resources: the platform, programming language, and
-libraries for an app; the medium for a piece of art. Find out early which
-of those choices they want to make, which they're handing to you, and what
-they already have to work with. Someone with strong views or skills will
-want to talk it through. Someone counting on you needs sensible defaults,
-said in plain words. When there's existing work, build on what it already
+libraries for an app; the medium for a piece of art. Read from how they
+talk which of those choices they want to make. Someone who raises the how
+or asks about trade-offs wants the options with your pick. Someone who
+talks about outcomes is handing you the how: make those calls and state
+each in a line. When there's existing work, build on what it already
uses. Any choice you make goes in the design as your call, never as
something they agreed to.
@@ -131,24 +149,26 @@ already plain, say what you're hoping to learn or what the answer would
change. A proposal they can correct, plus your reason for it, often
beats a question.
-**Offer recon.** Once you have a bit of grounding and looking further
-would help, offer to go look: deeper into their codebase or project,
-their own files and data, or the web. Say what you'd look for. They
-decide whether you go.
+**Do recon.** Once you have a bit of grounding and looking further
+would help, go look: deeper into their codebase or project, their own
+files and data, or the web. Say what you looked for and what you found.
**Lay out the approaches.** Once you understand what they want, and
before you write anything up, put the ways of building it in a message
of its own. Come up with several real alternatives and drop the weak
ones, including any that work against why they want it and any the
-existing work rules out. Present the two or three that remain, grounding
-each in what the project actually does and saying what it trades off.
-Recommend one and say why, then ask which way they want to go. When
-there's genuinely one sensible way, say so and explain why the others
-don't fit. This is for how it gets built; for what they want, get them
+existing work rules out. Sketch the two or three that remain concretely
+enough to picture, grounded in what the project actually does, with what
+each trades off. Recommend one and say why, then ask which way they want
+to go; if they've handed you the how, say you'll go with your pick
+instead. When there's genuinely one sensible way, say so in that
+message and explain why the others don't fit; the design comes in the
+next one. This is for how it gets built; for what they want, get them
describing first.
-**Show, don't tell.** Offer the visual companion (below) whenever seeing
-would help more than reading:
+**Show, don't tell.** Whenever seeing would help more than reading,
+sketch it in text: a few lines of what they'd see. Offer the visual
+companion (below) when the look itself is theirs to decide:
- something they'll look at: a screen, a page, a printout, a sign
- a layout or arrangement: of a screen, a room, a schedule
@@ -180,10 +200,11 @@ as your proposal, with your reason. End each chunk by asking what's wrong
or missing.
Before you send a chunk, check it: does it describe something they'll
-look at, like a page, a screen, a schedule, or a printout? If so, and
-they haven't seen the visual companion offer yet, send the offer instead
-(its own message, below) and hold the chunk for the next message. Once
-they've accepted, put a mockup next to the description.
+look at, like a page, a screen, a schedule, or a printout? If so, put a
+text sketch next to the description. If the look itself is theirs to
+decide and they haven't seen the visual companion offer yet, send the
+offer instead (its own message, below) and hold the chunk for the next
+message. Once they've accepted, put a mockup next to the description.
## Size the Work
@@ -223,7 +244,8 @@ builder check.
**Where it goes:** in a software repo,
`docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`, committed.
-Otherwise, ask. Your human partner's preferences override both.
+Otherwise, pick a sensible place and say where. Your human partner's
+preferences override both.
**Builder check** (for a project): dispatch a fresh subagent with
`builder-check-prompt.md` in this directory. When you tell your human
@@ -266,7 +288,7 @@ superpowers:writing-plans and no other skill.
|---------|---------|
| "I'll offer a menu of what they might want" | Options steer. Ask them to describe it first. |
| "I'll fill in sensible defaults" | Good. Say them out loud. A default they never heard is one they couldn't reject. |
-| "I've answered their questions, so I'll write the doc" | Lay out the approaches first, in a message of their own. |
+| "I've answered their questions, so I'll write the doc" | Lay out the approaches first, in a message of their own (or, when nothing was open from the start, in your first message's short design). |
| "I should explain the process first" | Ask your question. The process shows itself. |
| "They said 'sounds good' to the idea" | Approval covers what you showed them. A design doc you haven't written isn't approved. |
| "The spike works, I'll keep building on it" | Keeping it is a new request. Back through the gate. |
diff --git a/skills/brainstorming/scripts/start-server.sh b/skills/brainstorming/scripts/start-server.sh
index 016a8e4..f6d538a 100755
--- a/skills/brainstorming/scripts/start-server.sh
+++ b/skills/brainstorming/scripts/start-server.sh
@@ -114,6 +114,13 @@ umask 077
SESSION_ID="$$-$(date +%s)"
if [[ -n "$PROJECT_DIR" ]]; then
+ # Make the project dir absolute now: the script cds into its own directory
+ # before starting the server, which would re-root a relative path there.
+ # mkdir -p keeps the existing behavior of creating a missing project dir.
+ if ! PROJECT_DIR="$(mkdir -p -- "$PROJECT_DIR" && CDPATH='' cd -- "$PROJECT_DIR" && pwd)"; then
+ echo "{\"error\": \"Cannot create or enter --project-dir\"}"
+ exit 1
+ fi
SESSION_DIR="${PROJECT_DIR}/.superpowers/brainstorm/${SESSION_ID}"
# Persist the bound port and key per project so a restart reuses them and an
# already-open browser tab reconnects to the same URL with a valid cookie.
diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md
index ac77129..ea23196 100644
--- a/skills/executing-plans/SKILL.md
+++ b/skills/executing-plans/SKILL.md
@@ -123,7 +123,8 @@ The workspace and ledger are shared with superpowers:subagent-driven-development
and the new one resumes from the same ledger.
- Each plan owns a workspace: at skill start, run
- `../subagent-driven-development/scripts/sdd-workspace PLAN_FILE` — it
+ `../subagent-driven-development/scripts/sdd-workspace PLAN_FILE` by its
+ absolute path, from the working tree you're executing in — it
prints the plan's git-ignored directory
(`<repo-root>/.superpowers/sdd/<plan-basename>/`), home to every
artifact for THIS plan: ledger, briefs, review packages. Another plan's
@@ -169,7 +170,8 @@ in the workspace and read its tail; read a brief, not the whole plan.
### 1. Take the task
-- Run this skill's `scripts/task-start PLAN_FILE N`. It prints the brief
+- Run this skill's `scripts/task-start PLAN_FILE N` by its absolute path,
+ from the working tree you're executing in. It prints the brief
path and BASE (the commit the task's range is cut from) in one call.
Read the brief for every task, including ones you remember from setup:
what you remember is a summary, the brief has the exact values,
@@ -222,7 +224,7 @@ the claim. If any item is missing, the task is not complete: finish it.
### 4. Complete the task
Run this skill's `scripts/task-done PLAN_FILE N BASE -- <test command>`
-with the test command the brief names for the whole task. It runs the
+by its absolute path, from the working tree you're executing in, with the test command the brief names for the whole task. It runs the
tests, keeps the full output in the workspace, prints the tail, and — only
if they pass — appends the completion line to the ledger:
@@ -234,7 +236,7 @@ mark the todo complete and take the next task.
## Final Review
Run `../subagent-driven-development/scripts/review-package PLAN_FILE MERGE_BASE HEAD`
-(MERGE_BASE = the commit the branch started from, e.g.
+by its absolute path, from the working tree you're executing in (MERGE_BASE = the commit the branch started from, e.g.
`git merge-base main HEAD`) and review from the file it prints.
**With a subagent tool:** dispatch the reviewer on the most capable
diff --git a/skills/executing-plans/scripts/task-done b/skills/executing-plans/scripts/task-done
index e5fc6a9..d6400b4 100755
--- a/skills/executing-plans/scripts/task-done
+++ b/skills/executing-plans/scripts/task-done
@@ -20,7 +20,10 @@ base=$3
shift 4
sdd="$(cd "$(dirname "$0")/../../subagent-driven-development/scripts" && pwd)"
-git rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
+# The repository the workspace and ledger belong to (see sdd-repo); BASE and
+# HEAD are read there, not in the bare cwd.
+repo=$("${BASH:-bash}" "$sdd/sdd-repo" --with-commit)
+git -C "$repo" rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
dir=$("$sdd/sdd-workspace" "$plan")
log="$dir/task-${n}-tests.log"
@@ -47,6 +50,6 @@ fi
last=$(grep -v '^[[:space:]]*$' "$log" | tail -n 1) || last="(no output)"
[ -f "$ledger" ] || printf '# SDD ledger — plan: %s\n' "$plan" > "$ledger"
-line="Task $n: complete (commits $(git rev-parse --short=7 "$base")..$(git rev-parse --short=7 HEAD), tests: $cmd → $last)"
+line="Task $n: complete (commits $(git -C "$repo" rev-parse --short=7 "$base")..$(git -C "$repo" rev-parse --short=7 HEAD), tests: $cmd → $last)"
printf '%s\n' "$line" >> "$ledger"
echo "ledger: $line"
diff --git a/skills/executing-plans/scripts/task-start b/skills/executing-plans/scripts/task-start
index fab75b5..04f1c65 100755
--- a/skills/executing-plans/scripts/task-start
+++ b/skills/executing-plans/scripts/task-start
@@ -20,9 +20,13 @@ plan=$1
n=$2
sdd="$(cd "$(dirname "$0")/../../subagent-driven-development/scripts" && pwd)"
+# BASE comes from the same repository the brief is written into (sdd-repo
+# also refuses one with no commit yet), not from the bare cwd.
+repo=$("${BASH:-bash}" "$sdd/sdd-repo" --with-commit)
out=$("$sdd/task-brief" "$plan" "$n")
brief=$(printf '%s\n' "$out" | sed -n 's/^wrote \(.*\): [0-9][0-9]* lines$/\1/p')
[ -n "$brief" ] || { echo "task-brief did not report a path: $out" >&2; exit 1; }
+base=$(git -C "$repo" rev-parse --verify HEAD)
echo "brief: $brief"
-echo "base: $(git rev-parse HEAD)"
+echo "base: $base"
diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md
index ea170ed..4519578 100644
--- a/skills/subagent-driven-development/SKILL.md
+++ b/skills/subagent-driven-development/SKILL.md
@@ -111,7 +111,8 @@ 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
- `bash scripts/sdd-workspace PLAN_FILE` — it prints the plan's git-ignored
+ `bash scripts/sdd-workspace PLAN_FILE` by its absolute path, from the
+ working tree you're executing in — it prints the plan's git-ignored
directory (under `<repo-root>/.superpowers/sdd/`), home to
every artifact for THIS plan: ledger, briefs, reports, review packages.
Another plan's directory is never yours to read or write.
@@ -200,7 +201,8 @@ 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
- `bash scripts/task-brief PLAN_FILE N` — it extracts the task's full text to a
+ `bash scripts/task-brief PLAN_FILE N` by its absolute path, from the
+ working tree you're executing in — 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
@@ -238,7 +240,7 @@ Template: [implementer-prompt.md](implementer-prompt.md)
Implementer subagents report one of four statuses. Handle each appropriately:
-**DONE:** Generate the review package (`bash 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:** Generate the review package (`bash scripts/review-package PLAN_FILE BASE HEAD` by its absolute path, from the working tree you're executing in — 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.
**Any other status** (DONE_WITH_CONCERNS, NEEDS_CONTEXT, BLOCKED): read
[references/handling-reports.md](references/handling-reports.md) and follow
@@ -257,7 +259,8 @@ required. Implementer self-review never replaces the task review; both are
needed.
- Hand the reviewer its diff as a file: run this skill's
- `bash scripts/review-package PLAN_FILE BASE HEAD` and pass the reviewer the file path
+ `bash scripts/review-package PLAN_FILE BASE HEAD` by its absolute path, from
+ the working tree you're executing in, 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
diff --git a/skills/subagent-driven-development/re-review-prompt.md b/skills/subagent-driven-development/re-review-prompt.md
index d49c182..eb520df 100644
--- a/skills/subagent-driven-development/re-review-prompt.md
+++ b/skills/subagent-driven-development/re-review-prompt.md
@@ -110,6 +110,7 @@ Subagent (general-purpose):
- `[FIX_BASE_SHA]` — the head the previous review saw
- `[HEAD_SHA]` — current commit
- `[DIFF_FILE]` — the path `bash scripts/review-package PLAN_FILE FIX_BASE HEAD` printed
+ (run by its absolute path, from the working tree you're executing in)
**Re-reviewer returns:** per-finding verdicts (ADDRESSED / NOT ADDRESSED),
new breakage in the fix diff, out-of-scope observations, and a round verdict.
diff --git a/skills/subagent-driven-development/references/final-review.md b/skills/subagent-driven-development/references/final-review.md
index 851a5c5..cf03546 100644
--- a/skills/subagent-driven-development/references/final-review.md
+++ b/skills/subagent-driven-development/references/final-review.md
@@ -4,7 +4,8 @@ Part of superpowers:subagent-driven-development. Every task in the plan is
complete.
The final whole-branch review gets a package too: run
-`bash scripts/review-package PLAN_FILE MERGE_BASE HEAD` (MERGE_BASE = the commit the
+`bash scripts/review-package PLAN_FILE MERGE_BASE HEAD` by its absolute path,
+from the working tree you're executing in (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
@@ -19,7 +20,8 @@ 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
-(`bash scripts/review-package PLAN_FILE FIX_BASE HEAD` over the fix range,
+(`bash scripts/review-package PLAN_FILE FIX_BASE HEAD` by its absolute path,
+from the working tree you're executing in, over the fix range,
[re-review-prompt.md](../re-review-prompt.md)).
Adjudicate any residual findings as in the fix loop's breaker
(references/fix-loop.md): park with rulings, or rule on the load-bearing
diff --git a/skills/subagent-driven-development/references/fix-loop.md b/skills/subagent-driven-development/references/fix-loop.md
index 0b476e9..34e4a48 100644
--- a/skills/subagent-driven-development/references/fix-loop.md
+++ b/skills/subagent-driven-development/references/fix-loop.md
@@ -42,7 +42,7 @@ covering test files in the fix message — a one-line fix does not need the
whole suite.
**The re-review is scoped.** Run `bash scripts/review-package PLAN_FILE FIX_BASE HEAD`
-where FIX_BASE is the head the previous review saw, and dispatch
+by its absolute path, from the working tree you're executing in, 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 --git a/skills/subagent-driven-development/scripts/review-package b/skills/subagent-driven-development/scripts/review-package
index fa7625f..04c2b91 100755
--- a/skills/subagent-driven-development/scripts/review-package
+++ b/skills/subagent-driven-development/scripts/review-package
@@ -4,13 +4,22 @@
# call. Using the recorded per-task BASE (not HEAD~1) keeps multi-commit
# tasks intact.
#
-# Usage: review-package PLAN_FILE BASE HEAD [OUTFILE]
+# Usage: review-package [-C DIR] 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).
+# The repository is the one sdd-repo names; -C DIR runs as if started in DIR,
+# as in sdd-workspace.
set -euo pipefail
+here=$(cd "$(dirname "$0")" && pwd)
+if [ "${1:-}" = "-C" ]; then
+ [ -d "${2:-}" ] || { echo "bad -C directory: ${2:-}" >&2; exit 2; }
+ cd "$2"
+ shift 2
+fi
+
if [ $# -lt 3 ] || [ $# -gt 4 ]; then
- echo "usage: review-package PLAN_FILE BASE HEAD [OUTFILE]" >&2
+ echo "usage: review-package [-C DIR] PLAN_FILE BASE HEAD [OUTFILE]" >&2
exit 2
fi
@@ -19,35 +28,37 @@ 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; }
+# Invoke via bash rather than direct exec: some extractors (Python zipfile)
+# strip Unix exec bits when unpacking marketplace packages (#2040).
+repo=$("${BASH:-bash}" "$here/sdd-repo" --with-commit)
+
+git -C "$repo" rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
+git -C "$repo" rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&2; exit 2; }
# Range guards (exit 3): a wrong-branch HEAD yields a range that is empty or
# not rooted at BASE; either would silently produce a bogus review package.
-git merge-base --is-ancestor "$base" "$head" || { echo "HEAD is not a descendant of BASE: ${base}..${head}" >&2; exit 3; }
-[ "$(git rev-list --count "${base}..${head}")" -gt 0 ] || { echo "empty commit range: ${base}..${head}" >&2; exit 3; }
+git -C "$repo" merge-base --is-ancestor "$base" "$head" || { echo "HEAD is not a descendant of BASE: ${base}..${head}" >&2; exit 3; }
+[ "$(git -C "$repo" rev-list --count "${base}..${head}")" -gt 0 ] || { echo "empty commit range: ${base}..${head}" >&2; exit 3; }
if [ $# -eq 4 ]; then
out=$4
else
- # Invoke via bash rather than direct exec: some extractors (Python zipfile)
- # strip Unix exec bits when unpacking marketplace packages (#2040).
- dir=$("${BASH:-bash}" "$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
- out="$dir/review-$(git rev-parse --short "$base")..$(git rev-parse --short "$head").diff"
+ dir=$("${BASH:-bash}" "$here/sdd-workspace" "$plan")
+ out="$dir/review-$(git -C "$repo" rev-parse --short "$base")..$(git -C "$repo" rev-parse --short "$head").diff"
fi
{
echo "# Review package: ${base}..${head}"
echo
echo "## Commits"
- git log --oneline "${base}..${head}"
+ git -C "$repo" log --oneline "${base}..${head}"
echo
echo "## Files changed"
- git diff --stat "${base}..${head}"
+ git -C "$repo" diff --stat "${base}..${head}"
echo
echo "## Diff"
- git diff -U10 "${base}..${head}"
+ git -C "$repo" diff -U10 "${base}..${head}"
} > "$out"
-commits=$(git rev-list --count "${base}..${head}")
+commits=$(git -C "$repo" rev-list --count "${base}..${head}")
echo "wrote ${out}: ${commits} commit(s), $(wc -c < "$out" | tr -d ' ') bytes"
diff --git a/skills/subagent-driven-development/scripts/sdd-repo b/skills/subagent-driven-development/scripts/sdd-repo
new file mode 100755
index 0000000..b1756b9
--- /dev/null
+++ b/skills/subagent-driven-development/scripts/sdd-repo
@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Print the top-level directory of the git working tree the SDD scripts use:
+# the current directory's, exactly as git itself picks one. A caller that
+# means a different working tree says so with the scripts' -C DIR, which
+# they apply (cd) before calling this.
+#
+# The plan file's location never picks the repository. An executor working
+# in a linked worktree commonly holds an absolute path to the plan in the
+# main checkout (writing-plans leaves the plan uncommitted there), and its
+# workspace and commits belong to the worktree it is working in. And a
+# caller standing outside any repository, such as the skill's own directory
+# in an installed plugin, is in the wrong place: guessing a repository from
+# the plan would silently act on whichever checkout the path points into.
+#
+# Outside any working tree, stop. --with-commit also stops on a repository
+# with no commit yet, for callers that need HEAD as a BASE or a review
+# range. The message covers both ways to get here: running from the wrong
+# directory (where 'git init' would be the wrong fix) and a new project
+# that has no repository or commit yet.
+#
+# Single source of truth for which repository the SDD and executing-plans
+# scripts work in, so no two of them can disagree.
+#
+# Usage: sdd-repo [--with-commit]
+set -euo pipefail
+
+with_commit=false
+if [ "${1:-}" = "--with-commit" ]; then
+ with_commit=true
+ shift
+fi
+
+if [ $# -ne 0 ]; then
+ echo "usage: sdd-repo [--with-commit]" >&2
+ exit 2
+fi
+
+if root=$(git rev-parse --show-toplevel 2>/dev/null); then
+ if [ "$with_commit" = false ] || git -C "$root" rev-parse --verify --quiet HEAD >/dev/null; then
+ printf '%s\n' "$root"
+ exit 0
+ fi
+ said=$(git -C "$root" rev-parse --verify HEAD 2>&1 >/dev/null) || true
+else
+ said=$(git rev-parse --show-toplevel 2>&1 >/dev/null) || true
+fi
+
+# git's own first line always follows the shared message: where git refuses
+# a working tree the caller is inside (dubious ownership, git missing from
+# PATH, the cwd inside .git), the shared message alone would be wrong, and
+# git's line names the real fix.
+echo "SDD scripts must run from inside the git working tree you're executing in, with at least one commit (current directory: $PWD). If this is a new project, run 'git init' and make a first commit, then rerun." >&2
+echo "git said: ${said%%$'\n'*}" >&2
+exit 2
diff --git a/skills/subagent-driven-development/scripts/sdd-workspace b/skills/subagent-driven-development/scripts/sdd-workspace
index b4661eb..ca3ac3b 100755
--- a/skills/subagent-driven-development/scripts/sdd-workspace
+++ b/skills/subagent-driven-development/scripts/sdd-workspace
@@ -27,11 +27,23 @@
# Single source of truth for the workspace location, so task-brief and
# review-package cannot drift to different directories.
#
-# Usage: sdd-workspace PLAN_FILE
+# The repository is the current directory's (see sdd-repo). -C DIR runs as
+# if started in DIR, the way git -C does: a caller working on another
+# checkout or worktree needs no `cd DIR ;` prefix, a compound that harnesses
+# cannot allowlist because DIR differs on every run (#1799).
+#
+# Usage: sdd-workspace [-C DIR] PLAN_FILE
set -euo pipefail
+here=$(cd "$(dirname "$0")" && pwd)
+if [ "${1:-}" = "-C" ]; then
+ [ -d "${2:-}" ] || { echo "bad -C directory: ${2:-}" >&2; exit 2; }
+ cd "$2"
+ shift 2
+fi
+
if [ $# -ne 1 ]; then
- echo "usage: sdd-workspace PLAN_FILE" >&2
+ echo "usage: sdd-workspace [-C DIR] PLAN_FILE" >&2
exit 2
fi
@@ -44,8 +56,12 @@ slug=$(basename "$plan" .md)
# Physical path, spelled the way pwd -P spells the plan path below: on Git
# Bash, rev-parse prints C:/Users/... while pwd prints /c/Users/..., and the
-# repo-relative marker check needs both in the same form.
-root=$(CDPATH='' cd -- "$(git rev-parse --show-toplevel)" && pwd -P)
+# repo-relative marker check needs both in the same form. Two steps, so a
+# failing sdd-repo stops the script instead of handing cd an empty path.
+# Invoke via bash rather than direct exec: some extractors (Python zipfile)
+# strip Unix exec bits when unpacking marketplace packages (#2040).
+toplevel=$("${BASH:-bash}" "$here/sdd-repo")
+root=$(CDPATH='' cd -- "$toplevel" && pwd -P)
base="$root/.superpowers/sdd"
# Normalize the plan path (physical directory, so relative/absolute/../
@@ -84,4 +100,11 @@ fi
# Create-only: a repo may commit its own .gitignore here (e.g. to version
# progress.md ledgers); overwriting it would revert that on every run.
[ -e "$base/.gitignore" ] || printf '*\n' > "$base/.gitignore"
-CDPATH='' cd -- "$dir" && pwd
+
+# On Windows (Git Bash, MSYS2, Cygwin) print C:/Users/... rather than
+# /c/Users/... or /tmp/...: the caller may be PowerShell or another native
+# tool, which can't resolve MSYS paths, and bash accepts this form too.
+# Only the printed path changes; the plan-path markers above keep pwd -P's
+# spelling, so existing workspaces still match their plans.
+CDPATH='' cd -- "$dir"
+if command -v cygpath >/dev/null 2>&1; then cygpath -m "$PWD"; else pwd; fi
diff --git a/skills/subagent-driven-development/scripts/task-brief b/skills/subagent-driven-development/scripts/task-brief
index b49fc54..a490211 100755
--- a/skills/subagent-driven-development/scripts/task-brief
+++ b/skills/subagent-driven-development/scripts/task-brief
@@ -3,14 +3,21 @@
# implementer reads in one call, so the task text never has to be pasted
# through the controller's context.
#
-# Usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE]
+# Usage: task-brief [-C DIR] PLAN_FILE TASK_NUMBER [OUTFILE]
# 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).
+# working tree share it). -C DIR runs as if started in DIR, as in sdd-workspace.
set -euo pipefail
+here=$(cd "$(dirname "$0")" && pwd)
+if [ "${1:-}" = "-C" ]; then
+ [ -d "${2:-}" ] || { echo "bad -C directory: ${2:-}" >&2; exit 2; }
+ cd "$2"
+ shift 2
+fi
+
if [ $# -lt 2 ] || [ $# -gt 3 ]; then
- echo "usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE]" >&2
+ echo "usage: task-brief [-C DIR] PLAN_FILE TASK_NUMBER [OUTFILE]" >&2
exit 2
fi
@@ -23,17 +30,75 @@ if [ $# -eq 3 ]; then
else
# Invoke via bash rather than direct exec: some extractors (Python zipfile)
# strip Unix exec bits when unpacking marketplace packages (#2040).
- dir=$("${BASH:-bash}" "$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
+ dir=$("${BASH:-bash}" "$here/sdd-workspace" "$plan")
out="$dir/task-${n}-brief.md"
fi
-awk -v n="$n" '
- /^```/ { infence = !infence }
- !infence && /^#+[ \t]+Task[ \t]+[0-9]+/ {
- intask = ($0 ~ ("^#+[ \t]+Task[ \t]+" n "([^0-9]|$)"))
+# A task heading is `Task` followed by an ID: letters and digits, optionally
+# dot-separated, containing at least one digit (3, 6b, A1, 2.1). The digit
+# keeps headings like "## Task Overview" or "#### Task notes" from becoming
+# task boundaries. The ID is compared to TASK_NUMBER as a whole string, so
+# Task 6 never matches Task 6b, Task 1 never matches Task 1.1, and
+# TASK_NUMBER never reaches awk as a regex (#2459). A deeper Task heading
+# whose ID extends the requested one with a letter or dot is a sub-task and
+# stays in its brief (### Task 7 keeps #### Task 7a), as it always has.
+# Depth alone is not enough: plans drift from "## Task 1" to "### Task 2".
+#
+# The word stays the English literal "Task", whatever language the rest of
+# the plan is in. A plan with no Task headings at all usually translated it
+# ("## Tarea 1"), so list the headings shaped like tasks before the
+# not-found error instead of implying the plan has no task 1 (#2496).
+#
+# A fence that never closes hides every Task heading after it (#2436). When
+# it hides one while the requested task is being captured, that task's end
+# can't be found and the brief would run on through every later task: refuse
+# (exit 4) rather than hand an implementer several tasks as its requirements.
+# When it hides the requested heading itself, say so before the not-found
+# error. A stray fence that hides no Task heading (real plans end with a lone
+# ``` line) leaves the brief complete, so brief it with a warning.
+# The plan path goes through ENVIRON, not -v, which would mangle the
+# backslashes of a Windows path.
+rc=0
+TASK_BRIEF_PLAN="$plan" awk -v n="$n" '
+ /^```/ { infence = !infence; if (infence) { fence_line = NR; hidden = 0 } }
+ infence && /^#+[ \t]+Task[ \t]/ { hidden = 1 }
+ !infence && /^#+[ \t]+Task[ \t]/ {
+ id = $0
+ sub(/^#+[ \t]+Task[ \t]+/, "", id)
+ if (match(id, /^[A-Za-z0-9]+(\.[A-Za-z0-9]+)*/) && substr(id, 1, RLENGTH) ~ /[0-9]/) {
+ tasks++
+ id = substr(id, 1, RLENGTH)
+ match($0, /^#+/)
+ subtask = intask && RLENGTH > level && substr(id, 1, length(n)) == n \
+ && substr(id, length(n) + 1, 1) ~ /[A-Za-z.]/
+ if (!subtask) {
+ intask = (id == n)
+ level = RLENGTH
+ }
+ }
+ }
+ !infence && /^#+[ \t]+[^ \t]+[ \t]+[A-Za-z0-9.]*[0-9]/ && shaped < 5 { shaped_heading[++shaped] = $0 }
+ intask { print; found = 1 }
+ END {
+ where = "the code fence opened at line " fence_line " of " ENVIRON["TASK_BRIEF_PLAN"] " never closes"
+ if (infence && hidden && (intask || !found)) {
+ print "task-brief: " where ", so no Task heading after it can be seen; close that fence in the plan and rerun" | "cat >&2"
+ if (intask) exit 4
+ } else if (infence && intask) {
+ print "task-brief: warning: " where "; it hides no Task heading, so this brief is complete" | "cat >&2"
+ }
+ # An open fence that hid Task headings already explains why none were
+ # seen; the English-word hint would contradict it.
+ if (!tasks && shaped && !(infence && hidden)) {
+ print "task-brief: no task headings found. Task headings must use the English word \"Task\" (\"### Task 1: ...\"), even when the rest of the plan is in another language. Headings shaped like tasks:" | "cat >&2"
+ for (i = 1; i <= shaped; i++) print " " shaped_heading[i] | "cat >&2"
+ }
}
- intask { print }
-' "$plan" > "$out"
+' "$plan" > "$out" || rc=$?
+if [ "$rc" -ne 0 ]; then
+ if [ -f "$out" ]; then rm -f "$out"; fi
+ exit "$rc"
+fi
if [ ! -s "$out" ]; then
echo "task ${n} not found in ${plan} (no heading matching 'Task ${n}')" >&2
diff --git a/skills/subagent-driven-development/task-reviewer-prompt.md b/skills/subagent-driven-development/task-reviewer-prompt.md
index 5c619bc..4cf7860 100644
--- a/skills/subagent-driven-development/task-reviewer-prompt.md
+++ b/skills/subagent-driven-development/task-reviewer-prompt.md
@@ -189,7 +189,8 @@ Subagent (general-purpose):
**Placeholders:**
- `[MODEL]` — REQUIRED: reviewer model per SKILL.md Model Selection
-- `[BRIEF_FILE]` — REQUIRED: the task brief file (`bash scripts/task-brief PLAN N`
+- `[BRIEF_FILE]` — REQUIRED: the task brief file (`bash scripts/task-brief PLAN N`,
+ run by its absolute path, from the working tree you're executing in,
prints the path; same file the implementer worked from)
- `[GLOBAL_CONSTRAINTS]` — the binding requirements copied verbatim from
the plan's Global Constraints section or the spec: exact values, formats,
@@ -200,7 +201,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 (`bash scripts/review-package PLAN_FILE BASE HEAD` prints the unique
+ package to (`bash scripts/review-package PLAN_FILE BASE HEAD`, run by its
+ absolute path, from the working tree you're executing in, prints the unique
path it wrote; the package never enters the controller's context)
**Reviewer returns:** Spec Compliance verdict (✅/❌/⚠️), Strengths, Issues
diff --git a/tests/brainstorm-server/server.test.js b/tests/brainstorm-server/server.test.js
index a2bfeda..de3b56b 100644
--- a/tests/brainstorm-server/server.test.js
+++ b/tests/brainstorm-server/server.test.js
@@ -150,6 +150,17 @@ async function runTests() {
'Server should process the barrier file');
}
+ // The server logs a screen on stdout and broadcasts its reload in the same
+ // tick, but the two reach this process on separate channels, so stdout can
+ // win. The server answers a ping on the same socket after the reload, so
+ // once the pong arrives, every reload sent before it has arrived too.
+ function drainSocket(ws) {
+ let ponged = false;
+ ws.once('pong', () => { ponged = true; });
+ ws.ping();
+ return waitFor(() => ponged, 'Server should answer the ping');
+ }
+
let initialStdout = '';
let passed = 0;
let failed = 0;
@@ -535,6 +546,7 @@ async function runTests() {
fs.writeFileSync(path.join(CONTENT_DIR, 'data.txt'), 'not html');
await settleWatcher();
+ await drainSocket(ws);
// The only reload is the one for settleWatcher's own file.
assert.strictEqual(reloads, 1, 'Should NOT reload for non-HTML files');
@@ -553,6 +565,7 @@ async function runTests() {
fs.writeFileSync(path.join(CONTENT_DIR, '._sidecar.html'), 'resource fork');
await settleWatcher();
+ await drainSocket(ws);
// The only reload is the one for settleWatcher's own file.
assert.strictEqual(reloads, 1, 'a ._ dotfile appearing must not trigger a reload');
diff --git a/tests/brainstorm-server/start-server.test.sh b/tests/brainstorm-server/start-server.test.sh
index a4802da..37fb216 100644
--- a/tests/brainstorm-server/start-server.test.sh
+++ b/tests/brainstorm-server/start-server.test.sh
@@ -109,6 +109,52 @@ else
fi
echo ""
+echo "--- start-server.sh relative --project-dir ---"
+
+cat > "$TEST_DIR/fake-bin/node" <<'EOF'
+#!/usr/bin/env bash
+echo "CAPTURED_BRAINSTORM_DIR=${BRAINSTORM_DIR:-__UNSET__}"
+exit 0
+EOF
+chmod +x "$TEST_DIR/fake-bin/node"
+
+# The script cds into its own directory before starting the server, so a
+# relative --project-dir must be resolved against the caller's cwd first.
+# Covers an existing dir and a not-yet-created one, both with spaces.
+for relative_dir in "." "new project dir"; do
+ caller_dir="$TEST_DIR/caller with space"
+ rm -rf "$caller_dir"
+ mkdir -p "$caller_dir"
+ expected_root="$(cd "$caller_dir" && pwd)"
+ if [[ "$relative_dir" != "." ]]; then
+ expected_root="$expected_root/$relative_dir"
+ fi
+
+ captured=$(
+ cd "$caller_dir" &&
+ PATH="$TEST_DIR/fake-bin:$PATH" \
+ MSYSTEM="" \
+ bash "$START_SCRIPT" --project-dir "$relative_dir" --foreground 2>&1 || true
+ )
+ brainstorm_dir=$(echo "$captured" | grep "CAPTURED_BRAINSTORM_DIR=" | head -1 | sed 's/CAPTURED_BRAINSTORM_DIR=//')
+
+ case "$brainstorm_dir" in
+ "$expected_root/.superpowers/brainstorm/"*)
+ pass "--project-dir '$relative_dir' gives the server an absolute session dir under the caller's cwd" ;;
+ *)
+ fail "--project-dir '$relative_dir' gives the server an absolute session dir under the caller's cwd" \
+ "expected prefix '$expected_root/.superpowers/brainstorm/', got: $captured" ;;
+ esac
+
+ if [[ -n "$brainstorm_dir" && -f "$brainstorm_dir/state/server.pid" ]]; then
+ pass "--project-dir '$relative_dir' writes server.pid into the project session dir"
+ else
+ fail "--project-dir '$relative_dir' writes server.pid into the project session dir" \
+ "no server.pid under '$brainstorm_dir/state', output: $captured"
+ fi
+done
+
+echo ""
echo "--- Results: $passed passed, $failed failed ---"
if [[ $failed -gt 0 ]]; then
exit 1
diff --git a/tests/claude-code/test-executing-plans-scripts.sh b/tests/claude-code/test-executing-plans-scripts.sh
index e4e3904..8ad9e81 100755
--- a/tests/claude-code/test-executing-plans-scripts.sh
+++ b/tests/claude-code/test-executing-plans-scripts.sh
@@ -33,8 +33,9 @@ main() {
git init -q -b main "$TEST_ROOT/repo"
local repo
repo="$(cd "$TEST_ROOT/repo" && git rev-parse --show-toplevel)"
- # Same spelling as the scripts print (pwd), not rev-parse's C:/... on Git Bash.
- repo="$(cd "$repo" && pwd)"
+ # Same spelling as the scripts print: C:/... from cygpath -m on Windows,
+ # plain pwd elsewhere.
+ repo="$(cd "$repo" && if command -v cygpath >/dev/null 2>&1; then cygpath -m "$PWD"; else pwd; fi)"
local git_id=(-c user.email=t@example.com -c user.name=t -c commit.gpgsign=false)
cat > "$repo/plan.md" <<'PLAN'
@@ -154,6 +155,77 @@ PLAN
echo " ledger:"; sed 's/^/ /' "$ledger" 2>/dev/null || echo " (missing)"
fi
+ # --- no usable repository: every helper stops with one message (#2242, #2429) ---
+ # The same message for a new project and for a caller standing in the
+ # wrong directory (such as the plugin's skill directory, where git init
+ # is the wrong fix), so "init and commit" is only the new-project case.
+ git init -q -b main "$TEST_ROOT/unborn"
+ cp "$repo/plan.md" "$TEST_ROOT/unborn/plan.md"
+ mkdir -p "$TEST_ROOT/no-repo"
+ cp "$repo/plan.md" "$TEST_ROOT/no-repo/plan.md"
+ # git's own first error line follows the shared message, so the reason
+ # git refused is never hidden.
+ local where msg said
+ for where in unborn no-repo; do
+ msg="SDD scripts must run from inside the git working tree you're executing in, with at least one commit (current directory: $TEST_ROOT/$where). If this is a new project, run 'git init' and make a first commit, then rerun."
+ said="git said: fatal: "
+ [[ "$where" == no-repo ]] && said="git said: fatal: not a git repository"
+ rc=0
+ out="$(cd "$TEST_ROOT/$where" && "$EP_SCRIPTS/task-start" plan.md 1 2>&1)" || rc=$?
+ if [[ "$rc" -eq 2 && "$out" == "$msg"$'\n'"$said"* ]]; then
+ pass "task-start in a $where directory exits 2 with the shared message"
+ else
+ fail "task-start in a $where directory exits 2 with the shared message"
+ echo " exit: $rc"
+ echo " got: $out"
+ fi
+ rc=0
+ out="$(cd "$TEST_ROOT/$where" && "$EP_SCRIPTS/task-done" plan.md 1 HEAD -- true 2>&1)" || rc=$?
+ if [[ "$rc" -eq 2 && "$out" == "$msg"$'\n'"$said"* ]]; then
+ pass "task-done in a $where directory exits 2 with the shared message"
+ else
+ fail "task-done in a $where directory exits 2 with the shared message"
+ echo " exit: $rc"
+ echo " got: $out"
+ fi
+ done
+ if [[ ! -e "$TEST_ROOT/unborn/.superpowers" && ! -e "$TEST_ROOT/no-repo/.superpowers" ]]; then
+ pass "nothing is written without a usable repository"
+ else
+ fail "nothing is written without a usable repository"
+ fi
+
+ # --- outside any repository, a plan in a repository is not a fallback (#2429) ---
+ # Like git, the scripts act on the current directory's working tree; an
+ # absolute plan path into some repository does not pick that one instead.
+ msg="SDD scripts must run from inside the git working tree you're executing in, with at least one commit (current directory: $TEST_ROOT/no-repo). If this is a new project, run 'git init' and make a first commit, then rerun."
+ local before head_now
+ head_now="$(cd "$repo" && git rev-parse HEAD)"
+ before="$(find "$repo/.superpowers" | sort; cat "$repo/.superpowers/sdd/plan/progress.md")"
+ rc=0
+ out="$(cd "$TEST_ROOT/no-repo" && "$EP_SCRIPTS/task-start" "$repo/plan.md" 2 2>&1)" || rc=$?
+ if [[ "$rc" -eq 2 && "$out" == "$msg"$'\n'"git said: fatal: not a git repository"* ]]; then
+ pass "task-start outside any repository stops with the shared message despite a plan in a repository"
+ else
+ fail "task-start outside any repository stops with the shared message despite a plan in a repository"
+ echo " exit: $rc"
+ echo " got: $out"
+ fi
+ rc=0
+ out="$(cd "$TEST_ROOT/no-repo" && "$EP_SCRIPTS/task-done" "$repo/plan.md" 2 "$head_now" -- true 2>&1)" || rc=$?
+ if [[ "$rc" -eq 2 && "$out" == "$msg"$'\n'"git said: fatal: not a git repository"* ]]; then
+ pass "task-done outside any repository stops with the shared message despite a plan in a repository"
+ else
+ fail "task-done outside any repository stops with the shared message despite a plan in a repository"
+ echo " exit: $rc"
+ echo " got: $out"
+ fi
+ if [[ "$(find "$repo/.superpowers" | sort; cat "$repo/.superpowers/sdd/plan/progress.md")" == "$before" && ! -e "$TEST_ROOT/no-repo/.superpowers" ]]; then
+ pass "outside any repository, task-start and task-done write nothing to the plan's repository"
+ else
+ fail "outside any repository, task-start and task-done write nothing to the plan's repository"
+ fi
+
echo
if [[ "$FAILURES" -eq 0 ]]; then
echo "PASS"
diff --git a/tests/claude-code/test-sdd-workspace.sh b/tests/claude-code/test-sdd-workspace.sh
index 16cf50d..bbf0fca 100755
--- a/tests/claude-code/test-sdd-workspace.sh
+++ b/tests/claude-code/test-sdd-workspace.sh
@@ -17,15 +17,24 @@ fail() {
FAILURES=$((FAILURES + 1))
}
-# Push a path through the same `cd ... && pwd` normalization that
-# sdd-workspace's own printed output goes through, so both sides of a
-# string comparison are guaranteed to be spelled identically. On Windows
-# Git Bash/MSYS, `git rev-parse --show-toplevel` (Windows-style,
-# C:/Users/...) and `cd ... && pwd` (MSYS-style, /c/Users/...) can print
-# different spellings of the identical physical directory; on Linux/macOS
-# this is a no-op since the two already agree (module the resolved-symlink
-# /var -> /private/var case handled by the mktemp comment above).
-physical_path() { (cd "$1" && pwd); }
+# Push a path through the same normalization that sdd-workspace's own
+# printed output goes through, so both sides of a string comparison are
+# guaranteed to be spelled identically. On Windows (Git Bash/MSYS, Cygwin)
+# that is the drive-letter form `cygpath -m` prints (C:/Users/...), not the
+# MSYS form `pwd` prints (/c/Users/...); on Linux/macOS it is plain `pwd`
+# (modulo the resolved-symlink /var -> /private/var case handled by the
+# mktemp comment below).
+physical_path() {
+ (cd "$1" && if command -v cygpath >/dev/null 2>&1; then cygpath -m "$PWD"; else pwd; fi)
+}
+
+# On Windows, check that PowerShell (the shell an agent's PowerShell tool
+# runs) can open a path the helpers printed. Elsewhere there is nothing to
+# check: the printed path is the shell's own.
+native_readable() {
+ command -v cygpath >/dev/null 2>&1 && command -v powershell.exe >/dev/null 2>&1 || return 0
+ [[ "$(powershell.exe -NoProfile -Command "Test-Path -LiteralPath '$1'" | tr -d '\r')" == "True" ]]
+}
cleanup() {
if [[ -n "$TEST_ROOT" && -d "$TEST_ROOT" ]]; then
@@ -93,6 +102,13 @@ PLAN
echo " got: $dir_a"
fi
+ if native_readable "$dir_a"; then
+ pass "the printed workspace path opens from PowerShell on Windows"
+ else
+ fail "the printed workspace path opens from PowerShell on Windows"
+ 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
@@ -139,6 +155,270 @@ PLAN
fail "task-brief writes its brief under the plan's workspace"
echo " got: $brief_path"
fi
+ if native_readable "$brief_path"; then
+ pass "the printed brief path opens from PowerShell on Windows"
+ else
+ fail "the printed brief path opens from PowerShell on Windows"
+ echo " got: $brief_path"
+ fi
+
+ # --- Task IDs: alphanumeric (#2459), matched whole, never as a prefix ---
+ cat > "$repo/plan-ids.md" <<'PLAN'
+# Lanes Plan
+
+## Task Overview
+
+Shared context; not a task.
+
+### Task A1: First lane
+
+BODY-A1
+
+#### Task notes
+
+Still part of A1.
+
+### Task A10: Same lane, later
+
+BODY-A10
+
+### Task 6: Numbered
+
+BODY-6
+
+### Task 6b: Sub-task
+
+BODY-6B
+
+### Task 2.1: Dotted
+
+BODY-2.1
+
+### Task 201: Decoy
+
+BODY-201
+PLAN
+ local id want got id_out="$TEST_ROOT/id-brief.md"
+ for id in A1 A10 6 6b 2.1 201; do
+ want="BODY-$(printf '%s' "$id" | tr '[:lower:]' '[:upper:]')"
+ rc=0
+ (cd "$repo" && "$SDD_SCRIPTS/task-brief" plan-ids.md "$id" "$id_out" >/dev/null 2>&1) || rc=$?
+ got="$(grep '^BODY-' "$id_out" 2>/dev/null | tr '\n' ' ')" || true
+ if [[ "$rc" -eq 0 && "$got" == "$want " ]]; then
+ pass "task-brief extracts Task $id and nothing else"
+ else
+ fail "task-brief extracts Task $id and nothing else"
+ echo " exit: $rc, bodies: $got"
+ fi
+ : > "$id_out"
+ done
+ (cd "$repo" && "$SDD_SCRIPTS/task-brief" plan-ids.md A1 "$id_out" >/dev/null 2>&1) || true
+ if grep -q 'Still part of A1.' "$id_out"; then
+ pass "a Task heading with no digit in its ID is not a task boundary"
+ else
+ fail "a Task heading with no digit in its ID is not a task boundary"
+ echo " brief: $(cat "$id_out" 2>/dev/null)"
+ fi
+ # A deeper heading whose ID extends the task's (7 -> 7a) is a sub-task and
+ # stays in the parent's brief; a deeper heading for another task (a plan
+ # that drifts from ## Task 9 to ### Task 10) is still a boundary.
+ cat > "$repo/plan-nested.md" <<'PLAN'
+### Task 7: Parent
+
+BODY-7
+
+#### Task 7a: First part
+
+BODY-7A
+
+#### Task 7b: Second part
+
+BODY-7B
+
+### Task 8: Next
+
+BODY-8
+
+## Task 9: Shallower heading
+
+BODY-9
+
+### Task 10: Deeper, but not a sub-task
+
+BODY-10
+PLAN
+ for id in 7 7a 7b 8 9 10; do
+ case "$id" in
+ 7) want="BODY-7 BODY-7A BODY-7B " ;;
+ *) want="BODY-$(printf '%s' "$id" | tr '[:lower:]' '[:upper:]') " ;;
+ esac
+ rc=0
+ (cd "$repo" && "$SDD_SCRIPTS/task-brief" plan-nested.md "$id" "$id_out" >/dev/null 2>&1) || rc=$?
+ got="$(grep '^BODY-' "$id_out" 2>/dev/null | tr '\n' ' ')" || true
+ if [[ "$rc" -eq 0 && "$got" == "$want" ]]; then
+ pass "nested plan: Task $id brief holds exactly its own section"
+ else
+ fail "nested plan: Task $id brief holds exactly its own section"
+ echo " exit: $rc, bodies: $got (want: $want)"
+ fi
+ done
+
+ for id in 2 '2|6' '6(' Overview; do
+ rc=0
+ (cd "$repo" && "$SDD_SCRIPTS/task-brief" plan-ids.md "$id" "$id_out" >/dev/null 2>&1) || rc=$?
+ if [[ "$rc" -eq 3 ]]; then
+ pass "task-brief '$id' matches no task (exit 3)"
+ else
+ fail "task-brief '$id' matches no task (exit 3)"
+ echo " exit: $rc, brief: $(cat "$id_out" 2>/dev/null)"
+ fi
+ done
+
+ # --- Translated task headings: say so instead of "not found" (#2496) ---
+ cat > "$repo/plan-es.md" <<'PLAN'
+# Plan: demo
+
+## Tarea 1: Banner
+
+**Archivos:**
+
+## Tarea 2: Segunda
+PLAN
+ local es_err
+ rc=0
+ es_err="$(cd "$repo" && "$SDD_SCRIPTS/task-brief" plan-es.md 1 "$id_out" 2>&1 >/dev/null)" || rc=$?
+ if [[ "$rc" -eq 3 && "$es_err" == *'English word "Task"'* \
+ && "$es_err" == *"## Tarea 1: Banner"* && "$es_err" == *"## Tarea 2: Segunda"* ]]; then
+ pass "task-brief on a plan with no Task headings names the headings it saw"
+ else
+ fail "task-brief on a plan with no Task headings names the headings it saw"
+ echo " exit: $rc"
+ echo " stderr: $es_err"
+ fi
+
+ # A plan that has Task headings, just not this one, gets the plain error.
+ rc=0
+ es_err="$(cd "$repo" && "$SDD_SCRIPTS/task-brief" plan-ids.md 99 "$id_out" 2>&1 >/dev/null)" || rc=$?
+ if [[ "$rc" -eq 3 && "$es_err" == "task 99 not found in plan-ids.md (no heading matching 'Task 99')" ]]; then
+ pass "a missing task in a plan with Task headings gets only the not-found line"
+ else
+ fail "a missing task in a plan with Task headings gets only the not-found line"
+ echo " exit: $rc"
+ echo " stderr: $es_err"
+ fi
+
+ # --- An unclosed fence hides every later Task heading (#2436) ---
+ cat > "$repo/plan-unclosed.md" <<'PLAN'
+# Example Plan
+
+### Task 1: First task
+
+```typescript
+const x = 1
+```
+
+```typescript
+const y = 2
+
+### Task 2: Second task
+
+TASK-2-MARKER
+
+### Task 3: Third task
+
+TASK-3-MARKER
+PLAN
+ local fence_out="$TEST_ROOT/unclosed-brief.md" fence_err
+ rc=0
+ fence_err="$(cd "$repo" && "$SDD_SCRIPTS/task-brief" plan-unclosed.md 1 "$fence_out" 2>&1 >/dev/null)" || rc=$?
+ if [[ "$rc" -eq 4 && ! -e "$fence_out" && "$fence_err" == *"line 9"*"never closes"* ]]; then
+ pass "task-brief refuses a brief that an unclosed fence would run to EOF (exit 4, names the line)"
+ else
+ fail "task-brief refuses a brief that an unclosed fence would run to EOF (exit 4, names the line)"
+ echo " exit: $rc"
+ echo " stderr: $fence_err"
+ echo " brief: $(cat "$fence_out" 2>/dev/null)"
+ fi
+
+ rc=0
+ fence_err="$(cd "$repo" && "$SDD_SCRIPTS/task-brief" plan-unclosed.md 2 "$fence_out" 2>&1 >/dev/null)" || rc=$?
+ if [[ "$rc" -eq 3 && "$fence_err" == *"never closes"* ]]; then
+ pass "task-brief names the unclosed fence when it hides the requested heading"
+ else
+ fail "task-brief names the unclosed fence when it hides the requested heading"
+ echo " exit: $rc"
+ echo " stderr: $fence_err"
+ fi
+
+ # An unclosed fence in a later task does not touch an earlier task's brief.
+ sed 's/^### Task 1: First task$/### Task 0: Before/' "$repo/plan-unclosed.md" \
+ | sed '1a\
+\
+### Task 1: Clean\
+\
+CLEAN-MARKER' > "$repo/plan-unclosed-later.md"
+ rc=0
+ fence_err="$(cd "$repo" && "$SDD_SCRIPTS/task-brief" plan-unclosed-later.md 1 "$fence_out" 2>&1 >/dev/null)" || rc=$?
+ if [[ "$rc" -eq 0 && -z "$fence_err" ]] && grep -q CLEAN-MARKER "$fence_out" && ! grep -q 'Task 0' "$fence_out"; then
+ pass "an unclosed fence in a later task leaves an earlier task's brief alone"
+ else
+ fail "an unclosed fence in a later task leaves an earlier task's brief alone"
+ echo " exit: $rc"
+ echo " stderr: $fence_err"
+ echo " brief: $(cat "$fence_out" 2>/dev/null)"
+ fi
+
+ # A stray fence that hides no Task heading (seen in real plans as a lone
+ # ``` on the last line) leaves the brief complete: brief it, and warn.
+ cat > "$repo/plan-stray-fence.md" <<'PLAN'
+### Task 1: First
+
+BODY-1
+
+### Task 2: Last
+
+BODY-2
+```
+PLAN
+ rc=0
+ fence_err="$(cd "$repo" && "$SDD_SCRIPTS/task-brief" plan-stray-fence.md 2 "$fence_out" 2>&1 >/dev/null)" || rc=$?
+ if [[ "$rc" -eq 0 && "$fence_err" == *"warning"*"line 8"*"never closes"* ]] \
+ && grep -q BODY-2 "$fence_out" && ! grep -q BODY-1 "$fence_out"; then
+ pass "a stray fence that hides no Task heading briefs the task and warns"
+ else
+ fail "a stray fence that hides no Task heading briefs the task and warns"
+ echo " exit: $rc"
+ echo " stderr: $fence_err"
+ echo " brief: $(cat "$fence_out" 2>/dev/null)"
+ fi
+
+ # An unclosed fence that hides only some later prose, but no Task
+ # heading, also leaves the last task's brief complete.
+ printf '### Task 1: Only\n\nBODY-1\n\n```sh\necho hi\n\n## Notes\n\nNOT-A-TASK\n' > "$repo/plan-stray-prose.md"
+ rc=0
+ fence_err="$(cd "$repo" && "$SDD_SCRIPTS/task-brief" plan-stray-prose.md 1 "$fence_out" 2>&1 >/dev/null)" || rc=$?
+ if [[ "$rc" -eq 0 && "$fence_err" == *"warning"* ]] && grep -q BODY-1 "$fence_out"; then
+ pass "an unclosed fence that hides no Task heading does not block the brief"
+ else
+ fail "an unclosed fence that hides no Task heading does not block the brief"
+ echo " exit: $rc"
+ echo " stderr: $fence_err"
+ fi
+
+ # When the open fence hides every Task heading, the fence is the
+ # diagnosis: the plan's English Task headings must not also draw the
+ # "use the English word Task" hint, which would contradict it.
+ printf '## Phase 1: Setup\n\n```sh\necho hi\n\n### Task 1: Hidden\n\nBODY-1\n' > "$repo/plan-fence-hides-all.md"
+ rc=0
+ fence_err="$(cd "$repo" && "$SDD_SCRIPTS/task-brief" plan-fence-hides-all.md 1 "$fence_out" 2>&1 >/dev/null)" || rc=$?
+ if [[ "$rc" -eq 3 && "$fence_err" == *"line 3"*"never closes"* && "$fence_err" == *"task 1 not found"* \
+ && "$fence_err" != *"English word"* ]]; then
+ pass "a fence hiding every Task heading gets the fence message, not the English-word hint"
+ else
+ fail "a fence hiding every Task heading gets the fence message, not the English-word hint"
+ echo " exit: $rc"
+ echo " stderr: $fence_err"
+ 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)
@@ -225,10 +505,177 @@ PLAN
echo " status: $wt_status"
fi
+ # --- Which repository: cwd, then -C, then the plan's (#2429, #1799) ---
+ printf 'wt-only\n' > "$wt/wt-only.txt"
+ ( cd "$wt" && git add wt-only.txt && git "${git_id[@]}" commit -qm wt-change )
+ local wt_base wt_head
+ wt_base="$(cd "$wt" && git rev-parse HEAD~1)"
+ wt_head="$(cd "$wt" && git rev-parse HEAD)"
+
+ # An executor working in the worktree with an absolute path to the main
+ # checkout's plan (writing-plans leaves the plan uncommitted there) keeps
+ # its workspace in the worktree it is working in.
+ printf '# Main only\n\n## Task 1: Main only\n\nMain only.\n' > "$repo/main-only.md"
+ local wt_abs_dir
+ wt_abs_dir="$(cd "$wt" && "$SDD_SCRIPTS/sdd-workspace" "$repo/main-only.md")" || true
+ if [[ "$wt_abs_dir" == "$wt_root/.superpowers/sdd/main-only" ]]; then
+ pass "a plan in another worktree still resolves to the current worktree's workspace"
+ else
+ fail "a plan in another worktree still resolves to the current worktree's workspace"
+ echo " got: $wt_abs_dir"
+ fi
+
+ # -C DIR runs as if started in DIR: workspace and git commands both.
+ local c_dir
+ c_dir="$(cd "$repo" && "$SDD_SCRIPTS/sdd-workspace" -C "$wt" plan-a.md)" || true
+ if [[ "$c_dir" == "$wt_root/.superpowers/sdd/plan-a" ]]; then
+ pass "sdd-workspace -C DIR resolves DIR's workspace"
+ else
+ fail "sdd-workspace -C DIR resolves DIR's workspace"
+ echo " got: $c_dir"
+ fi
+
+ # These two run the way SKILL.md invokes them, `bash scripts/...` from the
+ # skill's directory: the relative script path must survive the -C cd.
+ local c_brief
+ c_brief="$(cd "$SDD_SCRIPTS/.." && bash scripts/task-brief -C "$wt" plan-a.md 1)" || true
+ if [[ "$c_brief" == "wrote $wt_root/.superpowers/sdd/plan-a/task-1-brief.md: "* ]]; then
+ pass "task-brief -C DIR writes the brief into DIR's workspace"
+ else
+ fail "task-brief -C DIR writes the brief into DIR's workspace"
+ echo " got: $c_brief"
+ fi
+
+ local c_rp c_rp_path
+ c_rp="$(cd "$SDD_SCRIPTS/.." && bash scripts/review-package -C "$wt" plan-a.md "$wt_base" HEAD)" || true
+ c_rp_path="$(printf '%s\n' "$c_rp" | sed -n 's/^wrote \(.*\): [0-9].*$/\1/p')"
+ case "$c_rp_path" in
+ "$wt_root/.superpowers/sdd/plan-a/review-"*.diff)
+ if grep -q 'wt-only.txt' "$c_rp_path"; then
+ pass "review-package -C DIR diffs DIR's HEAD into DIR's workspace"
+ else
+ fail "review-package -C DIR diffs DIR's HEAD into DIR's workspace"
+ echo " diff lacks the worktree's commit: $c_rp_path"
+ fi
+ ;;
+ *)
+ fail "review-package -C DIR diffs DIR's HEAD into DIR's workspace"
+ echo " got: $c_rp"
+ ;;
+ esac
+
+ rc=0
+ (cd "$repo" && "$SDD_SCRIPTS/review-package" -C "$TEST_ROOT/no-such-dir" plan-a.md HEAD~1 HEAD >/dev/null 2>&1) || rc=$?
+ if [[ "$rc" -eq 2 ]]; then
+ pass "review-package -C with a missing directory errors with exit 2"
+ else
+ fail "review-package -C with a missing directory errors with exit 2"
+ echo " exit: $rc"
+ fi
+
+ # Run from outside any repository (e.g. the skill's own directory in an
+ # installed plugin), the scripts stop even when the plan's absolute path
+ # is inside a repository: like git, they act on the current directory's
+ # working tree (or -C DIR), never on one guessed from the plan.
+ local nonrepo="$TEST_ROOT/not-a-repo"
+ mkdir -p "$nonrepo"
+ local nr_msg="SDD scripts must run from inside the git working tree you're executing in, with at least one commit (current directory: $nonrepo). If this is a new project, run 'git init' and make a first commit, then rerun."
+ local nr_before nr_cmd nr_err
+ nr_before="$(find "$wt_root/.superpowers" | sort)"
+ for nr_cmd in "sdd-workspace $wt/plan-a.md" "task-brief $wt/plan-a.md 1" "review-package $wt/plan-a.md $wt_base $wt_head"; do
+ rc=0
+ # shellcheck disable=SC2086 # nr_cmd is a fixed script name plus its arguments
+ nr_err="$(cd "$nonrepo" && "$SDD_SCRIPTS"/$nr_cmd 2>&1 >/dev/null)" || rc=$?
+ if [[ "$rc" -eq 2 && "$nr_err" == "$nr_msg"$'\n'"git said: fatal: not a git repository"* ]]; then
+ pass "${nr_cmd%% *} outside any repository stops with the shared message despite a plan in a repository"
+ else
+ fail "${nr_cmd%% *} outside any repository stops with the shared message despite a plan in a repository"
+ echo " exit: $rc"
+ echo " stderr: $nr_err"
+ fi
+ done
+ if [[ ! -e "$nonrepo/.superpowers" && "$(find "$wt_root/.superpowers" | sort)" == "$nr_before" ]]; then
+ pass "outside any repository, nothing is written to the cwd or the plan's repository"
+ else
+ fail "outside any repository, nothing is written to the cwd or the plan's repository"
+ fi
+
+ # --- No repository anywhere: a greenfield plan before Task 1 (#2242) ---
+ local gf="$TEST_ROOT/greenfield"
+ mkdir -p "$gf"
+ printf '## Task 1: Scaffold the repo\n\nCreate files.\n' > "$gf/plan.md"
+ # One message for both ways to get here: a caller standing in the wrong
+ # directory (such as the plugin's own skill directory, where git init is
+ # the wrong fix) and a new project with no repository yet. git's own
+ # first error line follows it, so the reason git refused is never hidden.
+ local no_repo_msg="SDD scripts must run from inside the git working tree you're executing in, with at least one commit (current directory: $gf). If this is a new project, run 'git init' and make a first commit, then rerun."
+ local cmd gf_err
+ for cmd in "sdd-workspace plan.md" "task-brief plan.md 1"; do
+ local script=${cmd%% *}
+ rc=0
+ # shellcheck disable=SC2086 # cmd is a fixed script name plus its arguments
+ gf_err="$(cd "$gf" && "$SDD_SCRIPTS"/$cmd 2>&1 >/dev/null)" || rc=$?
+ if [[ "$rc" -eq 2 && "$gf_err" == "$no_repo_msg"$'\n'"git said: fatal: not a git repository"* ]]; then
+ pass "$script outside any repository exits 2 naming both fixes"
+ else
+ fail "$script outside any repository exits 2 naming both fixes"
+ echo " exit: $rc"
+ echo " stderr: $gf_err"
+ fi
+ done
+ rc=0
+ gf_err="$(cd "$gf" && "$SDD_SCRIPTS/review-package" plan.md HEAD~1 HEAD 2>&1 >/dev/null)" || rc=$?
+ if [[ "$rc" -eq 2 && "$gf_err" == "$no_repo_msg"$'\n'"git said: fatal: not a git repository"* ]]; then
+ pass "review-package outside any repository exits 2 naming both fixes"
+ else
+ fail "review-package outside any repository exits 2 naming both fixes"
+ echo " exit: $rc"
+ echo " stderr: $gf_err"
+ fi
+ if [[ ! -e "$gf/.superpowers" ]]; then
+ pass "nothing is written outside a repository"
+ else
+ fail "nothing is written outside a repository"
+ find "$gf/.superpowers" | sed 's/^/ /'
+ fi
+
+ # A repository with no commit yet has no range to review, so
+ # review-package gets the same stop, naming its directory.
+ git init -q -b main "$gf"
+ rc=0
+ gf_err="$(cd "$gf" && "$SDD_SCRIPTS/review-package" plan.md HEAD~1 HEAD 2>&1 >/dev/null)" || rc=$?
+ if [[ "$rc" -eq 2 && "$gf_err" == "$no_repo_msg"$'\n'"git said: fatal: "* && ! -e "$gf/.superpowers" ]]; then
+ pass "review-package in a repository with no commit exits 2 with the same message"
+ else
+ fail "review-package in a repository with no commit exits 2 with the same message"
+ echo " exit: $rc"
+ echo " stderr: $gf_err"
+ fi
+
+ # --- git refuses the repository itself: its reason must reach the caller ---
+ # Inside a working tree git won't trust ("dubious ownership": another
+ # owner, a FAT or network drive, WSL /mnt/c), the shared message alone
+ # would be wrong, so git's own line has to follow it. git's test knob
+ # GIT_TEST_ASSUME_DIFFERENT_OWNER simulates another owner without root.
+ local dub_err dub_msg="SDD scripts must run from inside the git working tree you're executing in, with at least one commit (current directory: $repo). If this is a new project, run 'git init' and make a first commit, then rerun."
+ if (cd "$repo" && GIT_TEST_ASSUME_DIFFERENT_OWNER=1 git rev-parse --show-toplevel >/dev/null 2>&1); then
+ echo " [SKIP] git refusing a dubious-ownership repo ($(git --version) ignores GIT_TEST_ASSUME_DIFFERENT_OWNER)"
+ else
+ rc=0
+ dub_err="$(cd "$repo" && GIT_TEST_ASSUME_DIFFERENT_OWNER=1 "$SDD_SCRIPTS/sdd-workspace" plan-a.md 2>&1 >/dev/null)" || rc=$?
+ if [[ "$rc" -eq 2 && "$dub_err" == "$dub_msg"$'\n'"git said: fatal: detected dubious ownership in repository at "* ]]; then
+ pass "a repository git refuses as dubious stops with the shared message plus git's reason"
+ else
+ fail "a repository git refuses as dubious stops with the shared message plus git's reason"
+ echo " exit: $rc"
+ echo " stderr: $dub_err"
+ fi
+ fi
+
# --- helpers survive a mode-stripping extractor dropping exec bits (#2040) ---
local stripped="$TEST_ROOT/stripped-scripts"
mkdir -p "$stripped"
- cp "$SDD_SCRIPTS/sdd-workspace" "$SDD_SCRIPTS/task-brief" "$SDD_SCRIPTS/review-package" "$stripped/"
+ cp "$SDD_SCRIPTS/sdd-repo" "$SDD_SCRIPTS/sdd-workspace" "$SDD_SCRIPTS/task-brief" "$SDD_SCRIPTS/review-package" "$stripped/"
chmod -x "$stripped"/*
local noexec_out noexec_rc=0
noexec_out="$(cd "$repo" && bash "$stripped/task-brief" plan-b.md 1 2>&1)" || noexec_rc=$?
diff --git a/tests/codex-plugin-sync/test-sync-to-codex-plugin.sh b/tests/codex-plugin-sync/test-sync-to-codex-plugin.sh
index 84282c2..fb3aaa7 100755
--- a/tests/codex-plugin-sync/test-sync-to-codex-plugin.sh
+++ b/tests/codex-plugin-sync/test-sync-to-codex-plugin.sh
@@ -571,6 +571,12 @@ main() {
local bootstrap_output
local missing_manifest_status
local missing_manifest_output
+ local linked_upstream_main
+ local linked_upstream
+ local linked_dest_main
+ local linked_dest
+ local linked_preview_status
+ local linked_preview_output
local mixed_only_status
local mixed_only_output
local stale_preview_status
@@ -603,6 +609,10 @@ main() {
dest_branch="fixture/preview-target"
bootstrap_dest_branch="fixture/bootstrap-preview-target"
fake_bin="$TEST_ROOT/bin"
+ linked_upstream_main="$TEST_ROOT/linked-upstream-main"
+ linked_upstream="$TEST_ROOT/linked-upstream"
+ linked_dest_main="$TEST_ROOT/linked-destination-main"
+ linked_dest="$TEST_ROOT/linked-destination"
init_repo "$upstream"
write_upstream_fixture "$upstream"
@@ -635,6 +645,17 @@ main() {
write_bootstrap_destination_fixture "$bootstrap_dest"
checkout_fixture_branch "$bootstrap_dest" "$bootstrap_dest_branch"
+ # The sync script wants upstream on main, so park the primary checkout
+ # on another branch and check main out in the linked worktree.
+ init_repo "$linked_upstream_main"
+ write_upstream_fixture "$linked_upstream_main"
+ git -C "$linked_upstream_main" switch -q -c fixture/parked
+ git -C "$linked_upstream_main" worktree add -q "$linked_upstream" main
+
+ init_repo "$linked_dest_main"
+ write_destination_fixture "$linked_dest_main"
+ git -C "$linked_dest_main" worktree add -q -b fixture/linked-target "$linked_dest"
+
write_fake_gh "$fake_bin"
# This regression test is about dry-run content, so capture the preview
@@ -654,6 +675,8 @@ main() {
noop_apply_status=$?
missing_manifest_output="$(run_preview_without_manifest "$upstream" "$dest" "$fake_bin")"
missing_manifest_status=$?
+ linked_preview_output="$(run_preview "$linked_upstream" "$linked_dest" "$fake_bin")"
+ linked_preview_status=$?
set -e
help_output="$(run_help "$upstream" "$fake_bin")"
script_source="$(cat "$upstream/scripts/sync-to-codex-plugin.sh")"
@@ -731,6 +754,11 @@ Locally modified fixture content." "Dirty local apply preserves tracked working-
short_description: \"Destination-owned OpenAI metadata\"" "Clean no-op local apply preserves OpenAI agent metadata"
echo ""
+ echo "Linked worktree assertions..."
+ assert_equals "$linked_preview_status" "0" "Preview from a linked worktree into a linked worktree exits successfully"
+ assert_not_contains "$linked_preview_output" "is not a git checkout" "Linked worktrees are accepted as git checkouts"
+
+ echo ""
echo "Missing manifest assertions..."
assert_equals "$missing_manifest_status" "1" "Missing manifest exits with failure"
assert_contains "$missing_manifest_output" "ERROR: committed Codex manifest missing at" "Missing manifest reports committed manifest path"
diff --git a/tests/codex/test-package-codex-plugin.sh b/tests/codex/test-package-codex-plugin.sh
index 947cb6d..05e150a 100755
--- a/tests/codex/test-package-codex-plugin.sh
+++ b/tests/codex/test-package-codex-plugin.sh
@@ -9,6 +9,7 @@ FAILURES=0
TEST_ROOT="$(mktemp -d)"
cleanup() {
+ git -C "$REPO_ROOT" worktree remove --force "$TEST_ROOT/linked-worktree" >/dev/null 2>&1 || true
rm -rf "$TEST_ROOT"
}
trap cleanup EXIT
@@ -138,6 +139,8 @@ archive="$TEST_ROOT/superpowers"
tar_archive="$TEST_ROOT/superpowers.tar.gz"
extracted="$TEST_ROOT/extracted"
tar_extracted="$TEST_ROOT/tar-extracted"
+worktree_archive="$TEST_ROOT/superpowers-from-worktree.zip"
+linked_worktree="$TEST_ROOT/linked-worktree"
write_metadata_fixture "$metadata_source"
source_hooks="$(python3 -c 'import json; print(json.load(open("'"$REPO_ROOT"'/.codex-plugin/plugin.json")).get("hooks"))')"
@@ -160,6 +163,25 @@ assert_contains "$output" "Archive:" "reports archive path"
assert_contains "$output" "Format: zip" "reports default zip format"
assert_contains "$output" "SHA-256:" "reports archive checksum"
+if git -C "$REPO_ROOT" worktree add -q --detach "$linked_worktree" HEAD >/dev/null 2>&1; then
+ # The worktree is checked out at HEAD, so copy in the script under test
+ # (it may have uncommitted edits); that dirties the tree, hence --allow-dirty.
+ cp "$SCRIPT_UNDER_TEST" "$linked_worktree/scripts/package-codex-plugin.sh"
+ if output="$("$linked_worktree/scripts/package-codex-plugin.sh" --allow-dirty --metadata-source "$metadata_source" --output "$worktree_archive" 2>&1)"; then
+ pass "package script accepts a linked worktree checkout"
+ else
+ fail "package script accepts a linked worktree checkout"
+ printf '%s\n' "$output" | sed 's/^/ /'
+ fi
+ if [[ -f "$worktree_archive" ]]; then
+ pass "package script writes archive from a linked worktree"
+ else
+ fail "package script writes archive from a linked worktree"
+ fi
+else
+ fail "create linked worktree fixture"
+fi
+
extract_archive "$archive" "$extracted"
archive_paths="$(list_archive "$archive" | normalize_archive_paths)"
diff --git a/tests/hermes/test_plugin.py b/tests/hermes/test_plugin.py
index 57d619e..7c896a3 100644
--- a/tests/hermes/test_plugin.py
+++ b/tests/hermes/test_plugin.py
@@ -87,6 +87,24 @@ class TestBootstrapInjection:
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_subagent_platform_skips_bootstrap_on_first_turn(self, mock_ctx):
+ plugin = _load_plugin()
+ plugin.register(mock_ctx)
+ assert (
+ _fire_pre_llm(mock_ctx, is_first_turn=True, platform="subagent")
+ is None
+ )
+
+ def test_non_subagent_platforms_receive_bootstrap(self, mock_ctx):
+ plugin = _load_plugin()
+ plugin.register(mock_ctx)
+ for platform in ("cli", "desktop", "cron", "telegram"):
+ result = _fire_pre_llm(
+ mock_ctx, is_first_turn=True, platform=platform
+ )
+ assert isinstance(result, dict)
+ assert BOOTSTRAP_MARKER in result["context"]
+
def test_hook_tolerates_future_kwargs(self, mock_ctx):
plugin = _load_plugin()
plugin.register(mock_ctx)
diff --git a/tests/hooks/test-run-hook-cmd-windows.sh b/tests/hooks/test-run-hook-cmd-windows.sh
index b58c6d1..63e2db8 100755
--- a/tests/hooks/test-run-hook-cmd-windows.sh
+++ b/tests/hooks/test-run-hook-cmd-windows.sh
@@ -207,6 +207,24 @@ else
fi
fi
+# --- the hooks.json powershell form dispatches under PowerShell ---
+# Copilot (CLI and VS Code) on Windows runs hook commands through PowerShell,
+# where the quoted `command` form is a ParserError (#2189). It substitutes
+# ${CLAUDE_PLUGIN_ROOT} into the string first; the plugin root here has a
+# space, as real install paths can.
+ps_plugin="$TEST_ROOT/plugin root"
+make_plugin "$ps_plugin" real
+cp "$ps_plugin/hooks/probe-ok" "$ps_plugin/hooks/session-start"
+ps_command="$(sed -n 's/^ *"powershell": "\(.*\)",\{0,1\}$/\1/p' "$REPO_ROOT/hooks/hooks.json" | sed 's/\\"/"/g')"
+ps_command="${ps_command//\$\{CLAUDE_PLUGIN_ROOT\}/$(cygpath -w "$ps_plugin")}"
+RC=0
+OUT="$(cd "$TEST_ROOT" && powershell -NoProfile -NonInteractive -Command "$ps_command" 2>&1)" || RC=$?
+if [[ -n "$ps_command" && "$RC" -eq 0 && "$OUT" == *probe-ran* ]]; then
+ pass "hooks.json powershell command runs session-start under PowerShell"
+else
+ fail "hooks.json powershell command runs session-start under PowerShell (command=$ps_command, rc=$RC, out=$OUT)"
+fi
+
# --- no usable bash: exit 0 quietly, without invoking the WSL launcher ---
run_hook "$sandbox" "$TEST_ROOT" probe-ok \
LOCALAPPDATA="$NO_LA" PATH="$SYS32_PATH"
diff --git a/tests/hooks/test-session-start.sh b/tests/hooks/test-session-start.sh
index 6ddf011..1fc6ace 100755
--- a/tests/hooks/test-session-start.sh
+++ b/tests/hooks/test-session-start.sh
@@ -147,6 +147,12 @@ echo "SessionStart hook output tests"
# 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).
+#
+# VS Code Copilot ignores shell:"bash" and runs the `command` string through
+# PowerShell regardless (#2189). The optional `powershell` key supplies a
+# PowerShell-native form of the same dispatch: the `&` call operator makes the
+# quoted plugin-root path parse as a command invocation instead of a string
+# expression followed by the bareword `session-start`.
if node -e '
const hooks = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
const entry = hooks.hooks.SessionStart[0].hooks[0];
@@ -158,6 +164,14 @@ if (!/run-hook\.cmd" session-start$/.test(entry.command)) {
console.error(`unexpected SessionStart command shape: ${entry.command}`);
process.exit(1);
}
+if (typeof entry.powershell !== "string") {
+ console.error(`SessionStart hook missing powershell key for VS Code Copilot (#2189)`);
+ process.exit(1);
+}
+if (!/^& "/.test(entry.powershell) || !/run-hook\.cmd" session-start$/.test(entry.powershell)) {
+ console.error(`unexpected SessionStart powershell shape: ${entry.powershell}`);
+ process.exit(1);
+}
' "$REPO_ROOT/hooks/hooks.json"; then
pass "hooks.json registers SessionStart with shell:bash dispatch"
else
@@ -247,6 +261,49 @@ assert_command_output \
CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
"$bash_bin" "$WRAPPER_UNDER_TEST" session-start
+# On a Unix system with zsh but no bash (#2503), the harness can't honour
+# shell:"bash" and runs run-hook.cmd with zsh or sh. $BASH is unset there, so
+# the wrapper must find zsh, which runs session-start unchanged. sh only
+# counts when it isn't bash (Git Bash's and macOS's sh are bash, which sets
+# $BASH and never reaches the fallback).
+posix_sh="$(command -v sh)"
+if [[ -n "$(env -i "$posix_sh" -c 'echo "${BASH:-}"')" ]]; then
+ posix_sh=""
+fi
+no_bash_bin="$TEST_ROOT/no-bash/bin"
+mkdir -p "$no_bash_bin"
+if zsh_bin="$(command -v zsh)"; then
+ ln -s "$zsh_bin" "$no_bash_bin/zsh"
+ for runner_bin in "$zsh_bin" ${posix_sh:+"$posix_sh"}; do
+ assert_command_output \
+ "run-hook.cmd run by ${runner_bin##*/} without bash dispatches session-start through zsh" \
+ "nested" \
+ "" \
+ "" \
+ "$(make_home "no-bash-${runner_bin##*/}")" \
+ PATH="$no_bash_bin" \
+ CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
+ "$runner_bin" "$WRAPPER_UNDER_TEST" session-start
+ done
+else
+ echo " [SKIP] run-hook.cmd without bash: zsh not installed"
+fi
+
+# With neither bash nor zsh, exit 0 quietly like the Windows half: the plugin
+# still works, just without the bootstrap.
+if [[ -n "$posix_sh" ]]; then
+ no_shell_rc=0
+ no_shell_out="$(env -i PATH="$TEST_ROOT/no-shell" HOME="$TEST_ROOT" CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
+ "$posix_sh" "$WRAPPER_UNDER_TEST" session-start 2>&1)" || no_shell_rc=$?
+ if [[ "$no_shell_rc" -eq 0 && -z "$no_shell_out" ]]; then
+ pass "run-hook.cmd with neither bash nor zsh exits 0 with no output"
+ else
+ fail "run-hook.cmd with neither bash nor zsh exits 0 with no output (rc=$no_shell_rc, out=$no_shell_out)"
+ fi
+else
+ echo " [SKIP] run-hook.cmd with neither bash nor zsh: sh is bash here"
+fi
+
# Run by bare filename from inside hooks/ ($0 has no slash), the plugin root
# must still resolve.
bare_name_home="$(make_home bare-name)"
@@ -294,27 +351,57 @@ assert_command_output \
CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
"$bash_bin" -c 'cd "$1" && exec "$2" "$3"' _ "$backslash_cwd" "$bash_bin" "$backslash_hook"
-# When cat is on PATH, the JSON must still go through it: the pipe absorbs
-# EPIPE on Windows + Git Bash (#1612). The stub records that it ran.
-cat_stub_dir="$TEST_ROOT/cat-stub/bin"
-cat_marker="$TEST_ROOT/cat-stub/used"
-mkdir -p "$cat_stub_dir"
-printf '#!%s\n: > "%s"\nexec /bin/cat "$@"\n' "$bash_bin" "$cat_marker" > "$cat_stub_dir/cat"
-chmod +x "$cat_stub_dir/cat"
-cat_stub_home="$(make_home cat-stub)"
-assert_command_output \
- "session-start with cat on PATH emits nested additionalContext" \
- "nested" \
- "" \
- "" \
- "$cat_stub_home" \
- PATH="$cat_stub_dir" \
- CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
- "$bash_bin" "$HOOK_UNDER_TEST"
-if [[ -f "$cat_marker" ]]; then
- pass "session-start pipes its JSON through cat when cat is on PATH"
+# EPIPE on Windows + Git Bash (#1612): the harness can close the hook's stdout
+# before the JSON is written. The hook must still exit 0 with nothing on
+# stderr, directly and through run-hook.cmd. The reader (:) exits without
+# reading, so the write usually lands on a closed pipe.
+assert_closed_stdout() {
+ local description="$1"
+ shift
+ local err_file="$TEST_ROOT/closed-stdout.err"
+ local status
+ set +e
+ env -i PATH="${PATH:-}" HOME="$TEST_ROOT" CLAUDE_PLUGIN_ROOT="$REPO_ROOT" "$@" 2>"$err_file" | :
+ status="${PIPESTATUS[0]}"
+ set -e
+ if [[ "$status" -eq 0 && ! -s "$err_file" ]]; then
+ pass "$description"
+ else
+ fail "$description"
+ echo " exit $status, stderr:"
+ sed 's/^/ /' "$err_file"
+ fi
+}
+
+for _ in 1 2 3; do
+ assert_closed_stdout \
+ "session-start exits 0 silently when stdout is closed early" \
+ "$bash_bin" "$HOOK_UNDER_TEST"
+ assert_closed_stdout \
+ "run-hook.cmd exits 0 silently when stdout is closed early" \
+ "$bash_bin" "$WRAPPER_UNDER_TEST" session-start
+done
+
+# Each fork costs tens of milliseconds under Git Bash on Windows, and this hook
+# runs on every startup, /clear and compaction (#2081). Neither the hook nor
+# the wrapper may start a child process. Counted with Linux strace (Git for
+# Windows ships an unrelated strace.exe with other options).
+if [[ "$(uname -s)" == Linux ]] && command -v strace >/dev/null 2>&1; then
+ fork_log="$TEST_ROOT/forks.log"
+ for target in "$HOOK_UNDER_TEST" "$WRAPPER_UNDER_TEST session-start"; do
+ # shellcheck disable=SC2086 # split the wrapper's argument off its path
+ env -i PATH="${PATH:-}" HOME="$TEST_ROOT" CLAUDE_PLUGIN_ROOT="$REPO_ROOT" \
+ strace -f -qq -e trace=fork,vfork,clone,clone3 -o "$fork_log" \
+ "$bash_bin" $target > /dev/null
+ forks="$(grep -c -E '(fork|clone3?)\(' "$fork_log" || true)"
+ if [[ "$forks" -eq 0 ]]; then
+ pass "${target##*/} starts no child processes"
+ else
+ fail "${target##*/} starts no child processes ($forks started)"
+ fi
+ done
else
- fail "session-start pipes its JSON through cat when cat is on PATH"
+ echo " [SKIP] child-process count: needs Linux strace"
fi
if [[ "$FAILURES" -gt 0 ]]; then
diff --git a/tests/opencode/run-tests.sh b/tests/opencode/run-tests.sh
index 43e1a3a..4cdf546 100755
--- a/tests/opencode/run-tests.sh
+++ b/tests/opencode/run-tests.sh
@@ -46,6 +46,7 @@ while [[ $# -gt 0 ]]; do
echo " test-plugin-loading.sh Verify plugin installation and structure"
echo " test-bootstrap-caching.sh Verify bootstrap content caching"
echo " test-session-bootstrap.sh Verify session classification and lookup recovery"
+ echo " test-hook-registration.sh Verify V2 bootstrap registers on context, compaction, generate"
echo " test-skill-registration.sh Verify V2 skill registration contract (2.0.4 path field)"
echo " test-tools.sh Test use_skill and find_skills tools (integration)"
echo " test-priority.sh Test skill priority resolution (integration)"
@@ -64,6 +65,7 @@ tests=(
"test-plugin-loading.sh"
"test-bootstrap-caching.sh"
"test-session-bootstrap.sh"
+ "test-hook-registration.sh"
"test-skill-registration.sh"
)
diff --git a/tests/opencode/test-bootstrap-caching.mjs b/tests/opencode/test-bootstrap-caching.mjs
index 386b7b1..39e4daa 100644
--- a/tests/opencode/test-bootstrap-caching.mjs
+++ b/tests/opencode/test-bootstrap-caching.mjs
@@ -76,6 +76,9 @@ const failures = scenario === 'present'
if (scenario === 'present') {
failures.push(...assertV2Bootstrap(result));
+ // #2583: both flavors register bare skill ids and look them up exactly.
+ failures.push(...assertTeachesBareSkillIds('V1', bootstrapText(firstOutput), 'name'));
+ failures.push(...assertTeachesBareSkillIds('V2', v2Result.text, 'id'));
}
failures.push(...mappingFailures);
@@ -202,6 +205,25 @@ function assertMappingConstants(mod) {
return failures;
}
+// #2583: skills reference each other as `superpowers:<name>` (the Claude Code
+// plugin namespace), but OpenCode V1 and V2 register bare ids (`brainstorming`)
+// and their `skill` tools do an exact lookup, so a namespaced call fails with
+// "Unable to load skill". When the injected bootstrap contains namespaced
+// references, its tool mapping must tell the model to drop the prefix, using
+// the flavor's `skill` parameter (V1 `name`, V2 `id`).
+function assertTeachesBareSkillIds(flavor, text, param) {
+ const failures = [];
+ const refs = [...new Set(text.match(/superpowers:[a-z0-9-]+/g) || [])];
+ if (refs.length === 0) return failures;
+ if (!text.includes('drop the `superpowers:` prefix')) {
+ failures.push(`expected ${flavor} bootstrap to tell the model to drop the superpowers: prefix (bootstrap references ${refs.join(', ')})`);
+ }
+ if (!text.includes(`\`superpowers:brainstorming\` → \`skill\` with \`${param}: "brainstorming"\``)) {
+ failures.push(`expected ${flavor} bootstrap to show superpowers:brainstorming loading as \`skill\` with \`${param}: "brainstorming"\``);
+ }
+ return failures;
+}
+
// Drive setup() with a mock V2 ctx and fire the captured "context" hook on a
// top-level (parentID-less) session. Returns the injected-part count and the
// injected bootstrap text ('' when nothing was injected).
diff --git a/tests/opencode/test-hook-registration.mjs b/tests/opencode/test-hook-registration.mjs
new file mode 100644
index 0000000..9df6a6f
--- /dev/null
+++ b/tests/opencode/test-hook-registration.mjs
@@ -0,0 +1,98 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+// Issue #2391: the V2 plugin must register bootstrap injection on
+// `context`, `compaction`, and `generate`. OpenCode dispatches each request
+// shape through a different hook, so a handler on `context` only means
+// compaction and generate requests diverge from the cached prefix at the
+// tail — a cold re-prefill of the whole session on the largest request of
+// its lifetime.
+
+const [, , inputPath] = process.argv;
+assert.ok(inputPath, 'pass the plugin module path');
+const pluginURL = pathToFileURL(fs.realpathSync(inputPath));
+const marker = '<EXTREMELY_IMPORTANT>\nYou have superpowers.';
+let generation = 0;
+
+async function captureHooks(fetchSession) {
+ const mod = await import(`${pluginURL.href}?hooks-test=${++generation}`);
+ const hooks = new Map();
+ await mod.default.setup({
+ skill: { transform: async (transform) => transform({ add: () => {} }) },
+ session: {
+ get: ({ sessionID }) => fetchSession(sessionID),
+ hook: async (name, callback) => { hooks.set(name, callback); },
+ },
+ });
+ return hooks;
+}
+
+function event(sessionID) {
+ return {
+ sessionID,
+ messages: [{ role: 'user', content: [{ type: 'text', text: 'continue' }] }],
+ };
+}
+
+const session = (id) => ({ id });
+
+// All three request hooks must be registered.
+for (const required of ['context', 'compaction', 'generate']) {
+ const hooks = await captureHooks(async (id) => session(id));
+ assert.ok(hooks.has(required), `plugin registers '${required}' hook`);
+}
+
+// One shared handler: the three hooks resolve to the same function so
+// behaviour cannot drift between request shapes.
+const shared = await captureHooks(async (id) => session(id));
+assert.equal(
+ shared.get('compaction'),
+ shared.get('context'),
+ 'compaction handler is the context handler',
+);
+assert.equal(
+ shared.get('generate'),
+ shared.get('context'),
+ 'generate handler is the context handler',
+);
+
+// Each hook actually injects the bootstrap into an eligible session.
+for (const name of ['context', 'compaction', 'generate']) {
+ const hooks = await captureHooks(async (id) => session(id));
+ const ev = event(`${name}-root`);
+ await hooks.get(name)(ev);
+ assert.equal(
+ ev.messages[0].content.filter((p) => p.text?.startsWith(marker)).length,
+ 1,
+ `'${name}' hook injects bootstrap exactly once`,
+ );
+}
+
+// Child sessions stay suppressed on every hook (regression guard against
+// only 'context' checking parentID while compaction/generate skip the check).
+for (const name of ['context', 'compaction', 'generate']) {
+ const hooks = await captureHooks(async (id) => ({ id, parentID: 'parent' }));
+ const ev = event(`${name}-child`);
+ await hooks.get(name)(ev);
+ assert.equal(
+ ev.messages[0].content.filter((p) => p.text?.startsWith(marker)).length,
+ 0,
+ `'${name}' hook skips bootstrap for child sessions`,
+ );
+}
+
+// Idempotence: a second delivery of the same event does not double-inject.
+for (const name of ['context', 'compaction', 'generate']) {
+ const hooks = await captureHooks(async (id) => session(id));
+ const ev = event(`${name}-root`);
+ await hooks.get(name)(ev);
+ await hooks.get(name)(ev);
+ assert.equal(
+ ev.messages[0].content.filter((p) => p.text?.startsWith(marker)).length,
+ 1,
+ `'${name}' hook stays idempotent on repeat`,
+ );
+}
+
+console.log('V2 hook registration (context/compaction/generate) passed');
diff --git a/tests/opencode/test-hook-registration.sh b/tests/opencode/test-hook-registration.sh
new file mode 100755
index 0000000..47191ef
--- /dev/null
+++ b/tests/opencode/test-hook-registration.sh
@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+node "$SCRIPT_DIR/test-hook-registration.mjs" "$SCRIPT_DIR/../../.opencode/plugins/superpowers.js"
diff --git a/tests/opencode/test-session-bootstrap.mjs b/tests/opencode/test-session-bootstrap.mjs
index 31658d5..67b3118 100644
--- a/tests/opencode/test-session-bootstrap.mjs
+++ b/tests/opencode/test-session-bootstrap.mjs
@@ -139,6 +139,16 @@ for (const flavor of ['v1', 'v2']) {
await unknown.invoke(noID);
assert.equal(bootstrapCount(noID), 1);
assert.deepEqual(unknown.lookups, []);
+
+ // #2197: a prompt that merely mentions the bootstrap's tag is not the bootstrap.
+ const mentions = await makeHarness(flavor, (id) => reply(flavor, { id }));
+ const probe = makeEvent(flavor, `${flavor}-mentions-tag`);
+ (probe.messages[0].parts ?? probe.messages[0].content)[0].text =
+ "Is there an 'EXTREMELY_IMPORTANT' block in your context?";
+ await mentions.invoke(probe);
+ assert.equal(bootstrapCount(probe), 1, `${flavor}: prompt mentioning the tag still gets bootstrap`);
+ await mentions.invoke(probe);
+ assert.equal(bootstrapCount(probe), 1, `${flavor}: prompt mentioning the tag, repeated event`);
}
function compactedEvent(sessionID) {
diff --git a/tests/pi/test-pi-extension.mjs b/tests/pi/test-pi-extension.mjs
index d7af9cb..65d65e0 100644
--- a/tests/pi/test-pi-extension.mjs
+++ b/tests/pi/test-pi-extension.mjs
@@ -34,6 +34,14 @@ function firstHandler(handlers, event) {
return eventHandlers[0];
}
+// Fire an event the way pi does: every registered handler runs, and an event
+// the extension does not subscribe to is a no-op.
+async function emit(handlers, event, payload) {
+ for (const handler of handlers.get(event) ?? []) {
+ await handler({ type: event, ...payload }, {});
+ }
+}
+
function textOf(message) {
if (typeof message.content === 'string') return message.content;
return message.content
@@ -51,29 +59,20 @@ test('package.json declares a pi package with skills and extension resources', a
assert.deepEqual(pkg.pi.extensions, ['./.pi/extensions/superpowers.ts']);
});
-test('extension registers lifecycle hooks without pre-compaction injection', async () => {
+test('extension leaves package skill discovery to Pi and registers lifecycle hooks', async () => {
const { handlers } = await loadExtension();
- for (const event of ['resources_discover', 'session_start', 'session_compact', 'context', 'agent_end']) {
+ assert.equal((handlers.get('resources_discover') ?? []).length, 0, 'extension must not bypass package skill filters');
+ for (const event of ['session_start', 'session_compact', 'context']) {
assert.equal((handlers.get(event) ?? []).length, 1, `missing ${event} handler`);
}
assert.equal((handlers.get('session_before_compact') ?? []).length, 0);
});
-test('resources_discover contributes the bundled skills directory', async () => {
- const { handlers } = await loadExtension();
- const discover = firstHandler(handlers, 'resources_discover');
-
- const result = await discover({ type: 'resources_discover', cwd: repoRoot, reason: 'startup' }, {});
-
- assert.deepEqual(result.skillPaths, [resolve(repoRoot, 'skills')]);
-});
-
-test('startup context injects the bootstrap as one user message until agent_end', async () => {
+test('startup context injects the bootstrap as one user message', async () => {
const { handlers } = await loadExtension();
const sessionStart = firstHandler(handlers, 'session_start');
const context = firstHandler(handlers, 'context');
- const agentEnd = firstHandler(handlers, 'agent_end');
await sessionStart({ type: 'session_start', reason: 'startup' }, {});
@@ -94,10 +93,40 @@ test('startup context injects the bootstrap as one user message until agent_end'
const alreadyInjected = await context({ type: 'context', messages: result.messages }, {});
assert.equal(alreadyInjected, undefined, 'bootstrap should not duplicate when already present');
+});
+
+// pi emits agent_start/agent_end around every user prompt, not once per
+// session, and the messages a context handler returns are never written back
+// to session history. So every provider request of every prompt needs the
+// bootstrap injected again (#2083).
+test('every provider request of every prompt in a session carries the bootstrap', async () => {
+ const { handlers } = await loadExtension();
+ const context = firstHandler(handlers, 'context');
- await agentEnd({ type: 'agent_end', messages: [] }, {});
- const afterEnd = await context({ type: 'context', messages: originalMessages }, {});
- assert.equal(afterEnd, undefined, 'startup bootstrap should clear after agent_end');
+ await emit(handlers, 'session_start', { reason: 'startup' });
+
+ const history = [];
+ const prompts = [
+ { text: 'first prompt', providerRequests: 1 },
+ { text: 'second prompt with a tool call', providerRequests: 2 },
+ { text: 'third prompt', providerRequests: 1 },
+ ];
+ for (const [promptIndex, prompt] of prompts.entries()) {
+ history.push({ role: 'user', content: [{ type: 'text', text: prompt.text }], timestamp: promptIndex });
+ await emit(handlers, 'agent_start', {});
+ for (let request = 1; request <= prompt.providerRequests; request += 1) {
+ await emit(handlers, 'turn_start', {});
+ const result = await context({ type: 'context', messages: structuredClone(history) }, {});
+ const label = `prompt ${promptIndex + 1}, provider request ${request}`;
+ assert.ok(result, `${label}: bootstrap missing`);
+ assert.equal(result.messages.length, history.length + 1, `${label}: expected exactly one bootstrap message`);
+ assert.match(textOf(result.messages[0]), /You have superpowers/, `${label}: bootstrap not first`);
+ history.push({ role: 'assistant', content: [{ type: 'text', text: 'ok' }], timestamp: promptIndex });
+ await emit(handlers, 'turn_end', {});
+ }
+ await emit(handlers, 'agent_end', { messages: [] });
+ await emit(handlers, 'agent_settled', {});
+ }
});
test('session_compact injects bootstrap after compaction summaries, not before compaction', async () => {
diff --git a/tests/sdd-helper-paths/test-sdd-helper-paths.sh b/tests/sdd-helper-paths/test-sdd-helper-paths.sh
new file mode 100755
index 0000000..26c5fcb
--- /dev/null
+++ b/tests/sdd-helper-paths/test-sdd-helper-paths.sh
@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Fails when any file under skills/ tells the agent to run an SDD or
+# executing-plans helper (sdd-workspace, task-brief, review-package,
+# task-start, task-done) by a skill-relative `scripts/...` path without
+# saying to run it by its absolute path from the working tree.
+#
+# The helpers act on the git working tree of the current directory, like
+# git. A skill-relative path invites the agent to cd into the skill's own
+# directory (the plugin cache) to make the path work, which puts the
+# helpers outside the working tree it is executing in (#2429). Every such
+# reference must carry the phrase "by its absolute path" within a few
+# lines after it.
+#
+# Usage: tests/sdd-helper-paths/test-sdd-helper-paths.sh
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# A backticked invocation whose path is relative: optional "bash ", then an
+# optional ../<skill>/ prefix, then scripts/<helper>. Absolute paths ($S/...,
+# /...) don't match.
+invocation='`(bash )?(\.\./[a-z-]+/)?scripts/(sdd-workspace|task-brief|review-package|task-start|task-done)'
+phrase='by its absolute path'
+
+failed=0
+checked=0
+while IFS=: read -r file line _; do
+ checked=$((checked + 1))
+ # The phrase may wrap onto the next lines; look at this line and the two
+ # after it, joined (whitespace squeezed, so line-wrap indentation doesn't
+ # split the phrase), starting from the invocation itself.
+ window=$(sed -n "${line},$((line + 2))p" "$file" | tr -s '[:space:]' ' ')
+ after=$(printf '%s\n' "$window" | grep -oE "$invocation.*" | head -n 1)
+ if [[ "${after:0:240}" != *"$phrase"* ]]; then
+ echo "FAIL: ${file#"$REPO_ROOT"/}:$line runs a helper by a relative scripts/ path without \"$phrase\"" >&2
+ failed=1
+ fi
+done < <(grep -rnE --include='*.md' "$invocation" "$REPO_ROOT/skills")
+
+if ((checked == 0)); then
+ echo "FAIL: found no helper invocations under skills/; the pattern is stale" >&2
+ exit 1
+fi
+if ((failed)); then
+ echo "Say to run the script by its absolute path, from the working tree you're executing in." >&2
+ exit 1
+fi
+echo "PASS: all $checked relative helper references under skills/ say to run them by absolute path"
diff --git a/tests/skill-layout/test-no-dev-files-in-skills.sh b/tests/skill-layout/test-no-dev-files-in-skills.sh
new file mode 100755
index 0000000..9749f41
--- /dev/null
+++ b/tests/skill-layout/test-no-dev-files-in-skills.sh
@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Fails when a skill directory ships files meant for developing the skill.
+#
+# Everything under skills/<name>/ is installed next to SKILL.md, and agents
+# read and grep those directories during normal work. Pressure-test scenarios
+# open with lines like "This is a real scenario. You must choose and act", and
+# an agent that finds one there can take it as live instructions (#2277).
+# Scenarios and creation logs belong under tests/ instead.
+#
+# Usage: tests/skill-layout/test-no-dev-files-in-skills.sh
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+found=$(find "$REPO_ROOT/skills" -type f \( -name 'CREATION-LOG.md' -o -name 'test-*.md' \) | sort)
+
+if [[ -n "$found" ]]; then
+ while IFS= read -r file; do
+ echo "FAIL: ${file#"$REPO_ROOT"/} is skill-development material inside an installed skill" >&2
+ done <<<"$found"
+ echo "Move pressure scenarios and creation logs under tests/<skill>/." >&2
+ exit 1
+fi
+echo "PASS: no skill ships pressure scenarios or creation logs"
diff --git a/skills/systematic-debugging/CREATION-LOG.md b/tests/systematic-debugging/pressure-scenarios/CREATION-LOG.md
index 9aa0309..9aa0309 100644
--- a/skills/systematic-debugging/CREATION-LOG.md
+++ b/tests/systematic-debugging/pressure-scenarios/CREATION-LOG.md
diff --git a/skills/systematic-debugging/test-academic.md b/tests/systematic-debugging/pressure-scenarios/test-academic.md
index 23a6ed7..23a6ed7 100644
--- a/skills/systematic-debugging/test-academic.md
+++ b/tests/systematic-debugging/pressure-scenarios/test-academic.md
diff --git a/skills/systematic-debugging/test-pressure-1.md b/tests/systematic-debugging/pressure-scenarios/test-pressure-1.md
index 8d13b46..8d13b46 100644
--- a/skills/systematic-debugging/test-pressure-1.md
+++ b/tests/systematic-debugging/pressure-scenarios/test-pressure-1.md
diff --git a/skills/systematic-debugging/test-pressure-2.md b/tests/systematic-debugging/pressure-scenarios/test-pressure-2.md
index 2d2315e..2d2315e 100644
--- a/skills/systematic-debugging/test-pressure-2.md
+++ b/tests/systematic-debugging/pressure-scenarios/test-pressure-2.md
diff --git a/skills/systematic-debugging/test-pressure-3.md b/tests/systematic-debugging/pressure-scenarios/test-pressure-3.md
index 89734b8..89734b8 100644
--- a/skills/systematic-debugging/test-pressure-3.md
+++ b/tests/systematic-debugging/pressure-scenarios/test-pressure-3.md