# Repository Guidelines

## Project Structure & Module Organization
- Core library and CLI live in `src/discussions` (CLI entrypoint `cli.py`, models/orchestration in `discussion.py` and `runner.py`, parsing/voting utilities in `markers.py` and `voting.py`, participant registry in `participant.py`).
- Tests sit in `tests/` with pytest; mirror module names when adding coverage (e.g., `test_voting.py`).
- User-facing docs are under `docs/` (design + implementation notes), with runnable discussion examples in `examples/` and SmartTool configs in `smarttools/`.
- Discussion templates for new files live in `templates/` (`feature.yaml`, `brainstorm.yaml`).

## Build, Test, and Development Commands
- Install in editable mode with dev extras: `python -m pip install -e .[dev]`.
- Run the CLI locally: `discussions --help`, `discussions new "My Feature" --template feature`, `discussions turn examples/feature_discussion.md`.
- Execute the manual orchestration walkthrough: `bash scripts/run-turn.sh examples/feature_discussion.md` (shows each SmartTool step).
- Run tests: `pytest` or `pytest --maxfail=1 -q` for quick feedback.

## Coding Style & Naming Conventions
- Follow PEP 8 with 4-space indentation and type hints for public functions; prefer concise module-level docstrings like the existing files.
- Keep modules thin: orchestration in Python, heavy lifting in SmartTools via stdin/stdout (see `docs/DESIGN.md` for the Unix-style adapter pattern).
- Use snake_case for modules/functions, CapWords for classes, and uppercase for constants. Avoid adding new global state; prefer pure functions or dataclasses.
- New CLI flags should use argparse patterns already present in `cli.py`; align option names with existing verbs (`new`, `turn`, `status`, `comment`, `participants`).

## Testing Guidelines
- Add pytest coverage alongside new code; name tests after the module (`test_<module>.py`) and include scenario-focused test names (`test_consensus_requires_human`).
- When touching parsing or voting logic, assert both positive and negative cases (see `tests/test_markers.py` and `tests/test_voting.py`).
- If a feature depends on SmartTools output, stub with deterministic JSON fixtures instead of live calls.

## Commit & Pull Request Guidelines
- Use short, imperative commit subjects (e.g., `Add CHANGES threshold guard`); keep body lines wrapped and include rationale when non-obvious.
- PRs should link related issues, describe behavior changes, and show before/after snippets for CLI flows or discussion markdown changes.
- Always note test coverage (`pytest` command) and any SmartTools/config prerequisites for reviewers.

## Security & Configuration Tips
- Do not commit API keys or SmartTools cache; local participant configs live in `~/.smarttools/`.
- Favor configuration via environment variables or `.env` ignored files; validate inputs before invoking external tools to avoid malformed prompts.