@basementuniverse/kanbn 1.0.0 → 1.0.1

package/README.md

@@ -34,6 +34,7 @@ Where <command> is one of:
   sort .......... Sort a column in the index
   sprint ........ Start a new sprint
   burndown ...... View a burndown chart
+  gantt ......... Generate and view a Gantt chart
   validate ...... Validate index and task files
   archive ....... Archive a task
   restore ....... Restore a task from the archive

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basementuniverse/kanbn",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A CLI Kanban application",
   "main": "index.js",
   "scripts": {

package/skills/kanbn-plan/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: kanbn-plan
+description: Turn a project brief into Kanbn planning artifacts only. Use this skill to generate or revise a Kanbn board index and task markdown files, including task descriptions, sub-tasks, and dependency relationships, without implementing the project itself.
+---
+
+# Kanbn Plan
+
+Use this skill when the user wants project planning output in Kanbn format: a board, task files, dependencies, sequencing, scope breakdown, and task descriptions.
+
+Do not use this skill to implement the project, edit source code, scaffold files outside `.kanbn/`, or estimate progress from work that has not happened yet.
+
+## Core Contract
+
+Your output must stay inside the Kanbn planning surface:
+
+- `.kanbn/index.md`
+- `.kanbn/tasks/*.md`
+
+Do not create application code, tests, CI files, or documentation unrelated to the Kanbn board.
+
+If the user asks for planning plus implementation, complete the planning portion in Kanbn format first and keep the planning files cleanly separated from any later work.
+
+## Planning Goals
+
+Produce a board that is both valid and useful:
+
+- Break vague requirements into concrete, reviewable tasks.
+- Capture prerequisite relationships with Kanbn relations.
+- Preserve important scope, assumptions, risks, and milestones in task descriptions.
+- Avoid invented execution history such as fake progress, comments, timestamps, or completed work.
+- Keep the plan maintainable so a human can reprioritise it later.
+
+## Workflow
+
+### 1. Extract scope before writing files
+
+From the user prompt or specification, identify:
+
+- project goal
+- major workstreams or epics
+- prerequisites and external dependencies
+- constraints, risks, and open questions
+- any explicit milestones, deadlines, or sequencing requirements
+
+If the prompt is underspecified, make minimal planning assumptions and state them in the index description or in task descriptions where relevant.
+
+### 2. Choose a board shape
+
+If the user does not specify columns, default to Kanbn's standard workflow:
+
+- `Backlog`
+- `Todo`
+- `In Progress`
+- `Done`
+
+And default options:
+
+- `startedColumns: ["In Progress"]`
+- `completedColumns: ["Done"]`
+
+Use extra columns only when the project brief clearly benefits from them, for example `Review`, `Testing`, `Release`, or domain-specific approval states.
+
+Do not use columns to model architecture layers, epics, or teams when tags or task descriptions would be more appropriate. Columns should represent workflow state.
+
+### 3. Decompose into actionable tasks
+
+Each generated task should be:
+
+- small enough to complete as one coherent unit of work
+- specific enough that another agent or engineer can act on it later
+- named by outcome, not by vague area labels
+- independent where possible, but explicitly linked when not
+
+Prefer imperative or outcome-focused names such as:
+
+- `Define authentication flow`
+- `Create database migration plan`
+- `Document deployment rollback steps`
+
+Avoid umbrella task names such as:
+
+- `Backend`
+- `Frontend work`
+- `Finish project`
+
+### 4. Model dependencies carefully
+
+Use the relations section to encode sequencing.
+
+Preferred relation types:
+
+- `depends-on`: the current task cannot start until the referenced task is complete
+- `blocks`: the current task prevents the referenced task from starting or finishing
+
+Important rules:
+
+- Use one direction per dependency edge. Do not create both `depends-on A` and `blocks B` for the same relationship unless the user explicitly asks for mirrored wording.
+- Do not create self-references.
+- Do not create cycles.
+- Other relation types such as `duplicates` or `obsoletes` are allowed, but they are not scheduling dependencies.
+
+Kanbn's gantt dependency logic only treats `depends-on` and `blocks` as dependency edges.
+
+### 5. Write lean metadata
+
+Only include metadata when it is grounded in the prompt or materially useful.
+
+Safe defaults:
+
+- omit YAML front matter entirely when no metadata is needed
+- omit `created`, `updated`, `started`, `completed`, `progress`, `comments`, and `history`
+- omit `assigned` unless the user supplied owners
+- omit `due` unless the user supplied a deadline
+
+Useful optional metadata:
+
+- `tags` for epics, domains, or sizing labels
+- custom fields only if the board already defines them
+
+### 6. Place tasks in columns intentionally
+
+For a fresh plan, use this default placement strategy unless the user specifies otherwise:
+
+- put ready, near-term tasks with no unresolved prerequisites in `Todo`
+- put deferred or dependency-blocked tasks in `Backlog`
+- leave `In Progress` and `Done` empty unless the user explicitly says work has already started or finished
+
+Do not fabricate active work.
+
+### 7. Validate before finalising
+
+Before presenting the plan, validate it if the environment allows.
+
+Use these helper files from this skill when available:
+
+- `references/index-structure.md`
+- `references/task-structure.md`
+- `references/planning-rules.md`
+- `scripts/validate-kanbn.mjs`
+- `scripts/check-dependency-cycles.mjs`
+
+Validation sequence:
+
+1. Ensure `.kanbn/index.md` uses valid headings and task links.
+2. Ensure each task file has a valid title, description, and any reserved sections in the correct format.
+3. Run the validate wrapper.
+4. Run the dependency cycle checker.
+5. Fix any structural or dependency issues before stopping.
+
+## Output Standards
+
+### Index requirements
+
+The index must:
+
+- contain exactly one level-1 project heading
+- contain optional description text directly under the project heading
+- define workflow columns with level-2 headings
+- list task ids as markdown links to `tasks/<task-id>.md`
+
+### Task requirements
+
+Each task file must:
+
+- live at `.kanbn/tasks/<task-id>.md`
+- contain exactly one top-level heading with the human-readable task name
+- include a description tailored to the task
+- use reserved headings correctly when present: `Metadata`, `Sub-tasks`, `Relations`, `Comments`, `History`
+
+Descriptions should usually include:
+
+- the purpose of the task
+- key scope boundaries
+- expected deliverable or outcome
+- acceptance criteria or completion signals when useful
+
+### Task id rules
+
+Use stable kebab-case ids derived from the task name.
+
+Examples:
+
+- `Set up CI pipeline` -> `set-up-ci-pipeline`
+- `Plan data retention policy` -> `plan-data-retention-policy`
+
+## When Revising An Existing Board
+
+If `.kanbn/` already exists:
+
+- preserve the existing board structure unless the user asked to redesign it
+- preserve existing custom fields and option conventions
+- avoid rewriting unrelated tasks
+- add or edit only the planning artifacts needed for the requested plan change
+
+## References
+
+Use these files as the source of truth while authoring:
+
+- `references/index-structure.md` for `.kanbn/index.md`
+- `references/task-structure.md` for `.kanbn/tasks/*.md`
+- `references/planning-rules.md` for decomposition and dependency heuristics
+
+## Success Criteria
+
+This skill is successful when it produces a Kanbn board that:
+
+- accurately reflects the requested project scope
+- is structurally valid
+- contains actionable tasks instead of vague placeholders
+- captures dependency order without cycles
+- does not stray into implementation work

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

@@ -0,0 +1,89 @@
+# Kanbn Index Reference
+
+This reference describes the structure expected for `.kanbn/index.md` when generating a project plan.
+
+## Minimum Valid Shape
+
+```markdown
+---
+startedColumns:
+  - In Progress
+completedColumns:
+  - Done
+---
+
+# Project Name
+
+Short project summary and planning assumptions.
+
+## Backlog
+
+- [task-id-1](tasks/task-id-1.md)
+- [task-id-2](tasks/task-id-2.md)
+
+## Todo
+
+- [task-id-3](tasks/task-id-3.md)
+
+## In Progress
+
+## Done
+```
+
+## Rules
+
+- The file may begin with YAML front matter.
+- There must be exactly one level-1 heading for the project name.
+- Text under the project heading is the project description.
+- After the description, each level-2 heading defines a column.
+- Each column should contain a markdown list of task links.
+- Each task link should point to `tasks/<task-id>.md`.
+- The link text should be the task id, not the human-readable title.
+
+## Recommended Defaults
+
+If the user does not specify a workflow, prefer:
+
+```yaml
+startedColumns:
+  - In Progress
+completedColumns:
+  - Done
+```
+
+And columns:
+
+- `Backlog`
+- `Todo`
+- `In Progress`
+- `Done`
+
+## Placement Guidance
+
+- Put tasks in `Todo` only if they are ready to start and not obviously blocked.
+- Put blocked, later-phase, or lower-priority work in `Backlog`.
+- Leave `In Progress` empty for a newly generated plan unless the prompt explicitly says work is underway.
+- Leave `Done` empty unless the prompt explicitly references completed work.
+
+## Options Worth Using
+
+Only add options when they are meaningful.
+
+Commonly useful options:
+
+- `startedColumns`
+- `completedColumns`
+- `hiddenColumns`
+- `taskWorkloadTags`
+- `defaultTaskWorkload`
+- `customFields`
+
+Avoid adding large option blocks that the user did not ask for.
+
+## Common Mistakes
+
+- Using headings inside the project description.
+- Listing bare task ids instead of markdown links.
+- Linking to the wrong path, for example `./tasks/...` or absolute paths.
+- Treating columns as epics or teams instead of workflow states.
+- Populating `In Progress` or `Done` with speculative work states.

package/skills/kanbn-plan/references/planning-rules.md

@@ -0,0 +1,58 @@
+# Planning Rules
+
+Use these heuristics when turning a prompt into Kanbn planning artifacts.
+
+## Decomposition Heuristics
+
+- Split by deliverable, decision, integration point, or risk area.
+- Prefer tasks that produce one observable planning outcome.
+- Separate discovery work from execution work when the unknowns are material.
+- Separate prerequisite setup from dependent feature work.
+- Separate cross-cutting concerns such as security, observability, migration, or rollout planning when they would otherwise disappear into feature tasks.
+
+## Task Granularity
+
+Aim for tasks that are:
+
+- independently understandable
+- narrow enough to estimate or assign later
+- broad enough to avoid an explosion of trivial tasks
+
+If a task description needs multiple unrelated deliverables, split it.
+
+## Dependency Rules
+
+- Add dependencies only when order materially matters.
+- Prefer `depends-on` over ad hoc wording because Kanbn already understands it for scheduling.
+- Use `blocks` when it reads more naturally from the prerequisite task.
+- Do not encode the same dependency twice in opposite directions unless the user wants mirrored relations.
+- Avoid diamond-shaped dependency graphs when a simpler linear or fan-out structure is more accurate.
+
+## Prioritisation Rules
+
+- Put foundational work before feature-specific work.
+- Put architecture and interface decisions before implementation-heavy downstream tasks.
+- Put risk-reduction tasks earlier when they can invalidate later work.
+- Keep optional enhancements, stretch goals, and nice-to-haves in `Backlog`.
+
+## Naming Rules
+
+- Use explicit outcome-oriented titles.
+- Prefer verbs like `Define`, `Plan`, `Document`, `Design`, `Map`, `Specify`, `Assess`, `Prepare`.
+- Avoid names that just restate a subsystem with no action.
+
+## Assumption Rules
+
+- Do not invent deadlines, owners, or progress.
+- If the prompt leaves a critical planning choice unresolved, capture it as an assumption or an explicit planning task.
+- If the board already exists, preserve its conventions unless the user asks to change them.
+
+## Final Review Checklist
+
+Before finalising a generated board, confirm:
+
+- every task in the index has a corresponding task file
+- every relation points to an existing task id
+- the dependency graph has no cycles
+- task descriptions are specific enough to guide later execution
+- the board contains planning artifacts only, not implementation work

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();