superpowers-mcp 6.4.6 → 6.4.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/README.es.md +30 -3
  2. package/README.hi.md +30 -3
  3. package/README.ja.md +30 -3
  4. package/README.ko.md +30 -3
  5. package/README.md +31 -4
  6. package/README.pt-BR.md +30 -3
  7. package/README.zh-TW.md +30 -3
  8. package/docs/maintainers/upstream-sync.md +4 -0
  9. package/docs/skill-compositions.es.md +1 -1
  10. package/docs/skill-compositions.hi.md +1 -1
  11. package/docs/skill-compositions.ja.md +1 -1
  12. package/docs/skill-compositions.ko.md +1 -1
  13. package/docs/skill-compositions.md +1 -1
  14. package/docs/skill-compositions.pt-BR.md +1 -1
  15. package/docs/skill-compositions.zh-TW.md +1 -1
  16. package/out/server.js +148 -104
  17. package/out/setup-runner.js +51 -36
  18. package/out/setup.js +51 -36
  19. package/package.json +7 -6
  20. package/scripts/copy-skills.js +65 -6
  21. package/scripts/install.ps1 +11 -2
  22. package/scripts/install.sh +7 -1
  23. package/scripts/run-tests.js +164 -0
  24. package/scripts/setup.js +100 -11
  25. package/scripts/upstream-drift.js +31 -8
  26. package/skills/brainstorming/SKILL.md +24 -2
  27. package/skills/brainstorming/builder-check-prompt.md +23 -0
  28. package/skills/brainstorming/scripts/helper.js +2 -1
  29. package/skills/brainstorming/scripts/server.cjs +38 -10
  30. package/skills/brainstorming/scripts/start-server.ps1 +7 -3
  31. package/skills/brainstorming/scripts/start-server.sh +30 -6
  32. package/skills/brainstorming/scripts/stop-server.ps1 +10 -4
  33. package/skills/brainstorming/scripts/stop-server.sh +16 -10
  34. package/skills/diagnosing-superpowers/SKILL.md +6 -3
  35. package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
  36. package/skills/diagnosing-superpowers/templates/issue.md +23 -4
  37. package/skills/executing-plans/SKILL.md +18 -12
  38. package/skills/executing-plans/scripts/task-done +14 -5
  39. package/skills/executing-plans/scripts/task-done.ps1 +34 -12
  40. package/skills/executing-plans/scripts/task-start +16 -4
  41. package/skills/executing-plans/scripts/task-start.ps1 +9 -4
  42. package/skills/requesting-code-review/SKILL.md +1 -1
  43. package/skills/subagent-driven-development/SKILL.md +24 -15
  44. package/skills/subagent-driven-development/implementer-prompt.md +6 -5
  45. package/skills/subagent-driven-development/re-review-prompt.md +4 -3
  46. package/skills/subagent-driven-development/scripts/review-package +23 -17
  47. package/skills/subagent-driven-development/scripts/review-package.ps1 +41 -27
  48. package/skills/subagent-driven-development/scripts/sdd-repo +44 -0
  49. package/skills/subagent-driven-development/scripts/sdd-repo.ps1 +74 -0
  50. package/skills/subagent-driven-development/scripts/sdd-workspace +20 -11
  51. package/skills/subagent-driven-development/scripts/sdd-workspace.ps1 +38 -27
  52. package/skills/subagent-driven-development/scripts/task-brief +74 -11
  53. package/skills/subagent-driven-development/scripts/task-brief.ps1 +89 -17
  54. package/skills/subagent-driven-development/task-reviewer-prompt.md +5 -6
  55. package/skills/systematic-debugging/SKILL.md +2 -2
  56. package/skills/writing-skills/render-graphs.js +4 -3
  57. package/skills/brainstorming/spec-document-reviewer-prompt.md +0 -50
  58. package/skills/systematic-debugging/CREATION-LOG.md +0 -119
  59. package/skills/systematic-debugging/test-academic.md +0 -14
  60. package/skills/systematic-debugging/test-pressure-1.md +0 -58
  61. package/skills/systematic-debugging/test-pressure-2.md +0 -68
  62. package/skills/systematic-debugging/test-pressure-3.md +0 -69
@@ -5,11 +5,12 @@ Use this template when dispatching an implementer subagent.
5
5
  ```
6
6
  Subagent (general-purpose):
7
7
  description: "Implement Task N: [task name]"
8
- model: [MODEL — REQUIRED: when the brief carries a Tier line, set from it:
9
- mechanical → the cheapest model the subagent tool offers; judgment →
10
- a standard mid-tier model. Otherwise choose per SKILL.md Model
11
- Selection. An omitted model silently inherits the session's most
12
- expensive one]
8
+ model: [MODEL]
9
+ # Model selection: when the brief carries a Tier line, set from it —
10
+ # mechanical → the cheapest model the subagent tool offers; judgment →
11
+ # a standard mid-tier model. Otherwise choose per SKILL.md Model
12
+ # Selection. An omitted model silently inherits the session's most
13
+ # expensive one.
13
14
  prompt: |
14
15
  You are implementing Task N: [task name]
15
16
 
@@ -10,8 +10,9 @@ that the fix itself broke nothing.
10
10
  ```
11
11
  Subagent (general-purpose):
12
12
  description: "Re-review Task N fix round R"
13
- model: [MODEL — REQUIRED: choose per SKILL.md Model Selection; an omitted
14
- model silently inherits the session's most expensive one]
13
+ model: [MODEL]
14
+ # Model selection: choose per SKILL.md Model Selection; an omitted model
15
+ # silently inherits the session's most expensive one.
15
16
  prompt: |
16
17
  You are re-reviewing one task's fix round. A previous review produced
17
18
  findings; an implementer has attempted to fix them. Your job is to
@@ -114,7 +115,7 @@ Subagent (general-purpose):
114
115
  review `…/task-N-review.md`); append this round's verdicts to it
115
116
  - `[FIX_BASE_SHA]` — the head the previous review saw
116
117
  - `[HEAD_SHA]` — current commit
117
- - `[DIFF_FILE]` — the path `bash scripts/review-package PLAN_FILE FIX_BASE HEAD` printed
118
+ - `[DIFF_FILE]` — the path printed by `bash scripts/review-package PLAN_FILE FIX_BASE HEAD`, run by its absolute path from the working tree being executed in
118
119
 
119
120
  **Re-reviewer returns:** per-finding verdicts (ADDRESSED / NOT ADDRESSED),
120
121
  new breakage in the fix diff, out-of-scope observations, and a round verdict —
@@ -4,13 +4,21 @@
4
4
  # call. Using the recorded per-task BASE (not HEAD~1) keeps multi-commit
5
5
  # tasks intact.
6
6
  #
7
- # Usage: review-package PLAN_FILE BASE HEAD [OUTFILE]
7
+ # Usage: review-package [-C DIR] PLAN_FILE BASE HEAD [OUTFILE]
8
8
  # Default OUTFILE: <repo-root>/.superpowers/sdd/<plan-basename>/review-<base7>..<head7>.diff
9
9
  # (named per range, so a re-review after fixes gets a distinct fresh file).
10
+ # -C DIR runs as if started there, as in sdd-workspace.
10
11
  set -euo pipefail
11
12
 
13
+ here=$(cd "$(dirname "$0")" && pwd)
14
+ if [ "${1:-}" = "-C" ]; then
15
+ [ -d "${2:-}" ] || { echo "bad -C directory: ${2:-}" >&2; exit 2; }
16
+ cd -- "$2"
17
+ shift 2
18
+ fi
19
+
12
20
  if [ $# -lt 3 ] || [ $# -gt 4 ]; then
13
- echo "usage: review-package PLAN_FILE BASE HEAD [OUTFILE]" >&2
21
+ echo "usage: review-package [-C DIR] PLAN_FILE BASE HEAD [OUTFILE]" >&2
14
22
  exit 2
15
23
  fi
16
24
 
@@ -19,23 +27,21 @@ base=$2
19
27
  head=$3
20
28
  [ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
21
29
 
22
- git rev-parse --git-dir >/dev/null 2>&1 || {
23
- echo "error: not a git repository — review-package needs the BASE and HEAD commits of the task under review." >&2
24
- echo "A greenfield plan's first task creates the repo itself: run this from inside the repo once that task has committed." >&2
25
- exit 2
26
- }
30
+ # The helper gives every SDD command the same fail-closed repository rule.
31
+ # Use bash explicitly because package extractors may strip executable bits.
32
+ repo=$("${BASH:-bash}" "$here/sdd-repo" --with-commit)
27
33
 
28
- git rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
29
- git rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&2; exit 2; }
34
+ git -C "$repo" rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
35
+ git -C "$repo" rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&2; exit 2; }
30
36
 
31
37
  # Range guards (exit 3): a wrong-branch HEAD yields a range that is empty or
32
38
  # not rooted at BASE; either would silently produce a bogus review package.
33
- git merge-base --is-ancestor "$base" "$head" || {
39
+ git -C "$repo" merge-base --is-ancestor "$base" "$head" || {
34
40
  echo "HEAD ($head) is not a descendant of BASE ($base)" >&2
35
41
  exit 3
36
42
  }
37
43
 
38
- if [ "$(git rev-list --count "${base}..${head}")" -eq 0 ]; then
44
+ if [ "$(git -C "$repo" rev-list --count "${base}..${head}")" -eq 0 ]; then
39
45
  echo "empty commit range: ${base}..${head}" >&2
40
46
  exit 3
41
47
  fi
@@ -45,22 +51,22 @@ if [ $# -eq 4 ]; then
45
51
  else
46
52
  # Invoke via bash rather than direct exec: some extractors (Python zipfile)
47
53
  # strip Unix exec bits when unpacking marketplace packages (#2040).
48
- dir=$("${BASH:-bash}" "$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
49
- out="$dir/review-$(git rev-parse --short "$base")..$(git rev-parse --short "$head").diff"
54
+ dir=$("${BASH:-bash}" "$here/sdd-workspace" "$plan")
55
+ out="$dir/review-$(git -C "$repo" rev-parse --short "$base")..$(git -C "$repo" rev-parse --short "$head").diff"
50
56
  fi
51
57
 
52
58
  {
53
59
  echo "# Review package: ${base}..${head}"
54
60
  echo
55
61
  echo "## Commits"
56
- git log --oneline "${base}..${head}"
62
+ git -C "$repo" log --oneline "${base}..${head}"
57
63
  echo
58
64
  echo "## Files changed"
59
- git diff --stat "${base}..${head}"
65
+ git -C "$repo" diff --stat "${base}..${head}"
60
66
  echo
61
67
  echo "## Diff"
62
- git diff -U10 "${base}..${head}"
68
+ git -C "$repo" diff -U10 "${base}..${head}"
63
69
  } > "$out"
64
70
 
65
- commits=$(git rev-list --count "${base}..${head}")
71
+ commits=$(git -C "$repo" rev-list --count "${base}..${head}")
66
72
  echo "wrote ${out}: ${commits} commit(s), $(wc -c < "$out" | tr -d ' ') bytes"
@@ -1,38 +1,48 @@
1
1
  #!/usr/bin/env pwsh
2
2
  # Generate a review package: commit list, stat summary, and net diff.
3
- # Usage: ./review-package.ps1 PLAN_FILE BASE HEAD [OUTFILE]
3
+ # Usage: ./review-package.ps1 [-C DIR] PLAN_FILE BASE HEAD [OUTFILE]
4
4
  # Default OUTFILE: <repo-root>/.superpowers/sdd/<plan-basename>/review-<base7>..<head7>.diff
5
5
 
6
6
  $ErrorActionPreference = "Stop"
7
+ $scriptArgs = @($args)
8
+ $workingDir = (Get-Location).Path
9
+ if ($scriptArgs.Count -gt 0 -and $scriptArgs[0] -eq "-C") {
10
+ if ($scriptArgs.Count -lt 2 -or -not (Test-Path -LiteralPath $scriptArgs[1] -PathType Container)) {
11
+ [Console]::Error.WriteLine("bad -C directory: $($scriptArgs[1])")
12
+ exit 2
13
+ }
14
+ $workingDir = (Resolve-Path -LiteralPath $scriptArgs[1]).Path
15
+ if ($scriptArgs.Count -gt 2) { $scriptArgs = @($scriptArgs[2..($scriptArgs.Count - 1)]) } else { $scriptArgs = @() }
16
+ }
7
17
 
8
- if ($args.Count -lt 3 -or $args.Count -gt 4) {
9
- [Console]::Error.WriteLine("usage: review-package.ps1 PLAN_FILE BASE HEAD [OUTFILE]")
18
+ if ($scriptArgs.Count -lt 3 -or $scriptArgs.Count -gt 4) {
19
+ [Console]::Error.WriteLine("usage: review-package.ps1 [-C DIR] PLAN_FILE BASE HEAD [OUTFILE]")
10
20
  exit 2
11
21
  }
12
22
 
13
- $plan = $args[0]
14
- $base = $args[1]
15
- $head = $args[2]
23
+ $planArg = $scriptArgs[0]
24
+ $plan = if ([System.IO.Path]::IsPathRooted($planArg)) { $planArg } else { Join-Path $workingDir $planArg }
25
+ $base = $scriptArgs[1]
26
+ $head = $scriptArgs[2]
16
27
 
17
28
  if (-not (Test-Path -LiteralPath $plan -PathType Leaf)) {
18
29
  [Console]::Error.WriteLine("no such plan file: $plan")
19
30
  exit 2
20
31
  }
21
32
 
22
- & git rev-parse --git-dir *> $null
23
- if ($LASTEXITCODE -ne 0) {
24
- [Console]::Error.WriteLine("error: not a git repository — review-package needs the BASE and HEAD commits of the task under review.")
25
- [Console]::Error.WriteLine("A greenfield plan's first task creates the repo itself: run this from inside the repo once that task has committed.")
26
- exit 2
27
- }
33
+ $scriptDir = Split-Path -Parent $PSCommandPath
34
+ $repoHelper = Join-Path $scriptDir "sdd-repo.ps1"
35
+ $repoOutput = @(& $repoHelper -C $workingDir "--with-commit")
36
+ if ($LASTEXITCODE -ne 0 -or $repoOutput.Count -eq 0) { exit 2 }
37
+ $repo = ([string]$repoOutput[0]).Trim()
28
38
 
29
- & git rev-parse --verify --quiet $base *> $null
39
+ & git -C $repo rev-parse --verify --quiet "$base" *> $null
30
40
  if ($LASTEXITCODE -ne 0) {
31
41
  [Console]::Error.WriteLine("bad BASE: $base")
32
42
  exit 2
33
43
  }
34
44
 
35
- & git rev-parse --verify --quiet $head *> $null
45
+ & git -C $repo rev-parse --verify --quiet "$head" *> $null
36
46
  if ($LASTEXITCODE -ne 0) {
37
47
  [Console]::Error.WriteLine("bad HEAD: $head")
38
48
  exit 2
@@ -40,25 +50,28 @@ if ($LASTEXITCODE -ne 0) {
40
50
 
41
51
  # Range guards (exit 3): a wrong-branch HEAD yields a range that is empty or
42
52
  # not rooted at BASE; either would silently produce a bogus review package.
43
- & git merge-base --is-ancestor $base $head *> $null
53
+ & git -C $repo merge-base --is-ancestor "$base" "$head" *> $null
44
54
  if ($LASTEXITCODE -ne 0) {
45
55
  [Console]::Error.WriteLine("HEAD ($head) is not a descendant of BASE ($base)")
46
56
  exit 3
47
57
  }
48
58
 
49
- $commitCount = (& git rev-list --count "${base}..${head}").Trim()
59
+ $commitCount = (& git -C $repo rev-list --count "${base}..${head}").Trim()
50
60
  if ([int]$commitCount -eq 0) {
51
61
  [Console]::Error.WriteLine("empty commit range: ${base}..${head}")
52
62
  exit 3
53
63
  }
54
64
 
55
- if ($args.Count -eq 4) {
56
- $out = $args[3]
65
+ if ($scriptArgs.Count -eq 4) {
66
+ $outArg = [string]$scriptArgs[3]
67
+ $out = if ([System.IO.Path]::IsPathRooted($outArg)) { $outArg } else { Join-Path $workingDir $outArg }
57
68
  } else {
58
- $scriptDir = Split-Path -Parent $PSCommandPath
59
- $dir = (& (Join-Path $scriptDir "sdd-workspace.ps1") $plan | Select-Object -First 1).Trim()
60
- $baseShort = (& git rev-parse --short $base).Trim()
61
- $headShort = (& git rev-parse --short $head).Trim()
69
+ $workspaceScript = Join-Path $scriptDir "sdd-workspace.ps1"
70
+ $workspaceOutput = @(& $workspaceScript -C $workingDir $plan)
71
+ if ($LASTEXITCODE -ne 0 -or $workspaceOutput.Count -eq 0) { exit 2 }
72
+ $dir = ([string]$workspaceOutput[0]).Trim()
73
+ $baseShort = (& git -C $repo rev-parse --short "$base").Trim()
74
+ $headShort = (& git -C $repo rev-parse --short "$head").Trim()
62
75
  $out = Join-Path $dir "review-$baseShort..$headShort.diff"
63
76
  }
64
77
 
@@ -66,15 +79,16 @@ $content = New-Object System.Collections.Generic.List[string]
66
79
  $content.Add("# Review package: ${base}..${head}")
67
80
  $content.Add("")
68
81
  $content.Add("## Commits")
69
- (& git log --oneline "${base}..${head}") | ForEach-Object { $content.Add($_) }
82
+ (& git -C $repo log --oneline "${base}..${head}") | ForEach-Object { $content.Add($_) }
70
83
  $content.Add("")
71
84
  $content.Add("## Files changed")
72
- (& git diff --stat "${base}..${head}") | ForEach-Object { $content.Add($_) }
85
+ (& git -C $repo diff --stat "${base}..${head}") | ForEach-Object { $content.Add($_) }
73
86
  $content.Add("")
74
87
  $content.Add("## Diff")
75
- (& git diff -U10 "${base}..${head}") | ForEach-Object { $content.Add($_) }
88
+ (& git -C $repo diff -U10 "${base}..${head}") | ForEach-Object { $content.Add($_) }
76
89
 
77
- Set-Content -LiteralPath $out -Value $content -Encoding utf8
78
- $commits = (& git rev-list --count "${base}..${head}").Trim()
90
+ $utf8NoBom = [System.Text.UTF8Encoding]::new($false)
91
+ [System.IO.File]::WriteAllLines($out, $content, $utf8NoBom)
92
+ $commits = (& git -C $repo rev-list --count "${base}..${head}").Trim()
79
93
  $bytes = (Get-Item -LiteralPath $out).Length
80
94
  Write-Output "wrote ${out}: $commits commit(s), $bytes bytes"
@@ -0,0 +1,44 @@
1
+ #!/usr/bin/env bash
2
+ # Print the top-level directory of the git working tree the SDD scripts use:
3
+ # the current directory's, exactly as git itself picks one. A caller that
4
+ # means a different working tree says so with the scripts' -C DIR, which they
5
+ # apply before calling this helper.
6
+ #
7
+ # The plan file's location never picks the repository. An executor working in
8
+ # a linked worktree may hold an absolute plan path in the main checkout; its
9
+ # workspace and commits still belong to the worktree it is executing in.
10
+ # Outside any working tree, stop rather than writing state into a plugin cache
11
+ # or another unrelated directory.
12
+ #
13
+ # --with-commit also requires HEAD to resolve, for callers that need a BASE or
14
+ # review range. Usage: sdd-repo [--with-commit]
15
+ set -euo pipefail
16
+
17
+ with_commit=false
18
+ if [ "${1:-}" = "--with-commit" ]; then
19
+ with_commit=true
20
+ shift
21
+ fi
22
+
23
+ if [ $# -ne 0 ]; then
24
+ echo "usage: sdd-repo [--with-commit]" >&2
25
+ exit 2
26
+ fi
27
+
28
+ if root=$(git rev-parse --show-toplevel 2>/dev/null); then
29
+ if [ "$with_commit" = false ] || git -C "$root" rev-parse --verify --quiet HEAD >/dev/null; then
30
+ printf '%s\n' "$root"
31
+ exit 0
32
+ fi
33
+ said=$(git -C "$root" rev-parse --verify HEAD 2>&1 >/dev/null) || true
34
+ else
35
+ said=$(git rev-parse --show-toplevel 2>&1 >/dev/null) || true
36
+ fi
37
+
38
+ if [ "$with_commit" = true ]; then
39
+ echo "SDD scripts that record BASE or review commits need a git working tree with at least one commit (current directory: $PWD). If this is a new project, run 'git init', make a first commit, then rerun." >&2
40
+ else
41
+ echo "SDD scripts must run from inside the git working tree you're executing in (current directory: $PWD). If this is a new project, run 'git init' first, then rerun." >&2
42
+ fi
43
+ echo "git said: ${said%%$'\n'*}" >&2
44
+ exit 2
@@ -0,0 +1,74 @@
1
+ #!/usr/bin/env pwsh
2
+ # Print the top-level directory of the git working tree used by the SDD
3
+ # scripts. The current directory chooses the repository, just as it does for
4
+ # git; callers may select another checkout with -C DIR.
5
+ # --with-commit also requires HEAD to resolve for commands that need a BASE.
6
+
7
+ $ErrorActionPreference = "Stop"
8
+ $scriptArgs = @($args)
9
+ $withCommit = $false
10
+ $workingDir = (Get-Location).Path
11
+ for ($i = 0; $i -lt $scriptArgs.Count; $i++) {
12
+ switch ($scriptArgs[$i]) {
13
+ "--with-commit" { $withCommit = $true }
14
+ "-C" {
15
+ $i++
16
+ if ($i -ge $scriptArgs.Count) {
17
+ [Console]::Error.WriteLine("usage: sdd-repo.ps1 [-C DIR] [--with-commit]")
18
+ exit 2
19
+ }
20
+ $candidate = $scriptArgs[$i]
21
+ if (-not (Test-Path -LiteralPath $candidate -PathType Container)) {
22
+ [Console]::Error.WriteLine("bad -C directory: $candidate")
23
+ exit 2
24
+ }
25
+ $workingDir = (Resolve-Path -LiteralPath $candidate).Path
26
+ }
27
+ default {
28
+ [Console]::Error.WriteLine("usage: sdd-repo.ps1 [-C DIR] [--with-commit]")
29
+ exit 2
30
+ }
31
+ }
32
+ }
33
+
34
+ $root = $null
35
+ $said = ""
36
+ try {
37
+ $output = @(& git -C $workingDir rev-parse --show-toplevel 2>&1)
38
+ $gitStatus = $LASTEXITCODE
39
+ if ($gitStatus -eq 0 -and $output.Count -gt 0) {
40
+ $candidateRoot = ([string]$output[0]).Trim()
41
+ if (-not [string]::IsNullOrWhiteSpace($candidateRoot)) { $root = $candidateRoot }
42
+ } else {
43
+ $said = if ($output.Count -gt 0) { ([string]$output[0]).Trim() } else { "git rev-parse --show-toplevel failed" }
44
+ }
45
+ } catch {
46
+ $said = $_.ToString()
47
+ }
48
+
49
+ if (-not [string]::IsNullOrWhiteSpace($root)) {
50
+ if (-not $withCommit) {
51
+ Write-Output $root
52
+ exit 0
53
+ }
54
+ try {
55
+ $headOutput = @(& git -C $root rev-parse --verify HEAD 2>&1)
56
+ $gitStatus = $LASTEXITCODE
57
+ if ($gitStatus -eq 0) {
58
+ Write-Output $root
59
+ exit 0
60
+ }
61
+ $said = if ($headOutput.Count -gt 0) { ([string]$headOutput[0]).Trim() } else { "git rev-parse --verify HEAD failed" }
62
+ } catch {
63
+ $said = $_.ToString()
64
+ }
65
+ }
66
+
67
+ if ([string]::IsNullOrWhiteSpace($said)) { $said = "git could not resolve the current working tree" }
68
+ if ($withCommit) {
69
+ [Console]::Error.WriteLine("SDD scripts that record BASE or review commits need a git working tree with at least one commit (current directory: $workingDir). If this is a new project, run 'git init', make a first commit, then rerun.")
70
+ } else {
71
+ [Console]::Error.WriteLine("SDD scripts must run from inside the git working tree you're executing in (current directory: $workingDir). If this is a new project, run 'git init' first, then rerun.")
72
+ }
73
+ [Console]::Error.WriteLine("git said: $said")
74
+ exit 2
@@ -27,15 +27,22 @@
27
27
  # Single source of truth for the workspace location, so task-brief and
28
28
  # review-package cannot drift to different directories.
29
29
  #
30
- # A greenfield plan's first task is often "create the repo", so there is no
31
- # repo root to resolve yet: fall back to the current directory rather than
32
- # failing, since that task is exactly the one needing a brief.
30
+ # The repository is the current directory's (see sdd-repo). -C DIR runs as
31
+ # if started there, so a caller can target another checkout without a compound
32
+ # `cd DIR ; ...` command.
33
33
  #
34
- # Usage: sdd-workspace PLAN_FILE
34
+ # Usage: sdd-workspace [-C DIR] PLAN_FILE
35
35
  set -euo pipefail
36
36
 
37
+ here=$(cd "$(dirname "$0")" && pwd)
38
+ if [ "${1:-}" = "-C" ]; then
39
+ [ -d "${2:-}" ] || { echo "bad -C directory: ${2:-}" >&2; exit 2; }
40
+ cd -- "$2"
41
+ shift 2
42
+ fi
43
+
37
44
  if [ $# -ne 1 ]; then
38
- echo "usage: sdd-workspace PLAN_FILE" >&2
45
+ echo "usage: sdd-workspace [-C DIR] PLAN_FILE" >&2
39
46
  exit 2
40
47
  fi
41
48
 
@@ -46,10 +53,9 @@ slug=$(basename -- "$plan" .md)
46
53
  [ -n "$slug" ] && [ "$slug" != "." ] && [ "$slug" != ".." ] \
47
54
  || { echo "cannot derive a workspace name from: $plan" >&2; exit 2; }
48
55
 
49
- if ! root=$(git rev-parse --show-toplevel 2>/dev/null); then
50
- root=$PWD
51
- echo "sdd-workspace: no git repository yet, using $root/.superpowers/sdd until this plan's first task creates one" >&2
52
- fi
56
+ # Invoke through bash rather than direct exec: package extractors may strip
57
+ # executable bits, and these scripts must still find the same repository.
58
+ root=$("${BASH:-bash}" "$here/sdd-repo")
53
59
  root=$(CDPATH='' cd -- "$root" && pwd -P)
54
60
  base="$root/.superpowers/sdd"
55
61
 
@@ -86,5 +92,8 @@ if ! owns "$dir"; then
86
92
  fi
87
93
  fi
88
94
 
89
- printf '*\n' > "$base/.gitignore"
90
- CDPATH='' cd -- "$dir" && pwd
95
+ # Create-only: a repo may commit its own .gitignore here (e.g. to version
96
+ # progress.md ledgers); overwriting it would revert that on every run.
97
+ [ -e "$base/.gitignore" ] || printf '*\n' > "$base/.gitignore"
98
+ CDPATH='' cd -- "$dir"
99
+ if command -v cygpath >/dev/null 2>&1; then cygpath -m "$PWD"; else pwd; fi
@@ -17,22 +17,32 @@
17
17
  # legacy workspace adopts instead of detecting; acceptable, marker-less
18
18
  # workspaces age out as plans finish.
19
19
  #
20
- # A greenfield plan's first task is often "create the repo", so there is no
21
- # repo root to resolve yet: fall back to the current directory rather than
22
- # failing, since that task is exactly the one needing a brief.
23
- #
24
- # Usage: ./sdd-workspace.ps1 PLAN_FILE
20
+ # The repository is the current directory's (see sdd-repo.ps1). -C DIR runs
21
+ # as if started there, allowing another checkout to be selected without a
22
+ # compound `cd DIR ; ...` command.
23
+ # Usage: ./sdd-workspace.ps1 [-C DIR] PLAN_FILE
25
24
 
26
25
  $ErrorActionPreference = "Stop"
26
+ $scriptArgs = @($args)
27
+ $workingDir = (Get-Location).Path
28
+ if ($scriptArgs.Count -gt 0 -and $scriptArgs[0] -eq "-C") {
29
+ if ($scriptArgs.Count -lt 2 -or -not (Test-Path -LiteralPath $scriptArgs[1] -PathType Container)) {
30
+ [Console]::Error.WriteLine("bad -C directory: $($scriptArgs[1])")
31
+ exit 2
32
+ }
33
+ $workingDir = (Resolve-Path -LiteralPath $scriptArgs[1]).Path
34
+ if ($scriptArgs.Count -gt 2) { $scriptArgs = @($scriptArgs[2..($scriptArgs.Count - 1)]) } else { $scriptArgs = @() }
35
+ }
27
36
 
28
- if ($args.Count -ne 1) {
29
- [Console]::Error.WriteLine("usage: sdd-workspace.ps1 PLAN_FILE")
37
+ if ($scriptArgs.Count -ne 1) {
38
+ [Console]::Error.WriteLine("usage: sdd-workspace.ps1 [-C DIR] PLAN_FILE")
30
39
  exit 2
31
40
  }
32
41
 
33
- $plan = $args[0]
42
+ $planArg = $scriptArgs[0]
43
+ $plan = if ([System.IO.Path]::IsPathRooted($planArg)) { $planArg } else { Join-Path $workingDir $planArg }
34
44
  if (-not (Test-Path -LiteralPath $plan -PathType Leaf)) {
35
- [Console]::Error.WriteLine("no such plan file: $plan")
45
+ [Console]::Error.WriteLine("no such plan file: $planArg")
36
46
  exit 2
37
47
  }
38
48
 
@@ -42,21 +52,12 @@ if ([string]::IsNullOrEmpty($slug) -or $slug -eq "." -or $slug -eq "..") {
42
52
  exit 2
43
53
  }
44
54
 
45
- $root = $null
46
- try {
47
- # Collect all output without an early-terminating pipeline: a
48
- # Select-Object -First teardown can leave $LASTEXITCODE stale.
49
- $rootOutput = @(& git rev-parse --show-toplevel 2>$null)
50
- if ($LASTEXITCODE -eq 0 -and $rootOutput.Count -gt 0 -and -not [string]::IsNullOrWhiteSpace($rootOutput[0])) {
51
- $root = ([string]$rootOutput[0]).Trim()
52
- }
53
- } catch {
54
- $root = $null
55
- }
56
- if ([string]::IsNullOrWhiteSpace($root)) {
57
- $root = (Get-Location).Path
58
- [Console]::Error.WriteLine("sdd-workspace.ps1: no git repository yet, using $root/.superpowers/sdd until this plan's first task creates one")
59
- }
55
+ $scriptDir = Split-Path -Parent $PSCommandPath
56
+ $repoHelper = Join-Path $scriptDir "sdd-repo.ps1"
57
+ $rootOutput = @(& $repoHelper -C $workingDir)
58
+ $repoStatus = $LASTEXITCODE
59
+ if ($repoStatus -ne 0 -or $rootOutput.Count -eq 0) { exit 2 }
60
+ $root = ([string]$rootOutput[0]).Trim()
60
61
 
61
62
  function Get-PhysicalDirectoryPath($path) {
62
63
  if (-not (Test-Path -LiteralPath $path)) { return $path }
@@ -82,7 +83,7 @@ function Get-PhysicalDirectoryPath($path) {
82
83
  # repo-relative when the plan lives under the repo root, absolute otherwise.
83
84
  $planLeaf = Split-Path -Leaf $plan
84
85
  $planParent = Split-Path -Parent $plan
85
- if ([string]::IsNullOrEmpty($planParent)) { $planParent = "." }
86
+ if ([string]::IsNullOrEmpty($planParent)) { $planParent = $workingDir }
86
87
 
87
88
  $planDir = Get-PhysicalDirectoryPath $planParent
88
89
  $rootPhys = Get-PhysicalDirectoryPath $root
@@ -129,5 +130,15 @@ if (-not (Test-And-Claim-Workspace $dir $planId)) {
129
130
  }
130
131
  }
131
132
 
132
- Set-Content -LiteralPath (Join-Path $base ".gitignore") -Value "*" -NoNewline -Encoding ascii
133
- (Resolve-Path -LiteralPath $dir).Path
133
+ # Create-only: a repo may commit its own .gitignore here (e.g. to version
134
+ # progress.md ledgers); overwriting it would revert that on every run.
135
+ if (-not (Test-Path -LiteralPath (Join-Path $base ".gitignore"))) {
136
+ Set-Content -LiteralPath (Join-Path $base ".gitignore") -Value "*" -NoNewline -Encoding ascii
137
+ }
138
+ $printedPath = (Resolve-Path -LiteralPath $dir).Path
139
+ $cygpath = Get-Command cygpath -ErrorAction SilentlyContinue
140
+ if ($cygpath) {
141
+ $nativePath = & $cygpath.Source -m $printedPath
142
+ if ($LASTEXITCODE -eq 0 -and -not [string]::IsNullOrWhiteSpace($nativePath)) { $printedPath = ([string]$nativePath).Trim() }
143
+ }
144
+ Write-Output $printedPath
@@ -3,19 +3,30 @@
3
3
  # implementer reads in one call, so the task text never has to be pasted
4
4
  # through the controller's context.
5
5
  #
6
- # Usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE]
7
- # Default OUTFILE: <repo-root>/.superpowers/sdd/<plan-basename>/task-<N>-brief.md
6
+ # Usage: task-brief [-C DIR] PLAN_FILE TASK_ID [OUTFILE]
7
+ # Default OUTFILE: <repo-root>/.superpowers/sdd/<plan-basename>/task-<ID>-brief.md
8
8
  # (per plan and per worktree; concurrent runs of the SAME plan in the same
9
- # working tree share it).
9
+ # working tree share it). -C DIR runs as if started in DIR, as in sdd-workspace.
10
10
  set -euo pipefail
11
11
 
12
+ here=$(cd "$(dirname "$0")" && pwd)
13
+ if [ "${1:-}" = "-C" ]; then
14
+ [ -d "${2:-}" ] || { echo "bad -C directory: ${2:-}" >&2; exit 2; }
15
+ cd -- "$2"
16
+ shift 2
17
+ fi
18
+
12
19
  if [ $# -lt 2 ] || [ $# -gt 3 ]; then
13
- echo "usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE]" >&2
20
+ echo "usage: task-brief [-C DIR] PLAN_FILE TASK_ID [OUTFILE]" >&2
14
21
  exit 2
15
22
  fi
16
23
 
17
24
  plan=$1
18
25
  n=$2
26
+ if ! [[ "$n" =~ ^[A-Za-z0-9]+(\.[A-Za-z0-9]+)*$ && "$n" =~ [0-9] ]]; then
27
+ echo "usage: task-brief [-C DIR] PLAN_FILE TASK_ID [OUTFILE]" >&2
28
+ exit 2
29
+ fi
19
30
  [ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
20
31
 
21
32
  if [ $# -eq 3 ]; then
@@ -23,17 +34,69 @@ if [ $# -eq 3 ]; then
23
34
  else
24
35
  # Invoke via bash rather than direct exec: some extractors (Python zipfile)
25
36
  # strip Unix exec bits when unpacking marketplace packages (#2040).
26
- dir=$("${BASH:-bash}" "$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
37
+ dir=$("${BASH:-bash}" "$here/sdd-workspace" "$plan")
27
38
  out="$dir/task-${n}-brief.md"
28
39
  fi
29
40
 
30
- awk -v n="$n" '
31
- /^```/ { infence = !infence }
32
- !infence && /^#+[ \t]+Task[ \t]+[0-9]+/ {
33
- intask = ($0 ~ ("^#+[ \t]+Task[ \t]+" n "([^0-9]|$)"))
41
+ # A task heading is `Task` followed by an ID: letters and digits, optionally
42
+ # dot-separated, containing at least one digit (3, 6b, A1, 2.1). The digit
43
+ # keeps headings like "## Task Overview" or "#### Task notes" from becoming
44
+ # task boundaries. The ID is compared as a whole string, so Task 6 never
45
+ # matches Task 6b and Task 1 never matches Task 1.1. A deeper Task heading
46
+ # whose ID extends the requested one with a letter or dot is a sub-task and
47
+ # stays in its brief (### Task 7 keeps #### Task 7a). Depth alone is not
48
+ # enough: plans can drift from "## Task 1" to "### Task 2".
49
+ #
50
+ # The heading word remains the English literal "Task", whatever language the
51
+ # rest of the plan uses. If no Task headings exist, list headings shaped like
52
+ # tasks before the not-found error instead of implying the plan has no tasks.
53
+ #
54
+ # A fence that never closes can hide later task headings, making a brief
55
+ # silently include several tasks. Refuse such an incomplete brief (exit 4).
56
+ # A stray open fence that hides no Task heading does not change the brief, so
57
+ # it is allowed with a warning. The plan path goes through ENVIRON rather than
58
+ # awk -v, which would mangle backslashes in a Windows path.
59
+ rc=0
60
+ TASK_BRIEF_PLAN="$plan" awk -v n="$n" '
61
+ /^```/ { infence = !infence; if (infence) { fence_line = NR; hidden = 0 } }
62
+ infence && /^#+[ \t]+Task[ \t]/ { hidden = 1 }
63
+ !infence && /^#+[ \t]+Task[ \t]/ {
64
+ id = $0
65
+ sub(/^#+[ \t]+Task[ \t]+/, "", id)
66
+ if (match(id, /^[A-Za-z0-9]+(\.[A-Za-z0-9]+)*/) && substr(id, 1, RLENGTH) ~ /[0-9]/) {
67
+ tasks++
68
+ id = substr(id, 1, RLENGTH)
69
+ match($0, /^#+/)
70
+ subtask = intask && RLENGTH > level && substr(id, 1, length(n)) == n \
71
+ && substr(id, length(n) + 1, 1) ~ /[A-Za-z.]/
72
+ if (!subtask) {
73
+ intask = (id == n)
74
+ level = RLENGTH
75
+ }
76
+ }
34
77
  }
35
- intask { print }
36
- ' "$plan" > "$out"
78
+ !infence && /^#+[ \t]+[^ \t]+[ \t]+[A-Za-z0-9.]*[0-9]/ && shaped < 5 { shaped_heading[++shaped] = $0 }
79
+ intask { print; found = 1 }
80
+ END {
81
+ where = "the code fence opened at line " fence_line " of " ENVIRON["TASK_BRIEF_PLAN"] " never closes"
82
+ if (infence && hidden && (intask || !found)) {
83
+ print "task-brief: " where ", so no Task heading after it can be seen; close that fence in the plan and rerun" | "cat >&2"
84
+ exit 4
85
+ } else if (infence && intask) {
86
+ print "task-brief: warning: " where "; it hides no Task heading, so this brief is complete" | "cat >&2"
87
+ }
88
+ # An open fence that hid Task headings already explains why none were
89
+ # seen; the English-word hint would contradict it.
90
+ if (!tasks && shaped && !(infence && hidden)) {
91
+ 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"
92
+ for (i = 1; i <= shaped; i++) print " " shaped_heading[i] | "cat >&2"
93
+ }
94
+ }
95
+ ' "$plan" > "$out" || rc=$?
96
+ if [ "$rc" -ne 0 ]; then
97
+ if [ -f "$out" ]; then rm -f "$out"; fi
98
+ exit "$rc"
99
+ fi
37
100
 
38
101
  if [ ! -s "$out" ]; then
39
102
  echo "task ${n} not found in ${plan} (no heading matching 'Task ${n}')" >&2