cfsa-antigravity 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/cli.mjs +324 -0
- package/package.json +34 -0
- package/template/.agent/instructions/commands.md +48 -0
- package/template/.agent/instructions/patterns.md +61 -0
- package/template/.agent/instructions/structure.md +29 -0
- package/template/.agent/instructions/tech-stack.md +43 -0
- package/template/.agent/instructions/workflow.md +41 -0
- package/template/.agent/kit-sync.md +15 -0
- package/template/.agent/rules/boundary-not-placeholder.md +146 -0
- package/template/.agent/rules/completion-checklist.md +48 -0
- package/template/.agent/rules/decision-classification.md +103 -0
- package/template/.agent/rules/extensibility.md +47 -0
- package/template/.agent/rules/question-vs-command.md +81 -0
- package/template/.agent/rules/security-first.md +43 -0
- package/template/.agent/rules/specificity-standards.md +54 -0
- package/template/.agent/rules/tdd-contract-first.md +57 -0
- package/template/.agent/rules/vertical-slices.md +42 -0
- package/template/.agent/skill-library/MANIFEST.md +480 -0
- package/template/.agent/skill-library/README.md +38 -0
- package/template/.agent/skill-library/meta/brand-guidelines/SKILL.md +73 -0
- package/template/.agent/skill-library/meta/claude-code/README.md +9 -0
- package/template/.agent/skill-library/meta/claude-code/agent-development/SKILL.md +415 -0
- package/template/.agent/skill-library/meta/claude-code/hook-development/SKILL.md +712 -0
- package/template/.agent/skill-library/meta/claude-code/plugin-structure/SKILL.md +476 -0
- package/template/.agent/skill-library/meta/git-advanced/SKILL.md +972 -0
- package/template/.agent/skill-library/meta/mcp-builder/SKILL.md +236 -0
- package/template/.agent/skill-library/meta/product-marketing-context/SKILL.md +241 -0
- package/template/.agent/skill-library/meta/regex-patterns/SKILL.md +751 -0
- package/template/.agent/skill-library/meta/tmux-processes/SKILL.md +210 -0
- package/template/.agent/skill-library/meta/using-tmux-for-interactive-commands/SKILL.md +178 -0
- package/template/.agent/skill-library/stack/3d/threejs-pro/SKILL.md +300 -0
- package/template/.agent/skill-library/stack/ai/ai-sdk/SKILL.md +77 -0
- package/template/.agent/skill-library/stack/ai/langchain/SKILL.md +530 -0
- package/template/.agent/skill-library/stack/ai/ollama/SKILL.md +321 -0
- package/template/.agent/skill-library/stack/ai/openai-sdk/SKILL.md +549 -0
- package/template/.agent/skill-library/stack/analytics/google-analytics/SKILL.md +153 -0
- package/template/.agent/skill-library/stack/api/graphql/SKILL.md +1061 -0
- package/template/.agent/skill-library/stack/api/trpc/SKILL.md +576 -0
- package/template/.agent/skill-library/stack/auth/authjs/SKILL.md +569 -0
- package/template/.agent/skill-library/stack/auth/clerk/SKILL.md +590 -0
- package/template/.agent/skill-library/stack/auth/firebase-auth/SKILL.md +734 -0
- package/template/.agent/skill-library/stack/cms/payload-cms/SKILL.md +573 -0
- package/template/.agent/skill-library/stack/cms/shopify/SKILL.md +1193 -0
- package/template/.agent/skill-library/stack/cms/wordpress/SKILL.md +1104 -0
- package/template/.agent/skill-library/stack/css/sass-scss/SKILL.md +1121 -0
- package/template/.agent/skill-library/stack/css/tailwind-css-patterns/SKILL.md +863 -0
- package/template/.agent/skill-library/stack/css/tailwind-design-system/SKILL.md +490 -0
- package/template/.agent/skill-library/stack/css/vanilla-css/SKILL.md +1078 -0
- package/template/.agent/skill-library/stack/databases/clickhouse/SKILL.md +311 -0
- package/template/.agent/skill-library/stack/databases/influxdb/SKILL.md +280 -0
- package/template/.agent/skill-library/stack/databases/lancedb/SKILL.md +415 -0
- package/template/.agent/skill-library/stack/databases/mongodb/SKILL.md +1169 -0
- package/template/.agent/skill-library/stack/databases/neo4j/SKILL.md +839 -0
- package/template/.agent/skill-library/stack/databases/pgvector/SKILL.md +241 -0
- package/template/.agent/skill-library/stack/databases/pinecone/SKILL.md +212 -0
- package/template/.agent/skill-library/stack/databases/postgresql/SKILL.md +658 -0
- package/template/.agent/skill-library/stack/databases/qdrant/SKILL.md +312 -0
- package/template/.agent/skill-library/stack/databases/redis/SKILL.md +1079 -0
- package/template/.agent/skill-library/stack/databases/spacetimedb/SKILL.md +532 -0
- package/template/.agent/skill-library/stack/databases/sqlite/SKILL.md +1132 -0
- package/template/.agent/skill-library/stack/databases/supabase/SKILL.md +640 -0
- package/template/.agent/skill-library/stack/databases/surrealdb-expert/SKILL.md +945 -0
- package/template/.agent/skill-library/stack/databases/timescaledb/SKILL.md +745 -0
- package/template/.agent/skill-library/stack/databases/weaviate/SKILL.md +218 -0
- package/template/.agent/skill-library/stack/devops/github-actions/SKILL.md +554 -0
- package/template/.agent/skill-library/stack/devops/kubernetes/SKILL.md +950 -0
- package/template/.agent/skill-library/stack/devops/nginx/SKILL.md +841 -0
- package/template/.agent/skill-library/stack/devops/terraform/SKILL.md +860 -0
- package/template/.agent/skill-library/stack/email/resend/SKILL.md +391 -0
- package/template/.agent/skill-library/stack/engines/godot/SKILL.md +488 -0
- package/template/.agent/skill-library/stack/extensions/chrome-extension/SKILL.md +375 -0
- package/template/.agent/skill-library/stack/extensions/vscode-extension/SKILL.md +453 -0
- package/template/.agent/skill-library/stack/frameworks/astro-framework/SKILL.md +162 -0
- package/template/.agent/skill-library/stack/frameworks/electron/SKILL.md +1286 -0
- package/template/.agent/skill-library/stack/frameworks/fastapi/SKILL.md +650 -0
- package/template/.agent/skill-library/stack/frameworks/hono/SKILL.md +90 -0
- package/template/.agent/skill-library/stack/frameworks/nestjs/SKILL.md +878 -0
- package/template/.agent/skill-library/stack/frameworks/nextjs/SKILL.md +635 -0
- package/template/.agent/skill-library/stack/frameworks/nuxt/SKILL.md +564 -0
- package/template/.agent/skill-library/stack/frameworks/sveltekit/SKILL.md +614 -0
- package/template/.agent/skill-library/stack/frameworks/tauri/SKILL.md +920 -0
- package/template/.agent/skill-library/stack/gamedev/godot/SKILL.md +1032 -0
- package/template/.agent/skill-library/stack/gamedev/unity/SKILL.md +1175 -0
- package/template/.agent/skill-library/stack/hosting/aws/SKILL.md +467 -0
- package/template/.agent/skill-library/stack/hosting/cloudflare/SKILL.md +201 -0
- package/template/.agent/skill-library/stack/hosting/docker-expert/SKILL.md +409 -0
- package/template/.agent/skill-library/stack/hosting/vercel/SKILL.md +484 -0
- package/template/.agent/skill-library/stack/languages/bash-scripting/SKILL.md +773 -0
- package/template/.agent/skill-library/stack/languages/c-cpp/SKILL.md +712 -0
- package/template/.agent/skill-library/stack/languages/gdscript/SKILL.md +789 -0
- package/template/.agent/skill-library/stack/languages/go/SKILL.md +664 -0
- package/template/.agent/skill-library/stack/languages/java/SKILL.md +778 -0
- package/template/.agent/skill-library/stack/languages/kotlin/SKILL.md +665 -0
- package/template/.agent/skill-library/stack/languages/python/SKILL.md +678 -0
- package/template/.agent/skill-library/stack/languages/rust/SKILL.md +673 -0
- package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/SKILL.md +141 -0
- package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/advanced-generics.md +90 -0
- package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/branded-types.md +57 -0
- package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/builder-pattern.md +71 -0
- package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/common-pitfalls.md +135 -0
- package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/conditional-types.md +27 -0
- package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/decorators.md +98 -0
- package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/discriminated-unions.md +62 -0
- package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/mapped-types.md +53 -0
- package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/performance-best-practices.md +104 -0
- package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/template-literal-types.md +49 -0
- package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/testing-types.md +112 -0
- package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/type-guards.md +70 -0
- package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/type-inference.md +101 -0
- package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/utility-types.md +98 -0
- package/template/.agent/skill-library/stack/languages/vanilla-javascript/SKILL.md +803 -0
- package/template/.agent/skill-library/stack/messaging/kafka/SKILL.md +235 -0
- package/template/.agent/skill-library/stack/mobile/expo-react-native/SKILL.md +665 -0
- package/template/.agent/skill-library/stack/mobile/flutter/SKILL.md +316 -0
- package/template/.agent/skill-library/stack/mobile/react-native/SKILL.md +337 -0
- package/template/.agent/skill-library/stack/monitoring/posthog/SKILL.md +396 -0
- package/template/.agent/skill-library/stack/monitoring/sentry/SKILL.md +509 -0
- package/template/.agent/skill-library/stack/observability/datadog/SKILL.md +179 -0
- package/template/.agent/skill-library/stack/observability/distributed-tracing/SKILL.md +140 -0
- package/template/.agent/skill-library/stack/observability/logging-best-practices/SKILL.md +168 -0
- package/template/.agent/skill-library/stack/observability/opentelemetry/SKILL.md +164 -0
- package/template/.agent/skill-library/stack/observability/prometheus-grafana/SKILL.md +246 -0
- package/template/.agent/skill-library/stack/observability/python-observability/SKILL.md +158 -0
- package/template/.agent/skill-library/stack/orm/drizzle-orm/SKILL.md +613 -0
- package/template/.agent/skill-library/stack/orm/prisma/SKILL.md +744 -0
- package/template/.agent/skill-library/stack/payments/lemonsqueezy/SKILL.md +393 -0
- package/template/.agent/skill-library/stack/payments/stripe-integration/SKILL.md +457 -0
- package/template/.agent/skill-library/stack/queue/bullmq/SKILL.md +385 -0
- package/template/.agent/skill-library/stack/queue/inngest/SKILL.md +438 -0
- package/template/.agent/skill-library/stack/realtime/socketio/SKILL.md +595 -0
- package/template/.agent/skill-library/stack/search/elasticsearch/SKILL.md +248 -0
- package/template/.agent/skill-library/stack/search/meilisearch/SKILL.md +385 -0
- package/template/.agent/skill-library/stack/security/crypto-patterns/SKILL.md +437 -0
- package/template/.agent/skill-library/stack/security/csp-cors-headers/SKILL.md +588 -0
- package/template/.agent/skill-library/stack/security/dependency-auditing/SKILL.md +560 -0
- package/template/.agent/skill-library/stack/security/input-sanitization/SKILL.md +430 -0
- package/template/.agent/skill-library/stack/security/owasp-web-security/SKILL.md +421 -0
- package/template/.agent/skill-library/stack/state/tanstack-query/SKILL.md +637 -0
- package/template/.agent/skill-library/stack/state/zustand/SKILL.md +483 -0
- package/template/.agent/skill-library/stack/storage/aws-s3/SKILL.md +415 -0
- package/template/.agent/skill-library/stack/testing/playwright/SKILL.md +641 -0
- package/template/.agent/skill-library/stack/testing/storybook/SKILL.md +923 -0
- package/template/.agent/skill-library/stack/testing/testing-library/SKILL.md +872 -0
- package/template/.agent/skill-library/stack/testing/vitest/SKILL.md +714 -0
- package/template/.agent/skill-library/stack/ui/react-best-practices/SKILL.md +877 -0
- package/template/.agent/skill-library/stack/ui/react-composition-patterns/SKILL.md +1107 -0
- package/template/.agent/skill-library/stack/ui/react-flow/SKILL.md +425 -0
- package/template/.agent/skill-library/stack/ui/shadcn-ui/SKILL.md +703 -0
- package/template/.agent/skill-library/surface/api/api-caching/SKILL.md +458 -0
- package/template/.agent/skill-library/surface/api/api-documentation-openapi/SKILL.md +697 -0
- package/template/.agent/skill-library/surface/api/api-error-handling/SKILL.md +478 -0
- package/template/.agent/skill-library/surface/api/api-security-checklist/SKILL.md +147 -0
- package/template/.agent/skill-library/surface/api/api-versioning/SKILL.md +420 -0
- package/template/.agent/skill-library/surface/api/email-best-practices/SKILL.md +59 -0
- package/template/.agent/skill-library/surface/api/rate-limiting-abuse-protection/SKILL.md +147 -0
- package/template/.agent/skill-library/surface/api/rest-api-design/SKILL.md +478 -0
- package/template/.agent/skill-library/surface/api/webhook-design/SKILL.md +752 -0
- package/template/.agent/skill-library/surface/cli/cli-configuration-management/SKILL.md +445 -0
- package/template/.agent/skill-library/surface/cli/cli-error-diagnostics/SKILL.md +515 -0
- package/template/.agent/skill-library/surface/cli/cli-shell-integration/SKILL.md +479 -0
- package/template/.agent/skill-library/surface/cli/cli-ux-design/SKILL.md +477 -0
- package/template/.agent/skill-library/surface/desktop/desktop-app-distribution/SKILL.md +416 -0
- package/template/.agent/skill-library/surface/desktop/desktop-security-sandboxing/SKILL.md +407 -0
- package/template/.agent/skill-library/surface/desktop/desktop-ux-conventions/SKILL.md +361 -0
- package/template/.agent/skill-library/surface/desktop/native-os-integration/SKILL.md +563 -0
- package/template/.agent/skill-library/surface/extension/browser-extension-patterns/SKILL.md +482 -0
- package/template/.agent/skill-library/surface/extension/plugin-architecture-design/SKILL.md +632 -0
- package/template/.agent/skill-library/surface/extension/vscode-extension-development/SKILL.md +728 -0
- package/template/.agent/skill-library/surface/mobile/app-store-submission/SKILL.md +304 -0
- package/template/.agent/skill-library/surface/mobile/mobile-offline-sync/SKILL.md +443 -0
- package/template/.agent/skill-library/surface/mobile/mobile-responsive-patterns/SKILL.md +432 -0
- package/template/.agent/skill-library/surface/mobile/push-notifications/SKILL.md +495 -0
- package/template/.agent/skill-library/surface/web/accessibility-compliance/SKILL.md +827 -0
- package/template/.agent/skill-library/surface/web/ai-seo/SKILL.md +398 -0
- package/template/.agent/skill-library/surface/web/ai-seo/references/content-patterns.md +285 -0
- package/template/.agent/skill-library/surface/web/ai-seo/references/platform-ranking-factors.md +152 -0
- package/template/.agent/skill-library/surface/web/analytics-tracking/SKILL.md +309 -0
- package/template/.agent/skill-library/surface/web/analytics-tracking/references/event-library.md +260 -0
- package/template/.agent/skill-library/surface/web/analytics-tracking/references/ga4-implementation.md +300 -0
- package/template/.agent/skill-library/surface/web/analytics-tracking/references/gtm-implementation.md +390 -0
- package/template/.agent/skill-library/surface/web/authentication-ui-flows/SKILL.md +530 -0
- package/template/.agent/skill-library/surface/web/dark-mode-theming/SKILL.md +516 -0
- package/template/.agent/skill-library/surface/web/design-reference-data/SKILL.md +105 -0
- package/template/.agent/skill-library/surface/web/design-reference-data/data/charts.csv +26 -0
- package/template/.agent/skill-library/surface/web/design-reference-data/data/colors.csv +97 -0
- package/template/.agent/skill-library/surface/web/design-reference-data/data/landing.csv +31 -0
- package/template/.agent/skill-library/surface/web/design-reference-data/data/styles.csv +59 -0
- package/template/.agent/skill-library/surface/web/design-reference-data/data/typography.csv +58 -0
- package/template/.agent/skill-library/surface/web/design-reference-data/data/ux-guidelines.csv +100 -0
- package/template/.agent/skill-library/surface/web/design-reference-data/scripts/core.py +258 -0
- package/template/.agent/skill-library/surface/web/design-reference-data/scripts/design_system.py +1067 -0
- package/template/.agent/skill-library/surface/web/design-reference-data/scripts/search.py +106 -0
- package/template/.agent/skill-library/surface/web/form-handling-validation/SKILL.md +675 -0
- package/template/.agent/skill-library/surface/web/frontend-design/SKILL.md +1393 -0
- package/template/.agent/skill-library/surface/web/frontend-design/templates/cppn-hero.tsx +299 -0
- package/template/.agent/skill-library/surface/web/frontend-design/templates/wave-hero.tsx +875 -0
- package/template/.agent/skill-library/surface/web/frontend-verification/SKILL.md +111 -0
- package/template/.agent/skill-library/surface/web/frontend-verification/scripts/ux_audit.py +739 -0
- package/template/.agent/skill-library/surface/web/i18n-localization/SKILL.md +154 -0
- package/template/.agent/skill-library/surface/web/offline-first-pwa/SKILL.md +657 -0
- package/template/.agent/skill-library/surface/web/page-cro/SKILL.md +182 -0
- package/template/.agent/skill-library/surface/web/page-cro/references/experiments.md +248 -0
- package/template/.agent/skill-library/surface/web/programmatic-seo/SKILL.md +238 -0
- package/template/.agent/skill-library/surface/web/programmatic-seo/references/playbooks.md +308 -0
- package/template/.agent/skill-library/surface/web/schema-markup/SKILL.md +179 -0
- package/template/.agent/skill-library/surface/web/schema-markup/references/schema-examples.md +398 -0
- package/template/.agent/skill-library/surface/web/seo-audit/SKILL.md +394 -0
- package/template/.agent/skill-library/surface/web/seo-audit/references/ai-writing-detection.md +200 -0
- package/template/.agent/skill-library/surface/web/web-performance-optimization/SKILL.md +646 -0
- package/template/.agent/skill-library/surface/web/web-scraping/SKILL.md +58 -0
- package/template/.agent/skills/accessibility/SKILL.md +522 -0
- package/template/.agent/skills/accessibility/references/WCAG.md +162 -0
- package/template/.agent/skills/adversarial-review/SKILL.md +90 -0
- package/template/.agent/skills/antigravity-workflows/SKILL.md +81 -0
- package/template/.agent/skills/antigravity-workflows/resources/implementation-playbook.md +36 -0
- package/template/.agent/skills/api-design-principles/SKILL.md +37 -0
- package/template/.agent/skills/api-design-principles/assets/api-design-checklist.md +155 -0
- package/template/.agent/skills/api-design-principles/assets/rest-api-template.py +182 -0
- package/template/.agent/skills/api-design-principles/references/graphql-schema-design.md +583 -0
- package/template/.agent/skills/api-design-principles/references/rest-best-practices.md +408 -0
- package/template/.agent/skills/api-design-principles/resources/implementation-playbook.md +513 -0
- package/template/.agent/skills/api-versioning/SKILL.md +420 -0
- package/template/.agent/skills/architecture-mapping/SKILL.md +219 -0
- package/template/.agent/skills/bootstrap-agents/SKILL.md +259 -0
- package/template/.agent/skills/brainstorming/SKILL.md +236 -0
- package/template/.agent/skills/brand-guidelines/SKILL.md +44 -0
- package/template/.agent/skills/clean-code/SKILL.md +94 -0
- package/template/.agent/skills/code-review-pro/SKILL.md +152 -0
- package/template/.agent/skills/concise-planning/SKILL.md +68 -0
- package/template/.agent/skills/cross-layer-consistency/SKILL.md +117 -0
- package/template/.agent/skills/database-schema-design/SKILL.md +429 -0
- package/template/.agent/skills/deployment-procedures/SKILL.md +241 -0
- package/template/.agent/skills/design-anti-cliche/SKILL.md +159 -0
- package/template/.agent/skills/design-direction/SKILL.md +45 -0
- package/template/.agent/skills/error-handling-patterns/SKILL.md +721 -0
- package/template/.agent/skills/find-skills/SKILL.md +145 -0
- package/template/.agent/skills/git-advanced/SKILL.md +972 -0
- package/template/.agent/skills/git-workflow/SKILL.md +420 -0
- package/template/.agent/skills/idea-extraction/SKILL.md +271 -0
- package/template/.agent/skills/logging-best-practices/SKILL.md +851 -0
- package/template/.agent/skills/migration-management/SKILL.md +384 -0
- package/template/.agent/skills/minimalist-surgical-development/SKILL.md +69 -0
- package/template/.agent/skills/parallel-agents/SKILL.md +165 -0
- package/template/.agent/skills/parallel-debugging/SKILL.md +135 -0
- package/template/.agent/skills/parallel-feature-development/SKILL.md +166 -0
- package/template/.agent/skills/performance-budgeting/SKILL.md +144 -0
- package/template/.agent/skills/pipeline-rubrics/SKILL.md +51 -0
- package/template/.agent/skills/pipeline-rubrics/references/architecture-rubric.md +19 -0
- package/template/.agent/skills/pipeline-rubrics/references/be-rubric.md +21 -0
- package/template/.agent/skills/pipeline-rubrics/references/fe-rubric.md +20 -0
- package/template/.agent/skills/pipeline-rubrics/references/ia-rubric.md +19 -0
- package/template/.agent/skills/pipeline-rubrics/references/scoring.md +28 -0
- package/template/.agent/skills/pipeline-rubrics/references/vision-rubric.md +11 -0
- package/template/.agent/skills/prd-templates/SKILL.md +88 -0
- package/template/.agent/skills/prd-templates/references/architecture-design-template.md +88 -0
- package/template/.agent/skills/prd-templates/references/be-spec-template.md +101 -0
- package/template/.agent/skills/prd-templates/references/data-placement-template.md +74 -0
- package/template/.agent/skills/prd-templates/references/decomposition-templates.md +211 -0
- package/template/.agent/skills/prd-templates/references/design-system-decisions.md +198 -0
- package/template/.agent/skills/prd-templates/references/engineering-standards-template.md +124 -0
- package/template/.agent/skills/prd-templates/references/fe-classification-procedures.md +47 -0
- package/template/.agent/skills/prd-templates/references/fe-spec-template.md +84 -0
- package/template/.agent/skills/prd-templates/references/infrastructure-report-template.md +71 -0
- package/template/.agent/skills/prd-templates/references/operational-templates.md +116 -0
- package/template/.agent/skills/prd-templates/references/placeholder-guard-template.md +21 -0
- package/template/.agent/skills/prd-templates/references/surface-model.md +61 -0
- package/template/.agent/skills/prd-templates/references/vision-template.md +66 -0
- package/template/.agent/skills/prompt-engineer/README.md +659 -0
- package/template/.agent/skills/prompt-engineer/SKILL.md +249 -0
- package/template/.agent/skills/regex-patterns/SKILL.md +751 -0
- package/template/.agent/skills/resolve-ambiguity/SKILL.md +278 -0
- package/template/.agent/skills/rest-api-design/SKILL.md +478 -0
- package/template/.agent/skills/security-scanning-security-hardening/SKILL.md +231 -0
- package/template/.agent/skills/session-continuity/SKILL.md +730 -0
- package/template/.agent/skills/session-continuity/protocols/01-session-resumption.md +38 -0
- package/template/.agent/skills/session-continuity/protocols/02-progress-generation.md +85 -0
- package/template/.agent/skills/session-continuity/protocols/03-progress-update.md +70 -0
- package/template/.agent/skills/session-continuity/protocols/04-pattern-extraction.md +60 -0
- package/template/.agent/skills/session-continuity/protocols/05-session-close.md +37 -0
- package/template/.agent/skills/session-continuity/protocols/06-decision-analysis.md +84 -0
- package/template/.agent/skills/session-continuity/protocols/07-spec-pipeline-generation.md +48 -0
- package/template/.agent/skills/session-continuity/protocols/08-spec-pipeline-update.md +43 -0
- package/template/.agent/skills/session-continuity/protocols/09-parallel-claim.md +122 -0
- package/template/.agent/skills/session-continuity/protocols/10-placeholder-verification-gate.md +104 -0
- package/template/.agent/skills/session-continuity/protocols/ambiguity-gates.md +48 -0
- package/template/.agent/skills/skill-creator/LICENSE.txt +202 -0
- package/template/.agent/skills/skill-creator/README.md +270 -0
- package/template/.agent/skills/skill-creator/SKILL.md +590 -0
- package/template/.agent/skills/skill-creator/references/output-patterns.md +82 -0
- package/template/.agent/skills/skill-creator/references/workflows.md +28 -0
- package/template/.agent/skills/skill-creator/scripts/init_skill.py +303 -0
- package/template/.agent/skills/skill-creator/scripts/package_skill.py +110 -0
- package/template/.agent/skills/skill-creator/scripts/quick_validate.py +95 -0
- package/template/.agent/skills/spec-writing/SKILL.md +110 -0
- package/template/.agent/skills/systematic-debugging/CREATION-LOG.md +119 -0
- package/template/.agent/skills/systematic-debugging/SKILL.md +297 -0
- package/template/.agent/skills/systematic-debugging/condition-based-waiting-example.ts +158 -0
- package/template/.agent/skills/systematic-debugging/condition-based-waiting.md +115 -0
- package/template/.agent/skills/systematic-debugging/defense-in-depth.md +122 -0
- package/template/.agent/skills/systematic-debugging/find-polluter.sh +63 -0
- package/template/.agent/skills/systematic-debugging/root-cause-tracing.md +169 -0
- package/template/.agent/skills/systematic-debugging/test-academic.md +14 -0
- package/template/.agent/skills/systematic-debugging/test-pressure-1.md +58 -0
- package/template/.agent/skills/systematic-debugging/test-pressure-2.md +68 -0
- package/template/.agent/skills/systematic-debugging/test-pressure-3.md +69 -0
- package/template/.agent/skills/tdd-workflow/SKILL.md +409 -0
- package/template/.agent/skills/tech-stack-catalog/SKILL.md +49 -0
- package/template/.agent/skills/tech-stack-catalog/references/constraint-questions.md +21 -0
- package/template/.agent/skills/tech-stack-catalog/references/dev-tooling-decisions.md +37 -0
- package/template/.agent/skills/tech-stack-catalog/references/surface-decision-tables.md +69 -0
- package/template/.agent/skills/technical-writer/SKILL.md +242 -0
- package/template/.agent/skills/testing-strategist/SKILL.md +932 -0
- package/template/.agent/skills/verification-before-completion/SKILL.md +145 -0
- package/template/.agent/skills/workflow-automation/SKILL.md +73 -0
- package/template/.agent/workflows/audit-ambiguity-execute.md +165 -0
- package/template/.agent/workflows/audit-ambiguity-rubrics.md +83 -0
- package/template/.agent/workflows/audit-ambiguity.md +64 -0
- package/template/.agent/workflows/bootstrap-agents-fill.md +201 -0
- package/template/.agent/workflows/bootstrap-agents-provision.md +197 -0
- package/template/.agent/workflows/bootstrap-agents.md +66 -0
- package/template/.agent/workflows/create-prd-architecture.md +119 -0
- package/template/.agent/workflows/create-prd-compile.md +138 -0
- package/template/.agent/workflows/create-prd-design-system.md +135 -0
- package/template/.agent/workflows/create-prd-security.md +113 -0
- package/template/.agent/workflows/create-prd-stack.md +91 -0
- package/template/.agent/workflows/create-prd.md +168 -0
- package/template/.agent/workflows/decompose-architecture-structure.md +82 -0
- package/template/.agent/workflows/decompose-architecture-validate.md +119 -0
- package/template/.agent/workflows/decompose-architecture.md +111 -0
- package/template/.agent/workflows/evolve-contract.md +98 -0
- package/template/.agent/workflows/evolve-feature-cascade.md +140 -0
- package/template/.agent/workflows/evolve-feature-classify.md +116 -0
- package/template/.agent/workflows/evolve-feature.md +56 -0
- package/template/.agent/workflows/ideate-discover.md +144 -0
- package/template/.agent/workflows/ideate-extract.md +129 -0
- package/template/.agent/workflows/ideate-validate.md +117 -0
- package/template/.agent/workflows/ideate.md +113 -0
- package/template/.agent/workflows/implement-slice-setup.md +113 -0
- package/template/.agent/workflows/implement-slice-tdd.md +198 -0
- package/template/.agent/workflows/implement-slice.md +50 -0
- package/template/.agent/workflows/plan-phase.md +202 -0
- package/template/.agent/workflows/propagate-decision-apply.md +135 -0
- package/template/.agent/workflows/propagate-decision-scan.md +147 -0
- package/template/.agent/workflows/propagate-decision.md +56 -0
- package/template/.agent/workflows/remediate-pipeline-assess.md +138 -0
- package/template/.agent/workflows/remediate-pipeline-execute.md +135 -0
- package/template/.agent/workflows/remediate-pipeline.md +55 -0
- package/template/.agent/workflows/resolve-ambiguity.md +82 -0
- package/template/.agent/workflows/sync-kit.md +209 -0
- package/template/.agent/workflows/update-architecture-map.md +74 -0
- package/template/.agent/workflows/validate-phase.md +219 -0
- package/template/.agent/workflows/verify-infrastructure.md +207 -0
- package/template/.agent/workflows/write-architecture-spec-deepen.md +139 -0
- package/template/.agent/workflows/write-architecture-spec-design.md +202 -0
- package/template/.agent/workflows/write-architecture-spec.md +63 -0
- package/template/.agent/workflows/write-be-spec-classify.md +165 -0
- package/template/.agent/workflows/write-be-spec-write.md +98 -0
- package/template/.agent/workflows/write-be-spec.md +76 -0
- package/template/.agent/workflows/write-fe-spec-classify.md +170 -0
- package/template/.agent/workflows/write-fe-spec-write.md +94 -0
- package/template/.agent/workflows/write-fe-spec.md +71 -0
- package/template/AGENTS.md +176 -0
- package/template/GEMINI.md +177 -0
- package/template/docs/README.md +187 -0
- package/template/docs/audits/.gitkeep +0 -0
- package/template/docs/audits/README.md +10 -0
- package/template/docs/plans/.gitkeep +0 -0
- package/template/docs/plans/README.md +21 -0
- package/template/docs/plans/be/.gitkeep +0 -0
- package/template/docs/plans/be/README.md +11 -0
- package/template/docs/plans/fe/.gitkeep +0 -0
- package/template/docs/plans/fe/README.md +11 -0
- package/template/docs/plans/ia/.gitkeep +0 -0
- package/template/docs/plans/ia/README.md +17 -0
- package/template/docs/plans/ia/deep-dives/.gitkeep +0 -0
- package/template/docs/plans/ia/deep-dives/README.md +5 -0
- package/template/docs/plans/phases/.gitkeep +0 -0
- package/template/docs/plans/phases/README.md +11 -0
|
@@ -0,0 +1,478 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: api-error-handling
|
|
3
|
+
description: "Design consistent API error responses using RFC 7807 Problem Details, field-level validation errors, error correlation IDs, retry semantics, and circuit breaker patterns. Use when designing error handling for REST APIs or standardizing error response formats."
|
|
4
|
+
version: 1.0.0
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# API Error Handling
|
|
8
|
+
|
|
9
|
+
Every API must communicate errors clearly, consistently, and securely. Clients should never have to guess what went wrong, and servers should never leak internal details.
|
|
10
|
+
|
|
11
|
+
## RFC 7807 Problem Details
|
|
12
|
+
|
|
13
|
+
The standard format for machine-readable error responses. Use `application/problem+json` as the content type.
|
|
14
|
+
|
|
15
|
+
```typescript
|
|
16
|
+
// src/schemas/problem-details.schema.ts
|
|
17
|
+
import { z } from 'zod';
|
|
18
|
+
|
|
19
|
+
export const ProblemDetailsSchema = z.object({
|
|
20
|
+
type: z.string().url().describe('URI reference identifying the problem type'),
|
|
21
|
+
title: z.string().describe('Short human-readable summary'),
|
|
22
|
+
status: z.number().int().min(400).max(599).describe('HTTP status code'),
|
|
23
|
+
detail: z.string().optional().describe('Human-readable explanation specific to this occurrence'),
|
|
24
|
+
instance: z.string().optional().describe('URI reference identifying this specific occurrence'),
|
|
25
|
+
// Extension members
|
|
26
|
+
correlationId: z.string().uuid().optional().describe('Request correlation ID for support'),
|
|
27
|
+
errors: z.array(z.object({
|
|
28
|
+
field: z.string().describe('JSON pointer to the field (e.g., /body/email)'),
|
|
29
|
+
message: z.string().describe('Human-readable error for this field'),
|
|
30
|
+
code: z.string().describe('Machine-readable error code (e.g., required, too_short)'),
|
|
31
|
+
})).optional().describe('Field-level validation errors'),
|
|
32
|
+
retryAfter: z.number().int().optional().describe('Seconds before the client should retry'),
|
|
33
|
+
});
|
|
34
|
+
|
|
35
|
+
export type ProblemDetails = z.infer<typeof ProblemDetailsSchema>;
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### Example Responses
|
|
39
|
+
|
|
40
|
+
**Validation error (422):**
|
|
41
|
+
```json
|
|
42
|
+
{
|
|
43
|
+
"type": "https://api.example.com/problems/validation-error",
|
|
44
|
+
"title": "Validation Failed",
|
|
45
|
+
"status": 422,
|
|
46
|
+
"detail": "The request body contains 2 validation errors.",
|
|
47
|
+
"correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
48
|
+
"errors": [
|
|
49
|
+
{
|
|
50
|
+
"field": "/body/email",
|
|
51
|
+
"message": "Must be a valid email address",
|
|
52
|
+
"code": "invalid_format"
|
|
53
|
+
},
|
|
54
|
+
{
|
|
55
|
+
"field": "/body/name",
|
|
56
|
+
"message": "Must be at least 2 characters",
|
|
57
|
+
"code": "too_short"
|
|
58
|
+
}
|
|
59
|
+
]
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
**Not found (404):**
|
|
64
|
+
```json
|
|
65
|
+
{
|
|
66
|
+
"type": "https://api.example.com/problems/not-found",
|
|
67
|
+
"title": "Resource Not Found",
|
|
68
|
+
"status": 404,
|
|
69
|
+
"detail": "No model with ID 'gpt-5-turbo' exists.",
|
|
70
|
+
"correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
**Rate limited (429):**
|
|
75
|
+
```json
|
|
76
|
+
{
|
|
77
|
+
"type": "https://api.example.com/problems/rate-limited",
|
|
78
|
+
"title": "Too Many Requests",
|
|
79
|
+
"status": 429,
|
|
80
|
+
"detail": "You have exceeded 100 requests per minute.",
|
|
81
|
+
"correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
82
|
+
"retryAfter": 42
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## Error Code Taxonomy
|
|
89
|
+
|
|
90
|
+
### 4xx Client Errors
|
|
91
|
+
|
|
92
|
+
| Status | Code | When to Use |
|
|
93
|
+
|--------|------|-------------|
|
|
94
|
+
| 400 | `bad_request` | Malformed JSON, missing Content-Type, unparseable body |
|
|
95
|
+
| 401 | `unauthorized` | Missing or invalid authentication credentials |
|
|
96
|
+
| 403 | `forbidden` | Authenticated but lacks permission |
|
|
97
|
+
| 404 | `not_found` | Resource does not exist |
|
|
98
|
+
| 405 | `method_not_allowed` | Wrong HTTP method (e.g., GET on a POST-only endpoint) |
|
|
99
|
+
| 409 | `conflict` | Resource state conflict (e.g., duplicate email, version mismatch) |
|
|
100
|
+
| 410 | `gone` | Resource previously existed but was permanently deleted |
|
|
101
|
+
| 413 | `payload_too_large` | Request body exceeds size limit |
|
|
102
|
+
| 415 | `unsupported_media_type` | Content-Type not accepted |
|
|
103
|
+
| 422 | `validation_error` | Syntactically valid but semantically invalid (Zod validation failures) |
|
|
104
|
+
| 429 | `rate_limited` | Too many requests |
|
|
105
|
+
|
|
106
|
+
### 5xx Server Errors
|
|
107
|
+
|
|
108
|
+
| Status | Code | When to Use |
|
|
109
|
+
|--------|------|-------------|
|
|
110
|
+
| 500 | `internal_error` | Unhandled exception (catch-all) |
|
|
111
|
+
| 502 | `bad_gateway` | Upstream service returned invalid response |
|
|
112
|
+
| 503 | `service_unavailable` | Service temporarily down (maintenance, overloaded) |
|
|
113
|
+
| 504 | `gateway_timeout` | Upstream service timed out |
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## Validation Error Response Shape
|
|
118
|
+
|
|
119
|
+
Map Zod validation errors to RFC 7807 field errors.
|
|
120
|
+
|
|
121
|
+
```typescript
|
|
122
|
+
import { ZodError } from 'zod';
|
|
123
|
+
|
|
124
|
+
function zodToProblemDetails(error: ZodError, correlationId: string): ProblemDetails {
|
|
125
|
+
return {
|
|
126
|
+
type: 'https://api.example.com/problems/validation-error',
|
|
127
|
+
title: 'Validation Failed',
|
|
128
|
+
status: 422,
|
|
129
|
+
detail: `The request contains ${error.issues.length} validation error${error.issues.length > 1 ? 's' : ''}.`,
|
|
130
|
+
correlationId,
|
|
131
|
+
errors: error.issues.map((issue) => ({
|
|
132
|
+
field: `/${issue.path.join('/')}`,
|
|
133
|
+
message: issue.message,
|
|
134
|
+
code: issue.code,
|
|
135
|
+
})),
|
|
136
|
+
};
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
**Usage in a request handler:**
|
|
141
|
+
```typescript
|
|
142
|
+
export async function POST({ request }: APIContext) {
|
|
143
|
+
const correlationId = crypto.randomUUID();
|
|
144
|
+
|
|
145
|
+
const body = await request.json().catch(() => null);
|
|
146
|
+
if (body === null) {
|
|
147
|
+
return problemResponse({
|
|
148
|
+
type: 'https://api.example.com/problems/bad-request',
|
|
149
|
+
title: 'Invalid JSON',
|
|
150
|
+
status: 400,
|
|
151
|
+
detail: 'The request body is not valid JSON.',
|
|
152
|
+
correlationId,
|
|
153
|
+
});
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
const result = CreateModelSchema.safeParse(body);
|
|
157
|
+
if (!result.success) {
|
|
158
|
+
return problemResponse(zodToProblemDetails(result.error, correlationId));
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
// ... handle valid request
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
function problemResponse(problem: ProblemDetails): Response {
|
|
165
|
+
return new Response(JSON.stringify(problem), {
|
|
166
|
+
status: problem.status,
|
|
167
|
+
headers: {
|
|
168
|
+
'Content-Type': 'application/problem+json',
|
|
169
|
+
'X-Correlation-ID': problem.correlationId ?? '',
|
|
170
|
+
},
|
|
171
|
+
});
|
|
172
|
+
}
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## Stack Trace Suppression
|
|
178
|
+
|
|
179
|
+
Never expose stack traces, internal paths, or implementation details in production.
|
|
180
|
+
|
|
181
|
+
```typescript
|
|
182
|
+
// Global error handler
|
|
183
|
+
function handleUnexpectedError(error: unknown, correlationId: string): ProblemDetails {
|
|
184
|
+
// Log the full error internally
|
|
185
|
+
logger.error('Unhandled error', {
|
|
186
|
+
correlationId,
|
|
187
|
+
error: error instanceof Error ? {
|
|
188
|
+
message: error.message,
|
|
189
|
+
stack: error.stack,
|
|
190
|
+
name: error.name,
|
|
191
|
+
} : error,
|
|
192
|
+
});
|
|
193
|
+
|
|
194
|
+
// Return sanitized response to client
|
|
195
|
+
return {
|
|
196
|
+
type: 'https://api.example.com/problems/internal-error',
|
|
197
|
+
title: 'Internal Server Error',
|
|
198
|
+
status: 500,
|
|
199
|
+
detail: 'An unexpected error occurred. Please try again later.',
|
|
200
|
+
correlationId,
|
|
201
|
+
// NO stack trace, NO file paths, NO SQL queries
|
|
202
|
+
};
|
|
203
|
+
}
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
## Error Correlation IDs
|
|
209
|
+
|
|
210
|
+
Every request gets a unique correlation ID. Include it in the response header and body. This is the only way to link a user-reported error to server logs.
|
|
211
|
+
|
|
212
|
+
```typescript
|
|
213
|
+
// Middleware: assign correlation ID
|
|
214
|
+
function correlationMiddleware(handler: Handler): Handler {
|
|
215
|
+
return async (context) => {
|
|
216
|
+
const correlationId = context.request.headers.get('X-Correlation-ID')
|
|
217
|
+
?? crypto.randomUUID();
|
|
218
|
+
|
|
219
|
+
// Attach to context for use in handlers
|
|
220
|
+
context.locals.correlationId = correlationId;
|
|
221
|
+
|
|
222
|
+
const response = await handler(context);
|
|
223
|
+
|
|
224
|
+
// Always include in response
|
|
225
|
+
response.headers.set('X-Correlation-ID', correlationId);
|
|
226
|
+
return response;
|
|
227
|
+
};
|
|
228
|
+
}
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
**Client-side: include in error reports:**
|
|
232
|
+
```typescript
|
|
233
|
+
try {
|
|
234
|
+
const response = await fetch('/api/models', { method: 'POST', body, headers });
|
|
235
|
+
if (!response.ok) {
|
|
236
|
+
const problem = await response.json();
|
|
237
|
+
// Show to user: "Contact support with reference: a1b2c3d4"
|
|
238
|
+
showError(problem.detail, problem.correlationId);
|
|
239
|
+
}
|
|
240
|
+
} catch (error) {
|
|
241
|
+
showError('Network error. Please check your connection.');
|
|
242
|
+
}
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
---
|
|
246
|
+
|
|
247
|
+
## Retry-After Headers
|
|
248
|
+
|
|
249
|
+
For 429 (rate limited) and 503 (service unavailable), always include `Retry-After`.
|
|
250
|
+
|
|
251
|
+
```typescript
|
|
252
|
+
function rateLimitResponse(retryAfterSeconds: number, correlationId: string): Response {
|
|
253
|
+
const problem: ProblemDetails = {
|
|
254
|
+
type: 'https://api.example.com/problems/rate-limited',
|
|
255
|
+
title: 'Too Many Requests',
|
|
256
|
+
status: 429,
|
|
257
|
+
detail: `Rate limit exceeded. Try again in ${retryAfterSeconds} seconds.`,
|
|
258
|
+
correlationId,
|
|
259
|
+
retryAfter: retryAfterSeconds,
|
|
260
|
+
};
|
|
261
|
+
|
|
262
|
+
return new Response(JSON.stringify(problem), {
|
|
263
|
+
status: 429,
|
|
264
|
+
headers: {
|
|
265
|
+
'Content-Type': 'application/problem+json',
|
|
266
|
+
'Retry-After': String(retryAfterSeconds),
|
|
267
|
+
'X-Correlation-ID': correlationId,
|
|
268
|
+
},
|
|
269
|
+
});
|
|
270
|
+
}
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
---
|
|
274
|
+
|
|
275
|
+
## Partial Success (207 Multi-Status)
|
|
276
|
+
|
|
277
|
+
When a batch operation partially succeeds, use 207 to report per-item results.
|
|
278
|
+
|
|
279
|
+
```typescript
|
|
280
|
+
interface BatchResult {
|
|
281
|
+
status: number;
|
|
282
|
+
id: string;
|
|
283
|
+
error?: ProblemDetails;
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
function batchResponse(results: BatchResult[]): Response {
|
|
287
|
+
const allSucceeded = results.every((r) => r.status >= 200 && r.status < 300);
|
|
288
|
+
|
|
289
|
+
return new Response(JSON.stringify({ results }), {
|
|
290
|
+
status: allSucceeded ? 200 : 207,
|
|
291
|
+
headers: { 'Content-Type': 'application/json' },
|
|
292
|
+
});
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
// Example response:
|
|
296
|
+
// {
|
|
297
|
+
// "results": [
|
|
298
|
+
// { "status": 201, "id": "item-1" },
|
|
299
|
+
// { "status": 422, "id": "item-2", "error": { "title": "Validation Failed", ... } },
|
|
300
|
+
// { "status": 201, "id": "item-3" }
|
|
301
|
+
// ]
|
|
302
|
+
// }
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
---
|
|
306
|
+
|
|
307
|
+
## Idempotency-Aware Error Handling
|
|
308
|
+
|
|
309
|
+
When a client retries a request with an `Idempotency-Key`, return the same response as the original request.
|
|
310
|
+
|
|
311
|
+
```typescript
|
|
312
|
+
async function handleIdempotentRequest(
|
|
313
|
+
idempotencyKey: string,
|
|
314
|
+
handler: () => Promise<Response>
|
|
315
|
+
): Promise<Response> {
|
|
316
|
+
// Check if this key was already processed
|
|
317
|
+
const cached = await idempotencyStore.get(idempotencyKey);
|
|
318
|
+
if (cached) {
|
|
319
|
+
return new Response(cached.body, {
|
|
320
|
+
status: cached.status,
|
|
321
|
+
headers: { ...cached.headers, 'X-Idempotency-Replayed': 'true' },
|
|
322
|
+
});
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
const response = await handler();
|
|
326
|
+
|
|
327
|
+
// Cache the response for this key (only for non-server-errors)
|
|
328
|
+
if (response.status < 500) {
|
|
329
|
+
await idempotencyStore.set(idempotencyKey, {
|
|
330
|
+
status: response.status,
|
|
331
|
+
headers: Object.fromEntries(response.headers),
|
|
332
|
+
body: await response.clone().text(),
|
|
333
|
+
}, { ttl: 24 * 60 * 60 }); // 24 hours
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
return response;
|
|
337
|
+
}
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
---
|
|
341
|
+
|
|
342
|
+
## Error Logging vs Error Response
|
|
343
|
+
|
|
344
|
+
| What to Log (Server) | What to Return (Client) |
|
|
345
|
+
|----------------------|------------------------|
|
|
346
|
+
| Full stack trace | Generic message |
|
|
347
|
+
| Database query that failed | "An internal error occurred" |
|
|
348
|
+
| User ID, IP, request body | Correlation ID only |
|
|
349
|
+
| Upstream service error details | "Service temporarily unavailable" |
|
|
350
|
+
| File paths, line numbers | Nothing |
|
|
351
|
+
|
|
352
|
+
```typescript
|
|
353
|
+
// WRONG: leaking internals
|
|
354
|
+
return new Response(JSON.stringify({
|
|
355
|
+
error: 'SQLITE_CONSTRAINT: UNIQUE constraint failed: users.email',
|
|
356
|
+
stack: 'Error at /app/src/db/users.ts:42...'
|
|
357
|
+
}), { status: 500 });
|
|
358
|
+
|
|
359
|
+
// CORRECT: safe response + internal log
|
|
360
|
+
logger.error('Database constraint violation', {
|
|
361
|
+
correlationId,
|
|
362
|
+
table: 'users',
|
|
363
|
+
constraint: 'unique_email',
|
|
364
|
+
userId: context.locals.userId,
|
|
365
|
+
});
|
|
366
|
+
|
|
367
|
+
return problemResponse({
|
|
368
|
+
type: 'https://api.example.com/problems/conflict',
|
|
369
|
+
title: 'Conflict',
|
|
370
|
+
status: 409,
|
|
371
|
+
detail: 'An account with this email already exists.',
|
|
372
|
+
correlationId,
|
|
373
|
+
});
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
---
|
|
377
|
+
|
|
378
|
+
## Circuit Breaker Pattern
|
|
379
|
+
|
|
380
|
+
When an upstream service is failing, stop sending requests to avoid cascade failures.
|
|
381
|
+
|
|
382
|
+
```typescript
|
|
383
|
+
enum CircuitState { CLOSED, OPEN, HALF_OPEN }
|
|
384
|
+
|
|
385
|
+
class CircuitBreaker {
|
|
386
|
+
private state = CircuitState.CLOSED;
|
|
387
|
+
private failureCount = 0;
|
|
388
|
+
private lastFailureTime = 0;
|
|
389
|
+
|
|
390
|
+
constructor(
|
|
391
|
+
private readonly threshold: number = 5,
|
|
392
|
+
private readonly resetTimeout: number = 30_000,
|
|
393
|
+
) {}
|
|
394
|
+
|
|
395
|
+
async call<T>(fn: () => Promise<T>): Promise<T> {
|
|
396
|
+
if (this.state === CircuitState.OPEN) {
|
|
397
|
+
if (Date.now() - this.lastFailureTime > this.resetTimeout) {
|
|
398
|
+
this.state = CircuitState.HALF_OPEN;
|
|
399
|
+
} else {
|
|
400
|
+
throw new CircuitOpenError('Circuit breaker is open');
|
|
401
|
+
}
|
|
402
|
+
}
|
|
403
|
+
|
|
404
|
+
try {
|
|
405
|
+
const result = await fn();
|
|
406
|
+
this.onSuccess();
|
|
407
|
+
return result;
|
|
408
|
+
} catch (error) {
|
|
409
|
+
this.onFailure();
|
|
410
|
+
throw error;
|
|
411
|
+
}
|
|
412
|
+
}
|
|
413
|
+
|
|
414
|
+
private onSuccess(): void {
|
|
415
|
+
this.failureCount = 0;
|
|
416
|
+
this.state = CircuitState.CLOSED;
|
|
417
|
+
}
|
|
418
|
+
|
|
419
|
+
private onFailure(): void {
|
|
420
|
+
this.failureCount++;
|
|
421
|
+
this.lastFailureTime = Date.now();
|
|
422
|
+
if (this.failureCount >= this.threshold) {
|
|
423
|
+
this.state = CircuitState.OPEN;
|
|
424
|
+
}
|
|
425
|
+
}
|
|
426
|
+
}
|
|
427
|
+
|
|
428
|
+
class CircuitOpenError extends Error {
|
|
429
|
+
constructor(message: string) {
|
|
430
|
+
super(message);
|
|
431
|
+
this.name = 'CircuitOpenError';
|
|
432
|
+
}
|
|
433
|
+
}
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
**Usage:**
|
|
437
|
+
```typescript
|
|
438
|
+
const aiServiceBreaker = new CircuitBreaker(5, 30_000);
|
|
439
|
+
|
|
440
|
+
try {
|
|
441
|
+
const result = await aiServiceBreaker.call(() => callAIService(prompt));
|
|
442
|
+
return new Response(JSON.stringify(result), { status: 200 });
|
|
443
|
+
} catch (error) {
|
|
444
|
+
if (error instanceof CircuitOpenError) {
|
|
445
|
+
return problemResponse({
|
|
446
|
+
type: 'https://api.example.com/problems/service-unavailable',
|
|
447
|
+
title: 'Service Unavailable',
|
|
448
|
+
status: 503,
|
|
449
|
+
detail: 'The AI service is temporarily unavailable. Please try again shortly.',
|
|
450
|
+
correlationId,
|
|
451
|
+
retryAfter: 30,
|
|
452
|
+
});
|
|
453
|
+
}
|
|
454
|
+
throw error;
|
|
455
|
+
}
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
---
|
|
459
|
+
|
|
460
|
+
## Anti-Patterns
|
|
461
|
+
|
|
462
|
+
| Anti-Pattern | Correct Approach |
|
|
463
|
+
|-------------|------------------|
|
|
464
|
+
| Return 200 with `{ error: true }` in body | Use proper HTTP status codes |
|
|
465
|
+
| Return 500 for all errors | Distinguish client (4xx) from server (5xx) errors |
|
|
466
|
+
| Return stack traces in production | Log internally, return generic message + correlation ID |
|
|
467
|
+
| Different error formats per endpoint | Use RFC 7807 everywhere |
|
|
468
|
+
| Swallow errors silently | Log every error with correlation ID |
|
|
469
|
+
| Return `{ message: "Error" }` | Include type, title, status, detail, and correlation ID |
|
|
470
|
+
| Expose database error messages | Map to user-friendly messages |
|
|
471
|
+
| Return 404 for unauthorized resources | Return 403 or 404 depending on security model (prefer 404 to avoid resource enumeration) |
|
|
472
|
+
|
|
473
|
+
## References
|
|
474
|
+
|
|
475
|
+
- [RFC 7807: Problem Details for HTTP APIs](https://tools.ietf.org/html/rfc7807)
|
|
476
|
+
- [RFC 9457: Problem Details (updated)](https://www.rfc-editor.org/rfc/rfc9457.html)
|
|
477
|
+
- [HTTP Status Codes (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)
|
|
478
|
+
- [Microsoft API Guidelines: Error Handling](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md)
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: api-security-checklist
|
|
3
|
+
description: "API-focused security checklist covering OWASP API Top 10, authentication hardening, input validation, rate limiting, and compliance controls for API surfaces."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Implement comprehensive security hardening with defense-in-depth strategy through coordinated multi-agent orchestration:
|
|
7
|
+
|
|
8
|
+
[Extended thinking: This workflow implements a defense-in-depth security strategy across all application layers. It coordinates specialized security agents to perform comprehensive assessments, implement layered security controls, and establish continuous security monitoring. The approach follows modern DevSecOps principles with shift-left security, automated scanning, and compliance validation. Each phase builds upon previous findings to create a resilient security posture that addresses both current vulnerabilities and future threats.]
|
|
9
|
+
|
|
10
|
+
## Use this skill when
|
|
11
|
+
|
|
12
|
+
- Running a coordinated security hardening program
|
|
13
|
+
- Establishing defense-in-depth controls across app, infra, and CI/CD
|
|
14
|
+
- Prioritizing remediation from scans and threat modeling
|
|
15
|
+
|
|
16
|
+
## Do not use this skill when
|
|
17
|
+
|
|
18
|
+
- You only need a quick scan without remediation work
|
|
19
|
+
- You lack authorization for security testing or changes
|
|
20
|
+
- The environment cannot tolerate invasive security controls
|
|
21
|
+
|
|
22
|
+
## Instructions
|
|
23
|
+
|
|
24
|
+
1. Execute Phase 1 to establish a security baseline.
|
|
25
|
+
2. Apply Phase 2 remediations for high-risk issues.
|
|
26
|
+
3. Implement Phase 3 controls and validate defenses.
|
|
27
|
+
4. Complete Phase 4 validation and compliance checks.
|
|
28
|
+
|
|
29
|
+
## Safety
|
|
30
|
+
|
|
31
|
+
- Avoid intrusive testing in production without approval.
|
|
32
|
+
- Ensure rollback plans exist before hardening changes.
|
|
33
|
+
|
|
34
|
+
## Phase 1: Comprehensive Security Assessment
|
|
35
|
+
|
|
36
|
+
### 1. Initial Vulnerability Scanning
|
|
37
|
+
- Use Task tool with subagent_type="security-auditor"
|
|
38
|
+
- Prompt: "Perform comprehensive security assessment on: $ARGUMENTS. Execute SAST analysis with Semgrep/SonarQube, DAST scanning with OWASP ZAP, dependency audit with Snyk/Trivy, secrets detection with GitLeaks/TruffleHog. Generate SBOM for supply chain analysis. Identify OWASP Top 10 vulnerabilities, CWE weaknesses, and CVE exposures."
|
|
39
|
+
- Output: Detailed vulnerability report with CVSS scores, exploitability analysis, attack surface mapping, secrets exposure report, SBOM inventory
|
|
40
|
+
- Context: Initial baseline for all remediation efforts
|
|
41
|
+
|
|
42
|
+
### 2. Threat Modeling and Risk Analysis
|
|
43
|
+
- Use Task tool with subagent_type="security-auditor"
|
|
44
|
+
- Prompt: "Conduct threat modeling using STRIDE methodology for: $ARGUMENTS. Analyze attack vectors, create attack trees, assess business impact of identified vulnerabilities. Map threats to MITRE ATT&CK framework. Prioritize risks based on likelihood and impact."
|
|
45
|
+
- Output: Threat model diagrams, risk matrix with prioritized vulnerabilities, attack scenario documentation, business impact analysis
|
|
46
|
+
- Context: Uses vulnerability scan results to inform threat priorities
|
|
47
|
+
|
|
48
|
+
### 3. Architecture Security Review
|
|
49
|
+
- Use Task tool with subagent_type="backend-api-security::backend-architect"
|
|
50
|
+
- Prompt: "Review architecture for security weaknesses in: $ARGUMENTS. Evaluate service boundaries, data flow security, authentication/authorization architecture, encryption implementation, network segmentation. Design zero-trust architecture patterns. Reference threat model and vulnerability findings."
|
|
51
|
+
- Output: Security architecture assessment, zero-trust design recommendations, service mesh security requirements, data classification matrix
|
|
52
|
+
- Context: Incorporates threat model to address architectural vulnerabilities
|
|
53
|
+
|
|
54
|
+
## Phase 2: Vulnerability Remediation
|
|
55
|
+
|
|
56
|
+
### 4. Critical Vulnerability Fixes
|
|
57
|
+
- Use Task tool with subagent_type="security-auditor"
|
|
58
|
+
- Prompt: "Coordinate immediate remediation of critical vulnerabilities (CVSS 7+) in: $ARGUMENTS. Fix SQL injections with parameterized queries, XSS with output encoding, authentication bypasses with secure session management, insecure deserialization with input validation. Apply security patches for CVEs."
|
|
59
|
+
- Output: Patched code with vulnerability fixes, security patch documentation, regression test requirements
|
|
60
|
+
- Context: Addresses high-priority items from vulnerability assessment
|
|
61
|
+
|
|
62
|
+
### 5. Backend Security Hardening
|
|
63
|
+
- Use Task tool with subagent_type="backend-api-security::backend-security-coder"
|
|
64
|
+
- Prompt: "Implement comprehensive backend security controls for: $ARGUMENTS. Add input validation with OWASP ESAPI, implement rate limiting and DDoS protection, secure API endpoints with OAuth2/JWT validation, add encryption for data at rest/transit using AES-256/TLS 1.3. Implement secure logging without PII exposure."
|
|
65
|
+
- Output: Hardened API endpoints, validation middleware, encryption implementation, secure configuration templates
|
|
66
|
+
- Context: Builds upon vulnerability fixes with preventive controls
|
|
67
|
+
|
|
68
|
+
### 6. Frontend Security Implementation
|
|
69
|
+
- Use Task tool with subagent_type="frontend-mobile-security::frontend-security-coder"
|
|
70
|
+
- Prompt: "Implement frontend security measures for: $ARGUMENTS. Configure CSP headers with nonce-based policies, implement XSS prevention with DOMPurify, secure authentication flows with PKCE OAuth2, add SRI for external resources, implement secure cookie handling with SameSite/HttpOnly/Secure flags."
|
|
71
|
+
- Output: Secure frontend components, CSP policy configuration, authentication flow implementation, security headers configuration
|
|
72
|
+
- Context: Complements backend security with client-side protections
|
|
73
|
+
|
|
74
|
+
### 7. Mobile Security Hardening
|
|
75
|
+
- Use Task tool with subagent_type="frontend-mobile-security::mobile-security-coder"
|
|
76
|
+
- Prompt: "Implement mobile app security for: $ARGUMENTS. Add certificate pinning, implement biometric authentication, secure local storage with encryption, obfuscate code with ProGuard/R8, implement anti-tampering and root/jailbreak detection, secure IPC communications."
|
|
77
|
+
- Output: Hardened mobile application, security configuration files, obfuscation rules, certificate pinning implementation
|
|
78
|
+
- Context: Extends security to mobile platforms if applicable
|
|
79
|
+
|
|
80
|
+
## Phase 3: Security Controls Implementation
|
|
81
|
+
|
|
82
|
+
### 8. Authentication and Authorization Enhancement
|
|
83
|
+
- Use Task tool with subagent_type="security-auditor"
|
|
84
|
+
- Prompt: "Implement modern authentication system for: $ARGUMENTS. Deploy OAuth2/OIDC with PKCE, implement MFA with TOTP/WebAuthn/FIDO2, add risk-based authentication, implement RBAC/ABAC with principle of least privilege, add session management with secure token rotation."
|
|
85
|
+
- Output: Authentication service configuration, MFA implementation, authorization policies, session management system
|
|
86
|
+
- Context: Strengthens access controls based on architecture review
|
|
87
|
+
|
|
88
|
+
### 9. Infrastructure Security Controls
|
|
89
|
+
- Use Task tool with subagent_type="deployment-strategies::deployment-engineer"
|
|
90
|
+
- Prompt: "Deploy infrastructure security controls for: $ARGUMENTS. Configure WAF rules for OWASP protection, implement network segmentation with micro-segmentation, deploy IDS/IPS systems, configure cloud security groups and NACLs, implement DDoS protection with rate limiting and geo-blocking."
|
|
91
|
+
- Output: WAF configuration, network security policies, IDS/IPS rules, cloud security configurations
|
|
92
|
+
- Context: Implements network-level defenses
|
|
93
|
+
|
|
94
|
+
### 10. Secrets Management Implementation
|
|
95
|
+
- Use Task tool with subagent_type="deployment-strategies::deployment-engineer"
|
|
96
|
+
- Prompt: "Implement enterprise secrets management for: $ARGUMENTS. Deploy HashiCorp Vault or AWS Secrets Manager, implement secret rotation policies, remove hardcoded secrets, configure least-privilege IAM roles, implement encryption key management with HSM support."
|
|
97
|
+
- Output: Secrets management configuration, rotation policies, IAM role definitions, key management procedures
|
|
98
|
+
- Context: Eliminates secrets exposure vulnerabilities
|
|
99
|
+
|
|
100
|
+
## Phase 4: Validation and Compliance
|
|
101
|
+
|
|
102
|
+
### 11. Penetration Testing and Validation
|
|
103
|
+
- Use Task tool with subagent_type="security-auditor"
|
|
104
|
+
- Prompt: "Execute comprehensive penetration testing for: $ARGUMENTS. Perform authenticated and unauthenticated testing, API security testing, business logic testing, privilege escalation attempts. Use Burp Suite, Metasploit, and custom exploits. Validate all security controls effectiveness."
|
|
105
|
+
- Output: Penetration test report, proof-of-concept exploits, remediation validation, security control effectiveness metrics
|
|
106
|
+
- Context: Validates all implemented security measures
|
|
107
|
+
|
|
108
|
+
### 12. Compliance and Standards Verification
|
|
109
|
+
- Use Task tool with subagent_type="security-auditor"
|
|
110
|
+
- Prompt: "Verify compliance with security frameworks for: $ARGUMENTS. Validate against OWASP ASVS Level 2, CIS Benchmarks, SOC2 Type II requirements, GDPR/CCPA privacy controls, HIPAA/PCI-DSS if applicable. Generate compliance attestation reports."
|
|
111
|
+
- Output: Compliance assessment report, gap analysis, remediation requirements, audit evidence collection
|
|
112
|
+
- Context: Ensures regulatory and industry standard compliance
|
|
113
|
+
|
|
114
|
+
### 13. Security Monitoring and SIEM Integration
|
|
115
|
+
- Use Task tool with subagent_type="incident-response::devops-troubleshooter"
|
|
116
|
+
- Prompt: "Implement security monitoring and SIEM for: $ARGUMENTS. Deploy Splunk/ELK/Sentinel integration, configure security event correlation, implement behavioral analytics for anomaly detection, set up automated incident response playbooks, create security dashboards and alerting."
|
|
117
|
+
- Output: SIEM configuration, correlation rules, incident response playbooks, security dashboards, alert definitions
|
|
118
|
+
- Context: Establishes continuous security monitoring
|
|
119
|
+
|
|
120
|
+
## Configuration Options
|
|
121
|
+
- scanning_depth: "quick" | "standard" | "comprehensive" (default: comprehensive)
|
|
122
|
+
- compliance_frameworks: ["OWASP", "CIS", "SOC2", "GDPR", "HIPAA", "PCI-DSS"]
|
|
123
|
+
- remediation_priority: "cvss_score" | "exploitability" | "business_impact"
|
|
124
|
+
- monitoring_integration: "splunk" | "elastic" | "sentinel" | "custom"
|
|
125
|
+
- authentication_methods: ["oauth2", "saml", "mfa", "biometric", "passwordless"]
|
|
126
|
+
|
|
127
|
+
## Success Criteria
|
|
128
|
+
- All critical vulnerabilities (CVSS 7+) remediated
|
|
129
|
+
- OWASP Top 10 vulnerabilities addressed
|
|
130
|
+
- Zero high-risk findings in penetration testing
|
|
131
|
+
- Compliance frameworks validation passed
|
|
132
|
+
- Security monitoring detecting and alerting on threats
|
|
133
|
+
- Incident response time < 15 minutes for critical alerts
|
|
134
|
+
- SBOM generated and vulnerabilities tracked
|
|
135
|
+
- All secrets managed through secure vault
|
|
136
|
+
- Authentication implements MFA and secure session management
|
|
137
|
+
- Security tests integrated into CI/CD pipeline
|
|
138
|
+
|
|
139
|
+
## Coordination Notes
|
|
140
|
+
- Each phase provides detailed findings that inform subsequent phases
|
|
141
|
+
- Security-auditor agent coordinates with domain-specific agents for fixes
|
|
142
|
+
- All code changes undergo security review before implementation
|
|
143
|
+
- Continuous feedback loop between assessment and remediation
|
|
144
|
+
- Security findings tracked in centralized vulnerability management system
|
|
145
|
+
- Regular security reviews scheduled post-implementation
|
|
146
|
+
|
|
147
|
+
Security hardening target: $ARGUMENTS
|