Documentation map
September 8, 2026 · View on GitHub
English | 中文
Open one layer. Do not copy tables from another layer. If two files disagree, the spec wins; then fix the other file in the same change.
| Layer | File | Audience | Contains |
|---|---|---|---|
| Public product | README.md · README.zh.md | Users on GitHub | What it is, install xtz, plugin table, screenshots |
| Contribute | CONTRIBUTING.md · CONTRIBUTING.zh.md | Humans in this repo | Clone, inner loop, gates, where to put a change |
| Spec | conventions.md · conventions.zh.md | Everyone | What is true: homes, Git (main + tags, no Git Flow), package identity, CLI contract, versions, market catalog |
| Harness plugin delta | harness-plugin.md · harness-plugin.zh.md | Plugin authors and agents | Official Cordis/plugin links plus how this repo differs. Not a copied tutorial |
| Product changelog | CHANGELOG.md | Users and maintainers | What shipped in each vX.Y.Z |
| Procedure | workflow.md · workflow.zh.md | Humans and agents | How to do a job: create, install, commit, ship, parallel checkouts |
| Agent rules | AGENTS.md | Agents | Hard rules only. No tutorials. |
| Agent skills | .grok/skills/ | Agents | Job-specific; they point at spec/procedure, they do not replace them |
| Internal scratch | NOTES.md | Maintainers | Working notes. Not a contract. Not a public doc. |
| CLI product | apps/cli/README.md | Users of xtz | Command list and safety boundary |
| Plugin user docs | plugins/<slug>/README.md | Users of that plugin | What the plugin occupies and how to use it |
| Plugin PRD / design | plugins/<slug>/docs/ | Product and engineering | Implemented behavior. Deferred work is marked deferred. |
| UI design system | design-system/xiaotaozi-dsh/MASTER.md · upgrade record | Product, design, and frontend | Normative visual, interaction, accessibility, and responsive contract; completed rollout record |
| Historical plans | superpowers/ | Maintainers | Implemented or abandoned plans. Not the current spec. Do not update them when the product changes. |
| Historical reviews | reviews/ | Maintainers | One-off review records. Not a contract. |
Plugin Center navigation
User entry: Plugin Center → Installed → Models/IM bots/Xiaotaozi/Side workbench; Discover plugins is the curated catalog. Runtime controls: Settings → Advanced. See conventions for ownership, workflow for opening the UI, and Harness deltas for child-slot authorization and the pinned Settings adapter. Package READMEs describe each embedded capability; the market README describes installed/discovery operations.
Which file to edit
| You changed… | Update |
|---|---|
| A hard rule (homes, fail-closed commands, no Desktop, SemVer, Git) | AGENTS.md and docs/conventions.md (both languages) |
| Branching / worktrees / Git Flow | conventions.md § Git and workflow.md § Dev environment (both languages) |
| A product release | CHANGELOG.md, versions.json cliApp, git tag; procedure: workflow.md § Ship a product snapshot |
How xtz reaches npm | conventions.md § Versions (Trusted Publisher identity) and workflow.md § Ship |
| How to create / install / commit | docs/workflow.md (both languages) |
| How our plugins differ from official Harness plugin docs | harness-plugin.md (both languages); pointer in conventions § Plugin layout |
| Sandbox dogfood monitoring | conventions.md § Homes and workflow.md § Sandbox dogfood monitoring (both languages); AGENTS.md. Keep-alive is mandatory; poll origin/main every 10 minutes; when behind, fast-forward then restart pnpm dev; journey grep is not a substitute; product breaks are GitHub issues, not hub implementation. |
| Install command, plugin table, public narrative | root README.md / README.zh.md |
| Public website copy / Plugin Center navigation | apps/website/guide/ and apps/website/zh/guide/ (both languages); local pnpm --dir apps/website build. Do not deploy unless asked |
xtz flags or disabled commands | apps/cli/README.md and conventions § xtz CLI |
| A plugin's user-facing behavior | that plugin's README pair; PRD if the product contract changed |
| First-party plugin README portrait | brand.zh.md §7 (spec) and workflow.md § Create step 8 (files) |
| Agent routing (which skill) | .grok/skills/*/SKILL.md — keep them short |
| First-party plugin Web UI | design-system/xiaotaozi-dsh/MASTER.md and the affected plugin UI |
| Marketing website UI | apps/website/DESIGN.md and the affected website UI |
Public website hosting / tcb deploy | conventions.md § Public website and workflow.md § Deploy the public site (both languages); .grok/skills/website-deploy/SKILL.md |
A file under docs/superpowers/ or docs/reviews/ | Do not update. Those files are history, not the current spec. |
Project layout (engineering)
README.md public product
CONTRIBUTING.md contributor entry
AGENTS.md agent hard rules
NOTES.md internal scratch
docs/ spec + procedure + this map
apps/cli/ user product (xtz) — standalone workspace
apps/website/ public site — standalone workspace
plugins/<slug>/ one first-party installable package
plugins/market/ Plugin Center; third-party plugins are catalog rows
templates/ pnpm new skeletons
design-system/ first-party UI contract and visual reference
scripts/ new / link-plugin / sandbox / gates / doctor
.grok/skills/ agent skills
.dsh-home/ gitignored sandbox home (3081)
There is no apps/desktop/. History is git tag archive/desktop. There is no packages/ and no externals/.