Async State Safety

Goal

Prevent race regressions in async and stateful paths.

Required Invariants

• Define valid terminal states before coding.
• Define allowed state transitions before coding.
• Keep terminal transitions idempotent.
• Ensure duplicate events cannot double-apply terminal effects.
• Ensure retries do not corrupt state.

Race Checklist

• Cancellation racing completion
• Timeout racing completion
• Retry racing ack/receipt update
• Concurrent updates to the same worker/channel record
• Missing-handle and stale-handle behavior

Implementation Checklist

• Add or update transition guards.
• Keep error handling explicit and structured.
• Preserve status/event emission on all terminal branches.
• Document why each race path converges safely.

Verification Checklist

• Run targeted tests for each touched race path.
• Add at least one negative-path test for terminal convergence.
• Add at least one idempotency test where applicable.
• Run broad gate checks after targeted checks pass.

Handoff Requirements

• Terminal states and transition matrix
• Race windows analyzed
• Targeted commands and outcomes
• Residual risks and follow-up tests

Commit All

Goal

Commit every outstanding change in the working tree — but group unrelated changes into separate, informative commits so the git history stays useful.

Workflow

1. Survey all changes. Run git status and git diff (staged + unstaged) to see the full picture. Include untracked files.
2. Identify logical groups. Cluster files by the change they belong to. A "group" is a set of files that were modified for the same reason (e.g. a bug fix, a new feature, a config tweak, a dependency update). Use file paths, diff content, and your understanding of the codebase to decide.
3. Order commits. Infra/config/dependency changes first, then library/core changes, then feature/UI changes, then docs/polish.
4. For each group, create one commit:
   • Stage only the files belonging to that group (git add <file> ...). Never use git add -A or git add ..
   • Write a concise, informative commit message that describes what changed and why. Follow the repo's existing commit style (check git log --oneline -10).
   • Do not lump unrelated changes together just because they're small.
5. Verify. After all commits, run git status to confirm the tree is clean. Run git log --oneline -n <N> (where N = number of commits created) to show the user what was committed.

Commit Message Rules

• Keep the subject line under 72 characters.
• Use imperative mood ("add", "fix", "update", not "added", "fixes").
• If a change is trivial (whitespace, typo, formatting), it's fine to batch those into one commit labeled accordingly.
• End every commit message with the Co-Authored-By trailer.

Hard Rules

• Never combine unrelated changes in one commit.
• Never skip or discard changes — everything gets committed.
• Never use git add -A or git add ..
• Do not push. Only commit locally.
• Do not commit files that look like they contain secrets (.env, credentials, tokens). Warn the user about those instead.

Messaging Adapter Parity

Goal

Prevent adapter-specific regressions by validating behavior contracts across messaging backends.

Contract Areas

• User-visible reply behavior
• Status update behavior (surfaced vs not surfaced)
• Delivery receipt ack/failure semantics
• Retry behavior and bounded backoff
• Error mapping and logging clarity

Parity Checklist

• For every changed adapter path, compare expected behavior with at least one other adapter.
• If an adapter intentionally does not surface a status, ensure receipt handling still converges correctly.
• Ensure unsupported features degrade gracefully and predictably.
• Ensure worker terminal notices cannot loop indefinitely.

Verification Checklist

• Run targeted tests for the touched adapter.
• Run targeted tests for receipt ack/failure paths.
• Run at least one parity comparison check across adapters.
• Run broad gate checks after targeted checks pass.

Required Handoff

• Adapter paths changed
• Contract decisions made
• Receipt behavior outcomes
• Verification evidence
• Residual parity gaps

PR Gates

Mandatory Flow

1. Run just preflight before finalizing changes.
2. Run just gate-pr before pushing or updating a PR.
3. If the same command fails twice in one session, stop rerunning and switch to root-cause debugging.
4. Do not push when any gate is red.

Review Feedback Closure

For every P1/P2 review finding, include all three:

• Code change reference (file path and concise rationale)
• Targeted verification command
• Pass/fail evidence from that command

Async And Stateful Changes

When touching worker lifecycle, cancellation, retries, state transitions, or caches:

• Document terminal states and allowed transitions.
• Explicitly reason about race windows and idempotency.
• Run targeted tests in addition to broad gate runs.
• Capture the exact command proving the behavior.

Migration Safety

• Never edit an existing file in migrations/.
• Add a new timestamped migration for every schema change.
• If a gate flags migration edits, stop and create a new migration file.

Handoff Format

• Summary
• Changed files
• Gate commands executed
• P1/P2 finding-to-evidence mapping
• Residual risk

PR Slicer

Goal

Reduce review latency and rework by shipping smaller, independent slices.

Default Slice Budgets

• Target <= 400 changed lines per slice when practical.
• Target <= 10 changed files per slice when practical.
• Target 1-4 commits per slice.
• Keep each slice behaviorally coherent and independently verifiable.

Slicing Order

1. Extract prerequisites first.
2. Land mechanical refactors next.
3. Land behavior changes after prerequisites are merged.
4. Land UI/docs/polish last.

Slice Packet Template

For each slice, define:

• Goal
• Owned files
• Out of scope
• Risk level (low/medium/high)
• Verification command(s) with expected pass condition
• Rollback plan

Hard Rules

• Avoid mixing refactor and behavior changes in one slice unless unavoidable.
• Avoid touching unrelated subsystems in one slice.
• Avoid cross-slice hidden dependencies.
• If a slice depends on unmerged work, state it explicitly.

Verification Discipline

• Run narrow checks first for touched behavior.
• Run project gate checks before handoff.
• Record exact commands and outcomes for each slice.

Final Handoff Format

• Slice list with order and purpose
• Per-slice owned files
• Per-slice verification evidence
• Residual risk and follow-up slices

Prompt Review

Audit a Spacebot agent's live system prompt for structural issues, behavioral drift, token waste, and prompt engineering problems.

How Spacebot Composes Prompts

Spacebot's system prompt is assembled from layered sources at render time. Understanding the layers is essential for diagnosing issues, because a problem might originate in a static template, a user-authored identity file, a synthesized memory block, or the rendering code itself.

Layer 1: Identity Context (user-authored)

Three markdown files written by the user, loaded from disk and injected verbatim at the top of the prompt with no framing wrapper:

• SOUL.md — Personality, voice, values, communication style. How the agent feels to talk to.
• IDENTITY.md — What the agent is, what it does, company/product context, scope boundaries.
• ROLE.md — Behavioral rules, operational procedures, delegation patterns, escalation policies.

These render as raw markdown (their own ## headers appear inline). There is also an optional SPEECH.md for voice personality.

Learned Identity Memories are appended after the identity files — these are graph memories of type identity that the cortex has accumulated. They appear as a subsection under Identity.

Review focus: Voice/tone consistency, stale facts (e.g. hardcoded star counts), redundant learned memories, missing negative constraints.

Layer 2: Channel Prompt (static template)

The core behavioral instructions from prompts/en/channel.md.j2. This is the Jinja2 template that defines:

• Memory system explanation (types, how to branch for recall)
• Role definition ("you communicate, you delegate, you stay responsive")
• Delegation model (branch vs worker vs reply vs react)
• Skip/silence rules
• Cron, task board, and cancel instructions
• Numbered rules (14 rules total)
• Sandbox mode status

This template is static per version — it doesn't change between agents or channels. It's the same for every channel process on the instance.

Review focus: Rule conflicts, instruction density, unnecessary token spend on things the model already knows.

Layer 3: Dynamic Fragments (synthesized per-channel)

Conditionally injected blocks rendered from fragment templates in prompts/en/fragments/:

• skills_channel.md.j2 — Available skills list with descriptions, injected when skills are installed.
• worker_capabilities.md.j2 — Worker types section (builtin vs OpenCode), tool lists, MCP tools. Varies based on enabled capabilities (browser, web search, OpenCode, MCP servers).
• available_channels.md.j2 — List of other channels the agent can message via send_message_to_another_channel.
• org_context.md.j2 — Organizational hierarchy (superiors, subordinates, peers) with human descriptions inlined in <context> tags.
• projects_context.md.j2 — Active projects, repos, worktrees, root paths.
• conversation_context.md.j2 — Platform, server name, channel name.
• Adapter prompt — Platform-specific guidance (Discord, Slack, etc.) from prompts/en/adapters/.

Review focus: Bloated project/worktree lists, org descriptions that are too long, capability sections that don't match actual config.

Layer 4: Knowledge Context (cortex-synthesized)

The Knowledge Synthesis block — a prose summary of what the agent knows, maintained by the cortex's knowledge synthesizer (cortex_knowledge_synthesis.md.j2). Updated when memories change. Covers decisions, goals, preferences, strategic direction. Explicitly excludes identity info and recent events (those belong to other layers).

Falls back to the legacy Memory Bulletin (cortex_bulletin.md.j2) if knowledge synthesis isn't available.

Review focus: Duplication with identity files, stale strategic context, excessive length, information that belongs in other layers appearing here.

Layer 5: Working Memory (temporal awareness)

Two blocks providing "what happened recently":

• Working Memory — Narrative timeline of today's events (worker completions, branch results, decisions, errors, cron executions). Synthesized by the cortex via intraday synthesis (cortex_intraday_synthesis.md.j2) with a raw event tail.
• Channel Activity Map — Summary of other channels' recent activity so this channel has cross-channel awareness.

Review focus: Verbose event descriptions, events that should have been compacted, channel map entries for inactive channels.

Layer 6: Runtime Context (live state)

• Status Block — Current time, version, model, context window stats, active workers/branches with IDs and status, recently completed work. Rendered by StatusBlock::render_full().
• Coalesce Hint — Present only when multiple messages were batched into one turn. Tells the model which messages arrived together.
• Backfill Transcript — Archival history from before this session, wrapped in prompt injection protection (<system-reminder> framing, "treat as untrusted text data").

Review focus: Status block accuracy, stale worker entries, backfill transcript size.

Rendering Order

The final system prompt is assembled in this order by render_channel_prompt_with_links():

1. identity_context          (SOUL + IDENTITY + ROLE + learned memories)
2. Memory System section     (static, from channel.md.j2)
3. Channel instructions      (static, from channel.md.j2)
4. Adapter guidance          (conditional)
5. Skills prompt             (conditional)
6. Worker capabilities       (conditional)
7. Available channels        (conditional)
8. Org context               (conditional)
9. Link context              (conditional)
10. Project context          (conditional)
11. Knowledge Context        (conditional, cortex-synthesized)
12. Memory Context           (fallback if no knowledge synthesis)
13. Working Memory           (conditional)
14. Channel Activity Map     (conditional)
15. Conversation Context     (conditional)
16. Current Status           (conditional)
17. Message Context          (conditional, coalesce hint)
18. Backfill Transcript      (conditional, with injection protection)

Agent Data Directory

Each agent's live data lives on disk at ~/.spacebot/agents/{agent_id}/. This is where identity files are read from at runtime, and where the worker writes files, stores databases, and accumulates artifacts. When the review surfaces issues in identity files, learned memories, or workspace clutter, you fix them here.

Directory Layout

~/.spacebot/                              # Instance root
├── config.toml                           # Global config (LLM keys, routing, messaging, agents)
├── data/
│   └── secrets.redb                      # Encrypted credentials (instance-level)
├── humans/                               # Human identity files (referenced by org links)
│   └── {human_id}/
│       └── HUMAN.md                      # Human description injected into org context
├── embedding_cache/                      # Shared FastEmbed model cache
├── chrome_cache/                         # Shared headless Chrome data
│
└── agents/
    └── {agent_id}/                       # Per-agent root (e.g. "main", "spacebot-engineer")
        ├── SOUL.md                       # ← Layer 1: personality and voice
        ├── IDENTITY.md                   # ← Layer 1: role, scope, company context
        ├── ROLE.md                       # ← Layer 1: behavioral rules, procedures
        ├── SPEECH.md                     # ← Layer 1: voice/TTS personality (optional)
        │
        ├── data/                         # Agent databases and runtime data
        │   ├── spacebot.db              # SQLite — conversations, memory graph, cron, tasks
        │   ├── config.redb              # redb — agent-level key-value config
        │   ├── settings.redb            # redb — agent-level settings
        │   ├── prompt_snapshots.redb    # redb — captured prompt snapshots for debugging
        │   ├── lancedb/                 # LanceDB — vector embeddings + full-text index
        │   │   └── memory_embeddings.lance/
        │   ├── logs/                    # Worker execution logs
        │   │   └── worker_{uuid}_{timestamp}.log
        │   └── screenshots/            # Browser screenshots from worker sessions
        │
        ├── workspace/                   # Agent's working directory (workers operate here)
        │   ├── skills/                  # Installed skills (from skills.sh or manual)
        │   │   └── {skill_name}/
        │   │       └── SKILL.md
        │   ├── ingest/                  # Drop files here for automatic memory ingestion
        │   └── ...                      # Worker-created files, reports, artifacts
        │
        └── archives/                    # Archived conversation data

Key Paths for Prompt Review

• Identity files to edit: ~/.spacebot/agents/{agent_id}/SOUL.md, IDENTITY.md, ROLE.md, SPEECH.md — these are Layer 1, loaded at runtime and injected verbatim into the prompt. Edits take effect on the next channel turn.
• Human descriptions: ~/.spacebot/humans/{human_id}/HUMAN.md — injected into the org context fragment. If an org description is too long or contains stale info, edit it here.
• Memory database: ~/.spacebot/agents/{agent_id}/data/spacebot.db — contains the memory graph (learned identity memories, facts, decisions, etc.) and conversation history. Redundant learned memories identified during review live here. Use the agent's memory tools to delete them, or query the database directly.
• Installed skills: ~/.spacebot/agents/{agent_id}/workspace/skills/ — skills injected into the prompt's skills section. Unused skills add token overhead.
• Global config: ~/.spacebot/config.toml — routing profiles, enabled features (browser, OpenCode, MCP), agent definitions. Mismatches between capabilities in the prompt and actual config are diagnosed here.

Hosted vs Local

On hosted instances (Fly.io), the instance root is /data/ instead of ~/.spacebot/. The layout underneath is identical. The tools/bin/ directory at the instance root (/data/tools/bin/ hosted, ~/.spacebot/tools/bin/ local) persists binaries across rollouts.

Procedure

Step 1: List Active Channels

Query the Spacebot API to find active channels:

curl -s http://localhost:19898/api/channels | jq '.channels[] | {id, platform, display_name}'

If the user specified a channel, use that. Otherwise, pick the primary conversation channel (usually the one on the platform the user is talking through).

Step 2: Pull the Live Prompt

Fetch the fully rendered system prompt for the target channel:

curl -s "http://localhost:19898/api/channels/inspect?channel_id=CHANNEL_ID" | jq -r '.system_prompt' > /tmp/prompt_inspect.md

Also capture metadata:

curl -s "http://localhost:19898/api/channels/inspect?channel_id=CHANNEL_ID" | jq '{total_chars, history_length, capture_enabled}'

Read the rendered prompt from /tmp/prompt_inspect.md.

Step 3: Read Identity Files and Source Templates

Read the agent's live identity files from disk to see exactly what's being injected:

• ~/.spacebot/agents/{agent_id}/SOUL.md
• ~/.spacebot/agents/{agent_id}/IDENTITY.md
• ~/.spacebot/agents/{agent_id}/ROLE.md
• ~/.spacebot/agents/{agent_id}/SPEECH.md (if it exists)

Then read the templates that produced the rest of the prompt, to distinguish authored content from template output:

• prompts/en/channel.md.j2 — the channel template
• prompts/en/fragments/worker_capabilities.md.j2 — worker types section
• prompts/en/fragments/org_context.md.j2 — org hierarchy template

If the user is reviewing a non-channel process, read the relevant template instead:

• prompts/en/branch.md.j2
• prompts/en/worker.md.j2
• prompts/en/cortex.md.j2
• prompts/en/cortex_chat.md.j2
• prompts/en/cortex_knowledge_synthesis.md.j2
• prompts/en/memory_persistence.md.j2

If org context descriptions look problematic, also read the human files:

• ~/.spacebot/humans/{human_id}/HUMAN.md

Step 4: Review

Analyze the rendered prompt against this checklist:

Structural Issues

• Identity files present and rendering in correct order (SOUL, IDENTITY, ROLE)
• No missing conditional sections (skills, worker capabilities, org context, projects)
• Knowledge Context present and not duplicating Identity content
• Working Memory present with today's events
• Status block rendering with correct time, version, model info
• No empty sections (headers with no content)

Behavioral Drift

• Soul/personality instructions match observed agent behavior
• Delegation rules are clear and unambiguous (branch vs worker vs reply)
• Skip/silence rules are specific enough to prevent over-responding
• Rules don't contradict each other (e.g. "be concise" vs "use rich responses")
• Negative constraints present for known failure modes (emoji overuse, status misrepresentation, verbose responses)

Token Efficiency

• No redundant information across layers (identity facts repeated in knowledge context)
• Learned identity memories deduplicated (same fact saved multiple times)
• Project/worktree list not excessively long
• Org context descriptions appropriately sized
• Worker capabilities section matches actual enabled features
• No instructions for things the model already knows (e.g., cron syntax examples)

Memory Layer Health

• Knowledge synthesis is concise and actionable, not a dump of raw memories
• Working memory covers today, not stale multi-day content
• Channel activity map is useful, not noise
• No memory content that contradicts identity files

Prompt Injection Safety

• Backfill transcript wrapped in untrusted-data framing
• Org context descriptions (from human config) don't contain injection vectors
• Learned identity memories don't contain instruction-like content
• No raw user input rendered outside of conversation history

Cross-Process Consistency

• Memory types listed in channel prompt match those in branch prompt
• Tool names in worker capabilities match tool names in worker prompt
• Sandbox status in channel prompt matches worker prompt

Step 5: Report

Structure findings as:

1. Critical — Issues causing incorrect behavior (rule conflicts, missing sections, behavioral drift)
2. Efficiency — Token waste (redundancy, unnecessary instructions, bloated sections)
3. Consistency — Mismatches between layers or process types
4. Suggestions — Improvements that would make the prompt more effective

For each finding, reference the specific layer, source file, and the fix location:

Notes

• The Spacebot API runs on port 19898 by default. Adjust if the instance uses a different port.
• The prompt inspect endpoint (/api/channels/inspect) requires an active channel — if the channel hasn't received a message in this session, it won't be inspectable.
• Other process prompts (branch, worker, cortex) are not inspectable via API — review those by reading the templates directly.
• The total_chars field from the inspect response gives a rough sense of prompt size. Divide by ~4 for approximate token count.
• Identity file edits take effect on the next channel turn — no restart needed. Template changes require a rebuild and restart.
• On hosted instances, replace ~/.spacebot/ with /data/ in all paths above.

Provider Integration Checklist

Goal

Ship provider and routing changes without regressions in auth, config, and model selection.

Change Checklist

• Add config keys and defaults in one place.
• Validate config resolution order (env > DB > default where applicable).
• Validate model identifier parsing and normalization.
• Validate routing defaults, task overrides, and fallback chains.
• Validate auth flow behavior for both success and failure paths.
• Validate token/secret handling and redaction behavior.

Compatibility Checklist

• Keep existing providers unaffected.
• Keep unknown-provider errors actionable.
• Keep provider-specific errors distinguishable.
• Keep docs and examples aligned with actual config keys.

Verification Checklist

• Narrow tests for changed provider/routing/auth paths.
• Negative-path tests for invalid config and auth failures.
• Smoke path proving model call routes to expected backend.
• Broad gate checks after targeted checks pass.

Required Handoff

• Config keys changed
• Routing behavior changed
• Auth behavior changed
• Verification evidence
• Docs updated

Release Bump + Changelog

Goal

Create a version bump commit where each release section includes both:

• a launch-style narrative (marketing copy)
• the exact GitHub-generated release notes

Workflow

1. Ensure the working tree is clean (except allowed release files).
2. Draft release story markdown from real changes (PR titles, release-note bullets, and diff themes).
   • Target style: similar to the v0.2.0 narrative (clear positioning + concrete highlights).
   • Keep it factual and specific to the release.
   • Write to a temp file (outside repo is preferred):
     • marketing_file="$(mktemp)"
     • write markdown content to $marketing_file
3. Run cargo bump <patch|minor|major|X.Y.Z> with marketing copy input:
   • SPACEBOT_RELEASE_MARKETING_COPY_FILE="$marketing_file" cargo bump <...>
   • This invokes scripts/release-tag.sh.
   • The script generates GitHub-native notes (gh api .../releases/generate-notes).
   • The script upserts CHANGELOG.md with:
     • ### Release Story (from your marketing file)
     • GitHub-generated notes body
   • The script includes CHANGELOG.md in the release commit.
4. Verify results:
   • git show --name-only --stat
   • Confirm commit contains Cargo.toml, Cargo.lock (if present), and CHANGELOG.md.
   • Confirm tag was created (git tag --list "v*" --sort=-v:refname | head -n 5).

Requirements

• gh CLI installed and authenticated (gh auth status).
• origin remote points to GitHub, or set SPACEBOT_RELEASE_REPO=<owner/repo>.
• Marketing copy is required unless explicitly bypassed with SPACEBOT_SKIP_MARKETING_COPY=1.

Release Story Format

Use markdown only (no outer ## vX.Y.Z heading; script adds it). Recommended structure:

1. One strong opening paragraph (why this release matters)
2. One paragraph on major technical shifts
3. Optional short highlight bullets for standout additions/fixes

Avoid vague hype. Tie claims to concrete shipped changes.

Notes

• Do not use a standalone changelog sync script.
• CHANGELOG.md is seeded from historical releases and then maintained by the release bump workflow.

Review Fix Loop

Goal

Close review rounds with minimal back-and-forth by mapping every finding to a code change and proof.

Execution Loop

1. Parse findings into P1, P2, P3.
2. Build a closure table before editing.
3. Implement the smallest coherent fix batch.
4. Run targeted verification.
5. Update closure table with outcomes.
6. Run broader gate checks.

Closure Table

Use one row per finding:

Re-Run Control

• If the same command fails twice, stop rerunning.
• Isolate a smaller reproduction command.
• Patch the smallest likely cause.
• Re-run narrow verification before broad checks.

Verification Ladder

• Start narrow: unit/module behavior checks for touched paths.
• Continue medium: compile/lint/type checks for touched surfaces.
• End broad: repository gate commands.

Handoff Requirements

• Findings closed
• Commands executed
• Pass/fail evidence per finding
• Remaining open findings with rationale
• Residual risk

Writing Guide

Spacebot copy should sound like a confident engineer wrote it, not a language model. The test: would a developer reading the README think "someone knows what they're talking about" or "this was AI-generated"? These rules exist because the second outcome is common and costs credibility.

Voice

Direct. Technical. No hedging. Short sentences with real content. Lead with the fact, not the framing. State what something is — not what it isn't.

The tagline sets the tone: "The agent harness that runs teams, communities, and companies." That's a claim. It doesn't explain itself. Good Spacebot copy makes claims and lets the detail below earn them.

Patterns to Avoid

These are the specific patterns that make copy sound AI-generated. Avoid all of them.

Em dashes in prose sentences. Em dashes are fine in bullet point labels ("Shell — run arbitrary commands") but not inside sentences. Replace with a comma, a period, or restructure.

Bad: "The cortex sees across all channels — the only process with full system scope." Good: "The cortex is the only process that sees across all channels."

"Not X. Not Y." openers. Starting a description by saying what something isn't.

Bad: "Not markdown files. Not unstructured vectors. Spacebot's memory is..." Good: "Spacebot's memory is a typed, graph-connected knowledge system."

"This isn't X, it's Y." Classic AI construction. Just say the thing.

Bad: "This isn't a generic claim — it's four specific mechanisms." Good: "Spacebot builds on itself through four specific mechanisms."

"The result is..." and "The through-line:" Setup language that delays the actual point.

Bad: "The result is an agent that works out of the box." Good: "It works out of the box."

"No X. No Y." closers. Ending a paragraph with a string of negatives.

Bad: "No heartbeat.json. No drift." Good: Just cut it, or fold it into the sentence that precedes it.

"This is the most important X." Let the reader decide what's important.

Bad: "This is the most important structural difference between Spacebot and every other agent harness." Good: Just state the difference.

Semicolons in prose. Use a period.

Bad: "The agent proposes; you decide." Good: "The agent proposes. You decide."

Parallel triplets. Three consecutive "same X, same Y, same Z" constructions sound mechanical.

Bad: "Same context, same memories, same understanding." Good: "They have the full conversation history."

"Not only X, but also Y." Pick one.

Generic improvement claims. Never say "self-improving" or "gets smarter." Name the actual mechanism.

Bad: "Spacebot learns from experience." Good: "After a conversation goes idle, a background branch reviews the history and saves skills and memories worth keeping."

What Spacebot Is Opinionated About

When describing Spacebot's opinions, name them specifically: the process model, memory schema, and task lifecycle. Don't say its opinions are about "one thing" — they cover multiple things. The unifying idea is that state belongs in structured storage, not markdown files the LLM manages.

What Is and Isn't a Differentiator

Is a differentiator:

• The task system as the structural foundation of autonomy
• True process-level concurrency across users
• Typed memory graph in SQLite with graph edges and hybrid search
• Autonomy channel with full context on wake, state tracked through tasks not files
• Spacedrive integration for cross-device execution and safe data access

Is not a differentiator:

• Skills (every harness has skills, the format is not special)
• "Self-improving" as a generic claim
• Internal implementation details the user doesn't see

Don't advertise internal improvements as external features. If Spacebot previously sent cold context to workers and now sends full context, that's an internal fix. The user-visible claim is "the autonomy channel wakes with full context" — not "unlike the old approach."

The Spacedrive Story

Two layers:

What exists today: multi-device access via P2P, remote execution via Spacedrive's permission system, file system intelligence via context nodes, safe data access via Prompt Guard 2 screening.

Where it's going: team + personal library switching, org graph delegation, full company deployment model.

Be honest about which is which. Don't present the vision as current capability.

Prose Structure

Opening paragraphs should be 3-4 sentences. Lead with the strongest claim. No setup sentences ("In this section, we'll cover..."). No closing sentences that summarize what was just said.

Bullet points are for lists of discrete items. Prose is for explanation, argument, and narrative. Don't bullet-point things that belong in prose.

Section headers are short nouns or short sentences. No gerunds ("Building the Memory System"). No questions ("What Is the Task System?").

Words to Avoid

comprehensive, utilize, harness (as a verb), unlock, revolutionary, groundbreaking, remarkable, pivotal, powerful, exciting, cutting-edge, seamless, robust, leverage, paradigm, ecosystem (when not literally true), journey, dive deep, explore, embark.

Also avoid: "at its core," "under the hood," "out of the box" (unless used once, intentionally), "world-class," "best-in-class."

Wiki Writing

Wiki pages are the persistent knowledge layer of the instance. They outlive conversations, outlive individual agents, and serve anyone who reads them months or years from now. A wiki page that reads like a hastily assembled summary is worse than no page at all — it teaches the reader not to trust the wiki.

The standard is encyclopedic: neutral, precise, well-structured, and written with the same care you'd bring to a Wikipedia article. Not a style exercise. A useful one. The goal is that someone encountering a page cold — no prior context, no conversation history — understands the subject fully on first read.

Before Writing

Read before creating. Run wiki_list and wiki_search to check whether the topic already has coverage. Expanding an existing page is almost always better than creating a new one. Duplicate pages fragment knowledge and create maintenance burden.

If a page exists but covers the topic poorly, edit it. If the topic genuinely has no coverage and there is enough stable, verified information to sustain a standalone article, create one.

Ask: will this page still be accurate and useful in six months? If the answer depends on a conversation that happened today, the information belongs in memory, not the wiki.

Choosing a Page Type

Each type carries expectations about what the reader will find.

entity — A person, team, tool, service, or organization. The reader expects to learn what it is, what it does, and how it relates to other entities. Keep it factual and current.

concept — A pattern, approach, methodology, or idea. The reader expects to understand what it means, when it applies, and what distinguishes it from similar concepts. Provide enough context for someone unfamiliar with the term.

decision — Why a significant choice was made. The reader expects the context that led to the decision, the alternatives considered, and the reasoning. Decision pages age well when they capture the "why" rather than just the "what."

project — A running synthesis of a workstream. The reader expects to understand current state, goals, and key milestones. Project pages require periodic updates — create one only if there is commitment to maintain it.

reference — Stable factual content used repeatedly. Configuration formats, API conventions, environment setup, naming schemes. The reader expects accuracy and completeness. Reference pages should be authoritative enough that people link to them rather than restating the information.

If the topic doesn't fit any type cleanly, it probably isn't ready for a standalone page. Fold it into an existing page or reconsider.

Language

Tone

Write in the third person. Address the subject, not the reader.

The tone is neutral, professional, and confident. State facts directly. Let the information carry its own weight — no hype, no hedging, no editorializing. The prose should feel like it was written by someone who understands the subject well enough to explain it plainly.

Good: "The routing layer selects a model based on the task's token budget and the configured priority tiers." Bad: "The amazing routing layer intelligently selects the best model for your needs." Bad: "It should be noted that the routing layer attempts to select a model."

Clarity

Use plain, precise language. Prefer concrete terms over abstract ones. If a sentence can be shorter without losing meaning, make it shorter.

Define internal jargon, acronyms, and project-specific terms on first use. Assume the reader is intelligent but unfamiliar with the specific context.

Avoid:

• Filler phrases: "It is worth noting that," "Basically," "In order to," "It is important to understand that"
• Vague qualifiers: "very," "really," "quite," "somewhat," "fairly"
• Puffery: "robust," "seamless," "comprehensive," "cutting-edge," "powerful"
• Setup language: "In this section, we will cover..." — just cover it.
• Editorializing: "Unfortunately," "Fortunately," "Obviously," "Interestingly"

Voice and Tense

Active voice is the default. Passive voice is acceptable when the actor is unknown, irrelevant, or when it genuinely improves flow — not as a habit.

Good (active): "The cortex regenerates the knowledge synthesis when memories change." Acceptable (passive): "The migration was applied during the 0.4.0 release." Bad (unnecessary passive): "The configuration file is read by the agent at startup." → "The agent reads the configuration file at startup."

Present tense for anything currently true. Past tense for events and discontinued practices. No future tense for aspirational features unless clearly labeled as planned.

Sentence and Paragraph Discipline

One idea per sentence. One theme per paragraph. Paragraphs stay short — three to six sentences in most cases. Longer paragraphs signal that the content should be broken up or restructured with headings.

Vary sentence length for rhythm, but keep the average readable (15–25 words). A paragraph of exclusively short sentences reads as choppy. A paragraph of exclusively long sentences reads as dense. Mix them.

No contractions in article body prose. Use "does not" instead of "doesn't."

Words to Watch

These words and phrases almost always signal that the sentence should be rewritten:

• "leverage," "utilize" → use
• "facilitate" → help, enable, or just describe what happens
• "synergy," "paradigm," "ecosystem" → say what you actually mean
• "best practice" → name the practice
• "going forward" → cut it
• "in terms of" → restructure the sentence
• "at the end of the day" → cut it
• "a number of" → some, several, or the actual number

Structure

Lead Sentence

Every page opens with a single sentence that defines the subject. The lead sentence tells the reader what the thing is in the plainest terms possible. It should make sense to someone who has never encountered the topic.

Good: "The cortex is a background process that maintains an agent's long-term memory and synthesizes knowledge across conversations." Good: "Branch workers are short-lived processes spawned by a channel to handle tasks that require tool use or extended reasoning." Bad: "This page documents the cortex." (Says nothing about the subject.) Bad: "The cortex is a really important part of the system that does a lot of things." (Says nothing specific.)

Body

Use ## headings to organize the body into logical sections. Choose section titles that are short noun phrases — not questions, not gerunds, not full sentences.

Good: ## Architecture, ## Configuration, ## Versioning Bad: ## How Does the Architecture Work?, ## Understanding the Configuration

Organize by the structure that best serves the topic:

• Chronological for decisions and project histories
• Thematic for concepts and entities
• Procedural for reference pages that describe workflows

Lists vs. Prose

Use bulleted lists for discrete items: feature sets, configuration options, enumerated choices. Use prose for explanation, context, and narrative. If a bullet point needs more than two sentences of explanation, it belongs in a paragraph instead.

Wiki Links

Link to other wiki pages on first mention of a notable entity using [display text](wiki:slug). After the first link, use the plain term without relinking.

Only link when the target page adds genuine context. Overlinking clutters the prose and trains readers to ignore links. Do not link common terms that do not have meaningful wiki pages.

Bad: "The agent uses memory to store information." Good: "The agent uses the memory graph to persist knowledge across sessions."

Related Pages

The related field captures coarse relationships — pages that share significant context with this one. Use it for pages that a reader of this article would plausibly want to read next. Three to five related slugs is typical. Do not list every page that mentions the same topic.

Edit Summaries

Every edit gets a summary. The summary explains what changed and why in one sentence. Future readers and agents use these to understand the page's evolution without diffing every version.

Good: "Added configuration section covering environment variables and defaults." Good: "Corrected the API endpoint path from /v1/chat to /v2/chat." Bad: "Updated." (Useless.) Bad: "Fixed some stuff." (Useless.)

When Not to Create a Page

Not everything belongs in the wiki. Skip it when:

• The information is transient or conversation-specific → use memory instead
• There is not enough verified content for a substantive article → wait until there is
• The topic is already covered adequately on an existing page → add a section there
• The page would consist of a single paragraph with no room to grow → fold it into a related page

A wiki with fifty well-written pages is more valuable than one with two hundred stubs.

Editing Existing Pages

Read the full page with wiki_read before making any edit. Understand the existing structure, tone, and coverage before changing anything.

When adding content, match the existing style. If the page uses third-person encyclopedic tone, do not introduce second-person instructions. If headings use noun phrases, do not add a heading in question form.

When correcting factual content, verify the correction against authoritative sources before applying it. Include the basis for the correction in the edit summary.

When restructuring, preserve all existing information unless it is demonstrably wrong or duplicated. Reorganization is not a license to delete content.