@astrofoundry/pi-astro 0.3.1 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @astrofoundry/pi-astro
 
-Personal customizations for the [pi coding agent](https://github.com/badlogic/pi-mono) — registers an `astro_agent` tool and ships 8 curated subagents.
+Personal customizations for the [pi coding agent](https://github.com/badlogic/pi-mono) — registers an `astro_agent` tool, a `grimoire` docs tool, a `claude-globals` rules-injection extension, 8 curated subagents, 3 skills, and an `astro` theme.
 
 ## Full setup
 
@@ -10,61 +10,83 @@ Personal customizations for the [pi coding agent](https://github.com/badlogic/pi
 npm install -g @mariozechner/pi-coding-agent
 ```
 
-Verify:
+### 2. Install this package
 
 ```bash
-pi --version
+pi install npm:@astrofoundry/pi-astro
 ```
 
-### 2. Install this package
+### 3. Install CLI prerequisites
 
 ```bash
-pi install npm:@astrofoundry/pi-astro
+# grimoire (required by the `grimoire` tool — docs lookup)
+npm install -g @astrofoundry/grimoire
+
+# Playwright CLI (required by the `playwright-cli` skill / tester-ui agent)
+npm install -g @playwright/cli@latest
+
+# Postman CLI (required by the `postman-cli` skill / tester-api agent)
+npm install -g postman-cli
 ```
 
-### 3. Verify
+Optional: [Raycast](https://raycast.com) app, required only if you use the `raycast-script-creator` skill.
 
-```bash
-pi list
+### 4. Activate the `astro` theme
+
+Add to `~/.pi/agent/settings.json`:
+
+```json
+{ "theme": "astro" }
 ```
 
-Launch pi and confirm the `astro_agent` tool is available:
+Or run `/settings` inside pi and select `astro`.
+
+### 5. Verify
 
 ```bash
-pi
+pi list           # package shows installed
+pi                # launch; confirm [Extensions] lists astro-agents, claude-globals, grimoire
 ```
 
 ## What's inside
 
-- **`astro-agents` extension** — registers the `astro_agent` tool to delegate tasks to named subagents running in isolated `pi` subprocesses.
-- **8 bundled agents**:
-  - `code-reviewer`
-  - `google-tech-lead`
-  - `spec-writer`
-  - `tester-api`
-  - `tester-ui`
-  - `ui-architect`
-  - `ui-design-system`
-  - `ui-frontend-developer`
+**Tools** (LLM-callable):
+- `astro_agent` — delegate a task to a named subagent in an isolated pi subprocess
+- `grimoire` — search indexed technical documentation via the grimoire CLI
+
+**Extensions:**
+- `astro-agents` — registers `astro_agent` + ships 8 bundled subagents
+- `grimoire` — registers `grimoire` tool
+- `claude-globals` — auto-injects `~/.claude/CLAUDE.md` into every pi session's system prompt
+
+**Bundled subagents** (callable via `astro_agent`):
+- `code-reviewer`, `google-tech-lead`, `spec-writer`, `tester-api`, `tester-ui`, `ui-architect`, `ui-design-system`, `ui-frontend-developer`
+
+**Skills** (loadable via `/skill:<name>`):
+- `playwright-cli`, `postman-cli`, `raycast-script-creator`
+
+**Theme:**
+- `astro` — dark, gold accent, GitHub-dark-inspired
 
 ## Usage
 
-Inside pi, call the `astro_agent` tool with an agent name and a task:
+Delegate to a subagent:
 
 ```
-{
-  "agent": "code-reviewer",
-  "task": "Review the changes in src/routes/products.ts for security issues."
-}
+use the code-reviewer agent to review src/routes/products.ts
 ```
 
-Agent discovery priority (highest first):
+Search docs:
 
-1. **Project** — nearest `.pi/agents/*.md` walked from the current working directory. Requires `scope: "project"` or `scope: "both"` and interactive confirmation.
-2. **User** — `~/.pi/agent/agents/*.md`.
-3. **Bundle** — the 8 agents shipped with this package.
+```
+look up Firestore batched writes in the docs
+```
+
+Invoke a skill explicitly:
 
-Agents override by name — a project agent named `code-reviewer` wins over the bundled one when `scope` allows.
+```
+/skill:playwright-cli
+```
 
 ## License
 

package/extensions/astro-agents/agents/code-reviewer.md

@@ -3,13 +3,9 @@ name: code-reviewer
 description: |-
   Use this agent to review code for quality, security, correctness, and spec compliance. It is read-only and reports issues with severity and remediation guidance.
 color: red
-model: opus
-effort: max
-skills:
-  - grimoire
 memory: user
 tools: read, grep, find, ls, grimoire
-_notWired: model, effort, skills, memory
+_notWired: memory
 ---
 If any instruction below conflicts with the user's global rules (provided separately in the system prompt), flag the conflict explicitly in your response and let the user decide — do not silently override either side.
 

package/extensions/astro-agents/agents/google-tech-lead.md

@@ -3,14 +3,9 @@ name: google-tech-lead
 description: |-
   Use this agent for designing and implementing anything in the Google/Firebase ecosystem — Cloud Functions 2nd gen (Express), Firestore (data models, security rules, indexes), Firebase Auth (Identity Platform, MFA), Firebase Hosting, Firebase Storage, App Check, and Emulator Suite. This is a tech lead that both architects and writes production code, making decisions about the Firebase stack grounded in official documentation. Examples:\n\n<example>\nContext: Implementing a Cloud Function with Express\nuser: "Create a Cloud Functions 2nd gen HTTP function in europe-west3 that hosts an Express app with versioned API routes (/api/v1/...). It needs middleware for auth token verification, rate limiting, and request validation. Set up proper error handling and CORS."\nassistant: "I'll architect and implement the Cloud Function with Express. Let me use the google-tech-lead agent — it will verify Firebase Functions v2 API, Express integration patterns, and middleware setup through grimoire before writing any code."\n<commentary>\nCloud Functions hosting Express requires specific v2 patterns for region config, CORS handling, and middleware integration that differ from v1.\n</commentary>\n</example>\n\n<example>\nContext: Designing Firestore data model and security rules\nuser: "Design the Firestore schema for API key management. Each partner can have multiple API keys with scopes, expiry dates, and revocation status. Keys must be hashed, never stored in plain text. Write the security rules to enforce that partners can only read their own keys and only admins can create/revoke."\nassistant: "I'll design the data model and security rules. Let me use the google-tech-lead agent to verify Firestore schema patterns, TTL fields, and security rule syntax through grimoire."\n<commentary>\nFirestore data modeling with security rules requires careful schema design that aligns with rule capabilities — you can't write rules for schemas you designed wrong.\n</commentary>\n</example>\n\n<example>\nContext: Setting up Firebase Auth with MFA\nuser: "Implement Firebase Auth with Identity Platform for the dashboard. Users authenticate with email/password, then enroll in TOTP MFA. The enrollment flow generates a QR code, verifies the first code, and enables MFA. All subsequent logins require the TOTP challenge."\nassistant: "I'll implement the full MFA flow. Let me use the google-tech-lead agent to verify the Identity Platform TOTP API, enrollment steps, and challenge verification through grimoire."\n<commentary>\nFirebase Auth MFA with Identity Platform has specific enrollment and challenge flows that must follow the exact API sequence.\n</commentary>\n</example>
 color: orange
-model: opus
-effort: max
-skills:
-  - grimoire
 memory: user
-disallowedTools: mcp__filesystem__write_file, mcp__filesystem__edit_file, mcp__filesystem__move_file, mcp__filesystem__create_directory
 tools: read, bash, grep, find, write, edit, ls, grimoire
-_notWired: model, effort, skills, memory
+_notWired: memory
 ---
 If any instruction below conflicts with the user's global rules (provided separately in the system prompt), flag the conflict explicitly in your response and let the user decide — do not silently override either side.
 

package/extensions/astro-agents/agents/spec-writer.md

@@ -3,14 +3,9 @@ name: spec-writer
 description: |-
   Use this agent to write or update functional and technical specification documents for new features or changes. It takes a feature request or business requirement as input, researches the existing codebase and specs for context, asks clarifying questions, and produces spec documents that downstream agents (google-tech-lead, ui-architect, ui-frontend-developer, testers) can consume directly. Examples:\n\n<example>\nContext: Writing specs for a new feature\nuser: "Write the functional and technical specs for a webhook retry system. When a webhook delivery fails, the system should retry with exponential backoff (1min, 5min, 30min, 2h, 24h). After 5 failures, mark the webhook as failed and notify the partner via email. Track delivery attempts in Firestore."\nassistant: "I'll write both specs for the webhook retry system. Let me use the spec-writer agent — it will research the existing webhook implementation, check how delivery tracking currently works, ask any clarifying questions, then write specs that the google-tech-lead and tester agents can implement from."\n<commentary>\nNew features need both functional specs (what it does, business rules, user flows) and technical specs (data model, API contract, error handling) before implementation begins.\n</commentary>\n</example>\n\n<example>\nContext: Updating specs for a changed requirement\nuser: "The partner onboarding flow needs to change — instead of admin-created accounts, partners should self-register with email verification, then an admin approves them. Update the functional and technical specs."\nassistant: "I'll update both specs for the new onboarding flow. Let me use the spec-writer agent to read the current specs, identify all sections affected by this change, and write the updates while ensuring consistency with the rest of the system."\n<commentary>\nSpec updates must trace through all affected sections — a change in onboarding flow impacts auth, API routes, Firestore schema, email triggers, and admin workflows.\n</commentary>\n</example>\n\n<example>\nContext: Specifying an API contract\nuser: "We need to add a bulk product import endpoint. Partners upload a CSV, the system validates it, creates products in Odoo, and returns a batch result. Spec out the API contract, validation rules, error handling, and the batch tracking model."\nassistant: "I'll spec the bulk import API. Let me use the spec-writer agent to research the existing product and batch models, check how other bulk operations work in the system, and write a complete API contract with request/response shapes, validation, and error scenarios."\n<commentary>\nAPI contract specs must define every request/response shape, status code, error format, and edge case so the implementing agent has zero ambiguity.\n</commentary>\n</example>
 color: purple
-model: opus
-effort: max
-skills:
-  - grimoire
 memory: user
-disallowedTools: mcp__filesystem__write_file, mcp__filesystem__edit_file, mcp__filesystem__move_file, mcp__filesystem__create_directory
 tools: read, bash, grep, find, write, edit, ls, grimoire
-_notWired: model, effort, skills, memory
+_notWired: memory
 ---
 If any instruction below conflicts with the user's global rules (provided separately in the system prompt), flag the conflict explicitly in your response and let the user decide — do not silently override either side.
 

package/extensions/astro-agents/agents/tester-api.md

@@ -3,14 +3,11 @@ name: tester-api
 description: |-
   Use this agent to write and maintain API tests using Vitest + MSW for Express/Firebase Cloud Functions. It tests route handlers, middleware, validators, authentication, authorization, rate limiting, and Odoo integration (mocked). It also validates that Postman collections match the actual API implementation and vice versa. Examples:\n\n<example>\nContext: Writing tests for a new API endpoint\nuser: "Write tests for the POST /api/v1/products endpoint in apps/functions/src/routes/products.ts. It validates the request body with Zod, checks partner authentication, calls Odoo to create the product, and returns the created product. Mock Odoo calls with MSW."\nassistant: "I'll write comprehensive tests for the products endpoint. Let me use the tester-api agent — it will read the route handler, set up MSW mocks for Odoo, test validation, auth, success and error paths, and verify the Postman collection matches."\n<commentary>\nAPI endpoint tests require mocking external services (Odoo), testing the full middleware chain, and validating against Postman contract.\n</commentary>\n</example>\n\n<example>\nContext: Validating Postman collections against implementation\nuser: "Check that our Postman collections in postman/collections/ match the current API implementation. Flag any endpoints that exist in code but not in Postman, or vice versa."\nassistant: "I'll audit the Postman collections against the codebase. Let me use the tester-api agent to cross-reference every route definition with the corresponding Postman request and flag discrepancies."\n<commentary>\nPostman collection drift is common — the tester-api agent ensures collections stay in sync with the actual implementation.\n</commentary>\n</example>\n\n<example>\nContext: Testing middleware chain\nuser: "Write tests for the partner API middleware chain: apiKeyAuth -> rateLimiter -> scopeCheck -> requirePartnerType. Test each middleware in isolation and the full chain together."\nassistant: "I'll test the full middleware chain. Let me use the tester-api agent to test each middleware unit, then integration test the chain with various auth scenarios, rate limit edge cases, and scope combinations."\n<commentary>\nMiddleware chain testing requires both isolated unit tests and integration tests that verify the chain works correctly end-to-end.\n</commentary>\n</example>
 color: yellow
-model: opus
-effort: max
 skills:
-  - grimoire
+  - postman-cli
 memory: user
-disallowedTools: mcp__filesystem__write_file, mcp__filesystem__edit_file, mcp__filesystem__move_file, mcp__filesystem__create_directory
 tools: read, bash, grep, find, write, edit, ls, grimoire
-_notWired: model, effort, skills, memory
+_notWired: memory
 ---
 If any instruction below conflicts with the user's global rules (provided separately in the system prompt), flag the conflict explicitly in your response and let the user decide — do not silently override either side.
 

package/extensions/astro-agents/agents/tester-ui.md

@@ -3,15 +3,11 @@ name: tester-ui
 description: |-
   Use this agent to write and maintain UI tests for React components and pages using Vitest + React Testing Library for unit/component tests and Playwright for E2E flows. It tests user interactions, accessibility, responsive behavior, and design system token usage. Examples:\n\n<example>\nContext: Writing component tests\nuser: "Write tests for the StatusBadge component at src/components/ui/StatusBadge.tsx. It renders different colors and labels based on order status. Test all status variants, accessibility (text label always visible, not color-only), and that it uses design system tokens."\nassistant: "I'll write comprehensive tests for StatusBadge. Let me use the tester-ui agent — it will verify React Testing Library patterns through grimoire, test every status variant, check accessibility, and verify token usage."\n<commentary>\nComponent tests verify rendering, accessibility, and design system compliance across all variants and states.\n</commentary>\n</example>\n\n<example>\nContext: Writing E2E tests for a user flow\nuser: "Write Playwright E2E tests for the order creation flow: navigate to New Order page, fill the form (partner, products, quantities), submit, verify redirect to order detail page with correct data and 'Confirmed' status badge."\nassistant: "I'll write the E2E test for the order creation flow. Let me use the tester-ui agent to script the full user journey with Playwright, verify each step, and test error states along the way."\n<commentary>\nE2E tests verify complete user flows across multiple pages with real browser interactions.\n</commentary>\n</example>\n\n<example>\nContext: Testing responsive behavior\nuser: "Write tests that verify the Products List page works correctly at all three breakpoints: mobile (< 768px), tablet (768px - 1279px), and desktop (>= 1280px). The data table should become stacked cards on mobile, and the sidebar should collapse to a hamburger."\nassistant: "I'll write responsive tests across all breakpoints. Let me use the tester-ui agent to set up Playwright viewport tests and verify the layout adaptations at each breakpoint."\n<commentary>\nResponsive testing requires viewport manipulation and verifying that layout changes match the design system breakpoint specs.\n</commentary>\n</example>
 color: yellow
-model: opus
-effort: max
 skills:
-  - grimoire
   - playwright-cli
 memory: user
-disallowedTools: mcp__filesystem__write_file, mcp__filesystem__edit_file, mcp__filesystem__move_file, mcp__filesystem__create_directory
 tools: read, bash, grep, find, write, edit, ls, grimoire
-_notWired: model, effort, skills, memory
+_notWired: memory
 ---
 If any instruction below conflicts with the user's global rules (provided separately in the system prompt), flag the conflict explicitly in your response and let the user decide — do not silently override either side.
 

package/extensions/astro-agents/agents/ui-architect.md

@@ -3,15 +3,9 @@ name: ui-architect
 description: |-
   Use this agent to create component specifications, screen-by-screen UI specs, and layout patterns from an existing design system. This agent takes the design tokens produced by ui-design-system and defines how every UI element looks, behaves, and responds — button variants, form states, data tables, navigation patterns, status badges, modals, toasts, empty/loading/error states, and full page layouts. It outputs detailed spec documents, not code. Examples:\n\n<example>\nContext: Defining component specifications for a new project\nuser: "Using the design system in docs/ui/ui-specs/ui-00-design-system.md, create the component spec for all common UI elements: buttons, form inputs, selects, checkboxes, toggles, data tables, filter bars, status badges, modals, toasts, empty states, loading states, and error banners."\nassistant: "I'll create the full component specification. Let me use the ui-architect agent — it will read the design tokens, reference shadcn/ui component APIs through grimoire, and define every variant, state, and responsive behavior using the token system."\n<commentary>\nComponent specs require mapping abstract design tokens to concrete UI elements with precise dimensions, colors, states, and responsive behavior.\n</commentary>\n</example>\n\n<example>\nContext: Writing a screen spec for a specific page\nuser: "Write the screen spec for the Orders List page. It needs a filter bar (search, status pills, date range), a data table with sortable columns (Order ID, Partner, Status, Total, Date), pagination, and bulk actions. Reference the component specs and design system tokens."\nassistant: "I'll write the Orders List screen spec. Let me use the ui-architect agent to define the page layout, data requirements, component composition, interactions, and responsive behavior — all referencing the established tokens and component specs."\n<commentary>\nScreen specs compose components into full pages with specific data bindings, interaction flows, and responsive breakpoint behavior.\n</commentary>\n</example>\n\n<example>\nContext: Defining layout shells\nuser: "Define the layout structure for the application: auth shell (login, password reset), partner dashboard shell (sidebar + header + content area), and admin dashboard shell. Include responsive behavior for all three breakpoints."\nassistant: "I'll define all three layout shells. Let me use the ui-architect agent to specify the structure, dimensions, responsive collapse behavior, and how content areas adapt across mobile, tablet, and desktop."\n<commentary>\nLayout shells are the structural foundation that screen specs build on — they define navigation, header, content areas, and responsive behavior.\n</commentary>\n</example>
 color: cyan
-model: opus
-effort: max
-skills:
-  - grimoire
-  - playwright-cli
 memory: user
-disallowedTools: mcp__filesystem__write_file, mcp__filesystem__edit_file, mcp__filesystem__move_file, mcp__filesystem__create_directory
 tools: read, bash, grep, find, write, edit, ls, grimoire
-_notWired: model, effort, skills, memory
+_notWired: memory
 ---
 If any instruction below conflicts with the user's global rules (provided separately in the system prompt), flag the conflict explicitly in your response and let the user decide — do not silently override either side.
 

package/extensions/astro-agents/agents/ui-design-system.md

@@ -3,15 +3,9 @@ name: ui-design-system
 description: |-
   Use this agent to create or modify the foundational design system for a project — design tokens (colors, typography, spacing, border radius, shadows, motion, breakpoints) and their CSS implementation. This agent produces concrete Tailwind v4 + shadcn/ui v2 token files, not component specs or code. It asks clarifying questions before starting, proposes aesthetic direction, validates WCAG contrast ratios, and outputs both CSS config and a design system reference document. Examples:\n\n<example>\nContext: Creating a design system from scratch\nuser: "Create the design system for a maritime logistics dashboard. Brand colors are deep navy and amber gold. Target audience is warehouse managers and logistics operators. Needs dark mode."\nassistant: "I'll create the foundational design system. Let me use the ui-design-system agent — it will propose an aesthetic direction, define all tokens in oklch for shadcn/ui v2, configure the Tailwind v4 @theme block, and validate WCAG contrast ratios before finalizing."\n<commentary>\nA new design system requires establishing the complete visual language: color palette with semantic mapping, typography scale, spacing system, shadows, motion tokens, and breakpoints — all in the correct format for Tailwind v4 + shadcn/ui v2.\n</commentary>\n</example>\n\n<example>\nContext: Modifying an existing design system\nuser: "Our current design system uses hex colors and HSL for shadcn tokens. We need to migrate to oklch for shadcn/ui v2 and add a complete dark mode palette. Current tokens are in docs/ui/ui-specs/ui-00-design-system.md."\nassistant: "I'll migrate the design tokens to oklch and add dark mode. Let me use the ui-design-system agent to convert all colors, verify contrast ratios in both modes, and update the CSS variables and @theme block."\n<commentary>\nMigrating token formats requires systematic conversion, contrast re-validation, and updating the CSS output to match current Tailwind v4 + shadcn/ui v2 conventions.\n</commentary>\n</example>\n\n<example>\nContext: Extending the design system with new tokens\nuser: "We need to add a status badge color system to our design tokens. Statuses: draft, active, processing, shipped, delivered, failed, cancelled. Each needs background, text, and border colors that work in both light and dark mode."\nassistant: "I'll design the status color system. Let me use the ui-design-system agent to create accessible color pairings for each status, define the tokens in oklch, and add them to the CSS variables with dark mode variants."\n<commentary>\nAdding semantic color groups requires careful selection for distinctiveness, accessibility, and consistency with the existing palette.\n</commentary>\n</example>
 color: green
-model: opus
-effort: max
-skills:
-  - grimoire
-  - playwright-cli
 memory: user
-disallowedTools: mcp__filesystem__write_file, mcp__filesystem__edit_file, mcp__filesystem__move_file, mcp__filesystem__create_directory
 tools: read, bash, grep, find, write, edit, ls, grimoire
-_notWired: model, effort, skills, memory
+_notWired: memory
 ---
 If any instruction below conflicts with the user's global rules (provided separately in the system prompt), flag the conflict explicitly in your response and let the user decide — do not silently override either side.
 

package/extensions/astro-agents/agents/ui-frontend-developer.md

@@ -3,15 +3,9 @@ name: ui-frontend-developer
 description: |-
   Use this agent for implementing specific React components, pages, or features with TypeScript, Next.js App Router, Tailwind CSS, and shadcn/ui. This agent receives laser-focused prompts with exact specifications and strictly verifies all SDK/library usage through grimoire before writing any code. Examples:\n\n<example>\nContext: Implementing a specific component from a screen spec\nuser: "Implement the OrderHistoryTable component in src/components/orders/OrderHistoryTable.tsx. It receives OrderRow[] as props, uses shadcn/ui DataTable with sortable columns (Order ID, Date, Status, Total), a status badge using the design system color tokens, and pagination. Follow the screen spec in docs/ui/ui-specs/orders-list.md."\nassistant: "I'll implement the OrderHistoryTable component. Let me use the ui-frontend-developer agent — it will verify shadcn/ui DataTable API and Tailwind token usage through grimoire before writing the component."\n<commentary>\nSpecific component implementation with exact props, library usage, and design system constraints requires the frontend specialist.\n</commentary>\n</example>\n\n<example>\nContext: Fixing a typed component issue\nuser: "The ProductCard component at src/components/catalog/ProductCard.tsx has a type error — the price prop is typed as string but the API returns number. Fix the type, update the Zod schema in src/schemas/product.ts, and ensure the formatter in formatCurrency handles both."\nassistant: "I'll fix the type mismatch across the component, schema, and utility. Let me use the ui-frontend-developer agent to trace the type through all layers."\n<commentary>\nTypeScript type issues that span multiple files need systematic tracing through components, schemas, and utilities.\n</commentary>\n</example>\n\n<example>\nContext: Building a Next.js App Router page\nuser: "Create the /settings/profile page using Next.js App Router. Server Component that fetches user profile via Server Action, with a client form component using React Hook Form + Zod for validation. Use the design system spacing and typography tokens. Spec: docs/ui/ui-specs/settings-profile.md."\nassistant: "I'll build the settings profile page with the Server Component / Client Component split. Let me use the ui-frontend-developer agent to verify Next.js App Router patterns and React Hook Form integration through grimoire."\n<commentary>\nNext.js App Router pages with mixed Server/Client Components and form handling require precise knowledge of current API patterns.\n</commentary>\n</example>
 color: blue
-model: opus
-effort: max
-skills:
-  - grimoire
-  - playwright-cli
 memory: user
-disallowedTools: mcp__filesystem__write_file, mcp__filesystem__edit_file, mcp__filesystem__move_file, mcp__filesystem__create_directory
 tools: read, bash, grep, find, write, edit, ls, grimoire
-_notWired: model, effort, skills, memory
+_notWired: memory
 ---
 If any instruction below conflicts with the user's global rules (provided separately in the system prompt), flag the conflict explicitly in your response and let the user decide — do not silently override either side.
 

package/extensions/astro-agents/discovery.ts

@@ -10,6 +10,7 @@ export interface AgentConfig {
     description: string;
     color?: string;
     tools?: string[];
+    skills?: string[];
     systemPrompt: string;
     source: AgentSource;
     filePath: string;
@@ -20,6 +21,7 @@ interface AgentFrontmatter extends Record<string, unknown> {
     description?: string;
     color?: string;
     tools?: string;
+    skills?: unknown;
 }
 
 function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
@@ -47,11 +49,23 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
             .map((t) => t.trim())
             .filter(Boolean);
 
+        let skills: string[] | undefined;
+        const rawSkills = frontmatter.skills;
+        if (Array.isArray(rawSkills)) {
+            skills = rawSkills.map((s) => String(s).trim()).filter(Boolean);
+        } else if (typeof rawSkills === "string") {
+            skills = rawSkills
+                .split(",")
+                .map((s) => s.trim())
+                .filter(Boolean);
+        }
+
         agents.push({
             name: frontmatter.name,
             description: frontmatter.description,
             color: frontmatter.color,
             tools: tools && tools.length > 0 ? tools : undefined,
+            skills: skills && skills.length > 0 ? skills : undefined,
             systemPrompt: body,
             source,
             filePath,

package/extensions/astro-agents/index.ts

@@ -1,12 +1,33 @@
+import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import { Type } from "typebox";
 import { discoverAgents, type AgentScope } from "./discovery.ts";
 import { runAgent } from "./spawn.ts";
 
 const extensionDir = path.dirname(fileURLToPath(import.meta.url));
 const bundleAgentsDir = path.join(extensionDir, "agents");
+const packageSkillsDir = path.resolve(extensionDir, "..", "..", "skills");
+
+function resolvePackageSkills(
+    skillNames: string[],
+    ctx: ExtensionContext,
+): string[] {
+    const resolved: string[] = [];
+    for (const name of skillNames) {
+        const candidate = path.join(packageSkillsDir, name);
+        if (fs.existsSync(candidate)) {
+            resolved.push(candidate);
+        } else {
+            ctx.ui.notify(
+                `skill "${name}" declared by agent is not present in @astrofoundry/pi-astro; skipping.`,
+                "warning",
+            );
+        }
+    }
+    return resolved;
+}
 
 const params = Type.Object({
     agent: Type.String({ description: "Name of the subagent to invoke." }),
@@ -61,10 +82,13 @@ export default function astroAgentsExtension(pi: ExtensionAPI): void {
 
             ctx.ui.notify(`Running ${colorizePrefix(agent.name, agent.color)}…`, "info");
 
+            const skillPaths = agent.skills ? resolvePackageSkills(agent.skills, ctx) : [];
+
             const result = await runAgent({
                 agent,
                 task: input.task,
                 cwd: ctx.cwd,
+                skillPaths,
                 signal,
             });
 

package/extensions/astro-agents/spawn.ts

@@ -71,11 +71,12 @@ export interface RunAgentOptions {
     agent: AgentConfig;
     task: string;
     cwd: string;
+    skillPaths?: string[];
     signal?: AbortSignal | undefined;
 }
 
 export async function runAgent(options: RunAgentOptions): Promise<SpawnResult> {
-    const { agent, task, cwd, signal } = options;
+    const { agent, task, cwd, skillPaths, signal } = options;
 
     const args = ["--mode", "json", "-p", "--no-session"];
     let tmpDir: string | null = null;
@@ -84,6 +85,13 @@ export async function runAgent(options: RunAgentOptions): Promise<SpawnResult> {
         args.push("--tools", agent.tools.join(","));
     }
 
+    if (agent.skills && agent.skills.length > 0) {
+        args.push("--no-skills");
+        for (const skillPath of skillPaths ?? []) {
+            args.push("--skill", skillPath);
+        }
+    }
+
     if (agent.systemPrompt.trim()) {
         const tmp = writeSystemPromptTempFile(agent.name, agent.systemPrompt);
         tmpDir = tmp.dir;

package/extensions/grimoire/index.ts

@@ -3,18 +3,23 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import type { AgentToolResult } from "@mariozechner/pi-agent-core";
 import { Type } from "typebox";
 
-function loadGrimoireHelp(): string {
+function loadGrimoireHelp(): { help: string; available: boolean } {
     try {
-        return execFileSync("grimoire", ["--help"], {
+        const help = execFileSync("grimoire", ["--help"], {
             encoding: "utf-8",
             stdio: ["ignore", "pipe", "pipe"],
         }).trim();
+        return { help, available: true };
     } catch {
-        return "grimoire CLI not available on PATH at extension load time.";
+        return { help: "", available: false };
     }
 }
 
-const helpOutput = loadGrimoireHelp();
+const { help: helpOutput, available: grimoireAvailable } = loadGrimoireHelp();
+
+const NOT_INSTALLED_MESSAGE =
+    "grimoire CLI is not installed or not on PATH. Install it per your setup instructions " +
+    "(e.g. `npm install -g @astrofoundry/grimoire`), then restart pi so the extension can re-initialize.";
 
 const params = Type.Object({
     query: Type.String({ description: "Search query — use the library's own terminology." }),
@@ -30,17 +35,27 @@ export default function grimoireExtension(pi: ExtensionAPI): void {
         label: "Grimoire",
         description:
             "Search indexed technical documentation via the grimoire CLI. Prefer this over web search for library/framework docs.",
-        promptGuidelines: [
-            "Use `grimoire` for ALL documentation lookups — libraries, frameworks, APIs, CLIs, cloud services.",
-            "Match query terminology to the library's own docs (e.g. 'Firestore pagination cursors' not 'how do I paginate').",
-            "If the first search misses, rephrase or scope with `source`.",
-            "Cite the URL from results when precision matters.",
-            "",
-            "Current `grimoire --help` output:",
-            helpOutput,
-        ],
+        promptGuidelines: grimoireAvailable
+            ? [
+                  "Use `grimoire` for ALL documentation lookups — libraries, frameworks, APIs, CLIs, cloud services.",
+                  "Match query terminology to the library's own docs (e.g. 'Firestore pagination cursors' not 'how do I paginate').",
+                  "If the first search misses, rephrase or scope with `source`.",
+                  "Cite the URL from results when precision matters.",
+                  "",
+                  "Current `grimoire --help` output:",
+                  helpOutput,
+              ]
+            : [
+                  `grimoire CLI was NOT available when pi started. ${NOT_INSTALLED_MESSAGE}`,
+                  "Any call to this tool will return an error until grimoire is installed and pi is restarted.",
+              ],
         parameters: params,
-        async execute(_toolCallId, input, signal) {
+        async execute(_toolCallId, input, signal, _onUpdate, ctx) {
+            if (!grimoireAvailable) {
+                ctx.ui.notify("grimoire CLI not available — install it and restart pi.", "error");
+                throw new Error(NOT_INSTALLED_MESSAGE);
+            }
+
             return new Promise<AgentToolResult<unknown>>((resolve, reject) => {
                 const args = ["search", input.query, "--compact"];
                 if (input.source) args.push("--source", input.source);
@@ -74,16 +89,43 @@ export default function grimoireExtension(pi: ExtensionAPI): void {
                         );
                         return;
                     }
-                    const text = stdout.trim() || "(no results)";
+
+                    const output = stdout.trim();
+                    const isNoResults = output === "" || /^no results found\.?$/im.test(output);
+
+                    if (isNoResults) {
+                        const scopeNote = input.source ? ` in source '${input.source}'` : "";
+                        const suggestion = input.source
+                            ? "Try rephrasing the query or widening scope by omitting `source`."
+                            : "Try rephrasing with the library's own terminology, or check the indexed sources via `grimoire list --names`.";
+                        ctx.ui.notify(`grimoire: no results for "${input.query}"${scopeNote}`, "warning");
+                        resolve({
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `No results found for "${input.query}"${scopeNote}. ${suggestion}`,
+                                },
+                            ],
+                            details: { query: input.query, source: input.source, results: 0 },
+                        });
+                        return;
+                    }
+
                     resolve({
-                        content: [{ type: "text", text }],
+                        content: [{ type: "text", text: output }],
                         details: { query: input.query, source: input.source },
                     });
                 });
 
                 proc.on("error", (err) => {
                     signal?.removeEventListener("abort", abortHandler);
-                    reject(new Error(`grimoire CLI not runnable: ${err.message}`));
+                    const nodeErr = err as NodeJS.ErrnoException;
+                    if (nodeErr.code === "ENOENT") {
+                        ctx.ui.notify("grimoire CLI not available — install it and restart pi.", "error");
+                        reject(new Error(NOT_INSTALLED_MESSAGE));
+                        return;
+                    }
+                    reject(new Error(`grimoire CLI failed to run: ${err.message}`));
                 });
             });
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrofoundry/pi-astro",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Personal pi customizations (extensions, skills, prompts, themes) for the pi coding agent.",
   "keywords": [
     "pi-package"

package/skills/playwright-cli/SKILL.md

@@ -6,6 +6,54 @@ allowed-tools: Bash(playwright-cli:*)
 
 # Browser Automation with playwright-cli
 
+## Bypassing bot detection — use `attach --cdp` (IMPORTANT)
+
+If a site is guarded by Cloudflare / "Prove your humanity" / bot detection (Reddit, LinkedIn, X, CF-protected pages), **do NOT use `playwright-cli open`** — a launched Chromium gets blocked by `navigator.webdriver` / TLS / launch-flag fingerprinting.
+
+Instead, **attach to a real Chrome running with the CDP debug port**. This uses the user's genuine Chrome binary with a clean automation-free launch, so detection signals are absent.
+
+### Setup instructions to give the user
+
+```bash
+# User runs this once (in their own shell, not via the skill):
+mkdir -p ~/.chrome-profiles/pi-automation
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir="$HOME/.chrome-profiles/pi-automation" &
+```
+
+Notes:
+- An isolated `--user-data-dir` is **required** — Chrome 136+ refuses remote debugging on the default profile.
+- Path survives reboots; user logs into sites once and state persists in that profile.
+- To kill this Chrome later: `pkill -f "remote-debugging-port=9222"`.
+
+### Skill-side invocation
+
+```bash
+playwright-cli attach --cdp=http://localhost:9222
+playwright-cli goto https://www.reddit.com/r/popular/
+playwright-cli eval "() => document.title"
+```
+
+### Handling a human-verification challenge
+
+If `document.title` matches `/(Prove your humanity|Just a moment|Checking your browser|Access denied)/i` or the page body is empty after navigation, **a CAPTCHA is blocking the automation**. The attached Chrome window is visible to the user — stop, tell the user to solve it in that window, and resume after they confirm.
+
+Exact phrasing template:
+
+> "Captcha detected in the Chrome window — please solve it manually, then reply 'done' so I can resume."
+
+After the user replies, re-run `playwright-cli eval` to verify page content is now present, then continue with extraction.
+
+### When to prefer an API over playwright-cli entirely
+
+If the target site has a public JSON/REST endpoint, use `curl` with a proper User-Agent instead — faster, no CAPTCHA, no browser needed:
+- Reddit: `curl -H "User-Agent: …" https://www.reddit.com/r/popular.json`
+- Hacker News: `curl https://hacker-news.firebaseio.com/v0/topstories.json`
+- GitHub: `gh api` or the public REST API
+
+Reach for browser automation only when no API exists.
+
 ## Quick start
 
 ```bash