Skip to content

The aispec format

aispec is a terse, fact-dense documentation format designed for AI consumption rather than human readability. Files use the .aispec extension and prioritize structured factual density over explanatory prose so that an AI assistant can ingest a system's essential knowledge in a single read.

This repo (sw2102-docs) does not use the aispec format — Markdown is the source of truth here, and conventions optimize for human readability first. This page exists for two reasons:

  1. The legacy Sectorwars2102/DOCS/SPECS/ directory contains a set of .aispec files that future contributors and AI tools may encounter. They should know what they are looking at.
  2. If we ever decide to publish AI-only companion docs alongside the Markdown, the format conventions are recorded here so we don't have to reverse-engineer them.

For the actual contribution conventions in this repo (Markdown, status markers, voice, frontmatter), see CONTRIBUTING.md.

What an aispec is

  • Designed for machine consumption, not human readability.
  • Minimalist wording with strong hierarchical organization.
  • Facts are presented as bullet points with * prefix for rapid ingestion.
  • No redundant explanations or pedagogical elements.
  • Includes information that would otherwise require exploring multiple source files to discover.
  • Focuses on relationships between components rather than implementation details.

Standard sections

The canonical structure (per Sectorwars2102/DOCS/SPECS/AISpecificationDoc.aispec) uses these top-level section headers, written in ALL CAPS followed by a colon:

Section Purpose
OVERVIEW: 2–3 sentence summary of the topic.
FACTS: Bullet list (* prefix) of key facts about the system.
TERMINOLOGY: Domain-specific vocabulary defined inline.
FILES: Source files relevant to the topic, with paths (and optionally line ranges, e.g. /models.py:7-26).
SCHEMA: Database structure if applicable (table.column: type, constraints).
CONSTRAINTS: Limitations, guard rails, things the AI should not suggest.
EXAMPLES: Actual usage patterns or representative snippets.

Domain-specific spec files extend this with custom ALL-CAPS sections as needed (for example, Ships.aispec has EQUIPMENT_CAPACITY: and SHIP_STATS:; Ranking.aispec has ENLISTED_RANKS:, NCO_RANKS:, WARRANT_RANKS:, etc.). The convention is: one ALL-CAPS heading per logical block, with structured key/value content beneath.

Beyond the standard sections, observed patterns in the legacy spec set include ENDPOINTS: (for API specs), nested key/value blocks for catalog-style data (ranks, ships, equipment), and Mermaid code blocks for knowledge graphs.

Style conventions

  • * for facts — every bullet under FACTS: starts with *.
  • - for file trees — FILES: may use a tree-style listing with -/└──/├──.
  • No prose paragraphs outside OVERVIEW:. Everything else is bullets, key/value pairs, or tables.
  • Strong assertion, no hedging. "Session timeout is 24 hours" — not "Session timeout is generally around 24 hours".
  • One concept per line wherever the format allows.

Authoring constraints (from the meta-spec)

  • AI should not modify aispec files without explicit permission.
  • Information in aispec files should be treated as authoritative within its scope.
  • When aispec and code diverge, prefer code as source of truth.
  • Do not describe aispec files to end users as "documentation" — they are AI knowledge artifacts.

Where the canonical spec lives

The format-defining meta-spec is:

Sectorwars2102/DOCS/SPECS/AISpecificationDoc.aispec

That file is the authoritative reference. If anything on this page conflicts with that file, that file wins.

Legacy aispec inventory

The following .aispec files exist in Sectorwars2102/DOCS/SPECS/:

  • AISpecificationDoc.aispec — the format meta-spec itself.
  • Architecture.aispec
  • AuthSystem.aispec
  • Database.aispec
  • GameConcepts.aispec
  • GameMechanics.aispec
  • GameServer.aispec
  • Ranking.aispec
  • Resources.aispec
  • Ships.aispec
  • WebSocket.aispec

These were not migrated into sw2102-docs/. The equivalent design intent has been re-expressed in Markdown across FEATURES/, SYSTEMS/, ARCHITECTURE/, DATA_MODELS/, and OPERATIONS/. The .aispec files remain in the source repo as a snapshot of how that information used to be packaged for AI consumption.

This repo's stance

Markdown is the source of truth. The conventions in CONTRIBUTING.md — prescriptive voice, inline status markers in FEATURES/, repo-relative cross-links, phase tags — apply. New documentation should be written as Markdown, not aispec. If a future need arises for AI-optimized companion artifacts, they would be generated from the Markdown rather than authored in parallel.