Skip to content

Deliberation Log: Initial Foundation & Operating Rules

  • Date: October 2026
  • Participants: Project Initiator, AI Sparring Partner

1. Project Inception & Vision

Context & Goal

The initiator started a new project swayrm intended as a root project to define the requirements, domain model, and architecture of a new platform and ecosystem for global collaboration.

Core Mission Defined

"Empower citizen groups to organize themselves, work together in their own interest, and make decisions on their own behalf."

Core Problems Explored

  • Big Tech / Social Platforms: Profit from outrage and atomization; lack democratic decision mechanisms; subject to platform censorship and surveillance.
  • Traditional Institutions & Representative Bodies: High friction, gatekept, slow, detached from grassroots lived reality.
  • Web3 / DAOs: Overly financialized (coin-weighted voting: 1 coin = 1 vote), steep barriers to entry, plutocratic tendencies.
  • Corporate Collaboration Suites: Hierarchical, top-down permission models ill-suited for democratic, equal-voice civic coordination.

2. Universal, Model-Agnostic Operating Agreement

Tension Identified

The AI assistant initially considered creating internal agent memory structures. The project initiator intervened with a strict, fundamental requirement:

  1. No external writes: Memory must NEVER be placed outside the workspace (./).
  2. Volatile VM Resilience: Because cloud nodes are volatile and can be terminated at any moment, anything outside the repo is lost.
  3. Total Transparency: Every discussion, decision, and step must be auditable by any human or AI reviewer.
  4. Tool & Model Agnostic: The system cannot depend on Gemini-specific, Claude-specific, or OpenAI-specific proprietary conventions, nor on specific operating system paths (/home/...).

Resolution

  • Established AGENTS.md as the universal instruction file.
  • Created thin bridge files (GEMINI.md, CLAUDE.md, .cursorrules) that route all models directly to AGENTS.md.
  • Standardized on relative paths (./...).
  • Formalized the decision process via ADRs in docs/decisions/ (inaugurated by ADR-0001).
  • Established this deliberation journal to capture the reasoning and sparring dynamics for posterity.

3. Documentation Format, Public Evolution & Continuous Publishing

Question Raised

The project initiator explored whether to migrate file formats from Markdown (*.md) to AsciiDoc (*.adoc), whether .md could be transformed into professional documentation, and expressed a core requirement: make the incremental evolution of Swayrm publicly visible through a continuously published web site with an attractive, modern layout.

Deliberation & Trade-off Analysis

  • AsciiDoc (*.adoc):
    • Pros: Native file transclusion (include::[]), sophisticated callouts, rich enterprise publishing with Antora and Asciidoctor-PDF.
    • Cons: AI assistants (Gemini, Claude, GPT) are pre-trained predominantly on Markdown and exhibit minor syntax drift with complex AsciiDoc; ecosystem files (GEMINI.md, CLAUDE.md, AGENTS.md) must remain Markdown anyway.
  • Publishing Engine:
    • Astro Starlight: High flexibility and modern web stack, but forces heavy Node.js dependencies (package.json, lockfiles) into the repo root during early incubation.
    • Material for MkDocs: Standard in technical specifications; single YAML configuration (mkdocs.yml); zero JavaScript runtime in the repository; native search, responsive UI, dark/light themes, and git-based page timestamps.
  • Hosting Platform:
    • The repository is hosted on GitLab, allowing direct deployment to GitLab Pages via .gitlab-ci.yml using the official squidfunk/mkdocs-material Docker image and mkdocs-git-revision-date-localized-plugin.

Resolution

  • Retain Markdown (*.md) as the canonical source format across the repository.
  • Adopt Material for MkDocs configured via mkdocs.yml.
  • Automate continuous deployment to GitLab Pages via .gitlab-ci.yml on every commit to the default branch.
  • Formalize the decision in ADR-0002.

4. Open Sparring Questions for Next Sessions

  1. Decision Dynamics: Which decision models (Sociocratic consent, rough consensus, liquid democracy) form the core default for a newly created swarm?
  2. Topology: How do swarms federate? What does the local-vs-global hierarchy look like without central control?
  3. Identity & Trust: How do citizen groups prevent bot infiltration / Sybil attacks without requiring surveillance state KYC?