145 lines
6.9 KiB
Markdown
145 lines
6.9 KiB
Markdown
> **WARNING:** This document describes only the change applied in this PR.
|
|
> It may already be outdated once the next PR is merged.
|
|
> Historic PR-documentation is not maintained along with new PRs — treat it as a snapshot, not as current documentation.
|
|
|
|
## The Problem
|
|
|
|
Werkator is a complex build system with multiple components, configuration layers, build runtimes, and APIs.
|
|
AI coding agents working on the Werkator codebase need to understand its architecture, configuration, features, and interfaces to make informed changes and avoid breaking invariants.
|
|
|
|
Without dedicated documentation for agents, they must piece together understanding from scattered sources:
|
|
- The technical deep-dive in `AGENTS.md`
|
|
- User-facing guides like `configuration.md` and `bootstrapping.md`
|
|
- The ADR collection in `docs/adrs/`
|
|
- Source code inspection
|
|
|
|
This is inefficient and error-prone.
|
|
An agent might miss critical constraints like the branch-layer pinning rule, the hard invariants about worktree layout, or the multi-layer configuration merging strategy.
|
|
|
|
## Non-Goals
|
|
|
|
- Not a replacement for `configuration.md` — this is agent-focused, that is user-focused.
|
|
- Not a replacement for `AGENTS.md` — this covers what the system *does* and *exposes*, that covers how to *work* on it.
|
|
- Not a user guide or tutorial — agents do not need onboarding.
|
|
- No behavioral changes to Werkator itself.
|
|
|
|
## The Scenarios
|
|
|
|
### Feature: an agent can understand Werkator's architecture from one document
|
|
|
|
#### Scenario#36.01: An agent understands the system at a glance
|
|
|
|
So that it can navigate the codebase and predict where changes belong.
|
|
|
|
- **Given** an agent new to the Werkator codebase
|
|
- **When** it reads `docs/llms.md`
|
|
- **Then** it understands:
|
|
- What Werkator does (git-centric CI/CD, builds on native/Docker/werkdock, status reporting)
|
|
- Its dual-mode operation (CLI and Server)
|
|
- The five-layer configuration merging strategy
|
|
- The package structure and responsibilities
|
|
- Hard invariants (no primary-checkout builds, one build per branch, RepoContext scope)
|
|
|
|
##### Verified by
|
|
|
|
- Manual review of the documentation structure and completeness.
|
|
|
|
#### Scenario#36.02: An agent can make configuration changes correctly
|
|
|
|
So that it does not accidentally set pinned keys, breaks inheritance rules, or misunderstands layer precedence.
|
|
|
|
- **Given** an agent tasked with modifying build configuration
|
|
- **When** it reads the configuration reference in `docs/llms.md`
|
|
- **Then** it knows:
|
|
- Which keys belong to which config layer (instance, project, machine, branch)
|
|
- Which keys are pinned and cannot be overridden by branches
|
|
- How inheritance from `builds.default` works
|
|
- The exact default values for every setting
|
|
|
|
##### Verified by
|
|
|
|
- Manual review of the configuration reference section.
|
|
|
|
#### Scenario#36.03: An agent understands build execution without reading source code
|
|
|
|
So that it can predict build behavior and troubleshoot failures.
|
|
|
|
- **Given** an agent debugging a build issue
|
|
- **When** it reads the "Build Execution" and "Build Definitions and Triggering" sections
|
|
- **Then** it understands:
|
|
- How branch worktrees are created and reused
|
|
- The three build runtimes and their differences
|
|
- How `.git` is masked to prevent credential leaks
|
|
- How trigger rules work (onPush, atTimes, branch selectors)
|
|
- The pull-request gate and its implementation (git ls-remote, not API)
|
|
|
|
##### Verified by
|
|
|
|
- Manual review of the build execution documentation.
|
|
|
|
#### Scenario#36.04: An agent can interact with Werkator programmatically
|
|
|
|
So that it can query build status, retrieve artifacts, and trigger builds without reading the API implementation.
|
|
|
|
- **Given** an agent tasked with integrating another system with Werkator
|
|
- **When** it reads the "JSON API" and "Common Patterns for Agents" sections
|
|
- **Then** it knows:
|
|
- The endpoint URLs and methods (GET, POST)
|
|
- The response JSON structure and field meanings
|
|
- How to query status, trigger builds, retrieve artifacts
|
|
- How to detect build failures, understand build times, work with multi-build workflows
|
|
|
|
##### Verified by
|
|
|
|
- Manual review of the JSON API reference and patterns sections.
|
|
|
|
#### Scenario#36.05: An agent understands deployment without operator knowledge
|
|
|
|
So that it can make deployment-aware code changes (e.g., systemd service, runtime bundle).
|
|
|
|
- **Given** an agent tasked with modifying deployment behavior
|
|
- **When** it reads the "Deployment" section and the links to `deployment.md`
|
|
- **Then** it knows:
|
|
- How Werkator is deployed (systemd service, reverse proxy, optional managed nginx)
|
|
- The runtime bundle for hosts without Java
|
|
- The Hostsharing-specific patterns
|
|
|
|
##### Verified by
|
|
|
|
- Manual review of the deployment section and links.
|
|
|
|
## The Solution
|
|
|
|
A single, dense, agent-focused document: `docs/llms.md`.
|
|
|
|
The document covers in this order:
|
|
|
|
1. **System Overview** — what Werkator is and does at a glance.
|
|
2. **Architecture** — package structure (all packages under `de.hoennig.werkator` with one-line purpose), key invariants (five hard rules that must never be violated).
|
|
3. **Configuration** — the five layers, config file locations (table), complete reference of every top-level key with defaults, runtime inspection commands.
|
|
4. **Features** — detailed description of each capability:
|
|
- Build execution (three runtimes, worktree management, concurrency, git masking)
|
|
- Build definitions and triggering (named builds, inheritance, pinning, trigger types)
|
|
- Watcher (polling, startup recovery, per-context guards)
|
|
- Artifacts (retention, latest-green links, serving)
|
|
- Metrics (sampling, JSON API exposure)
|
|
- Web UI (server-rendered, drop-down navigation, no auth)
|
|
5. **CLI Commands** — one heading per command (`init`, `build`, `retry`, `status`, `server`, `config:print`), with usage examples and what it does.
|
|
6. **JSON API** — endpoint table (URL, method, purpose), response format examples, fields explained.
|
|
7. **Common Patterns for Agents** — how to solve typical integration problems (detect failures, retrieve artifacts, check logs, understand timing, work with multi-builds).
|
|
8. **Deployment** — brief description, links to `deployment.md`.
|
|
9. **Testing and Debugging** — test commands, config inspection, build monitoring.
|
|
10. **ADRs** — quick reference to the major decisions and their numbers.
|
|
11. **Related Documentation** — links to existing docs that complement this one.
|
|
|
|
The document is technical and complete, written **for agents**: dense, no tutorials, every statement is precise and verifiable against the code.
|
|
|
|
## Additional Changes
|
|
|
|
- None beyond the new file.
|
|
|
|
## Follow-up PRs
|
|
|
|
- If new features are added to Werkator (e.g., new CLI commands, new config keys, new API endpoints), this document must be updated alongside the feature — it is part of the feature's public interface for agents.
|
|
- Consider adding `docs/llms.md` to the pre-commit CI checks to verify it stays in sync with configuration.md and ADRs (optional, deferred).
|