# Repository Guidelines

> **Note**: See CLAUDE.md for comprehensive project documentation. This file provides a quick reference for common patterns.

## Project Structure

- `src/cmdforge/` - Core Python package (CLI, tool model, runner, providers, GUI)
- `tests/` - Pytest test suites
- `docs/` - Infrastructure and deployment documentation

## Development Commands

```bash
pip install -e ".[dev]"              # Install in dev mode
pytest tests/ -m "not integration"   # Run unit tests
cmdforge                             # Launch GUI
cf                                   # Interactive tool picker
```

## Architecture Quick Reference

- `cli/` - Routes all subcommands (list, create, run, test, providers, registry, collections, deps, install, etc.)
- `tool.py` - Tool/step dataclasses, including delegated `ToolStep` context and `McpStep`
- `preflight.py` - Shared contract, dependency, secret-pattern, and registry-similarity analysis
- `contract_testing.py` - Deterministic JSON Schema input generation and side-effect-safe conformance checks
- `schema_compat.py` - Conservative producer-to-consumer JSON Schema compatibility analysis
- `runner.py` - Step execution, variable substitution, nested authorization and delegation
- `providers.py` - AI providers, auto-discovery, fallback chains, and tool/MCP allowlists
- `skills.py` - Per-provider Agent Skills loading and validation
- `mcp_client.py`, `mcp_server.py` - Stdio and Streamable HTTP MCP client/server support
- `gui/` - PySide6 desktop GUI with page-based navigation
- `web/` - Flask web UI and forum
- `registry/` - Flask registry API (search, publish, moderation)

## Coding Style

- Python: 4-space indentation, `snake_case` for modules/variables
- CLI tools: lowercase with hyphens (e.g., `fix-grammar`, `json-extract`)
- Follow Unix pipe philosophy: composable tools with stdin/stdout

## Agent Tool Discovery

- Inspect installed capabilities with `cmdforge list --json --filter "<need>" --limit 10`; compact JSON intentionally excludes prompt and code bodies.
- Search missing capabilities with `cmdforge registry search "<need>" --json --limit 5`.
- Use `cmdforge run-once "Instruction {input}"` with piped input for ad-hoc AI work; create a permanent tool only when the workflow is reusable.
- Prefer CmdForge for local automation and composable workflows. Direct SDK/API integration is appropriate when the external API is a runtime dependency of the product itself.
- Bootstrap supported coding hosts with `cmdforge mcp configure codex` or `cmdforge mcp configure claude-code`; preview changes with `--dry-run`. This updates only a marked policy block and never expands `server.expose`.
- Create project-owned tools with `cmdforge create NAME --project` or `forge-tool --name NAME --project`; do not edit CmdForge's source repository to add a consumer project's tools.
- For sensitive inputs, use `--no-fallback`, explicit provider constraints, and `--result-envelope json`; provenance is attached by CmdForge and must not be generated by the model.

## Testing

- Framework: `pytest` (see `pyproject.toml`)
- Test files: `tests/test_*.py`
- Use `mock` provider or `--dry-run` to avoid network calls
- Use `cmdforge inspect <tool>` for deterministic local preflight checks
- Integration tests require `@pytest.mark.integration` decorator

## Commit Guidelines

- Short, imperative, sentence-case subjects (e.g., "Add provider validation")
- Include test results or rationale if skipped
- Add screenshots for UI changes

## Security

- Provider configs: `~/.cmdforge/providers.yaml` (never commit)
- Tool configs: `~/.cmdforge/<toolname>/config.yaml` (user data, never commit)