Skip to content

Install spectacles SDD suite (ref: v0.1.0) - #307

Merged
norrietaylor merged 18 commits into
mainfrom
spectacles/install
Jun 3, 2026
Merged

Install spectacles SDD suite (ref: v0.1.0)#307
norrietaylor merged 18 commits into
mainfrom
spectacles/install

Conversation

@norrietaylor

@norrietaylor norrietaylor commented Jun 3, 2026

Copy link
Copy Markdown
Member

Installs the spectacles SDD agent suite (ADR 0004) via scripts/quick-setup.sh. Wrappers pin hosted reusable workflows at @v0.1.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

  • New Features

    • Added GitHub issue templates for bug reports, feature requests, chores, and specifications with structured guidance
    • Introduced automated workflows for issue triage, task dispatch, review, and execution
    • Added automated monitoring and deduplication for issue tracking
    • Implemented auto-merge capabilities for pull requests
  • Documentation

    • Added SDD command vocabulary documentation in issue templates (e.g., /spec, /fastpath, /approve, /dispatch)

@coderabbitai

coderabbitai Bot commented Jun 3, 2026

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Walkthrough

This PR establishes the complete GitHub Actions-based SDD (Specification-Driven Development) pipeline infrastructure. It introduces four issue templates (bug, chore, feature, spec) to standardize issue entry, and deploys a comprehensive suite of workflows orchestrating spec submission, triage, multi-tier code generation/execution, review, validation, and monitoring phases with deterministic routing, lifecycle management, and failure recovery.

Changes

SDD Pipeline Infrastructure

Layer / File(s) Summary
GitHub Issue Templates
.github/ISSUE_TEMPLATE/bug.md, .github/ISSUE_TEMPLATE/chore.md, .github/ISSUE_TEMPLATE/feature.md, .github/ISSUE_TEMPLATE/spec.md
Four templates define the SDD issue schema: bug reports with reproduction steps, chores with motivation, feature requests with desired outcomes, and specs with Claude plan verification. All include YAML metadata (labels, title prefix) and a shared footer documenting the SDD command vocabulary (/spec, /fastpath, /triage, /approve, /dispatch, /revise, /execute) and lifecycle label behavior.
SDD Dispatch Orchestration
.github/workflows/sdd-dispatch.yml
Central dispatch workflow triggered by /dispatch comments on tracking issues. Routes dispatch, computes ready-set dependency matrix, fans out /execute comments and sdd:ready labels to task issues, manages lifecycle transitions (sdd:dispatchedsdd:in-progresssdd:done), and posts deterministic noop or guidance comments when dispatch is blocked or the ready set is empty.
SDD Execute Multi-Tier Wrappers
.github/workflows/sdd-execute-haiku.yml, .github/workflows/sdd-execute-sonnet.yml, .github/workflows/sdd-execute-opus.yml
Three parallel event-driven wrappers gate /execute and /revise commands to different model tiers (haiku/sonnet/opus). Each routes by event type and tier label, computes per-task-per-tier concurrency groups to prevent stale runs, calls the reusable tier-specific agent workflow with aw_context, and conditionally enables auto-merge on resulting PRs based on SDD_AUTO_MERGE configuration.
SDD Spec Workflow
.github/workflows/sdd-spec.yml
Spec agent wrapper that routes label/comment/PR events and produces aw_context plus fast-path decision outputs. Implements three execution paths: fast-path /approve triggering tier dispatch, normal spec processing via the reusable agent, and failure hand-off (posting needs-human for manual resumption). Handles token minting and error-safe comment posting.
SDD Triage Workflows
.github/workflows/sdd-triage.yml, .github/workflows/sdd-triage-dedupe-tasks.yml, .github/workflows/sdd-triage-promote-ready.yml
Three complementary triage workflows: sdd-triage routes /triage, /approve, and /revise commands and label mutations to the reusable triage agent; sdd-triage-dedupe-tasks closes lower-numbered phase-C task sub-issue duplicates under the same Unit; sdd-triage-promote-ready applies sdd:ready to tasks when their last blocker closes.
SDD Review Workflow
.github/workflows/sdd-review.yml
Review wrapper for sdd/ implementation PRs. Routes opened/synchronize events to compute should_run and aw_context, calls the reusable review agent to post inline advisory comments, and optionally resolves the App bot's advisory threads when SDD_AUTO_MERGE is enabled (enabling auto-squash + branch deletion).
SDD Validation and Monitoring
.github/workflows/sdd-validate.yml, .github/workflows/sdd-monitor.yml
sdd-validate routes PR and sdd:ready label events to invoke the reusable validation agent with aw_context. sdd-monitor detects "armed-but-idle" tracking issues (gated by SDD_MONITOR repo variable), applies debouncing, and posts /dispatch comments; serializes runs per repository to avoid overlapping audit.
Distillery Sync, PR Sanitize, Gitignore
.github/workflows/distillery-sync.yml, .github/workflows/sdd-pr-sanitize.yml, .gitignore
distillery-sync wraps the spectacles reusable workflow to sync spec/decision artifacts on main/master pushes, daily schedule, or manual dispatch with OAuth secrets and constrained permissions. sdd-pr-sanitize sanitizes PR body markdown for spec/ and arch/ branches. .gitignore excludes .serena/ directory for Serena MCP quick-setup state.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

  • gominimal/minspec-test#60: Introduces the same GitHub issue templates and SDD workflow suite (distillery-sync, dispatch, execute tiers, spec, triage, review, validate, monitor) at a parallel minimal test repository.

Poem

🐰 A rabbit hops through workflows bright,

Issue templates standing in the light,

/dispatch echoes through the queue,

Spec to code in tiers that flew,

SDD pipelines, shining true! ✨

🚥 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 clearly and specifically identifies the main change: installing the spectacles SDD suite at v0.1.0, which aligns with the PR's primary objective and all the file additions in the changeset.
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.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (1)
.github/workflows/sdd-review.yml (1)

45-58: ⚡ Quick win

Gate the route job on sdd/ head refs too.

Right now every pull_request.opened/synchronize event still starts a runner and invokes the routing action, even though non-sdd/ PRs are guaranteed to short-circuit later. Moving the head-ref check onto route would match the contract described above this job and avoid unnecessary third-party action executions on unrelated PRs.

♻️ Suggested change
   route:
+    if: startsWith(github.event.pull_request.head.ref, 'sdd/')
     runs-on: ubuntu-latest
     permissions:
       contents: read
🤖 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-review.yml around lines 45 - 58, The route job
currently always runs and invokes the external action (uses:
norrietaylor/spectacles/...sdd-route-review@v0.1.0) even for non-sdd PRs; add a
job-level conditional to short-circuit the entire route job by gating it on the
PR head ref starting with "sdd/" (use the GitHub Actions expression that checks
github.head_ref or startsWith(github.head_ref, 'sdd/')) so the job (route) —
including the Decide step (id: decide) — never launches for non-sdd/* head refs.
🤖 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.

Inline comments:
In @.github/workflows/sdd-dispatch.yml:
- Around line 293-303: The current try/catch around github.rest.issues.addLabels
swallows errors by calling core.info, which lets the run continue even if arming
the tracking issue fails; change the catch to fail the workflow instead (e.g.,
call core.setFailed with a message including err.message or rethrow the error)
so any failure in github.rest.issues.addLabels (with context and tracking
identifiers) stops the job and prevents proceeding without the sdd:dispatched
label.

In @.github/workflows/sdd-monitor.yml:
- Around line 126-138: The App token creation currently uses
actions/create-github-app-token@v3 without scoping permissions, so update the
Mint App token step (actions/create-github-app-token@v3) to include explicit
permission-* inputs to follow least privilege—add permission-actions: read,
permission-pull-requests: read, permission-issues: write and optionally
permission-contents: read if the sdd-monitor action
(norrietaylor/spectacles/.github/actions/sdd-monitor@v0.1.0) needs repo file
access; keep using the generated token (steps.app.outputs.token) for the
sdd-monitor step after adding these inputs.

---

Nitpick comments:
In @.github/workflows/sdd-review.yml:
- Around line 45-58: The route job currently always runs and invokes the
external action (uses: norrietaylor/spectacles/...sdd-route-review@v0.1.0) even
for non-sdd PRs; add a job-level conditional to short-circuit the entire route
job by gating it on the PR head ref starting with "sdd/" (use the GitHub Actions
expression that checks github.head_ref or startsWith(github.head_ref, 'sdd/'))
so the job (route) — including the Decide step (id: decide) — never launches for
non-sdd/* head refs.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c27af64a-325f-4abc-b62f-52f7a8701f32

📥 Commits

Reviewing files that changed from the base of the PR and between 1354466 and 0cca0a7.

📒 Files selected for processing (18)
  • .github/ISSUE_TEMPLATE/bug.md
  • .github/ISSUE_TEMPLATE/chore.md
  • .github/ISSUE_TEMPLATE/feature.md
  • .github/ISSUE_TEMPLATE/spec.md
  • .github/workflows/distillery-sync.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-triage-dedupe-tasks.yml
  • .github/workflows/sdd-triage-promote-ready.yml
  • .github/workflows/sdd-triage.yml
  • .github/workflows/sdd-validate.yml
  • .gitignore

Comment thread .github/workflows/sdd-dispatch.yml
Comment thread .github/workflows/sdd-monitor.yml
@norrietaylor
norrietaylor enabled auto-merge (squash) June 3, 2026 17:59
@norrietaylor
norrietaylor merged commit 8683942 into main Jun 3, 2026
68 of 98 checks passed
@norrietaylor
norrietaylor deleted the spectacles/install branch June 3, 2026 18:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants