Skip to content

v2.21.0

Choose a tag to compare

View all tags
@mrbro-bot mrbro-bot released this 23 May 15:26
· 632 commits to main since this release
v2.21.0
400f36f
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

What's new

Launch-surface cleanup — the first ~30 seconds a developer spends with this project. README, home page, Quick Start, config docs, and contributor docs now tell a coherent story instead of repeating each other.

Top-level docs split

AGENTS.md was carrying three audiences in 188 lines. Split into:

  • ARCHITECTURE.md — bird's eye overview, codemap, invariants, data flow, cross-cutting concerns
  • STRUCTURE.md — directory layout, per-directory purposes, naming conventions, where to add new code
  • AGENTS.md — slimmed to 68 lines of contributor conventions plus a routing table that points at the other two

README rewritten

400 lines of tables + Mermaid diagram + CLI reference → 75 lines of problem-first prose. The detail moved to the docs site where it belongs.

Home page and Quick Start

  • Home page rewritten as a real product landing page — concrete capability cards, the actual workflow as Steps, Quick Start snippet, and a "What Systematic Is Not" honesty section.
  • New getting-started/quick-start.mdx — 5-minute walkthrough from opencode.json install to a first completed workflow (brainstorm → plan → work → review). Uses a canonical example task across every surface so the story stays consistent.

Config docs merged

Two overlapping pages (getting-started/configuration + reference/systematic-config) → one human-owned reference/configuration page with auto-generated regions injected between sentinel markers. Legacy URLs redirect to the new location.

New project-scoped skill

.agents/skills/generating-project-docs/SKILL.md replaces the old .opencode/commands/generate-readme.md slash command. Picked up automatically by OpenCode via agentskills.io discovery. Broader scope: README + ARCHITECTURE + STRUCTURE, plus scoped section updates.

SEO pass

Every page under docs/src/content/docs/ now has a real frontmatter description (120–160 chars, action-oriented).

Bug catches

  • MDX {#anchor} heading syntax crashes the Astro/MDX 3 build — drop the explicit anchor; Starlight auto-slugs to the same fragment.
  • Astro redirects destinations don't get base-prefixed — production-404 class. Source keys resolve against base, but destinations write verbatim. Include base manually in every destination.

Three solution docs added under docs/solutions/ capturing the learnings.

Verification

  • bun test — 950 pass, 0 fail (+11 new tests)
  • bun run docs:build — green
  • bun run docs:dev + live-server navigation — visual rendering and redirect behavior confirmed
  • ce:review (7 reviewers) — 5 non-blocking findings, all resolved before merge

Compare

v2.20.6...v2.21.0

Also in this release

  • deps: update github/codeql-action action to v4.36.0 (#427)
Assets 2
Loading