@structured-vibe-coding/core 0.12.1 → 0.13.0

package/README.md

@@ -13,6 +13,7 @@ npm install @structured-vibe-coding/core
 ## Docs
 
 - [First change tutorial](https://github.com/harsha09/spec-driven-development/blob/main/docs/tutorials/first-change.md)
+- [Greenfield](https://github.com/harsha09/spec-driven-development/blob/main/docs/guides/greenfield.md)
 - [Docs site](https://harsha09.github.io/spec-driven-development/)
 - [Repository](https://github.com/harsha09/spec-driven-development)
 

package/defaults/memory/index.md

@@ -14,10 +14,13 @@ Parent page for **stable** project docs. Humans and coding agents: start here, t
 | Topic | File |
 |-------|------|
 | Product / vision | [product.md](product.md) |
+| Requirements | [requirements.md](requirements.md) (after greenfield) |
+| Feature backlog | [features.md](features.md) (after greenfield; `sdd feature start F-001`) |
 | Constitution (non-negotiables) | [constitution.md](constitution.md) |
 | Architecture | [architecture.md](architecture.md) |
 | Coding & process conventions | [conventions.md](conventions.md) |
 
+**Greenfield:** `sdd greenfield "one-line idea"` then promote into memory on complete.  
 Add rows here when you introduce new durable docs (e.g. `security.md`, `ops.md`).
 
 ## Active work

package/defaults/templates/features.md

@@ -0,0 +1,42 @@
+# Feature backlog
+
+> **{{title}}** · `{{id}}`  
+> Each feature should fit **one PR**. Start implementation with:  
+> `sdd feature start F-001`
+
+## How to write a feature
+
+Copy the block below for each item. Keep **Status** as `planned` until started.
+
+---
+
+## F-001: <short name>
+
+- **Status:** planned
+- **Priority:** must
+- **Workflow:** feature
+- **Summary:** One or two sentences of user-visible outcome.
+- **Requirements:** R-001
+- **Notes:**
+
+---
+
+## F-002: <short name>
+
+- **Status:** planned
+- **Priority:** must
+- **Workflow:** feature
+- **Summary:**
+- **Requirements:**
+- **Notes:**
+
+---
+
+## F-003: <short name>
+
+- **Status:** planned
+- **Priority:** should
+- **Workflow:** feature
+- **Summary:**
+- **Requirements:**
+- **Notes:**

package/defaults/templates/greenfield-architecture.md

@@ -0,0 +1,39 @@
+# High-level architecture
+
+> **{{title}}** · `{{id}}`  
+> MVP only — postpone scale fantasies.
+
+## Context
+
+What system are we building and what does it touch?
+
+-
+
+## Major components
+
+| Component | Responsibility |
+|-----------|----------------|
+| | |
+
+## Data
+
+-
+
+## Key flows
+
+1.
+2.
+
+## Tech choices (provisional)
+
+-
+
+## Risks & mitigations
+
+| Risk | Mitigation |
+|------|------------|
+| | |
+
+## Open questions
+
+1.

package/defaults/templates/requirements.md

@@ -0,0 +1,29 @@
+# Requirements
+
+> **{{title}}** · `{{id}}`  
+> Prefer testable statements. Avoid UI pixel detail unless critical.
+
+## Must have
+
+| ID | Requirement | Acceptance signal |
+|----|-------------|-------------------|
+| R-001 | | |
+| R-002 | | |
+
+## Should have
+
+| ID | Requirement | Acceptance signal |
+|----|-------------|-------------------|
+| R-010 | | |
+
+## Nice to have (later)
+
+-
+
+## Assumptions
+
+-
+
+## Risks
+
+-

package/defaults/templates/vision.md

@@ -0,0 +1,34 @@
+# Product vision
+
+> **{{title}}** · `{{id}}` · {{date}}  
+> Greenfield — keep the **smallest useful product**.
+
+## One-liner
+
+{{idea}}
+
+## Who is this for?
+
+-
+
+## Problem
+
+-
+
+## MVP success (how we know it worked)
+
+-
+
+## Non-goals (explicitly out of v1)
+
+-
+
+## Constraints
+
+- Time box:
+- Platforms:
+- Compliance / privacy:
+
+## Open questions
+
+1.

package/defaults/workflows/greenfield.yaml

@@ -0,0 +1,92 @@
+name: greenfield
+description: >
+  New product from a one-line idea — vision, requirements, feature backlog,
+  high-level architecture (then implement features as separate changes)
+version: 1
+recommendation:
+  priority: 40
+  when:
+    keywords: [greenfield, product, mvp, startup, new app, from scratch, build an app]
+    min_complexity: medium
+stages:
+  - id: vision
+    title: Product vision
+    summary: Who, problem, MVP success, non-goals — keep the smallest useful product
+    skippable: false
+    artifacts:
+      - id: vision
+        path: vision.md
+        template: vision.md
+        required: true
+    gate:
+      type: soft
+      checklist:
+        - "Users and problem are explicit"
+        - "MVP success is testable"
+        - "Non-goals limit scope"
+    agent_context:
+      instructions: |
+        GREENFIELD vision stage. Expand the one-line idea into a concrete MVP vision.
+        Prefer the smallest useful product. Do not invent enterprise scope.
+        Write only vision.md. Do not implement code yet.
+
+  - id: requirements
+    title: Requirements
+    summary: Testable product requirements derived from vision
+    skippable: false
+    artifacts:
+      - id: requirements
+        path: requirements.md
+        template: requirements.md
+        required: true
+    gate:
+      type: soft
+      checklist:
+        - "Requirements are testable (not vague wishes)"
+    agent_context:
+      instructions: |
+        Write testable requirements (shall/should). Link each to user value.
+        Avoid solution detail that belongs in architecture. Update requirements.md only.
+
+  - id: features
+    title: Feature backlog
+    summary: PR-sized features with ids F-001… for later sdd feature start
+    skippable: false
+    artifacts:
+      - id: features
+        path: features.md
+        template: features.md
+        required: true
+    gate:
+      type: soft
+      checklist:
+        - "Features are small enough for one PR each"
+        - "Each feature has id F-NNN and status planned"
+    agent_context:
+      instructions: |
+        Slice the MVP into PR-sized features. Use ids F-001, F-002, … exactly as in the template.
+        Status must be `planned` until implemented. Prefer must-have first. No code yet.
+
+  - id: architecture
+    title: High-level architecture
+    summary: System shape, major components, data, risks for the MVP
+    skippable: false
+    artifacts:
+      - id: architecture
+        path: architecture.md
+        template: greenfield-architecture.md
+        required: true
+    gate:
+      type: soft
+      checklist:
+        - "Major components and boundaries are clear"
+        - "Risks and open questions listed"
+    agent_context:
+      instructions: |
+        Propose a simple MVP architecture. Avoid over-engineering.
+        Align with requirements and features. Write architecture.md only.
+        When the human runs sdd complete, files promote into memory/ for the product.
+
+on_complete:
+  archive: false
+  domain_sync: never

package/dist/{agents-R4RMNXOS.js → agents-WL3PNTJL.js}

@@ -19,8 +19,11 @@ import {
   removeOtherAgentHosts,
   renderThinAgent,
   writeAgentHandoff
-} from "./chunk-24S2YWWL.js";
-import "./chunk-KZHNYGD6.js";
+} from "./chunk-S7SHVKG4.js";
+import "./chunk-OJFMJHNL.js";
+import "./chunk-C725DWSB.js";
+import "./chunk-A752UVPF.js";
+import "./chunk-67AUAGNV.js";
 import "./chunk-7MJYPJMR.js";
 import "./chunk-EPFURATC.js";
 export {

package/dist/change-context-W4HDO2IK.js

@@ -0,0 +1,23 @@
+import {
+  buildContext,
+  clearActiveIf,
+  getActiveChangeId,
+  listChanges,
+  loadChangeMeta,
+  resolveChangeId,
+  saveChangeMeta,
+  setActiveChange
+} from "./chunk-A752UVPF.js";
+import "./chunk-67AUAGNV.js";
+import "./chunk-7MJYPJMR.js";
+import "./chunk-EPFURATC.js";
+export {
+  buildContext,
+  clearActiveIf,
+  getActiveChangeId,
+  listChanges,
+  loadChangeMeta,
+  resolveChangeId,
+  saveChangeMeta,
+  setActiveChange
+};

package/dist/{chunk-KZHNYGD6.js → chunk-67AUAGNV.js}

@@ -1,14 +1,3 @@
-import {
-  configPath,
-  sddRoot
-} from "./chunk-7MJYPJMR.js";
-import {
-  ensureDir,
-  pathExists,
-  readYaml,
-  writeYaml
-} from "./chunk-EPFURATC.js";
-
 // src/schemas.ts
 import { z } from "zod";
 var GateSchema = z.object({
@@ -150,28 +139,6 @@ var ChangeMetaSchema = z.object({
   completed_at: z.string().optional()
 });
 
-// src/config.ts
-async function isInitialized(projectRoot) {
-  return pathExists(configPath(projectRoot));
-}
-async function loadConfig(projectRoot) {
-  const path = configPath(projectRoot);
-  if (!await pathExists(path)) {
-    throw new Error(
-      `SDD is not initialized in ${projectRoot}. Run \`sdd init\` first.`
-    );
-  }
-  const raw = await readYaml(path);
-  return ConfigSchema.parse(raw);
-}
-async function saveConfig(projectRoot, config) {
-  await ensureDir(sddRoot(projectRoot));
-  await writeYaml(configPath(projectRoot), ConfigSchema.parse(config));
-}
-function defaultConfig() {
-  return ConfigSchema.parse({});
-}
-
 export {
   GateSchema,
   ArtifactDefSchema,
@@ -179,9 +146,5 @@ export {
   StageSchema,
   WorkflowSchema,
   ConfigSchema,
-  ChangeMetaSchema,
-  isInitialized,
-  loadConfig,
-  saveConfig,
-  defaultConfig
+  ChangeMetaSchema
 };

package/dist/chunk-A752UVPF.js

@@ -0,0 +1,317 @@
+import {
+  ChangeMetaSchema,
+  WorkflowSchema
+} from "./chunk-67AUAGNV.js";
+import {
+  activePointerPath,
+  changeMetaPath,
+  changePath,
+  changesDir,
+  workflowsDir
+} from "./chunk-7MJYPJMR.js";
+import {
+  ensureDir,
+  listDirs,
+  listFiles,
+  pathExists,
+  readText,
+  readYaml,
+  writeText,
+  writeYaml
+} from "./chunk-EPFURATC.js";
+
+// src/slug.ts
+function slugify(input) {
+  return input.toLowerCase().trim().replace(/['"]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60).replace(/-+$/g, "");
+}
+function todayIsoDate(d = /* @__PURE__ */ new Date()) {
+  return d.toISOString().slice(0, 10);
+}
+function nowIso(d = /* @__PURE__ */ new Date()) {
+  return d.toISOString();
+}
+function changeDirName(title, d = /* @__PURE__ */ new Date()) {
+  const slug = slugify(title) || "change";
+  return `${todayIsoDate(d)}-${slug}`;
+}
+function uniqueChangeDirName(base, taken) {
+  if (!taken.has(base)) return base;
+  let n = 2;
+  while (taken.has(`${base}-${n}`)) n += 1;
+  return `${base}-${n}`;
+}
+
+// src/workflow.ts
+import { join } from "pathe";
+async function listWorkflowNames(projectRoot) {
+  const dir = workflowsDir(projectRoot);
+  const files = await listFiles(dir);
+  return files.filter((f) => f.endsWith(".yaml") || f.endsWith(".yml")).map((f) => f.replace(/\.ya?ml$/, "")).sort();
+}
+async function loadWorkflow(projectRoot, name) {
+  const dir = workflowsDir(projectRoot);
+  const candidates = [`${name}.yaml`, `${name}.yml`];
+  for (const file of candidates) {
+    const path = join(dir, file);
+    if (await pathExists(path)) {
+      const raw = await readYaml(path);
+      const workflow = WorkflowSchema.parse(raw);
+      if (workflow.name !== name) {
+      }
+      return workflow;
+    }
+  }
+  throw new Error(
+    `Workflow "${name}" not found in ${dir}. Available: ${(await listWorkflowNames(projectRoot)).join(", ") || "(none)"}`
+  );
+}
+function resolveStages(workflow, meta) {
+  const base = [...workflow.stages];
+  const extra = meta.overrides?.extra_stages ?? [];
+  const stages = [...base, ...extra];
+  return stages.map((stage) => {
+    const gateOverride = meta.overrides?.gates?.[stage.id];
+    if (!gateOverride) return stage;
+    return {
+      ...stage,
+      gate: {
+        ...stage.gate,
+        type: gateOverride
+      }
+    };
+  });
+}
+function isStageSkipped(meta, stageId) {
+  if (meta.overrides?.skip_stages?.includes(stageId)) return true;
+  if (meta.skipped?.some((s) => s.stage === stageId)) return true;
+  return false;
+}
+function shouldAutoSkip(stage, meta) {
+  const flags = stage.skip_when?.flags ?? [];
+  for (const flag of flags) {
+    if (meta.flags?.[flag] === true || meta.flags?.[flag] === "true") {
+      return true;
+    }
+  }
+  return false;
+}
+function activeStages(workflow, meta) {
+  return resolveStages(workflow, meta).filter((s) => {
+    if (isStageSkipped(meta, s.id)) return false;
+    if (shouldAutoSkip(s, meta)) return false;
+    return true;
+  });
+}
+function getStage(workflow, meta, stageId) {
+  return resolveStages(workflow, meta).find((s) => s.id === stageId);
+}
+function nextStageId(workflow, meta) {
+  const all = resolveStages(workflow, meta);
+  const activeIds = new Set(activeStages(workflow, meta).map((s) => s.id));
+  let start = all.findIndex((s) => s.id === meta.stage);
+  if (start === -1) start = -1;
+  for (let i = start + 1; i < all.length; i++) {
+    const id = all[i].id;
+    if (activeIds.has(id)) return id;
+  }
+  return null;
+}
+function firstActiveStageId(workflow, meta) {
+  return activeStages(workflow, meta)[0]?.id ?? null;
+}
+function inferComplexity(title, hints) {
+  const text = `${title} ${(hints?.keywords ?? []).join(" ")}`.toLowerCase();
+  const hotfixHints = ["typo", "hotfix", "nit", "rename", "bump", "chore", "readme", "docs"];
+  const highHints = [
+    "architecture",
+    "migration",
+    "auth",
+    "payment",
+    "billing",
+    "redesign",
+    "platform",
+    "arb",
+    "epic"
+  ];
+  if (hotfixHints.some((h) => text.includes(h))) return "low";
+  if (highHints.some((h) => text.includes(h))) return "high";
+  if (text.length > 80) return "medium";
+  return "medium";
+}
+async function recommendWorkflow(projectRoot, title, config, opts) {
+  const available = await listWorkflowNames(projectRoot);
+  const allowed = config.allowed_workflows?.length ? available.filter((n) => config.allowed_workflows.includes(n)) : available;
+  if (opts?.preferred) {
+    if (!available.includes(opts.preferred)) {
+      throw new Error(
+        `Workflow "${opts.preferred}" is not available. Available: ${available.join(", ") || "(none)"}`
+      );
+    }
+    if (config.allowed_workflows?.length && !config.allowed_workflows.includes(opts.preferred)) {
+      throw new Error(
+        `Workflow "${opts.preferred}" is not in allowed_workflows: ${config.allowed_workflows.join(", ")}`
+      );
+    }
+    return {
+      name: opts.preferred,
+      reason: "Explicitly selected",
+      alternatives: allowed.filter((n) => n !== opts.preferred)
+    };
+  }
+  if (config.default_workflow !== "recommend" && allowed.includes(config.default_workflow)) {
+    return {
+      name: config.default_workflow,
+      reason: `Repo default_workflow=${config.default_workflow}`,
+      alternatives: allowed.filter((n) => n !== config.default_workflow)
+    };
+  }
+  const complexity = opts?.complexity ?? inferComplexity(title);
+  const scored = [];
+  for (const name of allowed) {
+    try {
+      const wf = await loadWorkflow(projectRoot, name);
+      let score = wf.recommendation?.priority ?? 0;
+      let reason = `workflow priority ${score}`;
+      const when = wf.recommendation?.when;
+      if (complexity === "low" && name === "hotfix") {
+        score += 50;
+        reason = "Low complexity \u2192 hotfix";
+      } else if (complexity === "low" && name === "patch") {
+        score += 40;
+        reason = "Low complexity \u2192 patch";
+      } else if (complexity === "medium" && name === "feature") {
+        score += 45;
+        reason = "Medium complexity \u2192 feature";
+      } else if (complexity === "medium" && name === "patch") {
+        score += 30;
+        reason = "Medium complexity \u2192 patch";
+      } else if (complexity === "high" && name === "enterprise-feature") {
+        score += 50;
+        reason = "High complexity \u2192 enterprise-feature";
+      } else if (complexity === "high" && name === "feature") {
+        score += 35;
+        reason = "High complexity \u2192 feature";
+      }
+      const keywords = when?.keywords ?? [];
+      const titleLower = title.toLowerCase();
+      if (keywords.some((k) => titleLower.includes(k.toLowerCase()))) {
+        score += 20;
+        reason = `Keyword match for ${name}`;
+      }
+      scored.push({ name, score, reason });
+    } catch {
+    }
+  }
+  scored.sort((a, b) => b.score - a.score);
+  const best = scored[0];
+  if (!best) {
+    throw new Error("No workflows available. Run `sdd init` or add files under .sdd/workflows/");
+  }
+  return {
+    name: best.name,
+    reason: best.reason,
+    alternatives: scored.slice(1).map((s) => s.name)
+  };
+}
+
+// src/change-context.ts
+async function loadChangeMeta(projectRoot, config, changeId) {
+  const path = changeMetaPath(projectRoot, config, changeId);
+  if (!await pathExists(path)) {
+    throw new Error(`Change not found: ${changeId}`);
+  }
+  return ChangeMetaSchema.parse(await readYaml(path));
+}
+async function saveChangeMeta(projectRoot, config, meta) {
+  meta.updated = nowIso();
+  await writeYaml(changeMetaPath(projectRoot, config, meta.id), ChangeMetaSchema.parse(meta));
+}
+async function buildContext(projectRoot, config, changeId) {
+  const meta = await loadChangeMeta(projectRoot, config, changeId);
+  const workflow = await loadWorkflow(projectRoot, meta.workflow);
+  return {
+    id: changeId,
+    path: changePath(projectRoot, config, changeId),
+    meta,
+    workflow,
+    stages: resolveStages(workflow, meta),
+    active: activeStages(workflow, meta)
+  };
+}
+async function listChanges(projectRoot, config) {
+  return listDirs(changesDir(projectRoot, config));
+}
+async function getActiveChangeId(projectRoot, config) {
+  const pointer = activePointerPath(projectRoot, config);
+  if (await pathExists(pointer)) {
+    const id = (await readText(pointer)).trim();
+    if (id && await pathExists(changePath(projectRoot, config, id))) {
+      return id;
+    }
+    if (id) {
+      await writeText(pointer, "");
+    }
+  }
+  const all = await listChanges(projectRoot, config);
+  const inProgress = [];
+  for (const id of all) {
+    try {
+      const meta = await loadChangeMeta(projectRoot, config, id);
+      if (meta.status === "in_progress" || meta.status === "blocked") {
+        inProgress.push({ id, updated: meta.updated ?? meta.created });
+      }
+    } catch {
+    }
+  }
+  if (!inProgress.length) return null;
+  inProgress.sort((a, b) => b.updated.localeCompare(a.updated));
+  return inProgress[0].id;
+}
+async function clearActiveIf(projectRoot, config, changeId) {
+  const pointer = activePointerPath(projectRoot, config);
+  if (!await pathExists(pointer)) return;
+  const id = (await readText(pointer)).trim();
+  if (id === changeId) {
+    await writeText(pointer, "");
+  }
+}
+async function setActiveChange(projectRoot, config, changeId) {
+  await ensureDir(changesDir(projectRoot, config));
+  await writeText(activePointerPath(projectRoot, config), `${changeId}
+`);
+}
+async function resolveChangeId(projectRoot, config, changeId) {
+  if (changeId) return changeId;
+  const active = await getActiveChangeId(projectRoot, config);
+  if (!active) {
+    throw new Error("No active change. Pass --change <id> or run `sdd new`.");
+  }
+  return active;
+}
+
+export {
+  listWorkflowNames,
+  loadWorkflow,
+  resolveStages,
+  isStageSkipped,
+  shouldAutoSkip,
+  activeStages,
+  getStage,
+  nextStageId,
+  firstActiveStageId,
+  inferComplexity,
+  recommendWorkflow,
+  slugify,
+  todayIsoDate,
+  nowIso,
+  changeDirName,
+  uniqueChangeDirName,
+  loadChangeMeta,
+  saveChangeMeta,
+  buildContext,
+  listChanges,
+  getActiveChangeId,
+  clearActiveIf,
+  setActiveChange,
+  resolveChangeId
+};