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).

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.

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).

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.

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.

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.