pygienium/tasks/01-scaffolding.md

01. Extension scaffolding and project structure

meta: id: pygienium-01 feature: pygienium priority: P1 depends_on: [] tags: [infrastructure, setup]

objective:

• Establish the pygienium extension directory, package.json, tsconfig, and a minimal index.ts that loads without error and surfaces a startup notification.

deliverables:

• pygienium/package.json with pi package manifest (pi.extensions, keywords, peer deps echoing piolium)
• pygienium/tsconfig.json (extends the repo tsconfig)
• pygienium/src/index.ts default-export factory registering a session_start notify + a stub /pygienium-help
• pygienium/ subdirectories: src/, src/modes/, src/checks/, agents/, skills/ (empty, with .gitkeep)
• Verified load: pi -e ./pygienium/src/index.ts -p "/pygienium-help" runs without throwing

steps:

• Create the pygienium/ tree and empty subdirectories
• Author package.json: name pygienium, type module, pi.extensions: ["./src/index.ts"], peerDeps mirroring piolium (@earendil-works/pi-coding-agent, typebox, etc.), engines bun >=1.1.0
• Author tsconfig.json referencing the parent tsconfig.json
• Author src/index.ts: import ExtensionAPI, default-export factory that registers a session_start notify ("Pygienium loaded. Run /pygienium-help.") and a /pygienium-help command printing a placeholder line
• Confirm the extension auto-discovers from ~/.pi/agent/extensions/pygienium/src/index.ts (per docs, subdir index.ts); if discovery prefers pygienium/index.ts, adjust entry path in package.json

tests:

• Manual: run pi -e ./pygienium/src/index.ts -p "/pygienium-help"; confirm the placeholder help renders
• Manual: start pi in ~/.pi/agent/extensions and confirm the startup notify appears without session_start errors

acceptance_criteria:

• The directory tree and package.json exist with valid JSON
• pi loads the extension via auto-discovery with no load errors
• /pygienium-help responds with a non-empty line

validation:

• node -e "JSON.parse(require('fs').readFileSync('pygienium/package.json','utf8'))" exits 0
• pi -e ./pygienium/src/index.ts -p "/pygienium-help" prints the placeholder

notes:

• Place the extension in ~/.pi/agent/extensions/pygienium/ so it auto-discovers and hot-reloads with /reload
• Do NOT add backward-compat shims or migration paths (engineering rule)
• Keep index.ts minimal here; full command wiring lands in task 06