mojoakku

Imported from LukasLow/mojoakku (AGENTS.md). Install upstream with npx skills add LukasLow/mojoakku. Copyright stays with the author.

MojoAkku — Project Map

This file is a map, not a rulebook. It tells you where things live and where to go for the process. Detailed process steps live in .agents/workflows/.

What MojoAkku is

MojoAkku is a collection of independent Mojo libraries that live beside the official Mojo standard library. It focuses on sockets, TCP, HTTP and closely related layers, and is built agentically for a low-vision user — so APIs, naming and docs are designed to be predictable, consistent and easy to read.

Repository architecture

repo root/
  AGENTS.md
  README.md
  TODO.md
  LICENSE
  mojo.yml            <-- capability ledger: what Mojo 1.1.0 can and cannot do
  Taskfile.yml        <-- task commands, reads the .repo/todo/ catalogue
  .repo/todo/        <-- flat catalogue: one YAML file per planned library
  .repo/scrupts/     <-- maintenance scripts dispatched by Taskfiles
  docs/adr/           <-- architecture decision records
  .agents/workflows/*.md
  akku/               <-- public namespace (project/repository stays MojoAkku)
    net_socket/   <-- SIBLING library
    net_tcp/      <-- SIBLING library
    web_http/     <-- SIBLING library
    markup_html/  <-- SIBLING library
    format_json/  <-- SIBLING library
    ...
  akku_later/         <-- DEFERRED code, outside the test pool (not a library)
    net_socket/   <-- parked implementation; see its _dev/TODO.md handoff

Every library under akku/<lib>/ is a sibling. Libraries are never nested inside each other.

akku_later/<lib>/ parks a deferred implementation so it stops running in task test/ci (only akku/* is discovered) while its rebuild waits for dependencies. It is not a second akku/: nothing imports from it, and the live catalogue entry (.repo/todo/<lib>.yml) stays the source of truth. See .repo/todo/README.md.

Library naming: the domain prefix

The public import prefix is akku: from akku.codec_base64 import encode. Pass the repository root on the import path (mojo run -I . <consumer> from the root, or -I ../.. from akku/<lib>/). Keep the flat domain_local library names; do not split them into nested packages. There is no legacy namespace alias. Project branding, repository URLs and toolchain workspace identity stay MojoAkku. See docs/adr/0002-akku-public-namespace.md.

A flat namespace of 244 siblings stays readable only with a domain_local prefix joined by _ (never -, which would force backticks in imports): crypto_cipher, not cipher. Two segments are preferred, three the maximum; no filler segment (phy_cosmology, not math_func_cosmology).

covered_<x> marks a library already covered by std/MAX (never built, e.g. covered_simd); homeless_<x> marks one without a home yet (e.g. homeless_pdf). The decision record is docs/adr/0001-namespace-domains.md.

Capability ledger: mojo.yml and mojoNeeds:

mojo.yml records what Mojo 1.1.0 can (have), partly can (partial) or cannot (missing) do, each entry with a source. Every .repo/todo/<id>.yml declares mojoNeeds: — the capability keys it requires.

task todo applies the capability gate: a library is listed only when all three hold — status todo, every depends_on library done, and every mojoNeeds key state: have. "Buildable today" is therefore evidence-backed, not guessed. task todo -- --all (alias task todo-all) drops the capability filter and appends a reason per library, so planned-but-blocked entries stay visible.

Layout of one library

akku/<lib>/
  __init__.mojo      # package entry point + shared (whole-library) docs block; re-exports every public name
  <api_entry>.mojo   # ONE file per public API entry, name = API name lowercased
                     #   e.g. encode.mojo, padding_mode.mojo, base64_error.mojo
  _internal/         # private shared code — ONLY if there is genuinely shared code
  _tests/            # tests, one file per concern (no __init__.mojo)
  Taskfile.yml       # per-library test runner (task test)
  _dev/              # development folder: phase-1 research notes (one file per
                     # reference language), README.md (frozen run config),
                     # DESIGN.md (the design record) and TODO.md (the backlog)

There is no api/ directory, no API.mojo aggregator and no src/ directory. Documentation lives inline with the code between the markers # API-DOCS-START / # API-DOCS-END: the shared whole-library docs in __init__.mojo, and one seven-field docs block per API in that API's own file. The canonical reference is .agents/workflows/LibraryLayout.md.

Library independence rules

• Libraries MUST NOT be structurally nested. The directory tree stays flat under akku/.
• A library MAY depend on another library as a graph edge, e.g. web_http -> net_tcp -> net_socket.
• Every dependency edge must be technically justified and documented in the depending library's inline # API-DOCS shared block (__init__.mojo).
• Dependency edges MUST NOT determine directory nesting. A dependency is a conceptual edge, never a physical parent/child relationship.

Per-library backlog: _dev/TODO.md

Every library carries a backlog at akku/<lib>/_dev/TODO.md. It is the home for every API the research showed is theoretically possible in Mojo but which the current implementation did not ship — deferred entry points, later variants, ideas surfaced in _dev/<lang>.md / _dev/DESIGN.md that were consciously left out. The phase workflows keep it in sync (Phase 1 seeds it, Phase 3 classifies, Phase 4 reviews it, Phase 7 ensures it exists, Phase 11 records anything not shipped, Phase 13 audits it; CreatePR.md requires it).

Rules:

• The backlog is live, not a history. A finished item is removed from the file, never struck through and never marked done. An empty TODO.md is a valid and expected state — it means the library has no open, researched-but-unshipped ideas.
• Anything deferred must be recorded here, not only in prose inside DESIGN.md. If a Non-Goal, an Open Question or a "future addition" is a concrete API candidate, it belongs in TODO.md as one line.
• One line per candidate, kept short and readable for a low-vision user: the candidate name, a one-phrase meaning, and the research origin (e.g. rust.md §12). No implementation detail, no status bookkeeping.
• It is not end-user documentation and is never shipped; like the rest of _dev/, it stays in the repo as the developer record. The canonical format is defined in .agents/workflows/LibraryLayout.md.

Core process rules

• No implementation before research + API + scaffold + tests exist.
• The inline # API-DOCS blocks (__init__.mojo for the whole library, one block per API in that API's file) are the single source of truth for a library.
• Every API decision must be justified in the docs.
• The public API lives in one file per API entry directly under akku/<lib>/, never in a single API.mojo; private shared logic lives in akku/<lib>/_internal/ (only if genuinely shared); every public function carries its seven-field docs block next to it.
• Each library ships its own Taskfile.yml with a test task for its _tests/.
• The API design is approved by the user before the design review runs (NewLibPhase3Design.md, user review gate).
• Every workflow phase ends with a git commit naming the phase (and, for a review phase, its verdict), so each phase boundary is visible in history.
• One branch per library; never commit to main. All work for a library happens on a single long-lived branch whose name follows the convention: <libname>-library-new for a new library, <libname>-library-patch for a patch/improvement to an existing library (created at Phase 1 and checked out for every phase commit). main is never written directly. A library reaches main only through exactly one pull request per library, opened by CreatePR.md after Phase 13 passes, and merged only when CI on the PR is green. main-push.yml then auto-releases from .changes/new/. Consequence: a phase commit must be made on the library branch, and git push origin main from an agent is forbidden.
• CI uses task ci::smart for PRs and task ci::full for every main push. The root Taskfile discovers every akku/*/Taskfile.yml; no registration. A library's optional ci task includes its tests and extra checks; otherwise CI invokes test. Never run both hooks redundantly. Namespace, runner and MissingMojo checks remain mandatory. Release tags follow successful full CI. Smart selection scans Mojo imports and differences since that tag; native and Python code belongs to its library. See .repo/TESTING.md. PRs still require exactly one new .changes/new/ file.
• .changes/ drives the changelog and the tag. .changes/new/ holds pending change files (<date>-<slug>.md, category lines NEW, FIX, SECURITY, PERFORMANCE, BREAKING, DEPRECATED, INTERNAL, DOCS); CI moves released files to .changes/archive/<tag>/ (CI-only). Versions stay on 0.x.y and major is never bumped: NEW/BREAKING/DEPRECATED → minor, FIX/SECURITY/PERFORMANCE → patch, INTERNAL/DOCS → none (no tag; they fold into the next real release). .github/scripts/newversion.sh is the single source of this derivation; task changes:version previews it. See .changes/README.md.
• The Manager starts NO Manager.

Mojo knowledge: the buch tool

• Mojo facts MUST be looked up in the mojov1 buch — not researched from the internet and not recalled from memory.
• Tools: buch_search (find a page), buch_read (read buch/page or buch/page#section), buch_list (list buch and pages), buch_update (write a page).
• Goal: a Mojo research pass must no longer be necessary. mojov1 is the self-sufficient Mojo 1.x reference and the single lookup point for keywords, syntax, types, ownership/lifecycle, errors, interop, stdlib and tooling.
• Write access is allowed and wanted: any agent that finds an error, an outdated statement, a missing page or an improvable fact MUST fix it in mojov1 via buch_update instead of working around it. Improving the buch is part of normal work, not a special exception.
• Buch authoring constraints that updates must respect: content comes from the official Mojo 1.x documentation (never invented); where the official docs are silent or contradictory, write an explicit "Open question" marker rather than guessing; legacy pre-1.x spellings belong only in the versions/ change record, never as taught syntax; pages stay short and one topic per page; headings are anchors and therefore API — add a heading rather than renaming a used one.
• Location fact: mojov1 is a local (writable) buch under /Users/lukas/home/repos/buch-lib/.buch/mojov1.buch/; the same-named remote library entry is a read-only shadow.

Workflows

The process lives in .agents/workflows/. Start at the index: .agents/workflows/README.md.

• NewLibPhase1Research.md — research the problem space per language.
• NewLibPhase2ResearchReview.md — review the research output.
• NewLibPhase3Design.md — design the public API.
• NewLibPhase4DesignReview.md — review the API design.
• NewLibPhase5Docs.md — complete _dev/DESIGN.md (shared sections + one block per API entry).
• NewLibPhase6DocsReview.md — review the design document.
• NewLibPhase7Scaffold.md — create the library skeleton and materialise the design into inline end-user docs.
• NewLibPhase8ScaffoldReview.md — review the scaffold.
• NewLibPhase9Tests.md — write tests before implementation.
• NewLibPhase10TestsReview.md — review the tests.
• NewLibPhase11Implementation.md — implement against API, docs and tests.
• NewLibPhase12ImplementationReview.md — review the implementation.
• NewLibPhase13FinalReview.md — final review and sign-off.
• BugFix.md — fix a known bug with a test.
• BugInvestigation.md — root-cause an unclear failure.
• Refactor.md — restructure without changing behavior.
• DependencyReview.md — review and justify dependency edges.
• APIReview.md — review an API change.
• PerformanceInvestigation.md — investigate and fix performance.
• SecurityReview.md — security and hardening review.
• CreatePR.md — branch, .changes/ entry, push and open the pull request.
• Release.md — turn .changes/ into CHANGELOG.md and tag the release.

Toolchain and CI

• Mojo runs in the smd container (global mojo, version pinned by pixi.toml via smd.v0.6.toml). Use smd for commands; never bare bash.
• CI (.github/workflows/) runs task ci::full on main and task ci::smart on PR; on main it also auto-releases when .changes/new/ is non-empty (main-push.yml).
• Changes are recorded in .changes/ and drive the version tag; see .changes/README.md.