@dreki-gg/taskman 0.2.0 → 0.2.1

package/README.md

@@ -0,0 +1,85 @@
+# @dreki-gg/taskman
+
+A standalone task-management engine — and a `taskman` CLI — over a plain
+`.plans/` JSONL ledger. It is the core extracted from
+[`@dreki-gg/pi-plan-mode`](../plan-mode), so any harness (not just pi) can drive
+the same plans, initiatives, and tasks.
+
+## Why it exists
+
+Planning agents need durable, file-based task state that survives across
+sessions and tools. `taskman` owns that state machine — task status, plan and
+initiative lifecycle, and the projection rules that keep them consistent — with
+**no dependency on any specific agent harness**. Use it from a shell, a CI job,
+a different agent, or as a library.
+
+## The ledger (the one durable contract)
+
+Everything lives under `.plans/` in the current working directory:
+
+- `.plans/plans.jsonl` — the plan registry.
+- `.plans/initiatives.jsonl` — the initiative registry (initiatives group plans).
+- `.plans/<plan>/tasks.jsonl` — one plan's task list (first line is metadata).
+- `.plans/<plan>/HANDOFF.md`, `.plans/<initiative>/INITIATIVE.md` — prose docs.
+
+Three invariants are worth knowing; everything else is mechanism:
+
+1. **Status is a projection, not a flag.** A plan is `done` when its active
+   tasks are all resolved (and no follow-ups remain); an initiative is `done`
+   when every member plan is terminal. Writing task state re-derives the
+   registry — you do not set plan status by hand for the normal path.
+2. **Plan resolution is stateless.** A command targets a plan via `--plan
+   <name>` (accepts `.plans/<name>` too), else the *single* in-progress plan.
+   Ambiguous or missing → it exits non-zero and lists the candidates.
+3. **Terminal statuses set manually are never auto-reverted.** `reconcile` only
+   moves `in-progress ⇄ done`; it never resurrects a `superseded`/`abandoned`
+   plan or regresses a finished one.
+
+## Usage
+
+```bash
+taskman --help            # full, always-current command list
+taskman <command> --help  # flags + arguments for one command
+```
+
+`--help` is the source of truth for commands and flags — this README does not
+duplicate it (so it cannot drift). Every command prints human text by default
+and accepts `--json` for machine consumption.
+
+A typical execution loop:
+
+```bash
+taskman status                       # what's the active plan and its tasks?
+taskman update-task t-003 done       # mark progress (auto-reconciles the plan)
+taskman add-task "handle empty case" --reason "found gap while implementing"
+taskman reconcile --apply            # repair safe status drift
+```
+
+## As a library
+
+```ts
+import { makePlanRuntime, resolvePlanByName, setTaskStatus } from '@dreki-gg/taskman';
+
+const run = makePlanRuntime(); // bridges the Effect programs to the live filesystem
+const { planDir } = await run(resolvePlanByName({ name: 'my-plan' }));
+await run(setTaskStatus(planDir!, 't-001', 'done'));
+```
+
+The public surface (storage, schema, reconcile, initiative projection,
+resolution, and composite write flows) is exported from the package root. The
+engine is built on [Effect](https://effect.website) with a single `FileSystem`
+seam, so it is straightforward to test and to run against an alternate backend.
+
+## Agent skill
+
+This package ships a [TanStack Intent](https://tanstack.com/intent) skill
+(`skills/taskman/core`) — versioned guidance that AI coding agents discover from
+`node_modules`. If you use an AI agent, run:
+
+```bash
+npx @tanstack/intent@latest install
+```
+
+## License
+
+MIT

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@dreki-gg/taskman",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Standalone task-management engine + CLI over a .plans/ JSONL ledger — the plan-mode core, usable from any Node harness",
   "keywords": [
     "tasks",
     "planning",
-    "cli"
+    "cli",
+    "tanstack-intent"
   ],
   "author": "Juan Albarran <jalbarrandev@gmail.com>",
   "license": "MIT",
@@ -26,11 +27,14 @@
     "taskman": "./dist/cli.mjs"
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "skills"
   ],
   "scripts": {
     "build": "tsdown",
     "test": "bun test",
+    "intent:validate": "intent validate",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint src",
     "format": "oxfmt --write src",
@@ -41,6 +45,7 @@
     "effect": "^3.21.2"
   },
   "devDependencies": {
+    "@tanstack/intent": "^0.1.0",
     "@types/node": "24",
     "bun-types": "latest",
     "oxfmt": "^0.43.0",

package/skills/taskman/core/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: taskman/core
+description: >
+  Drive the taskman CLI and engine over a .plans/ JSONL ledger — plans,
+  initiatives, and tasks. Load when running `taskman` commands (status, list,
+  update-task, add-task, reconcile, close), tracking plan/task progress across
+  sessions or harnesses, or calling @dreki-gg/taskman as a library. Covers the
+  status-is-a-projection model, stateless plan resolution, and reconcile.
+type: core
+library: "@dreki-gg/taskman"
+library_version: "0.2.1"
+sources:
+  - "dreki-gg/pi-extensions:packages/taskman/README.md"
+  - "dreki-gg/pi-extensions:packages/taskman/src/cli.ts"
+  - "dreki-gg/pi-extensions:packages/taskman/src/engine.ts"
+---
+
+# taskman
+
+`taskman` manages plan/task state on disk under `.plans/` so planning agents
+keep durable progress across sessions and tools. It ships both a CLI (`taskman`)
+and a library (`@dreki-gg/taskman`).
+
+The command and flag inventory is **not** reproduced here — it lives in
+`--help`, which is always current for the installed version:
+
+```bash
+taskman --help            # all commands
+taskman <command> --help  # flags + arguments for one command
+```
+
+This skill teaches the model that `--help` cannot: the data contract and the
+three invariants that decide whether a command does what you expect.
+
+## The ledger
+
+Everything is plain JSONL/Markdown under `.plans/` in the current directory:
+
+- `.plans/plans.jsonl` — plan registry
+- `.plans/initiatives.jsonl` — initiative registry (initiatives group plans)
+- `.plans/<plan>/tasks.jsonl` — one plan's tasks (first line is metadata)
+- `.plans/<plan>/HANDOFF.md`, `.plans/<initiative>/INITIATIVE.md` — prose
+
+## Invariants (read before acting)
+
+1. **Status is a projection of task state, not a manual flag.** A plan becomes
+   `done` when its active tasks are all resolved and no follow-ups remain; an
+   initiative becomes `done` when every member plan is terminal. `update-task`
+   re-derives the registry automatically.
+2. **Plan resolution is stateless.** A command targets a plan via `--plan
+   <name>` (accepts `.plans/<name>`), else the *single* in-progress plan.
+   Ambiguous or missing → non-zero exit listing the candidates.
+3. **Manual terminal statuses are never auto-reverted.** `reconcile` only moves
+   `in-progress ⇄ done`; it never resurrects a `superseded`/`abandoned` plan or
+   regresses a finished one.
+
+## Core Patterns
+
+### Execution loop
+
+```bash
+taskman status                  # active plan + task ids/statuses
+taskman update-task t-003 done  # mark progress; plan status re-derived
+taskman add-task "handle empty input" --reason "found gap while implementing"
+taskman reconcile --apply       # repair safe (in-progress→done) drift
+```
+
+### Machine-readable output
+
+Every command prints human text by default and accepts `--json`:
+
+```bash
+taskman status --json   # { active, plan_name, title, total, counts, task_ids }
+taskman list --json     # array of plan items
+```
+
+### Library usage
+
+```ts
+import { makePlanRuntime, resolvePlanByName, setTaskStatus } from '@dreki-gg/taskman';
+
+const run = makePlanRuntime(); // bridges Effect programs to the live filesystem
+const { planName, planDir, candidates } = await run(resolvePlanByName({ name: 'my-plan' }));
+if (!planDir) throw new Error(`Unresolved; candidates: ${candidates.join(', ')}`);
+await run(setTaskStatus(planDir, 't-001', 'done')); // also reconciles the registry
+```
+
+## Common Mistakes
+
+### HIGH Setting plan status by hand to mark progress
+
+Wrong:
+
+```bash
+taskman close done --plan my-plan   # to "finish" a plan whose tasks are open
+```
+
+Correct:
+
+```bash
+taskman update-task t-007 done      # resolve the tasks; status follows
+```
+
+`close` forces a lifecycle status and is for `superseded`/`abandoned` (or an
+explicit override). For normal completion, resolve the tasks — the `done`
+projection is derived from task state, so a forced `done` will be re-opened the
+moment another task write reconciles the plan.
+
+### HIGH Assuming a bare command finds any plan
+
+Wrong:
+
+```bash
+taskman status   # expecting it to pick "the plan I just finished"
+```
+
+Correct:
+
+```bash
+taskman status --plan my-plan   # name it explicitly when not uniquely in-progress
+```
+
+With no `--plan`, resolution only succeeds when exactly one plan is
+`in-progress`. A just-completed plan is `done`, so it drops out of resolution
+and a bare command exits non-zero — pass `--plan`.
+
+### MEDIUM Treating reconcile as a force-sync in both directions
+
+Wrong:
+
+```bash
+taskman reconcile --apply   # expecting it to flip a done plan back to in-progress
+```
+
+Correct:
+
+```bash
+# A `done` plan with unfinished tasks is reported as downgrade drift, NOT fixed.
+# Resolve it by marking the tasks instead:
+taskman update-task t-004 done --plan my-plan
+```
+
+`reconcile --apply` only performs the safe upgrade (`in-progress → done`). A
+`done`→`in-progress` downgrade almost always means work merged without marking
+tasks; it is surfaced for a human, never auto-applied.
+
+### MEDIUM Expecting add-task to queue active work
+
+Wrong:
+
+```bash
+taskman add-task "refactor parser" --reason "messy"
+# ...then expecting it to show as pending work to do now
+```
+
+Correct:
+
+```bash
+taskman add-task "refactor parser" --reason "messy"   # captured as a deferred follow-up
+# Review/triage later; it is intentionally kept out of the active queue and
+# keeps the plan non-finalizable until resolved.
+```
+
+`add-task` records a `deferred`, `discovered` task — a follow-up for later
+triage, not an active to-do. It does not become pending automatically.