Skill: unit-executor

Goal

• Execute one unit end-to-end and leave the workspace in a consistent state.

Inputs

• UNITS.csv

• Unit inputs listed in the row (files)

Outputs

• Unit outputs listed in the row (files)

• Updated UNITS.csv status (TODO → DOING → DONE/BLOCKED )

• Optional: STATUS.md updated

Procedure (MUST FOLLOW)

• Load UNITS.csv and find the first unit with:

• status=TODO

• all depends_on units are DONE

• Set its status to DOING and persist UNITS.csv .

• Run the referenced skill (by following that skill’s SKILL.md ).

• Check the unit’s acceptance against produced artifacts.

• If acceptance passes, set status to DONE ; otherwise set to BLOCKED with a short note in STATUS.md .

• Stop after one unit (do not start the next unit automatically).

Acceptance criteria (MUST CHECK)

• Exactly one unit changes from TODO to DONE/BLOCKED (via DOING ).

• Output files exist (or acceptance explicitly allows otherwise).

Side effects

• Allowed: edit workspace artifacts (UNITS.csv , STATUS.md , unit outputs).

• Not allowed: modify .codex/skills/ content.

Script

Quick Start

• python .codex/skills/unit-executor/scripts/run.py --help

• python .codex/skills/unit-executor/scripts/run.py --workspace <workspace_dir>

All Options

• --strict : enable quality gate (blocks on scaffolds; writes output/QUALITY_GATE.md )

Examples

• Run exactly one unit (strict):

• python .codex/skills/unit-executor/scripts/run.py --workspace <ws> --strict

• Equivalent repo wrapper:

• python scripts/pipeline.py run-one --workspace <ws> --strict

Notes

• Returns 0 on DONE/IDLE , 2 on BLOCKED/ERROR (useful for automation).

Troubleshooting

Issue: no runnable unit is found

Fix:

• Check UNITS.csv for unmet dependencies, missing outputs, or owner=HUMAN units waiting on approvals in DECISIONS.md .

Issue: a unit is marked DONE but outputs are missing

Fix:

• Fix the status to TODO /BLOCKED and re-run; only mark DONE when acceptance criteria and outputs are satisfied.