Contributing

Contributing

Dev setup and conventions for extending the agent. Deep: CONTRIBUTING.md.

Setup

cp .env.example .env
make install
make lint                 # ruff + tsc
zyvor-qa test             # smoke
zyvor-qa run --source local

Layout (mental model)

Tree	Role
orchestrator/graph.py	Node wiring + routing
orchestrator/nodes/	Thin PipelineState → PipelineState wrappers
agents/*	Real logic per capability
agents/common/	Pydantic models + LLM factory
tests/manual/	Hand-owned — never overwritten by generate
tests/generated/	Disposable
prompts/	LLM system prompts
templates/	Jinja fallback test + HTML report

See Project Structure · Architecture.

Conventions (short)

• Python: Ruff, py310+, from __future__ import annotations; feature flags read at call time from env
• LLM-with-fallback: every LLM stage must degrade without a key (except zyvor-qa create)
• Quality gate: generated TS must pass agents/generator/quality.py before write
• Don’t pass ad-hoc dicts through PipelineState — use Pydantic models in agents/common/models.py

Adding a pipeline stage

1. Implement logic under agents/<capability>/
2. Add orchestrator/nodes/<name>.py wrapper
3. Wire in graph.py (+ routing if needed)
4. Document flag in docs/configuration.md / .env.example
5. Prefer a tutorial or wiki note for operators

PRs

• Include tests or a smoke path when possible
• No secrets in commits
• Match existing style; run make lint

Related: Tutorials Index · Releases