workflow-tracker

Files (6)

• SKILL.md
• workflow-tracker.ts · pi/
• hook_prompt.sh · scripts/
• hook_session_start.sh · scripts/
• steps.sh · scripts/
• wire_hooks.sh · scripts/

SKILL.md (first lines)

# workflow-tracker

A step chain reported in the conversation, driven by explicit CLI calls. Nothing is
inferred: you tell it the phases, mark them as you go, and post the chain after each mark.

Symbols: `✓` done · `●` in progress · `○` planned · `✗` failed. An active step may carry
a detail after `|` (e.g. `loop|check agent status`).

## How to use (Claude Code and pi)

`STEPS` below means `bash <this skill's dir>/scripts/steps.sh`. The Skill tool prints the
base directory of this skill when loaded; installed as a plugin it is
`${CLAUDE_PLUGIN_ROOT}` (Codex: `${PLUGIN_ROOT}`), as a symlinked skill it is
`~/.claude/skills/workflow-tracker`, under pi (run as oh-my-pi) it is `~/.omp/agent/skills/workflow-tracker`. Run it via the Bash tool from the project root — state
lives in `./.step-status/` (self-ignoring; each session gets a tracker of its own, see below).

1. **At the start** of a multi-step workflow, define the chain once, naming it for the task
   with `--name`. That name is the `[bracket]` label on every ticker line, so pick something
   descriptive (`add-plugin`, `fix-auth`) — never leave it as `default`. The first step
   becomes active:
   ```bash
   STEPS set --name add-plugin init loop summary   # → [add-plugin] init ● → loop ○ → summary ○
   ```
2. **On each transition**, run the command and **post the line it echoes in your reply**,
   on its own line, before continuing — that message *is* the progress indicator. The
   user may not see tool output, so a transition you do not quote is invisible.
   ```bash
   STEPS done init                          # ✓ init, auto-activates loop
   STEPS start loop "check agent status"    # optional detail → loop|check agent status ●
   STEPS done loop                          # ✓ loop, auto-activates summary
   STEPS fail summary                       # ✗ if a step blows up
   ```
   Progress moves **only** through `done`/`start`/`fail`. Never re-run `set` to record it: `set`
   restarts the chain, and it refuses status-looking step names such as `init:done` or `loop ✓`.
   There is no `advance` or `next` command. `done <step>` already activates the next step.
3. **At the end**: post the finished chain as the last progress line. There's no need to clear it.
   A chain is finished when no step is active: all `✓`, stopped at a `✗`, or the last step done past a
   skipped `○`. A minute after its last update (`STEP_STATUS_DONE_TTL`, in seconds), it stops rendering
   on the map and in the next prompt. `start`/`done`/`fail`/`msg` then refuse it, and a
   bare `set` starts `default` instead of overwriting it, so the next workflow always runs `set --name`
   for its own chain. Its files stay, and `list` shows it as history (`use` marks it `(finished)`).
   A chain with an active step never expires, and neither does a loop (a chain you have `cycle`d):
   it ends only with `set` or `clear`. Session starts and compaction preserve the chain and
   reinject tracking instructions.

### Sessions: one tracker per session

Two sessions in one directory must not read or advance each other's chain, so the tracker keeps one
per session. `STEP_STATUS_SESSION` names the session; state then lands in
`.step-status/sessions/<id>/`, with its own `current`, its own chains, notes and `✗` marks. A session
sees and moves only its own workflow. The harness sets that key for the session's own tools: pi's
extension exports `STEP_STATUS_SESSION` (pi spawns the session's tools from its own process, so they
inherit it) and passes the session id to the prompt hook; Claude Code's `SessionStart` hook appends
`export STEP_STATUS_SESSION=<id>` to `$CLAUDE_ENV_FILE`, which Claude Code applies to the session's Bash
tool. So the prompt line, the map and the agent's own `steps.sh` calls all agree on which
workflow is this session's. PenguPool's own extension exports the same session id, so a session
whose pi extension predates this still keys correctly. Without a valid key — a script, cron, a human at a shell, a harness that
sends no session id — the shared `.step-status/` is used, exactly as it always was, and that is where
chains predating this live. `list` shows the session's chains first, then the shared ones labelled
`shared `.

```bash
STEPS list                                     # mine, then the repo's shared chains
STEPS --shared list                            # only the shared tracker, whatever the environment says
STEPS --session <id> render                    # one call against another session's tracker
STEPS --shared clear                           # clear the repo's shared chain, not mine
```

`--session <id>` and `--shared` win over the environment for that one call. A session id is letters,
digits, `.`, `_`, `-` (it becomes a directory name); anything else is ignored and the shared tracker is
used, so a mangled or hostile id can never leave the state directory.

A session tracker that nothing has touched for 14 days (`STEP_STATUS_SESSION_TTL`, days) is pruned by
the next `set`, so `.step-status/sessions/` does not grow one directory per session forever. `list
--all` adds the other sessions' chains, labelled `session/<id>`, when you need to see what they are
working on; plain `list` stays yours plus the shared chains.

### Messages between sessions

When a workflow talks to another session (SendMessage or a pi-intercom send/ask out, a
`<cross-session-message>` or an intercom message in), record it on the active step and post the echoed line, so
the ticker shows the hand-off and the reply, not just a step that seems stalled:

```bash
STEPS msg sent RCM-info-2099 "asked for step-status diagnostics"   # → ask|⇢ RCM-info-2099: asked for … ●
STEPS msg recv RCM-info-2099 "cwd + state reported"                # → ask|⇠ RCM-info-2099: cwd + state reported ●
```

`sent` renders as `⇢ session`, `recv` as `⇠ session`; the detail is replaced by the latest
message, so a step waiting on another session always shows what it is waiting for. Once the
reply is handled, `done` the step as usual (or `start <step> "<detail>"` to overwrite).

### Named chains (several workflows in one session)

Every chain has a name and every rendered line starts with it in brackets, so the user can
always tell which workflow a ticker line belongs to. `set --name <name>` names the current
chain as you define it (the one-command form used above); `use <name>` switches to (or
creates) another. Use a distinct `use` when the user is likely to come back to a thread
after doing something else (a PR review, a migration, an investigation):

```bash
STEPS use pr-42                          # switch to (or create) chain "pr-42"; renders as [pr-42] …
STEPS set triage fix verify              # chains are independent — set/done/clear act on the current one
STEPS note "PR 42: flaky test in auth"   # one-line context so you can pick the thread up later
STEPS list                               # * marks current:  * [pr-42] triage ✓ → fix ● → verify ○  # PR 42: …
STEPS use default                        # switch back; pr-42 keeps its state
```

Context switching: when the user changes topic ("back to the PR", "park this, look at X"),
`STEPS list`, then `STEPS use <name>` for the chain that matches (or create one). Read the
note and the rendered chain aloud in one line so the user knows where that thread stopped,
then continue from the active step. Before leaving a chain, `STEPS note` what the next
action is. `STEPS clear` removes only the current chain; a fresh session (startup/clear)
removes all of them.

### Loops (`/loop`, polling, retry cadences)

A linear chain marks each step done once — wrong shape for a workflow that repeats. For a
loop, name the repeating steps as a *segment* with `cycle`; they bracket off with a `↻N`

From nduwork/pengupool, MIT.

More from nduwork/pengupool