Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,20 @@ jobs:
# payload-writing prompt states the refusal contract, and that no
# ID example or JSON skeleton teaches something the engine rejects.
run: python scripts/validate_skills.py
- name: The bundled engine matches the engine source
# Users install the skill, and the skill carries the engine. The
# bundle is generated, so a change to engine/executor/ that misses
# the bundle would ship one engine and test another.
run: python scripts/sync_engine.py --check
- name: The installed skill runs with no PYTHONPATH
# The claim in the README, executed: copy the skill out of the repo,
# drop PYTHONPATH, and run the launcher from an unrelated directory.
run: |
set -e
dest="$(mktemp -d)"
cp -R skills/executor "$dest/executor"
cd "$dest"
env -u PYTHONPATH python3 executor/scripts/executor --version
- name: Prompt-injection lint
# Every SKILL.md is executed as instruction by agents. This blocks
# override directives, concealment, exfiltration endpoints,
Expand Down
50 changes: 50 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,56 @@ project is tagged; between releases, entries are dated and `main` moves.

## [Unreleased]

## [2.0.2] — 2026-10-19

Patch release: the engine ships with the skill. Installing the skills used
to leave `executor` undefined — the skills call a bare command that only
existed for someone who had cloned the repository and exported
`PYTHONPATH`. Now the engine travels inside the router skill and a
launcher beside it resolves the copy relative to itself, so an install
needs no path setup at all.

### Fixed — an install is now a complete install

- **The engine ships inside `skills/executor/`.** `npx skills add` copies a
skill directory and nothing outside it, so `engine/executor/` — a sibling
of `skills/` — never reached a user. The package now also lives at
`skills/executor/scripts/lib/executor/`, which the installer copies, and
`skills/executor/scripts/executor` is the launcher the skills name.
- **No `PYTHONPATH`, no `pip`, no `PATH` edit.** The launcher resolves
`scripts/lib/` from `__file__`, so it works from any project directory.
Python 3.11+ is the only requirement; the engine remains standard
library only.
- **`scripts/sync_engine.py` is the one writer of the shipped copy**, and
`--check` is a CI gate. `engine/executor/` stays the source the suite
tests; the bundle is generated, so a hand edit to either side fails
`test_engine_ships_with_skill.py` rather than shipping an engine the
repository never tested.
- **A real install is exercised in CI**, not just the repository layout:
the skill is copied out of the tree, `PYTHONPATH` is dropped, and the
launcher runs from an unrelated directory.

### Changed — the documents name the command a reader can run

- **Every skill states the spelling.** `executor <verb>` is defined once in
the router and restated at the top of each phase skill, so loading
`executor-execution` directly no longer leaves an agent to guess at an
executable that is not on `PATH`.
- **Engine source citations point inside the skill.** The references cited
`engine/executor/paths.py` and `schemas.py` — paths an installed user
does not have. They now cite `scripts/lib/executor/`, which exists
wherever the skill was copied. A test walks the skills tree to keep it
that way.
- **The README install section is the install path.** The `PYTHONPATH`
step, the one-paste prompt's profile edit, and the `python3 -m executor`
examples are replaced by the launcher; working from a clone is documented
separately, where `PYTHONPATH` is still the honest spelling.
- **`CONTRIBUTING.md` describes this repository.** It documented
`exec-scan-secrets`, `validate-skills.sh`, `test-executor.sh`, and a
ShellCheck gate — all deleted in the v2 shell-to-Python cutover. The
file now names the Python entry points, the 100% branch floor, the
bundle rule, and the CI jobs that actually exist.

## [2.0.1] — 2026-10-16

Patch release: the documents say what the engine enforces. The README's
Expand Down
93 changes: 60 additions & 33 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,42 +1,67 @@
# Contributing to The Executor

Thanks for your interest in improving The Executor. This repository is a
library of agent-readable skill documents plus the shell scripts they call —
no build step, no test framework, no runtime. The contributions that matter
most are:
library of agent-readable skill documents plus the Python engine those
skills drive — no build step, no runtime dependency beyond Python 3.11+. The
contributions that matter most are:

1. **Skill edits** — clearer routing, better gates, sharper prompts.
2. **Script fixes** — the `skills/executor/scripts/` helpers must keep
resolving paths from `skills/executor/references/layout.md`, never
inventing locations.
2. **Engine fixes** — the engine in `engine/executor/` is the enforcer of
every contract the skills describe; a rule stated in prose and not
enforced in code is a rule that will drift.
3. **Documentation** — anything a reader of this README would find confusing
or missing.

## Repository layout

| Path | What lives there |
|---|---|
| `engine/executor/` | The engine source: `cli.py`, `engine.py`, `schemas.py`, `paths.py`, `store.py`, `views.py`, `policy.py` |
| `engine/tests/` | The suite, including the tree-walking contract tests |
| `skills/executor/` | Router skill: contract, ID grammar, phase gates |
| `skills/executor/references/` | The normative documents: layout, branches, frontmatter, indexes, safety, test-quality |
| `skills/executor/scripts/` | Executable helpers (`exec-id`, `exec-workspace`, `exec-scan-secrets`, …) |
| `skills/executor/scripts/executor` | The launcher users run; resolves the engine relative to itself |
| `skills/executor/scripts/lib/executor/` | The shipped engine — a generated mirror of `engine/executor/` |
| `skills/executor-*/` | One skill per lifecycle phase, each with its own `SKILL.md` |

There is no `docs/` directory: normative content lives in
`skills/executor/references/`, which is what the skills cite.
| `scripts/` | `run_tests.py`, `sync_engine.py`, `mutate.py`, the validators |

`skills/executor/references/layout.md` is normative: paths, document types,
and directory names resolve from it. If you move or add a document type,
update it first.

### The bundled engine

The engine ships **inside** the router skill because an installed skill is a
copied directory: `npx skills add` copies `skills/executor/` and nothing
outside it, so an engine kept only at `engine/` would never reach a user.
`skills/executor/scripts/lib/executor/` is that shipped copy.

**Never edit the bundle by hand.** `engine/executor/` is the source; the
bundle is generated from it. After changing the engine:

```bash
python3 scripts/sync_engine.py # rewrite the bundle
python3 scripts/sync_engine.py --check # what CI runs
```

A change that edits only one side fails `test_engine_ships_with_skill.py`
and the `--check` CI step, by design — two copies of one package that are
allowed to differ means the repository tests one engine and ships another.

## Getting started

```bash
git clone git@github.com:Atri10/executor.git
cd executor
pip install -r requirements-dev.txt # coverage, the one dev tool
```

That's the whole setup — the skills are plain Markdown and the scripts are
POSIX-ish bash with no dependencies beyond `git` and `find`.
The engine itself has zero third-party dependencies. From a clone it also
runs as a package:

```bash
PYTHONPATH=engine python3 -m executor --version
```

## How changes are reviewed

Expand All @@ -54,55 +79,57 @@ POSIX-ish bash with no dependencies beyond `git` and `find`.
`references/branches.md`, `references/frontmatter.md`, or
`references/indexes.md` in the same change, and call out the behavioral
delta in the PR description.
- **A behavior change needs a test that would fail without it.** The suite
holds a 100% branch-coverage floor, so an uncovered branch fails CI rather
than being merged untested.

## Submitting changes

1. Branch from `main`: `git checkout -b feature/<what>` (or `fix/<what>`,
`docs/<what>`).
2. Make the change in a focused commit. Conventional Commits style:
`feat(skills): ...`, `fix(scripts): ...`, `docs: ...`.
3. Before committing, check the diff for accidental secrets — this repo
`feat(engine): ...`, `fix(skills): ...`, `docs: ...`.
3. Before committing, check the diff for accidental secrets — the engine
includes a scanner you can borrow for the check:
`skills/executor/scripts/exec-scan-secrets <paths>`.
`python3 skills/executor/scripts/executor check --secrets`.
4. Open a pull request describing **what behavior changes for an agent** and
**why**. Link any issue it resolves.

## Reporting issues

- **Bug in a skill or script** — open a regular issue with the exact skill
text or script invocation, what the agent did, and what it should have
done.
- **Bug in a skill or the engine** — open a regular issue with the exact
skill text or command invocation, what the agent did, and what it should
have done.
- **Docs unclear or wrong** — same channel; wrong docs are bugs.
- **Security-sensitive disclosure** — do not open a public issue. See
[SECURITY.md](SECURITY.md).

## CI

Every PR runs five checks; all must pass before merge:
Every PR runs these checks; all must pass before merge:

| Check | What it enforces |
|---|---|
| **ShellCheck** (`--severity=warning`) | Every `exec-*` script parses and is warning-clean — these run inside users' agents with git and filesystem access |
| **Prompt-injection lint** | Skill markdown is *executed as instruction by agents*; the linter blocks override directives, concealment, exfiltration endpoints, fetch-and-execute, and credential literals |
| **Engine suite** (macOS, Linux, Windows) | The full suite at a 100% branch-coverage floor, plus `python -m executor --version` on each OS |
| **Bundled-engine sync** | `scripts/sync_engine.py --check`: the shipped copy is byte-identical to `engine/executor/` |
| **Installed-skill smoke** | The skill is copied out of the repo, `PYTHONPATH` is dropped, and the launcher runs — the install path users actually take |
| **Skill validation** | Frontmatter + `Use when` trigger, balanced fences, no duplicate names; every `SKILL.md` carries `## Self-Critique` and `## Verification`; every dispatch role in `references/layout.md` has a registered prompt template carrying the required markers; no `*-prompt.md` exists unregistered; no ASCII-art diagrams |
| **Secret scan** | The Executor's own `exec-scan-secrets` over the repo, plus gitleaks over full history |
| **Script smoke** | Usage paths work; the plan-lint and run-audit gates actually fire on known violations |
| **Prompt-injection lint** | Skill markdown is *executed as instruction by agents*; the linter blocks override directives, concealment, exfiltration endpoints, fetch-and-execute, and credential literals |
| **Secret scan** | The engine's own `executor check --secrets` against a fresh initiative, plus gitleaks over full history |

Run all of them locally before pushing:
Run them locally before pushing:

```bash
find skills/executor/scripts scripts -type f \( -name 'exec-*' -o -name '*.sh' \) -print0 \
| xargs -0 shellcheck --severity=warning
python3 scripts/run_tests.py # suite + coverage floor
python3 scripts/sync_engine.py --check # bundle drift
python3 scripts/validate_skills.py # skill contract
python3 scripts/lint-prompt-injection.py skills/
bash scripts/validate-skills.sh skills
bash skills/executor/scripts/exec-scan-secrets .
bash scripts/test-executor.sh
```

`test-executor.sh` is the regression suite: thirty-seven fixture cases
that rebuild disposable repositories and assert each enforced contract. Add
a case whenever a fix teaches a script to refuse something it used to
accept.
Mutation testing is available for a module whose tests you changed:
`python3 scripts/mutate.py engine/executor/<module>.py`. A surviving mutant
is either a missing assertion or a genuinely equivalent change, and the
latter belongs in `scripts/mutation-allow.json` with its reason.

The injection linter is heuristic and errs toward false positives — a
flagged line is a human-review prompt in the PR diff, not an accusation.
Expand Down
82 changes: 59 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,21 +25,21 @@ on macOS, Linux, and Windows.
## In sixty seconds

```text
$ npx skills add Atri10/executor # skills into your harness
$ export PYTHONPATH=/path/to/executor/engine # the engine on the path
$ npx skills add Atri10/executor # skills + engine into your harness
$ EXEC=~/.agents/skills/executor/scripts/executor # the launcher, no PATH setup

$ python3 -m executor new "Tenant isolation cells"
$ python3 "$EXEC" new "Tenant isolation cells"
{
"created": "INIT-0001",
"title": "Tenant isolation cells",
"store": ".../.executor/INIT-0001",
"docs": ".../docs/executor/INIT-0001"
}

$ python3 -m executor next
$ python3 "$EXEC" next
{"action":"PHASE-ENTER","initiative":"INIT-0001","phase":"intake", ...}

$ python3 -m executor status
$ python3 "$EXEC" status
INITIATIVE INIT-0001 - Tenant isolation cells
phase: intake (in_progress)
events: 3 | artifacts: 0 | tasks: 0
Expand All @@ -61,19 +61,33 @@ discovers every skill in the repo and wires them into your harness:
npx skills add Atri10/executor
```

Or clone and copy `skills/` into whatever directory your agent loads from,
and put `engine/` on your `PYTHONPATH`:
**The engine ships inside the `executor` skill**, at
`skills/executor/scripts/lib/executor/`, with a launcher beside it. An
install therefore needs no `pip`, no virtualenv, no `PYTHONPATH`, and no
command on `PATH`: the launcher resolves its engine relative to itself, so
it works from any project directory. Python 3.11+ is the only requirement,
and the engine is standard library only.

```bash
python3 ~/.agents/skills/executor/scripts/executor --version
```

`~/.agents/skills/` is where `npx skills add` puts a globally installed
skill; use `./.agents/skills/` for a project-local install, or your
harness's own skills directory if it keeps one. Throughout this README and
every skill, `executor <verb>` means that launcher.

Or clone and copy `skills/` into whatever directory your agent loads from:

```bash
git clone git@github.com:Atri10/executor.git
cp -R executor/skills/* <your-agents-skills-dir>/
export PYTHONPATH=<clone>/engine
```

Pin to a release tag instead of `main` for stability:

```bash
git clone --branch v2.0.1 git@github.com:Atri10/executor.git
git clone --branch v2.0.2 git@github.com:Atri10/executor.git
```

There are no dependencies to install: the engine is the standard library,
Expand All @@ -87,7 +101,7 @@ other harness. It discovers the right directories itself and verifies the
install:

```text
Install The Executor skill library and engine for me:
Install The Executor skill library for me:

1. Clone https://github.com/Atri10/executor.git into a temp directory
2. Find my agent's skills directory. Candidates, in order — use the first
Expand All @@ -99,14 +113,15 @@ Install The Executor skill library and engine for me:
- as my harness documents
3. Copy every directory from the clone's skills/ folder into that skills
directory (each is one skill: skills/executor, skills/executor-spec, ...).
Tell me the PYTHONPATH line that points at the clone's engine/ directory,
and add it to my shell profile if I confirm.
4. Verify: run PYTHONPATH=<clone>/engine python3 -m executor --version
(prints 2.0.1), then PYTHONPATH=<clone>/engine python3 -m executor
--help (lists the command surface). Also confirm every copied
skills/<name>/ directory contains a SKILL.md — count the directories,
not a remembered number: the skill set grows, and a stale count fails
an install that is actually fine.
The engine ships inside skills/executor/scripts/lib/, so copy the whole
directory — do not copy only the .md files.
4. Verify: run python3 <skills-dir>/executor/scripts/executor --version
(prints 2.0.2), then python3 <skills-dir>/executor/scripts/executor
--help (lists the command surface). Do not set PYTHONPATH and do not
install a package: the launcher carries its engine. Also confirm every
copied skills/<name>/ directory contains a SKILL.md — count the
directories, not a remembered number: the skill set grows, and a stale
count fails an install that is actually fine.
5. Tell me which directory you installed into, and how to invoke the
router in my harness (usually /skill:executor or just asking for
"the executor").
Expand All @@ -124,6 +139,20 @@ Then invoke the root router:
or say *"start an initiative"* — normal requests route by each skill's
description.

### Working in this repository

From a clone, the engine is also a package under `engine/`, which is what
the test suite imports:

```bash
export PYTHONPATH=<clone>/engine
python3 -m executor --version
```

Both spellings run the same code. `scripts/sync_engine.py` mirrors
`engine/executor/` into the skill bundle and `--check` fails CI when they
differ, so the two copies cannot drift.

## How a run is driven

One loop, and the controller holds no judgment: run `executor next`, read
Expand Down Expand Up @@ -402,6 +431,9 @@ the decision table is an engine gap to record, not to approximate).

### The CLI is the whole surface

`executor` below is `python3 <skill-base-dir>/scripts/executor`; the
launcher passes its arguments straight through.

```text
executor new "<title>" scaffold INIT-NNNN
executor next [INIT] one typed action + its prompt
Expand Down Expand Up @@ -528,21 +560,25 @@ archivable — open the folder and every pointer resolves inside it.

```mermaid
flowchart TD
R["repository root"] --> E["engine/ — the engine, stdlib only"]
R["repository root"] --> E["engine/ — the engine source, stdlib only"]
R --> S["skills/ — one directory per skill"]
R --> SC["scripts/ — run_tests.py, mutate.py, validators"]
R --> SC["scripts/ — run_tests.py, sync_engine.py, mutate.py, validators"]
R --> CI[".github/workflows/ — the gates"]
R --> DOC["docs/executor/ — the committed record of each initiative"]
E --> ET["engine/tests/ — the suite"]
S --> B["executor/scripts/lib/executor/ — the shipped copy"]
```

| Path | What it is |
|---|---|
| `engine/executor/` | the engine: `cli.py`, `engine.py`, `schemas.py`, `paths.py`, `store.py`, `views.py`, `policy.py` |
| `engine/tests/` | the suite (722 tests), including the tree-walking contract tests |
| `skills/executor/` | the router skill, its prompt templates, and the references |
| `engine/executor/` | the engine source: `cli.py`, `engine.py`, `schemas.py`, `paths.py`, `store.py`, `views.py`, `policy.py` |
| `engine/tests/` | the suite (739 tests), including the tree-walking contract tests |
| `skills/executor/` | the router skill, its prompt templates, the references, and the engine that ships with it |
| `skills/executor/scripts/executor` | the launcher; resolves `scripts/lib/executor/` relative to itself |
| `skills/executor/scripts/lib/executor/` | the installed engine — a generated mirror of `engine/executor/` |
| `skills/executor-*/` | one directory per phase skill |
| `scripts/run_tests.py` | the test runner; enforces the branch-coverage floor |
| `scripts/sync_engine.py` | mirrors the engine into the skill; `--check` is the drift gate |
| `scripts/mutate.py` | mutation testing; the allow list records equivalent survivors |
| `scripts/validate_skills.py` | the skill contract: registry, references, payload shapes |
| `scripts/lint-prompt-injection.py` | blocks override directives and concealment in skill text |
Expand Down
Loading
Loading