Skip to content

Stack & Archetype Wiki Convention

Owner: Annegreet (structural health) + Jaap (SSOT enforcement) Effective: 2026-03-26 Status: BINDING — all wiki contributions MUST conform

Directory Structure

wiki/docs/
├── stack/                    # Phase 1: Technology-specific knowledge
│   ├── CONVENTION.md         # THIS FILE
│   ├── {technology}/         # One directory per stack technology
│   │   ├── index.md          # Overview, version, when to use, GE conventions
│   │   ├── {topic}.md        # Deep topic pages
│   │   ├── pitfalls.md       # ALWAYS present — known failure modes
│   │   └── checklist.md      # ALWAYS present — machine-parseable checklists
│   └── ...
├── archetypes/               # Phase 2: Application archetype knowledge
│   ├── {archetype}/          # One directory per archetype
│   │   ├── index.md          # Archetype overview, common variants
│   │   ├── feature-tree.md   # ALWAYS present — complete feature decomposition
│   │   ├── {domain}.md       # Deep domain pages (auth, payments, etc.)
│   │   ├── integrations.md   # Common third-party integrations
│   │   ├── compliance.md     # Regulatory/legal requirements
│   │   └── checklist.md      # ALWAYS present — scope completeness checklist
│   └── ...
├── domains/                  # Existing: Role-based domain knowledge (unchanged)
└── development/              # Existing: GE internal standards (unchanged)

Naming Rules (BINDING)

Directories

  • ALL lowercase
  • Hyphenated compound words: e-commerce, b2b-saas, client-portal
  • Technology canonical names: nextjs (not next-js, not next.js), postgresql (not postgres), drizzle (not drizzle-orm), tailwind-shadcn (combined — always used together in GE), swift-swiftui (combined — GE uses both), vitest, playwright, hono, redis, kubernetes, terraform-upcloud (combined — UpCloud is our only provider), bunnynet, github-actions

Files

  • ALL lowercase, hyphenated: server-components.md, data-fetching.md
  • No abbreviations: authentication.md not auth.md
  • No version numbers in filenames: content versioned via git, not filenames
  • Mandatory files per directory: index.md, pitfalls.md, checklist.md
  • Archetype mandatory: + feature-tree.md

Cross-References

  • ALWAYS use relative paths from wiki root: wiki/docs/stack/nextjs/pitfalls.md
  • NEVER use absolute filesystem paths
  • Format: READ_ALSO: wiki/docs/stack/nextjs/server-components.md
  • Bidirectional: if A references B, B MUST reference A
  • Cross-layer references encouraged: stack ↔ archetype ↔ domain

Page Template (Stack)

# {Technology} — {Topic}

OWNER: {primary agent}
ALSO_USED_BY: {agent1}, {agent2}
LAST_VERIFIED: {date}
GE_STACK_VERSION: {version GE pins to}

---

## Overview
{2-3 lines: what this covers, when agents need it}

## Patterns
{Agentic format: CHECK:/IF:/THEN:/TOOL:/RUN: tags}

## Anti-Patterns
{ANTI_PATTERN:/FIX: pairs}

## GE-Specific Conventions
{How GE uses this differently from generic usage}

## Cross-References
READ_ALSO: {related stack pages}
READ_ALSO: {related archetype pages}
READ_ALSO: {related domain pages}

Page Template (Archetype)

# {Archetype} — {Domain}

OWNER: Aimee (scoping), {dev agent}
ALSO_USED_BY: Anna (spec), Antje (TDD), {team leads}
LAST_VERIFIED: {date}

---

## Overview
{What this domain covers in context of the archetype}

## Feature Decomposition
SCOPE_ITEM: {feature name}
  INCLUDES: {what's always part of this}
  OPTIONAL: {common add-ons}
  COMPLIANCE: {regulatory requirements}
  ESTIMATE_COMPLEXITY: simple | normal | complex | critical
  STACK_REF: wiki/docs/stack/{tech}/{relevant-page}.md

## Implementation Patterns
{How GE builds this — references to stack pages}

## Integration Points
{Third-party services, APIs, webhooks}

## Checklist
{Machine-parseable scope/implementation checklist}

## Cross-References
READ_ALSO: {related archetype pages}
READ_ALSO: {related stack pages}

Checklist Format (Machine-Parseable)

## {PHASE} CHECKLIST ({context})

- [ ] CHECK: {verification item}
- [ ] CHECK: {verification item}
  IF_SKIPPED: {consequence of skipping}
  ADDED_FROM: {learning source — e.g., "project-acme-2026-04, checkout bug"}

Checklists grow organically: - Agents add items when they discover pitfalls during development - Format: ADDED_FROM: {project}-{date}, {brief reason} - Items are NEVER removed — only marked DEPRECATED: {reason} if no longer applicable - Annegreet reviews weekly for duplicates and consolidation

Learning Feedback Routes

When an agent discovers a pitfall during development:

  1. Stack-level issue → wiki/docs/stack/{tech}/pitfalls.md + checklist.md
  2. Archetype-level issue → wiki/docs/archetypes/{type}/{domain}.md + checklist.md
  3. Cross-cutting issue → both locations + wiki/docs/development/pitfalls/
  4. Eltjo detects the pattern, Annegreet routes to correct page(s)

Health Checks (Annegreet RECURRING_TASK)

Weekly automated checks: - Dead links: every READ_ALSO: and STACK_REF: path verified - Naming violations: directory/file names against convention - Orphan pages: pages not referenced by any agent's WIKI_BRAIN - Stale content: LAST_VERIFIED older than 90 days - Missing mandatory files: every directory has index.md + pitfalls.md + checklist.md - Bidirectional references: if A→B then B→A

Version Pinning

GE pins stack versions. When a version changes: 1. Joshua (Innovation) proposes the upgrade 2. Discussion with affected agents 3. If approved: update GE_STACK_VERSION in ALL affected pages 4. Annegreet verifies all pages updated 5. Wiki restart