claude-code-kit 0.7.0__py3-none-any.whl

claude_kit/_payload/skills/spec-driven-development/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: spec-driven-development
+description: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea.
+---
+
+# Spec-Driven Development
+
+## Overview
+
+Write a structured specification before writing any code. The spec is the shared source of truth between you and the human engineer — it defines what we're building, why, and how we'll know it's done. Code without a spec is guessing.
+
+## When to Use
+
+- Starting a new project or feature
+- Requirements are ambiguous or incomplete
+- The change touches multiple files or modules
+- You're about to make an architectural decision
+- The task would take more than 30 minutes to implement
+
+**When NOT to use:** Single-line fixes, typo corrections, or changes where requirements are unambiguous and self-contained.
+
+## The Gated Workflow
+
+Spec-driven development has four phases. Do not advance to the next phase until the current one is validated.
+
+```
+SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
+   │          │        │          │
+   ▼          ▼        ▼          ▼
+ Human      Human    Human      Human
+ reviews    reviews  reviews    reviews
+```
+
+### Phase 1: Specify
+
+Start with a high-level vision. Ask the human clarifying questions until requirements are concrete.
+
+**Surface assumptions immediately.** Before writing any spec content, list what you're assuming:
+
+```
+ASSUMPTIONS I'M MAKING:
+1. This is a web application (not native mobile)
+2. Authentication uses session-based cookies (not token-based)
+3. The database is relational (based on existing schema)
+4. We're targeting modern clients only
+→ Correct me now or I'll proceed with these.
+```
+
+Don't silently fill in ambiguous requirements. The spec's entire purpose is to surface misunderstandings *before* code gets written — assumptions are the most dangerous form of misunderstanding.
+
+**Write a spec document covering these six core areas:**
+
+1. **Objective** — What are we building and why? Who is the user? What does success look like?
+
+2. **Commands** — Full executable commands with flags, not just tool names.
+   ```
+   Build: <project's build command>
+   Test: <project's test runner command with flags>
+   Lint: <project's linter command with auto-fix>
+   Dev: <project's dev server command>
+   ```
+
+3. **Project Structure** — Where source code lives, where tests go, where docs belong.
+   ```
+   src/           → Application source code
+   src/components → UI components
+   src/lib        → Shared utilities
+   tests/         → Unit and integration tests
+   e2e/           → End-to-end tests
+   docs/          → Documentation
+   ```
+
+4. **Code Style** — One real code snippet showing your style beats three paragraphs describing it. Include naming conventions, formatting rules, and examples of good output.
+
+5. **Testing Strategy** — What framework, where tests live, coverage expectations, which test levels for which concerns.
+
+6. **Boundaries** — Three-tier system:
+   - **Always do:** Run tests before commits, follow naming conventions, validate inputs
+   - **Ask first:** Database schema changes, adding dependencies, changing CI config
+   - **Never do:** Commit secrets, edit vendor directories, remove failing tests without approval
+
+**Spec template:**
+
+```markdown
+# Spec: [Project/Feature Name]
+
+## Objective
+[What we're building and why. User stories or acceptance criteria.]
+
+## Tech Stack
+[Framework, language, key dependencies with versions]
+
+## Commands
+[Build, test, lint, dev — full commands]
+
+## Project Structure
+[Directory layout with descriptions]
+
+## Code Style
+[Example snippet + key conventions]
+
+## Testing Strategy
+[Framework, test locations, coverage requirements, test levels]
+
+## Boundaries
+- Always: [...]
+- Ask first: [...]
+- Never: [...]
+
+## Success Criteria
+[How we'll know this is done — specific, testable conditions]
+
+## Open Questions
+[Anything unresolved that needs human input]
+```
+
+**Reframe instructions as success criteria.** When receiving vague requirements, translate them into concrete conditions:
+
+```
+REQUIREMENT: "Make the dashboard faster"
+
+REFRAMED SUCCESS CRITERIA:
+- Dashboard LCP < 2.5s on 4G connection
+- Initial data load completes in < 500ms
+- No layout shift during load (CLS < 0.1)
+→ Are these the right targets?
+```
+
+This lets you loop, retry, and problem-solve toward a clear goal rather than guessing what "faster" means.
+
+### Phase 2: Plan
+
+With the validated spec, generate a technical implementation plan:
+
+1. Identify the major components and their dependencies
+2. Determine the implementation order (what must be built first)
+3. Note risks and mitigation strategies
+4. Identify what can be built in parallel vs. what must be sequential
+5. Define verification checkpoints between phases
+
+The plan should be reviewable: the human should be able to read it and say "yes, that's the right approach" or "no, change X."
+
+### Phase 3: Tasks
+
+Break the plan into discrete, implementable tasks:
+
+- Each task should be completable in a single focused session
+- Each task has explicit acceptance criteria
+- Each task includes a verification step (test, build, manual check)
+- Tasks are ordered by dependency, not by perceived importance
+- No task should require changing more than ~5 files
+
+**Task template:**
+```markdown
+- [ ] Task: [Description]
+  - Acceptance: [What must be true when done]
+  - Verify: [How to confirm — test command, build, manual check]
+  - Files: [Which files will be touched]
+```
+
+### Phase 4: Implement
+
+Execute tasks one at a time following `skills/incremental-implementation/SKILL.md` (`incremental-implementation`) and `skills/test-driven-development/SKILL.md` (`test-driven-development`). Use `skills/context-engineering/SKILL.md` (`context-engineering`) to load the right spec sections and source files at each step rather than flooding the agent with the entire spec.
+
+## Keeping the Spec Alive
+
+The spec is a living document, not a one-time artifact:
+
+- **Update when decisions change** — If you discover the data model needs to change, update the spec first, then implement.
+- **Update when scope changes** — Features added or cut should be reflected in the spec.
+- **Commit the spec** — The spec belongs in version control alongside the code.
+- **Reference the spec in PRs** — Link back to the spec section that each PR implements.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "This is simple, I don't need a spec" | Simple tasks don't need *long* specs, but they still need acceptance criteria. A two-line spec is fine. |
+| "I'll write the spec after I code it" | That's documentation, not specification. The spec's value is in forcing clarity *before* code. |
+| "The spec will slow us down" | A 15-minute spec prevents hours of rework. Waterfall in 15 minutes beats debugging in 15 hours. |
+| "Requirements will change anyway" | That's why the spec is a living document. An outdated spec is still better than no spec. |
+| "The user knows what they want" | Even clear requests have implicit assumptions. The spec surfaces those assumptions. |
+
+## Red Flags
+
+- Starting to write code without any written requirements
+- Asking "should I just start building?" before clarifying what "done" means
+- Implementing features not mentioned in any spec or task list
+- Making architectural decisions without documenting them
+- Skipping the spec because "it's obvious what to build"
+
+## Verification
+
+Before proceeding to implementation, confirm:
+
+- [ ] The spec covers all six core areas
+- [ ] The human has reviewed and approved the spec
+- [ ] Success criteria are specific and testable
+- [ ] Boundaries (Always/Ask First/Never) are defined
+- [ ] The spec is saved to a file in the repository

claude_kit/_payload/skills/sprint/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: sprint
+description: Generate a sprint plan from a scoped backlog item, breaking it into parallelizable tasks for agent teams.
+argument-hint: [backlog item number]
+disable-model-invocation: true
+---
+
+Generate a sprint plan for backlog item #$ARGUMENTS.
+
+## Steps
+
+1. **Find the scope doc**: Look for the scope document in `docs/planning/*/scope.md` that corresponds to backlog item #$ARGUMENTS. If no scope doc exists, tell the user to run `/scope $ARGUMENTS` first.
+
+2. **Read the scope doc**: Understand all the component changes, data changes, route changes, and state changes.
+
+3. **Read the sprint template**: Read the [sprint template](sprint-template.md) for the output structure.
+
+4. **Break into tasks**: Create a detailed task breakdown:
+   - Each task should be small enough for one agent to complete in a focused session
+   - Tasks should have clear inputs and outputs
+   - Include the specific files to modify/create
+   - Order tasks by dependency (data models before business logic, business logic before interfaces, etc.)
+
+5. **Read post-sprint learnings**: Read `docs/reference/post-sprint-learnings.md` for execution heuristics from previous sprints. Apply relevant learnings to the plan.
+
+6. **Design parallelization**: Identify which tasks can run concurrently:
+   - Data/schema changes and scaffolding can usually run in parallel
+   - Module implementation can overlap if they don't share state
+   - Tasks modifying shared files (routing configuration, shared state stores, dependency injection configuration) should be sequential on one agent
+   - For multi-module features: build one module first to establish patterns, then parallelize the rest
+
+7. **Write the sprint plan**: Save to `docs/planning/{slug}/sprint.md` next to the scope doc. Include:
+   - Numbered deliverables with acceptance criteria
+   - Task tables organized by work stream (e.g., backend, frontend, integration, infrastructure)
+   - Parallelization diagram showing agent assignments
+   - Verification checklist
+
+8. **Suggest team composition**: Based on the tasks, recommend:
+   - How many agents to spawn and what type (e.g., backend-dev, frontend-dev, full-stack-dev)
+   - Task assignment per agent
+   - Plan extra tasks for faster-finishing agents (investigation, docs, design validation)
+
+9. **Output the plan**: Show the user the sprint plan summary and ask for approval before they kick off execution.
+
+## Guidelines
+
+- Tasks should be atomic — one clear objective per task
+- Always include a "verify integration" task at the end
+- Don't create tasks for things that are already done
+- Identify which work streams are independent (backend API, frontend UI, data migrations, infrastructure) and can run in parallel
+- Agent type for implementation: match to the stack (backend-dev for API work, frontend-dev for UI work, full-stack-dev for cross-cutting features)
+- For design-sensitive changes, suggest running a design-review agent after implementation
+- For coordinated changes (e.g., new data model + new API endpoint + new UI component + new route), ensure all changes are in the same sprint
+
+## Post-Sprint Report
+
+**When to write**: After the verification checklist passes and all tasks are complete (or explicitly descoped), the team lead must fill in the Sprint Report section of the sprint plan before archiving.
+
+**What to capture**:
+1. **Results table** — each deliverable with target vs actual vs status
+2. **Metrics** — tasks planned/completed, regressions found
+3. **What went well** — patterns that worked, velocity wins, risk catches
+4. **What went wrong** — regressions, scope errors, agent issues, blockers
+5. **Learnings** — actionable lessons for future sprints (check existing learnings in `docs/reference/post-sprint-learnings.md` to avoid duplicates)
+6. **Unresolved / carry-over** — issues discovered but not fixed, with enough detail to act on immediately in the next sprint
+
+**After writing the report**: Add any new learnings to `docs/reference/post-sprint-learnings.md`. Then run `/archive-sprint` to move docs to archive and update the backlog.

claude_kit/_payload/skills/sprint/sprint-template.md

@@ -0,0 +1,90 @@
+# Sprint Plan: {Item Title} (Backlog #{N})
+
+> **Scope Doc**: [{Item Title}](./{slug}/scope.md)
+> **Assignee**: {agent team or person}
+> **Date**: {YYYY-MM-DD}
+
+---
+
+## Deliverables
+
+1. {deliverable with acceptance criteria}
+2. {deliverable with acceptance criteria}
+
+## Task Breakdown
+
+### Components
+
+| # | Task | Files | Depends On |
+|---|------|-------|------------|
+| C1 | | | — |
+
+### Data / Mock Data
+
+| # | Task | Files | Depends On |
+|---|------|-------|------------|
+| D1 | | | — |
+
+### Integration / Wiring
+
+| # | Task | Files | Depends On |
+|---|------|-------|------------|
+| I1 | | | — |
+
+## Parallelization
+
+Which tasks can run concurrently across agents?
+
+```
+Agent 1 (frontend-dev): Task D1 → C1 → C2
+Agent 2 (frontend-dev): Task D2 → C3 → C4
+Integration:            ----waits---- → I1 (verify all)
+```
+
+## Verification Checklist
+
+- [ ] TypeScript compiles (`npm run build`)
+- [ ] No lint errors (`npm run lint`)
+- [ ] No regressions in existing pages
+- [ ] New components follow design system rules
+- [ ] All interactive elements have appropriate `aria-label`
+- [ ] Dev server renders correctly (`npm run dev`)
+
+---
+
+## Sprint Report
+
+> **Completed**: {YYYY-MM-DD}
+> **Team**: {agent count and types}
+
+### Results
+
+| Deliverable | Target | Actual | Status |
+|-------------|--------|--------|--------|
+| | | | |
+
+### Metrics
+
+| Metric | Value |
+|--------|-------|
+| Tasks planned | |
+| Tasks completed | |
+| Regressions found | |
+
+### What Went Well
+
+- {positive outcome}
+
+### What Went Wrong
+
+- {issue encountered}
+
+### Learnings
+
+1. {actionable lesson for future sprints — reference docs/reference/post-sprint-learnings.md for existing learnings}
+
+### Unresolved / Carry-Over
+
+| # | Issue | Details |
+|---|-------|---------|
+| K1 | | |