@leonarto/spec-embryo 0.1.0

package/src/templates.ts

@@ -0,0 +1,270 @@
+import { basename } from "node:path";
+import { serializeTomlFrontmatter } from "./frontmatter.ts";
+import { buildManagedPaths } from "./services/layout.ts";
+
+export function createConfigToml(projectName: string, memoryDir = "docs/spm"): string {
+  const managed = buildManagedPaths(memoryDir);
+  return `
+tool_version = "0.1.0"
+project_name = ${JSON.stringify(projectName)}
+memory_dir = ${JSON.stringify(managed.memoryDir)}
+state_file = ${JSON.stringify(managed.stateFile)}
+handoffs_dir = ${JSON.stringify(managed.handoffsDir)}
+specs_dir = ${JSON.stringify(managed.specsDir)}
+tasks_dir = ${JSON.stringify(managed.tasksDir)}
+skills_dir = ${JSON.stringify(managed.skillsDir)}
+
+[defaults]
+resume_backend = "deterministic"
+
+[backends.deterministic]
+enabled = true
+
+[backends.prompt]
+enabled = true
+
+[backends.codex]
+enabled = false
+command = "codex"
+args = ["exec", "{prompt_text_file}"]
+
+[backends.claude]
+enabled = false
+command = "claude"
+args = ["-p", "{prompt}"]
+`.trimStart();
+}
+
+export function createCurrentStateTemplate(updatedAt: string): string {
+  return serializeTomlFrontmatter(
+    {
+      doc_kind: "current-state",
+      id: "CURRENT",
+      title: "Current Project State",
+      summary: "Building the first usable local-first Spec Embryo foundation.",
+      focus: "Ship the first usable Spec Embryo workflow around init, status, resume, handoff, spec list, and task list.",
+      active_spec_ids: ["SPEC-001"],
+      active_task_ids: ["TASK-001", "TASK-002"],
+      blocked_task_ids: [],
+      next_action_hints: [
+        "Verify init/status/resume flows against the seed repo files.",
+        "Keep the file-backed storage layer stable before adding server mode.",
+      ],
+      updated_at: updatedAt,
+      tags: ["v1", "seed"],
+    },
+    `# Current State
+
+This file is the explicit checkpoint for interrupted work. It should answer:
+
+- what the project is trying to do right now
+- which specs and tasks are active
+- what should happen next
+- what is blocked
+- where a future human or agent should resume
+
+## Narrative
+
+The immediate goal is to establish a strong deterministic core. The repo itself is the durable memory system, so the first slice prioritizes file formats, linking, validation, and resume ergonomics before any local server or remote backend exists.
+
+## Notes
+
+- Prompt-return mode is first-class to avoid unnecessary nested agent spawning.
+- Subprocess agent backends are adapters, not the center of the product.
+`,
+  );
+}
+
+export function createSeedSpecTemplate(updatedAt: string): string {
+  return serializeTomlFrontmatter(
+    {
+      doc_kind: "spec",
+      id: "SPEC-001",
+      title: "Establish the deterministic local-first core",
+      status: "active",
+      summary: "Define the file-backed, spec-first architecture and ship the first usable CLI workflow.",
+      task_ids: ["TASK-001", "TASK-002", "TASK-003"],
+      tags: ["v1", "foundation", "cli"],
+      owner: "human-ai",
+      updated_at: updatedAt,
+    },
+    `# Problem
+
+AI-assisted software work loses continuity when the current state only lives in chat history or an external task tracker.
+
+# Goals
+
+- Keep repo memory local and readable.
+- Make specs central and tasks explicitly linked.
+- Support deterministic status and resume flows without any LLM.
+- Leave room for prompt-return and subprocess backends later.
+
+# Non-Goals For V1
+
+- No web UI yet.
+- No database dependency.
+- No mandatory hosted service.
+`,
+  );
+}
+
+export function createSeedTaskTemplates(updatedAt: string): Array<{ name: string; content: string }> {
+  return [
+    {
+      name: "TASK-001-bootstrap-cli.md",
+      content: serializeTomlFrontmatter(
+        {
+          doc_kind: "task",
+          id: "TASK-001",
+          title: "Implement the Bun CLI and file-backed repository layer",
+          status: "in_progress",
+          summary: "Create the runnable CLI entrypoint, document parser, storage helpers, and core commands.",
+          spec_ids: ["SPEC-001"],
+          depends_on: [],
+          blocked_by: [],
+          priority: 1,
+          owner_role: "builder",
+          created_at: updatedAt,
+          tags: ["v1", "cli"],
+          updated_at: updatedAt,
+        },
+        `# Scope
+
+Ship the initial commands and the document model so the project is already useful with local files alone.
+
+# Done Looks Like
+
+- \`init\`, \`status\`, \`resume\`, \`handoff\`, \`spec list\`, and \`task list\` exist
+- repo memory files are created and validated deterministically
+- the CLI can help a human or agent resume after interruption
+`,
+      ),
+    },
+    {
+      name: "TASK-002-deterministic-resume.md",
+      content: serializeTomlFrontmatter(
+        {
+          doc_kind: "task",
+          id: "TASK-002",
+          title: "Derive deterministic status, resume context, and next actions",
+          status: "todo",
+          summary: "Build the engine that links specs, tasks, current state, git data, blockers, and critical path.",
+          spec_ids: ["SPEC-001"],
+          depends_on: ["TASK-001"],
+          blocked_by: [],
+          priority: 1,
+          owner_role: "planner",
+          created_at: updatedAt,
+          tags: ["v1", "engine"],
+          updated_at: updatedAt,
+        },
+        `# Scope
+
+Use explicit rules to compute what matters now, what is blocked, and what should happen next.
+
+# Notes
+
+Critical path can be simple in v1: longest unfinished dependency chain by declared task links.
+`,
+      ),
+    },
+    {
+      name: "TASK-003-prompt-return-mode.md",
+      content: serializeTomlFrontmatter(
+        {
+          doc_kind: "task",
+          id: "TASK-003",
+          title: "Add prompt-return mode and subprocess backend adapters",
+          status: "todo",
+          summary: "Return structured context and prompts when an AI is already calling the tool, with future-ready subprocess adapters.",
+          spec_ids: ["SPEC-001"],
+          depends_on: ["TASK-002"],
+          blocked_by: [],
+          priority: 2,
+          owner_role: "orchestrator",
+          created_at: updatedAt,
+          tags: ["v1", "backends"],
+          updated_at: updatedAt,
+        },
+        `# Scope
+
+Prompt-return should be first-class. Spawning another AI should be opt-in rather than assumed.
+
+# Notes
+
+Adapters should keep backend-specific behavior behind a shared interface.
+`,
+      ),
+    },
+  ];
+}
+
+export function createSkillsReadme(): string {
+  return `# Managed Skills
+
+This folder is part of the managed Spec Embryo memory surface for the project.
+
+Possible future contents:
+
+- role definitions for planner / builder / reviewer agents
+- prompt snippets or subtask recipes
+- deterministic capability manifests
+- skill docs another agent can inspect before continuing work
+`;
+}
+
+export function createTemplateFiles(): Array<{ name: string; content: string }> {
+  const placeholderTimestamp = "2026-04-02T00:00:00Z";
+  return [
+    {
+      name: "spec-template.md",
+      content: createSeedSpecTemplate(placeholderTimestamp),
+    },
+    {
+      name: "task-template.md",
+      content: createSeedTaskTemplates(placeholderTimestamp)[0]!.content,
+    },
+    {
+      name: "handoff-template.md",
+      content: serializeTomlFrontmatter(
+        {
+          doc_kind: "handoff",
+          id: "HANDOFF-PLACEHOLDER",
+          title: "Checkpoint title",
+          summary: "Short handoff summary.",
+          handoff_kind: "checkpoint",
+          created_at: placeholderTimestamp,
+          active_task_ids: ["TASK-001"],
+          related_spec_ids: ["SPEC-001"],
+          author: "spec-embryo",
+          updated_at: placeholderTimestamp,
+          tags: ["handoff"],
+        },
+        `# Summary
+
+Describe where the project was left.
+
+## What Changed
+
+- Itemize meaningful changes.
+
+## Next Steps
+
+- List the clearest next moves.
+
+## Blockers
+
+- Note anything that needs a decision or unblocking.
+`,
+      ),
+    },
+    {
+      name: "current-state-template.md",
+      content: createCurrentStateTemplate(placeholderTimestamp),
+    },
+  ];
+}
+
+export function inferProjectName(rootDir: string): string {
+  return basename(rootDir);
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022"],
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}

package/web/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "spec-embryo-web",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "svelte-kit sync && vite dev",
+    "build": "svelte-kit sync && vite build",
+    "preview": "vite preview",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-auto": "7.0.1",
+    "@sveltejs/kit": "2.55.0",
+    "@sveltejs/vite-plugin-svelte": "7.0.0",
+    "@types/node": "25.5.0",
+    "svelte": "5.55.1",
+    "svelte-check": "4.4.6",
+    "typescript": "6.0.2",
+    "vite": "8.0.3"
+  },
+  "dependencies": {
+    "@lucide/svelte": "^1.7.0"
+  }
+}

package/web/src/app.css

@@ -0,0 +1,83 @@
+:root {
+  --bg: #f1ebdf;
+  --bg-deep: #e5dac7;
+  --panel: rgba(255, 252, 246, 0.84);
+  --panel-strong: rgba(255, 253, 249, 0.95);
+  --panel-muted: rgba(248, 242, 232, 0.82);
+  --ink: #181612;
+  --muted: #5a5143;
+  --muted-soft: #766b5d;
+  --line: rgba(24, 22, 18, 0.12);
+  --line-strong: rgba(24, 22, 18, 0.22);
+  --accent: #0f8d60;
+  --accent-soft: rgba(15, 141, 96, 0.12);
+  --warning: #8f5421;
+  --warning-soft: rgba(143, 84, 33, 0.14);
+  --danger: #972d2d;
+  --danger-soft: rgba(151, 45, 45, 0.12);
+  --shadow: 0 28px 80px rgba(37, 29, 13, 0.12);
+  --shadow-soft: 0 10px 28px rgba(34, 26, 12, 0.08);
+  --display-font: "Iowan Old Style", "Palatino Linotype", "Book Antiqua", Georgia, serif;
+  --body-font: "Avenir Next", "Helvetica Neue", "Segoe UI", sans-serif;
+  --radius-lg: 1.15rem;
+  --radius-xl: 1.55rem;
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  min-height: 100%;
+}
+
+body {
+  margin: 0;
+  color: var(--ink);
+  background:
+    radial-gradient(circle at top left, rgba(15, 141, 96, 0.12), transparent 24rem),
+    radial-gradient(circle at top right, rgba(151, 45, 45, 0.08), transparent 22rem),
+    linear-gradient(180deg, #f7f1e6 0%, var(--bg) 48%, var(--bg-deep) 100%);
+  font-family: var(--body-font);
+  text-rendering: optimizeLegibility;
+}
+
+body::before {
+  content: "";
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+  background-image:
+    linear-gradient(rgba(26, 24, 21, 0.03) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(26, 24, 21, 0.03) 1px, transparent 1px);
+  background-size: 24px 24px;
+  mask-image: linear-gradient(180deg, rgba(0, 0, 0, 0.85), transparent);
+}
+
+body::after {
+  content: "";
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+  background:
+    linear-gradient(140deg, rgba(255, 255, 255, 0.18), transparent 32%),
+    radial-gradient(circle at 80% 18%, rgba(15, 141, 96, 0.08), transparent 18rem);
+}
+
+a {
+  color: inherit;
+}
+
+button,
+input,
+textarea,
+select {
+  font: inherit;
+}
+
+::selection {
+  background: rgba(15, 141, 96, 0.18);
+}

package/web/src/app.d.ts

@@ -0,0 +1,6 @@
+// See https://svelte.dev/docs/kit/types#app.d.ts
+declare global {
+  namespace App {}
+}
+
+export {};

package/web/src/app.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    %sveltekit.head%
+  </head>
+  <body data-sveltekit-preload-data="hover">
+    <div style="display: contents">%sveltekit.body%</div>
+  </body>
+</html>

package/web/src/lib/components/AnalysisFilters.svelte

@@ -0,0 +1,293 @@
+<script lang="ts">
+  import { goto } from "$app/navigation";
+  import { page } from "$app/state";
+  import { Filter, Layers3, RotateCcw, SlidersHorizontal } from "@lucide/svelte";
+  import type { Snippet } from "svelte";
+  import type { DashboardData, DashboardTimeWindow } from "../../../../src/services/dashboard.ts";
+  import MultiSelectDropdown from "./MultiSelectDropdown.svelte";
+  import SelectDropdown from "./SelectDropdown.svelte";
+
+  let {
+    dashboard,
+    title = "Analysis filters",
+    detail = "Slice the analytical views by spec set and lifecycle period.",
+    eyebrow = "Analytical slice",
+    showTimeWindow = true,
+    resultCount = dashboard.analysis.filteredTaskCount,
+    resultLabel = "tasks in the current analytical slice",
+    hasActiveFilters = dashboard.analysis.hasActiveFilters,
+    inactiveDetail = "Without analytical filters, archived tasks stay hidden from active-flow views.",
+    activeDetail = "Archived tasks are included while filters are active.",
+    clearHref = "",
+    extraField,
+  } = $props<{
+    dashboard: DashboardData;
+    title?: string;
+    detail?: string;
+    eyebrow?: string;
+    showTimeWindow?: boolean;
+    resultCount?: number;
+    resultLabel?: string;
+    hasActiveFilters?: boolean;
+    inactiveDetail?: string;
+    activeDetail?: string;
+    clearHref?: string;
+    extraField?: Snippet;
+  }>();
+
+  const timeWindows: Array<{ value: DashboardTimeWindow; label: string; description: string }> = [
+    { value: "7d", label: "Last 7 days", description: "Only recently completed or cancelled work." },
+    { value: "30d", label: "Last 30 days", description: "A broader recent delivery slice." },
+    { value: "90d", label: "Last 90 days", description: "A quarterly view of lifecycle history." },
+  ];
+
+  const specOptions = $derived(
+    dashboard.analysis.availableSpecs.map((spec: DashboardData["analysis"]["availableSpecs"][number]) => ({
+      value: spec.id,
+      label: spec.id,
+      description: spec.title,
+    })),
+  );
+
+  const currentPath = $derived(page.url.pathname);
+
+  async function applyFilters(event: Event): Promise<void> {
+    const form = event.currentTarget as HTMLFormElement;
+    const formData = new FormData(form);
+    const searchParams = new URLSearchParams();
+
+    for (const [key, value] of formData.entries()) {
+      if (typeof value !== "string" || value.length === 0) {
+        continue;
+      }
+
+      searchParams.append(key, value);
+    }
+
+    const search = searchParams.toString();
+    await goto(search.length > 0 ? `${currentPath}?${search}` : currentPath, {
+      keepFocus: true,
+      noScroll: true,
+      replaceState: true,
+    });
+  }
+</script>
+
+<section class="filters-shell">
+  <div class="filters-copy">
+    <div class="copy-head">
+      <span class="icon-pill">
+        <Filter size={15} strokeWidth={1.9} />
+      </span>
+      <div>
+        <p class="eyebrow">{eyebrow}</p>
+        <h4>{title}</h4>
+      </div>
+    </div>
+    <p>{detail}</p>
+  </div>
+
+  <form class="filters-form" method="GET" action={currentPath} onchange={applyFilters}>
+    <div class="field-grid">
+      <fieldset class="field-card">
+        <legend>
+          <Layers3 size={14} strokeWidth={1.9} />
+          Specs
+        </legend>
+        <MultiSelectDropdown
+          name="spec"
+          options={specOptions}
+          selectedValues={dashboard.analysis.selectedSpecIds}
+          buttonLabel="Choose specs"
+          emptyLabel="All specs"
+        />
+      </fieldset>
+
+      {#if showTimeWindow}
+        <fieldset class="field-card field-card-select">
+          <legend>
+            <SlidersHorizontal size={14} strokeWidth={1.9} />
+            Time window
+          </legend>
+          <SelectDropdown
+            name="window"
+            options={timeWindows}
+            selectedValue={dashboard.analysis.timeWindow ?? ""}
+            buttonLabel="Choose window"
+            emptyLabel="All lifecycle history"
+          />
+        </fieldset>
+      {/if}
+
+      {@render extraField?.()}
+    </div>
+
+    <div class="filters-footer">
+      <div class="result-copy">
+        <strong>{resultCount}</strong>
+        <span>{resultLabel}</span>
+        {#if hasActiveFilters}
+          <small>{activeDetail}</small>
+        {:else}
+          <small>{inactiveDetail}</small>
+        {/if}
+      </div>
+
+      <div class="button-row">
+        <a class="ghost-button" href={clearHref || currentPath}>
+          <RotateCcw size={14} strokeWidth={1.9} />
+          Clear
+        </a>
+      </div>
+    </div>
+  </form>
+</section>
+
+<style>
+  .filters-shell {
+    display: grid;
+    gap: 0.85rem;
+    margin-bottom: 1rem;
+    padding: 0.9rem;
+    border-radius: var(--radius-xl);
+    border: 1px solid var(--line);
+    background: linear-gradient(180deg, rgba(255, 252, 246, 0.94), rgba(247, 241, 232, 0.88));
+    box-shadow: var(--shadow);
+  }
+
+  .filters-copy,
+  .filters-form,
+  .field-grid {
+    display: grid;
+    gap: 0.7rem;
+  }
+
+  .copy-head,
+  .filters-footer,
+  .button-row,
+  legend {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+  }
+
+  .filters-footer {
+    justify-content: space-between;
+    gap: 0.85rem;
+    flex-wrap: wrap;
+  }
+
+  .copy-head {
+    align-items: start;
+  }
+
+  .icon-pill {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 2.05rem;
+    height: 2.05rem;
+    border-radius: 0.85rem;
+    border: 1px solid var(--line);
+    background: rgba(255, 255, 255, 0.84);
+    color: var(--muted-soft);
+    flex-shrink: 0;
+  }
+
+  .eyebrow {
+    margin: 0 0 0.22rem;
+    text-transform: uppercase;
+    letter-spacing: 0.14em;
+    font-size: 0.68rem;
+    color: var(--muted);
+  }
+
+  h4,
+  p,
+  fieldset,
+  legend {
+    margin: 0;
+  }
+
+  h4 {
+    font-family: var(--display-font);
+    font-size: 1.02rem;
+  }
+
+  p,
+  .result-copy span,
+  .result-copy small {
+    color: var(--muted);
+    line-height: 1.45;
+  }
+
+  .field-grid {
+    grid-template-columns: minmax(0, 1.65fr) repeat(2, minmax(13rem, 0.9fr));
+  }
+
+  .field-grid:has(> :only-child) {
+    grid-template-columns: 1fr;
+  }
+
+  .field-card {
+    display: grid;
+    gap: 0.55rem;
+    min-width: 0;
+    padding: 0.72rem;
+    border-radius: var(--radius-lg);
+    border: 1px solid var(--line);
+    background: rgba(255, 255, 255, 0.72);
+    box-shadow: var(--shadow-soft);
+  }
+
+  .field-card-select {
+    align-content: start;
+  }
+
+  legend,
+  legend {
+    padding: 0;
+    color: var(--muted-soft);
+    font-size: 0.78rem;
+    font-weight: 600;
+  }
+
+  .ghost-button {
+    border-radius: 999px;
+    border: 1px solid var(--line-strong);
+    background: rgba(255, 255, 255, 0.9);
+    color: var(--ink);
+    box-shadow: var(--shadow-soft);
+  }
+
+  .result-copy {
+    display: grid;
+    gap: 0.08rem;
+  }
+
+  .result-copy strong {
+    font-family: var(--display-font);
+    font-size: 1.08rem;
+    line-height: 1;
+  }
+
+  .button-row {
+    flex-wrap: wrap;
+    justify-content: end;
+  }
+
+  .ghost-button {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.42rem;
+    padding: 0.62rem 0.88rem;
+    text-decoration: none;
+    cursor: pointer;
+  }
+
+  @media (max-width: 980px) {
+    .field-grid {
+      grid-template-columns: 1fr;
+    }
+  }
+</style>