aytuncyildizli/reprompter

Your prompt sucks. Let’s fix that.

What’s new (v13 — RePrompter v2): two intents (improve my prompt / build this whole thing), specifiability routing, One-Shot build prompts, team execution seeded from a build brief — digest

RePrompter is a prompt engineering skill for AI coding agents. It takes rough, low-quality prompts and transforms them into structured, high-scoring prompts that produce dramatically better results. Templates are aligned with 2026 vendor guidance: clear sectioning, calibrated emphasis, outcome-first instructions, load-bearing constraints, structured-output routing, context budgeting, and tool-description quality. Works with Claude Code, OpenClaw, Codex, Grok CLI, Hermes Agent, or any LLM that accepts structured prompts.

---

Two intents

Where the result goes. Improve outputs can be pasted (default), compressed to a /goal command (Codex, Claude Code, Hermes), compiled to a runnable Claude .workflow.js, or delivered to another model via headless-relay. Build runs as one prompt or splits across a team. Everything that used to be a separate “lane” is now one of these — a format the result takes or the way it executes.

Nothing was removed. Team execution (repromptverse, smart run, swarm triggers), the /goal and Workflow formats, cross-model relay delivery, and Reverse mode (extract the prompt DNA from a great output) all work exactly as before — see SKILL.md. v13 changed the map, not the machinery: every v12 trigger still routes to its intent. The one behavior change is honest and opt-out — a clearly whole-product “reprompt this” now offers an autonomous build prompt (say “spec” for the old structured, scored output); bounded and ambiguous asks stay spec-XML exactly as before.

---

Improve: a rough prompt becomes a good one

Input:  "uhh build a crypto dashboard, maybe coingecko data, add caching, test it too"
Score:  1.6/10

Output: Structured XML prompt with role, context, task, requirements,
        constraints, output format, and success criteria
Score:  9.0/10  (+462%)

Scores are self-assessed. Treat as directional indicators, not absolutes.

---

Build: a rough idea becomes a working thing

You say:  one-shot this: a first-person shooter like the recent Call of Duty games, in the browser

RePrompter asks a few plain questions, then emits one prose build prompt you paste into any coding agent. It names a real reference, staffs the work with a separate harsh critic that judges the running artifact (never the builder’s summary), and ends on a checkable bar. The image below is one real frame from a single maximal-mode dogfood run — a browser FPS in a self-contained HTML file, textures/models/audio generated in code — captured by the run’s own screenshot harness at 1600x900 with device pixel ratio 1 — the image is 1600x900, which is what a 1600x900 viewport produces only at pixel ratio 1. That is the condition behind the 269 FPS in the corner, and it is the whole point of this release: at the owner’s real pixel ratio of 2 the same build did not hold that number. The run itself is not in this repository, so the frame and its stated conditions are what is auditable here; the rest is the maintainer’s report. One run’s result under stated conditions, not a guarantee for every run:

Two dogfood runs, same lane:

Lands at a strong working prototype — expect to keep iterating after it stops. It does not produce a shipped AAA title; the FPS above still has rough edges (muzzle-flash bloom, one stray additive box), and the honest close says so up front.

Credit where the shape came from: the one-prompt build pattern is @mattshumer_'s — a CoD-like browser FPS from 152 dictated words — reproduced and dissected by @ziwenxu_ as the “Gauntlet Loop” (name a real bar, separate builder from critic, loop on real output). RePrompter’s One-Shot template is that shape made fillable, plus the checklist stop so a run ends on its own instead of at your rate limit.

---

Install

Claude Code

Recommended: install the Claude Code plugin. One install registers the RePrompter skill namespace and both Ambient Prompt Gate hooks; future updates use Claude Code’s native plugin update flow.

/plugin marketplace add AytuncYildizli/reprompter
/plugin install reprompter@reprompter

If you previously installed ~/.claude/skills/reprompter, remove that personal copy before using the plugin. Personal skills shadow/duplicate plugin skills, so leaving it in place can make Claude Code load the old copy instead of /reprompter:reprompter.

The plugin ships the Ambient Prompt Gate enabled for Claude Code UserPromptSubmit and Stop. Use REPROMPTER_AMBIENT=0 as the per-feature off switch; Claude Code’s disableAllHooks still disables all hooks, including plugin hooks.

Fallback for copy-based or non-plugin setups:

mkdir -p skills/reprompter
curl -sL https://github.com/aytuncyildizli/reprompter/archive/main.tar.gz | \
  tar xz --strip-components=1 -C skills/reprompter

Source archives are runtime-only (.gitattributes export-ignore): they contain SKILL.md, references/, and scripts/ but not dev/dist trees like skills/ (the Hermes-only install package — see Install paths), plugin/, .claude-plugin/, benchmarks/, assets/, or docs/. Plugin installs use git clone through Claude Code’s marketplace flow, so export-ignoring the plugin tree does not affect plugin installs. Installed an older full copy? It’s safe to delete those directories from it — upgrades won’t bring them back.

For the /goal output format on Claude Code, pin the CLI to v2.1.139 or later. /goal depends on the hooks layer — if disableAllHooks or allowManagedHooksOnly is set in settings.json the command is unavailable on any version (v2.1.140 only made the failure visible). Managed environments that block hooks should stick to Single mode for goal-shaped work.

claude --version
# Expect 2.1.139 or later. Upgrade if older.

Staying current (version self-check)

Copy-based RePrompter installs can tell you when they are behind the latest release. Claude Code plugin installs stay silent here because native plugin update detection owns freshness. On the first invocation in a copy-based session, RePrompter runs a fail-soft check (scripts/version-check.js) that compares your local SKILL.md version against the latest GitHub release and prints a notice only if you’re behind (silent when up to date). The result is cached ~24h (keyed by repo), so repeat runs add no latency; the first uncached check waits up to ~3s for GitHub, then fails soft and silent if it can’t reach it (a failed lookup is cached ~1h so offline sessions don’t repeat the timeout). Disable it entirely with REPROMPTER_VERSION_CHECK=0.

The notice’s upgrade command is path-aware: it re-fetches into the exact directory this skill is installed in, so it works the same whether you run Claude Code (~/.claude/skills/reprompter), Codex (~/.codex/skills/reprompter), OpenClaw, Grok CLI, or a project-local skills/reprompter/. (Hermes installs ship no scripts/, so the check doesn’t run there — use hermes skills install to update.)

Run it manually any time:

cd skills/reprompter                   # run from the skill's install dir (where scripts/ lives)
node scripts/version-check.js          # prints a notice only if behind; silent otherwise
node scripts/version-check.js --json   # explicit status: {local, latest, behind, notice}

To get nudged at session start (Claude Code, opt-in), add a SessionStart hook in ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      { "hooks": [ { "type": "command", "command": "node /absolute/path/to/skills/reprompter/scripts/version-check.js" } ] }
    ]
  }
}

Because a skill is cached per session, after updating you must start a new session for the new version to load.

OpenClaw / Codex / Grok CLI / Hermes Agent

Root SKILL.md is canonical for Claude Code, Codex, OpenClaw, Grok, and direct GitHub browsing. skills/reprompter/ is the Hermes-only installable package, generated from root and sanitized for Hermes Skills Guard.

Run copy-based installs from the parent directory that contains a cloned or downloaded reprompter/ folder:

mkdir -p /path/to/workspace/skills
cp -R reprompter /path/to/workspace/skills/

For Hermes Agent v0.14+, prefer the generated install package so Skills Guard scans only the runtime skill artifact:

hermes skills install AytuncYildizli/reprompter/skills/reprompter

Avoid using the two-part Hermes identifier as the primary install command because it can resolve stale marketplace content:

hermes skills install AytuncYildizli/reprompter

Hermes Agent’s default manual skill location is ~/.hermes/skills/reprompter/. The skills/ package is excluded from GitHub source archives, so a manual copy needs a git clone (or any hermes skills install form above), not a tarball/ZIP download:

git clone https://github.com/AytuncYildizli/reprompter.git
mkdir -p ~/.hermes/skills
cp -R reprompter/skills/reprompter ~/.hermes/skills/

For Codex, install or update the CLI and confirm the goals feature is available:

npm install -g @openai/codex@latest
codex --version
codex features list | grep '^goals'

If goals is present but disabled, set features.goals = true in ~/.codex/config.toml and start a fresh Codex session before using /goal.

Any LLM

Use SKILL.md as the behavior spec. Templates are in references/.

---

Quick Start

Improve a prompt — the everyday case. RePrompter picks the shape for the job: a structured, scored spec prompt for bounded work, or an autonomous build prompt for whole-product asks (announced, and you can say “spec” to override).

reprompt this: build a REST API with auth and rate limiting

Build a whole thing — one prompt that makes the app, game, or site. Finishes in one session; ask for a team and the same brief splits across agents.

one-shot this: a focus timer app like a clean pomodoro tool

Advanced: extract the prompt DNA from a great output you want to reproduce.

reverse reprompt this: [paste a great output you want to reproduce]

RePrompter interviews you when interactive clarification is useful, generates the prompt, and (for spec prompts) shows a before/after quality score.

---

How It Works

Improve

Rough prompt → Input guard → Interview (2-5 questions) → Specifiability router
→ spec-XML (enumerable done-state)  OR  outcome-prose (quality-bar ask, announced)
→ Quality scoring (spec only) → Delta rewrite if < 7/10 → optional output format

18 validated templates cover feature, bugfix, refactor, testing, API, UI, security, docs, content, research, workflow, and multi-agent swarm patterns. The router picks spec-XML for bounded work and the One-Shot prose shape for whole-product asks; you can always override.

Build

Idea → plain-language interview (max 4) → done-list brief
→ one prompt (default, finishes in one session)  OR  split across a team

The prose brief names a real reference, staffs parallel work with a separate harsh critic that judges the running artifact, and ends on a checkable done-list. Picking a team seeds the Repromptverse engine: each work area becomes an agent scope, the done-list becomes the team’s success criteria, the critic becomes the Phase-4 evaluator, and the smoothing pass becomes synthesis.

Advanced: Repromptverse & Reverse

Repromptverse  → Plan Cards → per-agent prompt → execute → Result Cards → evaluate → retry (max 2)
Reverse        → exemplar → EXTRACT structure → ANALYZE type/domain/tone → SYNTHESIZE prompt → flywheel

Repromptverse is the team-execution engine (standalone or seeded by a Build brief). Reverse extracts a reusable prompt from a great output and seeds the flywheel — solving its cold-start problem with known-good prompt/output pairs.

---

Key Features

Closed-Loop Flywheel (v12) - The loop is now end-to-end. Every prompt emits a `` block of testable assertions. After execution, scripts/outcome-record.js writes a structured record joining prompt + criteria + output; scripts/evaluate-outcome.js scores it against the criteria (regex / predicate / llm_judge / manual). Records feed into a local flywheel via npm run flywheel:ingest. At generation time, REPROMPTER_FLYWHEEL_BIAS=1 makes the skill consult past outcomes and bias toward historically winning recipes. npm run flywheel:ab compares bias-on vs bias-off effectiveness so you can prove whether the bias is helping. npm run flywheel:export and npm run flywheel:import move privacy-sanitized aggregate ledger packs across your own fleet without RePrompter networking. All data local.

Prompt Flywheel Recipe Fingerprinting - Every prompt carries a deterministic recipe fingerprint (template + patterns + capability tier + domain + context layers + quality bucket). Strategy learner groups outcomes by fingerprint so recommendations are grounded in repeated evidence, not one-off runs.

Ambient Prompt Gate (v12.13) - Opt-in Claude Code, Codex CLI, and Hermes Agent prompt hooks score task-shaped prompts locally and silently nudge only when the request is below threshold. Claude Code also records the boolean Stop-hook acceptance outcome. The gate is fail-soft, never blocks a prompt, dedupes outcomes, and writes no prompt or transcript text to the local outcome log (called telemetry in the code) or state.

Agent Cards - Plan Cards (before execution), Status Line (during), Result Cards (after). Full transparency into what agents will do, are doing, and found.

Advisory Run Supervisor (v12.15) - scripts/run-supervisor.js --advise reads local run telemetry and returns healthy, stalled, failing-evals, completed, or unknown verdicts for the orchestrator. It is read-only and advisory: it never kills, restarts, spawns, or messages workers.

Dimension Interview - Low-scoring prompt dimensions trigger targeted questions for interactive use. Autonomous goal/workflow/team lanes document reasonable defaults in `` instead of blocking on low-value questions.

Pattern Library - 7 pluggable prompt engineering patterns: runtime-aware constraint placement (constraint-first-framing compatibility key), uncertainty labeling, self-critique checkpoints, delta retry scaffolds, evidence-strength labeling, context-manifest transparency, and tool-description quality.

2026 Template Alignment - Templates keep validated structure, roles, success criteria, and delta retries while updating contested guidance: XML is the default but not mandatory, schemas route to structured-output APIs when available, prompts emphasize outcomes over hand-written plans, and constraints stay load-bearing rather than exhaustive.

Capability Routing - When multiple models are available, routes each agent by capability tier (reasoning, long context, cost-optimized, latency-optimized) with provider-diverse fallback chains.

Privacy

RePrompter never transmits or collects anything from anyone. The Ambient Prompt Gate and flywheel write local files only on the user’s own machine:

• Gate state and outcome log: $XDG_CACHE_HOME/reprompter/
• Flywheel and runtime telemetry runs: .reprompter/

No prompt or transcript text is ever persisted. Session ids are sha256-hashed before they are written.

Fleet flywheel packs are sanitized aggregates only: no prompt text, prompt hashes, task slugs, role labels, or hostnames are exported.

The single network call in the entire product is the version self-check (scripts/version-check.js) querying the GitHub releases API for the latest RePrompter release. It sends no user data and can be disabled with REPROMPTER_VERSION_CHECK=0.

You can inspect the local files, delete them anytime, and kill the gate log with REPROMPTER_TELEMETRY=0. To verify the local-only gate directly, read scripts/prompt-gate.js and scripts/stop-gate.js: they have no network imports.

---

Testing

npm run check    # 344 tests + 4 benchmarks
npm run test:reverse-engineer  # individual suite example

All benchmarks at 100%: swarm routing (9/9), real-world routing (64/64), artifacts (84/84), flywheel (13/13), provider (9/9).

---

Compatibility

¹ Claude Code /goal requires CLI v2.1.139+ (shipped 2026-05-11) and depends on the hooks layer. Under disableAllHooks or allowManagedHooksOnly in settings.json, /goal is unavailable on any version — v2.1.140 only upgraded the failure mode from a silent hang to a clear error message. No config flag needed beyond the version pin in environments that permit hooks; managed environments that block hooks must use Single mode for goal-shaped work.

² Hermes Agent /goal is documented in the v0.13.0 / 2026.5.7 release. It uses the same /goal command shape, with /goal status, /goal pause, /goal resume, and /goal clear available in the runtime.

Codex parallel paths: D1 native subagents (Codex CLI 0.121.0+, multi_agent default-enabled) or D2 shell-level (codex exec --ephemeral --sandbox workspace-write + background + wait; workspace-write is required for workers to write their /tmp/rpt-*.md artifacts, and codex exec keeps approval = never automatically). See SKILL.md Option D and references/runtime/codex-runtime.md.

Grok parallel paths: F1 native subagents (spawn_subagent) or F2 shell-level (grok -p ... & + wait). Grok does not expose /goal.

Hermes parallel paths: G1 delegate_task batch for normal Repromptverse, G2 shell-level (hermes -z / hermes chat -q + background + wait) for external orchestration, or G3 Kanban for durable multi-profile workflows. See references/runtime/hermes-agent-runtime.md.

³ Claude dynamic Workflow tool (Option H + the Workflow preflight lane): RePrompter compiles the reprompted task into a runnable .workflow.js (JS-scripted background fan-out — agent()/parallel()/pipeline() with schema-validated returns and resumeFromRunId). Picked at Order 4, just below Option B, because the Workflow tool has no mid-run cross-agent messaging. First-class ultracode (adversarial verify + completeness critic + budget-scaled fleets) with a --no-ultracode off-ramp. See references/runtime/claude-workflow-runtime.md. Compiler: scripts/workflow-command.js.

⁴ Hermes Agent installs ship no scripts/ helpers, so the Ambient Prompt Gate needs a git clone or copied checkout that includes scripts/prompt-gate.js.

⁵ Requires the headless-relay skill (v1.3.1+) installed in the same session — its README documents install paths for Claude Code, Codex CLI, OpenClaw, and Hermes. The offer is availability-gated: only targets whose CLI is installed and authenticated are listed (built-in lanes plus user-connected custom/local targets), and when none are available — or the relay skill is absent — the step is completely silent. Grok CLI is a relay target, not a documented headless-relay host. The Grok target additionally requires headless-relay v2.0.0+, which isolates Grok fail-closed in a non-git directory (v3.0.0 recommended — it also runs Grok under a hermetic env -i with a clean HOME/temp GROK_HOME and its cross-tool config scan off, so your global ~/.grok rules do not leak into the model turn); on an older relay, do not deliver to Grok.

---

Configuration

Ambient Prompt Gate (Claude Code, Codex CLI, Hermes Agent)

Claude Code plugin installs register the prompt and Stop hooks automatically. For copy-based Claude Code installs, add them manually:

{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [ { "type": "command", "command": "node /absolute/path/to/skills/reprompter/scripts/prompt-gate.js" } ] }
    ],
    "Stop": [
      { "hooks": [ { "type": "command", "command": "node /absolute/path/to/skills/reprompter/scripts/stop-gate.js" } ] }
    ]
  }
}

For Codex CLI copy-based installs, add a documented hook definition:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /absolute/path/to/skills/reprompter/scripts/prompt-gate.js --format=codex",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Review and trust the command via /hooks; changing the command requires re-trusting because Codex keys trust to the hook definition hash. Codex’s [features] hooks = false disables all hooks.

For Hermes Agent, use a clone or copied checkout that includes scripts/, then document the shell hook in ~/.hermes/config.yaml:

hooks:
  pre_llm_call:
    - command: "node /absolute/path/to/skills/reprompter/scripts/prompt-gate.js --format=hermes"
      timeout: 5

Hermes asks for first-use approval per (event, command); non-TTY runs need HERMES_ACCEPT_HOOKS=1 or hooks_auto_accept: true. pre_llm_call cannot block, matching RePrompter’s never-block contract.

Ambient flags: REPROMPTER_AMBIENT=0 disables nudges and outcome recording, REPROMPTER_AMBIENT_THRESHOLD changes the default score threshold (5), REPROMPTER_AMBIENT_COOLDOWN_MIN changes the per-session cooldown (15), and REPROMPTER_TELEMETRY=0 disables the privacy-safe gate local outcome log. Runtime-wide hook kill switches still win globally. The gate never blocks prompts or Stop events and never persists prompt or transcript text.

Repromptverse

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "preferences": {
    "model": "opus"
  }
}

Feature flags: REPROMPTER_FLYWHEEL, REPROMPTER_POLICY_ENGINE, REPROMPTER_LAYERED_CONTEXT, REPROMPTER_STRICT_EVAL, REPROMPTER_PATTERN_LIBRARY, REPROMPTER_TELEMETRY (all 0|1, enabled by default).

---

Architecture

SKILL.md                        # Behavior spec (the product)
references/                     # 18 templates (XML + markdown)
  feature-template.md
  bugfix-template.md
  reverse-template.md
  marketing-swarm-template.md
  ...
scripts/                        # Runtime engine
  intent-router.js              # Mode + profile routing
  reverse-engineer.js           # Exemplar analysis + prompt extraction
  capability-policy.js          # Model selection + fallback chains
  context-builder.js            # Token-budgeted context assembly
  artifact-evaluator.js         # Output quality gates
  pattern-selector.js           # Pluggable prompt patterns
  recipe-fingerprint.js         # Strategy hashing
  outcome-collector.js          # Flywheel data capture
  strategy-learner.js           # Historical recommendation engine
  repromptverse-runtime.js      # Orchestration composer

---

Contributing

See CONTRIBUTING.md. PRs welcome.

License

MIT