praxion

CI/CD pipeline design and GitHub Actions workflow authoring: pipeline architecture, testing stages, deployment strategies, caching, secrets management, security hardening, performance optimization. Triggers: creating CI/CD pipelines, writing GitHub Actions workflows, configuring automated testing, setting up deployment automation, debugging workflow failures, optimizing pipeline performance, reviewing CI/CD config, designing deployment pipelines, implementing build automation.

Application deployment: Docker Compose (watch mode, profiles, GPU passthrough, health checks), PaaS, cloud containers, Kubernetes, AI-native GPU platforms, reverse proxy, secrets management, AI/ML model serving. Triggers: deploying an app, writing compose.yaml or Dockerfile, choosing a hosting platform, configuring Caddy/nginx, deploying Ollama/vLLM, GPU passthrough, choosing Render/Railway/Fly.io/ Vercel, managing Railway environments or PR environments, wiring Railway's agent plugin/MCP/CLI, deploying to Cloud Run/ECS/Modal/CoreWeave, writing systemd units for Compose. Siblings: cicd-engineer (pipeline automation), observability (monitoring).

Planning complex software tasks via a three-document model (IMPLEMENTATION_PLAN.md, WIP.md, LEARNINGS.md) in small, known-good increments. Triggers: starting significant development, breaking down complex features, architecture planning, multi-session projects, feature breakdown, work planning, task tracking, WIP management, incremental development. Language modules available for Python, TypeScript.

Behavioral specification methodology with requirement traceability for medium and large features: spec format (When/and/the system/so that), complexity triage (trivial through spike), REQ ID conventions, REQ-* traceability threading through the pipeline, decision documentation, spec archival. Triggers: behavioral specifications, requirement traceability, SDD methodology, spec format, REQ IDs, spec-driven development, complexity triage, spec archival.

Interpret and act on the Agent Readiness score produced by /project-metrics: 8 Factory pillars × 5 maturity levels × 80%-per-level gate + Praxion-native Pillar 9 Manageability sub-score. Read the readiness block from METRICS_REPORT_*.json, understand the LLM-judged criteria (naming_conventions, test_quality, readme_quality, docs_agent_friendliness), prioritize remediation by failing criterion → pipeline handoff, and interpret level-by-level progress. Triggers: reading or acting on an agent readiness report, understanding why a project scored a given level, deciding how to improve readiness, interpreting mechanical vs LLM criteria, running readiness without an API key, grounding a new readiness run on a prior report.

Task-intake protocol for turning a fuzzy user request into an unambiguous, verifiable goal before committing to a direction. Covers the ask-vs-proceed decision rule (the 2x2 of intent-clarity x reversibility), lexical ambiguity detection, the XY-problem test, assumption surfacing over interrogation, Mom-Test question phrasing with a hard 3-question cap, and capturing measurable outcome signals (Intent / Key Signals / Health Guards / Uncertainty Flag) into a TASK_BRIEF.md that seeds downstream architecting, planning, testing, and verification. Triggers: at the start of any non-trivial task when the request is vague, implementation-first, or its success is not measurable; deciding whether to ask the user a clarifying question or proceed with stated assumptions; capturing acceptance criteria / definition-of-done at intake; reducing rework from misread intent.

AI agent evaluation: Inspect AI/DeepEval/Promptfoo framework selection, golden datasets, LLM-as-judge, grader design, scoring, non-determinism handling, CI/CD integration. Triggers: evaluating agent behavior, choosing an eval framework, designing eval suites, building golden datasets, trajectory evaluation, eval-driven development, integrating evals into CI/CD. Python-focused; TypeScript coverage (Vitest + Promptfoo) in references/typescript.md.

CLI/TUI design craft: clig.dev contract, output discipline (data→stdout, messages→stderr, NO_COLOR, --json), help-text levels, three-part error messages (what/why/fix), TTY detection, exit codes, TUI frameworks (Python textual+rich, Node Ink, Go Charm/Bubble Tea+Lip Gloss), render discipline (diff-before-render, DECSET 2026, stream-as-it-arrives), terminal accessibility. Triggers: designing/ reviewing CLI tools, agent terminal output, TUIs, help text, error messages, exit codes, choosing a TUI framework. Not for web UI (web-ui-design) or agent-tool design (api-design-craft, agentic-interface-design).

Retrieving current API documentation for external libraries and SDKs: search strategies, token-aware fetching (chub_search, chub_get, chub_annotate, chub_feedback), annotation persistence, provider fallback. Triggers: writing code against Stripe/OpenAI/Anthropic/AWS/FastAPI/Supabase or any external API, debugging an integration, evaluating SDK capabilities, looking up endpoint signatures/parameters, guarding against training-data staleness; external API reference, SDK docs lookup, current API signatures, integration reference.

Detect and remove ephemeral identifier citations (REQ-*, AC-*, EC-X.X.X, Step N, req{NN}_ test naming) from project source code. Triggers: pre-discipline Praxion project, check_id_citation_discipline.py reports violations, user asks to "clean up REQ citations"/"decontaminate id references"/"remove pipeline residues from code", /decontaminate-ids invoked.

Produces ROADMAP.md from a full-project audit via a project-derived lens set. Covers paradigm detection (deterministic/agentic/hybrid), lens-set derivation (SPIRIT, DORA, SPACE, FAIR, CNCF Platform Maturity, Custom), parallel audit fan-out, lens synthesis, multi-angle reframing, grounded claim generation. Triggers: ultra-in-depth project analysis, spring cleaning roadmap, project state of the union, lens-based audit, strengths/weaknesses/deprecations roadmap, agentic-era project evaluation, AGENTS.md-aware audit, SDLC health audit. Contrast with `roadmap-planning` (prioritizes existing backlog).

Writing and maintaining project documentation: README.md, catalogs, architecture docs, changelogs, Mermaid diagrams. Cross-reference validation, catalog maintenance, freshness checks, structural integrity. Triggers: creating/reviewing/ fixing documentation, maintaining catalog READMEs, verifying filesystem state match, documentation audit, checking doc freshness, authoring diagrams.

Decision rubric and recipes for querying LikeC4 architecture models: `likec4` MCP tools vs. reading `.c4` files directly. Path-scoped to architecture-authoring surfaces. Triggers: authoring/modifying DESIGN.md, .c4 files, diagram sources, exploring LikeC4 model for design decisions.

Producing best-in-class documentation of your OWN API surface for both humans and AI agents: REST/OpenAPI reference docs, Python and TypeScript library/service docs, GraphQL schema docs, MCP server docs from tools/list introspection, and agent-consumable docs (llms.txt). Covers spec-as-source-of-truth, the human-vs-agent divergence, mandatory doc sections (quickstart/auth/RFC9457 errors/pagination/ rate-limit/changelog), and docs-as-CI-artifact. Triggers: document my API, API reference docs, OpenAPI docs, MCP server docs, GraphQL schema docs, agent-consumable docs, llms.txt, document a REST/Python/TypeScript API surface.

Application observability: structured logging, metrics design, distributed tracing, alerting. Three pillars, RED/USE, SLI/SLO/error budgets, OpenTelemetry instrumentation, cardinality management. Triggers: adding observability, choosing logging/metrics/tracing strategy, designing alert rules, defining SLIs/SLOs, instrumenting OpenTelemetry, reviewing coverage; monitoring, telemetry, OTel, spans, log levels, burn-rate alerting, Prometheus naming, Grafana dashboards, trace context propagation, metrics cardinality, runbooks, on-call, SLA, log aggregation, trace analysis.

The un-bypassable runtime-enforcement layer for agentic apps: input validation, structured-output enforcement, tool-call gating, and budget/permission enforcement, via the deterministic-harness pattern. Triggers: design, build, or verify guardrails that enforce model I/O and gate tool calls regardless of model output. Prevention — not SDK mechanics (agentic-sdks), not failure classification (agent-failure-taxonomy).

Classification rubric for runtime failure modes of agentic AI apps (Microsoft AI Red Team taxonomy: prompt injection, excessive agency, tool abuse). Triggers: classify or diagnose an observed agent failure, or run a design-time failure-mode review. Diagnosis — not prevention (agent-runtime-guardrails), not plugin security (context-security-review).

Structured code review methodology: finding classification (PASS/FAIL/WARN), language adaptation, report templates. Triggers: reviewing code for convention compliance, post-implementation verification, pull request review, PR review, code audit, code quality checks.

Composition layer for multi-perspective deliberation primitives: calibrated confidence annotation, lens-independence discipline, heterogeneous model orchestration (Haiku-proposer / Opus-aggregator), and two-tier disconfirmation (Tier-A always-on for architectural ADRs; Tier-B cross-model adversarial challenge gated to high-stakes contested decisions). Triggers: high-stakes design decisions with genuine uncertainty, adversarial stress-testing of architectural choices, calibrating confidence on research claims, parallel lens fan-out that must remain independent, pre-mortem failure-imagination at planning→implementation boundary.

Architectural fitness functions: ArchUnit-style invariants via import-graph tooling and assertion-based tests, decision rubric (graph-rule vs assertion), citation contract (ADR/CLAUDE.md), waiver pattern. Triggers: authoring fitness rules, deciding between graph-rule and assertion-based invariants, authoring a fitness waiver. Language modules available for Python, TypeScript.

Pragmatic refactoring: modularity, low coupling, high cohesion, incremental improvement. Triggers: restructuring code, improving design, reducing coupling, organizing codebases, extracting modules, eliminating code smells, refactoring patterns/code organization, cleaning up code, addressing technical debt, splitting modules, simplifying complex code.

Software design principles for the AI era — SOLID reframed as heuristics in service of balanced coupling (managing knowledge flow between components), plus the agent-as-consumer lens. Covers single responsibility, open/closed, Liskov substitution, interface segregation, dependency inversion, low coupling / high cohesion, integration strength vs distance vs volatility, and why generation speed raises the stakes. Triggers: applying or reviewing SOLID, deciding whether to introduce an abstraction, reducing coupling, improving cohesion, designing module/interface boundaries, designing a surface an AI agent will consume, judging whether a design will accrue debt under fast code generation. Use up-front during architecture and design, not only during refactoring.

Interface design for the model as consumer: MCP tools, function-calling schemas, A2A contracts (Agent Cards). Human-vs-agent ergonomics, tool naming, error grammar, fat-vs-thin decomposition, progressive disclosure (lazy loading), idempotency (request_id), response pagination (next_cursor, has_more), JSON-schema craft. Triggers: designing/reviewing MCP tools, tool descriptions, function-calling schemas, agent error ergonomics, A2A contracts. Not for web/CLI (web-ui-design, tui-design) or REST/GraphQL quality (api-design-craft).

API quality, taste, and review craft — the layer above api-design methodology. Canonical APIs (Stripe, S3, Linear, GitHub, Twilio, Resend), Bloch core as review checklist, robust-API canon (RFC 9457, cursor pagination, idempotency, versioning), REST vs GraphQL vs gRPC selection, HTTP status code semantics (Retry-After, 422 vs 400), PATCH semantics, webhook design, long-running ops, low-latency ergonomics (N+1, ETag, DataLoader). Triggers: reviewing API quality, applying a taste lens, choosing a paradigm, designing error contracts/pagination/webhooks, evaluating latency ergonomics. Methodology in api-design; agentic tool design in agentic-interface-design.

API design methodology: API-first/design-first development, resource modeling, endpoint naming, HTTP semantics, OpenAPI 3.1 schema patterns, GraphQL schema design, API versioning strategies, schema evolution, contract testing concepts, consumer-driven contracts, service boundary definition, REST vs GraphQL. Triggers: designing APIs, writing OpenAPI specs, defining data contracts, planning API versioning, designing interface contracts, reviewing API surface design.

Building MCP (Model Context Protocol) servers with official SDKs: protocol concepts (tools, resources, prompts), transports (stdio, streamable HTTP), bundles (.mcpb), MCP Inspector testing, client integration with Claude Desktop and Claude Code, logging, error handling, security. Triggers: creating MCP servers, defining MCP tools/resources, configuring transports, packaging bundles, testing servers, integrating with Claude; MCP tool definition, MCP resource exposure, FastMCP server patterns. Language modules available for Python (FastMCP) and TypeScript (@modelcontextprotocol/sdk).

ML training job dispatch abstraction for Praxion ML/AI projects: mode-invariant training_job_descriptor schema, four backends (local subprocess, SkyPilot 20+ providers, RunPod and Nebius direct adapters). Triggers: configuring a compute backend, dispatching via /run-experiment, reading/writing training_job_descriptor YAML or neo_cloud_backend.yaml, debugging backend dispatch errors, choosing local vs SkyPilot vs RunPod vs Nebius, subprocess training, GPU cloud dispatch, Nebius, backend: nebius-direct. Activate alongside ml-training and llm-training-eval for full pipeline work.

Prompt engineering for LLMs: few-shot patterns, chain-of-thought, reasoning-effort control, structured output via Pydantic/Zod, prompt versioning, prompt testing (single-prompt regression assertions). Framework-agnostic. Triggers: designing prompts for production LLM calls, writing system prompts, debugging output-quality issues, migrating across model versions, picking a prompt-management platform, establishing prompt regression tests. Defers to claude-ecosystem for Claude-specific features, agentic-sdks for agent-loop plumbing, agent-evals for eval design, external-api-docs for current SDK signatures. Language modules available for Python and TypeScript.

Security review methodology for Claude Code plugin ecosystems: context artifact injection, hook compromise, dependency supply chain, script injection, secrets exposure, GitHub Actions security. Triggers: reviewing PRs for security, conducting security audits, verifying agent permissions, reviewing hook scripts, checking for secrets, assessing context artifacts (CLAUDE.md, skills, agents, rules, commands, hooks).

Python development conventions: type hints, pytest, code quality tools (ruff, mypy, pyright), data modeling (dataclasses, Pydantic), async patterns, error handling, structural pattern matching. Triggers: writing Python code, implementing tests, configuring linting/formatting, choosing between dataclasses and Pydantic, pytest fixtures and parametrize, ruff formatting/linting, mypy type checking, pytest configuration.

TypeScript development: strict-mode type system, Biome v2 (greenfield)/ESLint v9 (framework projects), Vitest test discipline, React 19/Next.js 15/Vite, Vue 3/ Nuxt 3. Triggers: writing/reviewing TypeScript source files, configuring tsconfig, choosing linter/formatter, setting up Vitest, bare-TS/Node services, React or Vue projects. Layered contexts: TypeScript baseline, React, Vue.

Provider contract, decision rubric, and composition guidance for implementing agentic transactions in a managed project — covering both Space A (agentic payments: mandate-based payment rails, stablecoin/card/crypto settlement) and Space B (agentic trading: brokerage order placement, market data, portfolio positions). Triggers: agentic payment, agentic trading, Provider contract, mandate, settlement finality, HITL spend-gating, brokerage agent, MCP trading, order execution, payment rail, idempotency key, TransactionError, supports_sandbox. Activate when a managed project needs to implement agentic payments or stock trading behind a provider-pluggable contract. Language modules not applicable — the contract is language-independent; a Python binding sketch is in references/provider-contract.md.

Language-independent testing knowledge: test strategy selection, test pyramid, mocking philosophy, fixture/test-data patterns, test isolation, coverage approach, property-based testing, naming conventions. Triggers: deciding test strategy, choosing unit/integration/e2e tests, designing mocking boundaries, architecting fixtures, evaluating coverage philosophy, assessing property-based testing; test architecture, testing methodology, test isolation.

Generate or refresh a project-local AGENTS.md.tmpl for Praxion Codex onboarding from a project's root CLAUDE.md: removes Claude-only operational details, preserves portable project guidance. Triggers: install.sh codex needs a Codex source template, refreshing a previously generated Codex project template.

Architectural patterns and decisions for performant software systems. Triggers: designing for performance, analyzing bottlenecks, choosing caching strategies, planning capacity, optimizing latency/throughput, setting up load testing, defining performance budgets, reviewing for performance anti-patterns; performance budgets, latency analysis, throughput, caching, connection pooling, async/concurrent patterns, database query optimization, load testing, benchmarking, capacity planning, scaling/scalability.

Developer-produced stakeholder communication patterns: technical status updates, RFC/design proposal authoring, release announcements, release notes, breaking change notifications, migration guides, technical demo scripts, approval workflows. Triggers: writing status reports/updates, authoring RFCs or design docs, communicating releases/breaking changes to downstream consumers, preparing sprint demo scripts, seeking architecture/security approval, drafting technical decision records.

Responsible upstream OSS contribution: issue deduplication, sensitive information sanitization, template compliance, contribution etiquette, responsible disclosure. Triggers: filing an upstream issue, reviewing a bug report draft for an external project, discovering an upstream bug during development, contributing a fix to an open-source dependency; filing issues on dependencies, reporting third-party bugs, OSS contribution workflow.

Version bumping, changelog generation, release automation, and tool detection for multi-file projects: SemVer strategy, tool-agnostic detection logic, flag mapping for common versioning tools, breaking change guidelines for textual/config ecosystems. Triggers: bumping versions, generating changelogs, configuring release automation, choosing a versioning tool, defining breaking changes in a non-library project.

Node.js project lifecycle: version pinning, package management, dependency graph hygiene, workspace/monorepo patterns, tsconfig baseline philosophy. Triggers: setting up a Node.js project, choosing a package manager, wiring a monorepo, managing transitive dependency conflicts, configuring tsconfig inheritance, auditing dependency graph health. Language module: TypeScript.

Python project management with pixi and uv: project initialization, dependency management, pyproject.toml, lockfiles (pixi.lock, uv.lock), virtual environments, workspaces, CI/CD integration, conda vs PyPI packages. Defaults to pixi unless uv is explicitly requested. Triggers: setting up Python projects, managing dependencies, choosing between package managers.