rob
/
CmdForge
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
CmdForge/AGENTS.md

3.6 KiB
Raw Blame History

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