69 lines
3.6 KiB
Markdown
69 lines
3.6 KiB
Markdown
# 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)
|