@bvdm/delano 0.2.4 → 0.2.5

package/.delano/viewer/public/styles.css

@@ -602,7 +602,7 @@ button { font-family: inherit; font-size: inherit; color: inherit; background: n
 /* ---------- Workspace dashboard ---------- */
 .project-grid {
   display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+  grid-template-columns: repeat(auto-fit, minmax(400px, 1fr));
   gap: 14px;
   padding-top: 16px;
 }

package/README.md

@@ -72,6 +72,8 @@ delano install --yes
 delano viewer
 delano validate
 delano init <slug> "<Project Name>" [owner] [lead]
+delano import-spec-kit <slug> <source-md> [--name <project-name>] [--owner <owner>] [--lead <lead>] [--json]
+delano research <project-slug> <research-slug> [--title <title>] [--question <question>] [--json]
 ```
 
 Command intent:
@@ -80,6 +82,8 @@ Command intent:
 - `delano viewer` launches the read-only local UI for `.project` contracts
 - `delano validate` checks whether the runtime and required assets are in place
 - `delano init` creates a delivery project inside a repository that already has Delano installed
+- `delano import-spec-kit` creates a planned Delano project from the first supported Spec Kit-style markdown fixture and then runs validation
+- `delano research` creates repo-native research intake files inside an existing Delano project and then runs validation
 
 `delano init` usage:
 
@@ -94,8 +98,36 @@ Notes:
 - `lead` defaults to `owner`
 - this is the right command for an agent to scaffold a new delivery project after `delano install`
 
+`delano import-spec-kit` usage:
+
+```bash
+delano import-spec-kit <slug> <source-md> [--name <project-name>] [--owner <owner>] [--lead <lead>] [--json]
+```
+
+Notes:
+
+- the source markdown must use the initial supported shape documented in `docs/spec-kit/import-contract.md`
+- agents should prefer named options over positional metadata, and `--json` when parsing the result
+- imported artifacts start in planned/ready states and still have to pass Delano validation, probe, and evidence gates
+- the command is additive and refuses to overwrite an existing `.project/projects/<slug>/` folder
+
+`delano research` usage:
+
+```bash
+delano research <project-slug> <research-slug> [--title <title>] [--question <question>] [--owner <owner>] [--json]
+```
+
+Notes:
+
+- use this before mutating `spec.md`, `plan.md`, workstreams, or tasks when intent is unclear
+- research files live under `.project/projects/<project-slug>/research/<research-slug>/`
+- agents should use `--json` when parsing the result
+- research findings must fold forward into canonical Delano artifacts or be explicitly closed as no-action
+
 ## How to use Delano after install
 
+For a fast guided path, start with [Delano in the First 15 Minutes](docs/first-15-minutes.md).
+
 Recommended first step:
 
 ```bash
@@ -125,6 +157,8 @@ delano status
 delano status --open --brief
 delano next -- --all
 delano init <slug> "<Project Name>" [owner] [lead]
+delano import-spec-kit <slug> <source-md> --json
+delano research <project-slug> <research-slug> --title "Research title" --question "Primary question" --json
 ```
 
 The wrapper commands call the existing PM scripts under `.agents/scripts/pm/`. You can also run those scripts directly:
@@ -134,6 +168,7 @@ bash .agents/scripts/pm/validate.sh
 bash .agents/scripts/pm/status.sh
 bash .agents/scripts/pm/status.sh --open --brief
 bash .agents/scripts/pm/next.sh --all
+bash .agents/scripts/pm/research.sh <project-slug> <research-slug> --title "Research title" --question "Primary question" --json
 ```
 
 The viewer is packaged with `@bvdm/delano` and serves the selected repository's `.project` files read-only. It defaults to `http://127.0.0.1:3977`; set `DELANO_VIEWER_PORT` or `PORT` to use another port. It indexes `.project/context`, `.project/templates`, and `.project/projects`, then derives artifact roles, statuses, project outlines, task/workstream relationships, snippets, and rendered markdown for local inspection.

package/assets/install-manifest.json

@@ -4,8 +4,10 @@
     ".agents/README.md",
     ".agents/adapters/claude/README.md",
     ".agents/adapters/codex/README.md",
+    ".agents/adapters/manifest.schema.json",
     ".agents/adapters/opencode/README.md",
     ".agents/adapters/pi/README.md",
+    ".agents/adapters/spec-kit/adapter.json",
     ".agents/common/README.md",
     ".agents/common/log-safety.js",
     ".agents/eval-fixtures/skill-output/invalid/missing-evidence/output.json",
@@ -88,8 +90,10 @@
     ".agents/scripts/pm/epic-list.sh",
     ".agents/scripts/pm/in-progress.sh",
     ".agents/scripts/pm/init.sh",
+    ".agents/scripts/pm/import-spec-kit.sh",
     ".agents/scripts/pm/next.sh",
     ".agents/scripts/pm/prd-list.sh",
+    ".agents/scripts/pm/research.sh",
     ".agents/scripts/pm/search.sh",
     ".agents/scripts/pm/standup.sh",
     ".agents/scripts/pm/status.sh",
@@ -170,6 +174,7 @@
     ".project/registry/linear-map.json",
     ".project/registry/migration-map.json",
     ".project/templates/completion-summary.md",
+    ".project/templates/decisions.md",
     ".project/templates/plan.md",
     ".project/templates/progress-update.md",
     ".project/templates/spec.md",

package/assets/payload/.agents/adapters/manifest.schema.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://delano.dev/schemas/adapter-manifest.schema.json",
+  "title": "Delano Adapter Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "name",
+    "type",
+    "owner",
+    "status",
+    "summary",
+    "commands",
+    "generated_files",
+    "validation",
+    "install",
+    "limits"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "type": {
+      "type": "string",
+      "enum": ["agent", "authoring-tool", "sync-tool", "workflow"]
+    },
+    "owner": {
+      "type": "string",
+      "minLength": 1
+    },
+    "status": {
+      "type": "string",
+      "enum": ["proposed", "experimental", "stable", "deprecated"]
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1
+    },
+    "commands": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "description", "input", "output", "writes", "validation"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "description": { "type": "string", "minLength": 1 },
+          "input": { "type": "array", "items": { "type": "string" } },
+          "output": { "type": "array", "items": { "type": "string" } },
+          "writes": { "type": "array", "items": { "type": "string" } },
+          "validation": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "generated_files": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "owner", "mode", "conflict_behavior", "fold_forward"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "owner": { "type": "string", "minLength": 1 },
+          "mode": { "type": "string", "enum": ["create-only", "update-owned", "proposal-only", "never-overwrite"] },
+          "conflict_behavior": { "type": "string", "enum": ["abort", "diff-required", "operator-approval-required"] },
+          "fold_forward": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "validation": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" }
+    },
+    "install": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["categories", "conflict_policy"],
+      "properties": {
+        "categories": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "conflict_policy": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "limits": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" }
+    }
+  }
+}

package/assets/payload/.agents/adapters/spec-kit/adapter.json

@@ -0,0 +1,71 @@
+{
+  "id": "spec-kit",
+  "name": "Spec Kit Interop",
+  "type": "authoring-tool",
+  "owner": "delano-team",
+  "status": "experimental",
+  "summary": "Imports Spec Kit-style intent artifacts into Delano-governed delivery projects.",
+  "commands": [
+    {
+      "name": "delano import-spec-kit",
+      "description": "Create a planned Delano project from a supported Spec Kit-style markdown artifact.",
+      "input": ["slug", "source-md", "--name", "--owner", "--lead", "--json"],
+      "output": ["human summary", "JSON result with ok, command, project, source, validation"],
+      "writes": [".project/projects/<slug>/"],
+      "validation": ["delano validate"]
+    },
+    {
+      "name": "delano research",
+      "description": "Open repo-native research intake for unclear imported intent.",
+      "input": ["project-slug", "research-slug", "--title", "--question", "--json"],
+      "output": ["human summary", "JSON result with ok, command, project, research, files, validation"],
+      "writes": [".project/projects/<project-slug>/research/<research-slug>/"],
+      "validation": ["delano validate"]
+    }
+  ],
+  "generated_files": [
+    {
+      "path": ".project/projects/<slug>/spec.md",
+      "owner": "spec-kit adapter",
+      "mode": "create-only",
+      "conflict_behavior": "abort",
+      "fold_forward": "canonical spec"
+    },
+    {
+      "path": ".project/projects/<slug>/plan.md",
+      "owner": "spec-kit adapter",
+      "mode": "create-only",
+      "conflict_behavior": "abort",
+      "fold_forward": "canonical plan"
+    },
+    {
+      "path": ".project/projects/<slug>/tasks/*.md",
+      "owner": "spec-kit adapter",
+      "mode": "create-only",
+      "conflict_behavior": "abort",
+      "fold_forward": "canonical tasks with evidence gates"
+    },
+    {
+      "path": ".project/projects/<project-slug>/research/<research-slug>/",
+      "owner": "research intake",
+      "mode": "create-only",
+      "conflict_behavior": "abort",
+      "fold_forward": "spec, plan, decisions, workstreams, tasks, or updates"
+    }
+  ],
+  "validation": [
+    "delano validate",
+    "npm run check:text-safety for Delano repo changes",
+    "fixture import smoke before release"
+  ],
+  "install": {
+    "categories": ["agent-runtime", "project-templates", "skills"],
+    "conflict_policy": "Use existing Delano install allowlist behavior; abort on generated project collisions unless an operator approves a diff-backed change."
+  },
+  "limits": [
+    "Does not replace Spec Kit.",
+    "Does not execute imported tasks automatically.",
+    "Does not write Linear or GitHub state directly.",
+    "Does not depend on Obsidian, OpenClaw, or private local paths."
+  ]
+}

package/assets/payload/.agents/schemas/status-transitions.json

@@ -39,6 +39,23 @@
         "plan.status is done or deferred"
       ]
     },
+    {
+      "id": "progressed-task-requires-active-workstream",
+      "status": "in-progress|done",
+      "description": "A task must not start or complete before its parent workstream has started.",
+      "requires": [
+        "in-progress tasks require workstream.status active",
+        "done tasks require workstream.status active or done"
+      ]
+    },
+    {
+      "id": "closed-task-set-requires-closed-workstream",
+      "status": "done|deferred",
+      "description": "A workstream with no open tasks must not remain open through a stale status.",
+      "requires": [
+        "workstream.status is done or deferred"
+      ]
+    },
     {
       "id": "blocked-owner-check-back",
       "status": "blocked",

package/assets/payload/.agents/scripts/check-status-transitions.mjs

@@ -19,7 +19,9 @@ for (const requiredRule of [
   "ready-dependencies-done",
   "blocked-owner-check-back",
   "progressed-task-requires-active-project",
-  "closed-task-set-requires-closed-project"
+  "closed-task-set-requires-closed-project",
+  "progressed-task-requires-active-workstream",
+  "closed-task-set-requires-closed-workstream"
 ]) {
   if (!rules.some((rule) => rule.id === requiredRule)) {
     errors.push(`status transition contract missing rule: ${requiredRule}`);
@@ -38,6 +40,15 @@ for (const projectDir of listDirectories(projectsRoot)) {
   const specFrontmatter = existsSync(specPath) ? parseFrontmatter(specPath) : null;
   const planFrontmatter = existsSync(planPath) ? parseFrontmatter(planPath) : null;
   const hasProjectLifecycle = Boolean(specFrontmatter || planFrontmatter);
+  const workstreams = collectWorkstreams(projectDir);
+  const workstreamSummaries = new Map();
+  for (const [workstreamId, workstream] of workstreams.entries()) {
+    workstreamSummaries.set(workstreamId, {
+      workstream,
+      totalTaskCount: 0,
+      openTaskCount: 0
+    });
+  }
   const tasksDir = path.join(projectDir, "tasks");
   if (!existsSync(tasksDir)) continue;
 
@@ -52,6 +63,12 @@ for (const projectDir of listDirectories(projectsRoot)) {
     totalTaskCount += 1;
     if (!isClosedTaskStatus(status)) openTaskCount += 1;
     if (isProgressedTaskStatus(status)) progressedTaskCount += 1;
+    const taskWorkstream = frontmatter.workstream || "";
+    if (taskWorkstream && workstreamSummaries.has(taskWorkstream)) {
+      const summary = workstreamSummaries.get(taskWorkstream);
+      summary.totalTaskCount += 1;
+      if (!isClosedTaskStatus(status)) summary.openTaskCount += 1;
+    }
     tasks.set(id, { file: taskFile, frontmatter });
   }
 
@@ -69,6 +86,18 @@ for (const projectDir of listDirectories(projectsRoot)) {
   for (const [taskId, task] of tasks.entries()) {
     const status = task.frontmatter.status || "";
     const dependencies = parseList(task.frontmatter.depends_on || "[]");
+    const taskWorkstream = task.frontmatter.workstream || "";
+    const workstream = taskWorkstream ? workstreams.get(taskWorkstream) : null;
+
+    if (isProgressedTaskStatus(status)) {
+      if (!taskWorkstream) {
+        errors.push(`${toRepoPath(task.file)} has status ${status} but is missing workstream frontmatter; expected an existing workstream id.`);
+      } else if (!workstream) {
+        errors.push(`${toRepoPath(task.file)} has status ${status} but workstream ${taskWorkstream} does not exist; expected an existing workstream id.`);
+      } else {
+        validateTaskWorkstreamLifecycle({ task, workstream });
+      }
+    }
 
     if (["ready", "in-progress", "done"].includes(status)) {
       for (const dependencyId of dependencies) {
@@ -90,6 +119,10 @@ for (const projectDir of listDirectories(projectsRoot)) {
       }
     }
   }
+
+  for (const summary of workstreamSummaries.values()) {
+    validateWorkstreamLifecycle(summary);
+  }
 }
 
 finish();
@@ -105,7 +138,8 @@ function parseTransitionArgs(args) {
   const blockedCheckBack = valueAfter(args, "--blocked-check-back");
   const specStatus = valueAfter(args, "--spec-status");
   const planStatus = valueAfter(args, "--plan-status");
-  return { nextStatus, dependencyStatuses, blockedOwner, blockedCheckBack, specStatus, planStatus };
+  const workstreamStatus = valueAfter(args, "--workstream-status");
+  return { nextStatus, dependencyStatuses, blockedOwner, blockedCheckBack, specStatus, planStatus, workstreamStatus };
 }
 
 function validateTransitionRequest(request) {
@@ -124,6 +158,12 @@ function validateTransitionRequest(request) {
     if (request.planStatus && !isActiveOrClosedPlanStatus(request.planStatus)) {
       errors.push(`cannot transition to ${request.nextStatus} while plan status is ${request.planStatus}; expected active or done`);
     }
+    if (request.nextStatus === "in-progress" && request.workstreamStatus && !isActiveWorkstreamStatus(request.workstreamStatus)) {
+      errors.push(`cannot transition to in-progress while workstream status is ${request.workstreamStatus}; expected active`);
+    }
+    if (request.nextStatus === "done" && request.workstreamStatus && !isActiveOrClosedWorkstreamStatus(request.workstreamStatus)) {
+      errors.push(`cannot transition to done while workstream status is ${request.workstreamStatus}; expected active or done`);
+    }
   }
 
   if (request.nextStatus === "blocked") {
@@ -153,6 +193,24 @@ function validateProjectLifecycle(request) {
   }
 }
 
+function validateTaskWorkstreamLifecycle({ task, workstream }) {
+  const status = task.frontmatter.status || "";
+  const workstreamStatus = workstream.frontmatter.status || "";
+  if (status === "in-progress" && !isActiveWorkstreamStatus(workstreamStatus)) {
+    errors.push(`${toRepoPath(task.file)} has status in-progress but workstream ${workstream.id} status is ${describeStatus(workstreamStatus)}; expected active.`);
+  }
+  if (status === "done" && !isActiveOrClosedWorkstreamStatus(workstreamStatus)) {
+    errors.push(`${toRepoPath(task.file)} has status done but workstream ${workstream.id} status is ${describeStatus(workstreamStatus)}; expected active or done.`);
+  }
+}
+
+function validateWorkstreamLifecycle({ workstream, totalTaskCount, openTaskCount }) {
+  const workstreamStatus = workstream.frontmatter.status || "";
+  if (totalTaskCount > 0 && openTaskCount === 0 && !isClosedWorkstreamStatus(workstreamStatus)) {
+    errors.push(`${toRepoPath(workstream.file)} has no open tasks but status is ${describeStatus(workstreamStatus)}; expected done or deferred.`);
+  }
+}
+
 function isProgressedTaskStatus(status) {
   return ["in-progress", "done"].includes(status);
 }
@@ -177,6 +235,18 @@ function isClosedPlanStatus(status) {
   return ["done", "deferred"].includes(status);
 }
 
+function isActiveWorkstreamStatus(status) {
+  return status === "active";
+}
+
+function isActiveOrClosedWorkstreamStatus(status) {
+  return ["active", "done"].includes(status);
+}
+
+function isClosedWorkstreamStatus(status) {
+  return ["done", "deferred"].includes(status);
+}
+
 function describeStatus(status) {
   return status || "missing status";
 }
@@ -244,6 +314,17 @@ function listMarkdownFiles(root) {
     .map((entry) => path.join(root, entry.name));
 }
 
+function collectWorkstreams(projectDir) {
+  const workstreamsDir = path.join(projectDir, "workstreams");
+  const workstreams = new Map();
+  for (const workstreamFile of listMarkdownFiles(workstreamsDir)) {
+    const frontmatter = parseFrontmatter(workstreamFile);
+    const id = frontmatter.id || path.basename(workstreamFile, ".md").match(/^(WS-[A-Za-z0-9]+)/)?.[1] || "";
+    if (id) workstreams.set(id, { id, file: workstreamFile, frontmatter });
+  }
+  return workstreams;
+}
+
 function resolveRepoRoot(startDir) {
   const candidates = [path.resolve(startDir, ".."), path.resolve(startDir, "..", "..")];
   for (const candidate of candidates) {