Skip to content

feat(019): OpenSpec Changes Plugin with npm-based upstream management - #17

Open
nprbst wants to merge 22 commits into
mainfrom
019-openspec-changes-plugin
Open

feat(019): OpenSpec Changes Plugin with npm-based upstream management#17
nprbst wants to merge 22 commits into
mainfrom
019-openspec-changes-plugin

Conversation

@nprbst

@nprbst nprbst commented Dec 8, 2025

Copy link
Copy Markdown
Owner

Summary

This PR implements the OpenSpec Changes Plugin (speck-changes) for managing upstream OpenSpec releases and creating change proposals.

Key Features

  • npm-based upstream management: Pull OpenSpec versions from npm registry instead of GitHub releases

    • Captures the actual user-facing redistributable output
    • Runs openspec init --tools claude to generate slash commands
    • Stores both npm package and generated artifacts for side-by-side comparison

  • Change proposal workflow: Commands for proposing, validating, and applying changes

    • /speck-changes.propose - Create new change proposals
    • /speck-changes.validate - Validate proposal structure
    • /speck-changes.apply - Apply proposals to target specs
    • /speck-changes.archive - Archive completed proposals

  • Upstream version tracking:

    • /speck-changes.check-upstream - Query npm registry for available versions
    • /speck-changes.pull-upstream - Install and capture specific versions

Directory Structure

upstream/
├── spec-kit/           # Spec-kit releases (moved from upstream root)
└── openspec/           # OpenSpec npm-based versions
    ├── 0.14.0/
    │   ├── package/    # Copy of node_modules/@fission-ai/openspec
    │   └── init-output/  # Output from openspec init
    ├── 0.15.0/
    ├── 0.16.0/
    ├── latest -> 0.16.0
    └── releases.json

Test plan

  • Run bun plugins/changes/scripts/check-upstream.ts --limit 5 - shows npm versions with status
  • Run bun plugins/changes/scripts/pull-upstream.ts 0.14.0 --dry-run - dry run works
  • Pull versions 0.14.0, 0.15.0, 0.16.0 successfully
  • Verify upstream directory structure matches expected layout
  • TypeScript compiles without errors
  • Tests pass

🤖 Generated with Claude Code

nprbst and others added 22 commits December 7, 2025 19:48
@nprbst @claude
wip(019): OpenSpec Changes Plugin planning artifacts
158a9cd 
- Add spec.md with 6 user stories and requirements
- Add plan.md with technical context and constitution check
- Add research.md with OpenSpec CLI analysis and transformation strategy
- Add data-model.md with entity definitions and Zod schemas
- Add quickstart.md with developer setup guide
- Update CLAUDE.md with new technologies

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@nprbst @claude
feat(019): add tasks.md and remediate spec analysis findings
934a944 
- Add tasks.md with 70 tasks across 9 phases organized by user story
- Add [TEST] tasks before implementation tasks (Constitution XI TDD)
- Add T017a for OpenSpec CLI install + .md extraction (FR-004b)
- Add T022a for test generation during transformation (FR-006)
- Add T041a for delta conflict resolution prompts
- Consolidate T053 to single `bun preflight` (Constitution IX)
- Define "typical releases" in SC-002/SC-003 (<50 files, <5MB)
- Define migration success criteria in SC-007 (20 repos, zero errors)
- Clarify FR-015 requirement syntax (FR IDs, scenarios, RFC 2119)
- Standardize "delta file" terminology throughout
- Remove hardcoded version from plan.md structure diagram

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@nprbst @claude
refactor(019): align spec artifacts with monorepo plugin structure
1eb7f0e 
Update all path references to match the refactored plugin architecture
established in origin/main:

- Plugin location: .speck/plugins/speck-changes/ → plugins/speck-changes/
- Commands location: .claude/commands/speck-changes/ → plugins/speck-changes/commands/
- Tests location: tests/.speck-plugins/speck-changes/ → plugins/speck-changes/tests/
- Remove duplicate GitHub API tasks (use @speck/common/github)
- Add package.json and tsconfig.json setup tasks
- Renumber tasks after consolidation (56 → 53 tasks)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@nprbst @claude
feat(019): implement OpenSpec Changes Plugin with full command suite
7c4150c 
Implements the speck-changes plugin bringing OpenSpec-style change management
to Speck projects. This includes structured proposal workflows, delta specs,
validation, archiving, and migration from OpenSpec.

Commands implemented:
- /speck-changes.propose - Create change proposals with delta files
- /speck-changes.list - List active change proposals
- /speck-changes.show - Show change details
- /speck-changes.validate - Validate proposal structure and RFC 2119 keywords
- /speck-changes.archive - Archive completed changes and merge deltas
- /speck-changes.migrate - Import existing OpenSpec projects
- /speck-changes.check-upstream - Query OpenSpec releases
- /speck-changes.pull-upstream - Fetch upstream releases
- /speck-changes.transform-upstream - Transform Node.js to Bun TypeScript

Key features:
- Delta file format with ADDED/MODIFIED/REMOVED sections
- Scenario validation (Given-When-Then format)
- Task completion checking before archive
- Delta merging into source specs
- OpenSpec directory detection and migration

Test coverage: 134 tests passing across 11 test files

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@nprbst @claude
docs(019): expand speck-changes README with comprehensive user guide
967f54f 
- Add "Why Speck Changes?" value proposition section
- Include ASCII workflow diagram showing full lifecycle
- Add complete example with AI assistant interaction walkthrough
- Document proposal options (--with-design, --specs flags)
- Expand delta file format with ADDED/MODIFIED/REMOVED examples
- Add validation checks table and archive options
- Include best practices, troubleshooting, and comparison sections

Also includes minor code improvements:
- Convert changeExists and transformFile to sync functions
- Add type annotations to JSON.parse calls in tests

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@nprbst @claude
refactor(019): restructure plugin directories and symlink commands
ef2710a 
- Rename plugins/speck-changes/ to plugins/changes/ (match plugins/reviewer pattern)
- Move speck-changes.*-upstream.md commands to .claude/commands/ (actual files)
- Create symlinks in .claude/commands/ for remaining 6 changes commands
- Create symlinks in .claude/commands/ for 2 reviewer commands
- Update all path references in scripts and command files

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@nprbst @claude
fix(019): improve pull-upstream to extract only essential files
143ca93 
- Add selective path extraction (src, package.json, tsconfig.json, etc.)
- Extract to temp directory first, then copy only needed files
- Clean up temp files after extraction

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@nprbst @claude
feat(019): add apply command to spec and documentation
e6a7cc1 
- Add User Story 7 for apply change proposal workflow
- Add FR-016, FR-016a, FR-016b, FR-017 requirements
- Add Phase 4.5 tasks for apply implementation
- Update README with apply command usage

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@nprbst @claude
chore(019): add OpenSpec v0.14.0 upstream release
321d9ce 
- Pull v0.14.0 release from Fission-AI/OpenSpec
- Contains src, package.json, tsconfig.json, and docs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@nprbst @claude
feat(019): implement apply command for change proposal workflow
3d21731 
- Add apply.ts script with task parsing, completion marking, and delta context loading
- Add apply.test.ts with 20 tests covering all functionality
- Create speck-changes.apply.md command definition
- Symlink command from .claude/commands
- Mark T054-T059 tasks as complete in tasks.md

Implements FR-016 (apply command), FR-016a (task completion marking),
FR-016b (delta context loading), and FR-017 (archive suggestion).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@nprbst @claude
refactor(019): switch from GitHub releases to npm-based upstream mana…
4691898 
…gement

- Replace GitHub tarball downloads with npm package installation
- check-upstream now queries npm registry for @fission-ai/openspec versions
- pull-upstream installs package as dev dep, runs openspec init --tools claude
- Capture both npm package and init output to upstream/openspec/<version>/
- Move AGENTS.md from project root to init-output directory
- Update Release schema: make commitSha optional, add npmPublishDate
- Reorganize upstream/: move spec-kit to upstream/spec-kit/
- Pull OpenSpec versions 0.14.0, 0.15.0, 0.16.0 with new npm-based flow

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@nprbst @claude
feat(019): capture openspec/ directory in pull-upstream
77cb45f 
- Add step 5c to copy openspec/AGENTS.md and project.md to init-output/
- Skip specs/ and changes/ dirs (may contain test content)
- Keep source openspec/ in project root for A/B testing
- Update CLI help text to document new step

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@nprbst @claude
docs(019): harmonize spec, plan, and tasks after /speck:analyze remed…
cc938ad 
…iation

Clarification session (2025-12-08):
- Skills architecture: 3 skill files (SKILL.md, spec-format.md, troubleshooting.md)
- Transform agent: explicit responsibilities for upstream transformation
- Path convention: specs at root, changes/archive in .speck/
- Delta-spec template: structure outline with ADDED/MODIFIED/REMOVED sections
- Plugin directory: standardized on plugins/changes/

Analysis remediation (11 issues fixed):
- I1 (CRITICAL): Fixed plugins/speck-changes/ → plugins/changes/ in all files
- I2 (HIGH): Fixed User Story 1 test references in spec.md
- D1 (HIGH): Merged duplicate FR-005/FR-047 SPECK-EXTENSION requirements
- C1 (CRITICAL): Added skills tasks T011b-T011e (FR-040, FR-041, FR-042)
- C2 (HIGH): Added transform agent task T011f (FR-043)
- C3 (HIGH): Added delta-spec template task T011a (FR-048-050)
- I4 (MEDIUM): Added skills/ and agents/ to plan.md structure
- U1, U2 (MEDIUM): Clarified T019a and T014a task descriptions
- T1 (LOW): Standardized "delta file" terminology throughout

Coverage now 100% (44/44 requirements have tasks).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@nprbst @claude
docs(019): add /speck:analyze findings and implementation details to …
c5fc8d0 
…pending tasks

- Add Analysis Findings section to plan.md with blocking items, foundation tasks, and recommended completion order
- Add implementation details to pending tasks T011a-T011f (skills, agents, templates)
- Add details to T014a (OpenSpec CLI template extraction)
- Add details to T019, T019a (validation and test generation)
- Add details to T051-T053 (documentation tasks)
- Add remaining work summary to tasks.md header

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@nprbst @claude
feat(019): complete implementation with skills, agents, validation, a…
c5f112f 
…nd docs

- Add delta-spec template with RFC 2119 keywords (T011a)
- Create changes-workflow skills: SKILL.md, spec-format.md, troubleshooting.md (T011b-e)
- Add transform-openspec agent with transformation patterns (T011f)
- Update pull-upstream to extract templates to templates/ directory (T014a)
- Add TypeScript/ESLint validation to transform-upstream (T019)
- Add validation tests for runTypeCheck, runLint, runValidation (T019a)
- Update speck-help skill with speck-changes plugin documentation (T051)
- Create website docs for speck-changes plugin (T052)
- Fix quickstart.md test paths and validate commands (T053)

Progress: 63/63 tasks complete (100%)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@nprbst @claude
feat(019): add copy-plugin script and speck-changes to build
c061678 
Build improvements:
- Add copy-plugin script for local development (bypasses marketplace)
- Add speck-changes plugin to build-plugin.ts with prefix stripping
- Fix marketplace.json source path rewriting for correct structure
- Fix owner schema to accept object format

Version script improvements:
- Add 'changes' target for plugins/changes
- Rename 'speck-reviewer' to 'reviewer' to match directory structure
- Add backwards-compatible tag lookup for legacy speck-reviewer-v* tags

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@nprbst @claude
wip(019): fix command script paths for production builds
d0d5825 
- Change .ts to .js extension (build bundles to JS)
- Use ${CLAUDE_PLUGIN_ROOT} consistently instead of relative paths

Note: Not fully working yet - needs testing after cache refresh.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@nprbst @claude
wip(019): add unified CLI with dynamic plugin subcommands
c1e20bd 
- Create unified speck-changes CLI with dispatch table pattern
- Add PluginCLISchema to manifest-schemas for cli field declaration
- Create plugin-loader.ts for plugin discovery and subprocess delegation
- Update plugin manifests with cli field (reviewer, changes)
- Add plugin routing to main CLI before Commander parsing
- Add dynamic plugin commands to help output

Enables: `speck reviewer <cmd>` and `speck changes <cmd>` instead of
separate binaries.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@nprbst @claude
wip(019): consolidate speck-changes to single CLI entrypoint
d24da06 
- Update 10 commands to use `speck changes <cmd>` instead of individual scripts
- Remove per-script bundling from build (10 scripts × ~128KB → 1 CLI × ~150KB)
- Remove bootstrap.sh from speck-reviewer (use unified CLI)
- Simplify /speck-reviewer:init to use `speck reviewer` instead of symlink
- Add plugin CLI development guide

Size reduction: speck-changes from 1.62MB to 246KB (-85%)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@nprbst @claude
test(019): add integration tests for plugin CLI routing
1a5943d 
T008: Add integration tests covering:
- Plugin subcommand routing (reviewer, changes)
- Core commands remain unchanged (env, --version, help)
- --json flag propagation to plugins
- Unknown command handling
- Plugin discovery in development mode
- Exit code propagation from plugins

16 tests verifying unified CLI pattern works correctly.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@nprbst @claude
refactor(019): rename plugin help skills for dynamic discovery
abc9a75 
- Rename pr-review → speck-reviewer-help with updated frontmatter
- Rename changes-workflow → speck-changes-help with updated frontmatter
- Replace hardcoded plugin docs in speck-help with brief reference

Enables dynamic skill routing:
- "how do I review a PR" → speck-reviewer-help
- "how do I propose a change" → speck-changes-help

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@nprbst @claude
fix(019): correct bootstrap.sh paths for plugin directory structure
dbf8924 
The plugin structure places bootstrap.sh at cli/bootstrap.sh (not src/cli/),
so path references needed updating:
- bootstrap.sh: ../../dist → ../dist to find speck-cli.js
- init.ts: src/cli/bootstrap.sh → cli/bootstrap.sh for all candidates

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@nprbst