@xxkeefer/mrkl 0.2.6 → 0.3.0

package/README.md

@@ -123,6 +123,23 @@ Archives a completed task.
 
 Moves the task file to `.tasks/.archive/` and sets its status to `done`.
 
+### `mrkl install-skills`
+
+Installs bundled Claude Code skills into the current project.
+
+Copies skill directories from the mrkl package into `.claude/skills/` so they are available to Claude Code agents working in this project.
+
+```sh
+mrkl install-skills
+# ✔ Installed plan-from-task
+```
+
+Currently ships with:
+
+| Skill | Description |
+|-------|-------------|
+| `plan-from-task` | Generate and execute implementation plans from mrkl task files |
+
 ## Task Types
 
 mrkl uses [conventional commit](https://www.conventionalcommits.org/) types:

package/dist/cli.mjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import { defineCommand, runMain } from 'citty';
 import consola from 'consola';
-import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
 import { stringify, parse as parse$1 } from 'smol-toml';
 import matter from 'gray-matter';
+import { fileURLToPath } from 'node:url';
 
 const CONFIG_PATHS = [
   join(".config", "mrkl", "mrkl.toml"),
@@ -164,8 +165,9 @@ function listTasks(filter) {
 function archiveTask(dir, id) {
   const config = loadConfig(dir);
   const tasksDir = join(dir, config.tasks_dir);
+  const idUpper = id.toUpperCase();
   const file = readdirSync(tasksDir).find(
-    (f) => f.endsWith(".md") && f.startsWith(id)
+    (f) => f.endsWith(".md") && f.toUpperCase().startsWith(idUpper)
   );
   if (!file) {
     throw new Error(`Task ${id} not found`);
@@ -192,6 +194,43 @@ const TASK_TYPES = [
   "style"
 ];
 
+async function promptForTask(dir) {
+  const type = await consola.prompt("Task type", {
+    type: "select",
+    options: TASK_TYPES.map((t) => t)
+  });
+  if (typeof type === "symbol") process.exit(0);
+  const title = await consola.prompt("Task title", {
+    type: "text",
+    placeholder: "e.g. add user authentication"
+  });
+  if (typeof title === "symbol") process.exit(0);
+  if (!title.trim()) {
+    consola.error("Title cannot be empty");
+    process.exit(1);
+  }
+  const desc = await consola.prompt("Description (optional, enter to skip)", {
+    type: "text",
+    placeholder: "Describe the task in detail"
+  });
+  if (typeof desc === "symbol") process.exit(0);
+  const criteria = [];
+  while (true) {
+    const ac = await consola.prompt(
+      criteria.length === 0 ? "Acceptance criterion (Esc to skip)" : `Criterion #${criteria.length + 1} (Esc to finish)`,
+      { type: "text" }
+    );
+    if (typeof ac === "symbol") break;
+    if (ac.trim()) criteria.push(ac.trim());
+  }
+  return {
+    dir,
+    type,
+    title,
+    description: desc || void 0,
+    acceptance_criteria: criteria.length > 0 ? criteria : void 0
+  };
+}
 const createCommand = defineCommand({
   meta: {
     name: "create",
@@ -201,36 +240,46 @@ const createCommand = defineCommand({
     type: {
       type: "positional",
       description: "Task type (feat, fix, chore, docs, perf, refactor, test, ci, build, style)",
-      required: true
+      required: false
     },
     title: {
       type: "positional",
       description: "Task title",
-      required: true
+      required: false
     },
     desc: {
       type: "string",
+      alias: "d",
       description: "Task description"
     },
     ac: {
       type: "string",
+      alias: "a",
       description: "Acceptance criterion (can be specified multiple times)"
     }
   },
-  run({ args }) {
-    if (!TASK_TYPES.includes(args.type)) {
-      consola.error(`Invalid type "${args.type}". Must be one of: ${TASK_TYPES.join(", ")}`);
+  async run({ args }) {
+    const dir = process.cwd();
+    const interactive = !args.type && !args.title;
+    if (!interactive && (!args.type || !args.title)) {
+      consola.error("Both type and title are required, or omit both for interactive mode");
       process.exit(1);
     }
-    const dir = process.cwd();
     try {
-      const task = createTask({
+      const opts = interactive ? await promptForTask(dir) : {
         dir,
-        type: args.type,
+        type: (() => {
+          if (!TASK_TYPES.includes(args.type)) {
+            consola.error(`Invalid type "${args.type}". Must be one of: ${TASK_TYPES.join(", ")}`);
+            process.exit(1);
+          }
+          return args.type;
+        })(),
         title: args.title,
         description: args.desc,
         acceptance_criteria: args.ac ? Array.isArray(args.ac) ? args.ac : [args.ac] : void 0
-      });
+      };
+      const task = createTask(opts);
       consola.success(`Created ${task.id}: ${task.title}`);
     } catch (err) {
       consola.error(String(err.message));
@@ -247,10 +296,12 @@ const listCommand = defineCommand({
   args: {
     type: {
       type: "string",
+      alias: "t",
       description: "Filter by task type"
     },
     status: {
       type: "string",
+      alias: "s",
       description: "Filter by status (todo, in-progress, done)"
     }
   },
@@ -300,6 +351,63 @@ const doneCommand = defineCommand({
   }
 });
 
+function findPackageRoot() {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  while (dir !== dirname(dir)) {
+    if (existsSync(join(dir, "package.json"))) {
+      const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8"));
+      if (pkg.name === "@xxkeefer/mrkl") return dir;
+    }
+    dir = dirname(dir);
+  }
+  throw new Error("Could not locate mrkl package root");
+}
+function copyDirSync(src, dest) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    if (statSync(srcPath).isDirectory()) {
+      copyDirSync(srcPath, destPath);
+    } else {
+      writeFileSync(destPath, readFileSync(srcPath));
+    }
+  }
+}
+const installSkillsCommand = defineCommand({
+  meta: {
+    name: "install-skills",
+    description: "Install mrkl Claude Code skills into the current project"
+  },
+  run() {
+    const dest = join(process.cwd(), ".claude", "skills");
+    try {
+      const packageRoot = findPackageRoot();
+      const skillsDir = join(packageRoot, "skills");
+      if (!existsSync(skillsDir)) {
+        consola.error("No skills directory found in mrkl package");
+        process.exit(1);
+      }
+      const skills = readdirSync(skillsDir).filter(
+        (f) => statSync(join(skillsDir, f)).isDirectory()
+      );
+      if (skills.length === 0) {
+        consola.info("No skills to install");
+        return;
+      }
+      for (const skill of skills) {
+        const src = join(skillsDir, skill);
+        const target = join(dest, skill);
+        copyDirSync(src, target);
+        consola.success(`Installed ${skill}`);
+      }
+    } catch (err) {
+      consola.error(String(err.message));
+      process.exit(1);
+    }
+  }
+});
+
 const main = defineCommand({
   meta: {
     name: "mrkl",
@@ -308,10 +416,14 @@ const main = defineCommand({
   },
   subCommands: {
     init: initCommand,
+    i: initCommand,
     create: createCommand,
     c: createCommand,
     list: listCommand,
-    done: doneCommand
+    ls: listCommand,
+    done: doneCommand,
+    d: doneCommand,
+    "install-skills": installSkillsCommand
   }
 });
 runMain(main);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xxkeefer/mrkl",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "type": "module",
   "description": "Lightweight CLI tool for structured markdown task tracking",
   "bin": {
@@ -14,7 +14,8 @@
   ],
   "license": "MIT",
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "repository": {
     "type": "git",
@@ -41,8 +42,7 @@
     "build": "unbuild",
     "dev": "node --import tsx src/cli.ts",
     "test": "vitest run",
-    "release": "./scripts/release.sh",
-    "changelog": "changelogen",
+    "changelog": "changelogen --output",
     "changelog:preview": "changelogen --no-output"
   }
 }

package/skills/plan-from-task/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: plan-from-task
+description: Generate and execute implementation plans from mrkl task files (.tasks/ directory). Use when user references a task ID (e.g., MRKL-001, PROJ-042) or a @path to a .tasks/ markdown file and wants to plan or implement it.
+---
+
+# Plan From Task
+
+Create implementation plans from mrkl task files and execute them.
+
+## Quick start
+
+The user provides a task reference in one of two forms:
+
+- **File path**: `@".tasks/PROJ-001 feat - user auth.md"` or `implement .tasks/PROJ-001...`
+- **Task ID**: `PROJ-001` or `mrkl-042` (case-insensitive)
+
+## Workflow
+
+### 1. Locate and read the task
+
+- **File path given**: read the file directly
+- **Task ID given**: glob for `.tasks/<ID>*.md` (case-insensitive) and read the match
+
+Parse the YAML frontmatter and markdown body. Task files follow this structure:
+
+```markdown
+---
+id: PROJ-001
+type: feat
+status: todo
+created: '2026-03-01'
+---
+
+## Description
+
+[What needs to be done]
+
+## Acceptance Criteria
+
+- [ ] first criterion
+- [ ] second criterion
+```
+
+### 2. Assess completeness
+
+If the description or acceptance criteria are too vague to plan from:
+
+- Ask the user targeted clarifying questions about scope, approach, or constraints
+- Gather enough context to produce a concrete implementation plan
+
+### 3. Plan the implementation
+
+1. Enter plan mode
+2. Explore the codebase to understand relevant architecture and patterns
+3. Write a step-by-step implementation plan that addresses every acceptance criterion
+4. Present the plan for user approval
+
+### 4. Execute the plan
+
+After approval, implement in this order:
+
+1. **Update the task file first** — rewrite the `## Description` body and `## Acceptance Criteria`
+   checklist to reflect the refined, concrete plan of what will be delivered.
+   The task file doubles as the PR description, so make it clear and accurate.
+2. Then implement the code changes following the plan.
+
+## Rules
+
+- **NEVER modify YAML frontmatter** — `id`, `type`, `status`, `created` are immutable
+- **NEVER modify markdown headings** — `## Description` and `## Acceptance Criteria` must stay as-is
+- You MAY rewrite the content under those headings to match the approved plan
+- Use `- [ ]` checkbox format for acceptance criteria
+- Follow existing codebase conventions discovered during exploration