taskman

name	taskman
description	Agent memory and task management CLI. Use this skill when you need to persist context across sessions, track tasks, hand off work, or store temporary agent scratch data. Provides the `taskman` CLI for init, sync, describe, and history operations.

Taskman

Version-controlled agent memory and task management. The .agent-files/ directory is local scratch space for agent work that persists across sessions - task tracking, memory, handoffs, notes, or temporary files.

Architecture

.agent-files/ is a standalone jj git repo, separate from the project's VCS (add to .gitignore). Created by taskman init.

• Workspaces: When the project uses git worktrees, each worktree gets its own jj workspace in the .agent-files/ repo via /wt. Commits are visible across workspaces via jj log (no push/pull), but must be merged to combine changes.
• Bookmarks: Each workspace has its own jj bookmark (e.g., default, feature-x). /sync checkpoints the current state and advances the workspace bookmark.

NEVER reference .agent-files content from tracked files or commit messages.

Structure

.agent-files/
  STATUS.md           # Shared task index, priorities, blockers
  LONGTERM_MEM.md     # Architecture knowledge (months+)
  MEDIUMTERM_MEM.md   # Patterns, learnings, index for memory topics
  handoffs/
    HANDOFF_<slug>.md # Per-agent session context
  topics/
    TOPIC_<slug>.md   # Topic-specific knowledge (agent-organized)
  tasks/
    TASK_<slug>.md    # Active tasks
    _archive/         # Completed tasks

STATUS.md: Shared operational state - task index, priorities, current focuses, cross-agent blockers. Multi-agent safe.

Staleness check: Use the Updated: field in task Meta to gauge staleness. Tasks untouched for weeks may need re-evaluation or archival. Note: file mtime is unreliable after jj merges/workspace updates (jj rewrites working copy, resetting mtime).

handoffs/: Per-agent handoff files. Use /continue <slug> and /handoff <slug> with your agent name.

LONGTERM_MEM.md: System architecture, component relationships. Rarely changes.

MEDIUMTERM_MEM.md: Reusable patterns and learnings. Index pointing to topics. NOT session logs

topics/: Topic files. Agent organizes as needed. Use TOPIC_.md for findability.

Task files: One per user-facing work unit. See Task Format below.

Topic-Based Memory

MEDIUMTERM_MEM.md should be an index, not a dump. When content grows:

• Extract related entries to topics/TOPIC_.md
• Keep MEDIUMTERM as index + cross-cutting patterns only

Topic File Format

Agent-optimized, dense:

# <topic>
updated: YYYY-MM-DD @ <commit>

## <entry>
problem: <one line>
fix: <one line>
check: <command to verify>
refs: <file:line, other.md#section>

Agents can adapt structure as needed. The key properties:

• Dense: keywords over prose (problem: not "The problem we encountered was...")
• Validation paths: check: field - how to verify this still holds
• Refs: Enable reconstruction, not just reference

Index Format

# Memory Index

## Topics
| slug | description | updated |
|------|-------------|---------|
| jj-gotchas | jj CLI pitfalls | 2024-01-26 |

## Cross-Cutting
<patterns spanning topics - keep lean>

Example Organizations

Agents can create subdirectories as needed:

topics/
  TOPIC_jj_gotchas.md       # flat - simple topics
  TOPIC_release_workflow.md
  
  perf/                     # grouped - related investigations
    TOPIC_checkpoint_sizing.md
    TOPIC_api_latency.md
  
  reviews/                  # council/subagent outputs
    TOPIC_api_redesign.md
  
  design/                   # design explorations, prototypes
    TOPIC_new_sync_model.md
  
  decisions/                # architectural decision records
    TOPIC_async_vs_sync.md

Example groupings (not prescriptive - organize however makes sense):

• perf/ - benchmarks, optimization experiments
• reviews/ - council outputs, code review findings
• design/ - design explorations, API sketches, prototypes
• decisions/ - why we chose X over Y
• bugs/ - root cause analyses, postmortems

Heuristic: keep flat until 5+ related files, then group.

Task Format

# TASK: <title>

## Meta
Status: planned|in_progress|blocked|complete
Priority: P0|P1|P2
Created: YYYY-MM-DD
Updated: YYYY-MM-DD
Completed: YYYY-MM-DD

## Problem
<what, why>

## Design
<decisions, alternatives rejected>

## Checklist
- [ ] item
- [x] completed item

## Attempts
### Attempt N (YYYY-MM-DD HH:MM) @ <commit>
Approach: ...
Result: ...

## Summary
Current state: ...
Key learnings: ...
Next steps: ...

## Notes
<breadcrumbs - pointers to recoverable info>

## Budget (optional)
Estimate: <tokens> (planning: X, impl: Y, validation: Z)
Variance: low|med|high
Intervention: autonomous|checkpoints|steering|collaborative
Spent: <tokens>

Include commit SHA or jj change-id in Attempt headers to anchor work to specific repo state.

Budget uses tokens (measurable) not time. Variance = estimate spread (low=tight, high=wide). Intervention = human engagement pattern, not duration.

Scratch space: .agent-files/ can store any temporary agent work - it's version-controlled separately from the main repo.

Progressive Disclosure

Use the principle of progressive disclosure!

Store pointers, not content. Recover on-demand via read/bash/curl.

Format: <slug>: <recovery-instruction>

Examples:

• auth-flow: src/auth/login.ts:45-80
• build-status: run make build
• prev-attempt: jj diff -r @--
• issue: github.com/org/repo/issues/123 (curl/WebFetch)

HOW > WHAT: Breadcrumbs should enable reconstruction, not just reference.

• Bad: fixed checkpoint bug
• Good: checkpoint-bug: TOPIC_perf.md#sizing (off-by-one in depth calc)

Include validation paths: How to verify a conclusion still holds.

Store inline only: Decisions, key insights, non-reproducible errors.

See /handoff for writing breadcrumbs, /continue for expanding them.

Commands

Command	Use when
/init	First time setup - creates .agent-files/ in project
/continue	Resuming work from a previous session
/handoff	Saving context mid-task for next session
/remember	Persisting learnings to memory/topics
/compact	Memory maintenance, pruning, reorganizing
/complete	Finishing and archiving a task
/sync	Checkpoint and advance workspace bookmark
/describe	Creating a named checkpoint
/history-search	Searching history for patterns
/history-diffs	Viewing diffs across revisions
/history-batch	Fetching file content at revisions
/wt	Setting up .agent-files in a git worktree
/wt-list	Listing worktrees with health status
/wt-rm	Removing a worktree and cleaning up state
/wt-prune	Cleaning up orphaned worktree state

When a command is invoked, read the corresponding .md file in this skill directory for detailed instructions. /wt-list, /wt-rm, and /wt-prune are documented in wt.md.

jj Snapshotting

jj does NOT auto-snapshot on file changes alone. A jj command must be run to trigger a snapshot. Run jj st periodically (after edits or batches of edits) to capture history. Without this, intermediate states are lost. Scripts can force a snapshot with jj util snapshot.

Recovery: jj snapshots repo state on every operation. If an operation goes wrong (botched merge, bad rebase, etc.), previous state is recoverable for as long as the op log retains it (default: 2 weeks, pruned by jj util gc). Use jj op log + jj op restore OP_ID to recover. Unsnapshotted working-copy edits are the one exception. Read the jj skill before assuming changes are gone.

jj workspace update-stale — use with care

Not data-destroying, but easy to misread. It snapshots your current working-copy edits onto the stale op (so they're preserved), then checks out the desired @. Your edits survive — they just live on a side branch in the op-log DAG, which is easy to mistake for "lost".

With snapshot.auto-update-stale = true, the same path runs automatically whenever any command would snapshot.

Recovery / inspection:

• jj op log — follow the graph edges; the branch merging back into @ is the snapshot op holding your edits.
• jj --at-op=<snapshot-op-id> diff — see what was captured.
• jj op restore <snapshot-op-id> — bring those edits back; then cherry-pick/merge into desired @.
• jj undo immediately after update-stale rewinds the whole thing.

When to prefer manual recovery: if the divergence is large or confusing,

1. jj op log — find a known-good op before the concurrent move.
2. jj op restore OP_ID — roll back.
3. Re-apply intended changes explicitly.

See jj skill gotchas for the full mechanics.

Important

• NEVER reference .agent-files content from tracked files or commit messages
• Treat as untracked local work - may contain session-specific context, internal task names, or scratch notes that don't belong in the project history