chore(claude): retire pair-flow remnants superseded by planwright - #33
Merged
Conversation
planwright now ships the spec-driven pipeline as a plugin, so remove the local pieces it supersedes: - delete scripts/spec-validate.sh (planwright ships its own validator) - trim scripts/skill-contracts.sh to the surviving review commands (panel-*, peer-review); the migrated pipeline skills moved to planwright - drop the dead stale-lock-threshold from pair-flow.yml (planwright owns the orchestrator lock now) - reframe the Spec-Driven Autonomy Pipeline section of CLAUDE.md to point at the planwright plugin and its overlay/doctrine model - move the deferred orchestrate-retirement task to Completed in specs/pair-flow/tasks.md (gate fired: planwright merged + proven) pair-flow-config.sh (repo-class), pair-flow.yml (panel-backends), the inbox substrate, and the panel-*/peer-review/copilot-*/code-review commands stay; planwright has no equivalent.
- pair-flow.yml: reword so the osx.yml pointer attaches to the planwright plugin install, not to config-get.sh (which osx.yml does not reference) - CLAUDE.md: rewrite the /polish bullet to planwright's actual loop (drains all action buckets on-branch, no dotfiles repo-class gating), resolving the contradiction with the Autonomy-gate paragraph - specs/README.md: the pair-flow index row no longer claims it 'defines' the pipeline skills (they moved to the planwright plugin in #30) specs/pair-flow/{design,tasks,kickoff} stale refs left intact: that bundle is preserved as origin spec + history.
scripts/inbox-*.sh pointed at repo root (where MCP sync scripts live); the inbox/heartbeat scripts actually live under roles/osx/files/claude/scripts/. Matches the tracked-source convention this doc already uses for worktree-bootstrap.sh.
There was a problem hiding this comment.
Pull request overview
This PR retires remaining local “pair-flow” pipeline remnants that have been superseded by the planwright Claude Code plugin, while keeping the dotfiles-local review and inbox surfaces.
Changes:
- Remove the local spec validator and the obsolete
stale-lock-thresholdconfig. - Trim the local contract checker to focus on surviving dotfiles-local review commands.
- Update specs and CLAUDE documentation to reflect planwright as the source of the pipeline skills and validator.
Lens Check (exhaustive)
- Correctness and logic bugs: 1 finding,
skill-contracts.shno longer checkspanel-review.mddespite claiming to coverpanel-*. - Security and secret handling: none, only docs and local scripts, no secret surfaces changed.
- Error handling and failure modes: none, no new failure paths introduced.
- Edge cases: none, changes are deletions and doc reframes.
- Idempotency: none, no Ansible task behavior changed here.
- Naming, readability, and code structure: 1 nit, terminology drift (“skills” vs “commands”) in
skill-contracts.shheader. - Documentation: 2 findings, incorrect file paths and stale config key mentioned in
specs/pair-flow/tasks.md. - Tests / verification: none, no new behavior added, existing pre-commit contract guard is the relevant check.
- Cross-file consistency: covered by the documentation findings above (config key removed but still described as present).
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
specs/README.md |
Reframes the pair-flow/ spec as origin/history and points pipeline skills to planwright. |
specs/pair-flow/tasks.md |
Moves orchestrate retirement to Completed and updates narrative for planwright ownership. |
specs/_observations/opportunities.md |
Adds a tooling-hardening observation (shellcheck absence). |
roles/osx/files/claude/scripts/spec-validate.sh |
Deletes the local spec validator (planwright owns validation now). |
roles/osx/files/claude/scripts/skill-contracts.sh |
Trims contract checks to remaining dotfiles-local review commands. |
roles/osx/files/claude/pair-flow.yml |
Removes stale-lock threshold and reframes file scope to review and inbox surfaces. |
roles/osx/files/CLAUDE.md |
Updates workflow and pipeline docs to reflect planwright plugin and remaining dotfiles-local pieces. |
…iew in skill-contracts
inkatze
marked this pull request as ready for review
June 25, 2026 18:59
inkatze
added a commit
that referenced
this pull request
Jul 13, 2026
- skill-contracts.sh: the three-bucket check was decorative in 2 of 3 files it's supposed to guard. Reproduced directly: mutating panel-pairing.md/peer-review.md back to "four buckets" still passed, because an unrelated "three-pass"/"three tables" sentence elsewhere in the same file independently satisfied the shared alternation regex. Same failure mode the v1-retrospective already documented once for this exact checker. Rewritten to anchor on each file's own specific declarative sentence plus an explicit Agent-resolvable absence guard, using if-blocks instead of a set -e-unsafe `cond && ! grep && err` chain (which silently exited the script on the passing case during my own validation of the fix). - decouple-review-tooling.md: fixed a status line that claimed "resolved" while the body still narrated the deleted files in present tense, and a numbering reference that didn't map to the doc's actual numbered lists. - tasks.md: fixed a citation typo (D-9.1, which doesn't exist as a design decision, for REQ-D9.1) and an incomplete REQ-C1.x list (missing C1.1/C1.3) in the retirement bullet I added. - opportunities.md: fixed a misattributed quote (the "convergence layer" phrase is decouple-review-tooling.md's, not obs #3's) and an overstated claim that obs #3's "commands not skills" point is still open (it was already resolved in PR #33, before this branch). Declined with rationale: test-spec.md's and scheduled-runner.md's stale references to pair-flow-config.sh were left untouched, matching the verified precedent that the /orchestrate retirement also left these two files alone despite equivalent staleness at the time.
inkatze
added a commit
that referenced
this pull request
Jul 14, 2026
…, repo-class) (#35) * chore(tmux,claude): remove cross-session inbox substrate + tmux dashboard The tmux status-bar segment and prefix+i popup didn't pan out, so the whole substrate comes out rather than leaving the write-side hooks running with no reader: the six inbox-*.sh scripts, the tmux-side status wrapper, settings.json hook wiring, the inbox Ansible task, and pair-flow.yml's heartbeat-interval config. notify-event.sh (macOS notifications) is untouched since it's called independently. * chore(claude): retire notify-event.sh (Stop/permission/idle noise) Became noise, so it goes the same way as the inbox substrate: script deleted, hooks.Stop/hooks.Notification set to [] in settings.json. The tnotify-send/tnotify-watch fish infra stays; it's generic terminal- notification plumbing also used directly by worktree-bootstrap.sh. * chore(claude): retire repo-class / pair-flow-config.sh and the Agent-resolvable bucket repo-class (solo vs multi-reviewer) existed to gate whether Agent-resolvable findings could auto-apply without asking. Walking every consumer showed none of them actually varies safe behavior on it: /panel-pairing, /peer-review, and planwright's /polish all already draft a PR and never mark it ready without human sign-off regardless of repo-class, and /peer-review's "solo" branch was vacuous (it only runs when a peer already reviewed). Deletes pair-flow-config.sh, pair-flow.yml, and their Ansible task; collapses Finding Categorization from four buckets back to three (Auto-applicable / Needs sign-off / Needs human judgment) across CLAUDE.md, panel-review.md, panel-pairing.md, peer-review.md, code-review.md, and skill-contracts.sh. panel-backends now resolves from the profile-table default that already existed as a fallback, no config file needed. * fix(claude): self-review findings on the repo-class retirement branch - skill-contracts.sh: the three-bucket check was decorative in 2 of 3 files it's supposed to guard. Reproduced directly: mutating panel-pairing.md/peer-review.md back to "four buckets" still passed, because an unrelated "three-pass"/"three tables" sentence elsewhere in the same file independently satisfied the shared alternation regex. Same failure mode the v1-retrospective already documented once for this exact checker. Rewritten to anchor on each file's own specific declarative sentence plus an explicit Agent-resolvable absence guard, using if-blocks instead of a set -e-unsafe `cond && ! grep && err` chain (which silently exited the script on the passing case during my own validation of the fix). - decouple-review-tooling.md: fixed a status line that claimed "resolved" while the body still narrated the deleted files in present tense, and a numbering reference that didn't map to the doc's actual numbered lists. - tasks.md: fixed a citation typo (D-9.1, which doesn't exist as a design decision, for REQ-D9.1) and an incomplete REQ-C1.x list (missing C1.1/C1.3) in the retirement bullet I added. - opportunities.md: fixed a misattributed quote (the "convergence layer" phrase is decouple-review-tooling.md's, not obs #3's) and an overstated claim that obs #3's "commands not skills" point is still open (it was already resolved in PR #33, before this branch). Declined with rationale: test-spec.md's and scheduled-runner.md's stale references to pair-flow-config.sh were left untouched, matching the verified precedent that the /orchestrate retirement also left these two files alone despite equivalent staleness at the time. * chore(osx): clean up orphaned pair-flow.yml symlink and inbox dir Two hard-disqualifier-zone findings from the self-review pass (delete ops reaching other hosts), reviewed and approved in conversation rather than deferred to the PR checklist. Any host that ran the pre-retirement osx.yml has a dangling ~/.claude/pair-flow.yml symlink (target deleted) and an orphaned ~/.claude/inbox/ directory (inbox-sweep.sh, the only thing that ever cleaned it, is also deleted). Both are state: absent, safe no-ops on a fresh machine. Verified against fixtures: removes an existing dangling symlink + populated directory, and is idempotent when already absent. * fix(claude): panel-pairing findings, reviewed and approved /panel-pairing iteration 1 (backend: codex) surfaced 2 real findings that lacked a tool citation, so they routed to Needs sign-off rather than Auto-applicable per the skill's own rule; both approved in conversation rather than left on the checklist. - tasks.md / decouple-review-tooling.md overclaimed that pair-flow.local.yml "was removed" -- it wasn't. It's untracked and was never Ansible-managed (a pre-existing, deliberate policy); I only manually deleted it on this one machine earlier. Reworded to say it's orphaned wherever it existed, not deleted. - skill-contracts.sh's new bucket_files/bucket_phrases parallel arrays had no length-parity guard. Confirmed a mismatch already fails loudly under set -u (not silent), but with an unhelpful "unbound variable" instead of a clear diagnostic. Added an explicit check; validated against real files (still passes) and a simulated mismatch (now fails with a specific message). Two other codex findings were declined after validation: the settings.json Stop/Notification "[]" wipe concern doesn't apply (no other writer touches those hook categories, and "[]" to remove a hook is this repo's own documented convention); codex's "correction" to my set -e comment is itself incomplete (doesn't hold for the exact function-wrapped case the comment was describing, re-confirmed empirically). * chore(claude): address copilot-pairing thread on CLAUDE.md:171 Copilot flagged that /copilot-pairing was listed among skills that "categorize each finding into one of three buckets and present them as separate tables," but copilot-pairing.md never references the bucket taxonomy anywhere -- confirmed via direct grep, both on this branch and on origin/main (pre-existing since before this PR, but the sentence itself is already in this diff's touched lines, so in scope). It has its own classification scheme entirely (valid / already-handled / false positive / adjacent finding). Removed it from the list; kept /copilot-review's adjacent-findings output, which does genuinely use the three-bucket tables (confirmed in copilot-review.md). * chore(claude): fix v1-retrospective citation path in skill-contracts.sh Copilot flagged that the comment I added cites research/v1-retrospective.md:89, which doesn't resolve from repo root (lefthook's cwd). Every other reference to this file in the repo uses the full path specs/pair-flow/research/v1-retrospective.md; mine was the only outlier. Fixed to match. * chore(specs): fix stale tasks.md header (Last reviewed date, private wording) Copilot flagged this via /copilot-pairing on PR #35, twice in a row (loop detection fired on the second occurrence since I'd already replied "tracking elsewhere" to the first). Pulling it into scope per explicit direction rather than continuing to loop against an already correct dismissal. Bumped Last reviewed to today; planwright went public 2026-06-23 per the already-open opportunities.md entry this also closes out. Left tasks.md:55's Deferred-section "private" mention alone -- not flagged by Copilot, describes a historical fact, out of scope for this pass.
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.
Summary
planwright now ships the spec-driven pipeline as a Claude Code plugin (installed via the marketplace flow in `roles/osx/tasks/osx.yml`). This removes the local pair-flow pieces planwright supersedes, while keeping the dotfiles-local surfaces planwright has no equivalent for.
Changes
Kept (planwright has no equivalent)
`pair-flow-config.sh` (`repo-class`), `pair-flow.yml` (`panel-backends`), the inbox/heartbeat substrate, and the `panel-`/`peer-review`/`copilot-`/`code-review` commands.
Validation
`skill-contracts.sh`, `yamllint`, `ansible-lint`, and `syntax-check` all pass; no active config/script/doc references the deleted validator.
Self-review audit
Standalone
/self-reviewpass againstorigin/main. Diff: 6 files (prose + config + one script trim + one deletion).Lens coverage
skill-contracts.shtrim passes (all invariants hold);spec-validate.shdeletion has zero live readers; droppedstale-lock-thresholdis unread bypair-flow-config.shskill-contracts.shretainsset -euo pipefailand the error-count/exit-1 pathscripts/(where MCP sync scripts live) instead of the realroles/osx/files/claude/scripts/skill-contracts.sh) passes against the surviving files; planwright owns the migrated-skill testsCLAUDE.md/settings.json/osx.yml/commands/*.md;tasks.mdDeferred→Completed move matches the actual changesAuto-applicable
Agent-resolvable
specs/pair-flow/with a siblingkickoff-brief.md); no test-backed findings surfacedNeeds sign-off
scripts/inbox-*.sh, which resolves to repo root; the scripts live underroles/osx/files/claude/scripts/roles/osx/files/CLAUDE.md:284roles/osx/files/claude/scripts/inbox-*.sh(matches the tracked-source convention this doc uses forworktree-bootstrap.sh)5f4b024Needs human judgment
Declined
Pending sign-off checklist
5f4b024— fix inbox substrate path inroles/osx/files/CLAUDE.md(repo-rootscripts/→roles/osx/files/claude/scripts/)Pass summary
origin/main(fetched at pre-flight)yamllint roles/osx/files/claude/pair-flow.yml(pass),skill-contracts.sh(pass — all invariants hold),bash -n skill-contracts.sh(pass).shellcheckunavailable on this host → degraded grounding for the shell lens; mitigated by the trim being a deletion-only change with a cleanbash -n.