agent-doc-system 0.0.0-stage → 1.0.0

package/templates/ADR.md

@@ -0,0 +1,26 @@
+# Architecture Decision Records
+
+One file per decision: `NNNN-short-title.md`. An ADR records a decision and its
+consequences, and is immutable once accepted — supersede it with a new ADR that
+links back.
+
+## Template
+
+    # NNNN. Short title in one imperative sentence
+
+    ## Status
+    proposed | accepted | superseded by NNNN
+
+    ## Context
+    What was true before this decision. Facts, with evidence.
+
+    ## Decision
+    What was decided, in one sentence.
+
+    ## Consequences
+    What becomes easier, what becomes harder, and what is now forbidden.
+
+    ## Evidence class of each claim
+    Which parts are authored intent, which are derived from code, and which
+    were observed in a running system. Disagreement between them is the point
+    of this section, not a flaw in it.

package/templates/ARCHITECTURE.md

@@ -0,0 +1,19 @@
+# Architecture
+
+This file explains *why the shape is what it is*. It does not enumerate
+components, contracts or data stores: `agentdoc query` returns those from the
+compiled graph, and a hand-maintained list would be wrong within a week.
+
+## How to read the system
+- `agentdoc query <path>` for one component and its boundaries.
+- `agentdoc impact <paths>` for what a change forces you to keep consistent.
+- `agentdoc audit` for the current classification of every fact.
+
+## Structural decisions
+<!-- One entry per decision, each linking to the ADR that records it. -->
+
+## Boundaries and why they exist
+<!-- Which components may talk to which, and what enforces it. -->
+
+## Deliberate non-relationships
+<!-- Things that look like they should be coupled and are not. -->

package/templates/CONSTRAINTS.md

@@ -0,0 +1,17 @@
+# Constraints
+
+Repository-wide rules that an agent must not violate. Anything that is *not*
+repository-wide belongs in the owning component's `CONSTRAINTS.md`, which the
+graph routes to automatically.
+
+## Rule format
+One rule, one imperative sentence, one reason. A rule that cannot be checked by
+reading code or running a command belongs in an ADR, not here.
+
+## Rules
+- <!-- rule -->
+  - Reason: <!-- why -->
+  - Checked by: <!-- command or test that proves it -->
+
+## Changing a rule
+A rule change is an ADR. Record why the old rule stopped being true.

package/templates/PRODUCT.md

@@ -0,0 +1,17 @@
+# Product
+
+## What this is
+<!-- One paragraph. The product in the words a user would use. -->
+
+## Who it is for
+<!-- The actors, and nothing else. -->
+
+## What it promises
+<!-- The behaviours a user can rely on. Each one must be observable somewhere. -->
+
+## What it explicitly does not do
+<!-- Non-goals. This section prevents more drift than any other. -->
+
+## Vocabulary
+<!-- Domain terms and their exact meaning. Point at the Domain entity rather
+     than restating it: the graph already carries the definition. -->

package/templates/api.yaml

@@ -0,0 +1,10 @@
+apiVersion: agentdoc.dev/v1
+kind: API
+metadata:
+  name: example-api
+  description: "Canonical JSON HTTP surface served by the example component."
+spec:
+  type: openapi
+  provider: component:default/example-service
+  contract:
+    ref: contracts/example.openapi.yaml

package/templates/ci.yml

@@ -0,0 +1,31 @@
+# Drift gate. The graph is a build artifact: compile it, then prove the
+# committed one is byte-identical to a fresh compile. A stale or hand-edited
+# graph fails here, not in someone's review three weeks later.
+name: agentdoc
+on:
+  pull_request:
+  push:
+    branches: [main]
+jobs:
+  agentdoc:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-node@v4
+        with: { node-version: '24' }
+      - name: Install the agentdoc CLI
+        # Unpinned tracks main. For CI reproducibility pin a tag or commit:
+        #   github:lbframe/agent-doc-system#v1.0.0
+        # A compiler upgrade intentionally invalidates committed graphs.
+        run: npm install -g github:lbframe/agent-doc-system
+      - name: Validate and compile
+        run: |
+          agentdoc validate
+          agentdoc compile
+          agentdoc check
+      - name: Reject dirty sources
+        run: agentdoc check --require-clean
+      - name: Routing evaluation
+        run: agentdoc eval routing

package/templates/component.yaml

@@ -0,0 +1,14 @@
+apiVersion: agentdoc.dev/v1
+kind: Component
+metadata:
+  name: example-service
+  description: "Serves the example read model for the example domain."
+spec:
+  type: service
+  # Choose exactly one of system, domain, or placementRationale.
+  system: example-system
+  context:
+    docs:
+      - services/example-service/README.md
+    constraints:
+      - services/example-service/CONSTRAINTS.md

package/templates/domain.yaml

@@ -0,0 +1,6 @@
+apiVersion: agentdoc.dev/v1
+kind: Domain
+metadata:
+  name: example-domain
+  description: "A bounded area of the product with its own vocabulary and rules."
+spec: {}

package/templates/journey.yaml

@@ -0,0 +1,7 @@
+schemaVersion: agentdoc.dev/journeys/v1
+journeys:
+  - id: example-end-to-end
+    description: "One sentence describing the user-visible outcome this journey produces."
+    components:
+      - component:default/example-service
+      - component:default/example-consumer

package/templates/observation.yaml

@@ -0,0 +1,19 @@
+apiVersion: agentdoc.dev/observation/v1
+kind: ObservationSet
+metadata:
+  name: production
+  description: "What the production platform reported for one observation window."
+  environment: production
+  capturedAt: "2026-01-01T00:00:00Z"
+  maxAgeDays: 30
+  sourceSystem: example-scheduler
+  collector: "example-cli schedules list --json"
+  evidenceBundle: agentdoc/observations/production/2026-01-01.json
+  provenance: "Collected during the scheduled change window; raw output committed verbatim."
+spec:
+  facts:
+    - id: nightly-digest
+      subject: component:default/example-service
+      key: schedule.cron
+      value: "0 3 * * *"
+      semantics: "The expression the production scheduler actually evaluates for this trigger."

package/templates/resource.yaml

@@ -0,0 +1,8 @@
+apiVersion: agentdoc.dev/v1
+kind: Resource
+metadata:
+  name: example-service-postgres
+  description: "Logical database owned by the example service."
+spec:
+  type: logical-database
+  system: example-system

package/templates/system.yaml

@@ -0,0 +1,10 @@
+apiVersion: agentdoc.dev/v1
+kind: System
+metadata:
+  name: example-system
+  description: "Owns one responsibility inside the example domain."
+spec:
+  domain: example-domain
+  context:
+    docs:
+      - docs/systems/example-system.md

package/templates/warning-acceptance.yaml

@@ -0,0 +1,14 @@
+# Warning acceptances live in agentdoc/agentdoc.config.yaml. Each one must carry
+# the evidence content hashes as they are *now*; `agentdoc validate` recomputes
+# them and fails when the evidence has moved, forcing a fresh review.
+warningAcceptances:
+  - code: AGENTDOC_SERVICE_BINDING_UNRESOLVED
+    subject: component:default/example-service
+    classification: INTENDED_DIVERGENCE
+    reason: "This divergence is intentional and will be reconciled in Q3."
+    reviewWhen: "Review when the platform migration lands or the divergence persists past its stated window."
+    observedRefs:
+      - component:default/example-service
+    evidence:
+      - path: services/example-service/wrangler.toml
+        sha256: "0000000000000000000000000000000000000000000000000000000000000000"