feat: Add team collaboration, route-aware gap analysis, and upgrade mode #12
Conversation
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
Fixes issue where /speckit.* slash commands were not being discovered by Claude Code after installing the StackShift plugin. Directory Structure Fix: - Moved from: plugin/claude-commands/ - Moved to: plugin/.claude/commands/ Why This Fixes Discovery: - Claude Code looks for plugin-level commands in .claude/commands/ - The claude-commands/ directory was not a standard location - Now commands are in the correct location per Claude Code conventions Commands Available: - /speckit.analyze - /speckit.clarify - /speckit.implement - /speckit.plan - /speckit.specify - /speckit.tasks Benefits: - Install StackShift plugin once → commands available in all projects - No per-project setup needed - Update plugin → updates commands everywhere - Zero maintenance overhead This fixes the command discovery issue without requiring per-project installation or duplication.
Adds setup command that team members can run to install slash commands without running full StackShift analysis. Use Case: - Developer joins project that already has StackShift specs - Slash commands not available in their local checkout - Runs /stackshift.setup to get commands What it does: 1. Copies all slash commands from plugin to project .claude/commands/ 2. Updates .gitignore to allow committing commands 3. Provides commit message template 4. Explains why committing is critical for team Commands Installed: - /speckit.* (6 Spec Kit commands) - /stackshift.* (StackShift commands) Team Collaboration: - First dev runs StackShift → commands auto-installed - First dev commits .claude/commands/ to git - Other devs clone → commands already there - OR late joiners run /stackshift.setup This enables spec-driven workflow for entire teams without requiring every developer to run StackShift or manually copy commands.
Addresses critical UX issue where gap-analysis was confusing for Greenfield users by trying to analyze old codebase implementation. Issue: - User selects Greenfield (building NEW app) - Gap analysis tried to compare specs to OLD codebase - Confusing: "Why analyze old code I'm not using?" Fix: - Added Route Detection as FIRST STEP - Split into two workflows based on route Greenfield Gap Analysis: - Analyzes SPEC completeness (not old code) - Identifies [NEEDS CLARIFICATION] markers - Checks for acceptance criteria in specs - Asks about TARGET tech stack for new app - Creates build order roadmap - ALL features are MISSING (building from scratch) - Does NOT run /speckit.analyze (nothing to compare to) Brownfield Gap Analysis: - Runs /speckit.analyze (compares specs to existing code) - Identifies missing/partial features in current implementation - Catalogs technical debt - Creates roadmap to fill gaps in existing app - Mix of COMPLETE/PARTIAL/MISSING features Route Comparison Table: - Shows different approach for each route - Explains what gap analysis means per route - Clarifies when to use /speckit.analyze This fixes confusing UX where Greenfield users were told to analyze gaps in code they're replacing with a new implementation.
Enables Greenfield users to specify where specifications and
documentation should be written when extracting business logic.
New Configuration: spec_output_location
Options during Gear 1:
A) Current repository (default) - ./docs/, ./.specify/
B) New application repository - ~/git/my-new-app/.specify/
C) Separate docs repository - ~/git/my-app-docs/.specify/
D) Custom location - user specifies path
Stored in state file:
{
"path": "greenfield",
"config": {
"spec_output_location": "~/git/my-new-app",
"build_location": "~/git/my-new-app",
"target_stack": "Next.js 15..."
}
}
Skills Updated:
analyze/SKILL.md:
- Added Question: Spec Output Location (Greenfield only)
- Documents state file structure
- Shows difference between spec_output_location and build_location
reverse-engineer/SKILL.md:
- Added Configuration Check section
- Loads spec_output_location from state
- Creates directories at custom location if set
- Table showing where files go per configuration
create-specs/SKILL.md:
- Added Configuration Check
- Creates .specify/ structure at custom location
- Documents common patterns
Use Cases:
- Extract from Java app, write specs to new Next.js repo
- Extract from PHP, write to central docs repo
- Keep old and new codebases completely separate
Benefits:
✅ Clean separation of old and new
✅ Specs live with NEW codebase from day one
✅ No clutter in legacy repo
✅ Supports multi-repo enterprise workflows
…ation Adds systematic dependency upgrade workflow that uses specifications as a safety net during modernization. New Command: /stackshift.modernize Executes 4-phase spec-driven upgrade process for Brownfield projects. Phase 0: Spec-Guided Test Coverage (30-90 min) - Load specs from .specify/memory/specifications/ - Use spec acceptance criteria as test blueprint - Improve coverage to 85%+ before upgrading - Map tests to specs for traceability - Ensures safety net exists before changes Phase 1: Baseline & Analysis - READ ONLY (15-30 min) - Run /speckit.analyze for spec-code baseline - Document current dependency versions - Analyze spec impact of breaking changes - Generate UPGRADE_PLAN.md - No file modifications (planning only) Phase 2: Upgrade & Spec-Guided Fixes (1-4 hours) - Upgrade all dependencies to latest - Detect breaking changes from test failures - For each failure: * Load affected spec * Read acceptance criterion * Fix to preserve spec behavior - Iterate until passing Phase 3: Validation & PR (15-30 min) - Run /speckit.analyze (validate no drift) - Verify coverage still ≥85% - Generate UPGRADE_REPORT.md - Create PR Key Features: ✅ Specs act as safety net during upgrade ✅ Acceptance criteria guide breaking change fixes ✅ Systematic validation at each phase ✅ Test coverage improvement alongside upgrade ✅ Spec validation ensures behavior preserved Files Created: - .upgrade/spec-coverage-map.json (tests → specs mapping) - .upgrade/UPGRADE_PLAN.md (analysis and plan) - .upgrade/spec-impact-analysis.json (which specs affected) - .upgrade/stackshift-upgrade.yml (progress tracking) - .upgrade/UPGRADE_REPORT.md (final report) Benefits vs Full Rewrite: ✅ Faster (days vs months) ✅ Lower risk (incremental changes) ✅ Keeps working code ✅ Spec-guided fixes preserve behavior New Documentation: - docs/guides/BROWNFIELD_UPGRADE_MODE.md (complete guide) This enables systematic modernization of legacy applications without full rewrites, using specs to preserve behavior.
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR contributes improvements from the Cox Automotive fork focused on team collaboration, route-aware workflows, and systematic dependency modernization. The changes introduce multi-repo support, improved command discoverability, and a 4-phase upgrade process for Brownfield projects.
Key Changes
- Route-aware gap analysis that differentiates between Greenfield (spec completeness validation) and Brownfield (implementation gap detection) workflows
- Configurable spec output location enabling specifications to be written to a separate repository for multi-repo workflows
- Team collaboration via
/stackshift.setupcommand that installs slash commands to project repositories for team-wide access - Brownfield Upgrade Mode via
/stackshift.modernizeproviding a systematic 4-phase process for dependency modernization using specs as safety net - Complete Spec Kit command suite (
/speckit.specify,/speckit.plan,/speckit.tasks,/speckit.implement,/speckit.clarify,/speckit.analyze) for spec-driven development workflow
Reviewed Changes
Copilot reviewed 7 out of 13 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| plugin/skills/reverse-engineer/SKILL.md | Adds configuration check for spec_output_location and route-specific output directories |
| plugin/skills/gap-analysis/SKILL.md | Implements route-aware gap analysis with distinct Greenfield and Brownfield workflows |
| plugin/skills/create-specs/SKILL.md | Adds configuration check for custom spec output locations |
| plugin/skills/analyze/SKILL.md | Adds spec_output_location questionnaire and configuration documentation |
| plugin/.claude/commands/stackshift.setup.md | New command for installing slash commands to projects for team collaboration |
| plugin/.claude/commands/stackshift.modernize.md | New command implementing 4-phase dependency upgrade workflow with spec guidance |
| plugin/.claude/commands/speckit.tasks.md | New command for generating actionable task lists from implementation plans |
| plugin/.claude/commands/speckit.specify.md | New command for creating feature specifications in GitHub Spec Kit format |
| plugin/.claude/commands/speckit.plan.md | New command for creating detailed implementation plans from specifications |
| plugin/.claude/commands/speckit.implement.md | New command for systematically implementing features from specs and plans |
| plugin/.claude/commands/speckit.clarify.md | New command for resolving [NEEDS CLARIFICATION] markers in specifications |
| plugin/.claude/commands/speckit.analyze.md | New command for validating specifications against implementation |
| docs/guides/BROWNFIELD_UPGRADE_MODE.md | New comprehensive guide documenting the 4-phase upgrade process with examples |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| # Stop conditions | ||
| if (( $(echo "$COVERAGE >= $MIN" | bc -l) )) && [ $ITERATION -gt 5 ]; then | ||
| echo "✅ Min coverage reached" |
There was a problem hiding this comment.
The shell script uses bc -l for floating-point comparison on lines 117 and 121, but line 136 uses bc -l without the -l flag on line 122. For consistency and to ensure proper floating-point arithmetic, all bc invocations in this section should use the -l flag.
|
|
||
| --- | ||
|
|
||
| ## Key Differences from existing migration tools |
There was a problem hiding this comment.
The comparison header "Key Differences from existing migration tools" with lowercase "existing migration tools" is grammatically awkward. This should either be a proper name (if referring to a specific tool) or be rephrased for clarity (e.g., "Key Differences from Standard Migration Tools" or "Comparison with Other Migration Tools").
Suggested change
| ## Key Differences from existing migration tools | |
| ## Key Differences from Other Migration Tools |
Comment on lines
+581
to
+612
| ## Key Differences from existing migration tools | ||
|
|
||
| **existing migration tools :** | ||
| - 3 phases (coverage, discovery, implementation) | ||
| - Hardcoded versions (ws-scripts 22.0.0-beta.11, React 19.2.0) | ||
| - Enzyme removal required | ||
| - ESLint 9 flat config required | ||
| - Batch processing 90+ widgets | ||
|
|
||
| **StackShift modernize (Generic + Spec-driven):** | ||
| - 4 phases (includes spec validation) | ||
| - Latest versions (whatever is current) | ||
| - **Spec acceptance criteria guide test writing** | ||
| - **Specs guide breaking change fixes** | ||
| - **Continuous spec validation** | ||
| - Single repo focus | ||
|
|
||
| **What we learned from existing migration tools:** | ||
| - ✅ Phase 0 test coverage foundation | ||
| - ✅ Read-only analysis phase | ||
| - ✅ Iterative fix loop | ||
| - ✅ Autonomous test writing | ||
| - ✅ Comprehensive tracking files | ||
| - ✅ Validation before proceeding | ||
|
|
||
| **What we added for specs:** | ||
| - ✅ Spec acceptance criteria = test blueprint | ||
| - ✅ Spec impact analysis | ||
| - ✅ Spec-guided breaking change fixes | ||
| - ✅ /speckit.analyze validation | ||
| - ✅ Spec-coverage mapping | ||
|
|
There was a problem hiding this comment.
The comparison section references "existing migration tools" (with lowercase) which appears to be referring to a Cox Automotive-specific tool that was supposed to be sanitized. Line 583-589 describes what appears to be a Cox-specific tool with hardcoded versions and references to "90+ widgets" (a Cox internal pattern). Line 598 also mentions "What we learned from existing migration tools" suggesting these are Cox-internal tools. This Cox-specific content should have been removed during sanitization as mentioned in the PR description.
Comment on lines
+31
to
+34
| ## Inspiration: existing migration tools | ||
|
|
||
|
|
||
|
|
There was a problem hiding this comment.
The documentation states "Inspiration: existing migration tools" with incomplete content - this header at line 31 is followed by an empty section before "Phase 0" begins at line 35. This appears to be an incomplete removal of Cox Automotive-specific content. The section should either be completed with generic migration tool context or removed entirely.
Suggested change
| ## Inspiration: existing migration tools |
| Or for manual users: | ||
| - Check `.stackshift-state.json` for `path` field | ||
| - Follow corresponding prompt file | ||
| - **Osiris** → Use custom Osiris extraction workflow |
There was a problem hiding this comment.
The route type listed here ("Osiris") doesn't appear to be documented elsewhere in the codebase. The PR description mentions that "Osiris/CMS-web widget routes (Cox-specific)" were removed, but this reference remains. This appears to be Cox-specific code that should have been removed during sanitization.
Suggested change
| - **Osiris** → Use custom Osiris extraction workflow |
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.
Improvements
5 Commits Included:
Benefits