Skip to content
Back to skills

Unit Executor

ASecurity

Execute exactly one eligible Unit in an existing research Workspace; use for stepwise or manual semantic execution when status, Attempt, Artifact, Manifest, checkpoint, and acceptance evidence must remain synchronized.

  • 512 stars
  • 0 votes
  • 0 copies
  • 2 views
  • Added February 8, 2026
developmentpythonbash

Security analysis

A100/100

Pro scans all 2 files and shows the line behind each finding

Scanned September 20, 2026

npx -y skills add WILLOSCAR/research-units-pipeline-skills --skill unit-executor --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Unit Executor?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Unit Executor
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/willoscar-unit-executor/badge)](https://www.skillsdirectory.com/skills/willoscar-unit-executor)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: unit-executor
binding: library
description: Execute exactly one eligible Unit in an existing research Workspace; use for stepwise or manual semantic execution when status, Attempt, Artifact, Manifest, checkpoint, and acceptance evidence must remain synchronized.
---

# Unit Executor

The leading principle is **atomicity**: one invocation owns one Unit Attempt and
either commits one accepted Completion or records one diagnosable block. It
never starts a second Unit.

## Inputs

- `UNITS.csv` and the selected Unit row.
- Files declared by that row's `inputs` field.
- `DECISIONS.md` when the Unit is checkpoint-gated.

## Outputs

- Files declared by the Unit's `outputs` field.
- Updated `UNITS.csv`, Run Evidence, and optional `STATUS.md` projection.
- `output/QUALITY_GATE.md` when strict quality checks block Completion.

## Steps

### 1. Reconcile and select one Unit

Inspect the Workspace through the Pipeline adapter. Select the requested Unit,
or the first `TODO` Unit whose dependencies are `DONE`. Stop when a HUMAN
checkpoint, unresolved Decision, open Attempt, or integrity failure prevents
selection.

Completion criterion: exactly one eligible Unit is selected, or one blocking
condition is recorded with a concrete next action.

### 2. Open the Attempt

Start semantic work through the adapter, never by editing a status cell:

```bash
uv run python scripts/pipeline.py mark \
  --workspace workspaces/<name> \
  --unit-id <U###> \
  --status DOING \
  --note "starting semantic execution"
```

Completion criterion: the Unit is `DOING` and one matching open Attempt owns
the execution.

### 3. Execute the declared Skill

Read the selected Unit's Skill and only the context pointers required by this
branch. Produce the declared outputs without changing unrelated Workspace
artifacts.

Completion criterion: every required output exists or the failure is specific
enough to commit as `BLOCKED`.

### 4. Verify and commit Completion

Evaluate the Unit acceptance rule and strict quality contract when requested.
Commit through the adapter:

```bash
uv run python scripts/pipeline.py mark \
  --workspace workspaces/<name> \
  --unit-id <U###> \
  --status DONE \
  --note "acceptance checked"
```

Use `BLOCKED` with a concrete reason when acceptance fails. Do not directly
edit `UNITS.csv`; the adapter aligns Attempt, Artifact, Manifest, Decision, and
status projections.

Completion criterion: Completion is `DONE` with acceptance and provenance
evidence, or `BLOCKED` with a diagnosable Failure.

### 5. Stop after one Unit

Refresh the Workspace projection and report the completed or blocked Unit. Do
not claim end-to-end completion and do not start the next eligible Unit.

Completion criterion: exactly one Unit changed execution state during this
invocation and the next operator can resume from Workspace files.

## Context Pointers

- The selected row in `UNITS.csv` owns dependencies, inputs, outputs,
  acceptance, checkpoint, and Skill identity.
- The selected Skill owns semantic behavior.
- The locked Pipeline owns cross-Unit gates and target Artifacts.
- Use `research-pipeline-runner` for automatic continuation across Units.

## Script

### Quick Start

```bash
uv run python .codex/skills/unit-executor/scripts/run.py \
  --workspace workspaces/<name>
```

### All Options

- `--workspace <path>`: existing Workspace.
- `--unit-id <U###>`: execute a specific eligible Unit.
- `--inputs`, `--outputs`, `--checkpoint`: Pipeline-runner compatibility
  arguments.
- `--strict`: block scaffold-like outputs and write the quality-gate report.

### Examples

Run exactly one strict Unit:

```bash
uv run python .codex/skills/unit-executor/scripts/run.py \
  --workspace workspaces/<name> \
  --strict
```

Equivalent adapter command:

```bash
uv run python scripts/pipeline.py run-one \
  --workspace workspaces/<name> \
  --strict
```

The helper returns `0` for `DONE` or `IDLE`, and `2` for `BLOCKED` or `ERROR`.

## Troubleshooting

- When no Unit is runnable, inspect dependencies, checkpoint approvals, and
  open Attempts before changing status.
- When a `DONE` Unit has missing outputs, reopen it through the adapter with an
  explanatory note; never repair the CSV projection alone.

Files in this skill

  • SKILL.md2.7 KB
  • scripts/run.py1 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in development →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.