work-in-time

A Claude Code plugin repo that provides file-based work item tracking. Ships two independent plugins: work (main -- skills + advisory hook) and work-auto-hooks (companion -- auto-scaffolds docs/work/ on session start). Work items persist as markdown files across sessions, unlike the built-in ephemeral TaskCreate/TaskUpdate tools.

Plugins

Plugin	Description
work	Interactive work item tracking skills + advisory PostToolUse hook
work-auto-hooks	Automatic docs/work/ scaffolding on SessionStart

Install independently or together.

Skills

Skill	Invocation	Purpose
track	/work:track	Create, start, complete, park, shelve, block, view persistent work items
list	/work:list	Display formatted summary of all tracked work items

Hooks

Hook	Event	Behavior
advise_persist.sh	PostToolUse:TaskCreate	Advisory reminder (never blocks) to persist ephemeral session tasks to files
scaffold_work_dir.sh	SessionStart	Creates docs/work/{backlog,chosen,engaged,finished,parked,shelved}/ and .archive/ if missing

Installation

Add the marketplace and install:

claude plugin marketplace add git@github.com:tgrnd/work-in-time.git
claude plugin install work@work-in-time --scope user
claude plugin install work-auto-hooks@work-in-time --scope user

Update to the latest version:

claude plugin marketplace update work-in-time
claude plugin update work@work-in-time
claude plugin update work-auto-hooks@work-in-time

Versioning

Versions use semver in plugin.json and are tagged in git. Keep them in sync:

1. Bump version in both plugins/work/.claude-plugin/plugin.json and plugins/work-auto-hooks/.claude-plugin/plugin.json
2. Commit: git commit -m "release: vX.Y.Z"
3. Tag: git tag vX.Y.Z
4. Push: git push && git push --tags

Claude Code reads the version from plugin.json, not git tags. Tags are for release tracking and changelog generation.

Migration

After installing the work plugin, remove the PreToolUse:TaskCreate prompt hook from ~/.claude/settings.json if present. The advisory PostToolUse command hook in this plugin replaces it with a non-blocking approach that outputs JSON with additionalContext instead of injecting prompts.

Work Item File Format

Each work item is a markdown file with YAML frontmatter:

---
status: pending | ready | started | done | paused | retired | ...
created: YYYY-MM-DD
updated: YYYY-MM-DD
blocked-by: []
---

# Work Item Title

## Goal

What needs to be accomplished.

## Acceptance Criteria

- [ ] Criterion one
- [ ] Criterion two

## Notes

Progress, decisions, blockers.

Filename convention: YYYY-MM-DD-<item-name>.md (date is creation date).

Directory Structure

docs/work/
├── .archive/         # Hidden — old/stale items, excluded from searches (status preserved)
├── backlog/          # Potential work, on the horizon (default: pending)
├── chosen/           # Selected work, in current cycle (default: ready)
├── engaged/          # Active work, ongoing now (default: started)
├── finished/         # Completed successfully (default: done)
├── parked/           # On hold, intending to resume (default: paused)
└── shelved/          # Removed, no further action (default: retired)

Work items move through the lifecycle: backlog → chosen → engaged → finished. Items can be parked (paused with intent to resume) or shelved (removed, no further action) from any non-terminal state, or archived to .archive/ when too old to clutter active views. Files are moved using git mv to preserve history.