mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-17 17:56:46 +00:00
39 lines
2.8 KiB
Markdown
39 lines
2.8 KiB
Markdown
|
# Repository Guidelines
|
||
|
|
|
||
|
|
## Project Structure & Module Organization
|
||
|
|
- `src/superclaude/` holds the Python package and pytest plugin entrypoints.
|
||
|
|
- `tests/` contains Python integration/unit suites; markers map to features in `pyproject.toml`.
|
||
|
|
- `pm/`, `research/`, and `index/` house TypeScript agents with standalone `package.json`.
|
||
|
|
- `skills/` holds runtime skills (e.g., `confidence-check`); `commands/` documents scripted Claude commands.
|
||
|
|
- `docs/` provides reference packs; start with `docs/developer-guide` for workflow expectations.
|
||
|
|
|
||
|
|
## Build, Test, and Development Commands
|
||
|
|
- `make install` installs the framework editable via `uv pip install -e ".[dev]"`.
|
||
|
|
- `make test` runs `uv run pytest` across `tests/`.
|
||
|
|
- `make doctor` or `make verify` check CLI wiring and plugin health.
|
||
|
|
- `make lint` and `make format` delegate to Ruff; run after significant edits.
|
||
|
|
- TypeScript agents: inside `pm/`, run `npm install` once, then `npm test` or `npm run build`; repeat for `research/` and `index/`.
|
||
|
|
|
||
|
|
## Coding Style & Naming Conventions
|
||
|
|
- Python: 4-space indentation, Black line length 88, Ruff `E,F,I,N,W`; prefer snake_case for modules/functions and PascalCase for classes.
|
||
|
|
- Keep pytest markers explicit (`@pytest.mark.unit`, etc.) and match file names `test_*.py`.
|
||
|
|
- TypeScript: rely on project `tsconfig.json`; keep filenames kebab-case and exported classes PascalCase; align with existing PM agent modules.
|
||
|
|
- Reserve docstrings or inline comments for non-obvious orchestration; let clear naming do the heavy lifting.
|
||
|
|
|
||
|
|
## Testing Guidelines
|
||
|
|
- Default to `make test`; add `uv run pytest -m unit` to scope runs during development.
|
||
|
|
- When changes touch CLI or plugin startup, extend integration coverage in `tests/test_pytest_plugin.py`.
|
||
|
|
- Respect coverage focus on `src/superclaude` (`tool.coverage.run`); adjust configuration instead of skipping logic.
|
||
|
|
- For TypeScript agents, add Jest specs under `__tests__/*.test.ts` and keep coverage thresholds satisfied via `npm run test:coverage`.
|
||
|
|
|
||
|
|
## Commit & Pull Request Guidelines
|
||
|
|
- Follow Conventional Commits (`feat:`, `fix:`, `refactor:`) as seen in `git log`; keep present-tense summaries under ~72 chars.
|
||
|
|
- Group related file updates per commit to simplify bisects and release notes.
|
||
|
|
- Before opening a PR, run `make lint`, `make format`, and `make test`; include summaries of verification steps in the PR description.
|
||
|
|
- Reference linked issues (`Closes #123`) and, for agent workflow changes, add brief reproduction notes; screenshots only when docs change.
|
||
|
|
- Tag reviewers listed in `CODEOWNERS` when touching owned directories.
|
||
|
|
|
||
|
|
## Plugin Deployment Tips
|
||
|
|
- Use `make install-plugin` to mirror the development plugin into `~/.claude/plugins/pm-agent`; prefer `make reinstall-plugin` after local iterations.
|
||
|
|
- Validate plugin detection with `make test-plugin` before sharing artifact links or release notes.
|