@chankov/agent-skills 0.1.0 → 0.2.0

package/.versions/0.2.0/.pi/agents/pi-pi/theme-expert.md

@@ -0,0 +1,40 @@
+---
+name: theme-expert
+description: Pi themes expert — knows the JSON format, all 51 color tokens, vars system, hex/256-color values, hot reload, and theme distribution
+tools: read,grep,find,ls,bash
+---
+You are a themes expert for the Pi coding agent. You know EVERYTHING about creating and distributing Pi themes.
+
+## Your Expertise
+- Theme JSON format with $schema, name, vars, colors sections
+- All 51 required color tokens across 7 categories:
+  - Core UI (11): accent, border, borderAccent, borderMuted, success, error, warning, muted, dim, text, thinkingText
+  - Backgrounds & Content (11): selectedBg, userMessageBg, userMessageText, customMessageBg, customMessageText, customMessageLabel, toolPendingBg, toolSuccessBg, toolErrorBg, toolTitle, toolOutput
+  - Markdown (10): mdHeading, mdLink, mdLinkUrl, mdCode, mdCodeBlock, mdCodeBlockBorder, mdQuote, mdQuoteBorder, mdHr, mdListBullet
+  - Tool Diffs (3): toolDiffAdded, toolDiffRemoved, toolDiffContext
+  - Syntax Highlighting (9): syntaxComment, syntaxKeyword, syntaxFunction, syntaxVariable, syntaxString, syntaxNumber, syntaxType, syntaxOperator, syntaxPunctuation
+  - Thinking Borders (6): thinkingOff, thinkingMinimal, thinkingLow, thinkingMedium, thinkingHigh, thinkingXhigh
+  - Bash Mode (1): bashMode
+- Optional HTML export section (pageBg, cardBg, infoBg)
+- Color value formats: hex (#ff0000), 256-color index (0-255), variable reference, empty string for default
+- vars system for reusable color definitions
+- Theme locations: ~/.pi/agent/themes/, .pi/themes/
+- Hot reload when editing active custom theme
+- Selection via /settings or settings.json
+- $schema URL for editor validation
+
+## CRITICAL: First Action
+Before answering ANY question, you MUST fetch the latest Pi themes documentation:
+
+```bash
+firecrawl scrape https://raw.githubusercontent.com/badlogic/pi-mono/refs/heads/main/packages/coding-agent/docs/themes.md -f markdown -o /tmp/pi-theme-docs.md || curl -sL https://raw.githubusercontent.com/badlogic/pi-mono/refs/heads/main/packages/coding-agent/docs/themes.md -o /tmp/pi-theme-docs.md
+```
+
+Then read /tmp/pi-theme-docs.md to have the freshest reference. Also search the local codebase (.pi/themes/) for existing theme examples.
+
+## How to Respond
+- Provide COMPLETE theme JSON with ALL 51 color tokens (no partial themes)
+- Use vars for palette consistency
+- Include the $schema for validation
+- Suggest color harmonies based on the user's aesthetic preference
+- Mention hot reload and testing tips

package/.versions/0.2.0/.pi/agents/pi-pi/tui-expert.md

@@ -0,0 +1,85 @@
+---
+name: tui-expert
+description: Pi TUI expert — knows all built-in components (Text, Box, Container, Markdown, Image, SelectList, SettingsList, BorderedLoader), custom components, overlays, keyboard input, widgets, footers, and custom editors
+tools: read,grep,find,ls,bash
+---
+You are a TUI (Terminal User Interface) expert for the Pi coding agent. You know EVERYTHING about building custom UI components and rendering.
+
+## Your Expertise
+
+### Component Interface
+- render(width: number): string[] — lines must not exceed width
+- handleInput?(data: string) — keyboard input when focused
+- wantsKeyRelease? — for Kitty protocol key release events
+- invalidate() — clear cached render state
+
+### Built-in Components (from @mariozechner/pi-tui)
+- Text: multi-line text with word wrapping, paddingX, paddingY, background function
+- Box: container with padding and background color
+- Container: groups children vertically, addChild/removeChild
+- Spacer: empty vertical space
+- Markdown: renders markdown with syntax highlighting
+- Image: renders images in supported terminals (Kitty, iTerm2, Ghostty, WezTerm)
+- SelectList: selection dialog with theme, onSelect/onCancel
+- SettingsList: toggle settings with theme
+
+### From @mariozechner/pi-coding-agent
+- DynamicBorder: border with color function — ALWAYS type the param: (s: string) => theme.fg("accent", s)
+- BorderedLoader: spinner with abort support
+- CustomEditor: base class for custom editors (vim mode, etc.)
+
+### Keyboard Input
+- matchesKey(data, Key.up/down/enter/escape/etc.)
+- Key modifiers: Key.ctrl("c"), Key.shift("tab"), Key.alt("left"), Key.ctrlShift("p")
+- String format: "enter", "ctrl+c", "shift+tab"
+
+### Width Utilities
+- visibleWidth(str) — display width ignoring ANSI codes
+- truncateToWidth(str, width, ellipsis?) — truncate with ellipsis
+- wrapTextWithAnsi(str, width) — word wrap preserving ANSI codes
+
+### UI Patterns (copy-paste ready)
+1. Selection Dialog: SelectList + DynamicBorder + ctx.ui.custom()
+2. Async with Cancel: BorderedLoader with signal
+3. Settings/Toggles: SettingsList + getSettingsListTheme()
+4. Status Indicator: ctx.ui.setStatus(key, styledText)
+5. Widgets: ctx.ui.setWidget(key, lines | factory, { placement })
+6. Custom Footer: ctx.ui.setFooter(factory)
+7. Custom Editor: extend CustomEditor, ctx.ui.setEditorComponent(factory)
+8. Overlays: ctx.ui.custom(component, { overlay: true, overlayOptions })
+
+### Focusable Interface (IME Support)
+- CURSOR_MARKER for hardware cursor positioning
+- Container propagation for embedded inputs
+
+### Theming in Components
+- theme.fg(color, text) for foreground
+- theme.bg(color, text) for background
+- theme.bold(text) for bold
+- Invalidation pattern: rebuild themed content in invalidate()
+- getMarkdownTheme() for Markdown components
+
+### Key Rules
+1. Always use theme from callback — not imported directly
+2. Always type DynamicBorder color param: (s: string) =>
+3. Call tui.requestRender() after state changes in handleInput
+4. Return { render, invalidate, handleInput } for custom components
+5. Use Text with padding (0, 0) — Box handles padding
+6. Cache rendered output with cachedWidth/cachedLines pattern
+
+## CRITICAL: First Action
+Before answering ANY question, you MUST fetch the latest Pi TUI documentation:
+
+```bash
+firecrawl scrape https://raw.githubusercontent.com/badlogic/pi-mono/refs/heads/main/packages/coding-agent/docs/tui.md -f markdown -o /tmp/pi-tui-docs.md || curl -sL https://raw.githubusercontent.com/badlogic/pi-mono/refs/heads/main/packages/coding-agent/docs/tui.md -o /tmp/pi-tui-docs.md
+```
+
+Then read /tmp/pi-tui-docs.md to have the freshest reference. Also search the local codebase for existing TUI component examples in extensions/.
+
+## How to Respond
+- Provide COMPLETE, WORKING component code
+- Include all imports from @mariozechner/pi-tui and @mariozechner/pi-coding-agent
+- Show the ctx.ui.custom() wrapper for interactive components
+- Handle invalidation properly for theme changes
+- Include keyboard input handling where relevant
+- Show both the component class and the registration/usage code

package/.versions/0.2.0/.pi/agents/teams.yaml

@@ -0,0 +1,31 @@
+full:
+  - scout
+  - planner
+  - builder
+  - code-reviewer
+  - documenter
+  - security-auditor
+
+plan-build:
+  - planner
+  - builder
+  - code-reviewer
+
+info:
+  - scout
+  - documenter
+  - code-reviewer
+
+frontend:
+  - planner
+  - builder
+  - bowser
+
+pi-pi:
+  - ext-expert
+  - theme-expert
+  - skill-expert
+  - config-expert
+  - tui-expert
+  - prompt-expert
+  - agent-expert

package/.versions/0.2.0/.pi/damage-control-rules.yaml

@@ -0,0 +1,278 @@
+bashToolPatterns:
+  - pattern: '\brm\s+(-[^\s]*)*-[rRf]'
+    reason: rm with recursive or force flags
+  - pattern: '\brm\s+-[rRf]'
+    reason: rm with recursive or force flags
+  - pattern: '\brm\s+--recursive'
+    reason: rm with --recursive flag
+  - pattern: '\brm\s+--force'
+    reason: rm with --force flag
+  - pattern: '\bsudo\s+rm\b'
+    reason: sudo rm
+  - pattern: '\brmdir\s+--ignore-fail-on-non-empty'
+    reason: rmdir ignore-fail
+  - pattern: '\bchmod\s+(-[^\s]+\s+)*777\b'
+    reason: chmod 777 (world writable)
+  - pattern: '\bchmod\s+-[Rr].*777'
+    reason: recursive chmod 777
+  - pattern: '\bchown\s+-[Rr].*\broot\b'
+    reason: recursive chown to root
+  - pattern: '\bgit\s+reset\s+--hard\b'
+    reason: git reset --hard (use --soft or stash)
+  - pattern: '\bgit\s+clean\s+(-[^\s]*)*-[fd]'
+    reason: git clean with force/directory flags
+  - pattern: '\bgit\s+push\s+.*--force(?!-with-lease)'
+    reason: git push --force (use --force-with-lease)
+  - pattern: '\bgit\s+push\s+(-[^\s]*)*-f\b'
+    reason: git push -f (use --force-with-lease)
+  - pattern: '\bgit\s+stash\s+clear\b'
+    reason: git stash clear (deletes ALL stashes)
+  - pattern: '\bgit\s+reflog\s+expire\b'
+    reason: git reflog expire (destroys recovery mechanism)
+  - pattern: '\bgit\s+gc\s+.*--prune=now'
+    reason: git gc --prune=now (can lose dangling commits)
+  - pattern: '\bgit\s+filter-branch\b'
+    reason: git filter-branch (rewrites entire history)
+  - pattern: '\bgit\s+checkout\s+--\s*\.'
+    reason: Discards all uncommitted changes
+    ask: true
+  - pattern: '\bgit\s+restore\s+\.'
+    reason: Discards all uncommitted changes
+    ask: true
+  - pattern: '\bgit\s+stash\s+drop\b'
+    reason: Permanently deletes a stash
+    ask: true
+  - pattern: '\bgit\s+branch\s+(-[^\s]*)*-D'
+    reason: Force deletes branch (even if unmerged)
+    ask: true
+  - pattern: '\bgit\s+push\s+\S+\s+--delete\b'
+    reason: Deletes remote branch
+    ask: true
+  - pattern: '\bgit\s+push\s+\S+\s+:\S+'
+    reason: Deletes remote branch (old syntax)
+    ask: true
+  - pattern: '\bmkfs\.'
+    reason: filesystem format command
+  - pattern: '\bdd\s+.*of=/dev/'
+    reason: dd writing to device
+  - pattern: '\bkill\s+-9\s+-1\b'
+    reason: kill all processes
+  - pattern: '\bkillall\s+-9\b'
+    reason: killall -9
+  - pattern: '\bpkill\s+-9\b'
+    reason: pkill -9
+  - pattern: '\bhistory\s+-c\b'
+    reason: clearing shell history
+  - pattern: '\baws\s+s3\s+rm\s+.*--recursive'
+    reason: aws s3 rm --recursive (deletes all objects)
+  - pattern: '\baws\s+s3\s+rb\s+.*--force'
+    reason: aws s3 rb --force (force removes bucket)
+  - pattern: '\baws\s+ec2\s+terminate-instances\b'
+    reason: aws ec2 terminate-instances
+  - pattern: '\baws\s+rds\s+delete-db-instance\b'
+    reason: aws rds delete-db-instance
+  - pattern: '\baws\s+cloudformation\s+delete-stack\b'
+    reason: aws cloudformation delete-stack (deletes infrastructure)
+  - pattern: '\baws\s+dynamodb\s+delete-table\b'
+    reason: aws dynamodb delete-table
+  - pattern: '\baws\s+eks\s+delete-cluster\b'
+    reason: aws eks delete-cluster
+  - pattern: '\baws\s+lambda\s+delete-function\b'
+    reason: aws lambda delete-function
+  - pattern: '\baws\s+iam\s+delete-role\b'
+    reason: aws iam delete-role
+  - pattern: '\baws\s+iam\s+delete-user\b'
+    reason: aws iam delete-user
+  - pattern: '\bgcloud\s+projects\s+delete\b'
+    reason: gcloud projects delete (DELETES ENTIRE PROJECT)
+  - pattern: '\bgcloud\s+compute\s+instances\s+delete\b'
+    reason: gcloud compute instances delete
+  - pattern: '\bgcloud\s+sql\s+instances\s+delete\b'
+    reason: gcloud sql instances delete
+  - pattern: '\bgcloud\s+container\s+clusters\s+delete\b'
+    reason: gcloud container clusters delete (GKE)
+  - pattern: '\bgcloud\s+storage\s+rm\s+.*-r'
+    reason: gcloud storage rm -r (recursive delete)
+  - pattern: '\bgcloud\s+functions\s+delete\b'
+    reason: gcloud functions delete
+  - pattern: '\bgcloud\s+iam\s+service-accounts\s+delete\b'
+    reason: gcloud iam service-accounts delete
+  - pattern: '\bgcloud\s+run\s+services\s+delete\b'
+    reason: gcloud run services delete (deletes Cloud Run service)
+  - pattern: '\bgcloud\s+run\s+jobs\s+delete\b'
+    reason: gcloud run jobs delete (deletes Cloud Run job)
+  - pattern: '\bgcloud\s+services\s+disable\b'
+    reason: gcloud services disable (disables GCP APIs)
+  - pattern: '\bgcloud\s+iam\s+roles\s+delete\b'
+    reason: gcloud iam roles delete (deletes IAM role)
+  - pattern: '\bgcloud\s+iam\s+policies\b'
+    reason: gcloud iam policies (modifies IAM policies)
+    ask: true
+  - pattern: '\bfirebase\s+projects:delete\b'
+    reason: firebase projects:delete (deletes entire project)
+  - pattern: '\bfirebase\s+firestore:delete\s+.*--all-collections'
+    reason: firebase firestore:delete --all-collections (wipes all data)
+  - pattern: '\bfirebase\s+database:remove\b'
+    reason: firebase database:remove (wipes Realtime DB)
+  - pattern: '\bfirebase\s+hosting:disable\b'
+    reason: firebase hosting:disable
+  - pattern: '\bfirebase\s+functions:delete\b'
+    reason: firebase functions:delete
+  - pattern: '\bvercel\s+remove\s+.*--yes'
+    reason: vercel remove --yes (removes deployment)
+  - pattern: '\bvercel\s+projects\s+rm\b'
+    reason: vercel projects rm (deletes project)
+  - pattern: '\bvercel\s+env\s+rm\b'
+    reason: vercel env rm (removes env variables)
+  - pattern: '\bvercel\s+rm\b'
+    reason: vercel rm (removes deployment)
+  - pattern: '\bvercel\s+remove\b'
+    reason: vercel remove (removes deployment)
+  - pattern: '\bvercel\s+domains\s+rm\b'
+    reason: vercel domains rm (removes custom domain)
+  - pattern: '\bnetlify\s+sites:delete\b'
+    reason: netlify sites:delete (deletes entire site)
+  - pattern: '\bnetlify\s+functions:delete\b'
+    reason: netlify functions:delete
+  - pattern: '\bwrangler\s+delete\b'
+    reason: wrangler delete (deletes Worker)
+  - pattern: '\bwrangler\s+r2\s+bucket\s+delete\b'
+    reason: wrangler r2 bucket delete
+  - pattern: '\bwrangler\s+kv:namespace\s+delete\b'
+    reason: wrangler kv:namespace delete
+  - pattern: '\bwrangler\s+d1\s+delete\b'
+    reason: wrangler d1 delete (deletes database)
+  - pattern: '\bwrangler\s+queues\s+delete\b'
+    reason: wrangler queues delete
+  - pattern: 'DELETE\s+FROM\s+\w+\s*;'
+    reason: DELETE without WHERE clause (will delete ALL rows)
+  - pattern: 'DELETE\s+\*\s+FROM'
+    reason: DELETE * (will delete ALL rows)
+  - pattern: '\bTRUNCATE\s+TABLE\b'
+    reason: TRUNCATE TABLE (will delete ALL rows)
+  - pattern: '\bDROP\s+TABLE\b'
+    reason: DROP TABLE
+  - pattern: '\bDROP\s+DATABASE\b'
+    reason: DROP DATABASE
+  - pattern: '\bDROP\s+SCHEMA\b'
+    reason: DROP SCHEMA
+  - pattern: '\bDELETE\s+FROM\s+\w+\s+WHERE\b.*\bid\s*='
+    reason: SQL DELETE with specific ID
+    ask: true
+
+zeroAccessPaths:
+  - ".env"
+  - ".env.local"
+  - ".env.development"
+  - ".env.production"
+  - ".env.staging"
+  - ".env.test"
+  - ".env.*.local"
+  - "*.env"
+  - "~/.ssh/"
+  - "~/.gnupg/"
+  - "~/.aws/"
+  - "~/.config/gcloud/"
+  - "*-credentials.json"
+  - "*serviceAccount*.json"
+  - "*service-account*.json"
+  - "~/.azure/"
+  - "~/.kube/"
+  - "kubeconfig"
+  - "*-secret.yaml"
+  - "secrets.yaml"
+  - "~/.docker/"
+  - "*.pem"
+  - "*.key"
+  - "*.p12"
+  - "*.pfx"
+  - "*.tfstate"
+  - "*.tfstate.backup"
+  - ".terraform/"
+  - ".vercel/"
+  - ".netlify/"
+  - "firebase-adminsdk*.json"
+  - "serviceAccountKey.json"
+  - ".supabase/"
+  - "~/.netrc"
+  - "~/.npmrc"
+  - "~/.pypirc"
+  - "~/.git-credentials"
+  - ".git-credentials"
+  - "dump.sql"
+  - "backup.sql"
+  - "*.dump"
+
+readOnlyPaths:
+  - /etc/
+  - /usr/
+  - /bin/
+  - /sbin/
+  - /boot/
+  - /root/
+  - ~/.bash_history
+  - ~/.zsh_history
+  - ~/.node_repl_history
+  - ~/.bashrc
+  - ~/.zshrc
+  - ~/.profile
+  - ~/.bash_profile
+  - "package-lock.json"
+  - "yarn.lock"
+  - "pnpm-lock.yaml"
+  - "Gemfile.lock"
+  - "poetry.lock"
+  - "Pipfile.lock"
+  - "composer.lock"
+  - "Cargo.lock"
+  - "go.sum"
+  - "flake.lock"
+  - "bun.lockb"
+  - "uv.lock"
+  - "npm-shrinkwrap.json"
+  - "*.lock"
+  - "*.lockb"
+  - "*.min.js"
+  - "*.min.css"
+  - "*.bundle.js"
+  - "*.chunk.js"
+  - dist/
+  - build/
+  - .next/
+  - .nuxt/
+  - .output/
+  - __pycache__/
+  - .venv/
+  - venv/
+  - target/
+
+noDeletePaths:
+  - ~/.claude/
+  - CLAUDE.md
+  - "LICENSE"
+  - "LICENSE.*"
+  - "COPYING"
+  - "COPYING.*"
+  - "NOTICE"
+  - "PATENTS"
+  - "README.md"
+  - "README.*"
+  - "CONTRIBUTING.md"
+  - "CHANGELOG.md"
+  - "CODE_OF_CONDUCT.md"
+  - "SECURITY.md"
+  - .git/
+  - .gitignore
+  - .gitattributes
+  - .gitmodules
+  - .github/
+  - .gitlab-ci.yml
+  - .circleci/
+  - Jenkinsfile
+  - .travis.yml
+  - azure-pipelines.yml
+  - Dockerfile
+  - "Dockerfile.*"
+  - docker-compose.yml
+  - "docker-compose.*.yml"
+  - .dockerignore

package/.versions/0.2.0/.pi/extensions/agent-skills-update-check/README.md

@@ -0,0 +1,58 @@
+# agent-skills-update-check
+
+A pi extension that surfaces an "update available" banner once per session when `@chankov/agent-skills` has a newer published version than the one recorded in `.ai/agent-skills-setup.md`.
+
+## What it does
+
+On the first `agent_start` event of a pi session, the extension:
+
+1. Reads `version:` from `.ai/agent-skills-setup.md` in the current working directory. If the record is missing (workspace was never set up via `/setup`), the check is skipped.
+2. Reads the cached latest version from `$XDG_CACHE_HOME/agent-skills/latest-version.json` (falling back to `~/.cache/agent-skills/`).
+3. If the cache is older than 24 hours or absent, fetches the latest version from the npm registry with a 3-second timeout.
+4. If the published version is greater than the recorded version, emits an `info`-level notification via `ctx.ui.notify`.
+
+The check runs **once per session** and is bounded to a single network call. It shares its cache file with the CLI update-notifier so the two never double-fetch.
+
+## When the banner fires
+
+```
+agent-skills update available: 0.1.0 → 0.2.0. Run "npx @chankov/agent-skills@latest update" then /setup to apply.
+```
+
+The banner appears in pi's UI notification area — the same surface used by other extensions for non-fatal status. It does not block, prompt, or modify any file. The user decides when to act on it.
+
+## When the banner does NOT fire
+
+- The workspace has no `.ai/agent-skills-setup.md` install record.
+- The published version equals or is older than the recorded version.
+- The cache shows the published version is current (≤24h since last fetch).
+- The registry is unreachable, returns non-200, or times out.
+- `AGENT_SKILLS_NO_UPDATE_CHECK=1`, `NO_UPDATE_NOTIFIER=1`, or `CI=true` is set in the environment.
+
+Every error path silently aborts. Update checks must never disrupt a session.
+
+## Install
+
+Installed via `/setup` as part of Group 10 — pi extensions. Or symlink manually:
+
+```bash
+ln -s /path/to/@chankov/agent-skills/.pi/extensions/agent-skills-update-check \
+      .pi/extensions/agent-skills-update-check
+```
+
+No runtime deps beyond pi's own `@mariozechner/pi-coding-agent` types and Node built-ins (`fs`, `os`, `path`, `https`).
+
+## Opt-out
+
+The check honours three environment variables (any of them disables it):
+
+- `AGENT_SKILLS_NO_UPDATE_CHECK=1` — agent-skills-specific opt-out
+- `NO_UPDATE_NOTIFIER=1` — the conventional opt-out used by many CLI tools
+- `CI=true` — auto-disabled in CI so the banner never spams build logs
+
+## Behavior notes
+
+- The check runs once per pi session; restarting pi triggers a new check.
+- The cache file is shared with the CLI (`agent-skills check-update`) so both update paths benefit from a single fetch per 24h window.
+- If the install record is *pre-versioning* (no `version:` line), the check is skipped — there's no recorded baseline to compare against. Run `/setup` once to stamp the current version.
+- The extension only reads; it never writes the install record itself.

package/.versions/0.2.0/.pi/extensions/agent-skills-update-check/index.ts

@@ -0,0 +1,161 @@
+// agent-skills-update-check — pi extension that surfaces an "update available"
+// banner once per session when @chankov/agent-skills has a newer published
+// version than the one recorded in .ai/agent-skills-setup.md.
+//
+// Design constraints:
+//   - Never blocks pi startup. The check runs once on the first agent_start
+//     event with a soft 3s timeout.
+//   - Shares the same XDG cache file as the CLI (~/.cache/agent-skills/
+//     latest-version.json) so the CLI and pi don't double-fetch.
+//   - Honors AGENT_SKILLS_NO_UPDATE_CHECK / NO_UPDATE_NOTIFIER / CI opt-outs.
+//   - Network errors, missing record files, and missing node-fetch all fall
+//     through to "do nothing" — never an error notification.
+
+import type { ExtensionAPI, ExtensionContext } from '@mariozechner/pi-coding-agent';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { request } from 'node:https';
+
+const PACKAGE_NAME = '@chankov/agent-skills';
+const REGISTRY = 'https://registry.npmjs.org';
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 3000;
+
+const CACHE_DIR = join(
+	process.env.XDG_CACHE_HOME || join(homedir(), '.cache'),
+	'agent-skills',
+);
+const CACHE_FILE = join(CACHE_DIR, 'latest-version.json');
+
+interface CachePayload {
+	latest: string;
+	checkedAt: number;
+}
+
+export default function updateCheckExtension(pi: ExtensionAPI) {
+	let checked = false;
+
+	pi.on('agent_start', async (_event, ctx) => {
+		if (checked) return;
+		checked = true;
+
+		try {
+			await runCheck(ctx);
+		} catch {
+			// Update checks must never disrupt a session — swallow everything.
+		}
+	});
+}
+
+async function runCheck(ctx: ExtensionContext): Promise<void> {
+	if (isDisabled()) return;
+
+	const recorded = readRecordedVersion();
+	if (!recorded) return; // workspace was never set up via /setup — nothing to compare
+
+	let latest = readCacheFresh();
+	if (!latest) {
+		latest = await fetchLatest(FETCH_TIMEOUT_MS);
+		if (latest) writeCache({ latest, checkedAt: Date.now() });
+	}
+	if (!latest) return;
+
+	if (!isGreater(latest, recorded)) return;
+
+	ctx.ui.notify(
+		`agent-skills update available: ${recorded} → ${latest}. ` +
+		`Run "npx ${PACKAGE_NAME}@latest update" then /setup to apply.`,
+		'info',
+	);
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+function isDisabled(): boolean {
+	return process.env.AGENT_SKILLS_NO_UPDATE_CHECK === '1'
+		|| process.env.NO_UPDATE_NOTIFIER === '1'
+		|| process.env.CI === 'true';
+}
+
+function readRecordedVersion(): string | null {
+	// pi runs from the workspace root; the install record lives at .ai/...
+	const recordPath = join(process.cwd(), '.ai', 'agent-skills-setup.md');
+	if (!existsSync(recordPath)) return null;
+	try {
+		const text = readFileSync(recordPath, 'utf8');
+		const m = text.match(/^version:\s*([^\s#]+)/m);
+		return m ? m[1].trim() : null;
+	} catch {
+		return null;
+	}
+}
+
+function readCacheFresh(): string | null {
+	try {
+		if (!existsSync(CACHE_FILE)) return null;
+		const payload = JSON.parse(readFileSync(CACHE_FILE, 'utf8')) as CachePayload;
+		if (Date.now() - payload.checkedAt >= CACHE_TTL_MS) return null;
+		return payload.latest;
+	} catch {
+		return null;
+	}
+}
+
+function writeCache(payload: CachePayload): void {
+	try {
+		mkdirSync(CACHE_DIR, { recursive: true });
+		writeFileSync(CACHE_FILE, JSON.stringify(payload, null, 2), 'utf8');
+	} catch {
+		// Cache write failed — fine, we'll re-fetch next session.
+	}
+}
+
+function fetchLatest(timeoutMs: number): Promise<string | null> {
+	return new Promise((resolve) => {
+		const url = `${REGISTRY}/${encodeURIComponent(PACKAGE_NAME).replace('%40', '@')}/latest`;
+		const req = request(
+			url,
+			{ method: 'GET', headers: { accept: 'application/json' } },
+			(res) => {
+				if (res.statusCode !== 200) {
+					res.resume();
+					resolve(null);
+					return;
+				}
+				let body = '';
+				res.setEncoding('utf8');
+				res.on('data', (chunk) => { body += chunk; });
+				res.on('end', () => {
+					try {
+						const parsed = JSON.parse(body);
+						resolve(typeof parsed.version === 'string' ? parsed.version : null);
+					} catch {
+						resolve(null);
+					}
+				});
+			},
+		);
+		req.on('error', () => resolve(null));
+		req.setTimeout(timeoutMs, () => {
+			req.destroy();
+			resolve(null);
+		});
+		req.end();
+	});
+}
+
+function isGreater(a: string, b: string): boolean {
+	const [aMain, aPre = ''] = a.split('-', 2);
+	const [bMain, bPre = ''] = b.split('-', 2);
+	const aParts = aMain.split('.').map(Number);
+	const bParts = bMain.split('.').map(Number);
+	for (let i = 0; i < 3; i++) {
+		const ai = aParts[i] ?? 0;
+		const bi = bParts[i] ?? 0;
+		if (ai !== bi) return ai > bi;
+	}
+	if (!aPre && bPre) return true;
+	if (aPre && !bPre) return false;
+	return aPre > bPre;
+}

package/.versions/0.2.0/.pi/extensions/agent-skills-update-check/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "agent-skills-pi-update-check",
+  "private": true,
+  "type": "module",
+  "main": "index.ts"
+}