PromptOps

Less context overhead. More disciplined coding-agent work.

An installable Claude Code + Codex skill and local CLI for task-focused code context, project memory, TDD, bounded subagents, and release-ready engineering.

imagePython 3.10+ imageNo runtime dependencies imageAlpha

Install · Try it · How it differs · Contribute

The coding-agent workflow, in one install

PromptOps is built for code changes that cross files and require more than a prompt dump. Its skill teaches Claude Code and Codex to prepare focused context, use compact repository memory, follow red/green/refactor, assign independent bounded work to subagents, and design CI/CD with explicit security and rollback gates. The local CLI makes file selection and budget decisions reviewable before code enters a prompt.

• Task-ranked context: rank candidate files from a task description, then include statically discovered local dependencies.
• A live budget bar: the keyboard picker animates a thin bar as files are selected, showing estimated bundle size against your ceiling.
• Project memory: keep a short, human-owned .promptops/MEMORY.md with verified architecture and repo rules. Load it only when useful.
• Engineering discipline: the skill gives agents a practical TDD loop, task boundaries for independent workers, integration ownership, and CI/CD release criteria.
• Local-first: no provider APIs, uploads, accounts, or runtime packages. The CLI reads local files and writes the bundle where you direct it.

Why PromptOps

Context packers and repository maps already solve important parts of this problem. Repomix packages a codebase into AI-friendly output and reports token counts; Aider's repository map ranks structural code context to fit a token budget. PromptOps does not claim to replace their semantic or syntax-aware retrieval. It joins context preparation to the operating rules that govern what an agent does next.

The difference is the combination: context selection + durable repo rules + evidence-based implementation workflow in one portable skill. It is useful when the hard part is keeping a complex change coherent across agents and CI, not only compressing files. Inspired by the focused, modular skill packaging and shared guidance in marketing-skill.

Install as a skill

Claude Code plugin marketplace

After publishing this repository, replace OWNER/REPO with its GitHub path:

claude plugin marketplace add OWNER/REPO
claude plugin install promptops@promptops

Start a new Claude Code session, then ask: “Use PromptOps to prepare a focused plan for the authentication refactor, with tests first.” The bundled skill includes its own standard-library context engine.

Codex skill

Install the skill into a project or your user-level Codex skills directory with the community skills installer:

npx skills add OWNER/REPO --skill promptops --agent codex

For user-wide installation, add --global. The installer supports selecting individual skills and agents. See its command options.

Install into Claude Code and Codex together

npx skills add OWNER/REPO --skill promptops --agent claude-code --agent codex

Claude Code users can also use the skills installer with --agent claude-code; the native Claude plugin marketplace option above installs the packaged Claude plugin. Codex skills use the portable SKILL.md convention and bundled helper files supported by Codex. OpenAI's skills documentation describes the format.

Quick start

Requirements: Python 3.10+. No runtime dependencies.

# Interactive file tree and animated context meter
python3 src/context_engine.py

# Rank likely files for a task, include repository memory and dependencies
python3 src/context_engine.py \
  --task "refactor authentication and add regression tests" \
  --top-files 8 \
  --memory .promptops/MEMORY.md \
  --graph \
  --max-tokens 12000 \
  --output /tmp/auth-context.xml

The task scorer uses lexical overlap with file paths and a bounded read of file contents. Review the candidates: it is intentionally transparent and deterministic, not semantic retrieval. Dependencies are included by default. Use --select PATH... when you know the exact files, or --no-dependencies for strict selection.

Initialize a sample memory file once, then edit it yourself:

python3 src/context_engine.py --init-memory

It creates .promptops/MEMORY.md and refuses to overwrite an existing file. Keep memory factual, short, and free of secrets. The optional --memory PATH flag adds it to the output in a separate <project_memory> block.

The agent workflow

flowchart TD
    A[Task and repo rules] --> B[Rank focused context]
    B --> C[Review dependency graph and memory]
    C --> D[Set scope, acceptance checks, and budget]
    D --> E{Independent work?}
    E -->|Yes| F[Assign bounded subagent tasks]
    E -->|No| G[Work serially]
    F --> H[Red: prove tests fail]
    G --> H
    H --> I[Green: smallest passing change]
    I --> J[Refactor and verify full checks]
    J --> K[CI gates, staged release, rollback]

The skill is a workflow guide, not an agent orchestrator: it does not spawn subagents by itself or claim control over provider reasoning modes. It instructs the active agent to delegate only independent work, provide each worker allowed paths and acceptance criteria, and retain integration and completion responsibility at the root.

Honest efficiency metrics

The bar is a live, local estimate based on selected file bytes and optional memory, divided by four characters per estimated token. It compares that estimate to the configured limit. The final summary also compares the emitted bundle size with discovered source bytes. Neither number is tokenizer-exact, provider billing data, or a benchmark of model quality. It excludes the surrounding conversation and tool traffic. The skill asks agents to report verified test and CI results, rather than claiming savings or checks they cannot measure.

What is included

The graph recognizes Python imports, JavaScript/TypeScript imports, and common markup/CSS references. It skips common dependency/build folders, symlinks, likely credential files, binary content, and oversized files. It does not resolve dynamic imports or custom build systems.

Development

make validate
make test
make install-hook

The CLI is standard-library-only. See docs/DEPLOYMENT.md for native builds and tagged releases. For architecture, safety, test, and pull request conventions, read AGENTS.md.

Contributing

Focused bug reports, reviews, and contributions are welcome. Explain the user-visible behavior, add or update tests, and report the checks you ran. If PromptOps makes complex coding sessions more deliberate, star the repository and tell us what you want it to handle next.