Wiki Conventions

How this wiki is structured and maintained.

Purpose

This wiki is an AI-first design knowledge base. It holds current belief about devwork-skills' design — what we currently think the system is, why we think it, and what's unresolved. Written mostly by AI agents, consumed mostly by AI agents, reviewed and approved by humans.

devwork-skills is a platform (a set of opinionated Claude Code skills that other projects consume), not an end-user application. The Role - and Contract - prefixes are first-class here, alongside the standard Product -, Design -, Concept -, and Research -.

Day-to-day skill installation, usage, and the canonical skill list live in the README, not the wiki.

Page Template

Every content page uses this structure:

---
Status: complete | incomplete
Last updated: YYYY-MM-DD
Parent: [[Parent Page]] | none
Read before this: [[Page A]], [[Page B]] | none
---

# <Page Title>

## Current state

What we currently believe, written as if true.

## Rationale

Compressed reasoning behind the current state. Why this and not something else.

## Open questions

What's unresolved on this page's subject. Empty section if nothing is open.

Frontmatter fields

• Status — complete if the page fully covers current belief. incomplete if known gaps exist (explain them under Open questions).
• Last updated — date of the last meaningful content change.
• Parent — the page this one logically sits under, or none for top-level pages. Used to build a dependency graph.
• Read before this — pages an agent should load first to make sense of this one. Keep the list short; chain through parents for deeper context.

Section discipline

• Current state is written as current belief, not as history. "The system uses X" — not "We decided to use X after considering Y."
• Rationale is why, not what. It compresses the reasoning so a future agent doesn't re-derive it.
• Open questions are per-page, not centralised. When a question resolves, it moves into Current state / Rationale and leaves the Open questions section.

Edit Discipline

Supersede, don't append. The wiki holds current state only. When belief changes, the existing text is replaced. Git history holds the evolution — the page does not.

No "previously we thought" sections. No strikethrough. No changelog on the page.

Page Status

Binary: complete or incomplete. A page stays complete through many revisions as long as each revision is a full statement of current belief. incomplete means there's a gap significant enough to flag — documented under Open questions.

Prefix Catalogue

Pages are grouped by filename prefix.

Active prefixes

• Product - — what the system is and the goals behind it (vision, principles).
• Design - — system design, architecture, data flow. The primary design-knowledge bucket.
• Role - — one page per functional role in the platform. What the role does, its interface, its lifecycle, how it composes with other roles.
• Contract - — adapter-level interface specifications. Input/output shapes, invariants, error semantics.
• Concept - — cross-cutting ideas that span multiple design pages.
• Research - — external inputs (Boris Cherny's reported workflow, community patterns, Anthropic's official plugins, prior art).

Reserved (not currently used)

• Security - — would activate if devwork-skills ever takes on compliance obligations of its own. See Wiki Conventions - Security Section Pattern (dormant).

Unprefixed pages

• Home, _Sidebar, Wiki Conventions and its sub-pages.

Naming Rules

• Title Case With Spaces in filenames.
• Hyphen and spaces around it in the prefix: Design - Architecture Overview, not Design-Architecture-Overview.
• Forgejo replaces spaces in URLs, so Design - Architecture Overview becomes Design---Architecture-Overview in the URL bar. This is cosmetic and doesn't affect [[WikiLink]] cross-references — always use the full title form when linking.

Learnings

There is no central Learnings page. Learnings split by kind:

• Process learnings about how the SDLC itself runs (recurring pitfalls, agent gotchas, model selection patterns) → captured in CLAUDE.md of consuming projects, where Claude Code reads them during development. devwork-skills doesn't itself have a CLAUDE.md for this purpose because it's not a project that runs through its own pipeline.
• Design learnings about the platform → the Rationale section of the relevant design page.

If a design learning has no obvious page to live on, that's a signal a design page is missing and should be created.

Write Access

Current model: AI writes, humans review.

• AI agents (Claude, Claude Code) draft and revise pages.
• Humans review and approve via git commits, the Forgejo wiki UI, or pull requests.
• No page is AI-writable without human review at this stage.

The probability-based governance model the scaffold provides (see Wiki Conventions - Governance Model) is dormant here. devwork-skills doesn't have a documentation-review agent of its own — it defines the pattern that consuming projects can adopt.

Reference Material

Patterns from the scaffold documented for reference but not currently in use:

• Wiki Conventions - Governance Model — probability-based review model (dormant)
• Wiki Conventions - Security Section Pattern — ISO 27001 structure (dormant)

These pages are not linked from _Sidebar — they live here as reference only.