Planning and Tasks

The commands behind Gate 1 and the durable task record. If you are asking "what am I supposed to be doing", orient answers it.

plan

Plan lifecycle. status / check are read-only (the plan Markdown stays the sole authority); approve / archive are the two mutating subcommands and live in their own modules so the read-only path imports no write API.

npx mewkit plan status <plan-dir>       # checkbox progress across plan.md + phase files
npx mewkit plan check <phase-file>      # required-section + checklist report for one phase
npx mewkit plan approve <plan-dir>      # stamp the Gate 1 approval receipt (after a human approves)
npx mewkit plan archive <plan-dir>      # mark completed + move to tasks/plans/archive/
npx mewkit plan archive <plan-dir> --dry-run

plan archive finishes a plan in one step:

• Stamps status: completed in plan.md frontmatter, every phase-*.md frontmatter, and every phases[*].status in .plan-state.json (the plan-creator checkpoint).
• Preserves the CLI-managed .plan-state.json visual block and leaves visual-plan/plan.json untouched — both are lifecycle-agnostic and travel with the directory.
• Clears a dangling active-task pointer that still points at the plan.
• Moves the whole directory into tasks/plans/archive/<name>/ — fail-closed if the destination exists, no-op if already archived.

Agents run it automatically at the end of a completed plan (cook Phase 6). --dry-run previews with zero writes.

task new

Create a new task file from a template.

npx mewkit task new --type <type> "description"

Arguments:

Flags:

Examples:

npx mewkit task new --type feature "Add user authentication"
# Creates: tasks/active/260327-add-user-authentication.feature.md

npx mewkit task new --type bug-fix --priority high "Fix login timeout"
# Creates: tasks/active/260327-fix-login-timeout.bug-fix.md

task list

List task files with status.

npx mewkit task list [--all] [--status <status>]

Flags:

Examples:

npx mewkit task list
# Lists active tasks only

npx mewkit task list --all
# Lists all tasks (active + completed + backlog)

npx mewkit task list --status blocked
# Lists only blocked tasks

task-state show

Reconstruct durable resume state from the task records under tasks/active/ — files only, no network. Marks the record whose plan matches the active-plan pointer as current, and surfaces any incompatible/corrupt record as an issue rather than crashing.

npx mewkit task-state show [--json]

task-state update

Atomically update a durable task record (created for planned / long-running work). Used by orchestration workflows to record status, the last completed step, the next action, and capability decisions so a fresh session can resume. Advisory — a failed write is surfaced but never blocks the workflow.

npx mewkit task-state update <id> [--status <active|blocked|done>] [--step "<what just finished>"] [--next "<next action>"] [--plan <path>] [--json]

Flags:

Examples:

npx mewkit task-state show
# Lists active task records + the current-plan marker

npx mewkit task-state update feat-auth --status active --step "wired login route" --next "add refresh-token test"

advice

Records the checkpoints of an opt-in supervised run — the --advice flag on mk:fix, mk:cook, mk:brainstorming, mk:plan-creator, mk:autobuild and mk:ship. The workflow drives these commands; you rarely type them yourself. They exist as a CLI because the caps, the stage rules and the receipt have to be enforced somewhere the model cannot talk its way past.

Supervision is evidence, not authority. Nothing here clears a gate, and a recorded directive never counts as verification.

npx mewkit advice begin --run <id> --skill <skill> --stage <stage> --checkpoint <id>
npx mewkit advice commit --run <id> --checkpoint <id> --disposition <value> --outcome <value> --reason "<one line>"
npx mewkit advice status --run <id>
npx mewkit advice validate-packet --evidence <file.json> --packet-kind input|output|brief

Subcommands:

Two flags worth understanding:

--release-stage is required by mk:ship and refused by every other skill. Ship's budget is 4 calls per release stage, so a run walking prepare → release → publish is three separate budgets. The stage is fixed when the slot is claimed and inherited by commit.

--correction-kind decides what a returned correction invalidates: source marks downstream verification and review evidence superseded but keeps Gate 1, while scope also returns Gate 1 to required — a plan whose scope moved needs a new human approval.

Examples:

# Open a checkpoint. Repeating the same --checkpoint returns the recorded
# result and spends no slot, which is what makes resume safe.
npx mewkit advice begin --run fix-260727-auth --skill mk:fix --stage GUIDE --checkpoint guide-1

# Record what came back, and what you decided to do with it. --reason is
# required even when you adopted the directive.
npx mewkit advice commit --run fix-260727-auth --checkpoint guide-1 \
  --disposition CONTINUE_WITH_DIRECTIVE --outcome adopted \
  --reason "matches the evidence in the root-cause proof" \
  --directive "fix the guard, not the caller" --next "write the regression test"

# Send work back, and supersede the evidence it invalidated.
npx mewkit advice commit --run fix-260727-auth --checkpoint review-1 \
  --disposition RETURN_TO_EXECUTOR --outcome adopted --reason "coverage gap" \
  --correction "cover the expired-token path" \
  --evidence tasks/plans/260727-auth/reports/evidence/workflow-evidence.json \
  --correction-kind source

# Ship charges each release stage its own budget.
npx mewkit advice begin --run ship-260727 --skill mk:ship --stage GUIDE \
  --checkpoint publish-guide --release-stage publish

npx mewkit advice status --run fix-260727-auth

When it refuses: a call past the cap, an illegal stage/disposition pair, a --checkpoint reused under a different stage, a corrupt dossier, or --evidence pointing anywhere but an existing workflow-evidence.json inside the project. A refusal is final for that checkpoint — continue unsupervised, or escalate when the refusal says to.

visual-plan

Structured visual review for UI-bearing plans. The canonical artifact visual-plan/plan.json (schema visual-plan/v1) is a coverage ledger + canvas (lanes, surface-locked artboards, semantic-HTML wireframes, connectors, annotations). Deterministic subcommands validate and gate it; edit/view serve a transient 127.0.0.1 React studio that renders and edits it.

npx mewkit visual-plan <subcommand> <plan-dir> [flags]

Subcommands

Flags

Security

• The studio server binds 127.0.0.1 only; Host-header guarded against DNS rebinding.
• Strict CSP (script-src 'self'); path traversal blocked on the static server.
• Wireframe HTML is DOMPurify-sanitized at BOTH save and render time via one shared allowlist.
• Writes use optimistic concurrency: PATCH requires If-Match; a stale ETag returns 409.
• Feedback batch ids are charset-validated before any path join; batches + receipts are write-once.

Notes

• If the studio bundle is missing at dist/visual-plan-web/, run npm run build:web in the mewkit package to produce it.
• The deterministic contract commands (validate/status/approve/rehash/prepare-feedback/apply-feedback/patch) run with no browser and no network.

orient

Print where the current task sits in the workflow, and what the next action is.

npx mewkit orient [--json] [--no-record]

Reads plans, reviews, tests, and git state rather than asking you. --no-record skips writing the result to the task record, which is what you want when you are only looking.