Install spectacles SDD suite (ref: v0.3.0) by norrietaylor · Pull Request #469 · gominimal/minimal

norrietaylor · 2026-06-19T15:11:40Z

Installs the spectacles SDD agent suite (ADR 0004) via scripts/quick-setup.sh. Wrappers pin hosted reusable workflows at @v0.3.0. Labels, variables, and secrets were applied directly; the file artifacts in this PR honor the protected default branch. Merge to activate the workflows.

Summary by CodeRabbit

Release Notes

New Features
- Added spec derivation workflow with command acknowledgment via reaction indicators.
Improvements
- Enhanced concurrency handling to prevent unintended job cancellations across workflows.
- Introduced deterministic command acknowledgment reactions (👀 → outcome emoji) for better user feedback.
- Updated authentication token integration across all command-processing workflows.
- Improved workflow routing with phase-based architecture and explicit permission scoping.

coderabbitai · 2026-06-19T15:11:55Z

📝 Walkthrough

Walkthrough

Upgrades all norrietaylor/spectacles reusable workflow and action references from v0.2.0 to v0.3.0 across the entire .github/workflows/ suite. Replaces COPILOT_GITHUB_TOKEN with CLAUDE_CODE_OAUTH_TOKEN in all affected secret mappings. Adds ack/ack-terminal 👀 reaction jobs to six workflows. Refactors the triage wrapper into three phase jobs. Rewrites concurrency keying in execute workflows. Adds a new sdd-derive workflow.

Changes

Spectacles v0.3.0 Upgrade

Layer / File(s)	Summary
Straightforward v0.3.0 action-only bumps `.github/workflows/sdd-monitor.yml`, `.github/workflows/sdd-pr-sanitize.yml`, `.github/workflows/sdd-status.yml`, `.github/workflows/sdd-spike-actuator.yml`, `.github/workflows/sdd-triage-dedupe-tasks.yml`, `.github/workflows/sdd-triage-promote-ready.yml`, `.github/workflows/distillery-sync.yml`	Seven workflows where only the `uses:` version string changes from `@v0.2.0` to `@v0.3.0` with no other logic edits.
`COPILOT_GITHUB_TOKEN` → `CLAUDE_CODE_OAUTH_TOKEN` swap with v0.3.0 bumps `.github/workflows/distillery-sync.yml`, `.github/workflows/sdd-review.yml`, `.github/workflows/sdd-validate.yml`, `.github/workflows/sdd-dispatch.yml`, `.github/workflows/sdd-execute-haiku.yml`, `.github/workflows/sdd-execute-opus.yml`, `.github/workflows/sdd-execute-sonnet.yml`, `.github/workflows/sdd-spec.yml`	Replaces `COPILOT_GITHUB_TOKEN` with `CLAUDE_CODE_OAUTH_TOKEN` in explicit secrets mappings for all locked reusable workflow calls; bumps routing action and lock workflow references to `v0.3.0`; adds `pull-requests: read` permission to route jobs in `sdd-spec` and `sdd-triage`.
Concurrency keying rewrites in execute workflows `.github/workflows/sdd-execute-haiku.yml`, `.github/workflows/sdd-execute-opus.yml`, `.github/workflows/sdd-execute-sonnet.yml`	Rewrites the `concurrency.group` expression so PR-attached triggers use `github.run_id`-scoped groups and do not cancel each other, while issue-comment `/execute` and `/revise` events continue to use deterministic issue/task-derived keys.
`ack` / `ack-terminal` 👀 reaction jobs `.github/workflows/sdd-dispatch.yml`, `.github/workflows/sdd-execute-haiku.yml`, `.github/workflows/sdd-execute-opus.yml`, `.github/workflows/sdd-execute-sonnet.yml`, `.github/workflows/sdd-spec.yml`, `.github/workflows/sdd-triage.yml`	Adds `ack` and `ack-terminal` job pairs: `ack` mints an App token and calls `sdd-ack-reaction@v0.3.0` in `mode: ack` to post 👀 on the triggering comment; `ack-terminal` runs under `always()` and replaces the reaction with a terminal outcome (`ran`/`failed`/`noop`) derived from upstream job results.
Triage workflow split into arch / plan / materialize phases `.github/workflows/sdd-triage.yml`	Replaces the single `sdd-triage.lock.yml` fan-out with three explicit jobs (`arch`, `plan`, `materialize`) gated on `route.outputs.target`; updates `route` to use `sdd-route-triage@v0.3.0` with `target`/`item_number` outputs; `cycle-detect` now depends on `[route, materialize]` and uses `sdd-cycle-detect@v0.3.0`.
Spike reentry: triage-plan lock and permissions adjustment `.github/workflows/sdd-spike-reentry.yml`	Changes phase-B reusable workflow from `sdd-triage.lock.yml@v0.2.0` to `sdd-triage-plan.lock.yml@v0.3.0`; remaps secrets (adds `CLAUDE_CODE_OAUTH_TOKEN`, removes `COPILOT_GITHUB_TOKEN` and `DISTILLERY_OAUTH_TOKEN`); reduces caller-granted `contents` permission from write to read.
New `sdd-derive` workflow `.github/workflows/sdd-derive.yml`	Introduces a new workflow with `pull_request`/`issue_comment` triggers. The `route` job computes `should_offer`/`has_runs`/`run_matrix` via `sdd-route-derive`. The `offer` job posts an idempotent offer comment and applies `needs-spec` label. The `derive` job runs a non-cancelling matrix fan-out calling `sdd-derive.lock.yml@v0.3.0`. `ack`/`ack-terminal` jobs implement the standard 👀 reaction pattern.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

gominimal/inbox#70: Tracks the v0.3.0 rollout of spectacles SDD agents, including the shift from COPILOT_GITHUB_TOKEN to CLAUDE_CODE_OAUTH_TOKEN and the addition of acknowledgment/reaction mechanisms implemented in this PR.

Possibly related PRs

gominimal/spectacles#18: Directly related — implements the sdd-triage agent that this PR's triage wrapper split (arch/plan/materialize) is wiring against.
gominimal/minspec-test#60: Updates the same sdd-* workflow wrappers with the same pattern (version bumps, token swap, ack/ack-terminal jobs) on a parallel repository.
gominimal/webapp#267: Bumps the same norrietaylor/spectacles uses: references and lock versions across the same set of workflow wrapper files.

Suggested reviewers

twitchyliquid64

🐇 A hop, a skip, v0.3 is here,
The Copilot token? Gone — Claude is near!
Eyes 👀 on each comment, reactions now flow,
Triage splits in three — arch, plan, materialize go.
Derive joins the dance, concurrency's aligned,
A warrenly workflow, precisely designed! 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: installing the spectacles SDD suite at version v0.3.0, which is the primary objective across all 17 modified/added workflow files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

gominimal-aw-bot · 2026-06-19T15:12:01Z

This pull request has no accompanying spec. Comment /derive-spec to have one derived retrospectively from the code — it opens a separate spec/<slug> documentation PR with demoable units, acceptance criteria, and a gap analysis (implementation gaps, missing failure paths, weak acceptance criteria). Ignore this to defer; the weekly unspecced-PR scan will re-surface it. See ADR 0027.

coderabbitai

🧹 Nitpick comments (1)

.github/workflows/sdd-triage.yml (1)
313-343: 💤 Low value

Minor documentation inconsistency: comment mentions noop but expression only produces ran/failed.

Line 314 describes three possible outcomes (🚀 ran / 😕 noop / 👎 failed), but the outcome expression on line 342 only produces 'failed' or 'ran'. For the triage workflow this is likely intentional—if should_run == 'true', exactly one phase job always runs, so noop never applies.

Consider updating the comment to reflect the actual outcomes for this workflow, or leave as-is if the comment is documenting the action's supported values rather than this workflow's usage.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/sdd-triage.yml around lines 313 - 343, The comment for the
ack-terminal job mentions three possible outcomes (🚀 ran / 😕 noop / 👎
failed), but the outcome expression on line 342 only produces 'failed' or 'ran'
because the workflow checks that should_run is 'true' before running any phases.
Update the comment to reflect the actual outcomes this workflow produces—only
'ran' and 'failed'—or clarify if the comment is documenting all supported values
of the sdd-ack-reaction action rather than documenting this specific workflow's
behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In @.github/workflows/sdd-triage.yml:
- Around line 313-343: The comment for the ack-terminal job mentions three
possible outcomes (🚀 ran / 😕 noop / 👎 failed), but the outcome expression on
line 342 only produces 'failed' or 'ran' because the workflow checks that
should_run is 'true' before running any phases. Update the comment to reflect
the actual outcomes this workflow produces—only 'ran' and 'failed'—or clarify if
the comment is documenting all supported values of the sdd-ack-reaction action
rather than documenting this specific workflow's behavior.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 19420dcb-765b-4483-a2f9-c94b5e1680b1

📥 Commits

Reviewing files that changed from the base of the PR and between 508dc61 and 4dc1f00.

📒 Files selected for processing (17)

.github/workflows/distillery-sync.yml
.github/workflows/sdd-derive.yml
.github/workflows/sdd-dispatch.yml
.github/workflows/sdd-execute-haiku.yml
.github/workflows/sdd-execute-opus.yml
.github/workflows/sdd-execute-sonnet.yml
.github/workflows/sdd-monitor.yml
.github/workflows/sdd-pr-sanitize.yml
.github/workflows/sdd-review.yml
.github/workflows/sdd-spec.yml
.github/workflows/sdd-spike-actuator.yml
.github/workflows/sdd-spike-reentry.yml
.github/workflows/sdd-status.yml
.github/workflows/sdd-triage-dedupe-tasks.yml
.github/workflows/sdd-triage-promote-ready.yml
.github/workflows/sdd-triage.yml
.github/workflows/sdd-validate.yml

norrietaylor added 22 commits June 19, 2026 08:11

chore: install sdd-spec wrapper (spectacles quick-setup)

ae4bfc5

chore: install sdd-triage wrapper (spectacles quick-setup)

7b8675a

chore: install sdd-dispatch wrapper (spectacles quick-setup)

759a2be

chore: install sdd-execute-haiku wrapper (spectacles quick-setup)

5fafb87

chore: install sdd-execute-sonnet wrapper (spectacles quick-setup)

a94d128

chore: install sdd-execute-opus wrapper (spectacles quick-setup)

40b39a4

chore: install sdd-validate wrapper (spectacles quick-setup)

e2773ef

chore: install sdd-review wrapper (spectacles quick-setup)

2b611e8

chore: install sdd-derive wrapper (spectacles quick-setup)

2b76364

chore: install distillery-sync wrapper (spectacles quick-setup)

8ff329a

chore: install sdd-pr-sanitize wrapper (spectacles quick-setup)

a484bab

chore: install sdd-triage-dedupe-tasks wrapper (spectacles quick-setup)

5d0deed

chore: install sdd-triage-promote-ready wrapper (spectacles quick-setup)

7787193

chore: install sdd-monitor wrapper (spectacles quick-setup)

3d9d49b

chore: install sdd-spike-actuator wrapper (spectacles quick-setup)

34c1d40

chore: install sdd-spike-reentry wrapper (spectacles quick-setup)

49cd36f

chore: install sdd-status wrapper (spectacles quick-setup)

98b2c11

chore: install feature issue template (spectacles quick-setup)

b1590d9

chore: install bug issue template (spectacles quick-setup)

0574f32

chore: install chore issue template (spectacles quick-setup)

8ee2cb9

chore: install spec issue template (spectacles quick-setup)

c6d2d6b

docs: install spike-author README (spectacles quick-setup)

4dc1f00

gominimal-aw-bot Bot added the needs-spec label Jun 19, 2026

coderabbitai Bot reviewed Jun 19, 2026

View reviewed changes

norrietaylor removed the needs-spec label Jun 19, 2026

evanspearman approved these changes Jun 19, 2026

View reviewed changes

norrietaylor merged commit f9d6dfb into main Jun 19, 2026
17 checks passed

norrietaylor deleted the spectacles/install branch June 19, 2026 15:30

coderabbitai Bot mentioned this pull request Jul 10, 2026

chore: uninstall spectacles SDD suite #716

Merged

Navigation Menu

Uh oh!

Install spectacles SDD suite (ref: v0.3.0) - #469

Install spectacles SDD suite (ref: v0.3.0)#469
norrietaylor merged 22 commits into
mainfrom
spectacles/install

norrietaylor commented Jun 19, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 19, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Possibly related PRs

Suggested reviewers

Uh oh!

gominimal-aw-bot Bot commented Jun 19, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

norrietaylor commented Jun 19, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Release Notes

Uh oh!

coderabbitai Bot commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Possibly related PRs

Suggested reviewers

Uh oh!

gominimal-aw-bot Bot commented Jun 19, 2026

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

norrietaylor commented Jun 19, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 19, 2026 •

edited

Loading