@structured-vibe-coding/core 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 harsha09
+
+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,37 @@
+# `@structured-vibe-coding/core`
+
+Core engine for **Structured Vibe Coding** — local-first Spec-Driven Development.
+
+Used by:
+
+- `@structured-vibe-coding/cli` (`sdd` command)
+- VS Code / Cursor extension (`packages/vscode`)
+
+## Install
+
+```bash
+npm install @structured-vibe-coding/core
+```
+
+## Usage
+
+```ts
+import { initProject, createChange, advanceStage, loadConfig } from "@structured-vibe-coding/core";
+
+const root = process.cwd();
+await initProject({ projectRoot: root });
+const config = await loadConfig(root);
+const change = await createChange({
+  projectRoot: root,
+  config,
+  title: "Add feature X",
+  workflowName: "feature",
+});
+await advanceStage(root, config, change.id);
+```
+
+See the [repository README](https://github.com/structured-vibe-coding/spec-driven-development) for workflows, customization, and CLI docs.
+
+## License
+
+MIT

package/defaults/memory/architecture.md

@@ -0,0 +1,19 @@
+# Architecture
+
+<!-- High-level system shape for local development -->
+
+## Overview
+
+-
+
+## Key components
+
+-
+
+## Data stores
+
+-
+
+## Non-negotiables
+
+-

package/defaults/memory/conventions.md

@@ -0,0 +1,15 @@
+# Conventions
+
+## Code
+
+-
+
+## Specs & process
+
+- Spec-first for non-trivial work
+- Prefer the lightest workflow that fits the change
+- Local verify before `sdd complete`
+
+## Agent guidance
+
+-

package/defaults/memory/product.md

@@ -0,0 +1,15 @@
+# Product
+
+<!-- What are you building? Who is it for? -->
+
+## Vision
+
+-
+
+## Users
+
+-
+
+## Success metrics
+
+-

package/defaults/templates/acceptance.md

@@ -0,0 +1,14 @@
+# Acceptance
+
+> **{{title}}** · `{{id}}`
+
+## Cases
+
+| # | Scenario | Expected (local) |
+|---|----------|------------------|
+| 1 | | |
+| 2 | | |
+
+## Explicitly not testing
+
+-

package/defaults/templates/arb-decision.md

@@ -0,0 +1,21 @@
+# ARB decision
+
+> **{{title}}** · `{{id}}`
+
+## Decision
+
+- [ ] Approve
+- [ ] Approve with conditions
+- [ ] Reject
+
+## Conditions / constraints
+
+-
+
+## Rationale
+
+-
+
+## Date / attendees
+
+-

package/defaults/templates/arb-packet.md

@@ -0,0 +1,23 @@
+# ARB packet
+
+> **{{title}}** · `{{id}}`
+
+## Summary
+
+-
+
+## Decision needed
+
+-
+
+## Options & tradeoffs
+
+-
+
+## Security / privacy / cost notes
+
+-
+
+## Rollback / risk
+
+-

package/defaults/templates/code-research.md

@@ -0,0 +1,21 @@
+# Code research
+
+> **{{title}}** · `{{id}}`
+
+## Where to change
+
+| Area | Path / module | Notes |
+|------|---------------|-------|
+| | | |
+
+## What to add vs modify
+
+-
+
+## How (patterns to follow)
+
+-
+
+## Risks / gotchas
+
+-

package/defaults/templates/db-design.md

@@ -0,0 +1,23 @@
+# DB design
+
+> **{{title}}** · `{{id}}`
+
+## Schema changes
+
+-
+
+## Indexes
+
+-
+
+## Migrations / backfill
+
+-
+
+## Rollback
+
+-
+
+## Local how-to
+
+-

package/defaults/templates/design.md

@@ -0,0 +1,23 @@
+# Design
+
+> **{{title}}** · `{{id}}`
+
+## Approach
+
+-
+
+## Components / modules
+
+-
+
+## Data flow
+
+-
+
+## Alternatives considered
+
+-
+
+## Risks
+
+-

package/defaults/templates/feature.md

@@ -0,0 +1,27 @@
+# Feature
+
+> **{{title}}** · `{{id}}` · {{date}}
+
+## Problem / opportunity
+
+-
+
+## Users & value
+
+-
+
+## Scope
+
+-
+
+## Non-goals
+
+-
+
+## Success criteria
+
+-
+
+## Risks / open questions
+
+-

package/defaults/templates/hl-design.md

@@ -0,0 +1,29 @@
+# High-level design
+
+> **{{title}}** · `{{id}}`
+
+## Context
+
+-
+
+## Options
+
+### Option A
+
+-
+
+### Option B
+
+-
+
+## Recommendation
+
+-
+
+## Tradeoffs
+
+-
+
+## Impacted systems
+
+-

package/defaults/templates/intent.md

@@ -0,0 +1,19 @@
+# Intent
+
+> **{{title}}** · `{{id}}` · {{date}}
+
+## Problem
+
+-
+
+## Proposed change
+
+-
+
+## Out of scope
+
+-
+
+## Local success check
+
+-

package/defaults/templates/lld.md

@@ -0,0 +1,23 @@
+# Low-level design
+
+> **{{title}}** · `{{id}}`
+
+## Components & responsibilities
+
+-
+
+## Interfaces / contracts
+
+-
+
+## Sequences
+
+-
+
+## Error handling
+
+-
+
+## Testing notes (local)
+
+-

package/defaults/templates/local-test-plan.md

@@ -0,0 +1,19 @@
+# Local test plan
+
+> **{{title}}** · `{{id}}`
+
+## Environment
+
+- How to run locally:
+- Branch / flags / seed data:
+
+## Cases
+
+| # | Case | Steps | Expected |
+|---|------|-------|----------|
+| 1 | Happy path | | |
+| 2 | | | |
+
+## Out of scope this change
+
+-

package/defaults/templates/local-test-results.md

@@ -0,0 +1,20 @@
+# Local test results
+
+> **{{title}}** · `{{id}}`
+
+## Results
+
+| # | Result | Notes |
+|---|--------|-------|
+| 1 | PASS / FAIL | |
+
+## Commands run
+
+```
+# paste local commands
+```
+
+## Sign-off
+
+- Tested by:
+- Date:

package/defaults/templates/outcome.md

@@ -0,0 +1,17 @@
+# Spike outcome
+
+> **{{title}}** · `{{id}}`
+
+## What we learned
+
+-
+
+## Recommendation
+
+- [ ] Promote to feature change
+- [ ] Abandon
+- [ ] Needs more research
+
+## Next steps
+
+-

package/defaults/templates/stories.md

@@ -0,0 +1,20 @@
+# User stories
+
+> **{{title}}** · `{{id}}`
+
+## Stories
+
+### US-1: …
+
+As a …  
+I want …  
+So that …
+
+**Acceptance**
+
+- [ ]
+- [ ]
+
+### US-2: …
+
+-

package/defaults/templates/tasks.md

@@ -0,0 +1,15 @@
+# Tasks
+
+> **{{title}}** · `{{id}}`
+
+## Breakdown
+
+- [ ] Task 1
+- [ ] Task 2
+- [ ] Task 3
+
+## Traceability
+
+| Task | Story / design ref |
+|------|--------------------|
+| | |

package/defaults/workflows/enterprise-feature.yaml

@@ -0,0 +1,161 @@
+name: enterprise-feature
+description: >
+  Full team path — feature, HL ARB, LLD, DB design, code research,
+  stories, tasks, implement, local verify
+version: 1
+recommendation:
+  priority: 5
+  when:
+    keywords: [arb, architecture, migration, epic, platform]
+    min_complexity: high
+stages:
+  - id: feature
+    title: Feature definition
+    summary: Capture problem, users, scope, success criteria, non-goals
+    skippable: false
+    artifacts:
+      - id: feature
+        path: feature.md
+        template: feature.md
+        required: true
+    gate:
+      type: soft
+      checklist:
+        - "Scope clear enough for high-level design"
+
+  - id: hl_arb
+    title: High-level design + ARB
+    summary: Architecture options, tradeoffs, ARB packet and decision
+    skippable: false
+    artifacts:
+      - id: hl-design
+        path: hl-design.md
+        template: hl-design.md
+        required: true
+      - id: arb-packet
+        path: arb-packet.md
+        template: arb-packet.md
+        required: true
+      - id: arb-decision
+        path: arb-decision.md
+        template: arb-decision.md
+        required: true
+    gate:
+      type: hard
+      mode: human_approval
+      overridable: false
+      checklist:
+        - "ARB decision recorded (approve / approve-with-conditions / reject)"
+        - "Conditions (if any) captured as constraints"
+
+  - id: lld
+    title: Low-level design
+    summary: Component contracts, sequences, error paths, interfaces
+    skippable: true
+    artifacts:
+      - id: lld
+        path: lld.md
+        template: lld.md
+        required: true
+    gate:
+      type: soft
+
+  - id: db_design
+    title: DB design
+    summary: Schema deltas, indexes, migrations, backfill
+    skippable: true
+    skip_when:
+      flags: [no_db]
+    artifacts:
+      - id: db-design
+        path: db-design.md
+        template: db-design.md
+        required: true
+    gate:
+      type: soft
+
+  - id: code_research
+    title: Code research
+    summary: Where / what / how to change in this codebase
+    skippable: true
+    artifacts:
+      - id: research
+        path: research.md
+        template: code-research.md
+        required: true
+    gate:
+      type: soft
+
+  - id: stories
+    title: User stories
+    summary: Slice into user-visible stories with acceptance
+    skippable: true
+    artifacts:
+      - id: stories
+        path: stories.md
+        template: stories.md
+        required: true
+    gate:
+      type: soft
+
+  - id: tasks
+    title: Task breakdown
+    summary: Implementable tasks traced to stories
+    skippable: true
+    artifacts:
+      - id: tasks
+        path: tasks.md
+        template: tasks.md
+        required: true
+    gate:
+      type: soft
+
+  - id: implement
+    title: Implementation
+    summary: Execute tasks; respect ARB conditions
+    skippable: false
+    artifacts:
+      - id: evidence
+        path: evidence/
+        required: false
+    gate:
+      type: soft
+      checklist:
+        - "Open tasks done or deferred with reason"
+        - "ARB conditions satisfied or waived in arb-decision.md"
+    agent_context:
+      instructions: |
+        Implement only open tasks in tasks.md.
+        Do not violate constraints in arb-decision.md.
+        Prefer patterns listed in research.md.
+
+  - id: local_verify
+    title: Local verification
+    summary: Run and verify the feature on the developer machine
+    skippable: true
+    artifacts:
+      - id: local-test-plan
+        path: local-test-plan.md
+        template: local-test-plan.md
+        required: true
+      - id: local-test-results
+        path: local-test-results.md
+        template: local-test-results.md
+        required: true
+      - id: evidence
+        path: evidence/local/
+        required: false
+    gate:
+      type: hard
+      overridable: true
+      checklist:
+        - "Happy path verified locally"
+        - "Critical edge cases from stories covered or waived"
+        - "Failures fixed or filed before complete"
+    verify:
+      commands: []
+      evidence_dir: evidence/local
+
+on_complete:
+  archive: true
+  domain_sync: recommend

package/defaults/workflows/feature.yaml

@@ -0,0 +1,82 @@
+name: feature
+description: Standard feature — intent, design, tasks, implement, local verify
+version: 1
+recommendation:
+  priority: 30
+  when:
+    keywords: [feature, add, build, support]
+    min_complexity: medium
+stages:
+  - id: intent
+    title: Feature intent
+    summary: Problem, users, scope, non-goals, success
+    skippable: false
+    artifacts:
+      - id: feature
+        path: feature.md
+        template: feature.md
+        required: true
+    gate:
+      type: soft
+      checklist:
+        - "Scope and non-goals are explicit"
+  - id: design
+    title: Design
+    summary: Approach, components, risks (keep short)
+    skippable: true
+    artifacts:
+      - id: design
+        path: design.md
+        template: design.md
+        required: true
+    gate:
+      type: soft
+  - id: tasks
+    title: Tasks
+    summary: Break work into implementable tasks
+    skippable: true
+    artifacts:
+      - id: tasks
+        path: tasks.md
+        template: tasks.md
+        required: true
+    gate:
+      type: soft
+  - id: implement
+    title: Implement
+    summary: Build the feature locally
+    skippable: false
+    artifacts: []
+    gate:
+      type: soft
+    agent_context:
+      instructions: |
+        Implement tasks from tasks.md following design.md and feature.md.
+        Prefer incremental, testable steps.
+  - id: local_verify
+    title: Local verify
+    summary: Verify the feature on this machine
+    skippable: true
+    artifacts:
+      - id: local-test-plan
+        path: local-test-plan.md
+        template: local-test-plan.md
+        required: true
+      - id: local-test-results
+        path: local-test-results.md
+        template: local-test-results.md
+        required: true
+      - id: evidence
+        path: evidence/local/
+        required: false
+    gate:
+      type: soft
+      checklist:
+        - "Happy path verified locally"
+        - "Key edge cases covered or waived with notes"
+    verify:
+      commands: []
+      evidence_dir: evidence/local
+on_complete:
+  archive: true
+  domain_sync: recommend