fadeno

Fadeno

The playbook layer for AI coding agents.

Stop re-typing "be careful, plan, review, test" every run. Define your workflow once as a repo-native YAML playbook, and any agent runs it the same disciplined way — leaving an inspectable trace of what it did. No runtime, no service, no lock-in.

Fadeno /fah-DEH-no/ — Esperanto for "thread." The thread that runs through every agent task.

npx fadeno init --codex     # or --claude

---

The problem

Coding agents are powerful but inconsistent. Every nontrivial task, you re-explain the same discipline:

"Codex, please be careful. Make a plan first, then implement it. Review your own code for edge cases. Run the tests. If something's broken, fix it. Don't install new dependencies or run anything destructive without checking with me."

You retype some version of that every time. You get different behavior every run. And when the chat closes, there's no record of what the agent actually did.

The fix

Define the workflow once, commit it to your repo, and then just say:

"Use the code-change-review playbook."

Same discipline — plan → implement → review → test → bounded revision — every time. Inspectable. Shareable. Portable across the agents your team actually uses.

Fadeno is harness-neutral: the same playbooks run on Codex and Claude Code today, and are designed to compile into a real orchestration runtime later. Only a thin per-target adapter differs.

Honest about enforcement, up front: in instruction-only hosts, approval policies are advisory — the model is asked to honor them, with no hard guarantee. For real guarantees, wire gates to your git/CI/pre-commit layer (or Claude Code hooks). See Enforcement. We'd rather you trust the tool because it's honest than because it overclaims.

---

Install & initialize

Requires Node.js ≥ 20.

# Codex target  → .agents/skills/, AGENTS.md, $-style invocation
npx fadeno init --codex

# Claude Code target → .claude/skills/, CLAUDE.md, /-style invocation
npx fadeno init --claude

init is safe to re-run: existing files are left untouched (and your AGENTS.md/CLAUDE.md content is preserved — Fadeno only appends a marked section). Use --force to overwrite. Add --with-hooks to also scaffold the tier-2 enforcement layer (a pre-commit guard + a CI workflow).

What gets created

.fadeno/
  vocabulary.md                 # the small, orthogonal term set
  enforcement.md                # advisory vs. enforced (tier-1 vs tier-2)
  playbooks/
    code-change-review.yaml
    research-synthesis.yaml
    pr-review.yaml
  schemas/
    playbook.schema.json        # the source of truth for the vocabulary
    run.schema.json
    review-report.schema.json
  runs/                         # run ledgers (execution traces, not source)

# Codex (--codex):                      # Claude Code (--claude):
AGENTS.md                                CLAUDE.md
.agents/skills/                          .claude/skills/
  fadeno-runner/  (SKILL.md, refs,         fadeno-runner/  (SKILL.md, refs)
                  agents/openai.yaml)      fadeno-builder/ (SKILL.md, refs)
  fadeno-builder/ (SKILL.md, refs,       .claude/agents/  (worker/reviewer/judge.md)
                  agents/openai.yaml)
.codex/agents/  (worker/reviewer/judge.toml)

The playbooks, schemas, vocabulary, and SKILL.md bodies are identical on both targets. Only the install dir, bootstrap file + invocation sigil, invocation policy, and subagent format differ.

Or install as a Claude Code plugin

init --claude copies the skills into one repo. For Claude Code, you can instead install Fadeno's skills + role subagents once, for every project, as a plugin — and let the CLI seed just the per-repo playbooks. (This is the capability/definitions split: the plugin carries how to run playbooks; the repo carries which playbooks.)

# the Fadeno repo doubles as a plugin marketplace
/plugin marketplace add <owner>/fadeno      # or a local path for testing
/plugin install fadeno@fadeno               # provides /fadeno:runner and /fadeno:builder

# then, in any project, seed just the playbooks/schemas (no skill copy):
npx fadeno init --claude --data-only

To test the plugin locally before publishing: claude --plugin-dir ./plugin. The plugin/ directory is generated from the same templates as the CLI (npm run build:plugin), so the skills never drift.

The plugin is self-contained: it bundles the fadeno CLI as a single executable in plugin/bin/ (auto-added to your PATH while the plugin is enabled), so the skills can call fadeno validate / diagram / gate with nothing else to install. A git-URL plugin install gives you a working fadeno out of the box.

---

Running a playbook

Fadeno ships two skills. Point your agent at the runner: