@leonarto/spec-embryo 0.1.0

package/README.md

@@ -0,0 +1,156 @@
+# spec-embryo
+
+`spec-embryo` is a local-first, spec-first, CLI-first project memory and orchestration tool for AI-assisted software work. It attaches to a repo's documentation surface when that is a good fit and otherwise creates its own `spm/` home. Durable memory stays readable in Markdown with TOML frontmatter while deterministic TypeScript derives status, resume context, and next actions from those files.
+
+## Philosophy
+
+- Local-first: the repo is the source of truth.
+- Deterministic-first: parsing, linking, validation, git inspection, and next-action derivation stay in local code.
+- Spec-first: specs anchor work; tasks attach to specs.
+- Review-gated execution: implementation work should pass through review before it is marked done, and review findings must be fixed before a task leaves the review gate.
+- Resume-friendly: current state and handoffs make interrupted work easy to continue.
+- Agent-native without agent-dependence: prompt-return is first-class, subprocess backends are adapters, and the tool is useful with zero agent configured.
+
+## V1 workflow
+
+```bash
+bun run spec-embryo init
+bun run spm init
+bun run spm status
+bun run spm current show
+bun run spm current set --focus "Implement current-state maintenance flows" --active-task-ids TASK-006
+bun run spm ui
+bun run spm resume
+bun run spm resume --backend prompt
+bun run spm spec list
+bun run spm spec create --title "Local visualization server" --summary "Define the UI slice for managed project memory" --status active --tags ui,server
+bun run spm spec set-status SPEC-003 active
+bun run spm spec import-prompt --source docs/specs --instructions "Preserve product intent and split execution into tasks"
+bun run spm task list
+bun run spm task create --title "Add spec create command" --summary "Let the CLI create new spec docs deterministically" --spec-ids SPEC-002 --depends-on TASK-004 --priority 1
+bun run spm task set-status TASK-005 in_progress
+bun run spm handoff --title "Checkpoint before refactor"
+bun run spm reshape --dry-run
+```
+
+## Install
+
+```bash
+bun add -g @leonarto/spec-embryo
+```
+
+Or install directly from GitHub:
+
+```bash
+bun add -g github:Leonarto/spec-embryo
+```
+
+You can also run the entrypoint directly:
+
+```bash
+bun run src/index.ts status
+```
+
+`spm` is the primary short command. `spec-embryo` is the long-form name.
+
+## Source-of-truth layout
+
+```text
+.specpm/
+  config.toml
+  templates/
+docs/
+  spm/
+    current.md
+    handoffs/
+    specs/
+    tasks/
+    skills/
+  architecture.md
+  spec-format.md
+src/
+tests/
+web/
+```
+
+## Command summary
+
+- `init`: act as the primary adoption entrypoint by classifying repo state, discovering a docs/specs surface when appropriate, and creating or completing the managed memory home.
+- `init --json`: return the same adoption classification plus a structured next-step guide for an already-running agent.
+- `reshape`: bring project memory back to the standard managed layout if it drifted.
+- `doctor`: inspect repo-memory health, adoption state, drift, and broken links without rewriting files.
+- `doctor --json`: return structured findings plus deterministic migration and first-week guidance for agent continuation.
+- `status`: inspect current repo state, linked work, blockers, git changes, changed managed docs, and critical path.
+- `current show` / `current set`: inspect and deterministically update the explicit current-state checkpoint.
+- `ui`: start the local SvelteKit dashboard that visualizes the managed project memory.
+- `resume`: build deterministic resume context for a human, or a prompt bundle for an already-running agent.
+- `handoff`: write a durable handoff Markdown checkpoint from the current state.
+- `spec list`: list specs and their linked tasks.
+- `spec create`: create a new spec doc with a deterministic ID and optional linked tasks.
+- `spec set-status`: update a spec status deterministically in-place.
+- `spec import-prompt`: scan an existing docs/specs folder and emit an agent-ready migration bundle for Spec Embryo format.
+- `task list`: list tasks with dependency and status details.
+- `task create`: create a new task doc with a deterministic ID and update linked specs automatically.
+- `task set-status`: update a task status deterministically in-place, including the explicit `review` stage before `done`.
+- `task archive` / `task archive-done` / `task archive-cancelled`: archive closed tasks without deleting their durable docs.
+- `task restore`: clear archival metadata so a task is visible in active-flow views again.
+
+Task docs now support explicit lifecycle metadata such as `created_at`, `completed_at`, and `cancelled_at`, so archival and time-based analysis can build on meaningful state transitions instead of `updated_at`.
+
+## Execution modes
+
+- `deterministic`: pure local code, the default.
+- `prompt`: return structured context, a recommended prompt, expected output, and subtask prompts instead of nesting another AI.
+- `codex` / `claude`: subprocess adapters that can be enabled later in `.specpm/config.toml`.
+
+When a subprocess backend is enabled, Spec Embryo now gives it a stable launch contract:
+
+- prompt text token: `{prompt}` or `{prompt_text}`
+- prompt bundle JSON token: `{prompt_bundle}`
+- prompt text file token: `{prompt_text_file}` or legacy `{prompt_file}`
+- prompt bundle file token: `{prompt_bundle_file}` or `{bundle_file}`
+- env vars: `SPM_BACKEND_NAME`, `SPM_PROJECT_ROOT`, `SPM_PROMPT_FILE`, `SPM_PROMPT_TEXT_FILE`, `SPM_PROMPT_BUNDLE_FILE`
+
+That keeps prompt-return and subprocess execution aligned instead of making each backend invent its own prompt packaging.
+
+## What is implemented now
+
+- Bun + TypeScript CLI with small, typed modules
+- Markdown + TOML frontmatter document model
+- Deterministic parsing and validation
+- Git-aware status and resume summaries, including deterministic changed-item derivation
+- Task dependency graph and simple critical path derivation
+- Local SvelteKit workspace launched through `spm ui`
+- Workspace views for overview dashboard, task Kanban, Specs, and a compact grouped Gantt timeline
+- Task Kanban spec filters that narrow the active board without pulling archived work back into the operational flow
+- Multi-spec and lifecycle-window filters for analytical Specs and Gantt slices, including archived work when the goal is slice analysis instead of active-board hygiene
+- Dedicated spec and task detail routes with deterministic not-found states, linked context, and inline source narrative rendering
+- Spec detail pages that can parse `Open Questions`, answer them in batch from the UI, write those answers back into Markdown deterministically, and surface continuation guidance plus an agent evaluation prompt bundle
+- A denser split-pane timeline with spec grouping and active-vs-completed display modes for broader planning scans
+- Interactive timeline tracing with URL-driven task selection, distinct upstream/downstream highlighting, and related-spec emphasis for cross-spec diagnosis
+- Prompt-return backend for agent-safe orchestration
+- Handoff file generation
+- Deterministic spec/task creation with automatic back-linking
+- Initial spec/task/current-state templates and seed files
+- Adoption-aware `init` output that classifies fresh, legacy-docs, partial, and already-adopted repos before seeding files
+
+## Architecture
+
+Architecture details live in [docs/architecture.md](docs/architecture.md).
+
+Spec format details live in [docs/spec-format.md](docs/spec-format.md).
+
+## Agent guidance
+
+- Root repo guidance lives in [AGENTS.md](AGENTS.md).
+- Growing areas also have local `AGENTS.md` files with folder-specific context.
+- Use `bun run check:agents` after updating those files to keep them concise and fast.
+- The same logic is available in-product through `bun run spm agents check`.
+- `bun run spm status` includes an AGENTS health summary so instruction drift shows up in normal PM flow.
+- The repo-local AGENTS maintenance skill lives in `skills/agents-md-maintainer/`.
+
+## Testing
+
+```bash
+bun test
+```

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@leonarto/spec-embryo",
+  "version": "0.1.0",
+  "description": "Spec Embryo: local-first, spec-first, CLI-first project memory and orchestration for AI-assisted software work.",
+  "module": "src/index.ts",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Leonarto/spec-embryo.git"
+  },
+  "homepage": "https://github.com/Leonarto/spec-embryo#readme",
+  "bugs": {
+    "url": "https://github.com/Leonarto/spec-embryo/issues"
+  },
+  "keywords": [
+    "ai",
+    "cli",
+    "project-memory",
+    "specs",
+    "tasks",
+    "agent"
+  ],
+  "license": "MIT",
+  "bin": {
+    "spec-embryo": "src/index.ts",
+    "spm": "src/index.ts"
+  },
+  "scripts": {
+    "spec-embryo": "bun run src/index.ts",
+    "spm": "bun run src/index.ts",
+    "ui": "bun run src/index.ts ui",
+    "start": "bun run src/index.ts",
+    "test": "bun test",
+    "check:agents": "bun run scripts/check-agents.ts",
+    "web:check": "bun run --cwd web check"
+  },
+  "dependencies": {
+    "@lucide/svelte": "^1.7.0",
+    "@sveltejs/adapter-auto": "7.0.1",
+    "@sveltejs/kit": "2.55.0",
+    "@sveltejs/vite-plugin-svelte": "7.0.0",
+    "@types/node": "25.5.0",
+    "smol-toml": "1.6.1",
+    "svelte": "5.55.1",
+    "typescript": "6.0.2",
+    "vite": "8.0.3"
+  }
+}

package/src/backends/base.ts

@@ -0,0 +1,18 @@
+import type { BackendName, ProjectConfig, ResumeContext } from "../domain.ts";
+
+export interface BackendRunOptions {
+  rootDir: string;
+  config: ProjectConfig;
+  json?: boolean;
+  spawn?: boolean;
+}
+
+export interface BackendRunResult {
+  text: string;
+  json?: unknown;
+}
+
+export interface ResumeBackend {
+  name: BackendName;
+  run(context: ResumeContext, options: BackendRunOptions): Promise<BackendRunResult>;
+}

package/src/backends/deterministic.ts

@@ -0,0 +1,105 @@
+import type { ResumeContext } from "../domain.ts";
+import type { BackendRunOptions, BackendRunResult, ResumeBackend } from "./base.ts";
+
+function section(title: string, lines: string[]): string {
+  return [title, ...lines.map((line) => `  ${line}`)].join("\n");
+}
+
+export class DeterministicBackend implements ResumeBackend {
+  name = "deterministic" as const;
+
+  async run(context: ResumeContext, options: BackendRunOptions): Promise<BackendRunResult> {
+    const lines: string[] = [];
+
+    lines.push(`Project: ${context.projectName}`);
+    lines.push(`Focus: ${context.focus}`);
+    lines.push(`Summary: ${context.summary}`);
+
+    if (context.git.available) {
+      lines.push(`Git: ${context.git.branch ?? "unknown branch"}${context.git.dirty ? " (dirty)" : " (clean)"}`);
+      if (context.git.lastCommit) {
+        lines.push(`Last commit: ${context.git.lastCommit}`);
+      }
+    }
+
+    const sections = [
+      section(
+        "Active Specs",
+        context.activeSpecs.length > 0
+          ? context.activeSpecs.map((spec) => `${spec.id} [${spec.status}] ${spec.title}`)
+          : ["No active specs recorded."],
+      ),
+      section(
+        "Active Tasks",
+        context.activeTasks.length > 0
+          ? context.activeTasks.map((entry) => {
+              const deps = entry.unmetDependencies.length > 0 ? ` | unmet deps: ${entry.unmetDependencies.join(", ")}` : "";
+              return `${entry.task.id} [${entry.task.status}] p${entry.task.priority} ${entry.task.title}${deps}`;
+            })
+          : ["No active tasks recorded."],
+      ),
+      section(
+        "Blocked",
+        context.blockedTasks.length > 0
+          ? context.blockedTasks.map((entry) => {
+              const reason = entry.unmetDependencies.length > 0 ? entry.unmetDependencies.join(", ") : "manually blocked";
+              return `${entry.task.id} ${entry.task.title} | waiting on ${reason}`;
+            })
+          : ["No blocked tasks."],
+      ),
+      section(
+        "Review",
+        context.reviewTasks.length > 0
+          ? context.reviewTasks.map((entry) => `${entry.task.id} [${entry.task.status}] p${entry.task.priority} ${entry.task.title}`)
+          : ["No tasks currently in review."],
+      ),
+      section(
+        "Ready Next",
+        context.readyTasks.length > 0
+          ? context.readyTasks.slice(0, 5).map((entry) => `${entry.task.id} p${entry.task.priority} ${entry.task.title}`)
+          : ["No ready tasks."],
+      ),
+      section(
+        "Critical Path",
+        context.criticalPath.length > 0
+          ? context.criticalPath.map((task) => `${task.id} [${task.status}] ${task.title}`)
+          : ["No unfinished dependency chain found."],
+      ),
+      section(
+        "Next Actions",
+        context.nextActions.map((action) => action),
+      ),
+    ];
+
+    if (context.recentHandoff) {
+      sections.push(
+        section("Recent Handoff", [
+          `${context.recentHandoff.id} at ${context.recentHandoff.createdAt}`,
+          context.recentHandoff.title,
+          context.recentHandoff.summary,
+        ]),
+      );
+    }
+
+    if (context.git.shortStatus.length > 0) {
+      sections.push(section("Git Changes", context.git.shortStatus.slice(0, 10)));
+    }
+
+    if (context.changedItems.length > 0) {
+      sections.push(
+        section(
+          "Changed Items",
+          context.changedItems.slice(0, 10).map((item) =>
+            item.id ? `[${item.kind}] ${item.id}${item.title ? ` ${item.title}` : ""}` : `[${item.kind}] ${item.path}`,
+          ),
+        ),
+      );
+    }
+
+    const text = `${lines.join("\n")}\n\n${sections.join("\n\n")}`;
+    return {
+      text,
+      json: options.json ? context : undefined,
+    };
+  }
+}

package/src/backends/index.ts

@@ -0,0 +1,26 @@
+import type { BackendName, ProjectConfig } from "../domain.ts";
+import type { ResumeBackend } from "./base.ts";
+import { DeterministicBackend } from "./deterministic.ts";
+import { PromptBackend } from "./prompt.ts";
+import { SubprocessBackend } from "./subprocess.ts";
+
+class CodexBackend extends SubprocessBackend {
+  name = "codex" as const;
+}
+
+class ClaudeBackend extends SubprocessBackend {
+  name = "claude" as const;
+}
+
+export function resolveResumeBackend(name: BackendName, config: ProjectConfig): ResumeBackend {
+  switch (name) {
+    case "deterministic":
+      return new DeterministicBackend();
+    case "prompt":
+      return new PromptBackend();
+    case "codex":
+      return new CodexBackend(config.backends.codex);
+    case "claude":
+      return new ClaudeBackend(config.backends.claude);
+  }
+}

package/src/backends/prompt.ts

@@ -0,0 +1,169 @@
+import type { ResumeContext } from "../domain.ts";
+import type { BackendRunOptions, BackendRunResult, ResumeBackend } from "./base.ts";
+
+export interface PromptBundle {
+  context: {
+    project_name: string;
+    focus: string;
+    summary: string;
+    active_specs: Array<{
+      id: string;
+      title: string;
+      status: string;
+      task_ids: string[];
+    }>;
+    active_tasks: Array<{
+      id: string;
+      title: string;
+      status: string;
+      spec_ids: string[];
+      unmet_dependencies: string[];
+      priority: number;
+    }>;
+    blocked_tasks: Array<{
+      id: string;
+      title: string;
+      unmet_dependencies: string[];
+    }>;
+    review_tasks: Array<{
+      id: string;
+      title: string;
+      status: string;
+      priority: number;
+    }>;
+    ready_tasks: Array<{
+      id: string;
+      title: string;
+      priority: number;
+    }>;
+    critical_path: string[];
+    recent_handoff: {
+      id: string;
+      title: string;
+      created_at: string;
+      summary: string;
+    } | null;
+    git: {
+      branch: string | null;
+      dirty: boolean;
+      last_commit: string | null;
+      short_status: string[];
+    };
+    changed_items: ResumeContext["changedItems"];
+    next_actions: string[];
+  };
+  recommended_prompt: string;
+  expected_output_format: {
+    summary_sections: string[];
+    require_explicit_file_refs: boolean;
+    prefer_deterministic_updates: boolean;
+  };
+  subtask_prompts: Array<{
+    task_id: string;
+    prompt: string;
+  }>;
+}
+
+export function buildPromptBundle(context: ResumeContext): PromptBundle {
+  return {
+    context: {
+      project_name: context.projectName,
+      focus: context.focus,
+      summary: context.summary,
+      active_specs: context.activeSpecs.map((spec) => ({
+        id: spec.id,
+        title: spec.title,
+        status: spec.status,
+        task_ids: spec.taskIds,
+      })),
+      active_tasks: context.activeTasks.map((entry) => ({
+        id: entry.task.id,
+        title: entry.task.title,
+        status: entry.task.status,
+        spec_ids: entry.task.specIds,
+        unmet_dependencies: entry.unmetDependencies,
+        priority: entry.task.priority,
+      })),
+      blocked_tasks: context.blockedTasks.map((entry) => ({
+        id: entry.task.id,
+        title: entry.task.title,
+        unmet_dependencies: entry.unmetDependencies,
+      })),
+      review_tasks: context.reviewTasks.map((entry) => ({
+        id: entry.task.id,
+        title: entry.task.title,
+        status: entry.task.status,
+        priority: entry.task.priority,
+      })),
+      ready_tasks: context.readyTasks.map((entry) => ({
+        id: entry.task.id,
+        title: entry.task.title,
+        priority: entry.task.priority,
+      })),
+      critical_path: context.criticalPath.map((task) => task.id),
+      recent_handoff: context.recentHandoff
+        ? {
+            id: context.recentHandoff.id,
+            title: context.recentHandoff.title,
+            created_at: context.recentHandoff.createdAt,
+            summary: context.recentHandoff.summary,
+          }
+        : null,
+      git: {
+        branch: context.git.branch ?? null,
+        dirty: context.git.dirty,
+        last_commit: context.git.lastCommit ?? null,
+        short_status: context.git.shortStatus,
+      },
+      changed_items: context.changedItems,
+      next_actions: context.nextActions,
+    },
+    recommended_prompt: [
+      "You are resuming work on this repository.",
+      `Current focus: ${context.focus}`,
+      "Use the structured context provided by Spec Embryo as the source of truth.",
+      "Do not restate everything. First answer:",
+      "1. where the project currently is",
+      "2. what should happen next",
+      "3. what is blocked or risky",
+      "4. which files/docs should be updated as part of the next slice",
+      "Then propose the smallest high-value next implementation step.",
+    ].join("\n"),
+    expected_output_format: {
+      summary_sections: ["where-we-are", "next-step", "blockers", "docs-to-touch"],
+      require_explicit_file_refs: true,
+      prefer_deterministic_updates: true,
+    },
+    subtask_prompts: context.readyTasks.slice(0, 3).map((entry) => ({
+      task_id: entry.task.id,
+      prompt: `Work on ${entry.task.id} (${entry.task.title}). Keep changes aligned with spec-backed files and update current state if the focus changes.`,
+    })),
+  };
+}
+
+export function renderPromptBundleText(bundle: PromptBundle): string {
+  return [
+    bundle.recommended_prompt,
+    "",
+    "Expected output format:",
+    JSON.stringify(bundle.expected_output_format, null, 2),
+    "",
+    "Structured context:",
+    JSON.stringify(bundle.context, null, 2),
+  ].join("\n");
+}
+
+export class PromptBackend implements ResumeBackend {
+  name = "prompt" as const;
+
+  async run(context: ResumeContext, options: BackendRunOptions): Promise<BackendRunResult> {
+    const bundle = buildPromptBundle(context);
+    const jsonText = JSON.stringify(bundle, null, 2);
+    const text = ["Prompt-return bundle", "", "Recommended prompt:", renderPromptBundleText(bundle)].join("\n");
+
+    return {
+      text: options.json ? jsonText : text,
+      json: bundle,
+    };
+  }
+}