notarius/docs/development.md

Development

This is the first-read landing page for people and LLM coding agents working on Notarius. It provides a concise repository orientation and routes each kind of change to its canonical documentation.

Notarius is a Go CLI for configured structured extraction workflows. The README provides product context; Architecture describes system boundaries, and Internal Overview maps implemented components. Read the documents applicable to your task.

Read Agent Policy before recommending, planning, or implementing changes. It owns implementation discipline and local commit rules.

Policy Reading Guide

Policy	Read before…
Policy set provenance	Adopting policies, checking upstream revisions, or updating the adopted policy set.
Agents	Recommending, planning, or implementing repository changes.
Architecture	Planning or changing application code or its structure.
Testing	Selecting validation for code changes, or adding, changing, removing, or evaluating tests.
Documentation	Writing, revising, or reorganizing documentation.
OSS	Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution.
Release	Preparing or publishing a release, changing release procedures, or making versioning and compatibility decisions.

• Read applicable policies before making decisions they govern; multiple policies may apply.
• Select policies using the task triggers above. Follow cross-references to relevant sections when needed to resolve a concrete question.
• Reuse policies already available in context; reread when changed or no longer available.
• Expand reading when the task's scope expands.
• When revising a policy itself, read that policy and any provisions elsewhere affected by the revision.

What To Read

When working on	Read	Why
Finding the package or component that owns current behavior	Internal Overview	It is the implemented component inventory and routes to focused internals.
CLI composition or command behavior	CLI Internals and CLI Reference	The internal guide owns composition and command flow; the reference owns public syntax.
Building a subprocess caller or changing its result protocol	Subprocess Consumer Guide, Complete D&D Consumer Guide, Run Result Receipt, and CLI Internals	These separate generic caller workflow, the complete D&D workflow, the durable receipt contract, and CLI implementation behavior.
Configuration loading, resolution, or user-visible configuration behavior	Configuration Internals and Configuration	The internal guide owns loading and resolution mechanics; the reference owns the configuration contract.
Pipeline resolution or execution	Pipeline Internals	It documents profiles, references, validation, retries, checkpoints, and runner behavior.
Production modules or validators	Module Internals, D&D Module Internals, and D&D integration contracts	The generic guide owns extension mechanics, the D&D guide owns shared family conventions, and the contracts own durable output shapes.
LLM clients, prompts, schemas, profiles, or scheduling	LLM Runtime	It documents the transport boundary and PromptKit integration.
Output, cache, resume, or debug artifacts	Run State Internals, Operations, and Configuration	These separate implementation details, operator behavior, and configuration contracts.
External input formats, artifact schemas, or durable output files	Integration Contracts	Integration documents define external and durable data contracts.
Repository-specific release commands or diagnostics	Source Releases	The runbook supplies publication commands and recovery procedures.
Proposed or unimplemented behavior	Roadmap	Future work belongs only in roadmap documentation until implemented.

For an existing subsystem, also inspect its focused tests and the package-local types and contracts before changing behavior.

Validation

Use focused package tests while iterating. Run the repository-wide checks when a change affects shared contracts, application behavior, or maintained documentation examples:

go test ./...
go vet ./...
go build ./cmd/notarius