afd

Agent-First Development methodology for building software where AI agents are first-class users. Covers command design, CLI validation, MCP servers, CommandResult schemas, testing strategies, and the core AFD philosophy. Use when: building agent-ready apps, designing commands, integrating MCP, understanding AFD patterns, or following the command-first workflow. Triggers: agent-first, AFD, command-first, MCP server, CommandResult, CLI validation, afd call, honesty check, define-validate-surface.

Python implementation patterns for AFD commands using Pydantic models, afd package, and FastMCP. Covers command definition with decorators, schema design, error handling, MCP server setup, and testing. Use when: implementing commands in Python, setting up Python MCP servers, writing Pydantic models, or debugging Python AFD code. Triggers: python afd, py command, pydantic model, @server.command, python implementation, fastmcp, afd python.

Rust implementation patterns for AFD commands using the afd crate, CommandResult types, and async handlers. Covers command definition, schema design with JSON Schema, error handling, registry patterns, and testing. Use when: implementing commands in Rust, building Rust MCP servers, working with CommandResult types, or debugging Rust AFD code. Triggers: rust afd, rs command, CommandResult rust, CommandHandler, rust implementation, afd crate, cargo afd.

Agent-First Development (AFD) patterns for building software where AI agents are first-class users. Covers command design, CLI validation, MCP servers, CommandResult schemas, and testing strategies. Use when building agent-ready apps, designing commands, or integrating MCP.

TypeScript implementation patterns for AFD commands using Zod schemas, @lushly-dev/afd-server, and @lushly-dev/afd-core. Covers command definition, schema design, error handling, MCP server setup, embeddable Node handlers, and testing. Use when: implementing commands in TypeScript, setting up MCP servers, writing Zod schemas, or debugging TypeScript AFD code. Triggers: typescript afd, ts command, zod schema, defineCommand, createMcpServer, createMcpHandler, @lushly-dev/afd-server, @lushly-dev/afd-core, typescript implementation.

Version bump, changelog finalize, build, test, tag, publish to registries, and create GitHub Release. Language-aware for TypeScript (npm), Python (PyPI), and Rust (crates.io). Delegates to manage-git for tagging strategy and manage-documentation for changelog format. Use when ready to release a new version.

Guides orchestration of system migrations, framework upgrades, dependency version bumps, database schema evolution, and codemod generation with safe incremental transformation patterns. Covers strangler fig, expand-contract, parallel run, dual-write verification, feature-flag-gated rollouts, AST-based codemods (jscodeshift, ts-morph, libcst), and agentic migration workflows where AI agents discover, transform, verify, and land changes at scale. Use when upgrading frameworks, migrating APIs, evolving database schemas, generating codemods, planning incremental migrations, or orchestrating large-scale automated refactors. Triggers: migrate, migration, upgrade, codemod, schema evolution, strangler fig, expand-contract, version bump, framework upgrade, dependency upgrade, database migration.

Guidance for designing optimistic mutation flows in interactive AFD clients. Covers when optimistic updates are appropriate, how to separate visual state, view-state, and business data, how to reconcile command results, and how to pair optimistic UI with AFD features like output schemas, reasoning, warnings, and undo metadata. Use when building or reviewing toggles, reordering, create flows, autosave, or other latency-sensitive mutations in user-facing apps. Triggers: optimistic UI, optimistic mutation, rollback, reconcile, pending state, temporary ID, optimistic reorder, optimistic create, autosave.

Guides usage of botcore's development commands for linting, testing, building, quality gates, and static analysis. Covers dev_lint/dev_test/dev_build (language-aware dispatch), quality checks (file size, coverage, dependency staleness), static analysis (dead code, circular imports, unused deps, dependency graphs), portability checks, and skill linting. Use when running dev checks, understanding quality thresholds, diagnosing lint or test failures, analyzing code quality, or checking cross-platform portability. Triggers: dev lint, dev test, dev build, coverage, file size, dead code, circular imports, unused deps, dependency graph, portability, skill lint.

Guides browser automation via botcore's CDP (Chrome DevTools Protocol) command suite. Covers session management (launch/attach/close), navigation and waiting, element interaction (click/type/fill/drag), DOM inspection with Shadow DOM traversal, diagnostics (screenshot/console/network/eval), form filling, multi-page management, and device emulation. Use when automating browsers, scraping web pages, testing web UIs, filling forms, taking screenshots, debugging frontend issues, or working with Shadow DOM components. Triggers: CDP, browser, Chrome, Chromium, automation, screenshot, click, fill form, Shadow DOM, console log, navigate, scrape, headless.

Guides development of botcore plugins from protocol implementation to distribution. Covers BotCorePlugin protocol, PluginRegistry API, async command authoring with AFD/CommandResult, MCP server factory (create_mcp_server, meta-tool pattern), CLI generation (build_namespace), entry-point registration, docs registration, and skills directory bundling. Use when building a new botcore plugin, adding commands to a plugin, registering entry points, or integrating with the MCP server factory. Triggers: plugin, botcore plugin, BotCorePlugin, PluginRegistry, entry point, command authoring, CommandResult, MCP server, create_mcp_server, build_namespace, plugin protocol, register commands.

Guides configuration of botcore projects via botcore.toml or pyproject.toml. Covers BotCoreConfig model, SkillsConfig, PackageOverrideConfig, EnvConfig, language detection and tool defaults, per-package overrides, precedence rules, plugin config validation, and common misconfiguration pitfalls. Use when setting up a new botcore project, configuring thresholds, adding per-package overrides, troubleshooting config-related silent failures, or understanding the config loading flow. Triggers: config, configuration, botcore.toml, pyproject.toml, BotCoreConfig, thresholds, language detection, tool defaults, per-package, SkillsConfig.

Periodic deep cleanup of repository-level cruft — stale branches, orphaned worktrees, dead test files, agent artifacts, dangling configs, and build output. Confirms destructive actions before executing. Use when a repo feels cluttered or before major milestones.

Run a documentation update pass across CHANGELOG, AGENTS.md, README.md, and skill files. Ensures docs reflect current code state with proper changelog formatting, semver alignment, and version-tag consistency. Standalone skill — invoke directly, not only as part of do-commit.

Provider-agnostic authentication adapter for AFD applications. Covers AuthAdapter interface, discriminated union session states, middleware for auth-gated commands, AFD command wrappers, multi-tab session sync, React hooks, and built-in adapters (Mock, Convex, BetterAuth). Triggers: auth, authentication, sign-in, sign-out, session, auth adapter, auth middleware, auth commands, convex auth, better-auth.

Guides software architecture decisions across patterns, trade-offs, and documentation. Covers monolith vs microservices, modular monoliths, event-driven architecture, CQRS, hexagonal/ports-and-adapters, DDD bounded contexts, ADRs, evolutionary architecture with fitness functions, and platform engineering. Use when designing system architecture, choosing patterns, writing ADRs, decomposing domains, evaluating trade-offs, or planning migrations. Triggers: architecture, system design, microservices, monolith, DDD, bounded context, event-driven, CQRS, ADR, hexagonal, fitness function, platform engineering.

Performs OSS license compliance audits, dependency license analysis, and SBOM generation. Covers license categorization (permissive, copyleft, public domain), compatibility matrices, per-ecosystem audit tooling (Node.js, Python, Go), CI/CD license gate integration, required attribution files, and red-flag detection. Use when adding dependencies, auditing existing licenses, checking compatibility, generating SBOMs, preparing for release, or setting up license enforcement in CI. Triggers: license, licensing, OSS compliance, SBOM, GPL, MIT, Apache, copyleft, dependency audit, license check, attribution, SPDX, CycloneDX, bill of materials.

Performs comprehensive security audits of web applications, APIs, MCP servers, and AI agent systems. Covers OWASP/CWE vulnerability discovery, threat modeling, SAST/DAST/SCA tooling, MCP server hardening, agentic review orchestration, supply chain security, secret management, risk prioritization, and structured reporting. Use when performing security audits, reviewing code for vulnerabilities, hardening MCP servers, designing agent permission models, building CI/CD security gates, or generating audit reports. Triggers: security audit, vulnerability, OWASP, CWE, threat model, injection, XSS, SSRF, MCP security, agent security, SAST, DAST, SCA, secrets scanning, supply chain, SBOM, penetration test, security checklist, access control, authentication, sanitize.

Guides construction of MCP servers using FastMCP 2.x with emphasis on token budget management, tool consolidation, output truncation, and the execute pattern for Opus compatibility. Covers async subprocess patterns, safe output limits, and action-based tool design. Use when creating MCP servers, debugging tool overload or context overflow, optimizing token usage, fixing Opus silent failures, or consolidating tools. Triggers: MCP, FastMCP, tool schema, token limit, context overflow, MCP server, execute pattern, tool consolidation.

Guides creation of Storybook 10 stories using CSF3 format, Custom Elements Manifest (CEM) integration, play function interaction tests, visual testing, and accessibility checks for web components. Covers story file structure, naming conventions, autodocs configuration, addon-vitest headless test loops, addon-a11y, coverage reporting, and shadow DOM assertion patterns. Use when writing stories, adding interaction tests to stories, configuring Storybook for web components, debugging play functions, or setting up story-based visual and accessibility testing. Triggers: storybook, story, stories, csf3, cem, custom elements manifest, play function, interaction test, visual testing, addon-vitest, autodocs.

Creates and manages agentic personas for role-based review and synthetic user testing. Covers persona YAML structure, data ingestion, LLM simulation, validation loops, and CI/CD integration. Use when creating user personas, simulating user feedback, conducting role-based reviews, validating features with synthetic users, or generating persona-driven critiques. Triggers: create persona, user persona, agentic persona, user simulation, persona review, role-based review, persona feedback, synthetic user.

Provides expert guidance for creating VS Code Copilot prompt files (.prompt.md) used as reusable slash commands. Covers frontmatter schema, agent modes, tool scoping, variables, prompt patterns (review, generate, summarize, delegate, transform, multi-step, session init), naming conventions, and best practices. Use when creating new prompt files, reviewing prompt quality, designing prompt architecture, or improving existing prompts. Triggers: prompt file, .prompt.md, slash command, create prompt, prompt template, agent prompt, copilot prompt, reusable prompt, /command.

Guides containerization, CI/CD pipeline setup, and production deployment. Covers Dockerfile best practices, GitHub Actions workflows, secret management, health checks, resource limits, environment parity, and rollback strategies. Use when building Docker images, configuring pipelines, preparing deployments, or reviewing infrastructure code. Triggers: Docker, CI/CD, deployment, Kubernetes, pipeline, container, GitHub Actions, infrastructure, deploy.

Provides API design guidance for REST, GraphQL, and gRPC services covering naming conventions, resource modeling, versioning strategies, error handling (RFC 9457), pagination patterns, OpenAPI 3.1 specification authoring, security (OAuth 2.1, rate limiting), and agent-friendly design patterns including MCP tool integration. Use when designing new APIs, reviewing API contracts, choosing between REST/GraphQL/gRPC, implementing error handling or pagination, writing OpenAPI specs, or making APIs consumable by AI agents. Triggers: API design, REST, GraphQL, gRPC, OpenAPI, error handling, pagination, versioning, API security, agent-friendly API, MCP tools, API-first.

Guides UX writing for user-facing interface text. Covers UI labels, button text, error messages, empty states, tooltips, dialog copy, headings, capitalization rules, voice and tone, and product terminology. Use when writing or reviewing any user-facing text in a prototype or production UI, crafting error messages, defining empty state copy, choosing button labels, or enforcing consistent terminology. Triggers: content design, UX writing, UI text, error message, button label, empty state, tooltip, dialog text, capitalization, terminology, microcopy, voice and tone.

Run quality gates, clean up temp files, update docs, and commit changes. Two modes: quick (automated checks + commit) and full (checks + cleanup + docs gate + self-review + commit). Delegates to write-commits for message generation. Use when ready to finalize and commit changes.

Create a hotfix branch from the latest release tag, apply a minimal targeted fix, verify with quality gates, and fast-track through commit and PR. Enforces scope discipline — hotfixes are minimal fixes only, no refactoring or features. Delegates to do-commit and do-pr for the landing steps. Use for emergency or urgent production fixes.

Push branch and create a pull request with structured description, linked issues, and review configuration. Verifies branch readiness, generates PR description from commits and diff, and creates the PR via CLI or API. Use when ready to submit work for review.

Review code changes — either self-review your own uncommitted work or review an incoming pull request. Routes on argument: no args for self-review, PR reference for PR review. Delegates to the review-code skill for methodology and structured feedback. Use when reviewing changes before committing or reviewing a PR.

Enforces language-specific coding conventions for Python, TypeScript, HTML, and CSS. Covers style rules, naming conventions, type safety, error handling, security practices, and performance patterns. Use when writing new code, reviewing pull requests, refactoring existing code, or applying linting and formatting rules. Triggers: code review, coding standards, Python style, TypeScript conventions, ESLint, Prettier, formatting, linting, BEM, PEP 8, type hints, error handling, security, performance, naming conventions.

Provides comprehensive accessibility review, guidance, and implementation patterns for WCAG 2.1+ AA compliance. Covers keyboard navigation, ARIA roles and states, screen reader support, assistive technology analysis, compliance frameworks (Section 508, ADA, EN 301 549, EAA, ACA, CVAA), UX component patterns, and accessible content authoring. Use when building interactive components, auditing UI for accessibility, implementing focus management, reviewing designs or specs against WCAG, mapping issues to compliance frameworks, or creating accessibility checklists. Triggers: accessibility, a11y, WCAG, ARIA, keyboard navigation, screen reader, assistive technology, focus management, inclusive design, compliance, Section 508, ADA.

Tracks cutting-edge CSS features, CSSWG specifications, and browser support status. Covers emerging layout primitives (Grid Lanes, Gap Decorations, Anchor Positioning), new selectors and scoping mechanisms, adoption tiers, and progressive enhancement strategies. Use when evaluating new CSS capabilities for production readiness, planning layout strategies with emerging specs, checking browser support for modern CSS, or reviewing CSSWG decisions that affect component architecture. Triggers: modern css, new css, css features, csswg, grid lanes, masonry, gap decorations, anchor positioning, css nesting, container queries, scope, css frontier, emerging css, flex-wrap balance, view transitions, starting-style.

Detects code duplication using hybrid analysis combining algorithmic (JSCPD) and semantic (AI) techniques. Covers Type-1 through Type-4 clone detection, safe refactoring workflows, and duplication prevention strategies. Use when scanning for copy-paste code, reducing code bloat, consolidating duplicate utilities, or improving DRY compliance. Triggers: duplicates, duplication, copy paste, code clone, DRY, refactor.

Guides authentication and authorization design for web applications, APIs, and AI agent systems. Covers OAuth 2.1, OIDC, passkeys/WebAuthn, RBAC/ABAC/ReBAC, Cedar policy language, session management (JWT vs server sessions), multi-tenant patterns, zero trust continuous verification, MCP server auth, and agentic identity with machine-to-machine delegation. Use when designing login flows, implementing authorization, adding passkeys, configuring SSO, building multi-tenant auth, securing MCP servers, or managing AI agent credentials. Triggers: authentication, authorization, OAuth, OIDC, passkey, WebAuthn, RBAC, ABAC, session, JWT, token, multi-tenant, SSO, MFA, zero trust, MCP auth, agent identity, delegation.

Provides error handling patterns and recovery strategies for TypeScript and Python applications. Covers custom error hierarchies, Result/Either types (neverthrow, Effect), discriminated union errors, retry with exponential backoff and circuit breakers, RFC 9457 structured API error responses, exception groups, error observability, and agent-safe error recovery with graceful degradation. Use when designing error handling strategies, implementing Result types, adding retry logic, building error hierarchies, creating structured API errors, or making agent workflows resilient. Triggers: error handling, Result type, Either, neverthrow, Effect, retry, circuit breaker, backoff, error hierarchy, RFC 9457, error recovery, exception, try-catch, error boundary, structured errors, error logging.

Identifies and remediates AI-generated text patterns including lexical signatures, syntactic rigidity, and structural tells that flag content as machine-written. Covers vocabulary replacement, sentence variation, specificity injection, and voice transformation across all content types. Use when reviewing content for authenticity, improving AI drafts, eliminating robotic writing patterns, or auditing text before publishing. Triggers: humanize, AI detection, sounds like AI, robotic writing, AI tells, machine-written, synthetic text, ai content, ai patterns, writing style.

Guides caching strategy selection and implementation across the full stack including HTTP caching, application-level caching (Redis, in-memory), frontend data caching (SWR, TanStack Query), LLM response caching (prompt caching, semantic caching), database query caching, cache invalidation patterns, and distributed cache architectures. Covers cache-aside, read-through, write-through, write-behind patterns, eviction policies (LRU/LFU), and agentic workflow caching considerations. Use when adding caching to an application, choosing a caching strategy, debugging stale data, optimizing API response times, reducing LLM costs, or designing distributed cache topologies. Triggers: cache, caching, Redis, CDN, TTL, cache invalidation, stale data, Cache-Control, ETag, SWR, TanStack Query, prompt caching, semantic cache, LRU, write-through, cache-aside, materialized view.

Guides the Figma design-to-code workflow using MCP integration, token extraction, and structured implementation. Covers Figma MCP setup, authentication, URL parsing, design context retrieval, token translation from Tailwind/Figma output to CSS custom properties, icon identification, asset management, and Code Connect mapping. Use when implementing a design from Figma, setting up the Figma MCP server, extracting design specs, translating design tokens, or converting React/Tailwind output to web components. Triggers: figma, design, design-to-code, implement design, figma link, screenshot, mcp, design tokens, figma mcp.

Guides implementation of internationalization and localization in web applications. Covers string externalization, pluralization, date/number/currency formatting, RTL layout support, translation file structure, translation workflows, and library selection across JavaScript, React, Vue, and Python ecosystems. Use when adding multi-language support, preparing for international markets, handling RTL layouts, formatting locale-sensitive data, externalizing hardcoded strings, or setting up translation pipelines. Triggers: i18n, internationalization, l10n, localization, translations, RTL, locale, language, multi-language, right-to-left, Intl, pluralization, translation files, react-intl, i18next, vue-i18n, gettext, string externalization.

Guides implementation of structured logging, metrics collection, and distributed tracing for production services. Covers the three pillars of observability (logs, metrics, traces), OpenTelemetry integration, correlation ID propagation, alerting thresholds, and common anti-patterns. Use when adding monitoring to a service, debugging production issues, improving error visibility, setting up alerting, or instrumenting business metrics. Triggers: observability, logging, metrics, tracing, monitoring, OpenTelemetry, alerts, instrumentation, structured logs, correlation ID.