@xxkeefer/mrkl 0.2.14 → 0.3.1

package/README.md

@@ -1,6 +1,8 @@
 <p align="center">
   <h1 align="center">mrkl</h1>
   <p align="center">
+    📝 <i>mrkl, rhymes with sparkle</i> ✨
+    <br />
     Lightweight CLI for structured markdown task tracking.
     <br />
     Track work in your repo, not in a separate app.
@@ -15,17 +17,17 @@
 
 ---
 
-## Why mrkl?
+## Why mrkl? 🤔
 
 Most task trackers live outside your codebase. mrkl keeps tasks as markdown files right alongside your code — version-controlled, greppable, and readable by both humans and AI agents.
 
-- **No external service** — tasks live in `.tasks/` as structured markdown
-- **Git-native** — commit, branch, and diff your tasks like any other file
-- **AI-agent friendly** — consistent YAML frontmatter makes tasks easy to parse programmatically
-- **Conventional commits vocabulary** — task types mirror what you already use (`feat`, `fix`, `chore`, etc.)
-- **Zero config** — one command to set up, sensible defaults for everything
+- 🗂️ **No external service** — tasks live in `.tasks/` as structured markdown
+- 🌿 **Git-native** — commit, branch, and diff your tasks like any other file
+- 🤖 **AI-agent friendly** — consistent YAML frontmatter makes tasks easy to parse programmatically
+- 📏 **Conventional commits vocabulary** — task types mirror what you already use (`feat`, `fix`, `chore`, etc.)
+- ⚡ **Zero config** — one command to set up, sensible defaults for everything
 
-## Install
+## Install 📦
 
 ```sh
 pnpm add -g @xxkeefer/mrkl
@@ -37,7 +39,7 @@ Or use without installing:
 npx @xxkeefer/mrkl init MY_PROJECT
 ```
 
-## Quick Start
+## Quick Start 🚀
 
 ```sh
 # Initialize in your project root
@@ -60,9 +62,25 @@ mrkl list --status todo
 
 # Archive a completed task
 mrkl done PROJ-001
+
+# All commands have short aliases
+mrkl c feat "dark mode"   # create
+mrkl ls --type fix         # list
+mrkl d PROJ-001            # done
+mrkl x PROJ-002            # close
 ```
 
-## Commands
+## Commands 🛠️
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `init` | `i` | Initialize mrkl in the current project |
+| `create` | `c` | Create a new task |
+| `list` | `ls` | List active tasks |
+| `done` | `d` | Mark a task as done and archive it |
+| `close` | `x` | Close a task (won't do, duplicate, etc.) and archive it |
+| `prune` | `p` | Delete archived tasks created on or before a given date |
+| `install-skills` | — | Install bundled Claude Code skills |
 
 ### `mrkl init <prefix>`
 
@@ -89,10 +107,10 @@ Creates a new task file.
 | `type` | Task type (see [Task Types](#task-types)) |
 | `title` | Short description of the task |
 
-| Option | Description |
-|--------|-------------|
-| `--desc <text>` | Detailed description |
-| `--ac <text>` | Acceptance criterion (repeatable) |
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--desc <text>` | `-d` | Detailed description |
+| `--ac <text>` | `-a` | Acceptance criterion (repeatable) |
 
 ```sh
 mrkl create feat "search functionality" \
@@ -102,14 +120,16 @@ mrkl create feat "search functionality" \
   --ac "highlights matching terms"
 ```
 
+Running `mrkl create` with no arguments enters **interactive mode**, prompting for type, title, description, and acceptance criteria.
+
 ### `mrkl list [options]`
 
 Lists all active tasks.
 
-| Option | Description |
-|--------|-------------|
-| `--type <type>` | Filter by task type |
-| `--status <status>` | Filter by status (`todo`, `in-progress`, `done`) |
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--type <type>` | `-t` | Filter by task type |
+| `--status <status>` | `-s` | Filter by status (`todo`, `in-progress`, `done`) |
 
 Non-conforming markdown files in the tasks directory are silently skipped.
 
@@ -123,7 +143,56 @@ Archives a completed task.
 
 Moves the task file to `.tasks/.archive/` and sets its status to `done`.
 
-## Task Types
+### `mrkl close <id>`
+
+Closes a task that won't be done — duplicates, out-of-scope work, etc.
+
+| Argument | Description |
+|----------|-------------|
+| `id` | Task ID to close (e.g., `PROJ-002`) |
+
+Sets the task status to `closed` and moves it to `.tasks/.archive/`.
+
+### `mrkl prune <date> [options]`
+
+Permanently deletes archived tasks created on or before a cutoff date.
+
+| Argument | Description |
+|----------|-------------|
+| `date` | Cutoff date (`YYYY-MM-DD` or `YYYYMMDD`) |
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--force` | `-f` | Skip confirmation prompt |
+
+Shows a confirmation prompt listing tasks to be deleted unless `--force` is used.
+
+```sh
+# Delete archived tasks from January or earlier
+mrkl prune 2026-01-31
+
+# Skip confirmation
+mrkl prune 2026-01-31 --force
+```
+
+### `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:
 
@@ -140,7 +209,7 @@ mrkl uses [conventional commit](https://www.conventionalcommits.org/) types:
 | `build` | Build system changes |
 | `style` | Code style/formatting |
 
-## Task File Format
+## Task File Format 📄
 
 Each task is a markdown file with YAML frontmatter:
 
@@ -168,7 +237,7 @@ Implement user authentication with OAuth2.
 
 The format is intentionally simple — edit task files directly when you need to update descriptions, change status, or check off criteria.
 
-## Project Structure
+## Project Structure 🗂️
 
 After initialization, mrkl adds the following to your project:
 
@@ -186,7 +255,7 @@ your-project/
 
 Commit `.config/mrkl/` and `.tasks/` to version control. They're designed to be tracked alongside your code.
 
-## Team Workflow
+## Team Workflow 👥
 
 When using mrkl with **git worktrees** or **protected branches**, task IDs can conflict if multiple branches create tasks concurrently. The fix is a simple convention: **separate planning from execution.**
 
@@ -210,7 +279,7 @@ mrkl done MRKL-019
 
 The counter only increments on planning branches — one at a time — so IDs never conflict. See **[docs/workflow.md](docs/workflow.md)** for the full guide with examples and edge cases.
 
-## Configuration
+## Configuration ⚙️
 
 Configuration lives in `.config/mrkl/mrkl.toml` (or `mrkl.toml` at the project root):
 
@@ -224,7 +293,7 @@ tasks_dir = ".tasks"
 | `prefix` | *(required)* | Project prefix for task IDs |
 | `tasks_dir` | `".tasks"` | Directory for task files |
 
-## Development
+## Development 🧑‍💻
 
 ```sh
 git clone https://github.com/xxKeefer/mrkl.git
@@ -241,10 +310,10 @@ pnpm tsx src/cli.ts list
 pnpm build
 ```
 
-## Contributing
+## Contributing 🤝
 
 Contributions are welcome! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for branch protection rules, merge strategy, and development setup.
 
-## License
+## License 📜
 
 [MIT](LICENSE)

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"),
@@ -57,7 +58,7 @@ const initCommand = defineCommand({
     const dir = process.cwd();
     try {
       initConfig(dir, { prefix: args.prefix });
-      consola.success("mrkl initialized");
+      consola.success("\u{1F389} mrkl initialized");
     } catch (err) {
       consola.error(String(err.message));
       process.exit(1);
@@ -144,9 +145,7 @@ function createTask(opts) {
 function listTasks(filter) {
   const config = loadConfig(filter.dir);
   const tasksDir = join(filter.dir, config.tasks_dir);
-  const files = readdirSync(tasksDir).filter(
-    (f) => f.endsWith(".md") && !f.startsWith(".")
-  );
+  const files = readdirSync(tasksDir).filter((f) => f.endsWith(".md") && !f.startsWith("."));
   let tasks = files.flatMap((f) => {
     try {
       const content = readFileSync(join(tasksDir, f), "utf-8");
@@ -164,8 +163,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`);
@@ -178,6 +178,70 @@ function archiveTask(dir, id) {
   writeFileSync(archivePath, render(task));
   unlinkSync(filePath);
 }
+function parseCutoffDate(input) {
+  const normalized = input.replace(/^(\d{4})(\d{2})(\d{2})$/, "$1-$2-$3");
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(normalized)) {
+    throw new Error(`Invalid date format: "${input}". Expected YYYY-MM-DD or YYYYMMDD.`);
+  }
+  const [y, m, d] = normalized.split("-").map(Number);
+  const date = new Date(y, m - 1, d);
+  if (date.getFullYear() !== y || date.getMonth() !== m - 1 || date.getDate() !== d) {
+    throw new Error(`Invalid date: "${input}" is not a real calendar date.`);
+  }
+  return normalized;
+}
+function normalizeCreatedDate(created) {
+  if (created instanceof Date) {
+    return created.toISOString().slice(0, 10);
+  }
+  return String(created);
+}
+function pruneTasks(dir, cutoff) {
+  const config = loadConfig(dir);
+  const archiveDir = join(dir, config.tasks_dir, ".archive");
+  if (!existsSync(archiveDir)) {
+    return { deleted: [], total: 0 };
+  }
+  const files = readdirSync(archiveDir).filter((f) => f.endsWith(".md") && !f.startsWith("."));
+  const deleted = [];
+  for (const f of files) {
+    try {
+      const content = readFileSync(join(archiveDir, f), "utf-8");
+      const task = parse(content, f);
+      const created = normalizeCreatedDate(task.created);
+      if (created <= cutoff) {
+        deleted.push({ id: task.id, title: task.title, created, filename: f });
+      }
+    } catch {
+    }
+  }
+  return { deleted, total: files.length };
+}
+function executePrune(dir, filenames) {
+  const config = loadConfig(dir);
+  const archiveDir = join(dir, config.tasks_dir, ".archive");
+  for (const f of filenames) {
+    unlinkSync(join(archiveDir, f));
+  }
+}
+function closeTask(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.toUpperCase().startsWith(idUpper)
+  );
+  if (!file) {
+    throw new Error(`Task ${id} not found`);
+  }
+  const filePath = join(tasksDir, file);
+  const content = readFileSync(filePath, "utf-8");
+  const task = parse(content, file);
+  task.status = "closed";
+  const archivePath = join(tasksDir, ".archive", file);
+  writeFileSync(archivePath, render(task));
+  unlinkSync(filePath);
+}
 
 const TASK_TYPES = [
   "feat",
@@ -192,6 +256,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("\u274C 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,37 +302,47 @@ 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("\u274C 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(`\u274C 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
-      });
-      consola.success(`Created ${task.id}: ${task.title}`);
+      };
+      const task = createTask(opts);
+      consola.success(`\u{1F4DD} Created ${task.id}: ${task.title}`);
     } catch (err) {
       consola.error(String(err.message));
       process.exit(1);
@@ -247,10 +358,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)"
     }
   },
@@ -263,7 +376,7 @@ const listCommand = defineCommand({
         status: args.status
       });
       if (tasks.length === 0) {
-        consola.info("No tasks found");
+        consola.info("\u{1F4ED} No tasks found");
         return;
       }
       for (const task of tasks) {
@@ -292,7 +405,138 @@ const doneCommand = defineCommand({
     const dir = process.cwd();
     try {
       archiveTask(dir, args.id);
-      consola.success(`Archived ${args.id}`);
+      consola.success(`\u2705 Archived ${args.id}`);
+    } catch (err) {
+      consola.error(String(err.message));
+      process.exit(1);
+    }
+  }
+});
+
+const pruneCommand = defineCommand({
+  meta: {
+    name: "prune",
+    description: "Delete archived tasks created on or before a given date"
+  },
+  args: {
+    date: {
+      type: "positional",
+      description: "Cutoff date (YYYY-MM-DD or YYYYMMDD)",
+      required: true
+    },
+    force: {
+      type: "boolean",
+      alias: "f",
+      description: "Skip confirmation prompt",
+      default: false
+    }
+  },
+  async run({ args }) {
+    const dir = process.cwd();
+    let cutoff;
+    try {
+      cutoff = parseCutoffDate(args.date);
+    } catch (err) {
+      consola.error(String(err.message));
+      process.exit(1);
+    }
+    const result = pruneTasks(dir, cutoff);
+    if (result.deleted.length === 0) {
+      consola.info(`\u{1F4ED} No archived tasks found on or before ${cutoff}`);
+      return;
+    }
+    consola.info(`\u{1F50D} Found ${result.deleted.length} task(s) to prune:`);
+    for (const task of result.deleted) {
+      consola.log(`  ${task.id} \u2014 ${task.title} (${task.created})`);
+    }
+    if (!args.force) {
+      const confirm = await consola.prompt("Delete these tasks?", {
+        type: "confirm"
+      });
+      if (typeof confirm === "symbol" || !confirm) {
+        consola.info("\u{1F44B} Aborted");
+        return;
+      }
+    }
+    executePrune(dir, result.deleted.map((t) => t.filename));
+    consola.success(`\u{1F9F9} Pruned ${result.deleted.length} archived task(s)`);
+  }
+});
+
+const closeCommand = defineCommand({
+  meta: {
+    name: "close",
+    description: "Close a task (won't do, duplicate, etc.) and archive it"
+  },
+  args: {
+    id: {
+      type: "positional",
+      description: "Task ID to close (e.g., VON-001)",
+      required: true
+    }
+  },
+  run({ args }) {
+    const dir = process.cwd();
+    try {
+      closeTask(dir, args.id);
+      consola.success(`\u{1F6AB} Closed ${args.id}`);
+    } catch (err) {
+      consola.error(String(err.message));
+      process.exit(1);
+    }
+  }
+});
+
+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("\u274C 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("\u{1F4ED} 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(`\u{1F9E9} Installed ${skill}`);
+      }
     } catch (err) {
       consola.error(String(err.message));
       process.exit(1);
@@ -308,10 +552,18 @@ const main = defineCommand({
   },
   subCommands: {
     init: initCommand,
+    i: initCommand,
     create: createCommand,
     c: createCommand,
     list: listCommand,
-    done: doneCommand
+    ls: listCommand,
+    done: doneCommand,
+    d: doneCommand,
+    prune: pruneCommand,
+    p: pruneCommand,
+    close: closeCommand,
+    x: closeCommand,
+    "install-skills": installSkillsCommand
   }
 });
 runMain(main);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xxkeefer/mrkl",
-  "version": "0.2.14",
+  "version": "0.3.1",
   "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",

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