Skip to content

AGENTS.md

Latest commit

 

History

History
38 lines (32 loc) · 2.79 KB

AGENTS.md

File metadata and controls

38 lines (32 loc) · 2.79 KB

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.