feat: integrate upstream spec-kit improvements with enhanced Spec-Ops planning

.claude/commands/detail.md

@@ -0,0 +1,79 @@
+---
+name: detail
+description: "Create detailed specifications for selected tasks. This follows the tasks command in the Spec-Driven Development lifecycle."
+---
+
+Create detailed specifications for selected tasks from the tasks.md file.
+
+This command follows the `/tasks` command in the Spec-Driven Development lifecycle to provide granular task details.
+
+Given the task selection provided as an argument, do this:
+
+1. Run `scripts/check-task-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
+
+2. Load and validate the tasks.md file:
+   - Read tasks.md from the feature directory
+   - Parse all task entries (T001, T002, etc.)
+   - Validate task numbering and structure
+   - Extract milestone organization
+
+3. Parse task selection from arguments:
+   - **Single task**: "T005" → detail only T005
+   - **Task range**: "T004-T007" → detail T004, T005, T006, T007
+   - **Milestone**: "Milestone 1" → detail all tasks in Milestone 1
+   - **Multiple selections**: "T001,T005-T007,Milestone 2" → combine selections
+   - **All tasks**: "all" → detail every task in tasks.md
+
+4. Load supporting design documents for context:
+   - Always read plan.md for tech stack and architecture decisions
+   - IF EXISTS: Read data-design.md for entity and state machine details
+   - IF EXISTS: Read architecture.md for service structure and patterns
+   - IF EXISTS: Read contracts/ for API specifications
+   - IF EXISTS: Read research.md for technical decisions and rationale
+   - IF EXISTS: Read quickstart.md for user scenarios and acceptance criteria
+
+5. Create tasks directory structure:
+   - Create `FEATURE_DIR/tasks/` directory if it doesn't exist
+   - For each selected task, create `FEATURE_DIR/tasks/T###-task-name.md`
+   - Use task ID and kebab-case description for filename
+
+6. Generate detailed task specifications:
+   - Use `/templates/task-detail-template.md` as the base
+   - Fill in all sections with specific details for each task:
+     * **Title**: Clear, action-oriented task title
+     * **Description**: Detailed explanation of what needs to be accomplished
+     * **Implementation Details**: Step-by-step technical approach
+     * **Acceptance Criteria**: Specific, testable success conditions
+     * **Dependencies**: Prerequisites and blocking tasks
+     * **Files Affected**: Exact file paths that will be created/modified
+     * **Testing Requirements**: How to verify the task is complete
+     * **Status Tracking**: Current status and progress indicators
+
+7. Task detail generation rules:
+   - **Test tasks**: Include test structure, assertions, mock requirements
+   - **Implementation tasks**: Include code structure, patterns, integration points
+   - **Integration tasks**: Include connection details, configuration, error handling
+   - **Documentation tasks**: Include content outline, format requirements, examples
+
+8. Cross-reference with design documents:
+   - Link to relevant sections in plan.md, data-design.md, architecture.md
+   - Include specific contract specifications for API tasks
+   - Reference entity definitions for model tasks
+   - Include user story context for integration tests
+
+9. Validate completeness:
+   - All selected tasks have detailed specifications
+   - All implementation details are actionable
+   - All acceptance criteria are testable
+   - All dependencies are clearly identified
+   - File paths are consistent with project structure
+
+10. Update tasks.md with detailed task tracking:
+    - Mark **Detailed**: Yes for each task that gets detailed specifications
+    - Update Task Registry section with latest detailed task count
+    - Maintain task numbering consistency
+    - Do NOT detail tasks that are simple or well-understood
+
+Context for task detailing: {ARGS}
+
+The detailed task files should provide enough information for any developer to implement the task without additional context or clarification.

.claude/commands/plan.md

@@ -0,0 +1,44 @@
+---
+name: plan
+description: "Plan how to implement the specified feature. This is the second step in the Spec-Driven Development lifecycle."
+---
+
+Plan how to implement the specified feature.
+
+This is the second step in the Spec-Driven Development lifecycle.
+
+Given the implementation details provided as an argument, do this:
+
+1. Run `scripts/setup-plan.sh --json` from the repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. All future file paths must be absolute.
+2. Read and analyze the feature specification to understand:
+   - The feature requirements and user stories
+   - Functional and non-functional requirements
+   - Success criteria and acceptance criteria
+   - Any technical constraints or dependencies mentioned
+   - Service boundaries and architecture implications
+   - Data storage and persistence requirements
+   - Interface and integration points
+
+3. Read the constitution at `/memory/constitution.md` to understand constitutional requirements.
+
+4. Execute the implementation plan template:
+   - Load `/templates/plan-template.md` (already copied to IMPL_PLAN path)
+   - Set Input path to FEATURE_SPEC
+   - Run the Execution Flow (main) function steps 1-10
+   - The template is self-contained and executable
+   - Follow error handling and gate checks as specified
+   - Let the template guide artifact generation in $SPECS_DIR:
+     * Phase 0 generates research.md
+     * Phase 1 generates architecture.md, data-design.md, deployment.md, contracts/, quickstart.md
+     * Phase 2 generates tasks.md
+   - Incorporate user-provided details from arguments into Technical Context: {ARGS}
+   - Update Progress Tracking as you complete each phase
+
+5. Verify execution completed:
+   - Check Progress Tracking shows all phases complete
+   - Ensure all required artifacts were generated
+   - Confirm no ERROR states in execution
+
+6. Report results with branch name, file paths, and generated artifacts.
+
+Use absolute paths with the repository root for all file operations to avoid path issues.

.claude/commands/specify.md

@@ -0,0 +1,17 @@
+---
+name: specify
+description: "Start a new feature by creating a specification and feature branch. This is the first step in the Spec-Driven Development lifecycle."
+---
+
+Start a new feature by creating a specification and feature branch.
+
+This is the first step in the Spec-Driven Development lifecycle.
+
+Given the feature description provided as an argument, do this:
+
+1. Run the script `scripts/create-new-feature.sh --json "{ARGS}"` from repo root and parse its JSON output for BRANCH_NAME and SPEC_FILE. All file paths must be absolute.
+2. Load `templates/spec-template.md` to understand required sections.
+3. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+4. Report completion with branch name, spec file path, and readiness for the next phase.
+
+Note: The script creates and checks out the new branch and initializes the spec file before writing.

.claude/commands/tasks.md

@@ -0,0 +1,88 @@
+---
+name: tasks
+description: "Break down the plan into executable tasks. This is the third step in the Spec-Driven Development lifecycle."
+---
+
+Break down the plan into executable tasks organized by milestones.
+
+This is the third step in the Spec-Driven Development lifecycle.
+
+Given the context provided as an argument, do this:
+
+1. Run `scripts/check-task-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
+2. Load and analyze available design documents:
+   - Always read plan.md for tech stack and libraries
+   - IF EXISTS: Read data-design.md for entities and state machines
+   - IF EXISTS: Read architecture.md for services and structure
+   - IF EXISTS: Read contracts/ for API endpoints
+   - IF EXISTS: Read research.md for technical decisions
+   - IF EXISTS: Read quickstart.md for test scenarios
+
+   Note: Not all projects have all documents. For example:
+   - CLI tools might not have contracts/
+   - Simple libraries might not need data-design.md
+   - Generate tasks based on what's available
+
+3. Identify milestones based on feature scope:
+   - **Small features** (1-5 endpoints): Single milestone with all functionality
+   - **Medium features** (6-15 endpoints): Split by logical feature groups
+   - **Large features** (16+ endpoints): Split by user workflows or service boundaries
+   - Each milestone should deliver a working, testable increment
+
+4. Generate milestone-based tasks following the template:
+   - Use `/templates/tasks-template.md` as the base
+   - Organize tasks by milestone phases:
+     * **Milestone 1 Tests**: Contract tests and integration tests for first milestone
+     * **Milestone 1 Implementation**: Core implementation for first milestone
+     * **Milestone 2 Tests**: Tests for second milestone (if needed)
+     * **Milestone 2 Implementation**: Implementation for second milestone
+     * Continue pattern for additional milestones
+     * **Final Polish**: Cross-milestone cleanup, performance, documentation
+
+5. Task generation rules:
+   - Group related contracts/entities into logical milestones
+   - Each milestone: Tests first, then implementation
+   - Each contract file → contract test task marked [P]
+   - Each entity in data-design → model creation task marked [P]
+   - Each endpoint → implementation task (not parallel if shared files)
+   - Each user story → integration test marked [P]
+   - Different files = can be parallel [P]
+   - Same file = sequential (no [P])
+
+6. Milestone ordering principles:
+   - Foundation services and models in Milestone 1
+   - Core user workflows in early milestones
+   - Advanced features in later milestones
+   - Administrative/management features last
+   - Each milestone builds on previous ones
+
+7. Include parallel execution examples:
+   - Group [P] tasks that can run together within each milestone
+   - Show actual Task agent commands for each milestone phase
+
+8. Create FEATURE_DIR/tasks.md with:
+   - Correct feature name from implementation plan
+   - Task Registry section with last task ID and status summary
+   - Milestone-organized structure with clear boundaries
+   - Numbered tasks (T001, T002, etc.) across all milestones with status tracking
+   - Clear file paths for each task
+   - Dependency notes within and between milestones
+   - Parallel execution guidance per milestone
+   - Task status management guidelines
+
+9. Ensure proper task numbering:
+   - Start with T001 and increment sequentially
+   - No gaps in task numbering sequence
+   - Update Task Registry with last task ID used
+   - Provide foundation for future task additions
+
+10. Define milestone branch assignments:
+   - Assign each task to its appropriate predefined branch
+   - Document branch strategy and predefined names in tasks.md
+   - Include branch assignment in each task's metadata
+   - Ensure branch names follow convention: [###-feature-name]/milestone-N
+   - Note: Branches are created on-demand, not automatically
+
+Context for task generation: {ARGS}
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.

AGENTS.md

@@ -0,0 +1,19 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+Core CLI logic lives in `src/specify_cli`, exposing the `specops` Typer app defined in `__init__.py`. Shell automation for task and milestone workflows sits in `scripts/`, while reusable authoring templates are stored under `templates/`. Long-form guidance and DocFX content are in `docs/`, reference materials for agent memories reside in `memory/`, and rich media assets live in `media/`. Keep new modules colocated with their domain resources so bootstrapped projects inherit a coherent layout.
+
+## Build, Test, and Development Commands
+Install dependencies with `uv sync`, which pins toolchains via `pyproject.toml` and `uv.lock`. Run the CLI locally using `uv run specops --help` to sanity-check command registration. Exercise the bootstrap flow with `uv run specops init demo --here --ai claude --ignore-agent-tools`, swapping agent flags as needed. Convenience scripts in `scripts/` are executable with `bash scripts/update-task-status.sh` (or similar) and should remain POSIX-compliant.
+
+## Coding Style & Naming Conventions
+Follow PEP 8 defaults: four-space indentation, `snake_case` for functions, `PascalCase` for Typer command classes, and uppercase module constants. Prefer type hints and keep Rich/typer output formatting centralized through helper functions rather than scattered print statements. When updating templates or memory files, preserve the concise, agent-ready tone and avoid introducing non-ASCII characters unless already present.
+
+## Testing Guidelines
+There is no packaged test suite yet, so each change must be validated by exercising the CLI commands above and confirming generated project scaffolding looks correct. When adding automated coverage, place tests under `tests/` and use `pytest` with `typer.testing.CliRunner` to simulate command invocations. Keep fixtures lightweight and mirror real template paths so regressions surface early. Document notable manual verification steps in the pull request for future automation.
+
+## Commit & Pull Request Guidelines
+Commits follow a Conventional Commits style (`feat:`, `fix:`, etc.), so use the imperative mood and scope prefixes where helpful. Group related work into focused commits, run `uv run specops --help` before staging, and update docs or templates alongside behavior changes. Pull requests should describe the scenario, list manual or automated checks, and link any relevant issues; screenshots or terminal captures are encouraged when they explain CLI UX changes. Review CONTRIBUTING.md and SECURITY.md before proposing substantial process updates.
+
+## Agent & Template Updates
+Changes that affect AI agent workflows must update the matching files in `templates/` and any supporting guidance in `memory/constitution.md`. Call out downstream impacts on bootstrap flows or generated documentation so maintainers can refresh published artifacts promptly.

CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to Spec Ops will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Cross-platform script support (PowerShell and Bash variants)
+- Simplified plan template structure based on upstream
+- Enhanced Claude Code command support
+
+## [0.0.5] - 2025-09-16
+
+### Added
+- Claude Code command support
+- Task management system with milestone tracking
+- Advanced planning with deployment, security, and performance
+- Branch naming and creation features
+- Task counter and status updates
+
+### Fixed
+- GitHub fallback for template download
+
+### Changed
+- Updated banner color theme to orange-to-black gradient
+- Renamed from spec-kit to spec-ops

CONTRIBUTING.md

@@ -1,6 +1,6 @@
-## Contributing to Spec Kit
+## Contributing to Spec Ops
 
-Hi there! We're thrilled that you'd like to contribute to Spec Kit. Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE).
+Hi there! We're thrilled that you'd like to contribute to Spec Ops. Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE).
 
 Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
 
@@ -17,7 +17,7 @@ These are one time installations required to be able to test your changes locall
 
 1. Fork and clone the repository
 1. Configure and install the dependencies: `uv sync`
-1. Make sure the CLI works on your machine: `uv run specify --help`
+1. Make sure the CLI works on your machine: `uv run specops --help`
 1. Create a new branch: `git checkout -b my-branch-name`
 1. Make your change, add tests, and make sure everything still works
 1. Test the CLI functionality with a sample project if relevant

Notes.md

@@ -0,0 +1,17 @@
+# Ideas
+
+## High Prio
+* extremem short context 
+  always following minimal hierarchical to do list during implementation
+    as soon as encountering bug/ implementation error, spawn new bug chat, that just tries to resolve this, tries around, debugs, logs, ..., this fills up context very fast
+    and should therefore not disturb the implementation agent, unless it finds out a fundamental flaw in the implementation plan.
+
+
+* different task types, bug, test implementation, test resolution, refactor, chore, pr, merge, ....   to map to specific agents? tools?
+
+## Medium prio
+improved parallelization of tasks? tool to fetch all parallel available task, importance, select manually from, usable by agent's via script? just simple point to task detail description or return tile description
+    so implementation agents like claude-flow can work on it!
+
+## Low Prio
+extend to ci/cd, cloud deployment, data!!! flow management, ML !!!