get-shit-specd 0.2.0 → 0.4.1

package/README.md

@@ -140,6 +140,12 @@ bunx get-shit-specd update
 
 This updates GSS files while preserving your `spec-config.json`.
 
+## Acknowledgments
+
+GSS was heavily influenced by [get-shit-done (GSD)](https://github.com/glittercowboy/get-shit-done), an execution-focused workflow for Claude Code. Where GSD excels at **building** (phases, plans, atomic commits), GSS focuses on what comes **before** — ensuring you spec the right thing before you build it.
+
+They're designed to work together: GSS specs feed into GSD phases.
+
 ## License
 
 MIT

package/claude/agents/gss-contract-architect.md

@@ -0,0 +1,82 @@
+# gss-contract-architect
+
+Role: Analyze multiple specs to extract shared contracts and file ownership boundaries for parallel development.
+
+## Input
+You receive:
+- Implementation Surface sections from all Ready/Handed Off specs
+- Project context: existing types, design tokens, routes, and component inventory from the codebase
+- List of spec IDs being coordinated
+
+## Process
+
+### 1. Catalog All Surfaces
+For each spec, extract:
+- Files created (exclusive ownership)
+- Files modified (shared — coordination needed)
+- Types consumed and created
+- Tokens referenced
+- Routes added
+- Components consumed and created
+
+### 2. Detect Conflicts
+Check for:
+- **File creation conflicts:** Two specs creating the same file → CONFLICT
+- **Type name collisions:** Two specs defining the same type → CONFLICT
+- **Route collisions:** Overlapping route patterns → CONFLICT
+- **Component name collisions:** Two specs creating same component → CONFLICT
+
+### 3. Map Dependencies
+Identify directional dependencies:
+- Spec A creates type `Deck`, Spec B consumes type `Deck` → B depends on A
+- Spec A creates `<CardGrid>`, Spec B uses `<CardGrid>` → B depends on A
+
+This informs dispatch order: dependency providers should start first or their contracts must be defined upfront.
+
+### 4. Define Type Contracts
+For each shared type:
+```typescript
+// Owner: SPEC-001 | Consumers: SPEC-002, SPEC-003
+interface Deck {
+  id: string;
+  name: string;
+  cards: Card[];
+}
+```
+
+Use existing codebase types as the starting point. Flag any spec that redefines an existing type.
+
+### 5. Define Component API Contracts
+For each shared component:
+```typescript
+// Owner: SPEC-001 | Consumers: SPEC-002
+interface CardGridProps {
+  cards: Card[];
+  columns?: number;
+}
+```
+
+### 6. Build File Ownership Matrix
+Every file mentioned across all specs gets exactly one classification:
+- **Exclusive:** Created by one spec, untouched by others
+- **Shared-modify:** Modified by multiple specs (list all)
+- **Conflict:** Created by multiple specs (must resolve)
+
+### 7. Generate Dispatch Guidance
+For each spec, output:
+- Suggested branch name
+- Files this spec owns exclusively
+- Shared files needing merge coordination
+- Contract dependencies (types/components this spec consumes from others)
+- Recommended dispatch order based on dependency graph
+
+## Output Format
+Write CONTRACTS.md using the contracts template with all sections populated.
+
+## Key Rules
+- Every created file MUST have exactly one owner spec
+- Modified files are NOT exclusive — list all specs that touch them
+- Type names MUST be consistent across specs (flag mismatches)
+- Token references must match codebase tokens (flag unknown tokens as NEW)
+- When in doubt, flag as a conflict — false positives are cheaper than merge failures
+- Be specific: use exact file paths, type names, and prop definitions

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

@@ -52,6 +52,17 @@ Based on tier:
 - Scan for vague language: "works", "properly", "correctly", "valid"
 - WARN for each instance (suggest specific replacement)
 
+### Implementation Surface Completeness
+Based on tier:
+- Micro: Skip (not applicable)
+- Standard: WARN if Implementation Surface section is missing or empty
+- Full: FAIL if Implementation Surface section is missing or empty
+
+When present, check:
+- At least one file in "Files Created"
+- Shared Surfaces section filled (or explicitly "None")
+- File paths look plausible (not just placeholders like "TBD" for Full tier)
+
 ### Synthesizer Issues
 - If synthesizer ran, any FAIL items block Ready
 - WARN items are advisory

package/claude/commands/gss/contracts.md

@@ -0,0 +1,59 @@
+---
+name: gss:contracts
+description: Extract shared contracts from Ready specs for parallel development
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Task
+  - Write
+---
+<objective>
+Read all Ready specs, identify shared surfaces (types, tokens, routes, components, files), and generate CONTRACTS.md with ownership boundaries for parallel agent dispatch.
+</objective>
+
+<process>
+
+<step name="find_specs">
+Read .planning/specs/ directory.
+Collect all specs with status Ready or Handed Off (check STATE.md in each).
+If fewer than 2 specs found, report: "Contracts require at least 2 Ready specs. Found {{count}}." and stop.
+</step>
+
+<step name="collect_surfaces">
+For each qualifying spec, read 01-SCOPE.md and extract the Implementation Surface section:
+- Files Created
+- Files Modified
+- Shared Surfaces (types, tokens, routes, components)
+
+If a spec lacks an Implementation Surface section, WARN and skip it.
+</step>
+
+<step name="spawn_contract_architect">
+Spawn the gss-contract-architect agent with:
+- All collected Implementation Surface data
+- Project context (existing types, tokens, routes from codebase)
+- List of spec IDs being coordinated
+
+The agent analyzes overlaps, detects conflicts, and drafts CONTRACTS.md.
+
+Use Task tool:
+  subagent_type: "general-purpose"
+  prompt: Include gss-contract-architect agent instructions + collected surfaces
+  model: "sonnet"
+</step>
+
+<step name="write_contracts">
+Write the agent's output to .planning/CONTRACTS.md.
+If CONTRACTS.md already exists, archive the previous version as CONTRACTS.prev.md.
+</step>
+
+<step name="report">
+Present summary to user:
+- Number of specs analyzed
+- Shared surfaces found
+- Conflicts detected (if any)
+- File ownership matrix overview
+</step>
+
+</process>

package/claude/commands/gss/help.md

@@ -28,6 +28,9 @@ GSS is a spec workflow that produces outcome-focused specs. Specs define WHAT mu
 - `/gss:review-spec` — Red-team a spec for ambiguity and missing states
 - `/gss:handoff` — Generate requirements mapping for engineering
 
+### Coordination
+- `/gss:contracts` — Extract shared contracts from Ready specs for parallel development
+
 ### Status
 - `/gss:progress` — Show all specs and their status (Draft/Review/Ready)
 
@@ -37,7 +40,8 @@ GSS is a spec workflow that produces outcome-focused specs. Specs define WHAT mu
 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
+4. /gss:contracts      ← Extract shared contracts (when 2+ specs Ready)
+5. /gss:handoff        ← Generate engineering requirements
 ```
 
 ## Spec Tiers

package/claude/get-shit-specd/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

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

@@ -0,0 +1,108 @@
+# Contracts
+
+> Auto-generated by `/gss:contracts` — do not edit manually.
+> Re-run `/gss:contracts` after spec changes to refresh.
+
+**Specs analyzed:** {{SPEC_LIST}}
+**Generated:** {{DATE}}
+
+---
+
+## Type Contracts
+
+Shared type definitions that multiple specs depend on. Owner spec defines the type; consumer specs import it.
+
+| Type | Owner | Consumers | Status |
+|------|-------|-----------|--------|
+| {{TYPE_NAME}} | {{OWNER_SPEC}} | {{CONSUMER_SPECS}} | {{Stable/New/Conflict}} |
+
+### Definitions
+
+```typescript
+// {{TYPE_NAME}} — Owner: {{OWNER_SPEC}}
+// Consumers: {{CONSUMER_SPECS}}
+{{TYPE_DEFINITION}}
+```
+
+---
+
+## Token Contracts
+
+Design tokens referenced across specs. Tokens must exist in the codebase or be flagged as new.
+
+| Token | Referenced By | Status |
+|-------|--------------|--------|
+| {{TOKEN_NAME}} | {{SPEC_LIST}} | {{Exists/New}} |
+
+---
+
+## Route Contracts
+
+Full route map with ownership. Each route has exactly one owner spec.
+
+| Route | Owner | Method | Purpose |
+|-------|-------|--------|---------|
+| {{ROUTE_PATTERN}} | {{OWNER_SPEC}} | {{GET/POST/etc}} | {{DESCRIPTION}} |
+
+---
+
+## Component API Contracts
+
+Shared components with agreed-upon props interfaces.
+
+| Component | Owner | Consumers |
+|-----------|-------|-----------|
+| {{COMPONENT_NAME}} | {{OWNER_SPEC}} | {{CONSUMER_SPECS}} |
+
+### Props Interfaces
+
+```typescript
+// {{COMPONENT_NAME}} — Owner: {{OWNER_SPEC}}
+// Consumers: {{CONSUMER_SPECS}}
+{{PROPS_INTERFACE}}
+```
+
+---
+
+## File Ownership Matrix
+
+Every file referenced across specs, classified by ownership.
+
+### Exclusive (one spec creates, no others touch)
+
+| File | Owner |
+|------|-------|
+| {{FILE_PATH}} | {{OWNER_SPEC}} |
+
+### Shared (modified by multiple specs — coordinate merges)
+
+| File | Modified By |
+|------|-------------|
+| {{FILE_PATH}} | {{SPEC_LIST}} |
+
+### Conflicts (created by multiple specs — MUST resolve before dispatch)
+
+| File | Claimed By | Resolution |
+|------|-----------|------------|
+| {{FILE_PATH}} | {{SPEC_LIST}} | {{PENDING/RESOLVED: description}} |
+
+---
+
+## Dispatch Guidance
+
+Recommended dispatch order based on dependency graph.
+
+### Wave 1 (no dependencies — start immediately)
+- **{{SPEC_ID}}:** {{BRANCH_NAME}} — owns {{FILE_COUNT}} files, no contract dependencies
+
+### Wave 2 (depends on Wave 1 contracts)
+- **{{SPEC_ID}}:** {{BRANCH_NAME}} — depends on {{DEPENDENCY_LIST}} from Wave 1
+
+### Per-Spec Summary
+
+#### {{SPEC_ID}}: {{SPEC_NAME}}
+- **Branch:** `feature/{{SLUG}}`
+- **Exclusive files:** {{FILE_LIST}}
+- **Shared files:** {{FILE_LIST}}
+- **Consumes:** {{TYPE/COMPONENT_LIST}} from {{OTHER_SPECS}}
+- **Provides:** {{TYPE/COMPONENT_LIST}} to {{OTHER_SPECS}}

package/claude/get-shit-specd/templates/handoff-to-gsd.md

@@ -10,8 +10,11 @@ Translate a Ready spec into engineering-facing requirements. Engineering owns im
 
 ## Outputs
 - Requirement IDs mapped to acceptance scenarios
+- **Traceability matrix** (REQ → Acceptance → Spec section)
 - Risk notes and open questions
 - Success criteria summary
+- **Implementation Surface** (from SCOPE: files created/modified, shared types, tokens, routes, components)
+- **Contract dependencies** (from CONTRACTS.md if it exists: types/components this spec consumes from others)
 
 ## Principles
 - **WHAT, not HOW**: Define outcomes, not implementation

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

@@ -1,25 +1,57 @@
 # Scope
 
-## In scope (v1 outcomes)
-1. {{IN_SCOPE_1}}
-2. {{IN_SCOPE_2}}
+## In Scope (v1 Outcomes)
+
+Requirements use stable IDs: `REQ-{SPEC_ID}-{PRIORITY}-{SEQ}`
+
+### P0 — Must Have
+
+- **REQ-{{SPEC_ID}}-P0-01:** {{P0_ITEM_1}}
+- **REQ-{{SPEC_ID}}-P0-02:** {{P0_ITEM_2}}
+
+### P1 — Should Have
+
+- **REQ-{{SPEC_ID}}-P1-01:** {{P1_ITEM_1}}
+
+### P2 — Nice to Have
+
+- **REQ-{{SPEC_ID}}-P2-01:** {{P2_ITEM_1}}
+
+## Out of Scope
 
-## Out of scope
 - {{OUT_SCOPE_1}}
 - {{OUT_SCOPE_2}}
 
 ## Dependencies
+
 - {{DEP_1}}
 
-## Rollout considerations
+## Rollout Considerations
 
 What matters for rollout (engineering determines approach):
 - Gradual exposure needed: {{GRADUAL_YN}}
 - Backout requirement: {{BACKOUT_NEED}}
 - Data migration scope: {{MIGRATION_SCOPE}}
 
-## Non-functional requirements
+## Non-Functional Requirements
+
 - Performance: {{PERF}}
 - Accessibility: {{A11Y}}
 - Security/privacy: {{SECURITY}}
 - Observability: {{OBS}}
+
+## Implementation Surface
+
+### Files Created (owned exclusively by this spec)
+- {{NEW_FILE_1}}
+
+### Files Modified (shared — coordinate with other specs)
+- {{MOD_FILE_1}}
+
+### Shared Surfaces
+- **Types consumed:** {{TYPES_THIS_SPEC_DEPENDS_ON}}
+- **Types created:** {{TYPES_THIS_SPEC_INTRODUCES}}
+- **Design tokens used:** {{TOKENS}}
+- **Routes added:** {{ROUTES}}
+- **Components consumed:** {{COMPONENTS_USED_FROM_ELSEWHERE}}
+- **Components created:** {{COMPONENTS_INTRODUCED}}

package/claude/get-shit-specd/workflows/contracts.md

@@ -0,0 +1,113 @@
+<purpose>
+Analyze multiple Ready specs to extract shared contracts and file ownership for parallel development.
+Produces .planning/CONTRACTS.md consumed by handoff and agent dispatch.
+
+This workflow prevents merge conflicts, duplicated types, and integration failures when multiple features are developed in parallel.
+</purpose>
+
+<process>
+
+<step name="discover_specs">
+Read .planning/specs/ directory.
+For each spec folder, read STATE.md and filter to status: Ready or Handed Off.
+
+If 0-1 qualifying specs:
+  - Output: "Contracts extraction requires 2+ Ready specs. Skipping."
+  - Exit gracefully (this is not an error).
+</step>
+
+<step name="extract_surfaces">
+For each qualifying spec, read 01-SCOPE.md.
+Extract the Implementation Surface section into structured data:
+
+```
+{
+  "spec_id": "SPEC-001",
+  "files_created": ["app/components/hero.tsx", ...],
+  "files_modified": ["app/root.tsx", "app/app.css", ...],
+  "types_consumed": ["Deck", "Card"],
+  "types_created": ["HeroProps"],
+  "tokens_used": ["brand-gold", "surface-primary"],
+  "routes_added": ["/deck/:id"],
+  "components_consumed": ["Footer", "Layout"],
+  "components_created": ["Hero", "CardGrid"]
+}
+```
+
+If a spec has no Implementation Surface, record a warning but continue.
+</step>
+
+<step name="detect_overlaps">
+Compare all extracted surfaces:
+
+**File conflicts:**
+- Two specs creating the same file → CONFLICT (must resolve before dispatch)
+- Two specs modifying the same file → SHARED (needs coordination, not blocking)
+
+**Type conflicts:**
+- Same type name created by two specs → CONFLICT
+- Same type consumed and created → dependency (note direction)
+
+**Route conflicts:**
+- Overlapping route patterns → CONFLICT
+
+**Token gaps:**
+- Token referenced but not in codebase → NEW (flag for creation)
+</step>
+
+<step name="build_ownership_matrix">
+For each file across all specs:
+
+| File | Owner Spec | Also Modified By | Action |
+|------|-----------|-----------------|--------|
+| app/components/hero.tsx | SPEC-001 | — | Exclusive |
+| app/root.tsx | — | SPEC-001, SPEC-002 | Coordinate |
+
+Rules:
+- Created files have exactly one owner
+- Modified files list all specs that touch them
+- Conflicts require resolution before dispatch
+</step>
+
+<step name="generate_type_contracts">
+For shared types (consumed by one spec, created by another):
+- Define the interface with field names and types
+- Note which spec owns the definition
+- Note which specs depend on it
+
+These become the "API boundary" between parallel work streams.
+</step>
+
+<step name="generate_component_contracts">
+For shared components (created by one spec, consumed by another):
+- Define the props interface
+- Note the owner spec
+- Note consumer specs
+
+This ensures component APIs are agreed upon before parallel coding starts.
+</step>
+
+<step name="write_contracts_md">
+Write .planning/CONTRACTS.md using the contracts template.
+
+Sections:
+1. Type Contracts
+2. Token Contracts
+3. Route Contracts
+4. Component API Contracts
+5. File Ownership Matrix
+6. Conflict Warnings
+
+If .planning/CONTRACTS.md already exists, rename to CONTRACTS.prev.md first.
+</step>
+
+<step name="summarize">
+Report:
+- Specs analyzed: {{count}}
+- Shared types: {{count}} ({{conflict_count}} conflicts)
+- Shared files: {{count}} modified by multiple specs
+- Routes: {{count}} total ({{conflict_count}} conflicts)
+- Blocking conflicts: {{count}} (must resolve before dispatch)
+</step>
+
+</process>

package/claude/get-shit-specd/workflows/create-spec.md

@@ -67,7 +67,21 @@ Record unknowns as assumptions + open questions.
 <step name="write_brief_and_scope">
 Main flow writes:
 - 00-BRIEF.md (problem, JTBD, goal, constraints, risks)
-- 01-SCOPE.md (in/out with priorities, dependencies, NFRs)
+- 01-SCOPE.md (in/out with priorities, dependencies, NFRs, Implementation Surface)
+
+**Requirement ID Convention:**
+Generate stable IDs at spec time using format: `REQ-{SPEC_ID}-{PRIORITY}-{SEQ}`
+- Example: REQ-001-P0-01, REQ-001-P1-02
+- IDs remain stable across spec revisions
+- Enables traceability from spec → handoff → implementation
+
+**Implementation Surface:**
+After writing in-scope items, fill the Implementation Surface section:
+- Identify likely files to create (new components, routes, utilities)
+- Identify files to modify (existing layouts, route config, shared types)
+- List shared surfaces: types consumed/created, tokens, routes, components
+- If exact file paths are unknown, infer from feature description and project structure
+- Mark unknowns as "TBD" — the /gss:contracts step refines these later
 
 These require intake context, so main flow handles them.
 </step>

package/claude/get-shit-specd/workflows/handoff.md

@@ -14,10 +14,26 @@ Read:
 </step>
 
 <step name="map_requirements">
-Create requirement IDs, each mapped to one or more acceptance scenarios.
+Use requirement IDs from SCOPE (REQ-{SPEC_ID}-{PRIORITY}-{SEQ}).
+Map each requirement to its acceptance scenarios from 04-ACCEPTANCE.md.
 Requirements describe OUTCOMES, not tasks.
 </step>
 
+<step name="generate_traceability_matrix">
+Create a traceability matrix linking:
+- Requirement ID → Acceptance scenario numbers → Spec source file:section
+
+Example format:
+| REQ ID | Acceptance Scenarios | Source |
+|--------|---------------------|--------|
+| REQ-001-P0-01 | 1.1.1, 1.1.2, 1.1.3 | 01-SCOPE.md#email-signup |
+
+This enables:
+- Coverage verification (every REQ has acceptance criteria)
+- Change impact analysis (which acceptance scenarios if REQ changes)
+- Engineering trace-back to product intent
+</step>
+
 <step name="summarize_context">
 Extract from BRIEF:
 - Problem statement (why this matters)
@@ -32,12 +48,28 @@ List:
 - Dependencies on other work
 </step>
 
+<step name="surface_implementation">
+Extract from 01-SCOPE.md Implementation Surface section:
+- Files created (exclusive ownership)
+- Files modified (shared)
+- Shared surfaces (types, tokens, routes, components)
+
+If .planning/CONTRACTS.md exists:
+- Read contracts relevant to this spec
+- List contract dependencies (types/components this spec consumes from others)
+- List contracts this spec provides to others
+- Include suggested branch name and dispatch order from CONTRACTS.md
+</step>
+
 <step name="write_handoff">
 Write HANDOFF.md with:
 - Requirements mapped to acceptance scenarios
 - Problem context and success criteria
 - Risks and open questions
-- NO engineering tasks, phases, or file paths
+- Implementation Surface (files, types, tokens, routes, components)
+- Contract dependencies (if CONTRACTS.md exists)
+- Dispatch section: suggested branch name, owned files, contract dependencies
+- NO engineering tasks, phases, or technical approach decisions
 </step>
 
 </process>

package/claude/get-shit-specd/workflows/review-spec.md

@@ -17,6 +17,8 @@ Find:
 - acceptance that cannot be objectively verified
 - data/UX mismatches
 - analytics gaps
+- missing Implementation Surface (no files created/modified listed)
+- file ownership conflicts with other specs in .planning/specs/ (check their Implementation Surfaces)
 </step>
 
 <step name="patch_or_questions">

package/examples/SPEC-003-watermarking-service/01-SCOPE.md

@@ -44,3 +44,23 @@
 | Security | Clean URLs require purchase validation; long-lived (24h+) after purchase — customers "own" their images |
 | Accessibility | Watermark text not conveyed to screen readers (decorative) |
 | Observability | Success/failure rates visible, alert on >5% failure rate |
+
+## Implementation Surface
+
+### Files Created (owned exclusively by this spec)
+- lib/watermark.ts
+- lib/storage/dual-store.ts
+- functions/inngest/watermark-step.ts
+
+### Files Modified (shared — coordinate with other specs)
+- functions/inngest/face-swap.ts
+- lib/storage/r2.ts
+- app/api/cards/[id]/route.ts
+
+### Shared Surfaces
+- **Types consumed:** Card, Deck, R2Object
+- **Types created:** WatermarkConfig, DualStoreResult
+- **Design tokens used:** None (backend service)
+- **Routes added:** None (modifies existing card route)
+- **Components consumed:** None (backend service)
+- **Components created:** None (backend service)

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "get-shit-specd",
-  "version": "0.2.0",
+  "version": "0.4.1",
   "description": "Spec-first development workflow for Claude Code. Transform vague ideas into engineering-ready specs.",
   "type": "module",
   "bin": {
-    "gss": "./bin/gss.ts",
-    "get-shit-specd": "./bin/gss.ts"
+    "gss": "./bin/gss",
+    "get-shit-specd": "./bin/gss"
   },
   "scripts": {
     "typecheck": "bun --bun tsc --noEmit"