Imported from gwozai/claude-code-practice (github-repos/SuperClaude_Framework/AGENTS.md). Install upstream with npx skills add gwozai/claude-code-practice --skill SuperClaude_Framework. Copyright stays with the author.

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.