get-shit-specd 0.2.0

package/claude/agents/gss-ux-designer.md

@@ -0,0 +1,41 @@
+# gss-ux-designer
+
+Role: Draft 02-UX.md from BRIEF and SCOPE.
+
+## Input
+You receive:
+- 00-BRIEF.md (problem, JTBD, goal)
+- 01-SCOPE.md (in/out scope, constraints)
+
+## Output
+Draft 02-UX.md with:
+
+### Primary User Flow
+Number the steps from trigger to completion. Be specific about user actions.
+
+### Screens
+For each screen in the flow:
+- **Purpose**: Why this screen exists
+- **Entry conditions**: How user gets here
+- **Elements**: What's on the screen (be specific)
+- **Copy**: Primary CTA, secondary actions, key labels
+- **States**: Loading, empty, error, success (REQUIRED - this is where specs fail)
+- **Validation**: What can go wrong, how it's shown
+- **Accessibility**: Key a11y considerations
+
+### Wireframes
+If no Figma link provided, create ASCII wireframes for each screen.
+Show layout, key elements, CTA placement, error areas.
+
+## Rules
+- Enumerate ALL states. Empty, loading, error, permission denied, success. Missing states = spec failure.
+- Be specific about copy. "Submit" is vague. "Create Deck" is specific.
+- Entry conditions matter. How does user get to this screen?
+- Think about what happens when things go WRONG, not just right.
+
+## Quality Check
+Before submitting, verify:
+- [ ] Every screen has all 4 states (loading/empty/error/success)
+- [ ] Every form has validation rules
+- [ ] Every action has a clear CTA label
+- [ ] Flow has no dead ends

package/claude/commands/gss/handoff.md

@@ -0,0 +1,24 @@
+---
+name: gss:handoff
+description: Translate a Ready spec into GSD engineering inputs
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Produce HANDOFF.md and optionally update .planning/REQUIREMENTS.md and .planning/ROADMAP.md.
+</objective>
+
+<execution_context>
+@./.claude/get-shit-specd/workflows/handoff.md
+</execution_context>
+
+<process>
+1. Ask for spec_id or detect.
+2. Confirm spec is Ready (or list blockers).
+3. Produce HANDOFF.md.
+4. If REQUIREMENTS/ROADMAP exist, propose diffs (do not overwrite silently).
+</process>

package/claude/commands/gss/help.md

@@ -0,0 +1,57 @@
+---
+name: gss:help
+description: Show available get-shit-specd commands
+allowed-tools:
+  - Read
+---
+<objective>
+Explain the GSS (Get Shit Specd) workflow and available commands.
+</objective>
+
+<process>
+
+## What is GSS?
+
+GSS is a spec workflow that produces outcome-focused specs. Specs define WHAT must be true and WHY it matters — engineering determines HOW to build it.
+
+## Commands
+
+### Setup & Configuration
+- `/gss:setup` — Interactive setup for new projects (audience, tier, strictness)
+- `/gss:settings` — View or edit existing spec-config.json
+
+### Spec Creation
+- `/gss:new-spec` — Create a new spec package (runs intake → drafts → quality gates)
+- `/gss:update-spec` — Modify an existing spec
+
+### Quality & Review
+- `/gss:review-spec` — Red-team a spec for ambiguity and missing states
+- `/gss:handoff` — Generate requirements mapping for engineering
+
+### Status
+- `/gss:progress` — Show all specs and their status (Draft/Review/Ready)
+
+## Typical Flow
+
+```
+1. /gss:setup          ← First time only
+2. /gss:new-spec       ← Create spec with intake questions
+3. /gss:review-spec    ← Red-team for gaps
+4. /gss:handoff        ← Generate engineering requirements
+```
+
+## Spec Tiers
+
+| Tier | Files | Agents | When |
+|------|-------|--------|------|
+| Micro | SPEC.md | None | Quick fixes |
+| Standard | BRIEF, SCOPE, ACCEPTANCE | 2 | Most features |
+| Full | All 5 files | 6 | Complex features |
+
+## More Info
+
+- Config reference: `.claude/get-shit-specd/references/spec-config.md`
+- Workflow details: `.claude/get-shit-specd/workflows/`
+- Agent definitions: `.claude/agents/gss-*.md`
+
+</process>

package/claude/commands/gss/new-spec.md

@@ -0,0 +1,51 @@
+---
+name: gss:new-spec
+description: Create a new spec package for a feature
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Create a new spec package in .planning/specs/ with BRIEF, SCOPE, UX, DATA, ACCEPTANCE, and STATE.
+</objective>
+
+<execution_context>
+@./.claude/get-shit-specd/workflows/create-spec.md
+@./.claude/get-shit-specd/references/product-questioning.md
+</execution_context>
+
+<process>
+
+## Phase 1: Setup (mandatory)
+1. Ensure .planning exists:
+```bash
+mkdir -p .planning/specs
+```
+
+2. Ensure spec config exists or create it:
+- If missing, run /gss:settings logic.
+
+## Phase 2: Intake
+Ask the minimum questions to define:
+- spec name
+- user/context
+- v1 goal
+- in/out scope
+- key screens
+- roles/permissions
+- acceptance definition
+
+## Phase 3: Create spec folder
+Create folder: .planning/specs/SPEC-{{id}}-{{slug}}/
+Create 00-04 files and STATE.md using the create-spec workflow.
+
+## Phase 4: Output
+Print:
+- Spec folder path
+- Current status (Draft/Review/Ready)
+- Blocking open questions (if any)
+- Next command suggestion: /gss:review-spec or /gss:handoff
+</process>

package/claude/commands/gss/progress.md

@@ -0,0 +1,18 @@
+---
+name: gss:progress
+description: Show spec inventory and status
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+  - AskUserQuestion
+---
+<objective>
+List all specs in .planning/specs and show their STATE.md status.
+</objective>
+
+<process>
+1. Find .planning/specs/*/STATE.md
+2. Print a short table: spec_id | name | status | open_questions_count | last_updated
+</process>

package/claude/commands/gss/review-spec.md

@@ -0,0 +1,23 @@
+---
+name: gss:review-spec
+description: Red-team a spec for ambiguity and missing states
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Find gaps before engineering starts. Produce REVIEW.md and optionally patch spec files.
+</objective>
+
+<execution_context>
+@./.claude/get-shit-specd/workflows/review-spec.md
+</execution_context>
+
+<process>
+1. Ask for spec_id or detect.
+2. Run the review workflow.
+3. Output: PASS/FAIL and any blocking questions.
+</process>

package/claude/commands/gss/settings.md

@@ -0,0 +1,20 @@
+---
+name: gss:settings
+description: Create or edit .planning/spec-config.json
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Ensure spec preferences exist at .planning/spec-config.json without overwriting existing GSD config.
+</objective>
+
+<process>
+1. If .planning/spec-config.json does not exist, create it with sensible defaults from:
+@./.claude/get-shit-specd/references/spec-config.md
+
+2. If it exists, show current settings and allow updates.
+</process>

package/claude/commands/gss/setup.md

@@ -0,0 +1,149 @@
+---
+name: gss:setup
+description: Interactive setup for GSS spec configuration
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - AskUserQuestion
+---
+<objective>
+Configure GSS for this project through interactive questions.
+Creates .planning/spec-config.json with settings tailored to your team and workflow.
+</objective>
+
+<execution_context>
+@./.claude/get-shit-specd/references/spec-config.md
+</execution_context>
+
+<process>
+
+## Phase 1: Check existing config
+```bash
+mkdir -p .planning
+```
+
+If .planning/spec-config.json exists:
+- Show current config
+- Ask: "Start fresh or edit existing?"
+- If edit, show current values as defaults in questions
+
+## Phase 2: Audience question
+Ask using AskUserQuestion:
+```
+Question: "Who will consume these specs?"
+Options:
+- "Just me + AI" → solo (lighter detail, faster iteration)
+- "Small team (2-5)" → small_team (standard detail)
+- "Larger team or contractors" → external (maximum detail, no assumptions)
+```
+
+## Phase 3: Default tier question
+Ask using AskUserQuestion:
+```
+Question: "What's your typical spec complexity?"
+Options:
+- "Quick fixes and small changes" → micro (single file, no agents)
+- "Most features" → standard (BRIEF + SCOPE + ACCEPTANCE)
+- "Complex multi-part features" → full (all 5 files + all agents)
+```
+
+## Phase 4: Strictness question
+Ask using AskUserQuestion:
+```
+Question: "How strict should spec enforcement be?"
+Options:
+- "Relaxed" → min_edge_cases: 1, min_out_of_scope: 1, max_open_questions: 5
+- "Standard (Recommended)" → min_edge_cases: 3, min_out_of_scope: 2, max_open_questions: 3
+- "Strict" → min_edge_cases: 5, min_out_of_scope: 3, max_open_questions: 2
+```
+
+## Phase 5: Format preferences
+Ask using AskUserQuestion:
+```
+Question: "Do you use Gherkin (Given/When/Then) for acceptance criteria?"
+Options:
+- "Yes" → require_gherkin: true
+- "No, plain language is fine" → require_gherkin: false
+```
+
+## Phase 6: Write config
+Create .planning/spec-config.json with:
+```json
+{
+  "output_dir": ".planning/specs",
+  "id_prefix": "SPEC",
+  "audience": "[from Q2]",
+  "default_tier": "[from Q3]",
+
+  "require_ascii_wireframes": true,
+  "require_gherkin": [from Q5],
+  "require_priorities": true,
+
+  "min_edge_cases": [from Q4],
+  "min_out_of_scope": [from Q4],
+  "max_open_questions": [from Q4],
+
+  "require_p0_coverage": true,
+  "require_all_states": true,
+  "require_nonfunctional_requirements": true,
+  "require_analytics_events": true,
+
+  "agents": {
+    "micro_tier": [],
+    "standard_tier": ["acceptance-writer", "spec-checker"],
+    "full_tier": ["ux-designer", "data-modeler", "acceptance-writer", "synthesizer", "spec-checker"]
+  }
+}
+```
+
+## Phase 7: Confirmation
+Print:
+- Config file location
+- Summary of choices
+- Suggest: "Run /gss:new-spec to create your first spec"
+
+</process>
+
+<presets>
+## Audience Presets
+
+### solo
+- Lighter detail requirements
+- min_edge_cases: 2
+- Skip synthesizer agent
+- Faster iteration
+
+### small_team
+- Standard detail
+- min_edge_cases: 3
+- All agents for full tier
+- Balanced rigor
+
+### external
+- Maximum detail
+- min_edge_cases: 5
+- All agents always
+- No assumptions about shared context
+- require_ascii_wireframes: true
+
+## Strictness Presets
+
+### relaxed
+- min_edge_cases: 1
+- min_out_of_scope: 1
+- max_open_questions: 5
+- Good for early exploration
+
+### standard
+- min_edge_cases: 3
+- min_out_of_scope: 2
+- max_open_questions: 3
+- Recommended for most teams
+
+### strict
+- min_edge_cases: 5
+- min_out_of_scope: 3
+- max_open_questions: 2
+- For high-stakes features or external teams
+</presets>

package/claude/commands/gss/update-spec.md

@@ -0,0 +1,26 @@
+---
+name: gss:update-spec
+description: Update an existing spec package
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Update an existing spec package after scope changes, UX changes, or new constraints.
+Re-run the spec checker and update STATE.md.
+</objective>
+
+<execution_context>
+@./.claude/get-shit-specd/workflows/create-spec.md
+</execution_context>
+
+<process>
+1. Ask for spec_id or detect from .planning/specs/ if only one exists.
+2. Read existing files.
+3. Ask only questions needed to resolve changes.
+4. Patch files and re-run spec_check.
+5. Update STATE.md.
+</process>

package/claude/get-shit-specd/VERSION

@@ -0,0 +1 @@
+0.2.0

package/claude/get-shit-specd/references/acceptance-patterns.md

@@ -0,0 +1,19 @@
+# Acceptance Patterns
+
+Write acceptance as testable scenarios.
+
+Coverage set (minimum):
+- Happy path
+- Validation error
+- Permission denied
+- Empty state
+- Failure and retry
+- Analytics events emitted
+- Performance requirement (if stated)
+- Accessibility requirement (if stated)
+
+Style:
+- Prefer Gherkin (Given/When/Then)
+- Keep each scenario independent
+- Use concrete values, not “works” or “properly”
+- If the UI is specified, criteria must reference exact labels and states

package/claude/get-shit-specd/references/product-questioning.md

@@ -0,0 +1,42 @@
+# Product Questioning Protocol (Spec Intake)
+
+Goal: Convert a vague idea into a testable spec package.
+
+Principles:
+- Ask the minimum number of questions that change build decisions.
+- If unknown, write explicit assumptions and track them as Open Questions.
+- Prefer outcomes over implementation.
+- Enumerate states. Most spec failures are missing empty/loading/error/permission states.
+
+Question stack (ask in this order):
+
+1) User and context
+- Who is the user?
+- What is the moment they need this?
+- What do they do today?
+
+2) Problem and desired outcome
+- What is painful today?
+- What does “better” look like in 1-2 sentences?
+- What is the smallest v1 that delivers the outcome?
+
+3) Scope boundaries
+- What must be in v1?
+- What is explicitly out of scope?
+- What constraints matter (time, policy, platform, performance)?
+
+4) UX and states
+- What is the primary flow?
+- What are the key screens?
+- What are the loading/empty/error states?
+- What are the permissions and roles?
+
+5) Acceptance and verification
+- What must be true for you to say “this is done”?
+- What is the highest-risk edge case?
+- What can we measure?
+
+Always end intake with:
+- Top 5 ambiguities that would change the build
+- Assumptions list
+- Open questions list with owners and dates

package/claude/get-shit-specd/references/spec-config.md

@@ -0,0 +1,86 @@
+# Spec Config (Preferences)
+
+These preferences drive how specs are written and how strict the checker is.
+
+## Full Configuration
+
+```json
+{
+  // Output
+  "output_dir": ".planning/specs",
+  "id_prefix": "SPEC",
+
+  // Audience (affects detail level and agent usage)
+  "audience": "solo | small_team | external",
+
+  // Default tier (can override per spec)
+  "default_tier": "standard",
+
+  // Content requirements
+  "require_ascii_wireframes": true,
+  "require_gherkin": true,
+  "require_priorities": true,
+
+  // Enforcement thresholds
+  "min_edge_cases": 3,
+  "min_out_of_scope": 2,
+  "max_open_questions": 3,
+
+  // Quality gates
+  "require_p0_coverage": true,
+  "require_all_states": true,
+  "require_nonfunctional_requirements": true,
+  "require_analytics_events": true,
+
+  // Agent configuration
+  "agents": {
+    "micro_tier": [],
+    "standard_tier": ["acceptance-writer", "spec-checker"],
+    "full_tier": ["ux-designer", "data-modeler", "acceptance-writer", "synthesizer", "spec-checker"]
+  }
+}
+```
+
+## Audience Presets
+
+**solo** (just you + AI):
+- Lighter detail, faster iteration
+- Skip synthesizer (you hold context)
+- min_edge_cases: 2
+
+**small_team** (2-5 close collaborators):
+- Standard detail
+- All agents for Full tier
+- min_edge_cases: 3
+
+**external** (contractors, external team):
+- Maximum detail, no assumptions
+- All agents always
+- min_edge_cases: 5
+- require_ascii_wireframes: true (no Figma assumptions)
+
+## Tier Behavior
+
+**Micro tier:**
+- Single SPEC.md file
+- 3 intake questions
+- No agents
+- Fast path for simple changes
+
+**Standard tier:**
+- BRIEF, SCOPE, ACCEPTANCE
+- 10 intake questions
+- acceptance-writer + spec-checker agents
+- Most features
+
+**Full tier:**
+- All 5 files
+- All intake questions
+- All agents (drafting + quality)
+- Complex multi-part features
+
+## Installation
+
+Run `/gss:setup` to create .planning/spec-config.json interactively.
+
+If a project already has config, GSS respects it and doesn't overwrite.

package/claude/get-shit-specd/references/ux-brand.md

@@ -0,0 +1,15 @@
+# UX Writing and Brand Notes
+
+Goal: UI text that is clear, short, and consistent.
+
+Rules:
+- Use active voice
+- Prefer specific labels over clever ones
+- Error messages: say what happened, why, and what to do next
+- Avoid jargon unless the user is expert
+- Always include:
+  - primary CTA label
+  - secondary action label (if exists)
+  - empty state copy
+  - error state copy
+  - success confirmation (toast or inline)

package/claude/get-shit-specd/templates/acceptance.md

@@ -0,0 +1,48 @@
+# Acceptance
+
+Definition of done
+- All acceptance scenarios pass
+- Observability goals met per DATA.md
+- Constraints satisfied per SCOPE.md
+
+## Gherkin scenarios
+
+```gherkin
+Feature: {{FEATURE_NAME}}
+
+Scenario: Happy path
+  Given {{GIVEN}}
+  When {{WHEN}}
+  Then {{THEN}}
+
+Scenario: Validation error
+  Given {{GIVEN}}
+  When {{WHEN}}
+  Then {{THEN}}
+
+Scenario: Permission denied
+  Given {{GIVEN}}
+  When {{WHEN}}
+  Then {{THEN}}
+
+Scenario: Empty state
+  Given {{GIVEN}}
+  When {{WHEN}}
+  Then {{THEN}}
+
+Scenario: Failure recovery
+  Given {{GIVEN}}
+  When {{WHEN}}
+  Then {{THEN}}
+
+Scenario: Key events emitted
+  Given {{GIVEN}}
+  When {{WHEN}}
+  Then events include {{EVENTS}}
+```
+
+## Verification notes
+
+What must be demonstrably true (engineering determines how to verify):
+- {{VERIFICATION_1}}
+- {{VERIFICATION_2}}

package/claude/get-shit-specd/templates/brief.md

@@ -0,0 +1,31 @@
+# SPEC: {{SPEC_NAME}}
+Owner: {{OWNER}}
+Date: {{DATE}}
+Status: Draft | Review | Ready
+
+Problem
+{{PROBLEM}}
+
+User and context
+{{USER_CONTEXT}}
+
+JTBD
+When {{SITUATION}}, I want to {{MOTIVATION}}, so I can {{OUTCOME}}.
+
+Goal (v1)
+{{GOAL}}
+
+Success metrics
+{{METRICS}}
+
+Constraints
+{{CONSTRAINTS}}
+
+Risks
+{{RISKS}}
+
+Assumptions
+{{ASSUMPTIONS}}
+
+Open questions
+{{OPEN_QUESTIONS}}

package/claude/get-shit-specd/templates/data.md

@@ -0,0 +1,34 @@
+# Data and behavior
+
+## Entities impacted
+- {{ENTITY_1}}
+
+## Permissions
+- Roles: {{ROLES}}
+- Read rules: {{READ_RULES}}
+- Write rules: {{WRITE_RULES}}
+
+## State machine
+- States: {{STATES}}
+- Transitions: {{TRANSITIONS}}
+
+## Integrations
+- {{INTEGRATION_1}}
+
+## Observability goals
+
+What we need to know (engineering determines implementation):
+- Success/failure visibility: {{SUCCESS_FAILURE_GOAL}}
+- Performance visibility: {{PERF_GOAL}}
+- Security visibility: {{SECURITY_GOAL}}
+
+## Edge cases
+
+Scenarios that must be handled:
+1. {{EDGE_1}}
+2. {{EDGE_2}}
+
+## Data considerations
+
+- New data: {{NEW_DATA}}
+- Migration needs: {{MIGRATION_NEEDS}}