konradcinkusz
UserArchitecture standards for .NET Aspire services on Fly.io and Azure: the reference architecture, operational guides and a per-ticket delivery procedure, packaged as installable agent plugins.
Categories
Indexed Skills (31)
cloud-test
Use when exercising an API against a deployed environment — a preview, a shared non-production environment, or anything else reachable over the network. The target base URL is passed in and echoed back, never derived from a naming convention, because a guessed host either wastes the pass or hits the wrong environment. Read-only by default: writes need authorising in that run, irreversible operations need confirming one at a time, and production stays read-only regardless. Confirms the deployed build actually contains the change before trusting any result, captures degraded optional integrations, and accounts for scale-to-zero cold starts. Credentials come from the environment and never reach a document; neither do real users' data or full response bodies. Never deploys and never edits code.
pr-review
Use when reviewing a pull request against the ticket it claims to deliver, before marking it ready for review or merging it. Starts from the acceptance criteria rather than from the diff and requires both satisfying code and a proving test for each one, identifies changes with no criterion behind them, walks the compliance checklist for every layer the diff touches, reads the pull request's recorded decisions first so justified deviations are not reported as findings, reads test bodies instead of counting them, ranks findings blocking / should fix / consider, and ends with an explicit verdict. Every finding cites the principle or guide section behind it; an uncited one is labelled a preference rather than dressed as a standard. Reports findings; never edits the code.
test-on-localhost
Use when exercising an API change over HTTP against the application already running on your own machine, after the automated tests are green and before opening the pull request. Resolves the base URL from the solution itself — the Aspire AppHost, the service's launchSettings profile, or the running dashboard — rather than from a remembered port; checks /health and /alive first and captures which optional integrations are degraded, so a correctly degrading endpoint is not filed as a 500; confirms the running process is the build under test; then exercises the acceptance criteria plus the regression, contract-shape and negative cases, in the estate's manual notation. Never starts the application and never edits code. Every regression it finds becomes a test at the layer holding the logic rather than a document to re-run by hand.
reference-architecture
Use when designing a new service or judging an existing repo against the estate's architecture. The 15 numbered principles (P1-P15) and the compliance checklist: Aspire AppHost as composition root, shared kernel not shared domain, service and database per bounded context, migrated persistence, environment configuration with platform secrets, one container per service, cost-shaped Fly.io topology, degrading optional dependencies, Program.cs as a manifest, interface-plus-registration extensibility, anti-corruption at the edge, tag-driven CI/CD, testing at the layer that holds the logic, in-repo documentation, and observability as a build-time decision. Read this before re-deriving any architectural rule.
repo-baseline
Use when creating a new repository, or auditing an existing repo's hygiene and developer tooling. What every repo carries before its first feature: hygiene files, secret scanning in pre-commit and CI, one-command onboarding, operational script conventions, workflow lifecycle and archiving, in-repo AI agent definitions with allowlisted tools and repo-relative paths, declaring architecture-standards adoption via `.claude/settings.json` rather than relying on memory, and documentation staleness rules.
azure-ai-foundry-agents
Use when provisioning persistent tool-using AI agents on Azure AI Foundry. The Hub/Project/Connection Bicep pattern, per-service managed identity and RBAC including the two-role gotcha where Azure AI Developer alone is not enough, agent-as-code provisioned by a run-and-exit job, azd versus az deployment in CI, GitHub Actions to Azure authentication, and which PR-environment resources are cheap. Getting this wrong looks like a healthy deploy until the first agent-creation call.
azure-operations
Use when running .NET services on Azure beyond AI Foundry. Passwordless SQL end to end, provision-versus-deploy staleness, the permission matrix document, CI credential preflight and soft-delete recovery, storage without keys, model deployments and capacity, and Container Apps manifest idioms and job escape hatches. The unifying rule: managed identity plus RBAC everywhere, and a key or password anywhere in the chain is a finding.
fly-io-deployment
Use when making a service deployable to Fly.io, writing or reviewing a fly.toml, or building the deploy pipeline. Every fly.toml field annotated, the four service shapes (HTTP service, database, frontend, one-shot job), 6PN .internal and .flycast networking, scale-to-zero and when not to, volumes and state, configuration and secrets, the tag-driven pipeline with change detection, bootstrapping a new app, scaling and teardown, and cost.
metrics-exposition
Use when adding or reviewing a /metrics endpoint, choosing metric labels, or diagnosing a monitoring system that is growing without bound: which labels are cardinality decisions, capping high-cardinality views, exporting the fact that you truncated, and provisioning dashboards from the repository.
pr-preview-environments
Use when giving each pull request its own running environment. Naming as the isolation mechanism, classifying what is shared versus per-PR, the deploy workflow and sticky status comments, teardown that actually tears down, and cost posture. The two hard problems are deciding what is shared and guaranteeing teardown, not deployment itself.
private-cloud-delivery
Use when selling or shipping the SaaS as a self-hosted, customer-deployed edition. The vendor-pushes-images / customer-runs-everything responsibility split, the per-client registry, the vendor push-and-stop workflow, the IaC handed over, upgrades and rollback, the one-flag product switch, and the commercial artifacts. A fifth deployment shape alongside the Fly guide's four, with no fork and no vendor production access.
shared-service-reuse
Use when a service in one system is about to be reused by a second, unrelated system in the estate: publishing it as a pinned image, running one independent instance per consumer with its own database and signing key, and keeping the publish pipeline free of deployment secrets. Not for delivering a whole product to a paying customer - that is private-cloud-delivery.
ai-evals
Use when testing an LLM-backed feature, prompt, tool loop or multi-step agent, where the same input can produce different outputs and a prompt or model change can regress behaviour with no code diff. The behaviour spec that precedes the prompt, scenario datasets including adversarial and degradation classes, deterministic assertions over OpenTelemetry traces, calibrated LLM-as-judge, CI gates with baselines, human-in-the-loop, and the production scoring loop that turns incidents into scenarios.
demo-data-and-seeding
Use when building or reviewing demo/seed data for a product with a dashboard, or a reset that must not touch real records: a reserved id namespace enforced server-side, reset by prefix across every store, seeding through the running API rather than the database, deterministic idempotent generation, a second generator that speaks the real ingest protocol, and personas so the data demonstrates something.
e2e-acceptance-testing
Use when writing, reviewing or auditing an end-to-end acceptance suite, especially one that was bulk-generated. The one rule that a test may not pass without checking anything, locator conventions chosen before the first component ships, web-first assertions only for waiting, independence and cleanup agreeing with parallelization, CI wiring as part of done, one canonical suite per live frontend, and the tells that an inherited suite was never fact-checked. A suite that reports green while testing nothing is worse than no suite, because it is trusted.
metric-ethics
Use when a product will publish numbers that score work - quality scores, productivity dashboards, SLAs, agent evaluations: anti-goals enforced by architecture rather than prose, a counter-metric blended into every pressurable metric, confidence carried with every score, human-state heuristics kept outside the composite, and the artifact rather than the person as the unit of evaluation.
open-source-release
Use when moving a repository from private to public. The one-time gate that ongoing hygiene rules do not cover, ordered around the history-aware secret audit that cannot be fixed after the fact, plus licensing, the stranger-facing surface, and repo description and topics.
research-documentation
Use when a repository produces measurements, benchmarks or experiments that need writing up as research rather than as a guide, or when any document in it has to be authored in LaTeX and compiled to PDF. What counts as research and what does not, the docs/research layout, the shape of a study document, the evidence rules (every number traceable, reproduction stated as a command, validate the instrument before trusting its readings, negative results get written up), when a study graduates to a LaTeX paper or a Beamer deck, how a non-study document borrows the house style without claiming to be research, how Mermaid diagrams reach a PDF from a single source, how a second language edition is published, and the shape of the GitHub Actions workflow that builds any of them. Bundled assets: the study template, the paper template and the Beamer theme.
browser-extensions
Use when building or shipping a browser extension as a fourth kind of client. Cross-browser MV3 baseline, web-to-extension session handoff, isolated worlds and the service worker, per-site adapters, packaging one source for N environments in CI, store submission, self-distribution with release channels, and why there is no mobile extension.
frontend-bff
Use when building a Next.js frontend or its backend-for-frontend. The browser talks only to its own origin: runtime configuration so one image serves every environment, HttpOnly cookie sessions instead of a token API, edge middleware that verifies rather than merely decodes, the catch-all proxy with a candidate ladder, entitlement UX, and the shared web kernel whose absence is the costliest finding in the worked example.
identity-and-accounts
Use when building an identity service or handling the account lifecycle. Everything beyond signing tokens: claims enriched at issuance, refresh token rotation, external OAuth providers and callbacks, account linking, enumeration safety, lockout, transactional email, account deletion, and versioned legal consent.
payments-and-monetization
Use when adding payments, subscriptions, quotas or metering to a service. Merchant-of-record versus payment gateway reasoning, mock-first integration, webhook discipline, the subscription lifecycle, quota and metering with deliberate fail-open, layered entitlement enforcement, the self-hosted tenant mode switch, and introducing paid tiers to an existing user base.
service-api-patterns
Use when building or reviewing an HTTP service's plumbing. Rate limiting, endpoint organization, validation, pagination and list queries, hardened cross-service HTTP calls, long-running work without a queue, background services versus migrations, seeded definitions, and the migration completion signal. Most are one extension method, which is why they belong in the shared kernel rather than copy-pasted per service.
state-snapshot-persistence
Use when a service holds a hot in-memory aggregate that must survive restart without a write on every mutation: dirty-set plus timed flush, a one-table JSON snapshot with idempotent DDL, bounded rehydrate, degrade-to-memory when the database is down, and deleting merged entries so they do not return as ghosts. Not for data where losing the last flush interval is losing a transaction - that is P4's ORM-managed schema.
implementation-phase
Use when implementing an approved ticket, once analysis and planning are done — the fixed procedure that replaces rewriting an implementation prompt per ticket. Pre-analysis that proves the build green and names every file and existing test before an edit is made; implementation keyed to the principles a diff can actually violate, from a kernel free of domain through database ownership, migrations, secrets, degrading optional dependencies, wiring, anti-corruption and observability to the API patterns; tests at the layer holding the logic, with regression coverage and the per-test bar; a manual test document only where automation genuinely cannot substitute for a human; recorded decisions that cite the principle behind them; and the pull-request description. Formatting is left to .editorconfig rather than restated. Refuses to proceed if the standards are not actually readable in the session.
ticket-analysis
Use when starting work on a ticket, before any implementation, or when unsure whether a ticket is ready to implement at all. Turns the business request into an architectural one: a table with a row per acceptance criterion carrying the owning bounded context and layer, the principle that governs it, the guide implementation must load, and the named files — then a walk of the compliance checklist listing what the change puts at risk, so a deviation is decided and recorded here rather than discovered mid-diff. Reads the ticket against the architecture rather than against the existing code, runs a read-only exploratory round, separates blocking questions from assumptions worth documenting, and tests the four conditions that gate entry into implementation. Refuses to proceed if the standards are not actually readable in the session.
architecture-session-playbook
Use when starting an architecture review or modernization of a repo, or when unsure which mode a repo needs. Chooses between REVIEW (already broadly compliant), MODERNIZE (predates the architecture but builds) and RECOVER (does not build, or source and dependencies are partly lost), states which documents each mode must produce, which guides to load for which domain, and why RECOVER begins with archaeology rather than design.
master-delivery-prompt
Use when running a delivery session against an application repo — one that must end aligned to the standards AND live as a workable product. The generic fill-in prompt covering, in phases: the assessment (a playbook mode plus gap analysis against the compliance checklist), adopting the external authservice as the system's only identity provider, bringing the frontend to a Next.js product surface under the frontend/BFF rules, comprehensive UI/UX documentation with a ranked backlog, shipping every service to Fly.io, and an optional parallel Azure provisioning job. States what to attach, the read-only scope of the standards and authservice repos, and the definition of done.
readme-badges
Use when writing or reviewing a README's badge block. The header metadata row and footer social block, the three badge families and which service is used for what, and the rules that keep a badge row honest: every badge a titled link, substitute owner/repo rather than copy-pasting URLs, and never badge what you do not have.
security-review
Use when performing a security review or triaging findings before launch. The repeatable method with justified N/A, the finding format, prioritization and the readiness ledger, plus the recurring rule sets: tokens in browsers, cryptographically secure random values, user-supplied paths and names, output/errors/rendering, and authorization structure. An audit whose output format changes each time cannot show whether the system is getting safer.
testing-strategy
Use when deciding what to test, at which layer, and what runs when. The E2E charter, three layers with time budgets, the when-to-run matrix, test infrastructure tiers, mechanics and conventions, the per-test quality bar for merging, what only a human can test, auditing an existing suite, and how test configs rot. A test suite is a budget, not a trophy.
Bio shown is the top-scored skill's repo description as a fallback — real GitHub bios land in a future update.