Improve Workflow

Work in the main context; do not fork. This loop drives the Workflow tool, a Monitor, and task notifications, which only the main loop can orchestrate (a subagent cannot spawn subagents).

Input: $ARGUMENTS is the workflow name followed by a concrete input to run it on.

1. Run

• Start any precondition the workflow assumes (for example npm run dev for a stage that drives the browser) and confirm it is up before launching.
• Launch the workflow with the Workflow tool, passing the concrete input as args. Keep the transcript dir and runId from the result.
• If the workflow launches freshly generated agents by agentType, reload first. A mid-session agent file does not register: agent({agentType}) resolves against the registry frozen at session start.

2. Observe without flooding context

• Arm a tree-change Monitor for a stage-by-stage play-by-play: poll git status --short and emit when the changed-file set changes.
• Read /journal.jsonl. It maps each agentId to its started and result records and holds each stage's return value, so it is the spine of the run.
• For stage detail, grep the per-stage agent-*.jsonl. Never read one whole: a subagent transcript is the full conversation and overflows context.

3. Verify the assumptions

• Gates fire: grep transcripts for gate not satisfied. A passing gate is silent, so absence proves nothing. To prove a gate fires, catch a stage that stops while its gate is unsatisfied, or run a throwaway probe agent whose gate appends to a log file (always exit 0 so it cannot loop), and reload so its agentType resolves.
• Structured returns thread and branch: read the verdict objects in the journal and confirm the workflow looped or broke on them as intended.
• Parallel stages overlap: in the journal, two stages show started before either shows result.
• The end state is real: run the check the workflow claims to enforce against the working tree.

4. Diagnose

For anything that did not progress as intended, trace it to the exact stage, agent, or workflow line, reading that one transcript with targeted greps.

5. Improve and propagate

• Fix the workflow, its agents, and its skills.
• Lift every general lesson into the build-workflow generator templates, so the next workflow it scaffolds embodies the fix instead of repeating the mistake.
• Re-run to confirm, then discard drill artifacts unless a commit stage recorded them on purpose.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hackersandwizards
• Source: hackersandwizards/artificer
• License: MIT
• Homepage: https://www.hackersandwizards.dev/factory

Install and usage instructions live in the source repository linked above.