@jakkrichm/create-nexus-devflow 2.11.0 → 2.12.0

package/template/.agents/skills/doctor/SKILL.md

@@ -1,20 +1,23 @@
 ---
 name: doctor
-description: "[devflow] Run a read-only DevFlow health and context check covering setup, adapters, commands, visibility, plans, overview freshness, configuration, and workflow drift. Use for /doctor, setup problems, context overhead, or health checks."
+description: "[devflow] Run a DevFlow health and context check covering setup, adapters, commands, visibility, plans, overview freshness, configuration, dashboard state, and workflow drift. May offer to reset malformed generated dashboard state after approval. Use for /doctor, setup problems, context overhead, or health checks."
 ---
 
-# doctor - Blueprint health check
+# doctor - DevFlow health check
+
+**Context reuse:** Reuse any required file already loaded in project instructions or the current session. Read it again only if absent, changed, or exact current bytes or line references are needed.
 
 Where this sits in the workflow:
 
     any time  ->  [doctor]  ->  reads setup + plans + workflow state + git
-                  (read-only)   prints health, warnings, and repair order
+                  (diagnostic)  prints health, warnings, and repair order
 
-This skill answers one question: *is this Blueprint project ready to use?* It is
+This skill answers one question: *is this DevFlow project ready to use?* It is
 the diagnostic pass for setup drift, incomplete onboarding, missing files,
-placeholder plans, stale generated context, Blueprint visibility, and confusing
+placeholder plans, stale generated context, DevFlow visibility, and confusing
 workflow state. It never changes anything: no edits, no commits, no installs, no
-builds, no branch changes.
+builds, no branch changes. Its only repair is an approved reset of a malformed
+generated `devflow/.state/run.json` file.
 
 Use `/status` when the user mainly wants progress and the next build action. Use
 `/doctor` when the user wants to know whether the workflow itself is healthy.
@@ -66,6 +69,10 @@ Gather these, then summarize. Do not dump file contents.
      logical adapters: Codex, Claude Code, GitHub Copilot, Antigravity, and OpenCode.
    - Confirm at least one compatible skill tree exists. Codex, Antigravity, and
      GitHub Copilot use `.agents/skills/`. Claude Code uses `.claude/skills/`.
+   - Confirm each installed adapter tree contains
+     `doctor/scripts/run-state.mjs`. This managed helper validates and atomically
+     writes dashboard activity. A missing helper needs a DevFlow update before
+     tracked commands can record activity safely.
    - If both skill trees are present, say that is healthy when the selected
      tools require both. Compare their skill folder names and warn about missing
      skills on either side.
@@ -105,39 +112,41 @@ Gather these, then summarize. Do not dump file contents.
    - A missing `Verify` command or GitHub workflow is informational. It means the
      optional automatic-check setup was not selected, not that DevFlow is
      unhealthy.
-4. **Ignore rules**
-   - Check obvious ignore patterns for the detected stack. For Node or Astro,
-     look for `node_modules`, `.env`, `dist`, and framework cache folders such as
-     `.astro` or `.next` when relevant.
-   - Detect local-only DevFlow mode if `.gitignore` ignores `.agents/`,
-     `.claude/`, `devflow/`, or `CLAUDE.md`. Report it as a visibility choice,
-     not a failure, when the local files exist.
-   - In local-only mode, check whether tracked `AGENTS.md` still describes the
-     Blueprint workflow, lists hidden adapter paths, or exposes the core skill
-     list. If so, warn that `/onboard` should make `AGENTS.md` public-safe.
-   - If local-only mode is active but those paths are already tracked by git,
-     warn that `.gitignore` does not hide tracked files and the user must approve
-     any `git rm --cached` cleanup separately.
-   - Keep this conservative. If uncertain, report "review" instead of failure.
-5. **Planning readiness**
-   - Check whether `devflow/project-plan.md` and `devflow/build-plan.md` look
-     filled in or still template-like. Treat obvious TODO, TBD, example-only text,
-     or empty required sections as not ready.
-   - Check whether `devflow/build-plan.md` is a numbered checkbox list. Raw
-     bullets are allowed as a first draft, but they should be normalized by
-     `/overview` before the build loop starts.
-   - Count checked and unchecked leaf items in `devflow/build-plan.md`.
-6. **Overview freshness**
-   - Check whether `devflow/context/project-overview.md` exists and looks
-     generated from the current plans.
+4. **Visibility and context loading**
+   - Confirm whether DevFlow files are public in git or listed in `.gitignore`
+     as local-only.
+   - When Claude Code is installed, report its startup-context shape. Confirm
+     `CLAUDE.md` imports `AGENTS.md` and lets skills load planning context on demand.
+5. **Project and build plans**
+   - Read `devflow/project-plan.md` and `devflow/build-plan.md`.
+   - Report total features in the build plan, how many are checked off (`- [x]`),
+     and which feature is next.
+   - Flag placeholder text (e.g. `[Your project name]`, `Feature 1 description`).
+6. **Project overview freshness**
+   - Read `devflow/context/project-overview.md` if it exists.
    - Report its byte size. At or above 20,000 bytes, call it oversized and say
      `/feature` should stop until `/overview` regenerates a compact
      consolidation.
    - If either planning file appears newer than the overview by filesystem time,
      call the overview possibly stale and suggest `/overview` before feature work.
 7. **Current workflow state**
-   - Scan `devflow/context/{xxx-slug}/` for active task directories and specs.
-   - If a spec is active, report checked and unchecked implementation steps.
+   - Inspect `devflow/.state/run.json` when it exists. Missing means no recorded
+     activity and is healthy. Require a regular non-symbolic-link JSON file that
+     matches dashboard schema version 1 from `AGENTS.md`.
+   - If the path is a symbolic link or not a regular file, do not read, replace,
+     or remove it. Report the exact path for manual review.
+   - If the regular file is invalid JSON or does not match the schema, report it
+     as malformed generated state. Explain that resetting it removes only the
+     dashboard's last-command record, not project work, and that the next tracked
+     DevFlow command recreates it.
+   - Offer this exact repair question: `Reset the malformed dashboard state now?`
+     On approval, use the installed dashboard activity helper's `reset` action.
+     It confirms the exact path is a regular non-symbolic-link file and removes
+     only `devflow/.state/run.json`. Verify the file is absent and report the
+     dashboard state as reset. Never remove `devflow/.state/`, its manifest,
+     backups, or any project file. Without approval, leave it unchanged and
+     include the reset in `Repair order:`.
+   - If a spec is active in `devflow/context/{xxx-slug}/`, report checked and unchecked implementation steps.
    - If no active task directory exists in `devflow/context/` but git has source or workflow
      changes, warn that work is happening without an active spec.
    - Flag active spec on `main`, all spec steps checked but no completion, or a
@@ -168,28 +177,20 @@ steps, in order. Keep it short and practical.
 
 Choose the repair order in this priority:
 
-- Required Blueprint files missing -> overlay the Blueprint again, or use
-  `/adopt` for a brownfield app.
+- Required DevFlow files missing -> overlay DevFlow again, or use `/adopt` for a brownfield app.
 - No git repo -> initialize git before using the build loop.
 - No tool adapter -> restore `.agents/skills/` or `.claude/skills/` for the
   selected tool. OpenCode can use either compatible tree.
+- Installed adapter is missing `doctor/scripts/run-state.mjs` -> update
+  DevFlow before relying on dashboard activity.
 - Onboarding incomplete -> run `/onboard`.
-- Root README is still the Blueprint workflow doc -> run `/onboard` to replace
+- Root README is still the DevFlow workflow doc -> run `/onboard` to replace
   it with a project README before publishing.
-- Local-only visibility selected but ignored Blueprint files are missing ->
-  reinstall or restore the Blueprint files locally.
-- Local-only visibility selected but Blueprint paths are tracked -> ask whether
-  to untrack them with `git rm --cached` while keeping local files.
-- Local-only visibility selected but `AGENTS.md` still exposes the workflow ->
-  run `/onboard` to make `AGENTS.md` a lightweight public project guide.
-- A documented `Verify` command, project script, and GitHub workflow disagree ->
-  run `/ci` to review and align them. Missing optional CI alone does not need
-  repair.
-- Commands or ignore rules need review -> update the files or run `/onboard` if
-  this is an early project.
 - Plans are placeholders -> fill `devflow/project-plan.md` and
   `devflow/build-plan.md`.
 - Overview missing or stale -> run `/overview`.
+- Malformed regular `devflow/.state/run.json` -> offer to reset that exact
+  generated file, then rerun `/doctor` or refresh the dashboard.
 - Active spec has unchecked steps -> run `/status` or `/implement`, depending on
   whether the user wants orientation or action.
 - A P0 or P1 finding is `open` -> repair it through `/implement` while a spec
@@ -201,8 +202,10 @@ Choose the repair order in this priority:
 
 ## Rules
 
-- **Read-only, always.** This skill never writes files, never commits, never runs
-  installs, never runs builds or tests, and never switches branches.
+- **Diagnostic by default.** This skill never edits project files, commits, runs
+  installs, runs builds or tests, or switches branches. It may remove only a
+  malformed regular `devflow/.state/run.json` through the installed helper
+  after the user approves the exact reset described above.
 - **Diagnose, then order repairs.** Do not just list problems. End with the
   smallest ordered sequence that gets the project back to a healthy state.
 - **Do not over-police adapters.** Extra adapters are optional clutter, not a

package/template/.agents/skills/doctor/scripts/run-state.mjs

@@ -0,0 +1,513 @@
+#!/usr/bin/env node
+
+// Standalone ESM because installed projects may use CommonJS.
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const ACTIONS = new Set(["start", "update", "finish", "reset"]);
+const BOUNDARIES = new Set(["read-only", "reviewed", "local-only"]);
+const COMMAND_PATTERN = /^[a-z][a-z-]{0,31}$/;
+const RUN_PATH = path.join("devflow", ".state", "run.json");
+const STATUSES = new Set(["running", "blocked", "ready", "completed"]);
+const MAX_LENGTHS = {
+  detail: 1000,
+  featureId: 80,
+  featureTitle: 160,
+  progressLabel: 80,
+  resumeCommand: 240,
+  summary: 240
+};
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  const projectRoot = await findProjectRoot(options.target);
+
+  if (options.action === "reset") {
+    await resetState(projectRoot);
+    console.log("Dashboard activity reset.");
+    return;
+  }
+
+  const previous = options.action === "start"
+    ? null
+    : await readState(projectRoot);
+  const state = buildState(options, previous, new Date().toISOString());
+  await writeState(projectRoot, state);
+  console.log(`Recorded /${state.command}: ${state.status} - ${state.summary}`);
+}
+
+function parseArgs(args) {
+  const options = {
+    action: null,
+    boundary: null,
+    command: null,
+    current: null,
+    detail: null,
+    featureId: null,
+    featureTitle: null,
+    help: false,
+    label: null,
+    resumeCommand: null,
+    status: null,
+    summary: null,
+    target: null,
+    total: null
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (ACTIONS.has(arg)) {
+      if (options.action) {
+        throw new Error("Choose only one run-state action.");
+      }
+      options.action = arg;
+      continue;
+    }
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+    if (arg === "--command") {
+      options.command = readValue(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--summary") {
+      options.summary = readValue(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--detail") {
+      options.detail = readValue(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--boundary") {
+      options.boundary = readValue(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--status") {
+      options.status = readValue(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--resume") {
+      options.resumeCommand = readValue(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--feature-id") {
+      options.featureId = readValue(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--feature-title") {
+      options.featureTitle = readValue(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--current") {
+      options.current = readInteger(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--total") {
+      options.total = readInteger(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--label") {
+      options.label = readValue(args, ++index, arg);
+      continue;
+    }
+    if (arg === "--target" || arg === "-t") {
+      options.target = readValue(args, ++index, arg);
+      continue;
+    }
+
+    throw new Error(`Unknown run-state option: ${arg}`);
+  }
+
+  validateOptions(options);
+  return options;
+}
+
+function validateOptions(options) {
+  if (options.help) {
+    return;
+  }
+  if (!options.action) {
+    throw new Error("Choose one run-state action: start, update, finish, or reset.");
+  }
+
+  const progressCount = [options.current, options.total, options.label]
+    .filter((value) => value !== null).length;
+  if (progressCount !== 0 && progressCount !== 3) {
+    throw new Error("Progress requires --current, --total, and --label together.");
+  }
+  if (options.featureId && !options.featureTitle) {
+    throw new Error("--feature-id requires --feature-title.");
+  }
+
+  if (options.action === "reset") {
+    const unsupported = [
+      options.boundary,
+      options.command,
+      options.current,
+      options.detail,
+      options.featureId,
+      options.featureTitle,
+      options.label,
+      options.resumeCommand,
+      options.status,
+      options.summary,
+      options.total
+    ].some((value) => value !== null);
+    if (unsupported) {
+      throw new Error("Reset accepts only --target and --help.");
+    }
+    return;
+  }
+
+  if (options.action === "start") {
+    if (!options.command || !options.summary || !options.boundary) {
+      throw new Error("Start requires --command, --summary, and --boundary.");
+    }
+    if (options.status) {
+      throw new Error("Start always records running status.");
+    }
+    return;
+  }
+
+  if (options.command) {
+    throw new Error("Only start accepts --command.");
+  }
+  if (options.boundary) {
+    throw new Error("Only start accepts --boundary.");
+  }
+  if (options.action === "finish") {
+    if (options.status && !["ready", "completed"].includes(options.status)) {
+      throw new Error("Finish status must be ready or completed.");
+    }
+    return;
+  }
+  if (options.status && !["running", "blocked", "ready"].includes(options.status)) {
+    throw new Error("Update status must be running, blocked, or ready.");
+  }
+
+  const hasUpdate = [
+    options.current,
+    options.detail,
+    options.featureTitle,
+    options.resumeCommand,
+    options.status,
+    options.summary
+  ].some((value) => value !== null);
+  if (!hasUpdate) {
+    throw new Error("Update needs at least one changed activity field.");
+  }
+}
+
+function buildState(options, previous, timestamp) {
+  if (options.action === "start") {
+    const state = {
+      schemaVersion: 1,
+      command: requireText(options.command, "command", 32),
+      status: "running",
+      summary: requireText(options.summary, "summary", MAX_LENGTHS.summary),
+      boundary: requireBoundary(options.boundary),
+      startedAt: timestamp,
+      updatedAt: timestamp
+    };
+    applyOptionalFields(state, options);
+    return validateState(state);
+  }
+
+  const state = {
+    ...previous,
+    status: options.action === "finish"
+      ? options.status || "completed"
+      : options.status || previous.status,
+    summary: options.summary
+      ? requireText(options.summary, "summary", MAX_LENGTHS.summary)
+      : previous.summary,
+    updatedAt: timestamp
+  };
+  applyOptionalFields(state, options);
+
+  if (
+    options.action === "finish" ||
+    (previous.status === "blocked" && state.status !== "blocked")
+  ) {
+    if (!options.resumeCommand) {
+      delete state.resumeCommand;
+    }
+    if (!options.detail) {
+      delete state.detail;
+    }
+  }
+
+  return validateState(state);
+}
+
+function applyOptionalFields(state, options) {
+  if (options.detail) {
+    state.detail = requireText(options.detail, "detail", MAX_LENGTHS.detail);
+  }
+  if (options.resumeCommand) {
+    state.resumeCommand = requireText(
+      options.resumeCommand,
+      "resume command",
+      MAX_LENGTHS.resumeCommand
+    );
+  }
+  if (options.current !== null) {
+    state.progress = validateProgress({
+      current: options.current,
+      total: options.total,
+      label: options.label
+    });
+  }
+  if (options.featureTitle) {
+    state.feature = {
+      id: options.featureId,
+      title: requireText(
+        options.featureTitle,
+        "feature title",
+        MAX_LENGTHS.featureTitle
+      )
+    };
+    if (state.feature.id !== null) {
+      state.feature.id = requireText(
+        state.feature.id,
+        "feature ID",
+        MAX_LENGTHS.featureId
+      );
+    }
+  }
+}
+
+function validateState(value) {
+  if (!isRecord(value)) {
+    throw new Error("Run state must be an object.");
+  }
+  if (
+    value.schemaVersion !== 1 ||
+    typeof value.command !== "string" ||
+    !COMMAND_PATTERN.test(value.command) ||
+    !STATUSES.has(value.status) ||
+    !isBoundedText(value.summary, MAX_LENGTHS.summary) ||
+    typeof value.startedAt !== "string" ||
+    typeof value.updatedAt !== "string" ||
+    Number.isNaN(Date.parse(value.startedAt)) ||
+    Number.isNaN(Date.parse(value.updatedAt)) ||
+    Date.parse(value.startedAt) > Date.parse(value.updatedAt) ||
+    (value.boundary !== undefined && !BOUNDARIES.has(value.boundary)) ||
+    (value.detail !== undefined && !isBoundedText(value.detail, MAX_LENGTHS.detail)) ||
+    (value.resumeCommand !== undefined &&
+      !isBoundedText(value.resumeCommand, MAX_LENGTHS.resumeCommand)) ||
+    (value.progress !== undefined && !isValidProgress(value.progress)) ||
+    (value.feature !== undefined && !isValidFeature(value.feature))
+  ) {
+    throw new Error("Run state does not match dashboard schema version 1.");
+  }
+
+  return value;
+}
+
+function validateProgress(progress) {
+  if (!isValidProgress(progress)) {
+    throw new Error(
+      "Progress requires integers where 0 <= current <= total and total >= 1."
+    );
+  }
+  return {
+    current: progress.current,
+    total: progress.total,
+    label: progress.label.trim()
+  };
+}
+
+function isValidProgress(value) {
+  return isRecord(value) &&
+    Number.isInteger(value.current) &&
+    Number.isInteger(value.total) &&
+    value.current >= 0 &&
+    value.total >= 1 &&
+    value.current <= value.total &&
+    isBoundedText(value.label, MAX_LENGTHS.progressLabel);
+}
+
+function isValidFeature(value) {
+  return isRecord(value) &&
+    (value.id === null || isBoundedText(value.id, MAX_LENGTHS.featureId)) &&
+    isBoundedText(value.title, MAX_LENGTHS.featureTitle);
+}
+
+async function findProjectRoot(target) {
+  let current = path.resolve(process.cwd(), target || ".");
+  const initial = await fs.lstat(current);
+  if (initial.isFile()) {
+    current = path.dirname(current);
+  }
+
+  while (true) {
+    const devflowPath = path.join(current, "devflow");
+    try {
+      const devflow = await fs.lstat(devflowPath);
+      if (devflow.isSymbolicLink() || !devflow.isDirectory()) {
+        throw new Error("DevFlow path must be a real directory.");
+      }
+      const statePath = path.join(devflowPath, ".state");
+      const state = await fs.lstat(statePath);
+      if (state.isSymbolicLink() || !state.isDirectory()) {
+        throw new Error("DevFlow state path must be a real directory.");
+      }
+      return current;
+    } catch (error) {
+      if (error?.code !== "ENOENT") {
+        throw error;
+      }
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      throw new Error("Could not find a DevFlow project with devflow/.state.");
+    }
+    current = parent;
+  }
+}
+
+async function readState(projectRoot) {
+  const filePath = path.join(projectRoot, RUN_PATH);
+  await requireRegularFile(filePath);
+
+  let parsed;
+  try {
+    parsed = JSON.parse(await fs.readFile(filePath, "utf8"));
+  } catch {
+    throw new Error("Existing dashboard state is malformed. Start a new run or use /doctor.");
+  }
+  return validateState(parsed);
+}
+
+async function writeState(projectRoot, state) {
+  const filePath = path.join(projectRoot, RUN_PATH);
+  await requireRegularOrMissing(filePath);
+  const temporaryPath = `${filePath}.${randomUUID()}.tmp`;
+
+  try {
+    await fs.writeFile(
+      temporaryPath,
+      `${JSON.stringify(validateState(state), null, 2)}\n`,
+      { encoding: "utf8", flag: "wx", mode: 0o600 }
+    );
+    await fs.rename(temporaryPath, filePath);
+    validateState(JSON.parse(await fs.readFile(filePath, "utf8")));
+  } catch (error) {
+    await fs.rm(temporaryPath, { force: true });
+    throw error;
+  }
+}
+
+async function resetState(projectRoot) {
+  const filePath = path.join(projectRoot, RUN_PATH);
+  try {
+    await requireRegularFile(filePath);
+    await fs.rm(filePath);
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+
+async function requireRegularFile(filePath) {
+  const stats = await fs.lstat(filePath);
+  if (stats.isSymbolicLink() || !stats.isFile()) {
+    throw new Error("Dashboard run state must be a regular file.");
+  }
+}
+
+async function requireRegularOrMissing(filePath) {
+  try {
+    await requireRegularFile(filePath);
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+
+function requireBoundary(value) {
+  if (!BOUNDARIES.has(value)) {
+    throw new Error("Boundary must be read-only, reviewed, or local-only.");
+  }
+  return value;
+}
+
+function requireText(value, label, maxLength) {
+  const normalized = value?.trim();
+  if (!normalized) {
+    throw new Error(`${label} is required.`);
+  }
+  if (normalized.length > maxLength) {
+    throw new Error(`${label} must be ${maxLength} characters or fewer.`);
+  }
+  return normalized;
+}
+
+function isBoundedText(value, maxLength) {
+  return typeof value === "string" &&
+    value.trim() !== "" &&
+    value.length <= maxLength;
+}
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readValue(args, index, flag) {
+  const value = args[index];
+  if (!value) {
+    throw new Error(`${flag} needs a value.`);
+  }
+  return value;
+}
+
+function readInteger(args, index, flag) {
+  const value = readValue(args, index, flag);
+  if (!/^\d+$/.test(value)) {
+    throw new Error(`${flag} needs a non-negative integer.`);
+  }
+  return Number(value);
+}
+
+function printHelp() {
+  console.log(`DevFlow dashboard activity helper
+
+Usage:
+  node <helper> start --command feature --summary "Specifying feature 3" --boundary reviewed
+  node <helper> update --status blocked --summary "A product decision is required" --resume "/feature 3"
+  node <helper> finish --status ready --summary "Feature specification ready"
+  node <helper> reset
+
+Options:
+  --command         DevFlow command name, required for start
+  --summary         Short activity summary
+  --detail          Concise safe detail
+  --boundary        read-only, reviewed, or local-only
+  --status          update: running, blocked, or ready; finish: ready or completed
+  --resume          Safe recovery command
+  --feature-id      Build-plan feature ID
+  --feature-title   Feature, fix, or rollback title
+  --current         Completed progress count
+  --total           Total progress count
+  --label           Progress unit label
+  --target, -t      Project directory, defaults to the current directory
+  --help, -h        Show help`);
+}
+
+main().catch((error) => {
+  console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+});

package/template/.agents/skills/feature/SKILL.md

@@ -6,6 +6,8 @@ argument-hint: "[{number, name, DISC-id, or IDEA-id}]"
 
 # feature - turn a build-plan feature into a buildable spec
 
+**Context reuse:** Reuse any required file already loaded in project instructions or the current session. Read it again only if absent, changed, or exact current bytes or line references are needed.
+
 **First action:** Before project inspection, preflight, or any other tool call,
 publish `running` to `devflow/.state/run.json` using the dashboard activity
 contract in `AGENTS.md`.