Repository navigation
feat(sdd): bind nested instruction files and enclosing-function context in reviews - #2
Merged
Merged
Conversation
…ckages Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
review-package, task-brief, and snapshot exec it directly; mode 100644 made them fail with "Permission denied" in a fresh checkout. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
Prints every AGENTS.md / CLAUDE.md from the repo root down to each given path's directory, with line numbers and byte-identical files deduped, from the working tree or a given tree-ish. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
Reviewer and implementer templates treat the package's or brief's AGENTS.md / CLAUDE.md files as binding (violations Important, cited as path:line) and check new state, effects, and resources against the unchanged code that encloses them. requesting-code-review builds a review package before dispatch. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
…ctions Packages now carry the AGENTS.md / CLAUDE.md files governing the changed files (read from the HEAD tree-ish) and widen each hunk to its enclosing function via git diff --function-context. A file over SDD_CONTEXT_CAP lines (default 400) falls back to -U10 and is marked. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
- review-package: --no-color/--no-ext-diff and fixed prefixes on every diff, guard against an empty Diff, stream per-file chunks to temp files (was quadratic), take capped paths from name-only output, build the range once. - instruction-files: resolve symlinked entries in tree mode, reject unknown flags, exit 2 outside a repo. - task-brief: ignore fenced Files blocks; end the block at the first blank line after its list. - snapshot: seed the temp index from the real index so file modes survive core.fileMode=false. - Templates: refactor reviewer leaves rule violations to the correctness reviewer; missing-package fallbacks use function context and read the instruction files. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
- instruction-files accepts -- as end of options; task-brief and review-package pass it, so a Files token starting with - is a path. - instruction-files refuses symlinks that resolve outside the repository. - review-package pairs chunks with --name-status so typechanges stay aligned; diffs use --submodule=short and --no-relative. - task-brief keeps wrapped Files items in the block and uses one fence rule for both passes. - Tests share repo/commit/exit helpers. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
…cape - Replace --no-relative with -c diff.relative=false (older git has no relative mode and rejects the flag). - instruction-files resolves link directories physically (cd -P), so a directory symlink plus a ../ target cannot escape the repository check. - Portable newline escaping for path labels; one symlink hop limit. - Tests grouped by script; task-brief header rewrapped. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
Callers read the output path directly instead of parsing the human "wrote <path>: ..." line. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
There was a problem hiding this comment.
🟡 Changes recommended
A critical symlink-validation flaw can include out-of-repository file contents in task briefs, while rename and newline-path handling can omit governing instructions.
3 open issues
What changed in this PR
This PR strengthens the fork’s subagent review workflow by supplying governing instruction files and enclosing-function context, helping agents assess changes against both repository rules and unchanged code.
Changes:
- Add instruction-file collection to review packages and task briefs, plus capped function-level diff context.
- Update reviewer and implementer guidance to use these inputs and check surrounding code.
- Add script tests to CI, correct snapshot file-mode handling, and bump release manifests to
6.0.4-fork.11.
| File | Description |
|---|---|
tests/claude-code/test-sdd-review-context.sh |
Adds coverage for instruction collection, context, paths, and snapshots. |
skills/subagent-driven-development/task-reviewer-prompt.md |
Requires governing rules and enclosing-code checks. |
skills/subagent-driven-development/SKILL.md |
Documents richer packages and task briefs. |
skills/subagent-driven-development/scripts/task-brief |
Appends governing instructions and adds path-only output. |
skills/subagent-driven-development/scripts/snapshot |
Seeds snapshots from the real index to preserve modes. |
skills/subagent-driven-development/scripts/sdd-workspace |
Makes the workspace helper executable. |
skills/subagent-driven-development/scripts/review-package |
Adds instruction files, capped function context, and path-only output. |
skills/subagent-driven-development/scripts/instruction-files |
Collects and deduplicates governing instruction files. |
skills/subagent-driven-development/refactor-reviewer-prompt.md |
Adds instruction constraints and surrounding-code checks. |
skills/subagent-driven-development/implementer-prompt.md |
Adds instruction citations and enclosing-code self-review. |
skills/requesting-code-review/SKILL.md |
Adds package generation before reviewer dispatch. |
skills/requesting-code-review/code-reviewer.md |
Integrates review packages and binding instructions. |
package.json |
Bumps the package version. |
gemini-extension.json |
Bumps the Gemini extension version. |
docs/superpowers/specs/2026-11-02-review-enclosing-context-design.md |
Records the design and acceptance criteria. |
docs/superpowers/plans/2026-11-02-review-enclosing-context.md |
Records implementation and verification steps. |
AGENTS.md |
Documents the fork’s expanded review context. |
.kimi-plugin/plugin.json |
Bumps the Kimi plugin version. |
.github/workflows/release-checks.yml |
Runs both SDD script test suites in CI. |
.cursor-plugin/plugin.json |
Bumps the Cursor plugin version. |
.codex-plugin/plugin.json |
Bumps the Codex plugin version. |
.claude-plugin/plugin.json |
Bumps the Claude plugin version. |
.claude-plugin/marketplace.json |
Synchronizes the marketplace version. |
Review effort: Balanced
| while [ -L "$p" ]; do | ||
| [ "$hops" -lt "$max_hops" ] || return 1 | ||
| hops=$((hops + 1)) | ||
| t=$(readlink -- "$p") |
| d=$(dirname -- "$p") | ||
| [ "$d" = . ] && continue | ||
| acc="" | ||
| IFS=/ read -r -a parts <<< "$d" |
Comment on lines
+104
to
+117
| changed=() | ||
| nl=$'\n' | ||
| esc='\n' | ||
| : > "$tmp/names" | ||
| while IFS= read -r -d '' status; do | ||
| IFS= read -r -d '' f | ||
| case $status in R*|C*) IFS= read -r -d '' f ;; esac | ||
| changed+=("$f") | ||
| shown=${f//$nl/$esc} | ||
| printf '%s\n' "$shown" >> "$tmp/names" | ||
| case $status in T*) printf '%s\n' "$shown" >> "$tmp/names" ;; esac | ||
| done < <("${gitdiff[@]}" --name-status -z "${range[@]}") | ||
|
|
||
| "$scripts/instruction-files" --tree "$head" -- ${changed[@]+"${changed[@]}"} > "$tmp/instr" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.


Who is submitting this PR? (required)
claude-opus-5-5) as controller; Sonnet implementers; Opus final reviewersWhat problem are you trying to solve?
Review and implementer subagents look at diff hunks, not at the code the hunks land in. On a downstream project, two bugs got past eight reviewer passes, and an external bot caught both:
<subdir>/AGENTS.md. No brief or reviewer read it.Both bugs come from new code meeting unchanged code.
What does this PR change?
scripts/instruction-fileshelper gathers every AGENTS.md / CLAUDE.md from the repo root down to each file's directory.review-packageandtask-briefinline those files with line numbers.review-packagewidens each hunk to its enclosing function (git diff --function-context). A file overSDD_CONTEXT_CAPlines falls back to-U10and is marked.Is this change appropriate for the core library?
Yes. Nothing here is specific to a stack: the change has no framework, language or product wording, uses only bash 3.2 and POSIX awk, and relies on git's own funcname rules or the repo's
.gitattributesdiff drivers.What alternatives did you consider?
--function-contextplus a per-file cap.wrote <path>:line: replaced with--print-path.Does this PR contain multiple unrelated changes?
The PR contains a few side changes. All of them came up in this work:
sdd-workspaceexec bit (100644 → 100755): without it, the repo's own scripts fail on a fresh checkout. The new CI step exposed this.scripts/snapshotindex seeding: undercore.fileMode=false, review packages showed mode changes that were not real.--print-path: chosen during branch-finish triage of a refactor finding.Existing PRs
Environment tested
New harness support (required if this PR adds a new harness)
Not applicable: no new harness.
Evaluation
review-package: Tasks 2 and 3, and every final review.tests/claude-code/test-sdd-review-context.sh(new) andtest-sdd-workspace.shpass locally, and CI now runs both.Rigor
superpowers-custom:writing-skillsand completed adversarial pressure testing (paste results below) — not done; template edits are additiveHuman review
🤖 Generated with Claude Code
https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8