@bhargavvc/sdd-cc 1.35.0 → 1.42.4

package/sdk/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@bhargavvc/sdk",
+  "version": "1.42.3",
+  "description": "SDD SDK — programmatic interface for running SDD plans via the Agent SDK",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "sdd-sdk": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "shared",
+    "prompts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bhargavvc/sdd-cc.git",
+    "directory": "sdk"
+  },
+  "homepage": "https://github.com/bhargavvc/sdd-cc/tree/main/sdk",
+  "bugs": {
+    "url": "https://github.com/bhargavvc/sdd-cc/issues"
+  },
+  "author": "TÂCHES",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "check:alias-drift": "npm run build && node scripts/check-command-aliases-fresh.mjs",
+    "gen:state-document": "npm run build && npx tsx scripts/gen-state-document.ts",
+    "check:state-document-fresh": "npm run build && node scripts/check-state-document-fresh.mjs",
+    "prepublishOnly": "rm -rf dist && tsc && chmod +x dist/cli.js",
+    "test": "vitest run",
+    "test:unit": "vitest run --project unit",
+    "test:integration": "vitest run --project integration"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.84",
+    "ws": "^8.20.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.1",
+    "tsx": "^4.22.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.1.1"
+  }
+}

package/sdk/prompts/templates/project.md

@@ -0,0 +1,186 @@
+# PROJECT.md Template
+
+Template for `.planning/PROJECT.md` — the living project context document.
+
+<template>
+
+```markdown
+# [Project Name]
+
+## What This Is
+
+[Current accurate description — 2-3 sentences. What does this product do and who is it for?
+Use the user's language and framing. Update whenever reality drifts from this description.]
+
+## Core Value
+
+[The ONE thing that matters most. If everything else fails, this must work.
+One sentence that drives prioritization when tradeoffs arise.]
+
+## Requirements
+
+### Validated
+
+<!-- Shipped and confirmed valuable. -->
+
+(None yet — ship to validate)
+
+### Active
+
+<!-- Current scope. Building toward these. -->
+
+- [ ] [Requirement 1]
+- [ ] [Requirement 2]
+- [ ] [Requirement 3]
+
+### Out of Scope
+
+<!-- Explicit boundaries. Includes reasoning to prevent re-adding. -->
+
+- [Exclusion 1] — [why]
+- [Exclusion 2] — [why]
+
+## Context
+
+[Background information that informs implementation:
+- Technical environment or ecosystem
+- Relevant prior work or experience
+- User research or feedback themes
+- Known issues to address]
+
+## Constraints
+
+- **[Type]**: [What] — [Why]
+- **[Type]**: [What] — [Why]
+
+Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Performance, Security
+
+## Key Decisions
+
+<!-- Decisions that constrain future work. Add throughout project lifecycle. -->
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| [Choice] | [Why] | [✓ Good / ⚠️ Revisit / — Pending] |
+
+---
+*Last updated: [date] after [trigger]*
+```
+
+</template>
+
+<guidelines>
+
+**What This Is:**
+- Current accurate description of the product
+- 2-3 sentences capturing what it does and who it's for
+- Use the user's words and framing
+- Update when the product evolves beyond this description
+
+**Core Value:**
+- The single most important thing
+- Everything else can fail; this cannot
+- Drives prioritization when tradeoffs arise
+- Rarely changes; if it does, it's a significant pivot
+
+**Requirements — Validated:**
+- Requirements that shipped and proved valuable
+- Format: `- ✓ [Requirement] — [version/phase]`
+- These are locked — changing them requires explicit discussion
+
+**Requirements — Active:**
+- Current scope being built toward
+- These are hypotheses until shipped and validated
+- Move to Validated when shipped, Out of Scope if invalidated
+
+**Requirements — Out of Scope:**
+- Explicit boundaries on what we're not building
+- Always include reasoning (prevents re-adding later)
+- Includes: considered and rejected, deferred to future, explicitly excluded
+
+**Context:**
+- Background that informs implementation decisions
+- Technical environment, prior work, user feedback
+- Known issues or technical debt to address
+- Update as new context emerges
+
+**Constraints:**
+- Hard limits on implementation choices
+- Tech stack, timeline, budget, compatibility, dependencies
+- Include the "why" — constraints without rationale get questioned
+
+**Key Decisions:**
+- Significant choices that affect future work
+- Add decisions as they're made throughout the project
+- Track outcome when known:
+  - ✓ Good — decision proved correct
+  - ⚠️ Revisit — decision may need reconsideration
+  - — Pending — too early to evaluate
+
+**Last Updated:**
+- Always note when and why the document was updated
+- Format: `after Phase 2` or `after v1.0 milestone`
+- Triggers review of whether content is still accurate
+
+</guidelines>
+
+<evolution>
+
+PROJECT.md evolves throughout the project lifecycle.
+These rules are embedded in the generated PROJECT.md (## Evolution section)
+and implemented by transition and milestone-completion workflows.
+
+**After each phase transition:**
+1. Requirements invalidated? → Move to Out of Scope with reason
+2. Requirements validated? → Move to Validated with phase reference
+3. New requirements emerged? → Add to Active
+4. Decisions to log? → Add to Key Decisions
+5. "What This Is" still accurate? → Update if drifted
+
+**After each milestone:**
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state (users, feedback, metrics)
+
+</evolution>
+
+<brownfield>
+
+For existing codebases:
+
+1. **Map the codebase first** — analyze the project structure and existing code before defining requirements.
+
+2. **Infer Validated requirements** from existing code:
+   - What does the codebase actually do?
+   - What patterns are established?
+   - What's clearly working and relied upon?
+
+3. **Gather Active requirements** from user:
+   - Present inferred current state
+   - Ask what they want to build next
+
+4. **Initialize:**
+   - Validated = inferred from existing code
+   - Active = user's goals for this work
+   - Out of Scope = boundaries user specifies
+   - Context = includes current codebase state
+
+</brownfield>
+
+<state_reference>
+
+STATE.md references PROJECT.md:
+
+```markdown
+## Project Reference
+
+See: .planning/PROJECT.md (updated [date])
+
+**Core value:** [One-liner from Core Value section]
+**Current focus:** [Current phase name]
+```
+
+This ensures Claude reads current PROJECT.md context.
+
+</state_reference>

package/sdk/prompts/templates/requirements.md

@@ -0,0 +1,231 @@
+# Requirements Template
+
+Template for `.planning/REQUIREMENTS.md` — checkable requirements that define "done."
+
+<template>
+
+```markdown
+# Requirements: [Project Name]
+
+**Defined:** [date]
+**Core Value:** [from PROJECT.md]
+
+## v1 Requirements
+
+Requirements for initial release. Each maps to roadmap phases.
+
+### Authentication
+
+- [ ] **AUTH-01**: User can sign up with email and password
+- [ ] **AUTH-02**: User receives email verification after signup
+- [ ] **AUTH-03**: User can reset password via email link
+- [ ] **AUTH-04**: User session persists across browser refresh
+
+### [Category 2]
+
+- [ ] **[CAT]-01**: [Requirement description]
+- [ ] **[CAT]-02**: [Requirement description]
+- [ ] **[CAT]-03**: [Requirement description]
+
+### [Category 3]
+
+- [ ] **[CAT]-01**: [Requirement description]
+- [ ] **[CAT]-02**: [Requirement description]
+
+## v2 Requirements
+
+Deferred to future release. Tracked but not in current roadmap.
+
+### [Category]
+
+- **[CAT]-01**: [Requirement description]
+- **[CAT]-02**: [Requirement description]
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent scope creep.
+
+| Feature | Reason |
+|---------|--------|
+| [Feature] | [Why excluded] |
+| [Feature] | [Why excluded] |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| AUTH-01 | Phase 1 | Pending |
+| AUTH-02 | Phase 1 | Pending |
+| AUTH-03 | Phase 1 | Pending |
+| AUTH-04 | Phase 1 | Pending |
+| [REQ-ID] | Phase [N] | Pending |
+
+**Coverage:**
+- v1 requirements: [X] total
+- Mapped to phases: [Y]
+- Unmapped: [Z] ⚠️
+
+---
+*Requirements defined: [date]*
+*Last updated: [date] after [trigger]*
+```
+
+</template>
+
+<guidelines>
+
+**Requirement Format:**
+- ID: `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02, SOCIAL-03)
+- Description: User-centric, testable, atomic
+- Checkbox: Only for v1 requirements (v2 are not yet actionable)
+
+**Categories:**
+- Derive from research FEATURES.md categories
+- Keep consistent with domain conventions
+- Typical: Authentication, Content, Social, Notifications, Moderation, Payments, Admin
+
+**v1 vs v2:**
+- v1: Committed scope, will be in roadmap phases
+- v2: Acknowledged but deferred, not in current roadmap
+- Moving v2 → v1 requires roadmap update
+
+**Out of Scope:**
+- Explicit exclusions with reasoning
+- Prevents "why didn't you include X?" later
+- Anti-features from research belong here with warnings
+
+**Traceability:**
+- Empty initially, populated during roadmap creation
+- Each requirement maps to exactly one phase
+- Unmapped requirements = roadmap gap
+
+**Status Values:**
+- Pending: Not started
+- In Progress: Phase is active
+- Complete: Requirement verified
+- Blocked: Waiting on external factor
+
+</guidelines>
+
+<evolution>
+
+**After each phase completes:**
+1. Mark covered requirements as Complete
+2. Update traceability status
+3. Note any requirements that changed scope
+
+**After roadmap updates:**
+1. Verify all v1 requirements still mapped
+2. Add new requirements if scope expanded
+3. Move requirements to v2/out of scope if descoped
+
+**Requirement completion criteria:**
+- Requirement is "Complete" when:
+  - Feature is implemented
+  - Feature is verified (tests pass, manual check done)
+  - Feature is committed
+
+</evolution>
+
+<example>
+
+```markdown
+# Requirements: CommunityApp
+
+**Defined:** 2025-01-14
+**Core Value:** Users can share and discuss content with people who share their interests
+
+## v1 Requirements
+
+### Authentication
+
+- [ ] **AUTH-01**: User can sign up with email and password
+- [ ] **AUTH-02**: User receives email verification after signup
+- [ ] **AUTH-03**: User can reset password via email link
+- [ ] **AUTH-04**: User session persists across browser refresh
+
+### Profiles
+
+- [ ] **PROF-01**: User can create profile with display name
+- [ ] **PROF-02**: User can upload avatar image
+- [ ] **PROF-03**: User can write bio (max 500 chars)
+- [ ] **PROF-04**: User can view other users' profiles
+
+### Content
+
+- [ ] **CONT-01**: User can create text post
+- [ ] **CONT-02**: User can upload image with post
+- [ ] **CONT-03**: User can edit own posts
+- [ ] **CONT-04**: User can delete own posts
+- [ ] **CONT-05**: User can view feed of posts
+
+### Social
+
+- [ ] **SOCL-01**: User can follow other users
+- [ ] **SOCL-02**: User can unfollow users
+- [ ] **SOCL-03**: User can like posts
+- [ ] **SOCL-04**: User can comment on posts
+- [ ] **SOCL-05**: User can view activity feed (followed users' posts)
+
+## v2 Requirements
+
+### Notifications
+
+- **NOTF-01**: User receives in-app notifications
+- **NOTF-02**: User receives email for new followers
+- **NOTF-03**: User receives email for comments on own posts
+- **NOTF-04**: User can configure notification preferences
+
+### Moderation
+
+- **MODR-01**: User can report content
+- **MODR-02**: User can block other users
+- **MODR-03**: Admin can view reported content
+- **MODR-04**: Admin can remove content
+- **MODR-05**: Admin can ban users
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Real-time chat | High complexity, not core to community value |
+| Video posts | Storage/bandwidth costs, defer to v2+ |
+| OAuth login | Email/password sufficient for v1 |
+| Mobile app | Web-first, mobile later |
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| AUTH-01 | Phase 1 | Pending |
+| AUTH-02 | Phase 1 | Pending |
+| AUTH-03 | Phase 1 | Pending |
+| AUTH-04 | Phase 1 | Pending |
+| PROF-01 | Phase 2 | Pending |
+| PROF-02 | Phase 2 | Pending |
+| PROF-03 | Phase 2 | Pending |
+| PROF-04 | Phase 2 | Pending |
+| CONT-01 | Phase 3 | Pending |
+| CONT-02 | Phase 3 | Pending |
+| CONT-03 | Phase 3 | Pending |
+| CONT-04 | Phase 3 | Pending |
+| CONT-05 | Phase 3 | Pending |
+| SOCL-01 | Phase 4 | Pending |
+| SOCL-02 | Phase 4 | Pending |
+| SOCL-03 | Phase 4 | Pending |
+| SOCL-04 | Phase 4 | Pending |
+| SOCL-05 | Phase 4 | Pending |
+
+**Coverage:**
+- v1 requirements: 18 total
+- Mapped to phases: 18
+- Unmapped: 0 ✓
+
+---
+*Requirements defined: 2025-01-14*
+*Last updated: 2025-01-14 after initial definition*
+```
+
+</example>

package/sdk/prompts/templates/research-project/ARCHITECTURE.md

@@ -0,0 +1,204 @@
+# Architecture Research Template
+
+Template for `.planning/research/ARCHITECTURE.md` — system structure patterns for the project domain.
+
+<template>
+
+```markdown
+# Architecture Research
+
+**Domain:** [domain type]
+**Researched:** [date]
+**Confidence:** [HIGH/MEDIUM/LOW]
+
+## Standard Architecture
+
+### System Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        [Layer Name]                          │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
+│  │ [Comp]  │  │ [Comp]  │  │ [Comp]  │  │ [Comp]  │        │
+│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │
+│       │            │            │            │              │
+├───────┴────────────┴────────────┴────────────┴──────────────┤
+│                        [Layer Name]                          │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │                    [Component]                       │    │
+│  └─────────────────────────────────────────────────────┘    │
+├─────────────────────────────────────────────────────────────┤
+│                        [Layer Name]                          │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐                   │
+│  │ [Store]  │  │ [Store]  │  │ [Store]  │                   │
+│  └──────────┘  └──────────┘  └──────────┘                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Component Responsibilities
+
+| Component | Responsibility | Typical Implementation |
+|-----------|----------------|------------------------|
+| [name] | [what it owns] | [how it's usually built] |
+| [name] | [what it owns] | [how it's usually built] |
+| [name] | [what it owns] | [how it's usually built] |
+
+## Recommended Project Structure
+
+```
+src/
+├── [folder]/           # [purpose]
+│   ├── [subfolder]/    # [purpose]
+│   └── [file].ts       # [purpose]
+├── [folder]/           # [purpose]
+│   ├── [subfolder]/    # [purpose]
+│   └── [file].ts       # [purpose]
+├── [folder]/           # [purpose]
+└── [folder]/           # [purpose]
+```
+
+### Structure Rationale
+
+- **[folder]/:** [why organized this way]
+- **[folder]/:** [why organized this way]
+
+## Architectural Patterns
+
+### Pattern 1: [Pattern Name]
+
+**What:** [description]
+**When to use:** [conditions]
+**Trade-offs:** [pros and cons]
+
+**Example:**
+```typescript
+// [Brief code example showing the pattern]
+```
+
+### Pattern 2: [Pattern Name]
+
+**What:** [description]
+**When to use:** [conditions]
+**Trade-offs:** [pros and cons]
+
+**Example:**
+```typescript
+// [Brief code example showing the pattern]
+```
+
+### Pattern 3: [Pattern Name]
+
+**What:** [description]
+**When to use:** [conditions]
+**Trade-offs:** [pros and cons]
+
+## Data Flow
+
+### Request Flow
+
+```
+[User Action]
+    ↓
+[Component] → [Handler] → [Service] → [Data Store]
+    ↓              ↓           ↓            ↓
+[Response] ← [Transform] ← [Query] ← [Database]
+```
+
+### State Management
+
+```
+[State Store]
+    ↓ (subscribe)
+[Components] ←→ [Actions] → [Reducers/Mutations] → [State Store]
+```
+
+### Key Data Flows
+
+1. **[Flow name]:** [description of how data moves]
+2. **[Flow name]:** [description of how data moves]
+
+## Scaling Considerations
+
+| Scale | Architecture Adjustments |
+|-------|--------------------------|
+| 0-1k users | [approach — usually monolith is fine] |
+| 1k-100k users | [approach — what to optimize first] |
+| 100k+ users | [approach — when to consider splitting] |
+
+### Scaling Priorities
+
+1. **First bottleneck:** [what breaks first, how to fix]
+2. **Second bottleneck:** [what breaks next, how to fix]
+
+## Anti-Patterns
+
+### Anti-Pattern 1: [Name]
+
+**What people do:** [the mistake]
+**Why it's wrong:** [the problem it causes]
+**Do this instead:** [the correct approach]
+
+### Anti-Pattern 2: [Name]
+
+**What people do:** [the mistake]
+**Why it's wrong:** [the problem it causes]
+**Do this instead:** [the correct approach]
+
+## Integration Points
+
+### External Services
+
+| Service | Integration Pattern | Notes |
+|---------|---------------------|-------|
+| [service] | [how to connect] | [gotchas] |
+| [service] | [how to connect] | [gotchas] |
+
+### Internal Boundaries
+
+| Boundary | Communication | Notes |
+|----------|---------------|-------|
+| [module A ↔ module B] | [API/events/direct] | [considerations] |
+
+## Sources
+
+- [Architecture references]
+- [Official documentation]
+- [Case studies]
+
+---
+*Architecture research for: [domain]*
+*Researched: [date]*
+```
+
+</template>
+
+<guidelines>
+
+**System Overview:**
+- Use ASCII box-drawing diagrams for clarity (├── └── │ ─ for structure visualization only)
+- Show major components and their relationships
+- Don't over-detail — this is conceptual, not implementation
+
+**Project Structure:**
+- Be specific about folder organization
+- Explain the rationale for grouping
+- Match conventions of the chosen stack
+
+**Patterns:**
+- Include code examples where helpful
+- Explain trade-offs honestly
+- Note when patterns are overkill for small projects
+
+**Scaling Considerations:**
+- Be realistic — most projects don't need to scale to millions
+- Focus on "what breaks first" not theoretical limits
+- Avoid premature optimization recommendations
+
+**Anti-Patterns:**
+- Specific to this domain
+- Include what to do instead
+- Helps prevent common mistakes during implementation
+
+</guidelines>