Open kb extension#8
Draft
arniwesth wants to merge 2 commits into
Draft
Conversation
Merged
6 tasks
sunholo-voight-kampff
added a commit
to sunholo-data/ailang
that referenced
this pull request
May 9, 2026
Concise 7-step walkthrough for third-party contributors building a new
motoko extension. Uses OpenKB (a knowledge-base lookup tool) as the
running example.
Pairs with the existing extension-packages.md reference (Diátaxis split:
that doc is reference, this is tutorial). Each step has a concrete file
example, a verify command, and explains the "why" alongside the "what".
Includes a "Common pitfalls" table covering the four mistakes that wreck
most first attempts:
1. Putting the extension inside motoko_agent/src/core/ext/ instead of
ailang-packages/packages/motoko-ext-foo/
2. Naming it motoko_foo (no _ext_) → ugly registry dispatch key
3. Hand-editing src/core/ext/registry_generated.ail (gets clobbered
on next ailang generate-extension-registry)
4. Leaving path = "../..." in the host ailang.toml (lockfile bakes in
absolute path; PR/CI clones break)
These are the exact failure modes seen in:
- arniwesth/motoko_agent#8 (OpenKB experiment, labeled "do not merge")
- PR #6 review feedback that surfaced the path-vs-registry issue
Refs: arniwesth/motoko_agent#8 (the test case for this tutorial)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Contributor
|
@arniwesth Saw your "do not merge / experimental" label and the note that this was a failed experiment — that's actually really useful test data. I treated it as an onboarding failure-mode survey for the extension system and wrote up a concise tutorial that addresses each thing this PR hit: 📘 Build Your First motoko Extension — 7 steps, ~260 lines, OpenKB as the running example. The "Common pitfalls" table at the end calls out four mistakes I saw in #8:
Each is genuinely easy to hit on first attempt — the tutorial is structured to make them obvious before you write the wrong thing. If you want to revive OpenKB as a real extension, the path is:
Happy to leave this PR open as a reference for the failure modes, or you can close it. Either way the work isn't lost — you can cherry-pick the actual logic in Also worth noting: this tutorial is now part of the AILANG docs (deployed as part of |
sunholo-voight-kampff
added a commit
to sunholo-data/ailang
that referenced
this pull request
May 9, 2026
…scaffolder Surfaced today (2026-05-09) when reviewing arniwesth/motoko_agent#8 — the "failed experiment" PR exhibits 4 structural mistakes that any AI agent or new contributor following our docs would make: 1. Extension placed inside motoko_agent/src/core/ext/ vs separate package 2. Package name missing the _ext_ infix → ugly registry short-name 3. Hand-edited registry.ail (gets clobbered by generate-extension-registry) 4. path = "../.." circular dep in package's own ailang.toml All four are documented as wrong in our docs. Nothing structurally prevents them. Tier 1 (this design): hardcoded `ailang init motoko-extension` type that scaffolds the canonical 4-file shape. ~3-4h Go work; ~150 LOC + tests. Tier 2 (deferred to separate sprint): generic [extension_template] block in host packages so any host can declare its own scaffold template. Critical motivation is axiom A7 (Machines First). Today an AI agent must ingest ~30,000 tokens of doc context to scaffold one extension; post-fix ~500 tokens. ~60× token reduction per extension creation. The value scales with each AI-driven extension authored. Design includes: - Axiom score +7 (A7 +3 alone justifies; no hard violations) - High-impact decisions table with 5 frozen choices - Phased plan (3 phases, ~3-4h total) - Conflict surface (none — pure CLI scaffolding, additive command type) - Snapshot tests + lock+check verification of generated package Refs: arniwesth/motoko_agent#8 (the failure case), M-AILANG-EXT-REGISTRY-GEN (v0.17.1, complementary feature) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
sunholo-voight-kampff
added a commit
to sunholo-data/ailang
that referenced
this pull request
May 9, 2026
…affolder Closes the AI-driven extension authoring gap surfaced by arniwesth/motoko_agent#8. Today, scaffolding a motoko extension by hand requires ~30,000 tokens of doc context per "add an extension" task — pure axiom-A7 violation. New: `ailang init motoko-extension` produces a working package in one command: ailang init motoko-extension \ --name arniwesth/motoko_ext_openkb \ --tools "OpenKBSearch,OpenKBList" \ --effects "FS,Process,Env" Generates 5 files at packages/motoko-ext-openkb/ — ailang.toml (registry deps, not path-based), register.ail (canonical wrapper), types.ail (placeholder), <short>.ail (full 8-hook ExtensionHooks no-op stub), README.md. Output passes ailang lock + ailang check with zero edits. The four PR #8 failure modes are STRUCTURALLY IMPOSSIBLE from generated output: - Extension nested in host's src/core/ext/ → output dir always packages/ - Package name missing motoko_ext_ infix → --name validation rejects - Hand-edited registry_generated.ail → scaffolder never writes one - path = '../...' in production toml → registry version always used Token-cost impact: ~500 tokens (read generated stubs) vs ~30,000 today. ~60× reduction per extension authored. Critical for AI agents creating extensions on the fly inside motoko_agent. 3 milestones, all passing acceptance criteria: M1 — init type + flag parsing + validation (16 unit tests) M2 — 5 file templates + render + write (manual e2e on /tmp verified) M3 — automated integration test asserting all 4 PR #8 failure modes structurally absent, gated full ailang lock+check behind AILANG_INTEGRATION_TESTS=1 (passes when set) Tutorial doc rewritten: Step 1 collapses from manual 4-file scaffolding to a single ailang init command. Old manual walkthrough preserved as Appendix A for users on AILANG < 0.18.5 or who want to understand the structure. Out of scope (deferred): - Tier 2 generic [extension_template] block (M-EXT-SCAFFOLD-GENERIC- TEMPLATES, future sprint when 2nd extension host exists) - Interactive TTY prompts (flag-only AI-friendly first) - Auto-publish (ailang publish stays separate) Refs: arniwesth/motoko_agent#8 (the failure case proving this matters), M-AILANG-EXT-REGISTRY-GEN (v0.17.1, complementary feature) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This was an experiment with using OpenKB, which I largely consider failed.
Note to self: Auto-PRs should be on near-term roadmap.