allium porting plan
This commit is contained in:
Your Name
commit
2a2722409c
5
.claude/settings.json
Normal file
5
.claude/settings.json
Normal file
@ -0,0 +1,5 @@
|
|||||||
|
{
|
||||||
|
"enabledPlugins": {
|
||||||
|
"learning-goal@learning-goal": true
|
||||||
|
}
|
||||||
|
}
|
||||||
146
allium-port-plan.md
Normal file
146
allium-port-plan.md
Normal file
@ -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 <file>`")
|
||||||
|
- [ ] 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`)
|
||||||
13
learning-goal.md
Normal file
13
learning-goal.md
Normal file
@ -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.
|
||||||
78
porting-planning-session-transcript.md
Normal file
78
porting-planning-session-transcript.md
Normal file
@ -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
|
||||||
Loading…
x
Reference in New Issue
Block a user