commit 2a2722409c87d51ac43817238271ce8d88d1ccb2 Author: Your Name Date: Wed Apr 22 10:27:30 2026 +0000 allium porting plan diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..8bc33c7 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,5 @@ +{ + "enabledPlugins": { + "learning-goal@learning-goal": true + } +} diff --git a/allium-port-plan.md b/allium-port-plan.md new file mode 100644 index 0000000..5f375d1 --- /dev/null +++ b/allium-port-plan.md @@ -0,0 +1,146 @@ +# Allium → Pi.dev Port Plan + +## Goal +Port allium (https://github.com/juxt/allium) to pi.dev, keeping upstream files by reference where possible. +Test with the turn-limit extension (https://gitea.apps.sustainabledelivery.com/QWAN/monotonic-pi-extensions). + +## Directory layout + +``` +pi-allium/ ← this repo +├── allium-main/ ← git clone of juxt/allium (submodule or checkout) +├── turn-limit/ ← checkout of monotonic-pi-extensions/packages/pi-turn-limit +├── .pi/ +│ └── skills/ +│ ├── allium/ ← root skill (entry point, routing table) +│ │ ├── SKILL.md ← adapted frontmatter + symlink or include of upstream content +│ │ └── references/ ← symlinks to allium-main/references/* +│ ├── elicit/ +│ │ ├── SKILL.md +│ │ └── references/ ← symlinks to allium-main/skills/elicit/references/* +│ ├── distill/ +│ │ ├── SKILL.md +│ │ └── references/ ← symlinks to allium-main/skills/distill/references/* +│ └── propagate/ +│ ├── SKILL.md +│ └── references/ ← (upstream has none currently) +├── allium-port-plan.md ← this file +└── learning-goal.md ← goal card +``` + +## Key differences: Claude Code plugin vs Pi skill + +| Aspect | Claude Code | Pi.dev | +|--------|-------------|--------| +| Skill location | `.claude-plugin/` + `skills/` | `.pi/skills/{name}/SKILL.md` | +| Frontmatter | `name`, `description`, `version`, `auto_trigger` | `name`, `description`, `disable-model-invocation`, `license`, `metadata` | +| References dir | `resources/` or `references/` | `references/` | +| Agents | `.claude/agents/{name}.md` with `model:`, `tools:` | No native agent support — needs extension or workaround | +| Hooks | `.claude/settings.json` → PostToolUse hooks | Not directly supported — needs extension | +| Rules | `.claude/rules/*.md` with `globs:` | No equivalent — content goes into SKILL.md or references | +| Auto-trigger | `auto_trigger: file_patterns, keywords` | `disable-model-invocation: true/false` | +| Invocation | `/allium`, `/allium:elicit` | `/skill:allium`, `/skill:elicit` | + +## Phases + +### Phase 1: Setup and smoke test +_Goal: get the root `/skill:allium` working in pi with a local model._ + +- [ ] Clone allium upstream into `allium-main/` + ``` + cd ~/research/pi-allium + git clone https://github.com/juxt/allium.git allium-main + ``` +- [ ] Create `.pi/skills/allium/SKILL.md` with pi-compatible frontmatter + - Source: `allium-main/SKILL.md` + - Change: add `disable-model-invocation: true`, `license: MIT`, `metadata` block + - Change: update routing table to use `/skill:elicit`, `/skill:distill`, `/skill:propagate` instead of Claude skill/agent references + - Keep: the full language reference body (copy or include) +- [ ] Symlink references: `ln -s ../../../allium-main/references .pi/skills/allium/references` +- [ ] Smoke test: `pi -p` in this directory, invoke `/skill:allium`, verify it loads and responds with the routing table +- [ ] Verify references load: ask allium about language syntax, confirm it can read `references/language-reference.md` + +### Phase 2: Port elicit, distill, propagate skills +_Goal: all three sub-skills work via `/skill:elicit` etc._ + +- [ ] Create `.pi/skills/elicit/SKILL.md` — adapt frontmatter from `allium-main/skills/elicit/SKILL.md` +- [ ] Symlink references: `ln -s ../../../allium-main/skills/elicit/references .pi/skills/elicit/references` +- [ ] Smoke test `/skill:elicit` — start a mini elicitation session, verify it follows the methodology +- [ ] Create `.pi/skills/distill/SKILL.md` — adapt frontmatter from `allium-main/skills/distill/SKILL.md` +- [ ] Symlink references: `ln -s ../../../allium-main/skills/distill/references .pi/skills/distill/references` +- [ ] Smoke test `/skill:distill` +- [ ] Create `.pi/skills/propagate/SKILL.md` — adapt frontmatter from `allium-main/skills/propagate/SKILL.md` +- [ ] Smoke test `/skill:propagate` + +### Phase 3: Test with turn-limit extension (TDD) +_Goal: use distill → propagate on real code, verify allium produces useful output._ + +- [ ] Checkout turn-limit into this workspace + ``` + git clone https://gitea.apps.sustainabledelivery.com/QWAN/monotonic-pi-extensions.git turn-limit-repo + ln -s turn-limit-repo/packages/pi-turn-limit turn-limit + ``` +- [ ] Run `/skill:distill` against `turn-limit/` — extract a `.allium` spec from existing code +- [ ] Review the generated spec: does it capture turn-limit constraints, enable/disable, UI separation? +- [ ] Run `/skill:propagate` against the generated spec — generate test suggestions +- [ ] Write at least one test based on propagate output (TDD red step) +- [ ] Implement to make the test pass (green step) +- [ ] Iterate: use allium to identify more test obligations, write them, make them pass +- [ ] Run `/skill:elicit` to explore the "disable turn limit" feature requirement +- [ ] Generate spec + tests for the new feature via propagate + +### Phase 4: Fold in allium rules content +_Goal: pi agent knows allium syntax rules when editing .allium files._ + +- [ ] Merge content from `allium-main/.claude/rules/allium.md` into `SKILL.md` or a reference file + - This contains syntax gotchas and anti-patterns that the model needs when writing .allium files + - In Claude Code this auto-triggers on `**/*.allium` globs — in pi we need it in the skill context +- [ ] Test: create/edit a `.allium` file via pi, verify the model follows naming conventions and avoids anti-patterns + +### Phase 5: Agent support (tend & weed) +_Goal: find a way to support tend/weed agent functionality in pi._ + +Tend and weed are Claude Code agents with `model: opus` and specific tool permissions (Read, Glob, Grep, Edit, Write, Bash). Pi doesn't have native agent support. + +Options to investigate: +- [ ] **Option A: Skills as agents** — port tend.md and weed.md as skills with `disable-model-invocation: true`. The model won't have enforced tool restrictions but the skill prompt still guides behavior. Simplest path. +- [ ] **Option B: Pi extension (TypeScript)** — write a TypeScript extension that registers `/tend` and `/weed` commands, controlling context injection. More control, more work. +- [ ] **Option C: npm agents package** — check if pi.dev has an agents extension or if one exists on npm (`npx skills` ecosystem). Check https://pi.dev/docs and https://github.com/nicepkg/agent-skills. +- [ ] Decide on approach and implement +- [ ] Test: use tend to modify a `.allium` spec, verify it follows allium conventions +- [ ] Test: use weed to check spec-code alignment on the turn-limit extension + +### Phase 6: Hook support (allium-check validation) +_Goal: .allium files get validated on write._ + +The Claude Code version runs `allium-check.mjs` as a PostToolUse hook on Edit/Write. + +- [ ] Investigate pi.dev hook/extension support for post-write validation +- [ ] If supported: configure the hook pointing to `allium-main/.claude/hooks/allium-check.mjs` +- [ ] If not: add validation instructions to the skill prompt ("after writing .allium files, run `node allium-check.mjs `") +- [ ] Test: write a `.allium` file with deliberate errors, verify validation catches them + +### Phase 7: Documentation and upstream +_Goal: publishable result._ + +- [ ] Add README.md with attribution (MIT license from JUXT) +- [ ] Add LICENSE +- [ ] Document the symlink-based approach for staying in sync with upstream +- [ ] Document known limitations vs Claude Code version +- [ ] Write blog post draft (separate file) +- [ ] Share with allium team and pi.dev community + +## Key URLs +- Allium upstream: https://github.com/juxt/allium +- Allium docs: https://juxt.github.io/allium/ +- Allium installation: https://juxt.github.io/allium/installation +- Turn-limit extension: https://gitea.apps.sustainabledelivery.com/QWAN/monotonic-pi-extensions +- Pi.dev: https://pi.dev +- Local allium cache (current): `~/.claude/plugins/cache/juxt-plugins/allium/f6fb08dd301f/` + +## Notes for the agent on the other machine +- Pi is invoked with `pi -p` to load project skills from `.pi/skills/` +- Default model: `qwen3.5:35b-a3b` via Ollama on `192.168.0.1:11434` +- Skills are invoked with `/skill:name` (requires `enableSkillCommands: true` in pi settings if not already set) +- Symlinks must resolve on the target machine — clone allium-main in the same relative position +- The `.allium` language version is 3 (check `allium-main/VERSION`) diff --git a/learning-goal.md b/learning-goal.md new file mode 100644 index 0000000..13fa3fe --- /dev/null +++ b/learning-goal.md @@ -0,0 +1,13 @@ +## My Learning Goal +Learn enough about allium's architecture and pi.dev's plugin system to port allium while keeping most of it as upstream references, so I'm not maintaining a full fork. By the end of this session, have it running against my turn-limit extension and getting useful output — tests, constraint extraction, or logic factoring. + +## Why It Matters +This is a gateway skill — cracking the porting pattern unlocks future plugins for pi.dev. It also makes a good blog post for both the allium and pi.dev communities, and moves my extensions from interactive code-and-fix toward specced, tested, and autonomous. + +## My If-Then Plans +- If I get interrupted and need to resume on another machine, then I will check my private wiki (today's page, "porting allium to pi.dev" with file locations). +- If I hit the sandbox-merge problem, then I will create a third JSON file combining permissions for both Claude and pi. +- If I need multiple repositories active in the sandbox, then I will create a parent directory containing clones for all repos I need. If agents get confused, I will run bash in the sandbox and cd into the repo I need. + +## My First Step +Try the simple install path (`npx skills add juxt/allium` or equivalent) and see what happens. If that doesn't work, read the allium repo structure and figure out what needs to move where. diff --git a/porting-planning-session-transcript.md b/porting-planning-session-transcript.md new file mode 100644 index 0000000..1dbac7c --- /dev/null +++ b/porting-planning-session-transcript.md @@ -0,0 +1,78 @@ +╭─── Claude Code v2.1.89 ──────────────────────────────────────────────────────╮ +│ │ Tips for getting started │ +│ Welcome back Willem! │ Run /init to create a CLAUDE.md fi… │ +│ │ ─────────────────────────────────── │ +│ ▐▛███▜▌ │ Recent activity │ +│ ▝▜█████▛▘ │ No recent activity │ +│ ▘▘ ▝▝ │ │ +│ │ │ +│ Opus 4.6 (1M context) · Claude Max │ │ +│ ~/research/pi-allium │ │ +╰──────────────────────────────────────────────────────────────────────────────╯ + +❯ /plugin update + ⎿ (no content) + +❯ I would like you to make an implementation plan in allium-port-plan.md with +[ ] check boxes and file locations, assuming we have allium main checked out in + allium-main, and our pi port is in pi-allium in the current directory. Add +file locations, relevant urls and anything else that is needed to give an agent + on my machine with pi (we can run pi -p to check and load the skill). I can +also checkout the 'turn-limit' skill as a subdirectory so we can define tests. +I like TDD and small steps. One of the phases (later) would be to find a +suitable way to implement agents. Etiher as a custom extension or using one of +the existing agents extensions from npm. + + Searched for 1 pattern, read 1 file (ctrl+o to expand) + +● Now let me read the individual skill files and check how pi.dev handles things + like auto_trigger and agents. + + Read 7 files (ctrl+o to expand) + +● Now let me check what pi.dev supports for skills/agents/hooks. + +● Bash(pi --help 2>/dev/null | head -50 || echo "pi not found in PATH") + ⎿  (No output) + + Read 1 file, listed 2 directories (ctrl+o to expand) + +● Good. Now I have everything I need. Let me write the plan. + +● Write(allium-port-plan.md) + ⎿  Wrote 146 lines to allium-port-plan.md + 1 # Allium → Pi.dev Port Plan + 2 + 3 ## Goal + 4 Port allium (https://github.com/juxt/allium) to pi.dev, keeping + upstream files by reference where possible. + 5 Test with the turn-limit extension (https://gitea.apps.sustainab + ledelivery.com/QWAN/monotonic-pi-extensions). + 6 + 7 ## Directory layout + 8 + 9 ``` + 10 pi-allium/ ← this repo + … +136 lines (ctrl+o to expand) + +● The plan is at allium-port-plan.md. Seven phases, small steps with checkboxes: + + 1. Setup + smoke test — clone allium, create root skill with pi frontmatter, + symlink references, verify it loads + 2. Port sub-skills — elicit, distill, propagate with symlinked references + 3. TDD with turn-limit — distill a spec from your extension, propagate tests, + write them red-green + 4. Rules content — fold the .allium syntax rules into the skill context + 5. Agents (tend/weed) — three options to evaluate: skills-as-agents + (simplest), TypeScript extension, or npm package + 6. Hooks (allium-check) — post-write validation for .allium files + 7. Docs and upstream — README, LICENSE, blog post + + The symlink approach means allium-main/ is the single source of truth — you + git pull to update. The SKILL.md files in .pi/skills/ are thin wrappers with + pi-compatible frontmatter. + + I also included notes for the agent on your other machine: model config, how + to invoke skills, and the symlink requirement. Want to start on Phase 1? + +✻ Worked for 1m 41s \ No newline at end of file