get-shit-specd 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brannon Lucas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+# get-shit-specd (GSS)
+
+Spec-first development workflow for [Claude Code](https://claude.ai/code). Transform vague ideas into engineering-ready specifications.
+
+## What is GSS?
+
+GSS is a structured workflow that helps you think through features **before** writing code. It guides you through:
+
+1. **Problem Definition** — What are you solving and for whom?
+2. **Scope** — What's in, what's out, what are the dependencies?
+3. **UX Design** — Screens, flows, states, copy (Full tier only)
+4. **Data Modeling** — Entities, permissions, state machines (Full tier only)
+5. **Acceptance Criteria** — Gherkin scenarios that define "done"
+
+The output is an engineering-ready handoff document with requirements mapped to testable acceptance criteria.
+
+## Requirements
+
+- [Bun](https://bun.sh) v1.0 or later
+
+```bash
+# Install Bun (if needed)
+curl -fsSL https://bun.sh/install | bash
+```
+
+## Installation
+
+```bash
+cd your-project
+bunx get-shit-specd init
+```
+
+This creates:
+- `.claude/commands/gss/` — Slash commands
+- `.claude/agents/gss-*` — AI agents for drafting and review
+- `.claude/get-shit-specd/` — Workflows, templates, references
+- `.planning/spec-config.json` — Your preferences
+- `.planning/specs/` — Where specs live
+
+## Usage
+
+After installation, use these commands in Claude Code:
+
+| Command | Description |
+|---------|-------------|
+| `/gss:setup` | Configure preferences (audience, tier, strictness) |
+| `/gss:new-spec` | Create a new spec package |
+| `/gss:review-spec <id>` | Red-team a spec for gaps |
+| `/gss:handoff <id>` | Generate engineering requirements |
+| `/gss:progress` | Show spec inventory and status |
+| `/gss:help` | Show all commands |
+
+### Typical Workflow
+
+```
+/gss:setup                          # One-time configuration
+/gss:new-spec                       # Start a new feature spec
+  → Answer intake questions
+  → AI drafts spec files
+  → Quality gates enforce completeness
+/gss:review-spec SPEC-001           # Red-team for gaps
+/gss:handoff SPEC-001               # Generate engineering doc
+```
+
+## Spec Tiers
+
+| Tier | Files | Best For |
+|------|-------|----------|
+| **Micro** | Single BRIEF+SCOPE combined | Bug fixes, small changes |
+| **Standard** | BRIEF + SCOPE + ACCEPTANCE | Most features |
+| **Full** | All 5 files including UX + DATA | Complex features, new surfaces |
+
+## Configuration
+
+Edit `.planning/spec-config.json`:
+
+```json
+{
+  "audience": "external",           // solo, small_team, external
+  "default_tier": "standard",       // micro, standard, full
+  "min_edge_cases": 5,              // Minimum edge cases required
+  "min_out_of_scope": 3,            // Minimum out-of-scope items
+  "max_open_questions": 2,          // Maximum unresolved questions
+  "require_gherkin": true           // Require Gherkin format
+}
+```
+
+### Audience Presets
+
+| Audience | Style | Edge Cases | Out of Scope |
+|----------|-------|------------|--------------|
+| `solo` | Informal, minimal docs | 2+ | 1+ |
+| `small_team` | Clear, some context | 3+ | 2+ |
+| `external` | Formal, full context | 5+ | 3+ |
+
+## Spec Package Structure
+
+A complete spec package (Standard tier):
+
+```
+.planning/specs/SPEC-001-feature-name/
+├── 00-BRIEF.md       # Problem, JTBD, success metrics
+├── 01-SCOPE.md       # In/out scope, dependencies, NFRs
+├── 04-ACCEPTANCE.md  # Gherkin scenarios, edge cases
+├── STATE.md          # Status tracking
+├── REVIEW.md         # Red-team findings (after review)
+└── HANDOFF.md        # Engineering requirements (after handoff)
+```
+
+Full tier adds:
+- `02-UX.md` — Screens, flows, states, copy
+- `03-DATA.md` — Entities, permissions, state machines
+
+## Philosophy: WHAT/WHY, not HOW/WHEN
+
+GSS specs define:
+- **WHAT** must be true (outcomes, acceptance criteria)
+- **WHY** it matters (problem, success metrics)
+
+They do NOT define:
+- **HOW** to build it (architecture, file paths, implementation)
+- **WHEN** to ship it (phases, sprints, task breakdowns)
+
+Engineering determines HOW and WHEN during implementation.
+
+## Example
+
+See `examples/SPEC-003-watermarking-service/` for a complete spec package demonstrating:
+- Problem definition with clear JTBD
+- Scoped outcomes with P0/P1/P2 priorities
+- 8 Gherkin acceptance scenarios
+- 8 edge cases with expected behaviors
+- Engineering handoff with requirement IDs
+
+## Updating
+
+```bash
+bunx get-shit-specd update
+```
+
+This updates GSS files while preserving your `spec-config.json`.
+
+## License
+
+MIT

package/bin/gss.ts

@@ -0,0 +1,160 @@
+#!/usr/bin/env bun
+
+import { existsSync, mkdirSync, cpSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+
+const packageRoot = resolve(import.meta.dir, "..");
+const packageJson = JSON.parse(
+  readFileSync(join(packageRoot, "package.json"), "utf-8")
+) as { version: string };
+const VERSION = packageJson.version;
+
+const command = process.argv[2];
+const targetDir = process.cwd();
+
+interface SpecConfig {
+  audience: "solo" | "small_team" | "external";
+  default_tier: "micro" | "standard" | "full";
+  min_edge_cases: number;
+  min_out_of_scope: number;
+  max_open_questions: number;
+  require_gherkin: boolean;
+  agents: {
+    micro_tier: string[];
+    standard_tier: string[];
+    full_tier: string[];
+  };
+}
+
+function printHelp(): void {
+  console.log(`
+get-shit-specd v${VERSION}
+Spec-first development workflow for Claude Code
+
+USAGE:
+  bunx get-shit-specd <command>
+  npx get-shit-specd <command>
+
+COMMANDS:
+  init      Install GSS into current project's .claude/ directory
+  update    Update GSS files to latest version (preserves spec-config.json)
+  version   Show installed version
+
+AFTER INSTALL:
+  Use /gss:help in Claude Code to see available commands:
+  - /gss:setup     Configure spec preferences
+  - /gss:new-spec  Create a new spec package
+  - /gss:review-spec <id>  Red-team a spec
+  - /gss:handoff <id>      Generate engineering requirements
+  - /gss:progress  Show spec inventory
+`);
+}
+
+function init(update: boolean = false): void {
+  const claudeDir = join(targetDir, ".claude");
+  const planningDir = join(targetDir, ".planning");
+
+  // Create directories if needed
+  if (!existsSync(claudeDir)) {
+    mkdirSync(claudeDir, { recursive: true });
+  }
+  if (!existsSync(planningDir)) {
+    mkdirSync(planningDir, { recursive: true });
+  }
+
+  // Copy commands
+  const commandsSrc = join(packageRoot, "claude", "commands", "gss");
+  const commandsDest = join(claudeDir, "commands", "gss");
+  if (existsSync(commandsSrc)) {
+    mkdirSync(dirname(commandsDest), { recursive: true });
+    cpSync(commandsSrc, commandsDest, { recursive: true });
+    console.log("  + .claude/commands/gss/");
+  }
+
+  // Copy agents
+  const agentsSrc = join(packageRoot, "claude", "agents");
+  const agentsDest = join(claudeDir, "agents");
+  if (existsSync(agentsSrc)) {
+    mkdirSync(agentsDest, { recursive: true });
+    cpSync(agentsSrc, agentsDest, { recursive: true });
+    console.log("  + .claude/agents/gss-*");
+  }
+
+  // Copy get-shit-specd core
+  const coreSrc = join(packageRoot, "claude", "get-shit-specd");
+  const coreDest = join(claudeDir, "get-shit-specd");
+  if (existsSync(coreSrc)) {
+    cpSync(coreSrc, coreDest, { recursive: true });
+    console.log("  + .claude/get-shit-specd/");
+  }
+
+  // Create default spec-config.json if not exists (skip on update)
+  const configPath = join(planningDir, "spec-config.json");
+  if (!existsSync(configPath) && !update) {
+    const defaultConfig: SpecConfig = {
+      audience: "solo",
+      default_tier: "standard",
+      min_edge_cases: 3,
+      min_out_of_scope: 2,
+      max_open_questions: 3,
+      require_gherkin: false,
+      agents: {
+        micro_tier: [],
+        standard_tier: ["acceptance-writer", "spec-checker"],
+        full_tier: [
+          "ux-designer",
+          "data-modeler",
+          "acceptance-writer",
+          "synthesizer",
+          "spec-checker",
+        ],
+      },
+    };
+    writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2));
+    console.log("  + .planning/spec-config.json (default config)");
+  } else if (existsSync(configPath)) {
+    console.log("  ~ .planning/spec-config.json (preserved)");
+  }
+
+  // Create specs directory
+  const specsDir = join(planningDir, "specs");
+  if (!existsSync(specsDir)) {
+    mkdirSync(specsDir, { recursive: true });
+    console.log("  + .planning/specs/");
+  }
+
+  console.log(`
+GSS ${update ? "updated" : "installed"} successfully!
+
+Next steps:
+  1. Run /gss:setup in Claude Code to configure preferences
+  2. Run /gss:new-spec to create your first spec
+  3. Run /gss:help for all available commands
+`);
+}
+
+switch (command) {
+  case "init":
+    console.log(`\nInstalling get-shit-specd v${VERSION}...\n`);
+    init(false);
+    break;
+  case "update":
+    console.log(`\nUpdating get-shit-specd to v${VERSION}...\n`);
+    init(true);
+    break;
+  case "version":
+  case "-v":
+  case "--version":
+    console.log(`get-shit-specd v${VERSION}`);
+    break;
+  case "help":
+  case "-h":
+  case "--help":
+  case undefined:
+    printHelp();
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    printHelp();
+    process.exit(1);
+}

package/claude/agents/gss-acceptance-writer.md

@@ -0,0 +1,58 @@
+# gss-acceptance-writer
+
+Role: Draft 04-ACCEPTANCE.md from SCOPE, UX, and DATA.
+
+## Input
+You receive:
+- 01-SCOPE.md (in/out scope with priorities)
+- 02-UX.md (screens, states, flows) - if Full tier
+- 03-DATA.md (entities, permissions, edge cases) - if Full tier
+
+## Output
+Draft 04-ACCEPTANCE.md with:
+
+### Definition of Done
+Standard checklist. Don't over-customize.
+
+### Gherkin Scenarios
+Write scenarios using Given/When/Then format.
+
+REQUIRED scenarios (minimum coverage set):
+1. **Happy path** - Main success flow works
+2. **Validation error** - Bad input handled gracefully
+3. **Permission denied** - Unauthorized access blocked
+4. **Empty state** - No data case handled
+5. **Failure recovery** - System failure handled gracefully
+6. **Key events emitted** - Observability verified
+
+ADDITIONAL scenarios:
+- One scenario per P0 scope item (from SCOPE.md)
+- One scenario per edge case (from DATA.md)
+
+### Scenario Writing Rules
+- **Given**: Setup state. Be specific. "Given a deck with 3 generated cards"
+- **When**: Single action. "When the user clicks Purchase"
+- **Then**: Observable outcome. "Then the order confirmation is displayed"
+
+Avoid:
+- Vague terms: "works correctly", "is valid", "properly handles"
+- Implementation details: "the database is updated" (not observable)
+- Multiple actions in When: split into separate scenarios
+
+### Verification Notes
+What must be demonstrably true. Engineering determines HOW to verify.
+
+NOT: "Unit test the watermark function"
+YES: "Watermarked images are visually distinguishable from clean images"
+
+## Rules
+- Every P0 scope item MUST have a scenario. No exceptions.
+- Every edge case from DATA.md SHOULD have a scenario.
+- Scenarios must be objectively testable - no judgment calls.
+
+## Quality Check
+Before submitting, verify:
+- [ ] All 6 required scenario types present
+- [ ] Every P0 scope item has a scenario
+- [ ] No vague language ("works", "properly", "correctly")
+- [ ] Each scenario has exactly one When clause

package/claude/agents/gss-data-modeler.md

@@ -0,0 +1,67 @@
+# gss-data-modeler
+
+Role: Draft 03-DATA.md from BRIEF, SCOPE, and UX (if available).
+
+## Input
+You receive:
+- 00-BRIEF.md (problem, goal)
+- 01-SCOPE.md (in/out scope)
+- 02-UX.md (screens and flows, if Full tier)
+
+## Output
+Draft 03-DATA.md with:
+
+### Entities Impacted
+List tables/collections affected. Note if new or modified.
+
+### Permissions
+- **Roles**: Who can do what (anonymous, authenticated, owner, admin)
+- **Read rules**: Who sees what data
+- **Write rules**: Who modifies what data
+
+Be explicit. "User can edit their own decks" not "users can edit decks."
+
+### State Machine
+If the feature has state transitions:
+- Draw the states
+- Define transitions (what triggers each)
+- Note any irreversible transitions
+
+### Integrations
+External systems touched:
+- APIs called
+- Webhooks received
+- Third-party services
+
+### Observability Goals
+What do we need to know? (Not specific log formats - that's engineering's job)
+- Success/failure visibility
+- Performance visibility
+- Security/audit visibility
+
+### Edge Cases
+MINIMUM 3 edge cases. This is where specs fail.
+
+Think about:
+- What if it fails halfway?
+- What if user does action twice?
+- What if related data is deleted?
+- What if permissions change mid-flow?
+- What about race conditions?
+- What about refunds/reversals?
+
+### Data Considerations
+- New data: What's being stored that wasn't before?
+- Migration: Does existing data need updating?
+
+## Rules
+- Edge cases are NOT optional. Minimum 3.
+- Permissions must be explicit per role.
+- State machines need ALL states, including failure states.
+
+## Quality Check
+Before submitting, verify:
+- [ ] At least 3 edge cases documented
+- [ ] Permissions explicit for each role
+- [ ] State machine has failure/error states
+- [ ] No vague language ("users can access" → WHO specifically?)

package/claude/agents/gss-product-researcher.md

@@ -0,0 +1,56 @@
+# gss-product-researcher
+
+Role: Quick domain and competitive scan when the problem space is unfamiliar.
+
+## When to Use
+- User is building something in an unfamiliar domain
+- Multiple valid approaches exist and user needs context
+- Competitive landscape would inform scope decisions
+- Technical constraints are unclear
+
+## NOT When to Use
+- User already knows the domain well
+- Simple feature with clear requirements
+- Internal tooling with no competitors
+
+## Input
+You receive:
+- User's initial request or problem statement
+- Any context about what they're building
+
+## Process
+1. **Domain scan**: What does this problem space look like?
+2. **Competitor scan**: Who else solves this? How?
+3. **Pattern scan**: What are common approaches?
+4. **Risk scan**: What typically goes wrong?
+
+## Output
+```
+## Research: [Topic]
+
+### Domain Context
+[3-5 bullets on the problem space]
+
+### Existing Solutions
+| Solution | Approach | Strengths | Weaknesses |
+|----------|----------|-----------|------------|
+| ... | ... | ... | ... |
+
+### Common Patterns
+[3-5 approaches with tradeoffs]
+
+### Risks & Pitfalls
+[5 things that commonly go wrong in this space]
+
+### Recommendation
+[Which approach fits user's context, with reasoning]
+
+### Sources
+[If web search used, list sources]
+```
+
+## Rules
+- Keep it brief. 10-15 minutes of research, not a thesis.
+- Focus on what changes BUILD decisions.
+- If research doesn't add value, say so and skip it.
+- Bias toward "you probably don't need this" for simple features.

package/claude/agents/gss-spec-checker.md

@@ -0,0 +1,87 @@
+# gss-spec-checker
+
+Role: Enforce Ready gate. Block specs that don't meet quality bar.
+
+## Input
+You receive:
+- All spec files
+- .planning/spec-config.json (enforcement settings)
+- Synthesizer report (if run)
+
+## Configuration (from spec-config.json)
+```json
+{
+  "min_edge_cases": 3,
+  "min_out_of_scope": 2,
+  "max_open_questions": 3,
+  "require_p0_coverage": true,
+  "require_all_states": true
+}
+```
+
+## Checks
+
+### File Completeness
+Based on tier:
+- Micro: SPEC.md exists
+- Standard: BRIEF, SCOPE, ACCEPTANCE exist
+- Full: All 5 files exist
+
+### Edge Case Minimum
+- Count edge cases in DATA.md (or ACCEPTANCE.md for Standard tier)
+- FAIL if < min_edge_cases
+
+### Scope Clarity
+- Count explicit "out of scope" items
+- FAIL if < min_out_of_scope
+- WARN if in-scope items lack priority (P0/P1/P2)
+
+### Open Questions
+- Count open questions across all files
+- FAIL if > max_open_questions
+
+### P0 Coverage (if require_p0_coverage)
+- Every P0 scope item must have acceptance scenario
+- FAIL if any P0 lacks scenario
+
+### State Completeness (if require_all_states)
+- Every UX screen must have: loading, empty, error, success states
+- FAIL if any screen missing states
+
+### Acceptance Testability
+- Scan for vague language: "works", "properly", "correctly", "valid"
+- WARN for each instance (suggest specific replacement)
+
+### Synthesizer Issues
+- If synthesizer ran, any FAIL items block Ready
+- WARN items are advisory
+
+## Output Format
+```
+## Spec Check: [SPEC-ID]
+
+### Status: READY | NOT READY
+
+### Blocking Issues (must fix)
+1. [issue] → [fix]
+2. [issue] → [fix]
+
+### Warnings (should fix)
+1. [issue] → [suggestion]
+
+### Passed Checks
+- [list of passed checks]
+
+### Ready Gate Score
+Files: ✓
+Edge cases: ✓ (5/3 minimum)
+Out of scope: ✓ (3/2 minimum)
+Open questions: ✓ (2/3 maximum)
+P0 coverage: ✓
+States: ✓
+```
+
+## Rules
+- Be strict. The point is to catch problems BEFORE engineering starts.
+- Every blocking issue needs a concrete fix.
+- Don't pass specs that will cause rework.

package/claude/agents/gss-spec-synthesizer.md

@@ -0,0 +1,68 @@
+# gss-spec-synthesizer
+
+Role: Cross-check spec files for coherence and contradictions.
+
+## Input
+You receive all spec files:
+- 00-BRIEF.md
+- 01-SCOPE.md
+- 02-UX.md (if exists)
+- 03-DATA.md (if exists)
+- 04-ACCEPTANCE.md
+
+## Output
+A coherence report with:
+
+### Cross-File Checks
+
+**SCOPE ↔ ACCEPTANCE alignment:**
+- Every in-scope P0 item must have an acceptance scenario
+- Every acceptance scenario must trace to a scope item
+- Flag: Scope items without scenarios
+- Flag: Scenarios without scope items (scope creep)
+
+**UX ↔ DATA alignment:**
+- Every UX role must appear in DATA permissions
+- Every UX state must have a data condition
+- Flag: Roles in UX not in DATA permissions
+- Flag: States in UX without data backing
+
+**BRIEF ↔ SCOPE alignment:**
+- Goal in BRIEF should be achievable with in-scope items
+- Constraints in BRIEF should appear in SCOPE NFRs
+- Flag: Goals not covered by scope
+- Flag: Constraints mentioned but not tracked
+
+**DATA ↔ ACCEPTANCE alignment:**
+- Every edge case should have a scenario (or explicit "not testing" note)
+- Flag: Edge cases without scenarios
+
+### Terminology Consistency
+- Same concepts should use same names across files
+- Flag: "deck" vs "pack" vs "order" inconsistency
+- Flag: Role names that differ between files
+
+### Contradiction Detection
+Look for:
+- Scope says X is out, but UX shows X
+- Permissions say role can't do Y, but acceptance tests Y
+- BRIEF says constraint Z, but SCOPE doesn't mention Z
+
+## Output Format
+```
+## Coherence Report
+
+### PASS
+- [list of checks that passed]
+
+### WARN (should fix)
+- [issues that reduce clarity but don't block]
+
+### FAIL (must fix before Ready)
+- [contradictions, missing coverage, broken traces]
+```
+
+## Rules
+- Be pedantic. Small inconsistencies become big bugs.
+- Every flag needs a specific fix recommendation.
+- Don't just list problems - show what to change.