# 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`
- `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 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

## Testing

- Framework: `pytest` (see `pyproject.toml`)
- Test files: `tests/test_*.py`
- Use `mock` provider or `--dry-run` to avoid network calls
- 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)