claude-code-orchestrator-kit 1.0.0

package/.claude/commands/health-security.md

@@ -0,0 +1,297 @@
+---
+description: Security vulnerability detection and remediation workflow with full cycle management
+---
+
+# Security Health Check
+
+> **PATTERN**: Agent-based orchestration (see `docs/Agents Ecosystem/AGENT-ORCHESTRATION.md` for details)
+
+Complete security scanning and vulnerability fixing workflow with orchestrator-worker coordination.
+
+**What it does:**
+- Full security scan (SQL injection, XSS, auth issues, RLS policies, secrets)
+- Staged fixing (critical → high → medium → low)
+- Quality gates after each stage
+- Verification scan
+- Up to 3 iterations if issues remain
+- Comprehensive final report
+
+**No configuration needed** - runs comprehensive security audit always.
+
+---
+
+## Your Task
+
+### Step 1: Phase 0 - Invoke Orchestrator (Pre-flight)
+
+Use Task tool to invoke security-orchestrator for pre-flight validation:
+
+```
+subagent_type: "security-orchestrator"
+description: "Security orchestrator pre-flight"
+prompt: "Execute Phase 0: Pre-flight Validation
+
+Tasks:
+1. Validate environment (package.json, scripts, git status)
+2. Initialize progress tracking via TodoWrite
+3. Initialize iteration tracking (iteration=1, max=3)
+4. Create .tmp/current/plans/security-detection.json for rollback tracking
+5. Report pre-flight status
+
+IMPORTANT: After completing pre-flight, create .tmp/current/plans/security-detection.json and return control to main session.
+
+Return the following information:
+- Pre-flight status (✅/⛔)
+- Environment validation results
+- Plan file path created
+- Ready for next phase: true/false
+"
+```
+
+**Then**: Wait for orchestrator to return.
+
+---
+
+### Step 2: Phase 1 - Invoke security-scanner (Detection)
+
+After orchestrator returns:
+
+1. **Read plan file** to confirm it was created:
+   ```
+   Use Read tool: .tmp/current/plans/security-detection.json
+   Verify nextAgent === "security-scanner"
+   ```
+
+2. **Invoke security-scanner** using Task tool:
+   ```
+   subagent_type: "security-scanner"
+   description: "Security detection phase"
+   prompt: "Execute vulnerability detection based on plan file: .tmp/current/plans/security-detection.json
+
+Read the plan file and execute comprehensive vulnerability detection:
+- Scan entire codebase
+- Categorize by priority (critical → high → medium → low)
+- Generate security-scan-report.md
+
+Return to main session when complete."
+   ```
+
+**Then**: Wait for security-scanner to return with report.
+
+---
+
+### Step 3: Quality Gate 1 - Resume Orchestrator (Validate Detection)
+
+After security-scanner returns:
+
+1. **Resume orchestrator** for validation using Task tool:
+   ```
+   subagent_type: "security-orchestrator"
+   description: "Validate vulnerability detection"
+   prompt: "Execute Quality Gate 1: Detection Validation
+
+Phase: Validate security-scanner output
+
+Tasks:
+1. Verify security-scan-report.md exists
+2. Validate report structure (required sections)
+3. Parse vulnerability counts by priority
+4. Run type-check validation (non-blocking warning)
+5. Report gate results
+
+IMPORTANT: After validation, if vulnerabilitys found:
+- Create .tmp/current/plans/security-fixing-{priority}.json for critical priority (or highest available)
+- Return control to main session
+
+If no vulnerabilitys found or all gates fail:
+- Skip to final summary
+- Return control
+
+Return the following:
+- Gate status (✅ PASSED / ⛔ FAILED / ⚠️ WARNINGS)
+- Security counts by priority
+- Next phase: fixing-critical / fixing-high / final-summary
+- Plan file created (if applicable)
+"
+   ```
+
+**Then**: Wait for orchestrator validation results.
+
+---
+
+### Step 4: Phase 2-5 - Fixing Stages (Iterative)
+
+After orchestrator returns with fixing plan:
+
+**For each priority level** (critical → high → medium → low):
+
+1. **Check if this priority has vulnerabilitys**:
+   - Read orchestrator response
+   - If orchestrator says "skip to next priority" → continue loop
+   - If orchestrator says "final summary" → go to Step 5
+
+2. **Read fixing plan**:
+   ```
+   Use Read tool: .tmp/current/plans/security-fixing-{priority}.json
+   Verify nextAgent === "vulnerability-fixer"
+   Verify config.priority === "{current-priority}"
+   ```
+
+3. **Invoke vulnerability-fixer** using Task tool:
+   ```
+   subagent_type: "vulnerability-fixer"
+   description: "Fix {priority} vulnerabilitys"
+   prompt: "Execute vulnerability fixing based on plan file: .tmp/current/plans/security-fixing-{priority}.json
+
+Read the plan file and fix vulnerabilitys for priority: {priority}
+- Read security-scan-report.md for vulnerability list
+- Fix vulnerabilitys one by one
+- Log changes to .vulnerability-changes.json
+- Update security-fixes-implemented.md (consolidated report)
+
+Return to main session when complete."
+   ```
+
+4. **Resume orchestrator** for validation:
+   ```
+   subagent_type: "security-orchestrator"
+   description: "Validate {priority} fixes"
+   prompt: "Execute Quality Gate 2: Fixes Validation for priority={priority}
+
+Tasks:
+1. Verify security-fixes-implemented.md exists
+2. Run type-check (BLOCKING)
+3. Run build (BLOCKING)
+4. Parse fix success rate
+5. Check if retry needed (if < 80% success)
+
+If validation PASSES and more priorities remain:
+- Create next .tmp/current/plans/security-fixing-{priority}.json
+- Return control
+
+If validation FAILS:
+- Provide rollback instructions
+- Return control with error
+
+If all priorities complete:
+- Proceed to verification phase
+- Return control
+
+Return:
+- Gate status
+- Fix success rate
+- Next phase: fixing-{next-priority} / verification / final-summary
+"
+   ```
+
+5. **Repeat** for next priority level.
+
+---
+
+### Step 5: Phase 6 - Verification
+
+After all fixing stages complete:
+
+1. **Resume orchestrator** for verification:
+   ```
+   subagent_type: "security-orchestrator"
+   description: "Create verification plan"
+   prompt: "Execute Phase 6: Verification Preparation
+
+Create .tmp/current/plans/security-verification.json for re-scanning codebase.
+
+Return control with plan file path."
+   ```
+
+2. **Invoke security-scanner** for verification:
+   ```
+   subagent_type: "security-scanner"
+   description: "Verification scan"
+   prompt: "Execute verification scan based on: .tmp/current/plans/security-verification.json
+
+Re-scan codebase to verify fixes. Overwrites security-scan-report.md.
+
+Return when complete."
+   ```
+
+3. **Resume orchestrator** for verification validation:
+   ```
+   subagent_type: "security-orchestrator"
+   description: "Validate verification"
+   prompt: "Execute Quality Gate 3: Verification Validation
+
+Compare original security-scan-report.md (baseline) with new scan:
+- Count vulnerabilitys fixed
+- Check if new vulnerabilitys introduced
+- Determine if iteration needed
+
+Return:
+- Verification status
+- Securitys remaining
+- Iteration decision: iterate / complete
+"
+   ```
+
+---
+
+### Step 6: Final Summary
+
+After all phases complete:
+
+1. **Resume orchestrator** for final summary:
+   ```
+   subagent_type: "security-orchestrator"
+   description: "Generate final summary"
+   prompt: "Execute Phase 8: Final Summary
+
+Generate comprehensive security-orchestration-summary.md:
+- All vulnerabilitys detected
+- All vulnerabilitys fixed
+- Success rates by priority
+- Validation results
+- Iteration summary
+- Cleanup instructions
+
+Return final summary."
+   ```
+
+2. **Display results** to user:
+   ```
+   Read security-orchestration-summary.md
+   Display key metrics
+   Show validation status
+   List next steps
+   ```
+
+---
+
+## Example Usage
+
+```bash
+# Run complete vulnerability workflow
+/health-vulnerabilitys
+```
+
+---
+
+## Architecture Notes
+
+**Orchestrator Role**:
+- Creates plan files
+- Validates worker outputs
+- Returns control to main session
+- NO direct worker invocation
+
+**Main Session Role** (this command):
+- Reads plan files
+- Invokes workers via Task tool
+- Resumes orchestrator for validation
+- Manages full cycle
+
+**Worker Role**:
+- Reads plan file
+- Executes work
+- Generates report
+- Returns to main session
+
+This pattern follows Claude Code's actual capabilities (no auto-invoke).

package/.claude/commands/push.md

@@ -0,0 +1,21 @@
+---
+description: Automated release management with version bumping and changelog updates
+argument-hint: [patch|minor|major]
+---
+
+Execute the release automation script with auto-confirmation for Claude Code.
+
+**Features:**
+- Auto-syncs package.json versions with latest git tag (prevents version conflicts)
+- Analyzes commits since last release
+- Auto-detects version bump type from conventional commits
+- Generates CHANGELOG entries
+- Updates all package.json files
+- Creates git tag and pushes to GitHub
+- Full rollback support on errors
+
+**Usage:**
+
+# Navigate to project root first
+PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")
+cd "$PROJECT_ROOT" && bash .claude/scripts/release.sh $ARGUMENTS --yes

package/.claude/commands/speckit.analyze.md

@@ -0,0 +1,184 @@
+---
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.md`.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements
+- Non-Functional Requirements
+- User Stories
+- Edge Cases (if present)
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Phases
+- Technical constraints
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `.specify/memory/constitution.md` for principle validation
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Non-functional requirements not reflected in tasks (e.g., performance, security)
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+## Specification Analysis Report
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+**Coverage Summary Table:**
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|-----------------|-----------|----------|-------|
+
+**Constitution Alignment Issues:** (if any)
+
+**Unmapped Tasks:** (if any)
+
+**Metrics:**
+
+- Total Requirements
+- Total Tasks
+- Coverage % (requirements with >=1 task)
+- Ambiguity Count
+- Duplication Count
+- Critical Issues Count
+
+### 7. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `/speckit.implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
+
+### 8. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+## Context
+
+$ARGUMENTS