Skip to content

tim-hub/powerball-harness / harness/skills/maintenance

maintenance

Verified

Periodic housekeeping and session lifecycle management. Use when performing cleanup, pruning, or session commands.

Maintenance

Periodic housekeeping skill for Harness projects. Handles stale state file removal, plugin cache purging, and orphaned worktree cleanup.

Quick Reference

SubcommandWhat It Does
--clear-stateRemove stale files from .claude/state/
--purge-cacheClear the plugin cache from ~/.claude/plugins/cache/
--clean-worktreesRemove git worktrees with no associated branch
--allRun all of the above in sequence

When to Use

Run /maintenance when any of the following apply:

  • .claude/state/ contains loop-active.json but no loop is running
  • Old sprint contracts from completed phases are cluttering .claude/state/contracts/
  • git worktree list shows entries for branches that have been deleted
  • The plugin cache has grown stale after a Harness version upgrade

Operations

--clear-state

Scans .claude/state/ and removes files that are safe to delete:

  • loop-active.json — only if no Breezing/harness-work loop is currently running
  • Sprint contract files (*.sprint-contract.json) for tasks marked cc:Done in Plans.md
  • Stale review-result.json files older than 7 days

Will not touch: Active loop state, pending fix proposals, or the contracts/ directory itself.

--purge-cache

Removes the plugin cache directory at ~/.claude/plugins/cache/. The cache is rebuilt automatically on next plugin load. Use after a major Harness version upgrade if stale cached files are causing unexpected behavior.

--clean-worktrees

Lists all git worktrees (git worktree list) and removes entries where the associated branch no longer exists in the repository.

Safe: uses git worktree remove --force only on worktrees confirmed to have no live branch.

Safety Guarantees

  • All operations print a dry-run summary before making changes
  • Destructive operations (--purge-cache) require explicit confirmation
  • Operations never touch files outside their defined scope
  • The main working tree is never modified

Execution Details

See ${CLAUDE_SKILL_DIR}/references/cleanup.md for step-by-step execution procedures for each subcommand.


Session Lifecycle

Consolidates session-related subcommands: listing, inbox checks, and broadcasting.

User InputBehavior
session listShow all active Claude Code sessions in the current project
session inboxCheck for incoming messages from other sessions
session broadcast "message"Send a message to all active sessions

session list

Shows all active Claude Code sessions in the current project.

Active Sessions

| Session ID | Status | Last Activity |
|------------|--------|---------------|
| abc123     | active | 2 min ago     |
| def456     | idle   | 15 min ago    |

session inbox

Checks for incoming messages from other sessions.

Session Inbox

| From   | Time    | Message            |
|--------|---------|---------------------|
| abc123 | 5m ago  | "Ready for review"  |

session broadcast "message"

Sends a message to all active sessions.

For memory optimization, session lifecycle details, and state transitions, see:


Related Skills

  • harness-plan archive — Archive completed phases from Plans.md (not the same as maintenance)
  • harness-work — Implementation; run maintenance before long breezing sessions
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 197kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall