Prompt Registry

Prompt Registry is a small toolkit for storing, inspecting, validating, rendering, and assembling reusable prompt assets.

The shipped prompt assets and examples are English-first so the repository is ready for public and open-source workflows out of the box.

Right now the project is intentionally constructor-first:

• build prompts from versioned templates;
• compose prompts from reusable snippets;
• inspect required placeholders before rendering;
• validate the repository so broken prompt assets are caught early;
• orchestrate multi-step manual workflows on top of constructors.

The repository may later grow into a GitHub-star discovery workflow, but that is not the current product scope.

Start here

If you are new to the project, the easiest mental model is:

• use render when you want one plain prompt file;
• use build-constructor when you want a prompt template plus reusable guardrail snippets;
• use console when you want a guided interactive flow instead of long CLI commands;
• use run-pipeline only when you want a manual multi-step workflow;
• use validate after changing prompts, constructors, or pipelines.

Current scope

What the project does today:

• render a single prompt template;
• inspect-prompt to see required placeholders;
• build-constructor to assemble a prompt from a template plus shared snippets;
• validate the registry contents;
• optionally run manual pipelines for multi-step prompt workflows;
• ship reusable assets for intake, spec, test planning, execution, review, risk review, and PR delivery.

What the project explicitly does not do in v1:

• call LLM providers directly;
• orchestrate agents;
• fetch GitHub stars;
• hide workflow logic behind automation;
• add GUI or provider-specific integrations.

Repository layout

constructors/ reusable prompt constructors (template + snippets)
prompts/      prompt templates and shared snippets
pipelines/    optional manual multi-step workflows
examples/     sample inputs for local experiments
docs/         format and usage notes
src/          package source
tests/        test suite

Quick start

Create a virtual environment, install the project, and inspect the available constructors.

macOS / Linux / Git Bash

python -m venv .venv
. .venv/bin/activate
pip install -e .[dev]

prompt-registry list-constructors
prompt-registry show-constructor --root . --constructor constructors/pr_plan_strict.toml

Windows cmd.exe

python -m venv .venv
call .venv\Scripts\activate.bat
pip install -e .[dev]

prompt-registry list-constructors
prompt-registry show-constructor --root . --constructor constructors/pr_plan_strict.toml

If prompt-registry is not available yet in your shell, reinstall with pip install -e .[dev] after activation.

First 5 minutes

If you only try one workflow first, make it this one. It follows the project's main happy path: build a prompt from a constructor.

macOS / Linux / Git Bash

prompt-registry build-constructor \
  --root . \
  --constructor constructors/pr_plan_strict.toml \
  --var REPO_NAME=project_invariant \
  --var-file REQUEST=examples/project_invariant/request_example.md \
  --output built/pr_plan.md

prompt-registry validate --root .

Windows cmd.exe

prompt-registry build-constructor ^
  --root . ^
  --constructor constructors\pr_plan_strict.toml ^
  --var REPO_NAME=project_invariant ^
  --var-file REQUEST=examples\project_invariant\request_example.md ^
  --output built\pr_plan.md

prompt-registry validate --root .

If everything is working, you will get:

• a rendered prompt at built/pr_plan.md;
• a successful Registry validation passed. message;
• a concrete feel for how constructors, variables, and examples fit together.

Common flows

Build a planning prompt from a constructor

Use this when you want a reusable prompt assembled from a base template plus shared snippets.

prompt-registry build-constructor \
  --root . \
  --constructor constructors/pr_plan_strict.toml \
  --var REPO_NAME=project_invariant \
  --var-file REQUEST=examples/project_invariant/request_example.md

prompt-registry build-constructor ^
  --root . ^
  --constructor constructors\pr_plan_strict.toml ^
  --var REPO_NAME=project_invariant ^
  --var-file REQUEST=examples\project_invariant\request_example.md

Inspect a plain template

Use this when you want to see which placeholders must be provided before rendering.

prompt-registry inspect-prompt \
  --prompt prompts/execution/pr_execute_universal.md

prompt-registry inspect-prompt ^
  --prompt prompts\execution\pr_execute_universal.md

Validate the whole registry

Run this after changing prompts, constructors, or pipelines.

prompt-registry validate --root .

prompt-registry validate --root .

Launch the interactive console

If you prefer a guided interactive flow instead of long argument lists, launch the console app:

prompt-registry console --root .
prompt-registry-console --root . --color never

prompt-registry console --root .
prompt-registry-console --root . --color never

The interactive console uses ANSI colors without external dependencies. Keep the default --color auto, force colors with --color always, or disable them with --color never if your terminal renders ANSI poorly.

Run a manual pipeline

Use this only when you want a traceable multi-step workflow where one stage feeds the next one manually.

prompt-registry run-pipeline \
  --root . \
  --pipeline pipelines/request_to_spec.toml \
  --input repo_name=project_invariant \
  --input-file request=examples/project_invariant/request_example.md

prompt-registry run-pipeline ^
  --root . ^
  --pipeline pipelines\request_to_spec.toml ^
  --input repo_name=project_invariant ^
  --input-file request=examples\project_invariant\request_example.md

You can also write rendered output to a file with --output. Relative output paths are resolved against --root, so --output built/result.md writes inside the repository root you selected.

Validation now also guards a few important invariants:

• constructor and pipeline asset references must stay inside the repository root;
• pipeline step-output references must point to earlier steps that actually capture output;
• output_key values must stay unique within a pipeline.

Why constructors matter

Plain prompt files are useful, but the real leverage appears when prompts become:

• versioned assets;
• parameterized templates;
• reusable building blocks;
• deterministic assemblies that can be validated before use.

That is why the repository now has a separate constructors/ layer: prompt templates stay focused, while reusable guardrails live in snippets.

Optional manual pipelines

The project still includes manual pipeline support for step-by-step workflows where one rendered prompt feeds the next stage. This is kept as an optional layer, not the center of the product.

Pipeline runs are manual by design:

1. render a prompt;
2. paste the external model output yourself;
3. store artifacts under .runs/;
4. continue to the next step.

This keeps the current tool simple and model-agnostic while the constructor mode stays the main supported workflow.

New shipped workflows now cover:

• request -> spec
• request -> plan -> execute
• implementation -> review -> risk review -> PR description

Troubleshooting

• prompt-registry or prompt-registry-console is not found: reactivate the virtual environment and run pip install -e .[dev] again.
• Missing placeholder value for <...>: run prompt-registry inspect-prompt ... or prompt-registry show-constructor ... first to see which placeholders are required.
• Output was written to an unexpected directory: --output is resolved relative to --root, not relative to wherever your shell currently is.
• A constructor or pipeline path is rejected as outside the repository: asset references inside constructors and pipelines must stay repo-relative and inside the selected repository root.
• You are not sure whether to use render, build-constructor, or run-pipeline: start with build-constructor; it is the main supported workflow in this repository.

Commands

• console
• render
• inspect-prompt
• list-prompts
• list-constructors
• show-constructor
• build-constructor
• list-pipelines
• show-pipeline
• run-pipeline
• validate

For a more detailed walkthrough, see docs/how_to_use.md, docs/constructor_format.md, and docs/pipeline_format.md.

Roadmap

Near-term focus:

• strengthen prompt constructors;
• improve prompt validation and examples;
• keep assets deterministic and easy to maintain.

Later, after the constructor mode is solid:

• index prompt assets from external sources;
• experiment with GitHub-star collection workflows;
• add search/discovery layers on top of the registry.

See docs/constructor_format.md, docs/how_to_use.md, docs/pipeline_format.md, and docs/roadmap.md for details.