Your AI agent needs a tsukkomi.
Scope Harisen sits inside an AI coding agent and interrupts when a small Mission expands into unrelated refactors, abstractions, tools, subagents, research, or over-verification — with a sharp paper-fan joke, hard evidence, and a clear verdict.
Agent: “While I am here, I will refactor the related modules and build a reusable framework—”
🪭 Scope Harisen: “Why are you renovating the whole building! Where is that in the Acceptance Criteria?”
Reason: outside the current Scope and not required for Production Verify
Verdict: defer → return to the current Mission
한국어 · MIT License · v0.1.0
Ponytail asks “How can this be simpler?” Scope Harisen asks one step earlier: “Why are we doing this now?” The pattern catalog is the detector; the Mission ladder filters false positives; the harisen interrupts the loop.
| Family | Patterns |
|---|---|
| Scope expansion | Scope Monster · Refactor Hitchhiker · Cleanup Cascade · Feature Smuggling |
| Solution inflation | Abstraction Fever · Framework First · Future-Proofing Fantasy · Dependency Shopping |
| Investigation drift | Rabbit Hole · Archaeology Expedition · Source Safari · Context Avalanche |
| Meta-work | Tool Swamp · Plan-for-the-Plan · Documentation Theater · Workflow Cathedral |
| Coordination expansion | Agent Fan-out · Delegation Ping-Pong · Consensus Swamp · Orchestration Tax |
| Decision friction | Option Explosion · Clarification Carousel · Permission Pinball · Owner-Override Laundering |
| Verification distortion | Verification Vortex · Benchmark Theater · Read-back Ritual · Green-Test Mirage |
| Completion distortion | Completion Avoidance · Last-Mile Aversion · Local-is-Production · Premature Victory Lap |
Five guard patterns prevent false positives: Acceptance-Criterion Blocker, Production-Verify Requirement, Real P0/P1, Explicit Owner Promotion, and Safety Gate.
Each pattern has observable signals, its seductive rationale, legitimate exceptions, a default verdict, recovery action, and fan cue in the full pattern catalog.
Scope Harisen now has two detection layers:
- Semantic detector — all 32 patterns. The active skill reads the proposed next action, visible action sequence, and completion claim, then applies the pattern catalog.
- Runtime signal detector — seven strong signals. Hooks reduce tool events to a local Action Ledger and raise a candidate when a sequence crosses a deliberately small threshold.
| Runtime candidate | Strong signal |
|---|---|
| Rabbit Hole | 6 consecutive reads without a write or decision |
| Read-back Ritual | The same target is read 3 times |
| Agent Fan-out | A third agent call occurs before an integrating write |
| Permission Pinball | The same approval question is asked twice |
| Verification Vortex | 4 verification runs occur without a change |
| Local-is-Production | A production claim has only local-test evidence and lacks deploy/live read-back |
| Premature Victory Lap | Completion is claimed before requested PR/CI/deploy/read-back evidence exists |
A runtime candidate is not a verdict. It is injected back into the agent, which must apply the Decision ladder and guard patterns. Signal hooks never deny a tool call. In full and ultra, a completion-evidence mismatch can delay Stop once; the second Stop fails open to prevent a loop. lite remains advisory.
The local JSONL ledger stores only event kinds, booleans, counts, pattern names, and SHA-256 target hashes. It does not store a raw prompt, raw command, tool response, secret, or file path. Files use owner-only POSIX permissions where supported, are capped at 256 KB per session, removed on normal session end, and pruned after seven days if abandoned. The detector uses no model call, API key, database, or dependency.
Heuristics are intentionally narrow. They can miss semantic drift, and tool activity outside the host's hook surface is invisible. That is why the 32-pattern skill remains the judge and the seven runtime rules remain candidates.
| Mode | Behavior |
|---|---|
| lite | Names the drift and a safer alternative; continues unless dangerous |
| full (default) | Stops the detour, defers/discards it, resumes the Mission |
| ultra | Allows only actions required for Acceptance Criteria or Production Verify |
| off | Deactivated |
- Directly part of the current Mission?
- Skipping fails an Acceptance Criterion?
- Blocks Production Verify?
- Real P0/P1 that must interrupt the batch?
- Owner explicitly promoted it into this batch?
Every answer no → tsukkomi → defer or discard → return to Mission.
🪭 <one sharp tsukkomi line — at most two sentences>
Pattern: <one catalog name; at most two if recovery changes>
Reason: <Scope / Acceptance Criteria / Priority evidence>
Verdict: continue | defer | discard | owner-approval
Recovery: <one concrete next action on the current Mission>
Silent until drift is detected. The joke attacks the proposal, never a person. Real production/security P0 is never discarded. Owner “do it now anyway” overrides a drift stop; safety gates still hold.
This repository is a local Codex / Claude Code plugin skill. It is installed from the Git repository; there is no npm package.
Runtime hooks require Node.js 18 or newer on PATH. The instruction-only fallback does not.
codex plugin marketplace add beamonic/scope-harisen
codex plugin add scope-harisen@scope-harisenRestart Codex, open /hooks, and review the lifecycle and observation hooks. As an instruction-only fallback, copy skills/scope-harisen into your skills directory.
claude plugin marketplace add beamonic/scope-harisen --scope user
claude plugin install scope-harisen@scope-harisenRestart Claude Code. As an instruction-only fallback, copy skills/scope-harisen into your Claude skills path.
If hooks are unavailable, paste or link AGENTS.md into the agent’s instruction surface.
For local development, clone https://github.com/beamonic/scope-harisen.git and use the checkout path as the marketplace source.
/scope-harisen # report current level
/scope-harisen lite
/scope-harisen full
/scope-harisen ultra
/scope-harisen off
Also: stop scope-harisen / normal mode.
Mode switches affect only the current session. Set new-session behavior with /scope-harisen default lite|full|ultra|off.
Default mode: env SCOPE_HARISEN_DEFAULT_MODE or ~/.config/scope-harisen/config.json → {"defaultMode":"full"}.
npm testRuns deterministic grader unit tests, hook lifecycle tests, and manifest validation. No API key.
Optional model eval (baseline vs Scope Harisen, not in CI):
npx promptfoo@latest eval -c benchmarks/behavior.yamlskills/scope-harisen/ # SKILL.md + pattern catalog + agents/openai.yaml
hooks/ # lifecycle hooks + private Action Ledger detector
AGENTS.md # instruction-only fallback
benchmarks/ # offline grader + optional promptfoo config
tests/ # node:test suites
.codex-plugin/ # Codex plugin manifest
.claude-plugin/ # Claude Code plugin + marketplace manifests
Architecture and product-communication patterns (persona-led skill, short decision ladder, persistent lifecycle hooks, plugin manifests, offline grader tests, optional behavior evals) were studied from Ponytail by Dietrich Gebert (MIT). Scope Harisen’s character, prose, examples, branding, and code are original. No Ponytail source was copied.
The project-behavior pattern-language method was inspired by Tom DeMarco, Peter Hruschka, Tim Lister, Steve McMenamin, James Robertson, and Suzanne Robertson’s Adrenaline Junkies and Template Zombies. Scope Harisen’s 32 AI-agent patterns are original; the book’s pattern descriptions are not reproduced.