claude-spec

Claude Spec Plugin

A comprehensive Claude Code plugin for project specification and implementation lifecycle management.

Features

• Deep Analysis Commands - Opus 4.5 optimized, parallel agent orchestration

  • /claude-spec:deep-clean - Comprehensive code review and remediation (6-12+ specialists)
    • Focus modes: --focus=security, --focus=performance, --focus=maintainability
    • Maximum coverage: --focus=MAX / --focus=MAXALL
  • /claude-spec:deep-explore - Exhaustive codebase exploration
  • /claude-spec:deep-research - Multi-phase investigation

• Specification Lifecycle Commands - Full project planning lifecycle

  • /claude-spec:plan - Strategic project planning with Socratic requirements elicitation
    • Flags: --inline, --no-worktree, --no-branch
  • /claude-spec:approve - Review and approve/reject specs before implementation
  • /claude-spec:implement - Implementation progress tracking with document sync
  • /claude-spec:status - Portfolio and project status monitoring
  • /claude-spec:complete - Project close-out and archival
  • /claude-spec:report-issue - Investigate and create AI-actionable GitHub issues
    • Flags: --type bug|feat|docs|chore|perf, --repo owner/repo

• Worktree Commands - Git worktree automation

  • /claude-spec:worktree-create - Create worktrees with Claude agents
  • /claude-spec:worktree-status - View worktree status
  • /claude-spec:worktree-cleanup - Clean up worktrees

• Approval Workflow - Governance controls

  • SCENARIOS.md validation — holdout scenarios required for feature/system specs
  • PreToolUse hook (hooks/check-approved-spec.sh) — optional governance gate (disabled by default)
  • Audit trail with approver identity, timestamps, and shapiro_level
  • Rejection workflow with spec preservation

• Parallel Agent Orchestration - Built-in directives for parallel specialist agent usage

Installation

From GitHub (Recommended)

/plugin marketplace add asymblinc/claude-spec
/plugin install cs@claude-spec-marketplace

From Local Clone (Development)

git clone https://github.com/asymblinc/claude-spec.git
cd claude-spec
claude plugins install --marketplace ./.claude-plugin/marketplace.json cs

Usage

Start a New Project

/claude-spec:plan my new feature idea

This initiates Socratic requirements elicitation, parallel research, and generates:

• docs/spec/active/YYYY-MM-DD-project-slug/
  • README.md (shapiro_level in frontmatter)
  • REQUIREMENTS.md (with Discovery Summary and Scope Exclusions)
  • SCENARIOS.md (holdout validation — hidden from implementer during build)
  • ARCHITECTURE.md
  • IMPLEMENTATION_PLAN.md
  • DECISIONS.md
  • RESEARCH_NOTES.md
  • CHANGELOG.md

Plan Flags

Flag	Description
--inline	Skip worktree and branch creation, work in current directory
--no-worktree	Skip worktree creation only
--no-branch	Skip branch creation only

Triage Gate (Step 0.5)

Before elicitation, /plan now classifies work type via an AskUserQuestion:

Type	Shapiro Level	Protocol
Fix / Bug	2	Evidence-first → lightweight spec
Feature	4	Full elicitation (5 questions incl. scope exclusions) + SCENARIOS.md
System / Architecture	5	Full elicitation + system context reference + SCENARIOS.md

Approve the Specification

/claude-spec:approve project-slug

Reviews the spec and records approval decision:

• Approve: Updates status, records approver and timestamp
• Request Changes: Adds feedback, keeps in review status
• Reject: Moves spec to docs/spec/rejected/

Track Implementation Progress

/claude-spec:implement project-slug
/claude-spec:implement SPEC-2025-12-25-001
/claude-spec:implement docs/spec/active/2025-12-25-my-project/
/claude-spec:implement --help

Creates and maintains PROGRESS.md, syncs checkboxes across documents. Shows warning if spec not approved (advisory, non-blocking).

Features:

• Checkbox Sync: Automatically syncs task status between PROGRESS.md and IMPLEMENTATION_PLAN.md
• Extended Argument Hints: Rich help output with argument patterns and examples
• Validation with Suggestions: Typo detection with "Did you mean...?" suggestions (Levenshtein ≤3)

Check Project Status

/claude-spec:status              # Current project status
/claude-spec:status --list       # List all active projects
/claude-spec:status --expired    # Find expired plans

Close Out Project

/claude-spec:complete project-slug

Generates RETROSPECTIVE.md, archives to docs/spec/completed/.

Report an Issue

/claude-spec:report-issue
/claude-spec:report-issue --type bug
/claude-spec:report-issue --type feat --repo asymblinc/claude-spec