# Repository Guidelines

> Runtime code lives under src/promptheus/. main.py owns the CLI entry point, providers.py wraps the adapters for multiple LLM providers (Gemini, Claude, OpenAI, Groq, Qwen, GLM), config.py manages environment-driven…

- Skill: `tools-only/repository-guidelines-5` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/repository-guidelines-5`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/repository-guidelines-5/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/repository-guidelines-5

---

# Repository Guidelines

## Project Structure & Module Organization
Runtime code lives under `src/promptheus/`. `main.py` owns the CLI entry point, `providers.py` wraps the adapters for multiple LLM providers (Gemini, Claude, OpenAI, Groq, Qwen, GLM), `config.py` manages environment-driven settings, and `history.py` persists prompt sessions. Shared assets (e.g., `models.json`, `logging_config.py`, `utils.py`) sit alongside. Tests mirror this layout in `tests/`, while helper tools such as `sample_prompts.txt` remain at the repository root. Add new runtime modules inside `src/promptheus/` and keep provider-specific helpers beside existing integrations to simplify discovery.

## Build, Test, and Development Commands
Install dependencies in editable mode before contributing:
```bash
pip install -e .[dev]
pip install -r requirements.txt  # extras for env_validator
```
Run the CLI locally with either binary or module syntax:
```bash
promptheus "Draft an onboarding email"
python -m promptheus.main --skip-questions "Smoke test"

# Quiet mode for scripting (clean stdout/stderr separation)
promptheus "Generate a report" > output.txt  # Auto-quiet when piping
promptheus "Write code" | cat  # Auto-quiet when piping

# Different output formats
promptheus -o json "Create function" | jq .
promptheus -o plain "Write haiku"
```
Validate credentials before hitting remote APIs:
```bash
promptheus validate --providers google
promptheus validate --test-connection  # to test actual API connectivity
```

## Coding Style & Naming Conventions
Target Python 3.8+ with four-space indentation, `snake_case` for functions/variables, and `CapWords` for classes. Mirror existing type hints (see `main.py`) and keep modules under ~300 lines by extracting helpers where needed. Format with `black .`, keep imports sorted, and align terminal output with the `rich` styles already used in the CLI panels/table helpers.

## Testing Guidelines
Tests live in `tests/` and follow the `test_<module>.py` naming pattern. Prefer fast, offline unit tests that stub provider calls rather than exercising live APIs. Run `pytest -q` before sending a PR, and supplement with a manual CLI smoke test (`promptheus --skip-questions "Smoke test"`) when you touch interactive flows or history features.

## Commit & Pull Request Guidelines
Use concise, imperative commit messages (e.g., `Add OpenAI provider guard`, `Tighten question validation`). PRs should summarize behavioral changes, reference related issues, list tests run, and include CLI transcripts or screenshots whenever user-facing output changes. Keep changes focused—split feature work and refactors into separate PRs for easier review.

## Security & Configuration Tips
Store provider secrets in `.env` (bootstrap from `.env.example`) and never log raw tokens. Run `promptheus validate` after updating credentials to ensure required keys are present. Honor the default timeout settings in `constants.py`, and mask sensitive values when printing exceptions (use `sanitize_error_message` to stay consistent).

## Supported Providers
Promptheus supports 6 major LLM providers:
- **Google** (formerly Gemini) - using `GOOGLE_API_KEY`
- **Claude** (Anthropic) - using `ANTHROPIC_API_KEY`
- **OpenAI** - using `OPENAI_API_KEY`
- **Groq** - using `GROQ_API_KEY`
- **Qwen** (Alibaba/DashScope) - using `DASHSCOPE_API_KEY`
- **GLM** (Zhipu) - using `ZHIPUAI_API_KEY`

Model information is dynamically fetched from the models.dev API and cached locally for 24 hours. Cache location: `~/.promptheus/models_cache.json`

Each provider has its own configuration in `models.json` and respective adapter in `providers.py`.

## History Management
The system automatically tracks all prompt refinements in a local history file. Users can access:
- CLI command: `promptheus history`
- Interactive commands: `/history`, `/load <n>`, `/clear-history`
- History includes timestamps, task types, and both original and refined prompts.

## Quiet Mode & Piping
Promptheus supports clean stdout/stderr separation for scripting and piping:
- **Auto-quiet mode**: Automatically enabled when stdout is not a TTY (e.g., when piping)
- **Prompt processing unchanged**: Questions are still asked based on LLM's decision, regardless of output mode
- **Output formats**: `-o/--output-format` supports `plain` (default) and `json`
- **Behavior**: In quiet mode, all UI (status, warnings, spinners, questions) goes to stderr, only the refined prompt goes to stdout
- **Limitations**: Interactive tweaks and clipboard (`--copy`) are disabled in quiet mode

## MCP Server Integration

Promptheus includes a **Model Context Protocol (MCP) server** for integration with MCP-compatible clients and AI toolchains.

### Starting the MCP Server
```bash
# Start MCP server
promptheus mcp

# Or direct Python execution
python -m promptheus.mcp_server
```

### Available MCP Tools
- **refine_prompt**: Intelligent prompt refinement with Q&A workflow
- **tweak_prompt**: Surgical prompt modifications  
- **list_models**: Provider model discovery
- **list_providers**: Configuration status checking
- **validate_environment**: Environment validation with connectivity testing

### MCP Integration Workflow
1. **Initial Request**: Call `refine_prompt` with basic prompt
2. **Clarification Handling**: Process `clarification_needed` responses with AskUserQuestion
3. **Final Refinement**: Submit answers for optimized prompt generation
4. **Tool Integration**: Use refined prompts with client's native LLM capabilities

### MCP Development Guidelines
- Tools return consistent response formats (success/clarification/error)
- Support both interactive and structured AskUserQuestion modes
- Maintain comprehensive error handling with sanitized messages
- Document all tools with JSON examples and usage patterns

For detailed MCP documentation, see the [MCP Server section in README.md](README.md#mcp-server).