# promptkitx

Prompt pack manager that drops AGENTS snippets and `.agent` templates into a repo. Ships with the ExecPlan pack and is ready to host more packs later.

## Quick use (no install)

- Python/uvx (PyPI): `uvx promptkitx install execplan`
- Python/uvx (from GitHub tip): `uvx --from git+https://github.com/mikewong23571/promptkit.git promptkit install execplan`
- Node/npx: `npx promptkitx install execplan`

Both commands are idempotent and cache their envs. Add `-p /path/to/repo` to target another repo and `--force` to overwrite existing files.

## Install (optional)

- Python: `pip install promptkitx` or `pipx install promptkitx`
- Node: `npm install -g promptkitx` (or use `npx` per above)

## Commands (Python & Node CLIs)

- `promptkit list [-p PATH]` — show available built-in packs and installed packs in PATH (default `.`)
- `promptkit install <pack> [-p PATH] [--force]` — install/update a pack (built-in: `execplan`)

## Pack spec (v1)

Each pack lives under `src/promptkit_builtin_packs/<name>/` and contains:

- `pack.json` — metadata
  - `name`, `version`, `description`
  - `agents_entry`: relative path to the snippet inserted into `AGENTS.md`
  - `files`: array of `{ "source": "files/PLANS.md", "target": ".agent/PLANS.md" }`
- `agents_snippet.md` — the text dropped into `AGENTS.md`
- `files/` — tree of files copied to repo root respecting `target` paths

Install metadata is recorded in `.agent/promptkit/registry.json` (per repo). `AGENTS.md` is updated inside a managed block `<!-- promptkit:start --> ... <!-- promptkit:end -->`, so multiple packs stay tidy.

## Built-in pack: execplan

- Adds the ExecPlans rule to `AGENTS.md`.
- Writes `.agent/PLANS.md` containing the full Codex ExecPlan spec (living-plan guidance, milestones, validation, etc.).

## Road to PyPI & npm

This repo is structured to publish both:

- PyPI: package name `promptkit` exposes the Python CLI (`promptkit`). Works with `uvx promptkit ...` once published.
- npm: package `promptkit` exposes the Node CLI (`promptkit`). Works with `npx promptkit ...`.

## Development notes

- Python package data lives in `src/promptkit_builtin_packs/` and is included via `MANIFEST.in`.
- Node CLI reads the same pack data from `src/promptkit_builtin_packs/` to stay in sync.
- Quality tools:
  - Make (recommended): `make lint`, `make format`, `make typecheck`, or `make all` (runs lint+typecheck). Requires `uvx` available and `npm install` for JS dev deps.
  - Python direct: `uvx ruff check .`, `uvx black .`, `uvx mypy src` (deps in `optional-dependencies.dev`).
  - Node direct: `npm run lint`, `npm run format`, `npm run typecheck`.
