taskmanager-exe 0.1.0__tar.gz

taskmanager_exe-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

taskmanager_exe-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Cache cargo
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/bin/jj
+            ~/.cargo/.crates.toml
+            ~/.cargo/.crates2.json
+          key: cargo-jj-${{ runner.os }}
+
+      - name: Install jj
+        run: command -v jj || cargo install --locked jj-cli
+
+      - name: Configure git
+        run: |
+          git config --global user.email "ci@test.com"
+          git config --global user.name "CI"
+
+      - name: Install package
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest

taskmanager_exe-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Agent files
+.agent-files/
+.claude/
+
+# OS
+.DS_Store
+Thumbs.db

taskmanager_exe-0.1.0/DESIGN.md

@@ -0,0 +1,369 @@
+# TaskManager.exe Design
+
+## Overview
+
+A version-controlled task management system for AI agents. Agents use familiar file editing tools; versioning and sync happen transparently via jj (jujutsu).
+
+**Design philosophy:** Dumb store + automation for things agents forget. Intelligence is wielded by the agent, not baked into the system.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Agent                                    │
+│                           │                                      │
+│              ┌────────────┴────────────┐                        │
+│              ▼                         ▼                        │
+│         Edit tool                 MCP Server                    │
+│         (file ops)                (batch/sync ops)              │
+│              │                         │                        │
+│              ▼                         ▼                        │
+│         raw jj commands           compound workflows            │
+│              │                         │                        │
+│              └────────────┬────────────┘                        │
+│                           ▼                                      │
+│                    .agent-files/                                │
+│                       (jj repo)                                 │
+│                           │                                      │
+│                      push/pull                                  │
+│                           ▼                                      │
+│                  .agent-files.git/                              │
+│                    (bare origin)                                │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Components:**
+
+1. **Agent**: Uses Edit tool for files, raw jj for simple ops, MCP for batch/compound ops
+2. **MCP Server**: FastMCP, in-process, stdio. Only for things that need scripting.
+3. **.agent-files/**: jj repo (can be colocated or non-colocated with git)
+4. **.agent-files.git/**: Bare git origin for worktree sync
+
+**Why clones instead of jj workspaces?**
+
+jj workspaces share a commit graph immediately (no push/pull). But:
+- No natural "source of truth" - all workspaces are peers
+- Race conditions when multiple agents sync simultaneously
+- Bare origin provides serialization: first push wins, second must pull first
+- Explicit sync boundaries via push/pull match our session model
+
+## Repo Structure
+
+```
+repo/
+├── .agent-files.git/          # bare origin (shared across worktrees)
+├── .agent-files/              # jj clone
+│   ├── .jj/                   # jj internals (includes git at .jj/repo/store/git)
+│   ├── STATUS.md
+│   ├── LONGTERM_MEM.md
+│   ├── MEDIUMTERM_MEM.md
+│   └── tasks/
+│       ├── TASK_<slug>.md
+│       └── _archive/
+├── worktree-a/.agent-files/   # another jj clone
+└── worktree-b/.agent-files/   # another jj clone
+```
+
+All clones push/pull to `.agent-files.git/`.
+
+**Colocate vs non-colocate:** Either works. Non-colocated repos store git internally at `.jj/repo/store/git`. Push/pull works identically. Colocate only needed if you want git tools to work directly.
+
+## Task File Format
+
+```markdown
+# TASK: <title>
+
+## Meta
+Status: planned|in_progress|blocked|complete
+Priority: P0|P1|P2
+Created: YYYY-MM-DD
+Completed: YYYY-MM-DD
+
+## Problem
+<what, why>
+
+## Design
+<decisions, alternatives rejected>
+
+## Checklist
+- [ ] item
+- [x] completed item
+
+## Attempts
+<!-- append-only, raw log -->
+### Attempt 1 (YYYY-MM-DD HH:MM)
+Approach: ...
+Result: ...
+
+## Summary
+<!-- distilled on handoff, kept lean -->
+Current state: ...
+Key learnings: ...
+Next steps: ...
+
+## Notes
+<breadcrumbs, file:line references>
+```
+
+## Versioning Model
+
+**jj configuration:**
+```toml
+[ui]
+conflict-marker-style = "git"
+```
+
+**Auto-snapshot:** jj snapshots working copy at start of any jj command. No explicit trigger needed.
+
+**Revision syntax:**
+- `@` = working copy commit
+- `@-` = parent, `@--` = grandparent
+- `bookmark..@` = range from bookmark to working copy
+
+## Sync Model
+
+**Sync at task boundaries only:**
+- Session start: pull
+- `/continue`: pull
+- `/handoff`: push
+- Task complete: push
+
+**Last handoff tracking:** Agent records in STATUS.md: `Last handoff: <timestamp> (rev <id>)`
+
+## CLI (taskman)
+
+```bash
+# Setup
+taskman init                  # create .agent-files.git/ (bare) + .agent-files/ (clone)
+taskman wt                    # in worktree: clone from root's .agent-files.git/
+taskman install <agent>       # install MCP config (claude, cursor, codex)
+taskman install-skills        # install skill files to ~/.claude/commands/
+
+# Operations (used by both MCP and skills)
+taskman describe <reason>                     # create checkpoint
+taskman sync <reason>                         # full sync workflow
+taskman history-diffs <file> <start> [end]    # diffs across range
+taskman history-batch <file> <start> [end]    # versions across range
+taskman history-search <pattern> [file] [mode] [limit]  # search history
+```
+
+## Dual Interface: MCP + Skills
+
+Both interfaces call the same CLI commands:
+
+```
+┌─────────────┐     ┌─────────────┐
+│  MCP tools  │     │   Skills    │
+└──────┬──────┘     └──────┬──────┘
+       │                   │
+       └───────┬───────────┘
+               ▼
+        taskman CLI
+               │
+               ▼
+         jj commands
+```
+
+**MCP Server**: Calls `taskman` subprocess, returns output
+**Skills**: Markdown prompts that run `taskman` via Bash
+
+Same operations available either way. MCP preferred when available (typed params, structured errors), skills as fallback.
+
+## What Agents Use Directly vs MCP
+
+**Use jj directly (no wrapper needed):**
+```bash
+jj status                           # see current state
+jj log                              # view history
+jj log -r 'bookmark..@'             # changes since bookmark
+jj restore --from <rev> <file>      # restore file
+jj op log                           # operation history
+jj op restore <id>                  # restore to operation
+jj diff                             # see changes
+jj git fetch                        # fetch only
+jj git push                         # push only
+```
+
+**Use MCP tools (need scripting/batching):**
+- `describe(reason)` - important checkpoint, ensures snapshot first
+- `sync(reason)` - compound: describe + fetch + rebase + push + conflict check
+- `history_diffs(file, start, end)` - aggregate diffs across range
+- `history_batch(file, start, end)` - fetch multiple file versions
+- `history_search(pattern, file, limit)` - search using jj's `diff_contains()` revset
+
+## Code Architecture
+
+```
+taskman/
+├── core.py      # Core logic (describe, sync, history_*)
+├── jj.py        # jj command utilities
+├── server.py    # MCP server (imports core)
+└── cli.py       # CLI (imports core)
+
+~/.claude/commands/
+├── describe.md      # Skill: runs `taskman describe`
+├── sync.md          # Skill: runs `taskman sync`
+├── history-diffs.md # Skill: runs `taskman history-diffs`
+└── ...
+```
+
+```
+┌─────────────────┐     ┌─────────────┐
+│   MCP server    │     │    CLI      │
+│   (in-process)  │     │ (subprocess)│
+└────────┬────────┘     └──────┬──────┘
+         │ import              │ import
+         └──────────┬──────────┘
+                    ▼
+              taskman/core.py
+                    │
+                    ▼
+              taskman/jj.py
+                    │
+                    ▼
+               jj commands
+                    ↑
+            Skills (bash) ─── taskman CLI
+```
+
+MCP imports core directly (no subprocess overhead). Skills call CLI via bash.
+
+## MCP API
+
+Thin wrappers around sync core functions. FastMCP handles exceptions as tool errors automatically.
+
+```python
+from mcp.server.fastmcp import FastMCP
+from taskman import core
+
+mcp = FastMCP("taskman")
+
+@mcp.tool()
+def describe(reason: str) -> str:
+    """Create named checkpoint."""
+    return core.describe(reason)
+
+@mcp.tool()
+def sync(reason: str) -> str:
+    """Full sync: describe, fetch, rebase, push."""
+    return core.sync(reason)
+
+@mcp.tool()
+def history_diffs(file: str, start_rev: str, end_rev: str = "@") -> str:
+    """Get all diffs for file across revision range."""
+    return core.history_diffs(file, start_rev, end_rev)
+
+@mcp.tool()
+def history_batch(file: str, start_rev: str, end_rev: str = "@") -> str:
+    """Fetch file content at all revisions in range."""
+    return core.history_batch(file, start_rev, end_rev)
+
+@mcp.tool()
+def history_search(pattern: str, file: str = None, limit: int = 20) -> str:
+    """Search history for pattern in diffs."""
+    return core.history_search(pattern, file, limit)
+```
+
+## Skills
+
+Skill files call CLI (which imports core):
+
+**describe.md:**
+```markdown
+Run: taskman describe "$ARGUMENTS"
+```
+
+**sync.md:**
+```markdown
+Run: taskman sync "$ARGUMENTS"
+If conflicts, resolve with Edit, then run again.
+```
+
+**history-diffs.md / history-batch.md / history-search.md:**
+```markdown
+Run: taskman <command> $ARGUMENTS
+```
+
+## Sync Protocol
+
+**sync() implementation:**
+```
+1. jj describe -m "<reason>"     # snapshot + describe
+2. jj git fetch                  # get remote changes
+3. jj rebase -d main@origin      # rebase onto remote
+4. check jj status for conflicts
+   - if conflicts: return conflict info, agent resolves, calls sync() again
+5. jj git push                   # push to origin
+   - if rejected: return error (remote changed, need to sync again)
+```
+
+## Conflict Resolution
+
+With `ui.conflict-marker-style = "git"`:
+
+```
+<<<<<<< side A
+local changes
+||||||| base
+original content
+=======
+remote changes
+>>>>>>> side B
+```
+
+Agent resolves with Edit, calls `sync()` to complete.
+
+## Handoff Types
+
+**handoff_detailed (mid-task):** Comprehensive to avoid repeating mistakes.
+- Attempts: what was tried, what failed
+- Summary: current state, learnings, next steps
+- Notes: breadcrumbs (file:line references)
+
+**handoff_next_task (task complete):** Brief pointer to next task.
+
+**Breadcrumbs principle:** Include enough to reconstruct, not everything.
+
+## Error Handling
+
+Bubble up jj errors to agent. No complex handling - agent decides.
+
+## jj Gotchas
+
+1. **Stale working copy**: If operation interrupted, fix with `jj workspace update-stale`
+2. **Conflicted commits in git**: Appear as `.jjconflict-*/` directories
+3. **Change IDs**: Stored in non-standard git headers, may not survive pure-git ops
+
+## MCP Configuration Locations
+
+**Claude Code:**
+- Global: `~/.claude.json`
+- Project: `.mcp.json`
+- Format: JSON with `mcpServers` key
+
+```json
+{
+  "mcpServers": {
+    "taskman": {
+      "type": "stdio",
+      "command": "taskman",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+**Cursor:**
+- Global: `~/.cursor/mcp.json`
+- Project: `.cursor/mcp.json`
+- Format: JSON with `mcpServers` key (same structure as Claude)
+
+**Codex:**
+- Global: `~/.codex/config.toml`
+- Format: TOML with `mcp_servers` key (underscore, not hyphen)
+
+```toml
+[mcp_servers.taskman]
+command = "taskman"
+args = ["serve"]
+```

taskmanager_exe-0.1.0/LICENSE

@@ -0,0 +1,3 @@
+This is 100% (or maybe 99.5%) AI-generated code. It is free! You may do with it what you want!
+
+I TAKE ZERO RESPONSIBILITY FOR ANYTHING THIS CODE DOES! IT IS SLOP!

taskmanager_exe-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: taskmanager-exe
+Version: 0.1.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: mcp
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'

taskmanager_exe-0.1.0/PROMPT.md

@@ -0,0 +1,116 @@
+# TaskManager.exe
+
+Build a task management system for AI agents.
+
+## Problem
+
+AI agents using file-based task systems lose work when:
+- Multiple agents edit the same file
+- Agent context resets mid-task and overwrites with stale state
+- No history to recover from
+- **Agents go in circles** - after context reset, they repeat the same mistakes because they don't know what was already tried
+
+## Use Cases
+
+### Single agent, single repo
+Agent works on tasks, context resets periodically. Need to preserve what was tried.
+
+### Multiple agents, worktrees
+Multiple agents work in different git worktrees of same repo. Each has own `.agent-files/` that should sync with others. Agents shouldn't trample each other's work.
+
+## Task System Structure
+
+```
+.agent-files/
+  STATUS.md           # Task index, current session state, blockers, next steps
+  LONGTERM_MEM.md     # Architecture knowledge (stable for months)
+  MEDIUMTERM_MEM.md   # Patterns, gotchas (stable for weeks)
+  HANDOFF_<slug>.md   # Handoff prompts between sessions
+  tasks/
+    TASK_<slug>.md    # Individual tasks with status, checklist, notes
+    _archive/         # Completed tasks
+```
+
+**Task file format:**
+```markdown
+# TASK: <title>
+
+## Meta
+Status: planned|in_progress|blocked|complete
+Priority: P0|P1|P2
+Created: YYYY-MM-DD
+
+## Problem
+<what, why>
+
+## Design
+<decisions, alternatives>
+
+## Checklist
+- [ ] item
+- [x] completed item
+
+## Attempts
+<!-- append-only log of what was tried -->
+### Attempt 1 (YYYY-MM-DD HH:MM)
+Approach: ...
+Result: ...
+
+## Summary
+<!-- distilled on handoff, kept lean -->
+Current state: ...
+Key learnings: ...
+Next steps: ...
+
+## Notes
+<gotchas, breadcrumbs>
+```
+
+## Requirements
+
+### Core
+- Version every file change automatically
+- Expose history queries via API (raw git is too heavy, agents forget to use it)
+- MCP server (in-process, stdio transport). Recommend FastMCP but open to alternatives.
+- Agents should keep using Edit tool for file ops (familiar, low friction)
+
+### Handoff Requirements
+
+Need two handoff modes with different verbosity:
+- **Mid-task handoff**: Comprehensive context to avoid next session repeating mistakes
+- **Task complete handoff**: Brief pointer to next task (avoid memory bloat)
+
+### Breadcrumbs Principle
+
+Don't include all context in handoffs. Include enough that a clean session can reconstruct what's needed - references with short summaries, not full content.
+
+### Backing Store Options
+
+**jj (jujutsu):**
+- Working copy is always a commit (automatic snapshotting)
+- Simpler model than git (no staging area)
+
+**git:**
+- Ubiquitous
+- Heavier (commit messages, staging area)
+
+**Alternative:** Each `.agent-files/` is a cloned repo that agents push/pull. Downside: commit messages and merge conflicts burn tokens.
+
+### Edit Tool Compatibility
+
+Agents know the Edit tool well. Ideal: keep using Edit, get versioning "for free."
+
+Options:
+1. MCP tools for everything (agents learn new API)
+2. Edit tool + background auto-commit watcher
+3. Edit passthrough via MCP
+4. Just use git directly (heavy)
+
+## Open Design Questions
+
+1. jj vs git?
+2. MCP API for writes, or let agents use Edit?
+3. How to surface history to agents who forget to query it?
+4. Atomic multi-file commits - needed?
+5. What triggers commit? (every write, debounced, explicit)
+6. Worktree sync model - workspaces vs clones?

taskmanager_exe-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "taskmanager-exe"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+    "mcp",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[project.scripts]
+taskman = "taskman.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["taskman"]

taskmanager_exe-0.1.0/skills/describe.md

@@ -0,0 +1,5 @@
+Create a named checkpoint in .agent-files.
+
+Run: taskman describe "$ARGUMENTS"
+
+Report the revision ID.

taskmanager_exe-0.1.0/skills/history-batch.md

@@ -0,0 +1,7 @@
+Fetch file content at all revisions in range.
+
+Arguments: <file> <start_rev> [end_rev]
+
+Run: taskman history-batch $ARGUMENTS
+
+Display the output.

taskmanager_exe-0.1.0/skills/history-diffs.md

@@ -0,0 +1,7 @@
+Get all diffs for a file across revisions.
+
+Arguments: <file> <start_rev> [end_rev]
+
+Run: taskman history-diffs $ARGUMENTS
+
+Display the output.

taskmanager_exe-0.1.0/skills/history-search.md

@@ -0,0 +1,13 @@
+Search history for a pattern in diffs.
+
+Arguments: <pattern> [--file <file>] [--limit N]
+
+Pattern syntax (jj native):
+- Default: glob match
+- regex:pattern - regex match
+- exact:pattern - exact match
+- substring:pattern - substring match
+
+Run: taskman history-search $ARGUMENTS
+
+Display matching revisions.

taskmanager_exe-0.1.0/skills/sync.md

@@ -0,0 +1,5 @@
+Sync .agent-files with origin.
+
+Run: taskman sync "$ARGUMENTS"
+
+If conflicts are reported, help the user resolve them with Edit, then run sync again.