curtain

Nobody likes spoilers, especially agents.
Show them the ending and they skip the plot. Curtain keeps the script backstage until it's time to act.

Physical token withholding for AI coding agent workflows. Executes multi-act Markdown playbooks one step at a time, keeping future instructions backstage until prior acts complete.

• How it works
• Features
• FAQ
• Installation
• Quick Start
• Authoring Playbooks
• Syntax & Delimiters
• Commands & Controls
• Architecture
• Development
• Changelog
• License

How it works

When an AI coding agent receives a multi-step task in a single prompt or file, it attempts to execute the entire plan at once: skipping tests, hallucinating downstream phases, cutting corners, and bypassing review gates.

Prompting cannot prevent this. If future tokens exist in the context window, the model attends to them.

Curtain enforces physical token withholding across a four-step lifecycle:

[ User invokes /db-migrate ]
              │
              ▼
┌─────────────────────────────┐
│ Act 1: Schema & Draft SQL   │ ◄── Only Act 1 tokens enter context
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│   > [!INTERMISSION] Gate    │ ◄── Turn stops. Control yields to user.
└─────────────┬───────────────┘
              │
     [ User enters /next ]
              │
              ▼
┌─────────────────────────────┐
│ Act 2: Local Verification   │ ◄── Act 2 tokens injected
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│    > [!CURTAIN] Advance     │ ◄── Turn completes. Next act begins immediately.
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│ Act 3: Cleanup & Docs       │ ◄── Act 3 tokens injected
└─────────────────────────────┘

1. Structure instructions into Acts

Convert an existing skill with /curtain-adopt <skill>, or write a playbook in PLAYBOOK.md using callout delimiters to separate sequential phases:

# Database Migration

## Act 1: Schema Audit & Draft Migration
Audit existing tables in `src/db/schema.ts`. Write a migration script in `migrations/002_user_prefs.sql`.
Do not apply the migration yet.

> [!INTERMISSION] Review migration SQL
> Ensure all columns have default values and no destructive DROP operations exist.

## Act 2: Local Verification
Run the migration script against local test Postgres. Run the test suite to check for regressions.

> [!CURTAIN] Continue automatically to cleanup

## Act 3: Cleanup & Documentation
Update ORM models, export types, and update schema docs in `docs/db.md`.

2. Invoke the skill in chat

Trigger the workflow via its slash command (e.g. /db-migrate). Curtain intercepts the prompt, resolves PLAYBOOK.md, and injects Act 1 into the agent's context.

The agent prompt receives only the active instructions:

[STEP 1 OF 3]
Audit existing tables in src/db/schema.ts. Write a migration script in migrations/002_user_prefs.sql.
Do not apply the migration yet.

[INTERMISSION CRITERIA]
Review migration SQL. Ensure all columns have default values and no destructive DROP operations exist.

Downstream instructions for Act 2 and Act 3 remain on disk and do not exist in the context window.

3. Review at an intermission

When the agent finishes drafting the migration, it concludes its turn. Curtain's Stop hook detects the > [!INTERMISSION] delimiter, sets the runner status to paused, and yields control to the user.

If you send chat messages or request changes during an intermission, Curtain appends [INTERMISSION REVIEW] instructions to ensure the agent addresses your feedback without advancing.

4. Advance with /next

When satisfied with the changes, type /next (Codex: $curtain:next). Curtain advances the step pointer and injects Act 2.

When Act 2 completes, its concluding > [!CURTAIN] delimiter triggers an automatic advance. The Stop hook intercepts turn completion, supplies Act 3 immediately, and lets the agent finish the workflow without manual confirmation.

Features

• Physical token withholding: Injects only the active Act into the prompt. Downstream steps do not exist in the context window.
• Intermission review gates: Pauses execution at > [!INTERMISSION] delimiters, yielding control to the user and replaying criteria on feedback turns.
• Autonomous act advancement: Delimiters (> [!CURTAIN]) raise the curtain and feed the next Act immediately upon turn completion.
• Zero schema overhead: Standard Markdown playbooks parsed by a generic AST tokenizer without complex YAML workflow configs.
• Backstage file protection: Intercepts file-reading tools and runner commands to prevent agents from peeking backstage at PLAYBOOK.md.
• Universal environment support: Shared single-source architecture supporting Google Antigravity, Anthropic Claude Code, and OpenAI Codex.
• Skill adoption and ejection: Built-in skills to migrate single-file skills into playbooks (/curtain-adopt) and reverse them cleanly (/curtain-eject).
• Zero-dependency bundled shim: Packaged into a single ESM file (dist/curtain.mjs) executed directly by host harness hooks without npm install.

FAQ

Installation

agy plugin install https://github.com/lukstei/curtain

claude plugin marketplace add lukstei/curtain
claude plugin install curtain@curtain-marketplace

/plugin marketplace add lukstei/curtain
/plugin install curtain@curtain-marketplace

codex plugin marketplace add lukstei/curtain
codex plugin add curtain@curtain

Quick Start

1. Adopt an existing skill (/curtain-adopt)

Convert any existing single-file skill into a multi-act playbook:

/curtain-adopt <skill-name-or-path>

Curtain automatically:

• Preserves original prose and headings verbatim without inventing artificial titles.
• Prunes redundant wait instructions (e.g. "Wait for user confirmation") handled natively by > [!INTERMISSION].
• Prunes forward-context leaks (e.g. "In Step 3 we will apply...") rendered obsolete by physical token withholding.
• Strips Tables of Contents to prevent leaking future step names into Act 1 context.
• Inserts > [!INTERMISSION] at approval boundaries and > [!CURTAIN] at automatic section boundaries.
• Previews the proposed playbook in the review sidebar before writing PLAYBOOK.md and wrapping SKILL.md.

2. Run in chat

Invoke the adopted skill directly using its slash command:

• Claude Code & AGY: /<skill-name>
• Codex: $<skill-name>

When paused at an intermission, review the agent's work and resume with /next (Codex: $curtain:next).

[!NOTE]

• Antigravity: Antigravity executes skills by instructing the agent to read SKILL.md via view_file. Curtain intercepts any view_file call on a skill backed by a PLAYBOOK.md to begin Act 1. To inspect or edit a Curtain SKILL.md in Antigravity without triggering playbook execution, open the file directly in your editor.
• Codex: Hook output is visible in chat until openai/codex#25403 is resolved.

3. Eject anytime (/curtain-eject)

Restore an adopted playbook back to a standard single-file skill with zero lock-in:

/curtain-eject <skill-name-or-path>

• Recombines YAML frontmatter from SKILL.md with instructions from PLAYBOOK.md.
• Strips all > [!CURTAIN] and > [!INTERMISSION] callouts.
• Previews the restored SKILL.md in the review sidebar, deleting PLAYBOOK.md upon confirmation.

Authoring Playbooks

To create a new multi-act skill from scratch without adopting an existing one:

1. Directory layout

Organize your workflow inside a skill directory with SKILL.md for manifest metadata and PLAYBOOK.md for instructions:

.agents/skills/db-migrate/  (or .claude/skills/db-migrate/)
├── SKILL.md       # Public skill manifest
└── PLAYBOOK.md    # Backstage multi-act script

2. Define the playbook

In PLAYBOOK.md, separate sequential phases using callout alert delimiters:

# Database Migration

## Act 1: Schema Audit & Draft Migration
Audit existing tables in `src/db/schema.ts`. Write a migration script in `migrations/002_user_prefs.sql`.
Do not apply the migration yet.

> [!INTERMISSION] Review migration SQL
> Ensure all columns have default values and no destructive DROP operations exist.

## Act 2: Local Verification
Run the migration script against local test Postgres. Run the test suite to check for regressions.

> [!CURTAIN] Continue automatically to cleanup

## Act 3: Cleanup & Documentation
Update ORM models, export types, and update schema docs in `docs/db.md`.

Syntax & Delimiters

Playbooks are standard Markdown files divided into sequential Acts by GitHub-style callout blockquotes:

Delimiter criteria

Delimiters accept optional instructions:

• > [!INTERMISSION] Criteria: Injected as [INTERMISSION CRITERIA] during the step prompt, and replayed as [INTERMISSION REVIEW] during review turns.
• > [!CURTAIN] Criteria: Injected as [TRANSITION CRITERIA] during the step prompt.

Multi-line instructions are supported:

> [!INTERMISSION] Review migration SQL
> - Ensure all columns have default values.
> - Confirm no destructive DROP operations exist.

Grammar rules

• Top-level callouts: Delimiters must appear as top-level Markdown blockquotes.
• Code block isolation: Callout blockquotes inside fenced code blocks are ignored and never trigger act boundaries.
• Case-insensitive: Delimiters match case-insensitively (> [!curtain], > [!INTERMISSION]).
• Preamble support: Any Markdown text before the first delimiter or heading is preserved as playbook preamble context.

Commands & Controls

Development

npm install
npm run verify      # Runs tests, linter, and typecheck
npm run build       # Builds dist/curtain.mjs
npm run test:watch  # Runs test watcher

Changelog

See CHANGELOG for release history and notable changes.

License

MIT © 2026 Lukas Steinbrecher