CmdForge/AGENTS.md

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

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
• 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
• 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)