Docs management

Skill theseus-run/theseus/.agents/skills/docs-management

the harness rebuilds itself — agents rewrite agents, skills replace skills.

Install

npx -y skills add theseus-run/theseus --skill docs-management

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when editing the Theseus docs vault under docs/, including adding, moving, splitting, renaming, archiving, cross-linking, changing doc status, or restructuring section indexes.

SKILL.md

3.3 KB, as published. Nobody here has run it

Theseus Docs Management

Use this skill whenever you edit docs/.

The docs are durable design memory. They must make status obvious: what is current, what is draft, what is speculative, and what is superseded.

Folder Contract

docs/
  README.md
  direction/          current product direction
  primitives/         current primitive and protocol doctrine
  runtime/            current runtime architecture and implementation notes
  clients/            current client/operator surface notes
  drafts/             unadopted design drafts, research notes, and POCs
  brainstorms/        loose speculative ideas
  archive/            superseded designs kept for archaeology
  design-notes/       adopted or active rationale that does not fit a concept note
  maps/               navigation maps for humans and coding agents

Default placement:

current truth about implemented or intended architecture: direction, primitives, runtime, clients
useful but unadopted design/research: drafts
deliberately wild or unvalidated ideation: brainstorms
superseded history: archive
adopted time-bound rationale: design-notes
navigation over existing docs: maps

Do not leave stray top-level folders under docs/.

Link Policy

Use relative Markdown links, not Obsidian wikilinks.

Good:

[architecture](../runtime/architecture.md)
[tool](tool.md)

Bad:

double-bracket link to architecture
double-bracket link to tool

After moving files, update obvious links and run a link-resolution check.

Status Rules

Current notes should say what is true now. Do not mix aspirational behavior into current implementation notes without labeling it as not implemented.

Use short status banners when they prevent confusion:

> Status: current implementation
> Status: active doctrine
> Status: draft
> Status: brainstorm
> Status: SUPERSEDED — see [architecture](../runtime/architecture.md)

If a note moves to archive, add or keep a superseded banner.

Editing Rules

One durable concept per note.
Keep active docs accurate against the code.
Preserve useful history by moving it, not deleting it.
Split concept truth from reasoning history.
Keep docs/README.md and section README.md files current.
Prefer precise links to companion notes over duplicating large explanations.
Do not hand-wave with "future"; say not implemented, draft, or brainstorm.

Accuracy Workflow

Read the note and linked companion notes.
Read the relevant source files before changing implementation claims.
Decide the note status: current, draft, brainstorm, archive, or design note.
Move or split the note if its status is wrong for its folder.
Rewrite claims so active docs describe real code and durable doctrine.
Update section indexes and docs/README.md.
Verify no wikilinks remain and all relative .md links resolve.

Useful checks:

rg -n "\\[\\[" docs
bun run docs:check

Preservation Rule

Before deleting or heavily reducing a note, verify it has no unique durable value. Prefer moving to drafts, brainstorms, or archive with a status banner.