sam/pi-config
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

nixos-workflow: document /config-add runbook for adding extensions & skills (vendoring, discovery, worked pi-langfuse example)

Browse Source
This commit is contained in:
Sam Rolfe
2026-08-03 20:10:52 +10:00
parent bc91a15905
commit 6d15e14550
1 changed files with 33 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
skills/nixos-workflow/SKILL.md
View File

@@ -1,7 +1,7 @@
--- ---
name: nixos-workflow name: nixos-workflow
description: STRICT workflow for managing Pi assets via Gitea on NixOS description: STRICT workflow for managing Pi assets via Gitea on NixOS
version: 1.1.0 version: 1.2.0
--- ---
# NixOS Gitea Asset Manager (STRICT) # NixOS Gitea Asset Manager (STRICT)
@@ -19,18 +19,42 @@ All assets MUST be managed in the local Git-controlled directory:
## 🏗 ASSET DEPLOYMENT WORKFLOW ## 🏗 ASSET DEPLOYMENT WORKFLOW
When the user asks for a new tool or skill, you MUST follow these steps exactly: When the user asks for a new tool or skill, you MUST follow these steps exactly:
1. **Local Authoring**: 1. **Local Authoring** — the asset MUST be a directory under `~/.agents/`:
- Write code/markdown directly into the appropriate subfolder in `~/.agents/` (e.g., `extensions/` or `skills/`). - Skills: `skills/<name>/SKILL.md` (+ optional supporting files).
- If cloning an external repo, immediately `rm -rf .git` inside that folder to prevent submodule issues. Also inside that folder remove '.gitignore' if it is there. - Extensions: `extensions/<name>/index.ts` (or `index.js`), or a `package.json` with a `"pi": { "extensions": ["./index.ts"] }` manifest.
2. **Local Dependency Check**: - **Vendoring an external npm package**: copy the published package into `extensions/<name>/` (e.g. `npm pack <pkg>` then extract). If cloning a git repo instead, immediately `rm -rf .git` inside that folder (prevents submodule issues) and remove `.gitignore` if present.
- If an extension, run `npm install` inside that specific subfolder. 2. **Local Dependency Check + Security**:
- If an extension, run `npm install` inside that specific subfolder. `node_modules/` is gitignored (see `.gitignore`) — pi runs `npm install` automatically after pulling from Gitea, so deps are never committed.
- Run `vet scan -D .` (npm-security skill) and follow the vet → npq → socket workflow for any installs.
3. **Gitea Synchronization**: 3. **Gitea Synchronization**:
- `cd /home/sam/.agents` - `cd /home/sam/.agents`
- `git add .` - `git add .`
- `git commit -m "Add [asset name]"` - `git commit -m "Add [asset name]"`
- `git push origin main` - `git push origin main`
4. **Project Activation**: 4. **Project Activation — via `/config-add`, NEVER by hand**:
- Instruct the user to add the relative path (e.g., `"extensions/my-tool/index.ts"`) to their current project's `.pi/settings.json`. - The user activates per project with `/config-add skill <name>` or `/config-add ext <name>`, then `/reload`.
- **Do NOT hand-edit any `.pi/settings.json`**, and do NOT add bare `"npm:..."` package entries to settings. `/config-add`/`/config-remove`/`/config-show`/`/config-list` (pi-config extension) are the ONLY sanctioned interface to project settings.
## 🔍 DISCOVERY & ACTIVATION (pi-config commands)
`/config-add`, `/config-remove`, `/config-show`, `/config-list` are provided by the **pi-config** extension (`~/.agents/extensions/pi-config/index.ts`). Mechanics that matter:
- **Discovery is directory-based.** The commands list subdirectory names under `~/.agents/skills/` and `~/.agents/extensions/`. If an asset is not a directory there, it is invisible to `/config-list`/`/config-show` and `/config-add` will refuse it ("not found in ~/.agents/...").
- `/config-add` resolves the entry point (`skills/<name>`, `extensions/<name>/index.ts`, or the `pi.extensions` list from the folder's `package.json`) and appends it to the project's `~/.agents` package entry in `.pi/settings.json`, then asks for `/reload`.
- Project settings **replace** (not merge) global settings — each folder loads only what it needs, keeping the LLM context lean. This is the point of the whole workflow: no clutter.
- **Global-only packages** (e.g. pi-memctx, @tintinweb/*) are NOT per-project assets — they live in the home-manager-managed global `~/.pi/agent/settings.json` (`/etc/nixos/home/sam/home.nix`) and are out of scope for `/config-add`.
## ✅ WORKED EXAMPLE — adding `pi-langfuse` (2026-08-03)
External npm extension (Langfuse LLM observability for pi) vendored + activated:
1. `npm pack pi-langfuse@1.5.8` → extracted into `~/.agents/extensions/pi-langfuse/` (contains `package.json` with `pi.extensions: ["./index.ts"]`)
2. `npm install` inside the folder (deps gitignored; pi reinstalls on pull)
3. `vet scan -D .` → clean (242 packages)
4. `git add . && git commit && git push` → Gitea `pi-config` (commit `bc91a15`)
5. Project activation: `/config-add ext pi-langfuse` → writes `"extensions/pi-langfuse/index.ts"` to the project's `.pi/settings.json`, then `/reload`
The extension's own config lives at `~/.pi/agent/pi-langfuse/config.json` (`publicKey`/`secretKey`/`host` → `http://192.168.20.13:3001`). Commands: `/langfuse-setup`, `/langfuse-status`. Full documentation: `/home/sam/obsidian/300 areas/350 AI/Pi Agent Extensions & Skills.md` (section "pi-langfuse — LLM Observability for Pi").
## ❄ NIXOS INTEGRATION ## ❄ NIXOS INTEGRATION
The ONLY time you reference Nix is for the **Global Settings**. Confirm the user's `home.nix` contains a `settings.json` that points to the Gitea source: The ONLY time you reference Nix is for the **Global Settings**. Confirm the user's `home.nix` contains a `settings.json` that points to the Gitea source: