windowmaker-wl/tools/wm-port/SUMMARY.md

tools/wm-port/ — 6 scripts + 1 data file

Architecture

                    ┌─────────────┐
                    │ ACTION_PLAN │  task descriptions
                    │     .md     │  (file, lines, operation)
                    └──────┬──────┘
                           │ extract_task_block()
                           ▼
┌──────────┐     ┌─────────────────┐     ┌───────────────┐
│ task-map  │────▶│  wm-dispatch    │◀────│ ACTION_PLAN   │
│   .sh    │     │                 │     │ _PROMPTS.md   │
│ ID→T,W,B │     │ compose prompt  │     │ (templates)   │
└──────────┘     │ spawn agent     │     └───────────────┘
                 └────────┬────────┘
                          │  $OLLIE/s/b
                          ▼
                 ┌─────────────────┐
                 │  ollie session  │  wm-port-{task-id}
                 │  (coding agent) │  creates port/{id} branch
                 └────────┬────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
    ┌──────────┐   ┌──────────┐   ┌──────────┐
    │wm-status │   │wm-review │   │ wm-kill  │
    │ monitor  │   │ diff/    │   │ abort    │
    │ --watch  │   │ approve  │   │ session  │
    └──────────┘   └──────────┘   └──────────┘

Scripts

Script	What you type	What happens
wm-tasks	wm-tasks	Task board: 52 tasks grouped by wave, colored by status (✓ done, ○ ready, ● running, • blocked)
wm-dispatch	wm-dispatch B.1	Extracts task B.1 from ACTION_PLAN.md, matches to Template 3, composes full prompt with reference tables, spawns a coding agent session
wm-status	wm-status --watch	Live dashboard of all running wm-port-* sessions, refreshing every 2s
wm-review	wm-review B.1	Interactive review: shows diff, agent status, then prompts for approve/reject/edit/skip
wm-done	wm-done G.1	Manually mark verification tasks done (or --undo to reopen)
wm-kill	wm-kill --all	Kill stuck agent sessions

Your typical session

export PATH="$PWD/tools/wm-port:$PATH"

# 1. See what's ready
wm-tasks --ready

# 2. Dispatch (pick one)
wm-dispatch B.1                          # single, foreground (wait for result)
wm-dispatch --bg A5.1 B.1 B.3 C.1       # batch, background
wm-dispatch --wave 1 --bg               # entire wave 1 in parallel
wm-dispatch --next 5 --bg               # next 5 unblocked tasks

# 3. Monitor (in another terminal)
wm-status --watch                        # dashboard
wm-status --follow B.1                   # tail one agent's chat

# 4. Review
wm-review --pending                      # list branches ready
wm-review B.1                            # interactive: [a]pprove [r]eject [d]iff [l]og [e]dit [s]kip

# 5. Repeat
wm-tasks                                 # updated board, blockers auto-resolved

Key design decisions

• No template variable filling — the prompt includes both the raw task block and the template procedure. The agent connects them. This is more robust than regex substitution on {{FILE}} placeholders, and the agent handles it trivially.
• Git branch per task — the agent creates port/{id} branches, keeping main clean. wm-review merges on approve.
• done.txt is the single source of truth — one task ID per line. Blocker resolution is computed from this file. wm-review --approve appends automatically.
• --dry-run prints the exact prompt that would be sent, so you can inspect/tweak before committing API tokens.
• Foreground vs background — foreground (wm-dispatch B.1) blocks until done and auto-parses DONE/STOP/FAIL from the agent's output. Background (--bg) returns session paths immediately for monitoring.