Files
notarius/docs/development.md

5.4 KiB

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, Native Completion Report, and CLI Internals These separate generic caller workflow, the complete D&D workflow, the native completion report, 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 typed preparation, complete assessment, native continuation, workers, and handoff eligibility.
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.
Native execution, prompts, schemas, profiles, or admission LLM Integration It locates shared engine construction, native request/continuation calls, and evidence hooks.
Kit API, source handoff, or standard-suite integration ConfigKit, PromptKit, and CommandKit These define the selected upstream integration boundaries and link pinned native contracts.
Output, accepted-result reuse, 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.
Implementation status or future scope Implementation plan, native migration target, and separate backlog The plan records verified work and remaining acceptance; the target owns cutover requirements and the backlog keeps other work separate. Implemented behavior belongs in canonical documentation.

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