@basementuniverse/kanbn 1.0.0 → 1.1.0

package/skills/kanbn-plan/references/task-structure.md

@@ -0,0 +1,143 @@
+# Kanbn Task Reference
+
+This reference describes the structure expected for task files in `.kanbn/tasks/`.
+
+## Minimum Valid Shape
+
+```markdown
+# Define authentication flow
+
+Describe the scope of the task, the decisions to make, and the expected output.
+
+## Sub-tasks
+
+- [ ] Review requirements
+- [ ] Document the proposed flow
+
+## Relations
+
+- [depends-on gather-auth-requirements](gather-auth-requirements.md)
+```
+
+## With Metadata
+
+```markdown
+---
+tags:
+  - Auth
+  - Planning
+due: 2026-08-01T00:00:00.000Z
+---
+
+# Define authentication flow
+
+Describe the scope of the task, the constraints, and the deliverable.
+
+## Sub-tasks
+
+- [ ] Map user journeys
+- [ ] Compare session and token approaches
+- [ ] Document recommendation
+
+## Relations
+
+- [depends-on gather-auth-requirements](gather-auth-requirements.md)
+- [blocks design-login-ui](design-login-ui.md)
+```
+
+## Rules
+
+- File name: `<task-id>.md`
+- File path: `.kanbn/tasks/<task-id>.md`
+- The first level-1 heading is the task name.
+- Content below the title is the task description.
+- Reserved level-2 headings are:
+  - `Metadata`
+  - `Sub-tasks`
+  - `Relations`
+  - `Comments`
+  - `History`
+
+Other headings are allowed inside the description, but use them sparingly.
+
+## Description Guidance
+
+Good task descriptions usually cover:
+
+- what needs to be planned, decided, designed, or documented
+- what is explicitly in scope
+- what is out of scope when that boundary matters
+- what output should exist when the task is complete
+
+Useful patterns:
+
+```markdown
+# Plan deployment strategy
+
+Define how the application will be deployed across environments.
+
+## Deliverables
+
+- Deployment approach for development, staging, and production
+- Rollback approach
+- Infrastructure assumptions
+
+## Acceptance Criteria
+
+- Target environments are named
+- Release path is documented
+- Rollback constraints are captured
+```
+
+## Metadata Guidance
+
+Prefer omission over invention.
+
+Usually omit:
+
+- `created`
+- `updated`
+- `started`
+- `completed`
+- `progress`
+- `assigned`
+- `comments`
+- `history`
+
+Add metadata only when the user supplied it or when the board already relies on it.
+
+Good uses of metadata:
+
+- `tags` for epics, teams, domains, or sizing labels
+- `due` for explicit deadlines
+- custom fields already defined by the existing board
+
+## Relations Guidance
+
+Relation entries use markdown links.
+
+Examples:
+
+```markdown
+## Relations
+
+- [depends-on plan-data-model](plan-data-model.md)
+- [blocks define-api-contract](define-api-contract.md)
+- [duplicates old-auth-plan](old-auth-plan.md)
+```
+
+Semantics:
+
+- `depends-on X`: this task waits for `X`
+- `blocks X`: this task is a prerequisite for `X`
+- `duplicates` and similar non-dependency relations are informational only
+
+Do not add both `depends-on X` and the mirrored inverse on the same task unless the user wants that phrasing explicitly.
+
+## Common Mistakes
+
+- Mismatching the file name and referenced task id.
+- Using plain text instead of a markdown link in `## Relations`.
+- Inventing timestamps, progress, or comments.
+- Writing a task name that is too broad to act on.
+- Creating a relation to a task file that does not exist.

package/skills/kanbn-plan/scripts/check-dependency-cycles.mjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import process from 'process';
+
+function usage() {
+  console.error('Usage: node skills/kanbn-plan/scripts/check-dependency-cycles.mjs [project-root] [--json]');
+}
+
+function parseArgs(argv) {
+  let projectRoot = process.cwd();
+  let json = false;
+
+  for (const arg of argv) {
+    if (arg === '--json') {
+      json = true;
+      continue;
+    }
+
+    if (arg.startsWith('-')) {
+      usage();
+      process.exit(1);
+    }
+
+    if (projectRoot !== process.cwd()) {
+      usage();
+      process.exit(1);
+    }
+
+    projectRoot = arg;
+  }
+
+  return {
+    json,
+    projectRoot: path.resolve(projectRoot)
+  };
+}
+
+function ensureKanbnFiles(projectRoot) {
+  const tasksPath = path.join(projectRoot, '.kanbn', 'tasks');
+  if (!fs.existsSync(tasksPath)) {
+    throw new Error(`No Kanbn tasks directory found at ${tasksPath}`);
+  }
+  return tasksPath;
+}
+
+function normaliseRelationType(type) {
+  return String(type || '').trim().toLowerCase();
+}
+
+function getTaskIdFromHref(href) {
+  const fileName = path.basename(String(href || '').trim());
+  return fileName.endsWith('.md') ? fileName.slice(0, -3) : fileName;
+}
+
+function extractRelationsSection(markdown) {
+  const lines = markdown.split(/\r?\n/);
+  const sectionLines = [];
+  let inSection = false;
+
+  for (const line of lines) {
+    if (/^##\s+Relations\s*$/.test(line.trim())) {
+      inSection = true;
+      continue;
+    }
+
+    if (inSection && /^##\s+/.test(line.trim())) {
+      break;
+    }
+
+    if (inSection) {
+      sectionLines.push(line);
+    }
+  }
+
+  return sectionLines.join('\n').trim();
+}
+
+function parseRelations(markdown) {
+  const section = extractRelationsSection(markdown);
+  if (!section) {
+    return [];
+  }
+
+  const relations = [];
+  const lines = section.split(/\r?\n/);
+  const relationPattern = /^-\s+\[([^\]]+)\]\(([^)]+)\)\s*$/;
+
+  for (const line of lines) {
+    const match = line.trim().match(relationPattern);
+    if (!match) {
+      continue;
+    }
+
+    const text = match[1].trim();
+    const href = match[2].trim();
+    const targetTaskId = getTaskIdFromHref(href);
+    const relationType = text.endsWith(targetTaskId)
+      ? text.slice(0, text.length - targetTaskId.length).trim()
+      : text;
+
+    relations.push({
+      task: targetTaskId,
+      type: normaliseRelationType(relationType)
+    });
+  }
+
+  return relations;
+}
+
+function loadTasks(tasksPath) {
+  const tasks = new Map();
+
+  for (const entry of fs.readdirSync(tasksPath, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) {
+      continue;
+    }
+
+    const taskId = entry.name.slice(0, -3);
+    const markdown = fs.readFileSync(path.join(tasksPath, entry.name), 'utf8');
+    tasks.set(taskId, {
+      id: taskId,
+      relations: parseRelations(markdown)
+    });
+  }
+
+  return tasks;
+}
+
+function buildDependencyGraph(tasks) {
+  const graph = new Map();
+  const danglingReferences = [];
+
+  for (const taskId of tasks.keys()) {
+    graph.set(taskId, new Set());
+  }
+
+  for (const [taskId, task] of tasks.entries()) {
+    for (const relation of task.relations) {
+      if (!relation.task) {
+        continue;
+      }
+
+      let fromId = null;
+      let toId = null;
+
+      if (relation.type === 'depends-on') {
+        fromId = relation.task;
+        toId = taskId;
+      } else if (relation.type === 'blocks') {
+        fromId = taskId;
+        toId = relation.task;
+      } else {
+        continue;
+      }
+
+      if (!tasks.has(fromId) || !tasks.has(toId)) {
+        danglingReferences.push({
+          from: taskId,
+          relationType: relation.type,
+          target: relation.task
+        });
+        continue;
+      }
+
+      graph.get(fromId).add(toId);
+    }
+  }
+
+  return { danglingReferences, graph };
+}
+
+function findCycles(graph) {
+  const visited = new Set();
+  const visiting = new Set();
+  const stack = [];
+  const cycles = [];
+  const seenCycleKeys = new Set();
+
+  function recordCycle(startNode) {
+    const startIndex = stack.indexOf(startNode);
+    if (startIndex === -1) {
+      return;
+    }
+
+    const cycle = stack.slice(startIndex).concat(startNode);
+    const uniqueNodes = cycle.slice(0, -1);
+    const canonicalStart = [...uniqueNodes].sort()[0];
+    const canonicalIndex = uniqueNodes.indexOf(canonicalStart);
+    const rotated = uniqueNodes.slice(canonicalIndex).concat(uniqueNodes.slice(0, canonicalIndex));
+    const cycleKey = rotated.join('>');
+
+    if (!seenCycleKeys.has(cycleKey)) {
+      seenCycleKeys.add(cycleKey);
+      cycles.push(rotated.concat(rotated[0]));
+    }
+  }
+
+  function visit(node) {
+    visited.add(node);
+    visiting.add(node);
+    stack.push(node);
+
+    for (const nextNode of graph.get(node) || []) {
+      if (!visited.has(nextNode)) {
+        visit(nextNode);
+      } else if (visiting.has(nextNode)) {
+        recordCycle(nextNode);
+      }
+    }
+
+    stack.pop();
+    visiting.delete(node);
+  }
+
+  for (const node of graph.keys()) {
+    if (!visited.has(node)) {
+      visit(node);
+    }
+  }
+
+  return cycles;
+}
+
+function printTextReport(result) {
+  if (result.danglingReferences.length > 0) {
+    console.error(`Dangling dependency references: ${result.danglingReferences.length}`);
+    for (const reference of result.danglingReferences) {
+      console.error(`- ${reference.from}: ${reference.relationType} ${reference.target}`);
+    }
+  }
+
+  if (result.cycles.length > 0) {
+    console.error(`Dependency cycles detected: ${result.cycles.length}`);
+    for (const cycle of result.cycles) {
+      console.error(`- ${cycle.join(' -> ')}`);
+    }
+  }
+
+  if (result.danglingReferences.length === 0 && result.cycles.length === 0) {
+    console.log('No dependency cycles or dangling dependency references found');
+  }
+}
+
+function main() {
+  const { json, projectRoot } = parseArgs(process.argv.slice(2));
+
+  let tasksPath;
+  try {
+    tasksPath = ensureKanbnFiles(projectRoot);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+
+  const tasks = loadTasks(tasksPath);
+  const { graph, danglingReferences } = buildDependencyGraph(tasks);
+  const cycles = findCycles(graph);
+  const result = { cycles, danglingReferences };
+
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printTextReport(result);
+  }
+
+  if (cycles.length > 0 || danglingReferences.length > 0) {
+    process.exit(1);
+  }
+}
+
+main();

package/skills/kanbn-plan/scripts/validate-kanbn.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import process from 'process';
+import { spawnSync } from 'child_process';
+
+function usage() {
+  console.error('Usage: node skills/kanbn-plan/scripts/validate-kanbn.mjs [project-root]');
+}
+
+function resolveProjectRoot(argv) {
+  if (argv.length > 1) {
+    usage();
+    process.exit(1);
+  }
+
+  return path.resolve(argv[0] || process.cwd());
+}
+
+function ensureKanbnFiles(projectRoot) {
+  const indexPath = path.join(projectRoot, '.kanbn', 'index.md');
+  const tasksPath = path.join(projectRoot, '.kanbn', 'tasks');
+
+  if (!fs.existsSync(indexPath)) {
+    console.error(`No Kanbn index found at ${indexPath}`);
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(tasksPath)) {
+    console.error(`No Kanbn tasks directory found at ${tasksPath}`);
+    process.exit(1);
+  }
+}
+
+function getCandidates(projectRoot) {
+  const candidates = [];
+  const localBin = path.join(projectRoot, 'node_modules', '.bin', 'kanbn');
+
+  if (process.env.KANBN_BIN) {
+    candidates.push({ command: process.env.KANBN_BIN, args: [], label: process.env.KANBN_BIN });
+  }
+
+  if (fs.existsSync(localBin)) {
+    candidates.push({ command: localBin, args: [], label: localBin });
+  }
+
+  candidates.push({ command: 'kanbn', args: [], label: 'kanbn' });
+  candidates.push({ command: 'npx', args: ['-y', '@basementuniverse/kanbn'], label: 'npx -y @basementuniverse/kanbn' });
+
+  return candidates;
+}
+
+function runValidate(projectRoot) {
+  const candidates = getCandidates(projectRoot);
+  let lastError = null;
+
+  for (const candidate of candidates) {
+    const result = spawnSync(
+      candidate.command,
+      [...candidate.args, 'validate', '--json'],
+      {
+        cwd: projectRoot,
+        encoding: 'utf8'
+      }
+    );
+
+    if (result.error && result.error.code === 'ENOENT') {
+      lastError = result.error;
+      continue;
+    }
+
+    return { candidate, result };
+  }
+
+  throw lastError || new Error('Unable to locate a runnable Kanbn CLI');
+}
+
+function extractValidationErrors(output) {
+  const start = output.indexOf('[');
+  const end = output.lastIndexOf(']');
+
+  if (start === -1 || end === -1 || end < start) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(output.slice(start, end + 1));
+  } catch (error) {
+    return null;
+  }
+}
+
+function main() {
+  const projectRoot = resolveProjectRoot(process.argv.slice(2));
+  ensureKanbnFiles(projectRoot);
+
+  let execution;
+  try {
+    execution = runValidate(projectRoot);
+  } catch (error) {
+    console.error(`Unable to run Kanbn validation: ${error.message}`);
+    process.exit(1);
+  }
+
+  const { candidate, result } = execution;
+  const combinedOutput = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+
+  if (result.status === 0) {
+    if (combinedOutput) {
+      console.log(combinedOutput);
+    } else {
+      console.log(`Kanbn validation passed via ${candidate.label}`);
+    }
+    return;
+  }
+
+  const errors = extractValidationErrors(combinedOutput);
+  if (errors) {
+    console.error(`Kanbn validation reported ${errors.length} error(s) via ${candidate.label}:`);
+    for (const error of errors) {
+      if (error && typeof error === 'object') {
+        console.error(JSON.stringify(error, null, 2));
+      } else {
+        console.error(String(error));
+      }
+    }
+    process.exit(1);
+  }
+
+  console.error(combinedOutput || `Kanbn validation failed via ${candidate.label}`);
+  process.exit(result.status || 1);
+}
+
+main();

package/skills/kanbn-replan/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: kanbn-replan
+description: Recalculate unfinished Kanbn task dates from the current project state, preserving completed tasks and writing updated scheduled dates back to existing task markdown files.
+---
+
+# Kanbn Replan
+
+Use this skill when a Kanbn board needs to be rescheduled after time has passed, work was paused, or the current Gantt chart shows that unfinished work no longer fits the available timeline.
+
+Do not use this skill to redesign scope, rewrite completed tasks, or invent new task structure. Keep the workflow focused on rescheduling existing incomplete work.
+
+## Core Contract
+
+Your output must stay inside the Kanbn task surface:
+
+- `.kanbn/index.md`
+- `.kanbn/tasks/*.md`
+
+You may read the current board and gantt output, but the end result should be a revised schedule for existing tasks, not a new plan.
+
+Do not modify completed tasks unless the user explicitly asks to reopen them. Leave completed task descriptions, relations, and completion history intact.
+
+## When to Use
+
+Use this skill when the user wants to:
+
+- move overdue work forward to a realistic schedule
+- reschedule unfinished tasks after a long interruption
+- spread work out to reduce overload
+- refresh `started`, `plannedStart`, `plannedFinish`, and `due` dates for incomplete tasks
+- inspect Gantt output and derive a revised schedule from it
+
+## Workflow
+
+### 1. Inspect the current board state
+
+Gather the current planning context before making edits:
+
+- current date
+- tracked tasks and their columns
+- task metadata relevant to scheduling (`started`, `plannedStart`, `plannedFinish`, `due`, `progress`, workload tags)
+- dependency relations
+- the current Gantt layout
+
+Prefer `kanbn gantt -j` for the machine-readable schedule. If the replanning should be anchored to a specific point in time, pass `--now "date"` so the schedule is evaluated against the intended date.
+
+### 2. Decide what is in scope
+
+Reschedule only incomplete work.
+
+Treat these as locked unless the user says otherwise:
+
+- tasks marked complete
+- completed subtasks that should remain completed
+- task names, descriptions, comments, and history
+- dependency structure, unless the task graph itself is wrong and must be repaired to make the schedule valid
+
+If a task is incomplete but already in progress, preserve evidence of work where that matters. Prefer updating scheduling metadata over rewriting task content.
+
+### 3. Rebuild the schedule
+
+Use the gantt data and dependency order to decide new dates.
+
+General rules:
+
+- dependency order wins over wishful dates
+- `plannedStart` should be the earliest preferred start floor when present
+- `plannedFinish` should be the preferred finish target when present
+- `started` should reflect when work actually begins or resumes
+- `due` should reflect the target finish date for the current schedule
+- if a task would otherwise overlap too much with adjacent work, shift it later rather than ignoring the overload
+- if the user has returned after a long gap, treat incomplete tasks as candidates for re-baselining from the current date forward
+
+When task size information is available, use it to distribute work more realistically. If exact sizing is missing, use the gantt layout, task relations, and existing metadata as the primary signals.
+
+If `kanbn gantt -j` reports dependency cycles, stop and resolve or report them before rescheduling dependent tasks.
+
+### 4. Edit task files directly
+
+Update the existing `.kanbn/tasks/*.md` files rather than creating a new board.
+
+Prefer minimal metadata changes:
+
+- keep task titles and descriptions stable
+- update only the date fields needed to express the new plan
+- preserve completed tasks exactly as they are
+- avoid changing `created`, `completed`, comments, or history unless the user explicitly asks
+
+If the task file format uses front matter or a `Metadata` section, keep it valid and consistent with the repo docs.
+
+### 5. Verify the result
+
+After editing, validate the board:
+
+1. Run `kanbn validate`
+2. Re-run `kanbn gantt -j` to confirm the new dates produce a coherent schedule
+3. Check for obvious dependency or date regressions
+4. Fix any malformed task files before stopping
+
+## Scheduling Heuristics
+
+Use these heuristics when the user has not specified a custom policy:
+
+- keep completed tasks unchanged
+- schedule tasks in dependency order
+- move overdue unfinished tasks forward if they cannot realistically finish on their original due dates
+- avoid piling every incomplete task onto the earliest possible date
+- keep `due` dates aligned with the revised execution window
+- if a task has no meaningful `started` date yet, set it when work is planned to resume rather than inventing a long-past start
+- use workload tags and any existing custom scheduling fields as additional inputs when the board defines them
+
+## References
+
+Use the repo docs as the source of truth for the data model and commands:
+
+- `docs/commands/gantt.txt`
+- `docs/commands/edit.txt`
+- `docs/commands/validate.txt`
+- `docs/task-structure.md`
+- `docs/index-structure.md`
+