exosuit / scaffold

# Exosuit

> A drop-in development framework for Claude Code with structured sprint workflows, TDD practices, quality gates, and backlog management.

## Project Entry Point
- CLAUDE.md: Project configuration, commands, conventions, skill quick-reference

## Key Documentation
- docs/reference/CODING_STANDARDS.md: Language-specific coding standards
- docs/reference/TESTING_STRATEGY.md: TDD workflow, test quality criteria, guard rails
- docs/reference/GROUND_RULES.md: Per-project architectural principles (MUST/SHOULD), checked at planning and shipping time
- docs/architecture/ARCHITECTURE.md: System architecture and module boundaries
- docs/reference/BACKLOG_INDEX.md: Epic and story status overview
- docs/progress.md: Sprint history and metrics
- docs/FRAMEWORK_REFERENCE.md: Comprehensive framework reference
- docs/reference/MCP_INTEGRATION.md: MCP server selection guide with categories, decision tree, and integration patterns
- docs/context/: Persistent project context knowledge base (project-overview, tech-context, system-patterns, project-structure, product-context, error-patterns)

## Skills (invoked via /skill-name in Claude Code)
- .claude/skills/bootstrap/SKILL.md: First-run setup, auto-detect stack, generate project context knowledge base, optional MCP server detection
  - references/stack-detection.md: Technology detection tables and commands
  - references/new-project.md: New project braindump and generation workflow
  - references/accuracy-safeguards.md: Anti-hallucination protocol for documentation creation
  - scripts/detect-stack.sh: Automated stack detection helper
- .claude/skills/sprint-start/SKILL.md: Pre-flight checks, branch creation
- .claude/skills/story-cycle/SKILL.md: Universal story delivery with confidence gate, risk-calibrated depth, intent-based security activation, adaptive depth calibration, discovery gates, depth exploration, clarification scanning, WHAT/HOW plan separation, ground rules checks, intent decomposition, reasoning scaffolds, workflow state persistence, failure state persistence, control flow markers, error recovery, error learning, disaster prevention, parallel stream decomposition, wave execution, skill lifecycle metrics, cross-skill status, completion verification, micro-component composition, and handoff suggestions
  - references/story-types.md: Per-type execution details (TDD, bug fix, refactoring, etc.)
  - references/self-review.md: Self-review checklist with red flags + disaster prevention reference
  - references/disaster-prevention.md: Adversarial LLM failure mode checklist (wheel reinvention, spec drift, integration wiring, file structure, regression surface)
  - references/reasoning-tools.md: Named reasoning scaffolds (scope_analysis, ambiguity_scan, test_strategy_selection, failure_diagnosis, architectural_impact, plan_completeness, risk_classification, depth_exploration)
  - references/elicitation-techniques.md: Structured questioning methods (assumption surfacing, constraint mapping, failure mode exploration, stakeholder perspective shift, boundary probing)
  - references/plan-template.md: Plan output template with workflow state frontmatter, Specification (WHAT/WHY) and Implementation (HOW) sections, anti-patterns
  - references/error-recovery.md: Phase-specific error/cause/recovery decision tables (19 error patterns)
- .claude/skills/sprint-end/SKILL.md: Quality gates with control flow markers, error recovery, graceful degradation, project state adaptation, compliance ledger, cross-skill status awareness, micro-component composition, PR, merge
  - references/quality-gates.md: Detailed quality gate checks and recovery
  - references/error-recovery.md: Step-specific error/cause/recovery decision tables (18 error patterns)
  - scripts/test-count-delta.sh: Compare test counts between branch and main
- .claude/skills/brainstorm/SKILL.md: Design exploration with alternative approaches and handoff suggestions
  - assets/brainstorm-output.md: Structured brainstorm output template
- .claude/skills/ideate/SKILL.md: Ideas → typed backlog stories with story template, doc quality check, and handoff suggestions
  - references/story-template.md: Story output template with user-centric framing (As a/I want/So that), Given/When/Then criteria, independent testability, and priority justification
  - assets/story-template.md: Structured story output template for /ideate
- .claude/skills/continue/SKILL.md: Smart session resumption with failure state detection, project health scan, micro-component composition
- .claude/skills/handoff/SKILL.md: Session end, handoff document with quality check
- .claude/skills/skill-create/SKILL.md: Generate technology-specific skills with co-located references
  - scripts/init-skill.sh: Scaffold a new skill directory with SKILL.md template
  - scripts/update-registry.sh: Generate skills-registry.json from YAML frontmatter
- .claude/skills/skills-registry.json: Machine-readable index of all skills (generated)
- .claude/skills/skills-registry.schema.json: JSON Schema for registry validation
- .claude/skills/debug-session/SKILL.md: 5-phase structured debugging with reasoning scaffolds, error recovery tables, error learning, halt conditions, and handoff suggestions
  - references/root-cause-tracing.md: Backward tracing technique
  - references/condition-based-waiting.md: Replace timeouts with condition polling
  - references/error-recovery.md: Phase-specific error/cause/recovery decision tables (15 error patterns)
  - assets/debug-report.md: Structured debug report output template
- .claude/skills/parallel-work/SKILL.md: Git worktree management
  - scripts/worktree-status.sh: Worktree status with merge info
- .claude/skills/architecture-check/SKILL.md: Architecture validation
- .claude/skills/doctor/SKILL.md: Framework health check — validates config, hooks, dependencies, rules, documentation freshness, skill conformance
  - scripts/validate-skills.sh: Skill conformance validator (frontmatter, line budget, references, registry)
- .claude/skills/skill-eval/SKILL.md: Skill evaluation — test, A/B compare, metrics, baseline capture, regression detection
  - baselines/: Stored baseline outputs for regression detection
- .claude/skills/refine-loop/SKILL.md: Iterative self-improvement until completion criteria met
- .claude/skills/SKILLS_INVENTORY.md: Full skill inventory
- .claude/skills/SKILL_TEMPLATE.md: Skill creation guidelines with YAML frontmatter, skill prerequisites (requires), subagent context protocol, tool restrictions per agent, resource types, reference file budgets, control flow markers (IF/ELSE/LOOP/HALT), reasoning tools, error recovery tables, script policy, grep navigation, graceful degradation, pre-execution validation, TDD methodology, and skill-specific persistent sidecar memory
- .claude/commands/review-pr-ci.md: Non-interactive CI PR review command

## Rules
- .claude/rules/testing.md: Test file protection rules
- .claude/rules/documentation.md: Documentation rules + reference file size budgets + cross-skill output optimization
- .claude/rules/security.md: Security-sensitive file rules + fix-immediately pattern + expanded path scope (API, routes, middleware, DB, models, uploads, sessions)
- .claude/rules/git.md: Git workflow rules
- .claude/rules/dependencies.md: Dependency management rules
- .claude/rules/verification.md: Evidence required before completion claims + four-question completion evidence protocol + CLI discovery pattern + task completion enforcement + context budget awareness + context relevance scoring (5-level classification) + pre-compaction state persistence + rule effectiveness tracking protocol
- .claude/rules/code-slop.md: AI slop detection — banned comment patterns, obvious comment detection, code prose anti-patterns
- .claude/rules/edit-recovery.md: Edit failure recovery decision tree — re-read before retry, escalating recovery

## Prompt Snippets
- .claude/prompts/review-security.md: Security review of a specific file
- .claude/prompts/explain-pattern.md: Explain a code pattern in this codebase
- .claude/prompts/suggest-tests.md: Suggest test cases for a file

## Micro-Components (reusable cross-skill operations)
- .claude/prompts/discover-commands.md: Extract configured commands from CLAUDE.md
- .claude/prompts/quality-gate-sequence.md: Run lint → typecheck → test sequence
- .claude/prompts/verify-clean-git-state.md: Verify clean git working tree
- .claude/prompts/context-budget.md: Estimate context budget usage and compaction proximity
- .claude/prompts/context-prime.md: Intent-aware context loading with task classification (security, UI, data/API, refactoring, new feature) + error patterns
- .claude/prompts/confidence-gate.md: Pre-implementation confidence assessment (5 dimensions, 0-100 scoring, threshold-gated)
- .claude/prompts/record-failure.md: Cross-session error learning — records failure patterns, root causes, and prevention strategies
- .claude/prompts/wave-execution.md: Wave → Checkpoint → Wave parallel execution pattern for independent operations
- .claude/prompts/select-tool.md: MCP server vs built-in tool selection guide with decision matrix

## Native Agents (.claude/agents/)
- .claude/agents/code-reviewer.md: Code review with severity classification (correctness, conventions, security lenses)
- .claude/agents/spec-reviewer.md: Spec compliance verification with file:line references (model: haiku)
- .claude/agents/security-analyst.md: Security-focused analysis with attacker mindset, OWASP top 10, CWE references
- .claude/agents/performance-engineer.md: Performance analysis with bottleneck identification, N+1 detection, and scaling assessment
- .claude/agents/architecture-reviewer.md: Architecture validation with boundary enforcement, dependency direction, and coupling analysis
- .claude/agents/codebase-explorer.md: Fast file discovery and codebase mapping (model: haiku)

## Hooks
- .claude/hooks/engine.py: Unified Python dispatch engine routing all hook events to handler modules with YAML rule configuration
- .claude/hooks/rules/safety.yaml: PreToolUse blocking patterns (git force push, destructive ops, publishing, DB, process killing)
- .claude/hooks/rules/quality.yaml: Stop quality gate rules (weak claims, completion evidence)
- .claude/hooks/handlers/: Per-event handler modules (pre_tool_use, post_tool_use, stop, user_prompt, subagent_stop, session_start, worktree)
- .claude/hooks/post-edit-format.sh: Auto-format and auto-lint after edits + automated secrets detection (bash, kept for file-type switching)
- .claude/hooks/worktree-bash-fix.sh: Transparent worktree directory fix for Bash commands (bash, apply_to_subagents)
- Engine falls back gracefully if Python unavailable

## GitHub Templates
- .github/workflows/claude-pr-review.yml: CI-based Claude Code PR review with tiered access
- .github/pull_request_template.md: PR template with quality gates checklist
- .github/ISSUE_TEMPLATE/bug_report.yml: Structured bug report form
- .github/ISSUE_TEMPLATE/feature_request.yml: Structured feature request form

## Scripts
- scripts/pm/status.sh: Sprint status overview (git state, progress, backlog, PRs)
- scripts/pm/next-story.sh: Next available TODO story from backlog
- scripts/pm/standup.sh: Daily standup summary
- scripts/pm/metrics.sh: Skill execution metrics, rule trigger counts, tool usage distribution

## Other
- CHANGELOG.md: Per-optimization changelog with test and revert instructions