Rewrite speckit-flow pipeline with proven 8-step workflow#38
Merged
nextlevelshit merged 32 commits intomainfrom Feb 9, 2026
Merged
Rewrite speckit-flow pipeline with proven 8-step workflow#38nextlevelshit merged 32 commits intomainfrom
nextlevelshit merged 32 commits intomainfrom
Conversation
Add three new JSON schemas for the reworked doc-loop pipeline: - doc-scan-results: changed files and documentation state snapshot - doc-consistency-report: severity-rated documentation inconsistencies - doc-issue-result: GitHub issue creation result
Delete 5 contract schemas that were referenced by the old doc-loop pipeline but never actually used: change-analysis, documentation-state, context-analysis, sync-plan, validation-results.
…cy gate Replace the broken 5-step doc-loop pipeline (no dependencies, no artifact injection, nonexistent contracts) with a focused 3-step pipeline: 1. scan-changes (navigator): identify changed files, snapshot docs 2. analyze-consistency (reviewer): cross-reference code vs docs 3. create-issue (github-analyst): file GitHub issue with task checklist Now accepts CLI input for scan scope (branch diff, "full", or custom ref).
…prompts Fix all 7 deficiencies: step 2 now reads its injected artifact, all steps have JSON schema contract validation with retry, outputs are structured JSON, workspace uses root:./ syntax, and prompts include detailed format specs.
…order Replace map[string]string with ordered slice for test data inserts so parent rows (pipeline_run) are always inserted before child rows (performance_metric) that reference them via foreign key.
…fact output Persona constraints like "NEVER write any files" prevented LLMs from writing pipeline output artifacts. Permission enforcement is handled mechanically by the executor via AllowedTools, not by prompt-level restrictions. Replace blanket prohibitions with role-focused guidance.
Sync 5 personas (3 mismatched, 2 missing), 2 pipelines (missing), and 17 contracts (1 mismatched, 16 missing) that had drifted between .wave/ and internal/defaults/.
…ipeline Completely rewrites the speckit-flow pipeline with fixes discovered through iterative end-to-end testing of all 6 spec-building steps. Adds speckit slash commands as .claude/commands for use by pipeline personas. Key fixes: - Switch all spec steps to implementer persona (philosopher has Bash denied) - Add cd to project root instruction in every prompt (workspace is isolated) - Inject specify output artifact into all subsequent steps for context - Each step writes structured JSON status report as output artifact Steps 1-6 (specify→clarify→plan→tasks→checklist→analyze) tested and confirmed working end-to-end with consistent ~270-540s step times.
There was a problem hiding this comment.
Pull request overview
This PR refactors Wave’s “speckit-flow” planning and documentation gates into more structured, contract-validated pipelines, adds new pipelines/personas/contracts to support the workflow, and updates related commands and tests.
Changes:
- Reworks the
planpipeline to produce structured JSON artifacts (exploration/tasks/review) with JSON Schema handover validation. - Replaces the legacy documentation sync pipeline with a new
doc-loopconsistency gate that scans changes and can open a GitHub issue. - Adds a new
issue-researchpipeline plus multiple new JSON schemas and persona definitions to support web/GitHub workflows.
Reviewed changes
Copilot reviewed 72 out of 72 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| internal/state/rollback_test.go | Makes FK-safe test insert ordering deterministic for rollback integrity test. |
| internal/defaults/pipelines/plan.yaml | Updates plan pipeline prompts/artifacts to structured JSON + schema validation. |
| internal/defaults/pipelines/issue-research.yaml | Adds new pipeline to fetch/analyze/research an issue and post a comment. |
| internal/defaults/pipelines/doc-loop.yaml | Replaces documentation sync analysis with scan/consistency/issue-creation gate. |
| internal/defaults/personas/summarizer.md | Adjusts summarizer constraints wording. |
| internal/defaults/personas/researcher.md | Adds new researcher persona. |
| internal/defaults/personas/planner.md | Adjusts planner constraints wording. |
| internal/defaults/personas/philosopher.md | Adjusts philosopher constraints wording. |
| internal/defaults/personas/navigator.md | Adjusts navigator constraints wording. |
| internal/defaults/personas/github-pr-creator.md | Simplifies PR creator output guidance to “follow injected schema”. |
| internal/defaults/personas/github-enhancer.md | Simplifies enhancer output guidance to “follow injected schema”. |
| internal/defaults/personas/github-commenter.md | Adds GitHub commenter persona for posting issue comments via gh. |
| internal/defaults/personas/github-analyst.md | Simplifies analyst output guidance to “follow injected schema”. |
| internal/defaults/contracts/validation-results.schema.json | Removes legacy schema no longer used by updated doc-loop. |
| internal/defaults/contracts/test-report.schema.json | Adds schema for test pipeline final report artifact. |
| internal/defaults/contracts/test-plan.schema.json | Adds schema for test plan artifact. |
| internal/defaults/contracts/test-analysis.schema.json | Updates schema shape for test analysis artifact. |
| internal/defaults/contracts/sync-plan.schema.json | Removes legacy schema no longer used by updated doc-loop. |
| internal/defaults/contracts/research-topics.schema.json | Adds schema for extracted research topics. |
| internal/defaults/contracts/research-report.schema.json | Adds schema for synthesized research report. |
| internal/defaults/contracts/research-findings.schema.json | Adds schema for research findings grouped by topic. |
| internal/defaults/contracts/pr-result.schema.json | Adds schema for PR creation result output. |
| internal/defaults/contracts/plan-tasks.schema.json | Adds schema for structured plan tasks output. |
| internal/defaults/contracts/plan-review.schema.json | Adds schema for structured plan review output. |
| internal/defaults/contracts/plan-exploration.schema.json | Adds schema for structured plan exploration output. |
| internal/defaults/contracts/mismatches.schema.json | Adds schema for doc vs impl mismatch reporting. |
| internal/defaults/contracts/judged-issues.schema.json | Adds schema for selecting/prioritizing top mismatches. |
| internal/defaults/contracts/issue-spec.schema.json | Adds schema for a detailed spec for a selected mismatch issue. |
| internal/defaults/contracts/issue-content.schema.json | Adds schema for parsed GitHub issue content. |
| internal/defaults/contracts/impl-plan.schema.json | Adds schema for implementation plan tasks derived from a spec. |
| internal/defaults/contracts/impl-analysis.schema.json | Adds schema for analysis of actual implemented behaviors/features. |
| internal/defaults/contracts/documentation-state.schema.json | Removes legacy schema no longer used by updated doc-loop. |
| internal/defaults/contracts/docs-analysis.schema.json | Adds schema for analysis of documented behaviors/features. |
| internal/defaults/contracts/doc-scan-results.schema.json | Adds schema for doc-loop scan results. |
| internal/defaults/contracts/doc-issue-result.schema.json | Adds schema for doc-loop issue creation result. |
| internal/defaults/contracts/doc-consistency-report.schema.json | Adds schema for doc-loop consistency report. |
| internal/defaults/contracts/context-analysis.schema.json | Removes legacy schema no longer used by updated doc-loop. |
| internal/defaults/contracts/comment-result.schema.json | Adds schema for GitHub comment-posting result. |
| internal/defaults/contracts/change-analysis.schema.json | Removes legacy schema no longer used by updated doc-loop. |
| internal/defaults/contracts/branch-info.schema.json | Adds schema for branch creation info. |
| internal/defaults/contracts/auth-specification.schema.json | Adds schema for auth system specification docs. |
| internal/defaults/contracts/auth-flow-analysis.schema.json | Adds schema for detailed auth-flow analysis. |
| internal/defaults/contracts/auth-files.schema.json | Adds schema for discovered auth-related files. |
| Makefile | Adds basic build/install/test/lint/clean targets for the Go CLI. |
| .wave/pipelines/plan.yaml | Mirrors the internal default plan pipeline changes in the user-facing location. |
| .wave/pipelines/doc-loop.yaml | Mirrors the internal default doc-loop changes in the user-facing location. |
| .wave/personas/summarizer.md | Mirrors summarizer persona constraint changes. |
| .wave/personas/planner.md | Mirrors planner persona constraint changes. |
| .wave/personas/philosopher.md | Mirrors philosopher persona constraint changes. |
| .wave/personas/navigator.md | Mirrors navigator persona constraint changes. |
| .wave/contracts/validation-results.schema.json | Removes legacy schema mirroring internal/defaults removal. |
| .wave/contracts/sync-plan.schema.json | Removes legacy schema mirroring internal/defaults removal. |
| .wave/contracts/plan-tasks.schema.json | Adds plan-tasks schema mirroring internal/defaults. |
| .wave/contracts/plan-review.schema.json | Adds plan-review schema mirroring internal/defaults. |
| .wave/contracts/plan-exploration.schema.json | Adds plan-exploration schema mirroring internal/defaults. |
| .wave/contracts/documentation-state.schema.json | Removes legacy schema mirroring internal/defaults removal. |
| .wave/contracts/doc-scan-results.schema.json | Adds doc-scan-results schema mirroring internal/defaults. |
| .wave/contracts/doc-issue-result.schema.json | Adds doc-issue-result schema mirroring internal/defaults. |
| .wave/contracts/doc-consistency-report.schema.json | Adds doc-consistency-report schema mirroring internal/defaults. |
| .wave/contracts/context-analysis.schema.json | Removes legacy schema mirroring internal/defaults removal. |
| .wave/contracts/change-analysis.schema.json | Removes legacy schema mirroring internal/defaults removal. |
| .claude/commands/speckit.tasks.md | Adds speckit command to generate tasks.md using design docs. |
| .claude/commands/speckit.specify.md | Adds speckit command to generate/validate feature spec & branch setup. |
| .claude/commands/speckit.plan.md | Adds speckit command to produce implementation planning artifacts. |
| .claude/commands/speckit.implement.md | Adds speckit command to execute tasks.md with checklist gating. |
| .claude/commands/speckit.constitution.md | Adds speckit command to update constitution and propagate consistency. |
| .claude/commands/speckit.clarify.md | Adds speckit command for interactive clarification loop updating spec. |
| .claude/commands/speckit.analyze.md | Adds speckit command to analyze cross-artifact consistency (read-only). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Replace buffered json output with stream-json NDJSON format for real-time visibility into Claude Code tool calls. Add StreamEvent type, OnStreamEvent callback, and line-by-line scanner with parseStreamLine/extractToolTarget. Also adds --verbose and --dangerously-skip-permissions flags.
Add StateStreamActivity constant and ToolName/ToolTarget fields to Event. Wire OnStreamEvent callback in executor's runStepExecution() to emit stream_activity events for real-time tool call visibility. Render tool events in dim formatting for human-readable output.
Used by speckit-flow, docs-to-impl, gh-poor-issues, and umami pipelines. Without it, users get "persona not found" errors on wave init projects.
Used by issue-research pipeline for deep codebase analysis. Read-only permissions with gh and git log access.
Used by docs-to-impl, gh-poor-issues, umami, and doc-loop pipelines. Read-only with test runner and git diff access.
Used by issue-research pipeline to post analysis comments on GitHub issues.
Security logger was writing [SECURITY] lines to stdout, polluting pipeline output. Move all security logging to stderr where diagnostic output belongs.
…ut and -v/--verbose Consolidate three negative output flags into two positive persistent flags on the root command: -o, --output <format> Output format: auto, json, text, quiet (default: auto) -v, --verbose Include real-time tool activity Modes: auto (BubbleTea TUI if TTY, plain text if pipe), json (clean NDJSON to stdout), text (plain text to stderr), quiet (final result only). Key rule: stdout is either NDJSON or nothing, never mixed. - Create output.go with CreateEmitter() factory and OutputConfig - Update run.go, do.go, meta.go to use CreateEmitter() - Gate completion summary and deliverables on auto/text format only - Remove humanReadable field and NewNDJSONEmitterWithHumanReadable() from emitter - Fix meta.go completion message writing to stdout instead of stderr
… output - Add verbose field to BasicProgressDisplay and BubbleTea for tool activity - Add QuietProgressDisplay that only renders pipeline-level events - Add WAVE_FORCE_TTY env var to override TTY detection for testing/CI - Show CurrentAction instead of fake 25%/75% percentages in text mode - Skip blank step-start lines for running events without persona - Add LastToolName/LastToolTarget to PipelineContext for TUI verbose
Remove local --verbose flag from validate command (was shadowing the persistent -v/--verbose). Now reads the persistent flag from root command. Update tests to use root command wrapper for persistent flag propagation.
…to stderr - Security logger only enabled when --debug flag is set (prevents [SECURITY] noise on stderr in json/text modes) - Migration messages use fmt.Fprintf(os.Stderr) instead of fmt.Printf to avoid corrupting stdout in -o json mode - Add omitempty to Event.DurationMs so progress events omit duration_ms:0
- Update README flag listing - Update cli.md run examples with -o json, -o text -v, -o quiet - Update environment.md: remove stale WAVE_LOG_FORMAT, add WAVE_FORCE_TTY - Update quick-start.md: show text progress as default output example
test_suite contracts now support a `dir` field to control where commands run. Defaults to project_root (via git rev-parse) since test commands almost always need project context (go.mod, package.json, etc). Supported values: project_root, absolute path, relative to workspace.
When an adapter process exits non-zero (e.g. Claude Code JS crash after tool calls completed), emit a warning event instead of failing the step. Contract validation decides whether the work was actually completed. All three display modes (bubbletea, progress, basic) now handle the warning event type.
Default pipelines should be language-agnostic. Commented out Go-specific test commands so users customize per-project in .wave/pipelines/.
Wave spawns Claude Code and gh via exec.CommandContext with os.Environ(). GH_TOKEN from keyring doesn't propagate (D-Bus session lost), and Claude Code OAuth can expire silently. The shellHook now: - Extracts GH_TOKEN from gh auth at shell entry - Warns about missing ANTHROPIC_API_KEY or GH_TOKEN
- Update persona count 10→14 across README and personas guide - Update pipeline count 9/16→18 across README and pipelines guide - Add missing personas to tables: implementer, reviewer, researcher, github-analyst, github-commenter, github-enhancer, github-pr-creator - Add missing pipelines to tables: prototype, docs-to-impl, doc-loop, github-issue-enhancer, gh-poor-issues, issue-research, hello-world, smoke-test, umami - Fix speckit-flow steps to actual 8-step flow - Remove unimplemented env vars (WAVE_DEBUG, WAVE_MANIFEST, WAVE_WORKSPACE_ROOT), add migration env vars - Add template and format contract types to reference - Add markdown_spec to contract type descriptions - Fix Go version 1.22→1.25 in installation guide - Remove incorrect planner temperature from persona example - Clarify --verbose as global -v flag in CLI reference
…E_ROOT These env vars have no os.Getenv calls in the codebase. Remove from integration docs (github-actions, gitlab-ci) and workspaces concept doc.
14 tasks
Add readonly workspace mounts to pipeline steps that need repo access (plan/explore, doc-loop/scan-changes, doc-loop/analyze-consistency). Update gh CLI prompts to use --body-file instead of inline --body to avoid shell escaping and CLI length limit issues.
Keep --body-file approach over inline --body for gh CLI robustness.
nextlevelshit
added a commit
that referenced
this pull request
Mar 4, 2026
Rewrite speckit-flow pipeline with proven 8-step workflow
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
.claude/commands/speckit.*.md) for use by pipeline personasdirfield to test_suite contracts for working directory control (defaults to project_root)Closes #39
Test Plan
--from-stepresume tested across all stepsgo build ./cmd/wavepassesgo test -race ./...passes (all packages)