Contributing to Archon Horizon¶
Read AGENTS.md and architecture. The runtime
is src/archon_horizon/pipeline; all CLI entrypoints invoke that implementation.
AGENTS.md governs agents developing Horizon's source. CLAUDE.md imports it
so both development harnesses share one maintained instruction source. These
files do not configure dispatched formalization runs: those use the API's pinned
skills, prompts and descriptors. Keep development rules out of project missions.
Setup And Checks¶
Use Python 3.11 or newer and Node.js 20:
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
npm --prefix src/archon_horizon/frontend ci
mkdir -p "$HOME/.horizon/development-tmp"
export TMPDIR="$HOME/.horizon/development-tmp"
python -B -m pytest -q
python scripts/version.py --check
npm --prefix src/archon_horizon/frontend run typecheck
npm --prefix src/archon_horizon/frontend test
npm --prefix src/archon_horizon/frontend run build
npm --prefix src/archon_horizon/frontend run test:pipeline
Run checks in the foreground and wait for completion. Install the browser once
with npx playwright install chromium in the frontend directory. Browser fixtures
use isolated data; inspect a fixture before pointing it at a real service.
Set HORIZON_PIPELINE_TEST_URL to a disposable PostgreSQL database for database
and HTTP tests. They create/drop random schemas. Never use the operator database.
CI provides PostgreSQL 17. Backup tests additionally require
HORIZON_PIPELINE_BACKUP_TEST_CONTAINER naming a disposable container labelled
archon-horizon.scope=pipeline-development.
Layout¶
| Path | Responsibility |
|---|---|
src/archon_horizon/pipeline/cli.py |
Operator and dispatched-agent commands |
src/archon_horizon/pipeline/ |
Stable entrypoints, configuration, authentication, shared request contracts |
src/archon_horizon/pipeline/review/ |
Review contracts, packets, invocations, identities and decisions |
src/archon_horizon/pipeline/integrations/ |
Forgejo/Zulip transport, browser identities and delivery reconciliation |
src/archon_horizon/pipeline/missions/ |
Mission trees, conditions and transactional domain services |
src/archon_horizon/pipeline/execution/ |
Scheduling, admission, execution events and coordination recovery |
src/archon_horizon/pipeline/dashboard/ |
Scoped read models and activity presentation |
src/archon_horizon/pipeline/instructions/ |
Catalog discovery, prompt construction and pinned bundles |
src/archon_horizon/pipeline/persistence/ |
PostgreSQL schema, connections, record primitives and blob storage |
src/archon_horizon/pipeline/projects/ |
Project setup, source documents, milestones, references and search |
src/archon_horizon/pipeline/operations/ |
Installation diagnostics, health, storage and supervision |
src/archon_horizon/pipeline/providers/ |
Native event parsing, observations and usage accounting |
src/archon_horizon/pipeline/worker/ |
Provider execution, local journals, publication, sandbox and builds |
src/archon_horizon/pipeline/skills/ |
Bundled skills grouped into operations, Lean, and review procedures |
src/archon_horizon/pipeline/subagents/ |
Implementation, research, validation, planning and reviewer descriptors |
src/archon_horizon/pipeline/migrations/ |
Required Alembic schema history for current databases |
src/archon_horizon/search/ |
Lean index and standalone workspace search MCP |
src/archon_horizon/frontend/ |
Current React dashboard and tests |
deploy/pipeline/ |
Service and explicit configuration examples |
scripts/ |
Version and distribution validation |
Preserve operator data and unrelated working changes. Keep credentials, provider homes, journals, databases, caches, and release artifacts outside source control.
Code Documentation¶
Write docstrings for modules and public interfaces where readers need to know their purpose, contracts, side effects, or limitations. Add nearby comments for choices that the implementation alone does not explain:
- For constants, state their units, scope, and meaning. Distinguish compatibility revisions from tuning defaults and hard limits; explain when a revision must change. Label heuristics as such instead of implying measured optimal values.
- Explain security boundaries and failure behavior, such as why a credential is scoped, a path is rejected, or a cache miss is recoverable.
- Record ordering, locking, transaction, and retry invariants where changing them could break correctness. Link to the authoritative policy or helper when useful.
- Describe current behavior and known limitations. Avoid invented historical reasons, unsupported security guarantees, and comments that restate each line.
Keep comments and docstrings current when changing the behavior they describe. JSON examples must remain valid JSON; explain their choices in the configuration models or setup guide rather than inserting comments or unsupported fields.
Changes¶
Use typed request contracts and revision-checked domain services. Keep queue
claims and state changes transactional. Retries must reconcile the same intent;
an uncertain network outcome is not proof an operation failed. API startup checks
the database revision; apply schema changes only through the explicit migrate
command. Never rewrite applied migration history.
Workers must remain usable with [pipeline-worker] alone. Do not import server
or search dependencies in worker startup. Use structured provider streams and
retain unknown usage as unknown. Keep browser reads cancellable, bounded and
cached, and preserve drafts on refresh or revision conflicts.
Group implementation modules by responsibility; the number of files is a
readability signal, not a package size limit. Keep package __init__.py files
free of eager service imports. Import concrete modules rather than re-exporting
an entire subsystem. Resolve packaged assets through pipeline._resources
instead of assuming they are beside the consuming module. The documented
CLI/API entrypoints and applied migration history remain stable when internals
are reorganized. Check source imports, worker dependency isolation and built
distribution contents after moving modules.
Skills use metadata.category (operations, lean, review, or custom).
Bundles expose grouped SKILLS.md and SUBAGENTS.md indexes; agents read
relevant bodies on demand. Specialist descriptors include skill references and
live under their category in pipeline/subagents/; their names do not create
execution roles, functions or provider-native agent types.
skill_source_root supplies operator additions. Reviewer source descriptions
live under pipeline/subagents/reviewers/; the same loader
feeds presets and prompts. Existing project descriptors are revisioned records,
edited in the dashboard or API. Source edits do not overwrite them or an existing
session's pinned bundle. See reviewer workflow.
Build the frontend before producing wheels/source archives, then run
scripts/check_wheel.py and scripts/check_sdist.py. Use a clean build directory
so removed source files cannot survive as stale package artifacts.
Documentation And Review Tools¶
The documentation site guide covers the MkDocs
build, Pages workflow, generated dashboard demo and local preview. Keep synthetic
demo records separate from installation data. build:demo produces a standalone
artifact without changing the dashboard included in wheels.
Use scripts/review_inventory.py to enumerate Python files and scoped functions,
their documentation, branch/nesting counts and optional line-coverage or explicit
review evidence. Use the inventory to choose and record review work; metrics do
not establish correctness or justify refactors by themselves.