tim-hub/powerball-harness / harness/skills/maintenance
maintenance
VerifiedPeriodic housekeeping and session lifecycle management. Use when performing cleanup, pruning, or session commands.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.2 KB |
| references/cleanup.md | markdown | 5.7 KB |
| references/execution-flow.md | markdown | 1.2 KB |
| references/memory-optimization.md | markdown | 1.6 KB |
| references/session-control.md | markdown | 988 B |
| references/state-transition.md | markdown | 2.1 KB |
references/state-transition.md
View on GitHub---
name: state-transition
description: "Execute session state transitions using session-state.sh"
allowed-tools: [Read, Bash]
---
# State Transition
Execute session state transitions.
## Input
Workflow variables:
- `target_state` (string): Target state to transition to
- `event_name` (string): Trigger event
- `event_data` (string, optional): Additional event data (JSON)
## Valid States
| State | Description |
|-------|-------------|
| `idle` | Session not started |
| `initialized` | SessionStart completed |
| `planning` | Preparing for Plan/Work |
| `executing` | /work in progress |
| `reviewing` | Review in progress |
| `verifying` | Build/test in progress |
| `escalated` | Awaiting human confirmation |
| `completed` | Deliverables finalized |
| `failed` | Unrecoverable |
| `stopped` | Stop hook reached |
## Typical Transitions
| From | Event | To |
|------|-------|----|
| idle | session.start | initialized |
| initialized | plan.ready | planning |
| planning | work.start | executing |
| executing | work.task_complete | reviewing |
| reviewing | verify.start | verifying |
| verifying | verify.passed | completed |
| verifying | verify.failed | escalated |
| * | session.stop | stopped |
| stopped | session.resume | initialized |
## Execution
```bash
./scripts/session-state.sh --state <state> --event <event> [--data <json>]
```
### Example: Transition to executing state
```bash
./scripts/session-state.sh --state executing --event work.start
```
### Example: Escalation (with data)
```bash
./scripts/session-state.sh --state escalated --event escalation.requested \
--data '{"reason":"Build failed 3 times","retry_count":3}'
```
## Expected Results
- The `state`, `updated_at`, `last_event_id`, and `event_seq` fields in `.claude/state/session.json` are updated
- An event is appended to `.claude/state/session.events.jsonl`
- Invalid transitions produce an error on stderr + non-zero exit
## Error Handling
When a transition fails (e.g., invalid transition):
1. Output the current state and allowed transitions to stderr
2. Return a non-zero exit code
3. The caller (workflow) handles the escalation
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |