feat(docs): developer internals documentation + dev-docs-auditor (AL-22)#26
Merged
Conversation
Adds product-perspective developer documentation explaining what each AgentLinux component does and why, plus a reviewer agent + skill that keep the docs in sync via the existing review loop. What ships: - `docs/internals/` — index + 9 component docs (installer, agent-user, sudo-drop-in, nodejs-runtime, claude-code, gsd, playwright, registry-cli, catalog). Each follows a four-section contract: problem → AgentLinux's answer → value vs the naive approach → related. Audience is the project owner; tone is product-first so excerpts feed naturally into blog posts, marketing emails, and the agentlinux.org landing page. - `.claude/agents/dev-docs-auditor.md` — read-only reviewer agent (tools: Read, Grep, Glob, Bash) that checks the matching `docs/internals/<component>.md` is still accurate when changes touch `plugin/bin/`, `plugin/lib/`, `plugin/provisioner/`, `plugin/cli/src/`, `plugin/catalog/`, or `packaging/curl-installer/`. Skips on pure refactors, typos, or comment-only changes. - `.claude/skills/dev-docs/SKILL.md` — documents the docs contract + source-path -> doc-path dispatch table. - `CLAUDE.md` — Review Loop reviewer-by-file-type table extended with `dev-docs-auditor` for Bash, TS/JS, and Catalog rows. Pointers list grew to include `dev-docs/` and a top-level `docs/internals/` link. - `README.md` — new "Why AgentLinux — concepts" section + Links row pointing into `docs/internals/`. - `docs/decisions/015-developer-internals-docs.md` — ADR-015 records the design decision: embed dev-docs-auditor in the existing review loop, no third stop-hook. Companion to ADR-010. - `.planning/REQUIREMENTS.md` — DOC-01..DOC-07 added under a new `## Post-v0.4.0 Addendum Requirements` H2 with its own traceability sub-table. The v0.4.0 milestone count remains 21 (closed at c8a2787). - `.planning/ROADMAP.md` — Phase 12 marked complete (5/5 plans). GSD planning trail (CONTEXT, PATTERNS, 5 PLANs, 5 SUMMARYs, AUDIT, VERIFICATION) included for traceability. Verification: 8/8 must-haves green; gate: GREEN. Closes AL-22.
…/internals/ (AL-22)
Adds three review subagents that target user-facing / project-owner-facing
documents and external-audience copy. Then applies their first-pass
findings to the Phase 12 docs.
New agents (.claude/agents/):
- fact-checker — finds factual claims and verifies against source code,
tests, ADRs, and research files. Adapted from a sister project to
AgentLinux's verification hierarchy (plugin/, tests/bats/, docs/decisions,
Atlassian project AL).
- technical-writer — reviews for clarity, conciseness, and actionability.
Anti-bloat rules, self-sufficiency checklist, voice-rule pattern. Adapted
to AgentLinux's requirement vocabulary (BHV/RT/AGT/CLI/CAT/INST/HRN/TST/
DOC/EXPL/STRAT/SITE/ADR) and domain terms (preset vs profile, curated
combo vs default version set).
- external-audience-auditor — detects internal-vocabulary leakage in
externally-facing artifacts (top-level README, docs/internals/,
CONTRIBUTING.md, blog/email/website drafts). Rewritten from a
PatchFlow-specific template to AgentLinux's external-vs-internal split.
Internal vocabulary that must not leak: AL Jira keys, .planning/ paths,
GSD plan filenames, requirement IDs, phase numbering, bare ADR refs,
GSD orchestrator vocabulary, Claude Code self-references in product copy.
Findings applied to docs/internals/ (the Phase 12 deliverable, written for
the project owner so he can excerpt into blog posts, marketing emails, and
agentlinux.org copy):
Factual fixes (fact-checker):
- README.md: Playwright install command (npm @playwright/cli +
playwright-cli install --skills, NOT 'playwright install --with-deps')
- README.md: Registry CLI verb list (5 verbs including 'list', not 4)
- installer.md: Worked example shows all 5 provisioner steps run
(50-registry-cli was missing)
- installer.md: 'agentlinux list' column headers match the actual CLI
output (NAME STATUS CURATED INSTALLED DESCRIPTION) and the catalog
id (playwright-cli) and pin (0.1.11) match catalog.json
Vocabulary leaks (external-audience-auditor):
- ~10 bare 'AGT-02' requirement IDs dropped across 6 docs; prose now
carries the meaning ("the release-gate test", "the self-update-without-
sudo invariant")
- 'AGT-02b version-lock satisfied' worked-example output line in
claude-code.md replaced with natural-language equivalent
- Bare ADR-NNN refs spell-and-linked: ADR-003 (no-default-installs),
ADR-004 (per-user-prefix), ADR-005 (system-Node), ADR-006 (curl-pipe-
bash + .deb), ADR-012 (agent-user-full-sudo)
- 'CAT-01 / CAT-02 / CAT-03' bare IDs dropped from catalog.md
- 'security-engineer review subagent' / 'catalog auditor' renamed
to 'our PR review process' / 'our catalog reviewer'
- 'v0.3.0 Phases 1-4' and 'v0.4+ USR-05 sandboxing path' replaced
with neutral prose
Bloat fixes (technical-writer):
- EACCES + recursive-shim retelling consolidated to live canonically
in agent-user.md; nodejs-runtime.md, claude-code.md, gsd.md,
playwright.md now cross-link instead of re-narrate (~30+ lines saved)
- installer.md sudo-npm paragraph trimmed to one-line forward
reference to agent-user.md
…ue (AL-22)
A doc anti-pattern surfaced in the post-PR review: paragraphs describing
problems that only exist because AgentLinux exists, framed as "here's a
problem, here's how AgentLinux solves it." The reader has no use for that
framing — the problem isn't a problem unless they've already chosen to
use AgentLinux.
Removed instances:
- installer.md: dropped the main(){}; main "\$@" partial-download mitigation
paragraph, the AGENTLINUX_VERSION regex-validation sentence, the gzip
magic-bytes check, the --no-same-owner extraction note. Replaced with a
focus on what AgentLinux makes possible — a reproducible, version-pinned
install of the whole agent environment in one command, with the SHA256
verified before any code runs. Value-vs-naive summary slimmed accordingly.
- sudo-drop-in.md: trimmed the visudo -cf tmpfile validation + atomic-rename
+ post-install rehash detail to a one-line mode/ownership statement. The
fact that AgentLinux's own writer is careful not to corrupt sudoers is
not a real-world problem to anyone except AgentLinux's installer itself.
Kept unchanged: per-user npm prefix, PATH wiring across six modes,
catalog schema validation, run-as-agent CLI guard, catalog version
pinning. These describe problems any team setting up a similar agent
environment would face independently — implementation detail there is
legitimate user-facing context.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds product-perspective developer documentation explaining what each AgentLinux component does and why, plus a reviewer agent that keeps the docs in sync via the existing review loop. Closes AL-22.
The motivating question (from AL-22): "What value does AgentLinux provide in installing GSD instead of using the GSD installation from npm directly?" The new docs answer that class of question in <60 seconds, with a product-first tone so excerpts feed naturally into blog posts, marketing emails, and the agentlinux.org landing page.
What ships
docs/internals/— index + 9 component docs (installer, agent-user, sudo-drop-in, nodejs-runtime, claude-code, gsd, playwright, registry-cli, catalog). Each follows a four-section contract: problem → AgentLinux's answer → value vs the naive approach → related..claude/agents/dev-docs-auditor.md— read-only reviewer agent (Read, Grep, Glob, Bash). Triggers when changes touchplugin/bin/,plugin/lib/,plugin/provisioner/,plugin/cli/src/,plugin/catalog/, orpackaging/curl-installer/. Flags missing component docs, stale claims, source-line deep links, and TOC drift. Skips pure refactors and typos..claude/skills/dev-docs/SKILL.md— documents the docs contract + source-path → doc-path dispatch table.CLAUDE.md— Review Loop reviewer-by-file-type table extended withdev-docs-auditoron Bash, TS/JS, and Catalog rows (does not modify Bats spec or Docs rows). Pointers list addsdev-docs/and a top-leveldocs/internals/link.README.md— new "Why AgentLinux — concepts" section + Links row pointing intodocs/internals/.docs/decisions/015-developer-internals-docs.md— ADR-015 records the design decision: embeddev-docs-auditorin the existing review loop, no third stop-hook. Companion to ADR-010..planning/REQUIREMENTS.md— DOC-01..DOC-07 added under a new## Post-v0.4.0 Addendum RequirementsH2 with its own traceability sub-table. The v0.4.0 milestone count remains 21 (closed atc8a2787); the addendum is tracked separately..planning/phases/12-…/— full GSD planning trail (CONTEXT, PATTERNS, 5 PLANs, 5 SUMMARYs, AUDIT, VERIFICATION) for traceability.Key design decision
No new stop-hook. The two existing reminder hooks (
review-reminder.sh,session-tracker-reminder.sh) cover the surface; docs-sync enforcement rides inside the existing review loop via the new reviewer agent. This keeps the ADR-010 reminder-hook count at two and avoids stop-hook proliferation. Captured in ADR-015.Verification
gsd-verifier.docs/internals/..claude/hooks/dev-docs-reminder.shdoes not exist;.claude/settings.jsonwas not modified.Test plan
pre-commitpasses (markdown/yaml/JSON checks)test.ymlworkflow greendocs/internals/README.mdTOC links workThe problem,What AgentLinux does,Value vs the naive approach,Related)README.md"Why AgentLinux — concepts" link reachesdocs/internals/README.mddocs/decisions/015-developer-internals-docs.md) is well-formed🤖 Generated with Claude Code