promptkitty

README

PromptKitty

PromptKitty Assemble for task-specific engineering prompts

PromptKitty packages Microsoft PromptKit as a deterministic Go library and a standalone CLI. Describe the engineering task, find the most relevant template with weighted BM25 search, inspect its parameters, and assemble a complete prompt without reading external component files or contacting a service.

The embedded snapshot is PromptKit v0.6.1: 15 personas, 56 protocols, 24 formats, 5 taxonomies, 71 templates, and 4 pipelines. Every declared parameter must be resolved before assembly succeeds.

Install and set up

Run PromptKitty directly from npm:

npx --yes @baldaworks/promptkitty@latest --version
npx --yes @baldaworks/promptkitty@latest setup codex

Or install the native Go command:

go install github.com/baldaworks/promptkitty/cmd/promptkitty@v0.3.0

PromptKitty can install its Assemble integration for five agent hosts:

Host	Setup
Codex	promptkitty setup codex
Claude Code	promptkitty setup claude
Grok Build	promptkitty setup grok
Copilot CLI	promptkitty setup copilot
OpenCode	promptkitty setup opencode

Codex, Claude Code, Grok Build, and Copilot CLI setup use the repository's plugin marketplace. OpenCode setup writes .opencode/skills/promptkitty-assemble/SKILL.md and .opencode/commands/promptkitty.md into the current project. Existing OpenCode files are preserved; use --force only when they should be replaced. Host CLIs and credentials remain external.

Invoke the installed skill as $promptkitty:assemble in Codex, /promptkitty:assemble in Claude Code, /promptkitty-assemble in Grok Build or Copilot CLI, and /promptkitty in OpenCode.

Quick start

Search for a template using a natural-language task:

promptkitty search "write a requirements document" --type template
promptkitty show author-requirements-doc --json

Assemble the selected template after supplying every declared parameter:

promptkitty assemble author-requirements-doc \
  --param project_name=PromptKitty \
  --param description='Add deterministic offline prompt discovery' \
  --param context='Go library and CLI with an embedded PromptKit catalog' \
  --param audience='Go maintainers and coding agents'

assemble writes Markdown to stdout. Use --output only when a file is wanted, --json for the complete assembly result, and repeatable --param-file, --protocol, and --taxonomy flags for multiline or additional composition inputs.

BM25 relevance search

search uses the in-memory BM25 index from vecgo. PromptKitty indexes component names, descriptions, remaining metadata, and complete Markdown bodies with weights 4 / 2 / 1 / 1.

promptkitty search "review Go code" --type template --json
promptkitty search "root cause of a memory leak bug" --type template
promptkitty search "thread safety" --type protocol

Tokenization is Unicode-aware, common query terms are suppressed, filters retain global corpus scoring, and ties use stable catalog order. Scores stay internal so the existing Component JSON contract remains unchanged.

The installed command performs search and assembly offline. npx may contact npm to acquire the package when it is not already cached; the native package then uses only the embedded catalog.

Command surface

promptkitty list [--type ...] [--category ...] [--language ...] [--json]
promptkitty search <query> [--type ...] [--json]
promptkitty show <name> [--json]
promptkitty assemble <template> [composition flags]
promptkitty setup <codex|claude|grok|copilot|opencode> [--force]

Applications that already use Cobra can mount the same command tree:

cmd := cli.NewCommand(cli.Options{Use: "promptkit"})
host.AddCommand(cmd)

The reusable cli package keeps successful output on stdout and diagnostics on stderr. The root package remains library-first and has no CLI or process dependencies.

Go library

Install the module:

go get github.com/baldaworks/promptkitty@v0.3.0

Load the embedded catalog and assemble a fully parameterized prompt:

library, err := promptkitty.New()
if err != nil {
    return err
}

result, err := library.Assemble(promptkitty.AssembleRequest{
    Template: "investigate-bug",
    Params: map[string]string{
        "problem_description": "Parser crashes on empty input",
        "code_context":        "src/parser.c",
        "environment":         "Linux amd64",
    },
})
if err != nil {
    return err
}

fmt.Println(result.Markdown)

Browse the same immutable catalog through Go:

templates := library.List(promptkitty.Filter{Type: promptkitty.ComponentTemplate})
matches := library.Search("security review", promptkitty.Filter{Type: promptkitty.ComponentTemplate})
detail, err := library.Show("review-code")
pipelines := library.Pipelines()

NewFromFS loads a compatible private catalog for tests or applications. Runtime assembly remains one-pass, deterministic, and strict about unresolved parameters.

npm distribution

Releases publish @baldaworks/promptkitty with statically linked native executables for macOS and Linux on amd64/arm64 and Windows on amd64. Omnidist builds every target with CGO_ENABLED=0. The npm launcher selects the matching binary, so users need neither Go nor CGO tooling.

Updating the PromptKit snapshot

Change only the ref field in content/upstream.json, then run:

go generate ./...

The generator resolves that ref through GitHub, downloads the archive, copies supported components and the upstream license, and rewrites the resolved commit and SHA-256 inventory. Review content, license, commit, and inventory changes together. Do not hand-edit pinned component files.

About PromptKit

Microsoft PromptKit is a composable prompt engineering library organized around personas, protocols, taxonomies, formats, templates, and pipelines. Its bootstrap workflow inspired PromptKitty Assemble; PromptKitty adapts discovery and parameter gathering to the stable search, show, and assemble CLI instead of reading or rewriting upstream files.

License

PromptKitty's original Go code and documentation are available under the root MIT License, copyright Alexey Samoylov.

The embedded Microsoft PromptKit content remains under Microsoft's MIT license and attribution. Its exact license copy is stored at third_party/promptkit/LICENSE; see THIRD_PARTY_NOTICES.md for provenance and third-party terms.

PromptKitty uses vecgo's Apache-2.0-licensed BM25 implementation. The exact license is stored at third_party/vecgo/LICENSE and included with statically linked npm artifacts.

Documentation

Overview

Package promptkitty provides PromptKitty's embedded PromptKit component catalog and a deterministic prompt assembler.

Index

• type AmbiguousError
  • func (e *AmbiguousError) Error() string
• type AssembleRequest
• type AssembleResult
• type Component
• type ComponentDetail
• type ComponentRef
• type ComponentType
• type Filter
• type Library
  • func New() (*Library, error)
  • func NewFromFS(fsys fs.FS, root string) (*Library, error)
  • func (l *Library) Assemble(request AssembleRequest) (AssembleResult, error)
  • func (l *Library) List(filter Filter) []Component
  • func (l *Library) Pipelines() []Pipeline
  • func (l *Library) Search(query string, filter Filter) []Component
  • func (l *Library) Show(name string) (ComponentDetail, error)
  • func (l *Library) Version() string
• type NotFoundError
  • func (e *NotFoundError) Error() string
• type ParametersError
  • func (e *ParametersError) Error() string
• type Pipeline
• type PipelineStage

Types

type AmbiguousError

type AmbiguousError struct {
	Name  string
	Types []ComponentType
}

AmbiguousError reports a name shared by more than one component type.

func (*AmbiguousError) Error

func (e *AmbiguousError) Error() string

type AssembleRequest

type AssembleRequest struct {
	Template             string
	Params               map[string]string
	Persona              string
	AdditionalProtocols  []string
	AdditionalTaxonomies []string
	// Format leaves the template default when nil, omits the format when it
	// points to an empty string, and otherwise replaces the default.
	Format *string
}

AssembleRequest selects a template, supplies every declared parameter, and optionally adjusts its component composition.

type AssembleResult

type AssembleResult struct {
	Markdown   string         `json:"markdown"`
	Template   Component      `json:"template"`
	Components []ComponentRef `json:"components"`
}

AssembleResult is a completely rendered PromptKit prompt. All declared template parameters have been substituted.

type Component

type Component struct {
	Name        string         `json:"name"`
	Type        ComponentType  `json:"type"`
	Category    string         `json:"category,omitempty"`
	Path        string         `json:"path,omitempty"`
	Description string         `json:"description,omitempty"`
	Language    string         `json:"language,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

Component is a catalog entry enriched with its Markdown frontmatter. Metadata is a defensive copy and may be inspected by future transports.

type ComponentDetail

type ComponentDetail struct {
	Component

	UsedByTemplates []string `json:"usedByTemplates,omitempty"`
}

ComponentDetail adds reverse template references to a component.

type ComponentRef

type ComponentRef struct {
	Name string        `json:"name"`
	Type ComponentType `json:"type"`
	Path string        `json:"path"`
}

ComponentRef records one component included in an assembled prompt.

type ComponentType

type ComponentType string

ComponentType identifies one PromptKit component layer.

const (
	ComponentPersona  ComponentType = "persona"
	ComponentProtocol ComponentType = "protocol"
	ComponentFormat   ComponentType = "format"
	ComponentTaxonomy ComponentType = "taxonomy"
	ComponentTemplate ComponentType = "template"
)

type Filter

type Filter struct {
	Type     ComponentType
	Category string
	Language string
}

Filter selects catalog components. Empty fields match every component.

type Library

type Library struct {
	// contains filtered or unexported fields
}

Library is an immutable PromptKit catalog and assembler.

func New

func New() (*Library, error)

New loads the pinned embedded PromptKit component library.

func NewFromFS

func NewFromFS(fsys fs.FS, root string) (*Library, error)

NewFromFS loads a PromptKit library rooted at root within fsys. It is useful for tests and callers that maintain a compatible private catalog.

func (*Library) Assemble

func (l *Library) Assemble(request AssembleRequest) (AssembleResult, error)

Assemble resolves a template and returns a fully rendered prompt. Mustache examples that are not declared template parameters are ordinary Markdown literals and are preserved verbatim.

func (*Library) List

func (l *Library) List(filter Filter) []Component

List returns matching components in stable type/category/name order.

func (*Library) Pipelines

func (l *Library) Pipelines() []Pipeline

Pipelines returns the manifest's artifact pipelines in stable name order.

func (*Library) Search

func (l *Library) Search(query string, filter Filter) []Component

Search ranks catalog components by their relevance to query, then applies filter. Search is deterministic and uses only the loaded catalog.

func (*Library) Show

func (l *Library) Show(name string) (ComponentDetail, error)

Show returns one component and the templates that reference it.

func (*Library) Version

func (l *Library) Version() string

Version returns the version declared by the embedded PromptKit manifest.

type NotFoundError

type NotFoundError struct {
	Type ComponentType
	Name string
}

NotFoundError reports a requested component that is absent from the catalog.

func (*NotFoundError) Error

func (e *NotFoundError) Error() string

type ParametersError

type ParametersError struct {
	Template string
	Missing  []string
	Unknown  []string
}

ParametersError reports missing or unknown template parameters.

func (*ParametersError) Error

func (e *ParametersError) Error() string

type Pipeline

type Pipeline struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Stages      []PipelineStage `json:"stages"`
}

Pipeline is one named sequence from the embedded PromptKit manifest.

type PipelineStage

type PipelineStage struct {
	Template string `json:"template"`
	Consumes any    `json:"consumes,omitempty"`
	Produces any    `json:"produces,omitempty"`
}

PipelineStage describes one template and its artifact contract.