Repository navigation
Contributing
Contributions are welcome. This page explains how to set up a development environment, the code style requirements, how to run tests and lints, and the PR process.
Follow the same steps as Setup and Installation. You need:
- Python 3.12+
- uv (
pip install uvor see uv docs) - Bun (
curl -fsSL https://bun.sh/install | bash) - An Anthropic API key (set in
backend/.env)
git clone https://github.com/rupakc/storming-bastille.git
cd storming-bastille
cp backend/.env.example backend/.env
# Edit backend/.env and set ANTHROPIC_API_KEY
./start.shThis starts the backend on http://localhost:8000 and the frontend on http://localhost:3000.
For backend-only work, run the two servers separately:
# Backend
cd backend
uv sync
uv run uvicorn app.main:app --reload --port 8000
# Frontend (separate terminal)
cd frontend
bun install
bun devThe project uses ruff for both linting and formatting.
cd backend
uv run ruff check app/ # lint
uv run ruff format app/ # formatruff check runs with the configuration in pyproject.toml. Fix all lint errors before opening a PR — the CI pipeline fails on any ruff warning.
Type hints are expected on all function signatures. The project uses Python 3.12 and makes use of modern union syntax (X | Y rather than Optional[X]).
The project uses ESLint with the Next.js recommended configuration.
cd frontend
bun lint # ESLint check
bun run build # TypeScript type-check + production buildA clean bun run build is required before a PR can merge. Type errors and ESLint errors both fail the build.
cd backend
uv run pytest tests/ -vTo run with a coverage report:
uv run pytest tests/ --cov=app --cov-report=term-missingThe project targets 91% line coverage. New agent code should include tests with mocked Anthropic responses — see the existing agent tests in backend/tests/ for the pattern.
cd frontend
bun test- Create
backend/app/agents/{name}.pyand inherit fromBaseAgent(backend/app/agents/base_agent.py). - Write a focused system prompt. Agents should do one thing well — avoid combining research, analysis, and output formatting in a single prompt.
- Implement the specialist method (e.g.,
analyze(),research()). Use_call_claude()for non-streaming calls and the streaming variant for token-by-token output. - Wire the agent into
orchestrator.pyat the appropriate pipeline phase. If the agent can run in parallel with an existing phase, useasyncio.gather. If it must run sequentially, add it after the phase it depends on. - Add tests in
backend/tests/agents/with a mocked Anthropic client.
The five existing agents are good reference implementations:
-
historian.py— streaming output with embedded structured JSON -
causal_analyst.py— non-streaming structured JSON output -
graph_builder.py— pure Python, no AI call -
source_verifier.py— fire-and-forget with tiered output -
followup.py— conversational agent with session context
Use Conventional Commits:
| Prefix | When to use |
|---|---|
feat: |
New feature |
fix: |
Bug fix |
docs: |
Documentation only |
refactor: |
Code change that neither fixes a bug nor adds a feature |
test: |
Adding or updating tests |
chore: |
Build process, dependency updates, CI changes |
Examples:
feat: add FollowUpAgent with session context summarization
fix: handle missing JSON block in historian output
docs: add Architecture wiki page
refactor: extract search deduplication into utility function
Keep the subject line under 72 characters. Use the body for context when the change is non-obvious.
-
Create a feature branch from
main:git checkout -b feat/your-feature-name
-
Make your changes. Run tests and lints locally before pushing:
cd backend && uv run ruff check app/ && uv run pytest tests/ -v cd frontend && bun lint && bun run build
-
Open a PR against
main. The PR description should explain what the change does and why, not just what files were edited. -
All CI checks must pass before the PR can be merged:
-
ruff check— no lint errors -
pytest— all tests pass, coverage above threshold -
bun run build— TypeScript compiles, no ESLint errors - Bandit SAST scan — no high-severity findings
- pip-audit — no known CVEs in dependencies
- Trivy container scan — no critical vulnerabilities
-
-
Address review comments on the PR. Once approved and CI is green, the PR can be squash-merged into
main.
Do not push directly to main. All changes go through PRs.
Use GitHub Issues. For bugs, include:
- Steps to reproduce
- Expected behaviour
- Actual behaviour
- Backend logs if relevant (the backend logs to stdout;
./start.shoutput ordocker logsif containerised) - Browser console errors if the issue is on the frontend