Contributing

Contributing

CodingDude is developed with the same discipline it applies to your code: plan, test, gate, review, then ship. The repository's CONTRIBUTING.md is canonical; this page is the short version.

Setup

git clone https://github.com/cybersenses/codingdude.git
cd codingdude
uv sync

Python 3.12+, uv, git. Node is needed only for the frontend.

The gates

gates.bat

Runs three things, and all three must be clean:

uv run ruff check src tests tools
uv run mypy
uv run pytest -q

Frontend:

cd frontend && npm run lint && npm run test && npm run build

CI runs the same on windows-latest — pytest/lint/types, frontend (lint, vitest, build), and the scripted benchmark. Python tooling is venv-scoped: run through uv run, not a bare shell. Before declaring a tool "missing", check .venv/Scripts/ — "not recognised" does not mean absent.

The development process

spec → ticket → tests → implement → gates → review → commit/push → roadmap

1. Design first. Non-trivial work starts as a PRD and a tech design, then a roadmap item, then tickets. Each ticket is a tracer bullet: one demonstrable vertical slice with its blocking edges declared.
2. Tests at seams. The engine is tested with scripted FunctionModel runs against temporary workdirs. Mock only true system boundaries (third-party APIs, time); prefer the real store over a mocked one.
3. Behavior changes ship with tests at pre-agreed seams.
4. Gates before claims. Never say a change is complete without running the gate in that session and reading the output — cite the count and the exit code.
5. Review, then push. A push requires a recorded two-axis review of the exact diff (Review Gate). Fixing a finding voids the record, which is what forces the fix to be reviewed.
6. Track it. Close the ticket citing the commit that closed it; close the roadmap item when its tickets are closed, naming the evidence.

Code standards

The short list; the repository's own conventions file is authoritative.

• Read the target area first. Reuse existing helpers over new ones — one source of truth per behaviour — and name what you reused.
• Match the existing style. Same naming, same structure, same vocabulary (CONTEXT.md).
• Fail fast. Guard clauses, early returns, flat logic. Deep nesting and very long functions are a smell — split with intent.
• No silent catches. Every except handles, logs with context, or propagates. At tool boundaries return readable messages; in core logic, raise.
• Strict typing where the language supports it; validate external input at the boundary.
• No placeholders, no TODOs, no hardcoded secrets, no eval.
• Preserve line endings. This is a Windows-primary project with mixed history; a whole-file rewrite in a diff is usually a line-ending accident, not a change.
• Never cite your own branch SHA in tracked docs. It dangles after a squash-merge and breaks the next PR's CI.

Living documentation is tested

tools/claim_check.py runs as part of the suite over the strict documentation set. A stale file path, a line reference past the end of a file, an unknown commit hash or a wrong line count fails pytest rather than waiting for a reviewer to notice. If you change code that a document describes, the document is part of the change.

Changes to prompts and tools

• A new tool must honour workdir containment and go through the shared atomic-write helper.
• A new agent must take its caching from the capabilities seam (agent_caps.py) and its spend limits from limits.py; tests pin both, because a missing capability or limit is invisible at runtime.
• Tool policy for a delegation function is registry-locked in code — that lock is the safety property, so it is not a config knob.

Licensing and contributions

CodingDude is AGPL-3.0-or-later. Contributions are accepted under the CLA in CLA.md.

Third-party code and adapted skill libraries are recorded in NOTICE.md — add an entry when you bring work in.

Where to talk

• Discord — https://discord.gg/UA73mmfb for setup questions and design discussion.
• GitHub issues — reproducible bugs and feature requests.
• Security — never publicly; see SECURITY.md.