promper

Promper is a prompt-engineering toolkit for Claude Code and Codex. It routes rough intent to specialist personas, turns intent into evidence-backed plans, and keeps execution behind explicit quality gates.

The idea

Promper treats installed agents as prompt engineering: each agent contributes a domain-tuned persona instead of an invented “expert” role. The deterministic engine finds the right source, hydrates its context, and presents an engineered prompt before anything runs.

rough intent
  → deterministic routing       → lean map → domain agent
  → persona + toolkit           → engineered prompt
  → optional SDD / graph run    → gated execution and review

The native planning spine is Genesis → Sideeye → Horizon → Execute → Review. Genesis grounds the request, Sideeye tests patterns against evidence, Horizon provides visual validation, and the execution engine consumes the shared artifacts.

Install / use

Claude Code plugin

Inside Claude Code:

/plugin marketplace add justjammin/promper
/plugin install promper@promper

Equivalent terminal commands:

claude plugin marketplace add justjammin/promper
claude plugin install promper@promper

Reload plugins or restart Claude Code when prompted. Plugin installation loads Promper's skills and hooks directly; it does not run npm installation.

Build the role-routing map once after installation:

npx @ninjamin/promper bootstrap

This adds the required wshobson/agents role source and writes the lean map to ~/.invoker/map/.

npm fallback

npx @ninjamin/promper

This copies all nine skills into ~/.claude/skills/ and bootstraps the same role source. Re-run the command to refresh the copied skills and map. Use npx @ninjamin/promper scan to add supplementary local agents.

See docs/cli-reference.md for installation behavior, local checkout commands, and the full CLI reference.

Skills

Each skill has a short entry below and a detailed contract in docs/skills-reference.md.

| Command | What it does | Details | |---|---|---| | /promper <intent> | Creates a role-grounded prompt from rough intent. | Reference · SKILL.md | | /promper:setup | Builds the deterministic lean routing map from installed agents. | Reference · SKILL.md | | /prim | Audits agents against the prompt-engineering standard and records seals. | Reference · SKILL.md | | /promper:breakdown <intent> | Compile one finite project graph as an SDD/DAG package with PRD, routed prompts, and lane plan. | Reference · SKILL.md | | /promper:singularity <goal> | Execute and adapt a bounded graph through a bounded accretion-collapse loop until evidence-backed convergence or an event horizon. | Reference · SKILL.md | | /promper:orbit <intent> | Coordinates Genesis, Sideeye, Horizon, execution, and final review behind human gates. | Reference · SKILL.md | | /promper:genesis <intent> | Produces an evidence-grounded PRD, SDD-format Spec, and machine plan spine. | Reference · SKILL.md | | /promper:horizon <plan.json> | Runs the schema-backed visual gate; session/TUI owns answers for combined review artifacts. | Reference · SKILL.md | | /promper:sideeye <plan-or-diff> | Selects or reviews patterns; MAGI can elect among three independent candidates. | Reference · SKILL.md |

CLI reference

The CLI is deterministic and runs without model calls. Published installs use npx @ninjamin/promper; local checkouts can use node bin/promper.mjs.

| Command | Purpose | |---|---| | promper bootstrap | Add the role-source marketplace when missing, then scan it. | | promper scan | Build or refresh the lean routing map from flat dirs, plugin marketplaces, or category roots. | | promper hydrate <agent> "<task>" | Resolve an agent and emit a spawn-ready persona plus toolkit. | | promper brief "<task>" | Build the deterministic role-bearing spawn brief. | | promper gate "<prompt>" | Classify a turn as deep or follow-up; --plan marks plan/spec mode. | | promper classify "<text>" | Map task text to domains and suggested agents. | | promper horizon build\|serve\|export | Build, serve, or export a Horizon plan/review artifact. |

Horizon shortcommands:

promper horizon build .promper/<slug>/plan.json
promper horizon serve .promper/<slug>/review-artifact.json .promper/<slug>/horizon/feedback.json
promper horizon export .promper/<slug>/review-artifact.json .promper/<slug>/horizon.html

Direct shorthand is also supported: promper horizon <artifact.json> <feedback.json>. Run promper horizon --help for options. Full flags, map rules, filtering, and artifact semantics live in docs/cli-reference.md.

Orbit observer and MCP

Rich Orbit run data is local and opt-in. Start Horizon with a run root to enable read-only observer routes:

promper horizon serve \
  .promper/<slug>/plan.json \
  .promper/<slug>/horizon/feedback.json \
  --run-root=.promper

This adds GET /api/run and GET /api/run/artifact?path=<manifest-listed-path>; /api/status remains state-only. The optional @ninjamin/promper-orbit-mcp companion exposes exactly three read-only tools: orbit_list_runs, orbit_get_run, and orbit_query. It returns bounded summaries or cited excerpts only, never raw artifact access or execution controls.

Set PROMPER_ORBIT_RUN_ROOT or pass --run-root=<path> to configure the companion. Observer manifests, allowed artifacts, traversal protections, and evidence limits are documented in skills/orbit/observer/README.md.

Active mode

Promper's plugin hooks run automatically in Claude Code: SessionStart injects the contract; UserPromptSubmit classifies new work; PreToolUse enriches useful spawns and gates repository edits; SessionEnd clears the session decision. PROMPER_ACTIVE=0 disables all five hooks while manual slash commands remain available.

Active mode is verified on Claude Code CLI. Codex hook behavior remains experimental, and the VS Code extension currently drops UserPromptSubmit additionalContext. See docs/plugin-flow.md for the flow, state hand-off, verification matrix, and legacy-config migration guidance.

Repository layout

The corrected repository tree and generated-bundle notes live in docs/repo-layout.md.

More documentation

• docs/skills-reference.md — one-paragraph skill guide and artifact spine.
• docs/cli-reference.md — full CLI behavior and flags.
• docs/plugin-flow.md — manual/active hook flow and state contract.
• docs/migrating-legacy-global-config.md — remove older global hook/config setup.
• docs/orbit-grounding/ — Genesis, Sideeye, Horizon, and Orbit grounding records.
• reference/pe-principles.md — shared prompt-engineering standard.

License

Apache-2.0