Update CLAUDE.md and AGENTS.md to reflect current codebase
- Add missing CLI subcommands (ui, docs, check, providers, deps, install, lock, verify, add, remove, init, config) - Document new core modules (config.py, system_deps.py, dependency_graph.py, hash_utils.py) - Update GUI structure (Welcome page, widgets/, expanded dialogs list) - Add missing web modules (auth.py, sessions.py, email.py, seo.py) - Add missing registry modules (categorize.py, rate_limit.py, scrutiny.py, similarity.py, stats.py, settings.py) - Streamline AGENTS.md as quick reference that defers to CLAUDE.md Co-Authored-By: Claude Opus 4.5 <[email protected]>
This commit is contained in:
Claude Opus 4.5
@@ -1,42 +1,52 @@
|
||||
# Repository Guidelines
|
||||
|
||||
## Project Structure & Module Organization
|
||||
- `src/cmdforge/` contains the core Python package (CLI entry point, tool model, runner, providers, UI backends).
|
||||
- `tests/` holds pytest suites.
|
||||
- `docs/` includes installation, provider setup, examples, and design notes.
|
||||
- `examples/` provides sample tools and an installer script.
|
||||
- `wiki/` contains additional reference material.
|
||||
> **Note**: See CLAUDE.md for comprehensive project documentation. This file provides a quick reference for common patterns.
|
||||
|
||||
## Architecture Overview
|
||||
- `cli/` directory routes subcommands like `list`, `create`, `run`, `test`, and `refresh`.
|
||||
- `tool.py` defines tool/step models and handles YAML config loading and wrapper generation.
|
||||
- `runner.py` executes steps and performs `{input}`/argument variable substitution.
|
||||
- `providers.py` shells out to configured AI provider CLIs (or the `mock` provider).
|
||||
- `gui/` provides the PySide6 desktop GUI with pages for tools, registry, and providers.
|
||||
## Project Structure
|
||||
|
||||
## Build, Test, and Development Commands
|
||||
- `pip install -e ".[dev]"` installs CmdForge in editable mode with dev dependencies.
|
||||
- `pytest` runs the full test suite.
|
||||
- `pytest tests/test.py::test_name` runs a focused test.
|
||||
- `python -m cmdforge.cli` runs the CLI module directly.
|
||||
- `cmdforge` launches the desktop GUI (requires PySide6).
|
||||
- `docker-compose build` builds the dev container image.
|
||||
- `docker-compose run --rm test` runs tests inside Docker.
|
||||
- `src/cmdforge/` - Core Python package (CLI, tool model, runner, providers, GUI)
|
||||
- `tests/` - Pytest test suites
|
||||
- `docs/` - Infrastructure and deployment documentation
|
||||
|
||||
## Coding Style & Naming Conventions
|
||||
- Python code uses 4-space indentation and module/variable names in `snake_case`.
|
||||
- Keep CLI command names and tool IDs lowercase with hyphens (e.g., `fix-grammar`, `json-extract`).
|
||||
- Prefer small, composable functions that mirror the Unix pipe flow described in `README.md`.
|
||||
## Development Commands
|
||||
|
||||
## Testing Guidelines
|
||||
- Framework: `pytest` (configured in `pyproject.toml`).
|
||||
- Place new tests under `tests/` and name files `test_*.py`.
|
||||
- For provider-dependent logic, prefer the built-in `mock` provider to avoid network calls.
|
||||
```bash
|
||||
pip install -e ".[dev]" # Install in dev mode
|
||||
pytest tests/ -m "not integration" # Run unit tests
|
||||
cmdforge # Launch GUI
|
||||
cf # Interactive tool picker
|
||||
```
|
||||
|
||||
## Commit & Pull Request Guidelines
|
||||
- Commit messages follow short, imperative, sentence-case subjects (e.g., "Improve provider error messages").
|
||||
- PRs should include a clear summary, test results (or rationale if tests are skipped), and screenshots when UI behavior changes.
|
||||
## Architecture Quick Reference
|
||||
|
||||
## Security & Configuration Tips
|
||||
- Provider credentials live in `~/.cmdforge/providers.yaml`; avoid committing secrets.
|
||||
- User tool configs live in `~/.cmdforge/<toolname>/config.yaml` and should not be added to the repo.
|
||||
- `cli/` - Routes all subcommands (list, create, run, test, providers, registry, collections, deps, install, etc.)
|
||||
- `tool.py` - Tool/step dataclasses, YAML loading, wrapper generation
|
||||
- `runner.py` - Step execution, variable substitution (`{input}`, `{varname}`)
|
||||
- `providers.py` - AI provider abstraction (calls CLI tools via subprocess)
|
||||
- `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)
|
||||
|
||||
Reference in New Issue
Block a user