gv-specwright 1.0.2__tar.gz

gv_specwright-1.0.2/.claude/skills/sw-context/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: sw-context
+description: >
+  Load spec context for the current task. Use when starting work on a feature,
+  investigating a bug, or reviewing code that relates to a spec. Automatically
+  identifies relevant specs from git changes or a user-provided topic.
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - mcp__specwright__search
+  - mcp__specwright__get_spec
+  - mcp__specwright__get_section
+---
+
+# Load Spec Context
+
+You are loading spec context for the user's current task.
+
+## Step 1: Identify Relevant Files
+
+Check what the user is currently working on:
+
+```bash
+git diff --name-only HEAD 2>/dev/null || git diff --name-only --cached 2>/dev/null || echo ""
+```
+
+If the user provided a topic, use that instead of git changes.
+
+## Step 2: Find Relevant Specs
+
+**With MCP (preferred):** Use `mcp__specwright__search` to find specs matching changed files or the topic.
+
+**Without MCP (fallback):** Search locally:
+1. Use `Glob` to find all specs: `docs/specs/*.md`
+2. Use `Grep` to search spec content for terms from changed files or topic
+3. Use `Read` to load matching spec files
+
+## Step 3: Present Context
+
+For each relevant spec, present:
+- **Title** and **status** from frontmatter
+- **Relevant sections** with their status (draft/todo/in_progress/done)
+- **Acceptance criteria** — checked items and unchecked items
+- **Ticket links** if present
+
+## Spec Format Reference
+
+Specs use YAML frontmatter:
+```yaml
+---
+title: "Feature Name"
+type: spec          # spec, proposal, design, adr
+status: draft       # draft, in_progress, done, deprecated
+owner: "name"
+team: "team-name"
+tags: [tag1, tag2]
+---
+```
+
+Sections are numbered headings (`## 1. Section Title`).
+Status comments: `<!-- specwright:system:1.1 status:todo -->`
+Ticket links: `<!-- specwright:ticket:github:ORG-123 -->`
+AC checkboxes: `- [ ] Unchecked` / `- [x] Checked`

gv_specwright-1.0.2/.claude/skills/sw-new/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: sw-new
+description: >
+  Create a new spec document from a template. Use when starting a new feature,
+  writing a design doc, proposal, or ADR. Walks through structured creation
+  with the user.
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - mcp__specwright__create_spec
+---
+
+# Create New Spec
+
+You are helping the user create a new spec document.
+
+## Step 1: Gather Information
+
+Ask the user for:
+1. **Title** — what is this spec about?
+2. **Type** — spec (default), proposal, design, or adr
+3. **Team** — which team owns this?
+4. **Tags** — relevant tags for discovery
+
+## Step 2: Create the Spec
+
+**With MCP:** Use `mcp__specwright__create_spec` to create the file directly in the repo.
+
+**Without MCP:** Create locally using `Write`:
+- Path: `docs/specs/<slug>.md` (derived from title)
+- Use the template format below
+
+## Spec Template
+
+```markdown
+---
+title: "<Title>"
+type: spec
+status: draft
+owner: ""
+team: "<team>"
+review_status: draft
+tags: [<tags>]
+depends_on: []
+created: ""
+updated: ""
+---
+
+# <Title>
+
+## 1. Background
+
+Describe the context and motivation for this spec.
+
+## 2. Requirements
+
+### Acceptance Criteria
+
+- [ ] First requirement
+
+## 3. Design
+
+Describe the technical approach.
+
+## 4. Rollout Plan
+
+Describe phased rollout and success criteria.
+```
+
+## Step 3: Guide Next Steps
+
+After creation, suggest:
+1. Fill in the Background section with context
+2. Define specific acceptance criteria
+3. Add design details
+4. Run `/sw:review` when ready for review

gv_specwright-1.0.2/.claude/skills/sw-plan/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: sw-plan
+description: >
+  Spec-driven planning workflow inspired by OpenSpec. Use when starting a new
+  feature or project to go from exploration through spec creation to
+  implementation tasks. Follows the explore-propose-spec-design-tasks lifecycle.
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Bash
+  - mcp__specwright__search
+  - mcp__specwright__get_spec
+  - mcp__specwright__get_doc
+  - mcp__specwright__create_spec
+---
+
+# Spec-Driven Planning
+
+You are guiding the user through a spec-driven planning workflow.
+
+## Quick Task Extraction with CLI
+
+For an existing spec, try the CLI first to extract a structured task plan:
+
+```bash
+specwright plan <spec-file>
+```
+
+This parses the spec, lists todo/in_progress sections as tasks with ACs as
+subtasks, and includes dependency information. Use this as a starting point
+for the planning workflow below.
+
+## Phase 1: Explore
+
+Understand the current state:
+1. What exists in the codebase relevant to this work?
+2. Are there existing specs that overlap or depend on this?
+3. What constraints exist (architecture, dependencies, timeline)?
+
+Search with MCP `search` or local `Glob` + `Grep` to find related code and docs.
+
+## Phase 2: Propose
+
+Based on exploration, propose an approach:
+1. **Scope** — what will this spec cover?
+2. **Approach** — high-level technical direction
+3. **Dependencies** — what does this depend on?
+4. **Risks** — what could go wrong?
+
+Present this as a short proposal for the user to approve before writing the full spec.
+
+## Phase 3: Spec
+
+Create the spec document:
+1. Use `/sw:new` or `mcp__specwright__create_spec` to create the file
+2. Fill in:
+   - Background and motivation
+   - Requirements with specific acceptance criteria
+   - Technical design
+   - Rollout plan
+
+Each AC should be:
+- **Specific** — testable, not vague
+- **Independent** — can be verified on its own
+- **Valuable** — directly ties to user value
+
+## Phase 4: Design
+
+Add technical design details:
+1. Architecture decisions
+2. API contracts
+3. Data model changes
+4. Integration points
+
+## Phase 5: Tasks
+
+Break the spec into implementation tasks:
+1. Map each section/AC to concrete work items
+2. Identify dependencies between tasks
+3. Suggest implementation order
+4. Estimate relative complexity
+
+Present as a task list the user can use directly or sync to their ticket system.
+
+## Workflow Tips
+
+- Don't skip exploration — understanding context prevents rework
+- Keep ACs specific and testable
+- Design docs should live alongside specs, not separately
+- Tasks should map back to spec sections for traceability

gv_specwright-1.0.2/.claude/skills/sw-review/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: sw-review
+description: >
+  Review code changes against all documentation — specs, ADRs, READMEs,
+  architecture docs. Broader than verify. Use during code review or before
+  merging to catch documentation drift.
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - mcp__specwright__search
+  - mcp__specwright__get_spec
+  - mcp__specwright__get_doc
+  - mcp__specwright__list_specs
+  - mcp__specwright__list_docs
+---
+
+# Review Changes Against Documentation
+
+You are reviewing code changes against all project documentation.
+
+## Step 1: Identify Changes
+
+```bash
+git diff --name-only HEAD 2>/dev/null || git diff --name-only --cached 2>/dev/null
+```
+
+If reviewing a PR, examine all changed files.
+
+## Step 2: Find Relevant Documentation
+
+Search broadly — not just specs but all docs:
+- `docs/specs/*.md` — spec files
+- `docs/adrs/*.md` — architecture decision records
+- `docs/**/*.md` — any documentation
+- `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`
+
+Use MCP `search` or local `Glob` + `Grep` to find docs mentioning changed files, functions, or concepts.
+
+## Step 3: Check for Drift
+
+For each relevant doc, check:
+1. **Accuracy** — does the doc still accurately describe the code?
+2. **Completeness** — are new features/changes reflected in docs?
+3. **Consistency** — do docs agree with each other?
+4. **Spec compliance** — do code changes align with spec requirements?
+
+## Step 4: Report Findings
+
+Organize findings by severity:
+
+### Must Fix
+- Documentation that is now **incorrect** due to code changes
+- Spec ACs that are **contradicted** by the implementation
+
+### Should Update
+- Docs that are **incomplete** — missing new functionality
+- README sections that reference **changed** behavior
+
+### Consider
+- Opportunities to **improve** documentation
+- Specs that could be **updated** to reflect implementation learnings
+
+## Step 5: Suggest Updates
+
+For each finding, provide specific suggestions for what to change in the documentation.

gv_specwright-1.0.2/.claude/skills/sw-status/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: sw-status
+description: >
+  Show a spec coverage dashboard. Use to see overall project status,
+  spec progress, and coverage metrics. Works with MCP for org-wide
+  metrics or locally by parsing spec files.
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - mcp__specwright__get_coverage
+  - mcp__specwright__list_specs
+  - mcp__specwright__get_spec
+---
+
+# Spec Coverage Dashboard
+
+You are generating a spec coverage dashboard for the user.
+
+## With CLI (preferred — fast local parsing)
+
+Try the CLI first for an instant local dashboard:
+
+```bash
+specwright status
+```
+
+For a single spec detail view:
+
+```bash
+specwright status --spec <file>
+```
+
+If the CLI works, present its output directly. Only fall back to other methods
+if the CLI is unavailable or if org-wide metrics are needed.
+
+## With MCP (org-wide metrics)
+
+Use `mcp__specwright__get_coverage` to get aggregate metrics:
+- Total specs, sections, acceptance criteria
+- Coverage percentages (section, AC, realization)
+- Health score
+- Trend data
+
+Then use `mcp__specwright__list_specs` for per-spec breakdown.
+
+## Without MCP (local parsing)
+
+1. Find all specs: `Glob` for `docs/specs/*.md`
+2. Read each spec and extract:
+   - Frontmatter status
+   - Section count and statuses
+   - AC counts (total, checked, unchecked)
+
+## Dashboard Format
+
+Present the dashboard as:
+
+```
+Spec Coverage Dashboard
+========================
+
+Overall: X specs | Y sections | Z acceptance criteria
+
+| Spec | Status | Sections | ACs | Coverage |
+|------|--------|----------|-----|----------|
+| Auth | in_progress | 4/6 done | 8/12 | 67% |
+| Billing | draft | 0/3 done | 0/5 | 0% |
+
+Health Score: XX/100
+```
+
+## Section Status Breakdown
+
+For specs the user is interested in, show section-level detail:
+
+```
+Auth Spec (in_progress)
+  1. Login Flow ........... done
+    1.1 Password Reset .... in_progress
+  2. OAuth ................ todo
+  3. Session Management ... draft
+```
+
+## Acceptance Criteria Summary
+
+```
+Checked:   8 / 12 (67%)
+Realized:  5 / 12 (42%)  ← have code evidence
+Unchecked: 4 / 12 (33%)
+```

gv_specwright-1.0.2/.claude/skills/sw-task/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: sw-task
+description: >
+  Pick up a spec-driven task, work through its acceptance criteria, and mark it
+  done. Bridges the specwright CLI workflow with Claude Code's interactive
+  capabilities for a guided implementation experience.
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - mcp__specwright__get_spec
+  - mcp__specwright__get_section
+  - mcp__specwright__search
+  - mcp__specwright__add_realization
+  - mcp__specwright__update_section_status
+---
+
+# Spec-Driven Task Workflow
+
+You are guiding the user through a spec-driven development task — picking up a
+work item, implementing it against acceptance criteria, and marking it done.
+
+## Step 1: Show Available Tasks
+
+Try the CLI first for a quick overview:
+
+```bash
+specwright tasks
+```
+
+If the CLI is not available, fall back to local parsing:
+1. `Glob` for `docs/specs/*.md`
+2. `Read` each spec, find sections with `todo` or `in_progress` status
+
+Present available tasks as a numbered list:
+```
+Available tasks:
+  1. [1] Login Flow (todo) — 0/3 ACs
+  2. [2] OAuth (todo) — 0/2 ACs
+  3. [3.1] Password Reset (in_progress) — 1/4 ACs
+```
+
+Ask the user which task to pick up.
+
+## Step 2: Start the Task
+
+Mark the selected section as `in_progress`:
+
+```bash
+specwright start <section-id>
+```
+
+Or fall back to editing the spec file directly — update the status comment:
+```
+<!-- specwright:system:1.1 status:in_progress -->
+```
+
+If `--issue` is needed, the CLI can create a GitHub Issue too.
+
+## Step 3: Present Acceptance Criteria
+
+Load the full section and present ACs as an implementation checklist:
+
+```
+Task: 1.1 Password Reset (in_progress)
+
+Acceptance Criteria:
+  [ ] Reset email sends within 30 seconds
+  [x] Token expires after 1 hour
+  [ ] Rate limit: max 3 resets per hour per user
+  [ ] Reset link works exactly once
+```
+
+## Step 4: Implement
+
+Work through each unchecked AC:
+1. Search the codebase for existing relevant code
+2. Implement the requirement
+3. Verify the implementation satisfies the AC
+
+After implementing each AC, offer to check the box in the spec.
+
+## Step 5: Mark Done
+
+When all ACs are satisfied:
+
+```bash
+specwright done <section-id>
+```
+
+Or edit the spec directly to set status to `done`.
+
+## Step 6: Record Realization Evidence
+
+For each completed AC, add realization evidence linking code to the requirement.
+
+If MCP is available:
+```
+mcp__specwright__add_realization(
+  section_id="1.1",
+  ac_text="Reset email sends within 30 seconds",
+  pr_number=42,
+  code_file="src/auth/reset.py",
+  lines="15-30"
+)
+```
+
+Without MCP, insert realization comments directly:
+```markdown
+- [x] Reset email sends within 30 seconds
+<!-- specwright:realized-in:PR#42 file:src/auth/reset.py:15-30 -->
+```
+
+## Workflow Tips
+
+- Always read the full section content before implementing — context matters
+- Check existing code first to avoid duplicating work
+- Keep ACs atomic — implement and verify one at a time
+- If an AC is unclear, ask the user for clarification before implementing
+- Use `specwright verify` to double-check implementation coverage

gv_specwright-1.0.2/.claude/skills/sw-update/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: sw-update
+description: >
+  Update spec statuses based on code implementation evidence. Use after
+  implementing features to keep specs in sync with reality. Scans the codebase
+  for implementation evidence and proposes status transitions.
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - mcp__specwright__get_spec
+  - mcp__specwright__get_section
+  - mcp__specwright__search
+  - mcp__specwright__update_section_status
+  - mcp__specwright__add_realization
+  - mcp__specwright__sync_spec_status
+---
+
+# Update Spec Statuses
+
+You are scanning the codebase to update spec statuses based on implementation evidence.
+
+## Quick Status Updates with CLI
+
+For simple status transitions, use the CLI directly:
+
+```bash
+specwright start <section-id>   # Mark section as in_progress
+specwright done <section-id>    # Mark section as done
+```
+
+Add `--issue` to create/update GitHub Issues alongside the status change:
+
+```bash
+specwright start <section-id> --issue
+specwright done <section-id> --issue
+```
+
+For bulk automated updates based on code evidence, continue with the workflow below.
+
+## Step 1: Load Specs
+
+If the user specifies a spec, load it. Otherwise, load all specs:
+- MCP: `mcp__specwright__list_specs` then `mcp__specwright__get_spec` for each
+- Local: `Glob` for `docs/specs/*.md` then `Read` each
+
+## Step 2: Scan for Implementation Evidence
+
+For each spec section with unchecked ACs or non-done status:
+
+1. **Search the codebase** for implementation:
+   - `Grep` for function names, class names, or keywords from the AC
+   - Check recent git commits: `git log --oneline --since="30 days ago"`
+   - Look at test files for test coverage of the requirement
+
+2. **Evaluate** each section:
+   - All ACs checked + code exists → **done**
+   - Some ACs checked + active work → **in_progress**
+   - No ACs checked + no code → stays as-is
+
+## Step 3: Propose Updates
+
+Present proposed changes as a table:
+
+| Section | Current | Proposed | Evidence |
+|---------|---------|----------|----------|
+| 1.1 Password Reset | todo | in_progress | `src/auth/reset.py` exists, 2/3 ACs done |
+| 2. OAuth | todo | done | Full implementation in `src/auth/oauth/` |
+
+## Step 4: Apply Updates
+
+Ask the user to confirm before applying. Then:
+
+**With MCP (preferred):** Use `mcp__specwright__sync_spec_status` for bulk updates in a single commit.
+
+**Without MCP:** Use `Edit` to modify the spec files locally:
+- Update status comments: `<!-- specwright:system:1.1 status:in_progress -->`
+- Check AC boxes: `- [x] Requirement text`
+
+## Status Transitions
+
+Valid states: `draft` → `todo` → `in_progress` → `done`
+Also: `blocked` (with reason), `deprecated`
+
+Only propose forward transitions unless there's clear evidence of regression.

gv_specwright-1.0.2/.claude/skills/sw-verify/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: sw-verify
+description: >
+  Verify code implementation against spec acceptance criteria. Use when you want
+  to check if code satisfies spec requirements, after implementing a feature,
+  or during code review. Evaluates each AC as realized, partial, or conflicting.
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - mcp__specwright__get_spec
+  - mcp__specwright__get_section
+  - mcp__specwright__search
+  - mcp__specwright__add_realization
+  - mcp__specwright__update_section_status
+---
+
+# Verify Code Against Spec
+
+You are verifying whether the current codebase satisfies a spec's acceptance criteria.
+
+## Quick Check with CLI
+
+Try the CLI first for a fast static check:
+
+```bash
+specwright verify
+```
+
+Or for a specific section:
+
+```bash
+specwright verify --section <id>
+```
+
+This greps the codebase for keywords from each unchecked AC and classifies them
+as "likely realized", "not started", or "unknown". Use the results as a starting
+point, then do deeper analysis with the steps below.
+
+## Step 1: Load the Spec
+
+If the user specifies a spec file, load it directly. Otherwise, identify the relevant spec:
+- Check recent changes: `git diff --name-only HEAD`
+- Search for matching specs using MCP `search` or local `Glob` + `Grep`
+
+Load the full spec with `mcp__specwright__get_spec` or `Read`.
+
+## Step 2: Evaluate Each Acceptance Criterion
+
+For each AC checkbox in the spec:
+
+1. **Search the codebase** for implementation evidence using `Grep` and `Read`
+2. **Classify** the AC:
+   - **Realized** — code fully implements the requirement
+   - **Partial** — code partially implements it (explain what's missing)
+   - **Not Started** — no implementation found
+   - **Conflicting** — implementation contradicts the requirement
+
+## Step 3: Present Results
+
+Format as a table:
+
+| AC | Status | Evidence |
+|----|--------|----------|
+| Rate limiting | Realized | `src/auth/rate_limit.py:42-60` |
+| Email validation | Partial | Validates format but not domain |
+| OAuth support | Not Started | — |
+
+## Step 4: Offer Write-Back (MCP only)
+
+If MCP is available, offer to:
+- Update section statuses: `mcp__specwright__update_section_status`
+- Record realization evidence: `mcp__specwright__add_realization`
+
+Ask the user before making any writes.
+
+## Spec Format Reference
+
+AC checkboxes appear under `### Acceptance Criteria` headings:
+```markdown
+- [x] Checked (done)
+- [ ] Unchecked (not done)
+```
+
+Realization comments appear after ACs:
+```
+<!-- specwright:realized-in:PR#42 file:src/auth.py:10-25 -->
+```