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_<slug>.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_<slug>.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