@astrofoundry/pi-astro 0.2.9 → 0.2.11

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

@@ -1,6 +1,7 @@
 ---
 name: code-reviewer
-description: Use this agent to review code for quality, security, correctness, and spec compliance. It is read-only — it reports issues with severity and remediation guidance but does not modify code. It reviews TypeScript strictness, React patterns, Express middleware, Firestore security rules, Firebase Auth flows, accessibility, performance, design system token usage, test quality, and compliance with project specs. Examples:\n\n<example>\nContext: Reviewing a pull request\nuser: "Review the changes in the last 3 commits on the feature/order-webhooks branch. Check for security issues, TypeScript quality, spec compliance, and test coverage."\nassistant: "I'll review the branch changes. Let me use the code-reviewer agent — it will read every changed file, cross-reference against the project specs, check for security vulnerabilities and TypeScript issues, and report findings by severity."\n<commentary>\nPR reviews require reading all changed files, understanding the intent from specs, and checking across multiple dimensions: security, quality, correctness, and compliance.\n</commentary>\n</example>\n\n<example>\nContext: Reviewing Firestore security rules\nuser: "Review the Firestore security rules in firestore.rules. Check that they enforce proper access control for all collections, validate data shapes, and don't have any overly permissive rules."\nassistant: "I'll audit the security rules. Let me use the code-reviewer agent to verify each rule against the data model, check for overly broad permissions, and ensure validation is complete."\n<commentary>\nFirestore rules are a critical security boundary — a single permissive rule can expose entire collections.\n</commentary>\n</example>\n\n<example>\nContext: Reviewing a React component against its screen spec\nuser: "Review the ProductsListPage component at src/pages/products/ProductsListPage.tsx against the screen spec at docs/ui/ui-specs/ui-07-products-list.md. Check that it implements everything in the spec, uses the correct design system tokens, and follows React best practices."\nassistant: "I'll review the component against its spec. Let me use the code-reviewer agent to compare the implementation point-by-point with the screen spec and flag any deviations, missing states, or token misuses."\n<commentary>\nSpec compliance review catches missed requirements, wrong token usage, and missing edge cases that functional testing alone might miss.\n</commentary>\n</example>
+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

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

@@ -1,6 +1,7 @@
 ---
 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>
+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

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

@@ -1,6 +1,7 @@
 ---
 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>
+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

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

@@ -1,6 +1,7 @@
 ---
 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>
+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

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

@@ -1,6 +1,7 @@
 ---
 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>
+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

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

@@ -1,6 +1,7 @@
 ---
 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>
+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

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

@@ -1,6 +1,7 @@
 ---
 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>
+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

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

@@ -1,6 +1,7 @@
 ---
 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>
+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

package/extensions/claude-globals/index.ts

@@ -0,0 +1,17 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+const CLAUDE_GLOBAL_PATH = path.join(os.homedir(), ".claude", "CLAUDE.md");
+
+export default function claudeGlobalsExtension(pi: ExtensionAPI): void {
+    pi.on("before_agent_start", async (event) => {
+        if (!fs.existsSync(CLAUDE_GLOBAL_PATH)) return;
+        const content = fs.readFileSync(CLAUDE_GLOBAL_PATH, "utf-8").trim();
+        if (!content) return;
+        return {
+            systemPrompt: `${event.systemPrompt}\n\n<claude-global-rules source="~/.claude/CLAUDE.md">\n${content}\n</claude-global-rules>`,
+        };
+    });
+}

package/package.json

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