Documentation
¶
Overview ¶
Package docscheck is the documentation gate of card 110: the structural rules every release must pass, checked offline against the tree.
The documentation is one tree for humans and one for agents. Humans enter at README.md, which names five personas; each persona root names its topics; each topic root names its actions with a TL;DR and a Details link; the leaves hold the details. Agents enter at CLAUDE.md, whose @imports load the rule files under docs/agent/repository/. A harness Brigade ships a package for is one entry in docs/harnesses.json and six pages the gate requires. A decision is an ADR under docs/decisions/ (decisions.go). Run reports every rule the tree breaks; nothing here reaches the network, so a site going down is never a red build (cavalry ADR 0006). The one thing read beside the tree is its own git history, for the rule that a committed ADR keeps its text.
Index ¶
Constants ¶
const ( DecisionsDir = "docs/decisions" DecisionsIndex = "docs/decisions/README.md" DecisionsTemplate = "docs/decisions/0000-template.md" // DecisionsList is the index's section that lists every ADR. DecisionsList = "The decisions" )
The decisions' files, relative to the root.
const ( ReadmeFile = "README.md" AgentsFile = "AGENTS.md" ClaudeFile = "CLAUDE.md" ChangelogFile = "CHANGELOG.md" MakefileFile = "Makefile" VersionFile = "plugin/bin/VERSION" PluginManifest = "plugin/.claude-plugin/plugin.json" RegistryFile = "docs/harnesses.json" DocsDir = "docs" ResearchDir = "docs/research" ExperimentsDir = "docs/experiments" ExperimentsIndex = "docs/experiments/README.md" RulesDir = "docs/agent/repository" AgentTeamDir = "docs/agent/in-a-team" OptionsPage = "docs/team-member/configure/options.md" MakeTargetsPage = "docs/developer/reference/make-targets.md" CommandsPage = "docs/developer/reference/commands.md" // IfYouWantTo is the heading of the navigation table every persona root // and topic root carries. IfYouWantTo = "If you want to" // DetailsPrefix starts the line of an action section that names its leaf. DetailsPrefix = "Details:" // MaxOverviewSentences bounds a persona root's topic section. MaxOverviewSentences = 2 // MaxActionLines bounds a topic root's action section: a TL;DR, not the page. MaxActionLines = 20 // PreReleaseVersion is the pin of a tree that has not been released. PreReleaseVersion = "0.0.0" )
The files and directories the gate knows by name, relative to the root.
Variables ¶
var ErrFindings = errors.New("docscheck: the documentation breaks a rule")
ErrFindings is returned by Check when the tree breaks a rule.
var Personas = []Persona{
{Dir: "project-owner", Title: "Project Owner"},
{Dir: "team-admin", Title: "Team Admin"},
{Dir: "team-member", Title: "Team Member"},
{Dir: "developer", Title: "Developer"},
{Dir: "agent", Title: "AI Agent"},
}
Personas is the order README.md lists them in.
Functions ¶
func Check ¶
Check runs the gate and formats the result as the lines a person reads: one finding per line, then the summary. It returns ErrFindings when there is anything to fix.
func GenerateCommands ¶ added in v0.36.0
GenerateCommands renders the command reference page from internal/cli's command table (card 112): the `brigade help --all` block, then one section per command with the text `brigade help <name>` prints and the flags the command registers. It reads no file, so the gate stays offline and needs no built binary. The count is the number of commands.
func GenerateMakeTargets ¶
GenerateMakeTargets renders the make-target reference page from the Makefile's `target: ## help` lines, in Makefile order.
Types ¶
type Finding ¶
type Finding struct {
Check string // readme, persona, topic, links, reach, harness, agent, options, make, commands, coverage, changelog
Path string // the file the finding is about, relative to the root
Message string
}
Finding is one rule the tree breaks.
type Harness ¶
type Harness struct {
ID string `json:"id"`
Name string `json:"name"`
Vendor string `json:"vendor"`
Host string `json:"host"`
Package string `json:"package"`
Skills string `json:"skills"`
}
Harness is one entry of docs/harnesses.json.
type Persona ¶
type Persona struct {
Dir string // the directory under docs/
Title string // the H1 of its root page
}
Persona is one of the five readers the tree is organised for.
type Registry ¶
Registry is docs/harnesses.json.
func LoadRegistry ¶
LoadRegistry reads docs/harnesses.json under root.