Agent Skills: Taskman

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.

Recovery: jj snapshots repo state on every operation. If an operation goes wrong (botched merge, bad rebase, etc.), changes are never lost. Use jj op log + jj op restore OP_ID to recover. Read the jj skill before assuming changes are gone.

NEVER Use jj workspace update-stale

jj workspace update-stale is banned. Do not run it.

update-stale snapshots the current working copy first, then merges divergent operations, then checks out the desired commit. Unsaved edits are preserved in the snapshot and recoverable via jj op log.

Sequence:

1. Edit files in working copy (no jj command run → no snapshot yet)
2. @ moves via another workspace or concurrent operation
3. jj workspace update-stale → snapshots edits onto old operation, merges, updates working copy

Recovery (if someone ran it anyway): If edits appear lost after update-stale, they were captured in the snapshot operation. Use jj op log + jj op restore OP_ID to recover.

Instead of update-stale, if a workspace is stale:

1. Check jj op log to understand what diverged
2. Use jj op restore OP_ID to get back to a known-good state
3. Re-apply changes manually from there

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