update-docs

name	update-docs
description	Synchronize all documentation (Starlight docs, README, AGENTS, skills, memory) after code changes. Use after completing a feature, fixing bugs, or changing public APIs.
disable-model-invocation	true
argument-hint	package-name or "release X.Y.Z"

Update Documentation After Code Changes

Overview

This skill ensures all documentation stays truthful after code changes. Run it after completing any feature work.

Canonical source of truth for agent guidance is AGENTS.md. CLAUDE.md is a compatibility pointer only.

Integration with the Wiki Workflow

This skill follows the canonical 4-step pattern documented at [[wiki/Development/Wiki-Workflow]]. Specifically:

• Orient first: Run claude-obsidian:wiki-query "<feature-name>" before writing docs to find related decisions, prior debriefs, and existing concept pages. Avoids duplicating documentation.
• Capture correctly: Use claude-obsidian:obsidian-markdown when writing wiki pages — ensures proper OFM (wikilinks, callouts, frontmatter) so the graph stays coherent.
• Persist durably: For significant changes (new public API, deprecation, architectural shift), use claude-obsidian:save to create a debrief at wiki/Research/Debriefs/.
• Maintain after: End with claude-obsidian:wiki-lint to catch any orphan pages or dead wikilinks introduced by the doc update.

Storage convention reminder: All plans, specs, decisions, and debriefs live in wiki/. The docs/ directory was eliminated in May 2026. See AGENTS.md §Plans, Specs & Knowledge Storage.

Arguments

$ARGUMENTS = optional package name (e.g., a2a) or release tag (e.g., release 0.5.0).

If no arguments, scan for what changed and update accordingly.

Step 1: Determine What Changed

# See what files changed
git diff --name-only HEAD
git diff --stat HEAD

# Count current tests
bun test 2>&1 | tail -5

Categorize changes:

• New package created?
• New/changed builder methods?
• New CLI commands?
• New reasoning strategies?
• New LLM providers?
• Test count changed?
• API signatures changed?
• New features needing docs pages?

Step 2: Update AGENTS.md (Canonical)

Check and update these sections as needed:

1. Project status snapshot — test count, package count, latest shipped capabilities
2. Build commands — keep commands current and scoped
3. Documentation workflow — ensure references point to AGENTS/README/docs, not CLAUDE
4. Project skills index — keep all .agents/skills/*/SKILL.md entries accurate
5. Key file paths — include memory files and active docs

Step 3: Update README.md

Check and update:

1. Subtitle — package/layer counts
2. Packages table — add new packages
3. Architecture diagram — add new layers
4. Providers table — add new providers
5. Strategies table — add new strategies
6. Development section — test count
7. Code examples — verify they use actual API

Cross-check against latest release notes (CHANGELOG.md) for:

• Native function-calling behavior and tool-call fallback details
• Required-tools gating, dynamic stopping, and per-tool call budgets
• Builder/API additions (meta-tools, skills, composition, dynamic tools, pricing)

Step 4: Update CHANGELOG.md

If this is a release ($ARGUMENTS starts with "release"):

## [X.Y.Z] — YYYY-MM-DD

### Added

-   List each new feature with package scope in parentheses

### Changed

-   List package version bumps: `pkg` X.Y.Z → A.B.C: description

### Fixed

-   List bug fixes with root cause context

### Stats

-   N tests across M files (was P/Q)

Step 5: Update Starlight Docs Site

Check if pages need updating

Search docs for references to changed APIs:

grep -r "oldMethodName\|oldPackageName" apps/docs/src/content/docs/

Pages to check by change type

Changed	Check These Pages
Builder API	reference/builder-api.md, guides/quickstart.md, guides/your-first-agent.md
CLI	reference/cli.md
Reasoning	guides/reasoning.md, features/llm-providers.md
Tools	guides/tools.md
Memory	guides/memory.md
Providers	features/llm-providers.md
Architecture	concepts/architecture.md, concepts/layer-system.md
New feature	Create new page in features/ or guides/

Required audit pages for framework-level changes:

• apps/docs/src/content/docs/reference/builder-api.md
• apps/docs/src/content/docs/reference/configuration.md
• apps/docs/src/content/docs/guides/reasoning.md
• apps/docs/src/content/docs/guides/tools.md
• apps/docs/src/content/docs/guides/contributing.md
• apps/docs/src/content/docs/features/llm-providers.md

If new docs page needed

Create at apps/docs/src/content/docs/{section}/{name}.md:

---
title: Page Title
description: Brief description for SEO
---

Content here...

Sidebar is auto-generated from directory structure. Use sidebar: { order: N } in frontmatter to control ordering.

Step 6: Sync Canonical Documents (Critical)

After ANY code change, verify these 6 canonical documents stay synchronized:

Canonical Document Sync Rules

All documents live in docs/spec/docs/ with uniform naming NN-NAME.md:

Change Type	Update These Documents	How to Verify
New package shipped	07-ROADMAP-v1.0.md (architecture section) + 04-PROJECT-STATE.md (package count)	ls packages/ | wc -l matches both docs
New mechanism validated	06-AUDIT-v0.10.0.md §10.2 (if v0.10.0) OR 07-ROADMAP-v1.0.md (if v1.0+)	Verdict + rationale present in correct doc
Test count changed	04-PROJECT-STATE.md (test count) + 07-ROADMAP-v1.0.md (if impacts phase gate)	bun test 2>&1 | tail -3 matches docs
Phase gate passed	07-ROADMAP-v1.0.md (amendment log, next phase unlocked)	Date + gate results documented
New FM discovered	02-FAILURE-MODES.md (add FM entry) + relevant roadmap phase	FM-* code + references present
Architecture refined	05-DESIGN-NORTH-STAR.md + 07-ROADMAP-v1.0.md (Phase 2+ implications)	Both docs updated consistently
Release shipped	ROADMAP.md (move to "Released") + CHANGELOG.md + 04-PROJECT-STATE.md	Version present in all 3

Authority Enforcement

• DO NOT create one-off phase/spike plans for permanent planning (e.g., 2026-MM-DD-phase-N-*.md)
• Archive all tactical phase plans to docs/superpowers/plans/archive/ after completion
• If docs conflict: Amend lower-authority doc per AGENTS.md hierarchy; never silent drift
• Naming: All canonical docs use NN-NAME.md; no date prefixes or irregular suffixes

Quick Sync Checklist

After completing ANY feature, bug fix, or validation:

• 04-PROJECT-STATE.md test count matches bun test output
• 07-ROADMAP-v1.0.md amendment log updated (if phase gate passed)
• 06-AUDIT-v0.10.0.md mechanism verdicts updated (if v0.10.0 work)
• 02-FAILURE-MODES.md updated (if new FM discovered)
• .agents/MEMORY.md updated (new findings documented)
• No orphan one-off docs left in docs/superpowers/plans/ (archive if not current)
• No broken cross-references in AGENTS.md or DOCUMENT_INDEX.md

---

Step 6b: Update Agent Skills (.agents/skills/)

The .agents/skills/ directory contains skills used by agents to build with this framework. These must stay accurate — stale code examples or wrong API signatures directly cause agent errors.

Always check after:

• Builder method signatures change (.withReasoning(), .withTools(), .withMemory(), etc.)
• New builder methods are added (.withFallbacks(), .withLogging(), .withHealthCheck(), etc.)
• New stream event types are added (IterationProgress, StreamCancelled, etc.)
• New conversational APIs added (agent.chat(), agent.session())
• Config field names change (e.g., resultCompression field names)
• New strategy options added (enableStrategySwitching, etc.)

Skills index (all project skills)

Skill file	What to check
architecture-reference/SKILL.md	Dependency graph, build order, canonical docs pointers
build-coordinator/SKILL.md	Multi-agent coordination flow, parallelization assumptions
build-package/SKILL.md	Add-new-package scaffolding; canonical references (AGENTS, not CLAUDE)
kernel-extension/SKILL.md	Composable kernel phases, guards, meta-tools
agent-tdd/SKILL.md	Effect-TS TDD, timeouts, Effect.flip, server teardown
kernel-debug/SKILL.md	Symptom-to-phase debugging map
provider-streaming/SKILL.md	Provider streaming and adapter hooks
mcp-integration/SKILL.md	MCP client, Docker lifecycle, transport inference
reactive-feature-dev/SKILL.md	End-to-end feature workflow routing
prepare-release/SKILL.md	Release checklist, changeset, changelog template
effect-ts-patterns/SKILL.md	Core Effect-TS constraints and anti-patterns
implement-service/SKILL.md	Service scaffolding patterns and exports
implement-test/SKILL.md	Test harness usage and timeout guidance
llm-api-contract/SKILL.md	complete()/stream()/embed() signatures and tool-call contracts
memory-patterns/SKILL.md	SQLite/WAL/FTS5/vector memory patterns
review-patterns/SKILL.md	9-category compliance checks (incl. kernel extension)
update-docs/SKILL.md	This workflow, docs + memory synchronization
validate-build/SKILL.md	Build/test/review quality gates
obsidian-vault-query/SKILL.md	Read the Obsidian vault (external project oracle) at session start
obsidian-vault-sync/SKILL.md	Write durable artifacts (decisions, experiments, sessions) to the vault
obsidian-vault-hygiene/SKILL.md	Orphan/bitrot/duplicate loops keeping the vault graph coherent

How to update

1. For each skill affected by the change, open the file
2. Update code examples to use the current API
3. Update builder patterns in the "Agent objective" or "Implementation baseline" sections
4. Bump version in the frontmatter if the change is significant
5. Do NOT change prose that is still accurate — minimal diffs only

Step 7: Update Project Memory

When docs or workflow guidance changes, update memory artifacts so future agents inherit the same context:

1. Update .agents/MEMORY.md with a concise entry under current status and shipped changes.
2. Update repository memory notes in /memories/repo/ when conventions or canonical doc locations change.
3. Keep memory entries terse and factual (what changed, why it matters, where to look).

Update Agent Memory Files

After any significant feature or architecture change:

• Update .agents/MEMORY.md with new capabilities, patterns, or status
• Update Claude project memory at ~/.claude/projects/*/memory/ if session-level context has changed
• These two files keep future agents oriented without re-discovering project state

Step 7b: Sync to the Obsidian Vault (External Oracle)

The reactive-agents-ts Obsidian vault at <repo>/wiki/ is the project's external long-running oracle — compounding knowledge across sessions. Any doc update that reflects real project evolution should also land here so future agents discover it on query.

Delegate the write-back to obsidian-vault-sync. Rough protocol:

1. Decision-class change (architecture, canonical rename, public-API break) → create a note in Decisions/YYYY-MM-DD-<slug>.md from Templates/Decision Template.
2. Experiment-class change (benchmark result, failure-corpus finding, calibration update) → create a note in Experiments/YYYY-MM-DD-<slug>.md.
3. Concept / Package / Architecture refinement → edit the matching note in Concepts/ / Packages/ / Architecture/; bump updated: YYYY-MM-DD in frontmatter.
4. New failure mode → add an entry in Failure-Modes/ and update Failure-Modes/W-series Catalog.md.
5. Release → update Releases/vX.Y.Z.md + pointer in MOCs/Releases MOC.md.
6. Running Issues Log — if the change fixes or surfaces an issue, append to Issues/Running Issues Log.md.

Keep writes minimal and frontmatter-disciplined. See obsidian-vault-sync/SKILL.md for the full protocol and Playbooks/Agent Query API.md inside the vault for the schema.

Step 8: Update ROADMAP.md

If a milestone shipped:

• Move items from "target" to "✅ Released" with actual date
• Update the "Current State" section
• Update the Competitive Positioning table

Step 9: Verify Links Don't Break CI

Critical: Starlight/Astro converts relative paths in links, which can cause broken links in CI:

# Build docs locally to verify no link errors
cd apps/docs && rm -rf dist && bunx astro build

# For internal links within guides/:
# ❌ WRONG: ](./sibling-page) — rendered as /guides/whats-new/sibling-page
# ❌ WRONG: ](../guides/sibling-page) — in docs at /guides/file, becomes /guides/guides/sibling-page
# ✅ RIGHT: ](/guides/sibling-page) — absolute path works everywhere
# ✅ RIGHT: ](../features/page) — relative across directories OK (goes up then down)

# When editing files in guides/, use:
# - Sibling files in guides/: ](/guides/filename)
# - Files in features/: ](/features/filename)
# - Files in concepts/: ](/concepts/filename)
# - Files in reference/: ](/reference/filename)

Link checker will report: Cannot find file: file:///path/guides/guides/filename

Step 10: Verify

# Check for stale references
grep -r "CLAUDE.md.*package map\|CLAUDE.md.*build commands\|withTestResponses\|15 packages\|17 packages\|2194 tests" AGENTS.md README.md apps/docs .agents/skills

Step 11: CLAUDE.md Compatibility Check

Ensure CLAUDE.md remains a short compatibility pointer to AGENTS.md and does not become a second source of truth.

Quick Reference: Current Stats

Update these numbers when they change:

• Test count: check with bun test 2>&1 | tail -3
• Package count: ls packages/ | wc -l
• Doc pages: ls apps/docs/src/content/docs/**/*.md | wc -l