enhance with open-spec brownfield concepts #1044
Closed
+14,721
−299
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
…s/spec-kit
- Add install_claude_commands() function to copy command templates
- Integrate Claude command installation into init workflow
- Add tracker step for command installation progress
- Update next steps message to inform users of installed commands
- Only install commands when --ai claude is selected
- Support configurable repo owner/name/branch for template downloads
- Fixed package configuration to include templates/ directory in wheel - Updated install_claude_commands function to find templates in multiple locations - Added MANIFEST.in for better template file inclusion - Bumped version to 0.0.4 This resolves the 'templates/commands not found' error when running uvx --from git+https://github.com/hcnimi/spec-kit.git@prps-spec specify init --here --ai claude
Update release script to install Claude commands to .claude/commands/spec-kit
instead of .claude/commands for better organization
- Add transform_branch_structure() to detect and fix raw branch downloads
- Move memory/, scripts/, templates/ to .specify/ directory structure
- Filter scripts by variant (sh/ps) and remove unused variants
- Generate AI-specific commands from templates/commands/*.md files
- Apply transformation automatically after branch extraction
- Ensure consistent folder pattern regardless of download source
Prevent overwriting user documentation in specs/ when running
install command with --here flag. Framework files are still
updated while preserving custom documentation.
…dation
Update regex patterns in bash and PowerShell scripts to allow lowercase
ticket prefixes (e.g., proxy-929) instead of requiring uppercase only.
Also make setup-plan.sh executable.
Add deep analysis prompts to strategic decision points in: - /specify command Phase 1 research - /plan command execution flow steps 2-3 - /review command context engineering section - /debug command root cause analysis Enhances reasoning quality at critical architectural and debugging decisions.
…jects - Add --force flag to init command (only usable with --here) - Force overwrites existing directories/files instead of merging - Enhanced user warnings for force operations - Preserves specs folder unless template doesn't contain it - Enables updating projects with fresh template versions from releases 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
- Change from 001-... to JIRA-123-feature-name.md pattern - Updated create-new-feature.sh for flat file structure - Updated common.sh get_feature_paths() function - All spec-related files now use JIRA key prefix
Create new constitution.md command template for interactive constitution
management with placeholder handling, version control, and dependency
propagation features.
The main change is converting the JIRA issue key format from uppercase (PROJ-123) to lowercase
(proj-123) throughout all documentation, templates, and scripts. This affects:
- Documentation files (README.md, quickstart.md)
- Script functionality for branch naming and file structure
- Template examples and command outputs
- PowerShell and bash script consistency
The changes also include improvements to the init.sh script with better constitution.md
preservation handling and more flexible copy operations.
Introduces /decompose command to break large features (>500 LOC) into
atomic capabilities (200-500 LOC each), enabling:
- Atomic PRs instead of massive monolithic PRs
- Parallel development across independent capabilities
- Faster code reviews (1-2 days vs 7+ days)
- TDD at manageable scope (RED-GREEN-REFACTOR within 500 LOC)
Changes:
- Add decompose-template.md for capability breakdown structure
- Add capability-spec-template.md for scoped specifications
- Add /decompose command and supporting scripts (bash/PowerShell)
- Modify /plan to support --capability flag for scoped planning
- Add LOC budget tracking (200-500 LOC targets) to plan/tasks templates
- Update create-new-feature.sh with --capability mode
- Document workflows in README.md and spec-driven.md
Completes integration of decompose functionality (from commit 5d8e32b) into constitutional framework. Article VIII establishes: - 200-500 LOC per capability/PR targets - /decompose workflow for >500 LOC features - Justification requirements for exceptions - Benefits: faster reviews, manageable TDD, parallel development Updated constitution_update_checklist.md with Article VIII guidance and sync status reflecting 2025-10-05 decompose changes.
- Add --capability flag to setup-plan.sh/ps1 to create separate branches per capability
- Update /plan command to create branch username/jira-123.feature-cap-001 for each
capability
- Document atomic PR workflow: cap-XXX → main (200-500 LOC per PR)
- Update templates to reflect branch-per-capability model
- Enable parallel development with fast review cycles (1-2 days vs 7+ days)
Problem: Previous implementation created ONE branch for ALL capabilities,
resulting in massive PRs (1500+ LOC) defeating atomic PR goals.
Solution: Each capability now gets dedicated branch from parent, enabling:
- True atomic PRs (200-500 LOC each)
- Independent merges to main
- Team parallelization across capabilities
- Add --capability flag to setup-plan.sh/ps1 to create separate branches
per capability
- Update /plan command to create branch username/jira-123.feature-cap-001
for each capability
- Fix critical bug: /plan command now passes {ARGS} to script (was missing,
causing branch creation to fail)
- Document atomic PR workflow: cap-XXX → main (200-500 LOC per PR)
- Update templates to reflect branch-per-capability model
- Enable parallel development with fast review cycles (1-2 days vs 7+ days)
Problem: Previous implementation created ONE branch for ALL capabilities,
resulting in massive PRs (1500+ LOC) defeating atomic PR goals.
Solution: Each capability now gets dedicated branch from parent, enabling:
- True atomic PRs (200-500 LOC each)
- Independent merges to main
- Team parallelization across capabilities
Bugfix: The /plan command's YAML frontmatter wasn't passing user arguments
to setup-plan.sh, preventing capability branch creation entirely.
- Add capability branch detection to bash/PowerShell scripts
- Implement check-task-prerequisites scripts for /tasks command
- Update /implement to use capability-aware paths
- Document atomic PR workflow in README-WORKFLOW-GUIDE.md
- Add decompose workflow to docs/quickstart.md
Enables /tasks and /implement commands to automatically detect
capability branches (username/jira-123.feature-cap-001) and work
with capability subdirectories for atomic PRs (200-500 LOC each)?
Update regex patterns in common.sh to match capability IDs with optional
letter suffix (e.g., cap-002a). Fixes issue where /plan created sibling
directories instead of subdirectories for capabilities with letter suffixes.
Fixes path duplication bug causing .specify/.specify/ errors when
running /implement command. Template paths should be relative (scripts/,
memory/) to allow init.sh substitution to add .specify/ prefix for
initialized projects while working directly in spec-kit repo.
…own generation commands - Add UTF-8 encoding directive to /specify command (spec.md generation) - Add UTF-8 encoding to /plan template (research.md, data-model.md, quickstart.md, contracts) - Add UTF-8 encoding to /tasks command (tasks.md generation) - Add UTF-8 encoding to /decompose command (capabilities.md and capability specs) - Add UTF-8 encoding to /product-vision command (product-vision.md generation) - Add UTF-8 encoding to /constitution command (constitution.md updates) Fixes inconsistent encoding issues across platforms by explicitly instructing Claude Code to use UTF-8 when writing all generated markdown files.
- Move all AI assistant commands to spec-kit/ subfolders to prevent overwriting user's custom
commands
- Update Gemini, Copilot, and Cursor to match Claude's subfolder isolation pattern
- Increase default search depth from 2 to 3 for multi-repo mode
- Add documentation comment explaining subfolder protection strategy
… tests
Replace single 500 LOC limit with separate tracking:
- Implementation: 200-500 LOC (max 500)
- Tests: 200-500 LOC (max 500)
- Total: 400-1000 LOC (max 1000)
This prevents test code from ballooning without limits while maintaining
fast PR review times. Justification now required if ANY limit exceeded.
- Auto-discover repos with convention-based targeting
- Centralized specs/ with branches in target repos
- Workspace initialization via
- Backward compatible with single-repo mode
- Changed workspace config location from .spec-kit/ to .specify/
- Updated all scripts, docs, and Python CLI references
- Unified naming convention across repo and workspace contexts
- Added comprehensive comparison guide for batch vs workspace modes
- Created multi-repo-modes-comparison.md with visual decision trees
This ensures consistent use of .specify/ directory throughout spec-kit,
eliminating confusion between .spec-kit (workspace) and .specify (repo).
The presence of workspace.yml now serves as the discriminator.
…thods
Add 'Initialization Methods' section explaining both ways to initialize
a multi-repo workspace:
- Python CLI: specify init --workspace (user-friendly wrapper)
- Bash script: init-workspace.sh . (direct, no installation)
This clarifies the confusion around --workspace flag usage and helps users
understand that the Python CLI wraps the bash script, providing identical
functionality with better UX.
…quirements
- Change ideal LOC from 400-1000 range to ~1000 (800-1200 acceptable)
- Update implementation target from 200-500 to 400-600 LOC
- Update test target from 200-500 to 400-600 LOC
- Add minimum test-to-implementation ratio requirement (≥0.8:1, ideal ≥1:1)
- Replace separate impl/test limits with unified total + ratio validation
- Update all templates and command docs for consistency (9 files)
Promotes better test coverage with 1:1 ratio while maintaining
manageable capability sizes for atomic PRs and fast reviews.
Automatically detect GitHub host per repository and enforce Jira key
requirements accordingly. Enables mixed workspaces with conditional
Jira policies based on GitHub host (github.marqeta.com vs github.com).
Changes:
- Auto-detect GitHub host during workspace initialization
- Add github_host and require_jira fields to workspace.yml
- Strip Jira keys for convention matching (proj-123.backend-api → backend-)
- Prompt for Jira key when targeting repos that require it
- Add comprehensive documentation and examples
- Support enterprise GitHub hosts (github.{company}.com)
Implementation:
- workspace-discovery.sh: GitHub host detection and Jira requirement logic
- create-new-feature.sh: Per-repo Jira key validation in workspace mode
- multi-repo-workspaces.md: New section on GitHub host conventions
- example-workspace.yml: Mixed GitHub host example configuration
- specify.md: Command template updates with Jira key examples
Add adaptive depth system to spec-kit with three modes: - Quick mode (<200 LOC): minimal spec for bug fixes - Lightweight mode (200-800 LOC): compact spec for simple features - Full mode (800+ LOC): comprehensive spec (existing default) Changes: - Add mode detection to /specify command with AI-guided questions - Create spec-template-quick.md for minimal specifications - Create spec-template-lightweight.md for compact specifications - Create plan-template-lightweight.md for essential planning - Add template selection logic to create-new-feature.sh based on --mode flag - Add Change History section to spec-template.md for delta tracking - Create /archive command to move completed features to archive/ - Update README-WORKFLOW-GUIDE.md with adaptive workflow documentation Preserves all existing functionality: - All 12 slash commands work unchanged without flags - Workspace mode fully compatible - Capability mode fully compatible - Jira integration unchanged - Atomic PR workflow unchanged - Backward compatible (opt-in via flags) Benefits: - 80% of OpenSpec benefits without integration complexity - Single mental model with progressive disclosure - Reduces token consumption for simple changes - Beginner-friendly guided mode selection - Fast path for bug fixes and small features
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
No description provided.