8000 M12.7, M12.8: modules and distros — build your own, plug into the kernel by adeelahmad · Pull Request #127 · adeelahmad/aloop · GitHub
[go: up one dir, main page]

Skip to content

M12.7, M12.8: modules 8000 and distros — build your own, plug into the kernel - #127

Merged
adeelahmad merged 2 commits into
masterfrom
claude/project-thread-zwxou3
Nov 20, 2026
Merged

adeelahmad merged 2 commits into
masterfrom
claude/project-thread-zwxou3

Conversation

@adeelahmad
@adeelahmad adeelahmad commented Nov 20, 2026 •
Copy link
Copy Markdown
Owner

Requested by Adeel · project thread

Stacked on #124 (merged). This adds the second half of ROADMAP §4.15, using the names the owner chose on 2026-11-20:

  • The host harness (Claude Code, Codex, OpenCode, dsh) is the hardware.
  • aloop is the kernel.
  • Modules plug into the kernel.
  • A distro is a domain's full user-space bundle.

aloop ships the means to build these, not a marketed one. Only the software distro (the TDD loop) ships.

Modules: aloop module new|add|remove|list|run|hook

A module lives in ~/.aloop/modules/<name>/ and contains:

  • module.json, whose on field takes SubagentStop, SubagentStop:<role> or Stop, plus command and timeout.
  • An executable check.

How it runs:

  • A project runs a module only after adding it. aloop module add pins the module's sha256 in docs/agents/userspace/distro.json, which is tracked in git.
  • module hook is wired in hooks.json beside the core gates on SubagentStop and Stop, so a core block stands whatever a module says.
  • The module's exit 2 blocks, with its stderr as the reason.
  • These also block: a module changed since it was added, a missing module, a crash, a timeout, and an unreadable distro.json.
  • Every run is logged as a module.run event, which only the hook can write.

Distros: aloop distro [use|new|check|install]

  • A distro is a folder: distro.json, modules/<name>/ and userspace/agents|skills/.
  • module new and distro new scaffold a working, commented example check.
  • distro check refuses a distro that adds a role. A distro can only re-shape existing roles.
  • distro install does four things: it copies the distro's modules, adds them, copies its roles while keeping the user's own edits, and sets the project's distro.
  • The how-to is docs/BUILD-A-MODULE.md ("Build your own module").

Evidence

  • scripts/test/modules.test.py: 34/34 pass. On master it fails because the module tool doesn't exist there.
  • These also pass: userspace 48/48, hook-matchers 15, codex-hooks 20, opencode-plugin, dsh-plugin, readme, check-tracking (121 requirements), shellcheck, pycheck.

Calls / gaps

  • SKIP_HOOKS=1 skips modules too. That's the same escape hatch every core gate honors.
  • Only hooks.json hosts run modules so far (Claude Code and Codex). OpenCode and dsh are M12.12.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FeZyj8vyFzFFNgfzxTSoBd

~/.aloop/kernel/<name>/ modules (extension.json: on SubagentStop[:role] | Stop, command,
timeout) add checks to the kernel. A project loads one only by pinning its sha256 in
docs/agents/userspace/profile.json (aloop kernel pin, in git). kernel hook runs beside the
core gates on SubagentStop and Stop, so a core block stands; exit 2 blocks with its reason;
a module changed since its pin, missing, crashing or timing out, or an unreadable profile,
blocks. Every run logs kernel.extension_run (gate-owned). aloop kernel profile names the
opinion set (software, the TDD loop, is the default).

Test: scripts/test/kernel-extensions.test.py (25 checks).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeZyj8vyFzFFNgfzxTSoBd
…ffolds and how-to

The host harness is the hardware, aloop is the kernel, modules plug into it, and a distro is
a domain's full user-space bundle. Renamed from kernel extensions / packs / profile:
  aloop module new|add|remove|list|run|hook   ~/.aloop/modules/<name>/module.json
  aloop distro [use|new|check|install]        docs/agents/userspace/distro.json
  event: module.run (gate-owned)
module new and distro new scaffold a working, commented example check; distro check refuses a
distro that adds a role; distro install copies and adds its modules, copies its roles keeping
the user's edits, and sets the distro. How-to: docs/BUILD-A-MODULE.md.

Test: scripts/test/modules.test.py (34 checks).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeZyj8vyFzFFNgfzxTSoBd
@adeelahmad adeelahmad changed the title M12.7, M12.8: kernel extensions (hash-pinned, add-only) and the profile M12.7, M12.8: modules and distros — build your own, plug into the kernel Nov 20, 2026
adeelahmad pushed a commit that referenced this pull request Nov 20, 2026
… branch

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeZyj8wdhHQDM35jZMC9kX
@adeelahmad
adeelahmad marked this pull request as ready for review November 20, 2026 02:37
@adeelahmad
adeelahmad merged commit fb015ee into master Nov 20, 2026
5 checks passed
adeelahmad pushed a commit that referenced this pull request Nov 20, 2026
…randing branch; the site links the merged how-to

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeZyj8wdhHQDM35jZMC9kX
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

0