@cubis/foundry 0.3.71 → 0.3.73
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/CHANGELOG.md +23 -2
- package/dist/cli/core.js +9 -22
- package/dist/cli/core.js.map +1 -1
- package/package.json +1 -1
- package/src/cli/core.ts +13 -22
- package/workflows/powers/accessibility/POWER.md +83 -94
- package/workflows/powers/accessibility/SKILL.md +82 -94
- package/workflows/powers/agent-design/POWER.md +201 -0
- package/workflows/powers/agent-design/SKILL.md +198 -0
- package/workflows/powers/agent-design/references/clarification-patterns.md +153 -0
- package/workflows/powers/agent-design/references/skill-testing.md +164 -0
- package/workflows/powers/agent-design/references/workflow-patterns.md +226 -0
- package/workflows/powers/agentic-eval/POWER.md +62 -0
- package/workflows/powers/agentic-eval/SKILL.md +59 -0
- package/workflows/powers/agentic-eval/references/rubric-and-regression-checklist.md +11 -0
- package/workflows/powers/api-designer/POWER.md +43 -71
- package/workflows/powers/api-designer/SKILL.md +43 -71
- package/workflows/powers/api-patterns/POWER.md +42 -56
- package/workflows/powers/api-patterns/SKILL.md +42 -57
- package/workflows/powers/architecture-designer/POWER.md +43 -60
- package/workflows/powers/architecture-designer/SKILL.md +43 -60
- package/workflows/powers/ask-questions-if-underspecified/POWER.md +51 -3
- package/workflows/powers/auth-architect/POWER.md +69 -0
- package/workflows/powers/auth-architect/SKILL.md +66 -0
- package/workflows/powers/auth-architect/references/session-token-policy-checklist.md +45 -0
- package/workflows/powers/behavioral-modes/POWER.md +100 -9
- package/workflows/powers/c-pro/POWER.md +105 -0
- package/workflows/powers/c-pro/SKILL.md +102 -0
- package/workflows/powers/c-pro/references/build-systems-and-toolchains.md +148 -0
- package/workflows/powers/c-pro/references/common-ub-and-portability.md +166 -0
- package/workflows/powers/c-pro/references/debugging-with-sanitizers.md +205 -0
- package/workflows/powers/c-pro/references/memory-safety-and-build-checklist.md +60 -0
- package/workflows/powers/c-pro/references/posix-and-platform-apis.md +244 -0
- package/workflows/powers/changelog-generator/POWER.md +127 -63
- package/workflows/powers/changelog-generator/SKILL.md +126 -63
- package/workflows/powers/ci-cd-pipelines/POWER.md +156 -0
- package/workflows/powers/ci-cd-pipelines/SKILL.md +153 -0
- package/workflows/powers/ci-cd-pipelines/references/github-actions-patterns.md +160 -0
- package/workflows/powers/ci-cd-pipelines/references/pipeline-security-checklist.md +57 -0
- package/workflows/powers/cli-developer/POWER.md +152 -95
- package/workflows/powers/cli-developer/SKILL.md +152 -95
- package/workflows/powers/cpp-pro/POWER.md +111 -0
- package/workflows/powers/cpp-pro/SKILL.md +108 -0
- package/workflows/powers/cpp-pro/references/concurrency-primitives.md +266 -0
- package/workflows/powers/cpp-pro/references/move-semantics-and-value-types.md +149 -0
- package/workflows/powers/cpp-pro/references/performance-and-profiling.md +191 -0
- package/workflows/powers/cpp-pro/references/raii-and-modern-cpp-checklist.md +87 -0
- package/workflows/powers/cpp-pro/references/template-and-concepts-patterns.md +205 -0
- package/workflows/powers/csharp-pro/POWER.md +47 -22
- package/workflows/powers/csharp-pro/SKILL.md +47 -22
- package/workflows/powers/dart-pro/POWER.md +68 -0
- package/workflows/powers/dart-pro/SKILL.md +65 -0
- package/workflows/powers/dart-pro/references/isolate-and-concurrency.md +180 -0
- package/workflows/powers/dart-pro/references/null-safety-and-async-patterns.md +133 -0
- package/workflows/powers/dart-pro/references/package-structure-and-linting.md +193 -0
- package/workflows/powers/dart-pro/references/sealed-records-patterns.md +173 -0
- package/workflows/powers/dart-pro/references/testing-and-mocking.md +235 -0
- package/workflows/powers/database-design/POWER.md +47 -33
- package/workflows/powers/database-design/SKILL.md +47 -33
- package/workflows/powers/database-optimizer/POWER.md +43 -64
- package/workflows/powers/database-optimizer/SKILL.md +43 -64
- package/workflows/powers/database-skills/POWER.md +59 -93
- package/workflows/powers/database-skills/SKILL.md +59 -93
- package/workflows/powers/debugging-strategies/POWER.md +69 -0
- package/workflows/powers/debugging-strategies/SKILL.md +66 -0
- package/workflows/powers/debugging-strategies/references/reproduce-isolate-verify-checklist.md +42 -0
- package/workflows/powers/deep-research/POWER.md +67 -0
- package/workflows/powers/deep-research/SKILL.md +64 -0
- package/workflows/powers/deep-research/references/multi-round-research-loop.md +80 -0
- package/workflows/powers/design-system-builder/POWER.md +130 -116
- package/workflows/powers/design-system-builder/SKILL.md +130 -116
- package/workflows/powers/devops-engineer/POWER.md +120 -57
- package/workflows/powers/devops-engineer/SKILL.md +120 -57
- package/workflows/powers/docker-kubernetes/POWER.md +94 -0
- package/workflows/powers/docker-kubernetes/SKILL.md +91 -0
- package/workflows/powers/docker-kubernetes/references/dockerfile-optimization-checklist.md +35 -0
- package/workflows/powers/docker-kubernetes/references/kubernetes-deployment-patterns.md +59 -0
- package/workflows/powers/documentation-templates/POWER.md +158 -127
- package/workflows/powers/documentation-templates/SKILL.md +158 -127
- package/workflows/powers/drizzle-expert/POWER.md +66 -0
- package/workflows/powers/drizzle-expert/SKILL.md +63 -0
- package/workflows/powers/drizzle-expert/references/runtime-pairing-matrix.md +16 -0
- package/workflows/powers/drizzle-expert/references/schema-and-migration-playbook.md +18 -0
- package/workflows/powers/error-ux-observability/POWER.md +144 -131
- package/workflows/powers/error-ux-observability/SKILL.md +143 -131
- package/workflows/powers/fastapi-expert/POWER.md +46 -60
- package/workflows/powers/fastapi-expert/SKILL.md +46 -60
- package/workflows/powers/firebase/POWER.md +65 -0
- package/workflows/powers/firebase/SKILL.md +62 -0
- package/workflows/powers/firebase/references/platform-routing.md +16 -0
- package/workflows/powers/firebase/references/rules-and-indexes-checklist.md +11 -0
- package/workflows/powers/flutter-design-system/POWER.md +63 -0
- package/workflows/powers/flutter-design-system/SKILL.md +60 -0
- package/workflows/powers/flutter-design-system/references/shared-widgets.md +29 -0
- package/workflows/powers/flutter-design-system/references/tokens-and-theme.md +34 -0
- package/workflows/powers/flutter-drift/POWER.md +65 -0
- package/workflows/powers/flutter-drift/SKILL.md +62 -0
- package/workflows/powers/flutter-drift/references/migrations.md +22 -0
- package/workflows/powers/flutter-drift/references/query-patterns.md +26 -0
- package/workflows/powers/flutter-feature/POWER.md +65 -0
- package/workflows/powers/flutter-feature/SKILL.md +62 -0
- package/workflows/powers/flutter-feature/references/architecture-rules.md +85 -0
- package/workflows/powers/flutter-feature/references/composite-provider.md +58 -0
- package/workflows/powers/flutter-feature/references/outbox-pattern.md +87 -0
- package/workflows/powers/flutter-feature/references/testing-patterns.md +218 -0
- package/workflows/powers/flutter-go-router/POWER.md +64 -0
- package/workflows/powers/flutter-go-router/SKILL.md +61 -0
- package/workflows/powers/flutter-go-router/references/guards-and-deeplinks.md +20 -0
- package/workflows/powers/flutter-go-router/references/typed-routes.md +27 -0
- package/workflows/powers/flutter-offline-sync/POWER.md +62 -0
- package/workflows/powers/flutter-offline-sync/SKILL.md +59 -0
- package/workflows/powers/flutter-offline-sync/references/outbox-full.md +44 -0
- package/workflows/powers/flutter-repository/POWER.md +64 -0
- package/workflows/powers/flutter-repository/SKILL.md +61 -0
- package/workflows/powers/flutter-repository/references/drift-patterns.md +21 -0
- package/workflows/powers/flutter-repository/references/retrofit-patterns.md +20 -0
- package/workflows/powers/flutter-riverpod/POWER.md +70 -0
- package/workflows/powers/flutter-riverpod/SKILL.md +67 -0
- package/workflows/powers/flutter-riverpod/references/async-and-mutations.md +19 -0
- package/workflows/powers/flutter-riverpod/references/async-lifecycle.md +19 -0
- package/workflows/powers/flutter-riverpod/references/provider-selection.md +20 -0
- package/workflows/powers/flutter-riverpod/references/testing.md +21 -0
- package/workflows/powers/flutter-riverpod/references/version-matrix.md +24 -0
- package/workflows/powers/flutter-state-machine/POWER.md +62 -0
- package/workflows/powers/flutter-state-machine/SKILL.md +59 -0
- package/workflows/powers/flutter-state-machine/references/app-state-contract.md +23 -0
- package/workflows/powers/flutter-state-machine/references/ui-rendering.md +14 -0
- package/workflows/powers/flutter-testing/POWER.md +64 -0
- package/workflows/powers/flutter-testing/SKILL.md +61 -0
- package/workflows/powers/flutter-testing/references/offline-sync-tests.md +16 -0
- package/workflows/powers/flutter-testing/references/test-layers.md +33 -0
- package/workflows/powers/frontend-code-review/POWER.md +137 -0
- package/workflows/powers/frontend-code-review/SKILL.md +134 -0
- package/workflows/powers/frontend-code-review/references/common-antipatterns.md +86 -0
- package/workflows/powers/frontend-code-review/references/performance-budgets.md +56 -0
- package/workflows/powers/frontend-code-review/references/review-checklists.md +47 -0
- package/workflows/powers/frontend-design/POWER.md +163 -362
- package/workflows/powers/frontend-design/SKILL.md +163 -362
- package/workflows/powers/game-development/POWER.md +57 -140
- package/workflows/powers/game-development/SKILL.md +57 -140
- package/workflows/powers/geo-fundamentals/POWER.md +64 -126
- package/workflows/powers/geo-fundamentals/SKILL.md +64 -127
- package/workflows/powers/git-workflow/POWER.md +135 -0
- package/workflows/powers/git-workflow/SKILL.md +132 -0
- package/workflows/powers/git-workflow/references/pr-review-checklist.md +63 -0
- package/workflows/powers/golang-pro/POWER.md +46 -35
- package/workflows/powers/golang-pro/SKILL.md +46 -35
- package/workflows/powers/graphql-architect/POWER.md +44 -62
- package/workflows/powers/graphql-architect/SKILL.md +44 -62
- package/workflows/powers/i18n-localization/POWER.md +118 -103
- package/workflows/powers/i18n-localization/SKILL.md +118 -103
- package/workflows/powers/java-pro/POWER.md +47 -22
- package/workflows/powers/java-pro/SKILL.md +47 -22
- package/workflows/powers/javascript-pro/POWER.md +47 -34
- package/workflows/powers/javascript-pro/SKILL.md +47 -34
- package/workflows/powers/kotlin-pro/POWER.md +46 -23
- package/workflows/powers/kotlin-pro/SKILL.md +46 -23
- package/workflows/powers/legacy-modernizer/POWER.md +43 -60
- package/workflows/powers/legacy-modernizer/SKILL.md +43 -60
- package/workflows/powers/mcp-builder/POWER.md +65 -0
- package/workflows/powers/mcp-builder/SKILL.md +62 -0
- package/workflows/powers/mcp-builder/references/testing-and-evals.md +17 -0
- package/workflows/powers/mcp-builder/references/transport-and-tool-design.md +17 -0
- package/workflows/powers/microservices-architect/POWER.md +43 -70
- package/workflows/powers/microservices-architect/SKILL.md +43 -70
- package/workflows/powers/mobile-design/POWER.md +110 -345
- package/workflows/powers/mobile-design/SKILL.md +110 -345
- package/workflows/powers/mongodb/POWER.md +67 -0
- package/workflows/powers/mongodb/SKILL.md +64 -0
- package/workflows/powers/mongodb/references/mongodb-checklist.md +20 -0
- package/workflows/powers/mysql/POWER.md +67 -0
- package/workflows/powers/mysql/SKILL.md +64 -0
- package/workflows/powers/mysql/references/mysql-checklist.md +20 -0
- package/workflows/powers/neki/POWER.md +67 -0
- package/workflows/powers/neki/SKILL.md +64 -0
- package/workflows/powers/neki/references/neki-checklist.md +18 -0
- package/workflows/powers/nestjs-expert/POWER.md +45 -91
- package/workflows/powers/nestjs-expert/SKILL.md +45 -91
- package/workflows/powers/nextjs-developer/POWER.md +51 -44
- package/workflows/powers/nextjs-developer/SKILL.md +51 -44
- package/workflows/powers/nodejs-best-practices/POWER.md +48 -29
- package/workflows/powers/nodejs-best-practices/SKILL.md +48 -29
- package/workflows/powers/observability/POWER.md +109 -0
- package/workflows/powers/observability/SKILL.md +106 -0
- package/workflows/powers/observability/references/alerting-and-slo-checklist.md +87 -0
- package/workflows/powers/observability/references/opentelemetry-setup-guide.md +121 -0
- package/workflows/powers/openai-docs/POWER.md +61 -0
- package/workflows/powers/openai-docs/SKILL.md +58 -0
- package/workflows/powers/openai-docs/references/official-source-playbook.md +10 -0
- package/workflows/powers/performance-profiling/POWER.md +61 -114
- package/workflows/powers/performance-profiling/SKILL.md +61 -114
- package/workflows/powers/php-pro/POWER.md +116 -0
- package/workflows/powers/php-pro/SKILL.md +113 -0
- package/workflows/powers/php-pro/references/architecture-and-di.md +239 -0
- package/workflows/powers/php-pro/references/modern-php-features.md +189 -0
- package/workflows/powers/php-pro/references/performance-and-deployment.md +197 -0
- package/workflows/powers/php-pro/references/php84-strict-typing-checklist.md +161 -0
- package/workflows/powers/php-pro/references/testing-and-static-analysis.md +235 -0
- package/workflows/powers/playwright-e2e/POWER.md +85 -0
- package/workflows/powers/playwright-e2e/SKILL.md +82 -0
- package/workflows/powers/playwright-e2e/references/locator-trace-flake-checklist.md +80 -0
- package/workflows/powers/postgres/POWER.md +67 -0
- package/workflows/powers/postgres/SKILL.md +64 -0
- package/workflows/powers/postgres/references/postgres-checklist.md +20 -0
- package/workflows/powers/prompt-engineer/POWER.md +47 -30
- package/workflows/powers/prompt-engineer/SKILL.md +47 -30
- package/workflows/powers/python-pro/POWER.md +47 -36
- package/workflows/powers/python-pro/SKILL.md +47 -36
- package/workflows/powers/react-best-practices/POWER.md +56 -33
- package/workflows/powers/react-best-practices/SKILL.md +56 -33
- package/workflows/powers/react-expert/POWER.md +47 -37
- package/workflows/powers/react-expert/SKILL.md +47 -37
- package/workflows/powers/redis/POWER.md +67 -0
- package/workflows/powers/redis/SKILL.md +64 -0
- package/workflows/powers/redis/references/redis-checklist.md +19 -0
- package/workflows/powers/ruby-pro/POWER.md +118 -0
- package/workflows/powers/ruby-pro/SKILL.md +115 -0
- package/workflows/powers/ruby-pro/references/modern-ruby-features.md +189 -0
- package/workflows/powers/ruby-pro/references/object-design-patterns.md +220 -0
- package/workflows/powers/ruby-pro/references/performance-and-profiling.md +224 -0
- package/workflows/powers/ruby-pro/references/ruby-concurrency-and-testing.md +190 -0
- package/workflows/powers/ruby-pro/references/testing-and-rspec.md +236 -0
- package/workflows/powers/rust-pro/POWER.md +45 -31
- package/workflows/powers/rust-pro/SKILL.md +45 -31
- package/workflows/powers/security-engineer/POWER.md +129 -0
- package/workflows/powers/security-engineer/SKILL.md +126 -0
- package/workflows/powers/seo-fundamentals/POWER.md +59 -102
- package/workflows/powers/seo-fundamentals/SKILL.md +59 -102
- package/workflows/powers/serverless-patterns/POWER.md +171 -0
- package/workflows/powers/serverless-patterns/SKILL.md +168 -0
- package/workflows/powers/skill-creator/POWER.md +90 -0
- package/workflows/powers/skill-creator/SKILL.md +87 -0
- package/workflows/powers/skill-creator/references/platform-formats.md +181 -0
- package/workflows/powers/skill-creator/references/schemas.md +430 -0
- package/workflows/powers/spec-miner/POWER.md +49 -57
- package/workflows/powers/spec-miner/SKILL.md +49 -57
- package/workflows/powers/sqlite/POWER.md +67 -0
- package/workflows/powers/sqlite/SKILL.md +64 -0
- package/workflows/powers/sqlite/references/sqlite-checklist.md +19 -0
- package/workflows/powers/sre-engineer/POWER.md +123 -64
- package/workflows/powers/sre-engineer/SKILL.md +123 -64
- package/workflows/powers/static-analysis/POWER.md +121 -77
- package/workflows/powers/static-analysis/SKILL.md +121 -77
- package/workflows/powers/stripe-best-practices/POWER.md +140 -17
- package/workflows/powers/stripe-best-practices/SKILL.md +139 -17
- package/workflows/powers/supabase/POWER.md +67 -0
- package/workflows/powers/supabase/SKILL.md +64 -0
- package/workflows/powers/supabase/references/supabase-checklist.md +19 -0
- package/workflows/powers/swift-pro/POWER.md +118 -0
- package/workflows/powers/swift-pro/SKILL.md +115 -0
- package/workflows/powers/swift-pro/references/concurrency-patterns.md +165 -0
- package/workflows/powers/swift-pro/references/protocol-and-generics.md +172 -0
- package/workflows/powers/swift-pro/references/sendable-and-isolation.md +116 -0
- package/workflows/powers/swift-pro/references/swift-concurrency-and-protocols.md +260 -0
- package/workflows/powers/swift-pro/references/testing-and-packages.md +192 -0
- package/workflows/powers/tailwind-patterns/POWER.md +71 -240
- package/workflows/powers/tailwind-patterns/SKILL.md +71 -240
- package/workflows/powers/testing-patterns/POWER.md +155 -10
- package/workflows/powers/testing-patterns/SKILL.md +155 -10
- package/workflows/powers/typescript-pro/POWER.md +47 -38
- package/workflows/powers/typescript-pro/SKILL.md +47 -38
- package/workflows/powers/vitess/POWER.md +67 -0
- package/workflows/powers/vitess/SKILL.md +64 -0
- package/workflows/powers/vitess/references/vitess-checklist.md +19 -0
- package/workflows/powers/vulnerability-scanner/POWER.md +146 -10
- package/workflows/powers/vulnerability-scanner/SKILL.md +146 -10
- package/workflows/powers/web-perf/POWER.md +43 -170
- package/workflows/powers/web-perf/SKILL.md +43 -170
- package/workflows/powers/webapp-testing/POWER.md +43 -164
- package/workflows/powers/webapp-testing/SKILL.md +43 -164
- package/workflows/workflows/agent-environment-setup/platforms/antigravity/rules/GEMINI.md +65 -42
- package/workflows/workflows/agent-environment-setup/platforms/claude/rules/CLAUDE.md +8 -6
- package/workflows/workflows/agent-environment-setup/platforms/codex/rules/AGENTS.md +65 -41
- package/workflows/workflows/agent-environment-setup/platforms/copilot/rules/copilot-instructions.md +8 -6
- package/workflows/workflows/agent-environment-setup/shared/rules/STEERING.md +9 -8
- package/workflows/workflows/agent-environment-setup/shared/rules/overrides/codex.md +1 -1
|
@@ -2,82 +2,68 @@
|
|
|
2
2
|
---
|
|
3
3
|
inclusion: manual
|
|
4
4
|
name: api-patterns
|
|
5
|
-
description:
|
|
6
|
-
|
|
5
|
+
description: "Use when choosing between REST, GraphQL, and type-safe RPC patterns, or when standardizing response envelopes, versioning, pagination, auth shape, and API protection strategy."
|
|
6
|
+
license: MIT
|
|
7
|
+
metadata:
|
|
8
|
+
author: cubis-foundry
|
|
9
|
+
version: "3.0"
|
|
10
|
+
compatibility: Claude Code, Codex, GitHub Copilot
|
|
7
11
|
---
|
|
8
12
|
|
|
9
13
|
# API Patterns
|
|
10
14
|
|
|
11
|
-
|
|
12
|
-
> **Learn to THINK, not copy fixed patterns.**
|
|
15
|
+
## Purpose
|
|
13
16
|
|
|
14
|
-
|
|
17
|
+
Use when choosing between REST, GraphQL, and type-safe RPC patterns, or when standardizing response envelopes, versioning, pagination, auth shape, and API protection strategy.
|
|
15
18
|
|
|
16
|
-
|
|
19
|
+
## When to Use
|
|
17
20
|
|
|
18
|
-
|
|
21
|
+
- Choosing REST vs GraphQL vs type-safe RPC for a new surface.
|
|
22
|
+
- Standardizing response envelopes, pagination, filtering, and error format.
|
|
23
|
+
- Planning auth, rate limits, and evolution strategy for an API surface.
|
|
24
|
+
- Reviewing whether an API design matches client and organizational constraints.
|
|
19
25
|
|
|
20
|
-
##
|
|
21
|
-
|
|
22
|
-
| File | Description | When to Read |
|
|
23
|
-
|------|-------------|--------------|
|
|
24
|
-
| `api-style.md` | REST vs GraphQL vs tRPC decision tree | Choosing API type |
|
|
25
|
-
| `rest.md` | Resource naming, HTTP methods, status codes | Designing REST API |
|
|
26
|
-
| `response.md` | Envelope pattern, error format, pagination | Response structure |
|
|
27
|
-
| `graphql.md` | Schema design, when to use, security | Considering GraphQL |
|
|
28
|
-
| `trpc.md` | TypeScript monorepo, type safety | TS fullstack projects |
|
|
29
|
-
| `versioning.md` | URI/Header/Query versioning | API evolution planning |
|
|
30
|
-
| `auth.md` | JWT, OAuth, Passkey, API Keys | Auth pattern selection |
|
|
31
|
-
| `rate-limiting.md` | Token bucket, sliding window | API protection |
|
|
32
|
-
| `documentation.md` | OpenAPI/Swagger best practices | Documentation |
|
|
33
|
-
| `security-testing.md` | OWASP API Top 10, auth/authz testing | Security audits |
|
|
26
|
+
## Instructions
|
|
34
27
|
|
|
35
|
-
|
|
28
|
+
1. Clarify clients, latency needs, ownership model, and compatibility constraints.
|
|
29
|
+
2. Choose transport shape based on product and team context, not habit.
|
|
30
|
+
3. Standardize response and error patterns before implementation fans out.
|
|
31
|
+
4. Define pagination, filtering, and auth strategy explicitly.
|
|
32
|
+
5. Make versioning and operational protections part of the design, not an afterthought.
|
|
36
33
|
|
|
37
|
-
|
|
34
|
+
### Baseline standards
|
|
38
35
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
36
|
+
- Use one consistent response and error vocabulary per API surface.
|
|
37
|
+
- Prefer explicit evolution strategy over “we will figure it out later.”
|
|
38
|
+
- Match the pattern to client needs and team capability.
|
|
39
|
+
- Treat rate limiting and abuse controls as part of API design.
|
|
40
|
+
- Keep auth semantics visible and documented.
|
|
44
41
|
|
|
45
|
-
|
|
42
|
+
### Constraints
|
|
46
43
|
|
|
47
|
-
|
|
44
|
+
- Avoid defaulting to REST, GraphQL, or RPC by trend alone.
|
|
45
|
+
- Avoid inconsistent envelopes across related endpoints.
|
|
46
|
+
- Avoid mixing public and internal conventions into one confused surface.
|
|
47
|
+
- Avoid delaying versioning and pagination decisions until after rollout.
|
|
48
48
|
|
|
49
|
-
|
|
49
|
+
## Output Format
|
|
50
50
|
|
|
51
|
-
|
|
52
|
-
- [ ] **Chosen API style for THIS context?** (REST/GraphQL/tRPC)
|
|
53
|
-
- [ ] **Defined consistent response format?**
|
|
54
|
-
- [ ] **Planned versioning strategy?**
|
|
55
|
-
- [ ] **Considered authentication needs?**
|
|
56
|
-
- [ ] **Planned rate limiting?**
|
|
57
|
-
- [ ] **Documentation approach defined?**
|
|
51
|
+
Provide implementation guidance, code examples, and configuration as appropriate to the task.
|
|
58
52
|
|
|
59
|
-
|
|
53
|
+
## References
|
|
60
54
|
|
|
61
|
-
|
|
55
|
+
Load on demand. Do not preload all reference files.
|
|
62
56
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
-
|
|
66
|
-
- Return inconsistent response formats
|
|
67
|
-
- Expose internal errors to clients
|
|
68
|
-
- Skip rate limiting
|
|
57
|
+
| File | Load when |
|
|
58
|
+
| --- | --- |
|
|
59
|
+
| `references/pattern-selection-checklist.md` | You need a sharper decision aid for REST vs GraphQL vs RPC, response envelopes, auth shape, and versioning tradeoffs. |
|
|
69
60
|
|
|
70
|
-
|
|
71
|
-
- Choose API style based on context
|
|
72
|
-
- Ask about client requirements
|
|
73
|
-
- Document thoroughly
|
|
74
|
-
- Use appropriate status codes
|
|
61
|
+
## Scripts
|
|
75
62
|
|
|
76
|
-
|
|
63
|
+
No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
|
|
77
64
|
|
|
78
|
-
##
|
|
65
|
+
## Examples
|
|
79
66
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
| `scripts/api_validator.py` | API endpoint validation | `python scripts/api_validator.py <project_path>` |
|
|
67
|
+
- "Help me with api patterns best practices in this project"
|
|
68
|
+
- "Review my api patterns implementation for issues"
|
|
83
69
|
````
|
|
@@ -1,81 +1,66 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: api-patterns
|
|
3
|
-
description:
|
|
4
|
-
|
|
3
|
+
description: "Use when choosing between REST, GraphQL, and type-safe RPC patterns, or when standardizing response envelopes, versioning, pagination, auth shape, and API protection strategy."
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
author: cubis-foundry
|
|
7
|
+
version: "3.0"
|
|
8
|
+
compatibility: Claude Code, Codex, GitHub Copilot
|
|
5
9
|
---
|
|
6
10
|
|
|
7
11
|
# API Patterns
|
|
8
12
|
|
|
9
|
-
|
|
10
|
-
> **Learn to THINK, not copy fixed patterns.**
|
|
13
|
+
## Purpose
|
|
11
14
|
|
|
12
|
-
|
|
15
|
+
Use when choosing between REST, GraphQL, and type-safe RPC patterns, or when standardizing response envelopes, versioning, pagination, auth shape, and API protection strategy.
|
|
13
16
|
|
|
14
|
-
|
|
17
|
+
## When to Use
|
|
15
18
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
| File | Description | When to Read |
|
|
21
|
-
|------|-------------|--------------|
|
|
22
|
-
| `api-style.md` | REST vs GraphQL vs tRPC decision tree | Choosing API type |
|
|
23
|
-
| `rest.md` | Resource naming, HTTP methods, status codes | Designing REST API |
|
|
24
|
-
| `response.md` | Envelope pattern, error format, pagination | Response structure |
|
|
25
|
-
| `graphql.md` | Schema design, when to use, security | Considering GraphQL |
|
|
26
|
-
| `trpc.md` | TypeScript monorepo, type safety | TS fullstack projects |
|
|
27
|
-
| `versioning.md` | URI/Header/Query versioning | API evolution planning |
|
|
28
|
-
| `auth.md` | JWT, OAuth, Passkey, API Keys | Auth pattern selection |
|
|
29
|
-
| `rate-limiting.md` | Token bucket, sliding window | API protection |
|
|
30
|
-
| `documentation.md` | OpenAPI/Swagger best practices | Documentation |
|
|
31
|
-
| `security-testing.md` | OWASP API Top 10, auth/authz testing | Security audits |
|
|
19
|
+
- Choosing REST vs GraphQL vs type-safe RPC for a new surface.
|
|
20
|
+
- Standardizing response envelopes, pagination, filtering, and error format.
|
|
21
|
+
- Planning auth, rate limits, and evolution strategy for an API surface.
|
|
22
|
+
- Reviewing whether an API design matches client and organizational constraints.
|
|
32
23
|
|
|
33
|
-
|
|
24
|
+
## Instructions
|
|
34
25
|
|
|
35
|
-
|
|
26
|
+
1. Clarify clients, latency needs, ownership model, and compatibility constraints.
|
|
27
|
+
2. Choose transport shape based on product and team context, not habit.
|
|
28
|
+
3. Standardize response and error patterns before implementation fans out.
|
|
29
|
+
4. Define pagination, filtering, and auth strategy explicitly.
|
|
30
|
+
5. Make versioning and operational protections part of the design, not an afterthought.
|
|
36
31
|
|
|
37
|
-
|
|
38
|
-
|------|-------|
|
|
39
|
-
| API implementation | `@[skills/backend-development]` |
|
|
40
|
-
| Data structure | `@[skills/database-design]` |
|
|
41
|
-
| Security details | `@[skills/security-hardening]` |
|
|
32
|
+
### Baseline standards
|
|
42
33
|
|
|
43
|
-
|
|
34
|
+
- Use one consistent response and error vocabulary per API surface.
|
|
35
|
+
- Prefer explicit evolution strategy over “we will figure it out later.”
|
|
36
|
+
- Match the pattern to client needs and team capability.
|
|
37
|
+
- Treat rate limiting and abuse controls as part of API design.
|
|
38
|
+
- Keep auth semantics visible and documented.
|
|
44
39
|
|
|
45
|
-
|
|
40
|
+
### Constraints
|
|
46
41
|
|
|
47
|
-
|
|
42
|
+
- Avoid defaulting to REST, GraphQL, or RPC by trend alone.
|
|
43
|
+
- Avoid inconsistent envelopes across related endpoints.
|
|
44
|
+
- Avoid mixing public and internal conventions into one confused surface.
|
|
45
|
+
- Avoid delaying versioning and pagination decisions until after rollout.
|
|
48
46
|
|
|
49
|
-
|
|
50
|
-
- [ ] **Chosen API style for THIS context?** (REST/GraphQL/tRPC)
|
|
51
|
-
- [ ] **Defined consistent response format?**
|
|
52
|
-
- [ ] **Planned versioning strategy?**
|
|
53
|
-
- [ ] **Considered authentication needs?**
|
|
54
|
-
- [ ] **Planned rate limiting?**
|
|
55
|
-
- [ ] **Documentation approach defined?**
|
|
47
|
+
## Output Format
|
|
56
48
|
|
|
57
|
-
|
|
49
|
+
Provide implementation guidance, code examples, and configuration as appropriate to the task.
|
|
58
50
|
|
|
59
|
-
##
|
|
51
|
+
## References
|
|
60
52
|
|
|
61
|
-
|
|
62
|
-
- Default to REST for everything
|
|
63
|
-
- Use verbs in REST endpoints (/getUsers)
|
|
64
|
-
- Return inconsistent response formats
|
|
65
|
-
- Expose internal errors to clients
|
|
66
|
-
- Skip rate limiting
|
|
53
|
+
Load on demand. Do not preload all reference files.
|
|
67
54
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
-
|
|
71
|
-
- Document thoroughly
|
|
72
|
-
- Use appropriate status codes
|
|
55
|
+
| File | Load when |
|
|
56
|
+
| --- | --- |
|
|
57
|
+
| `references/pattern-selection-checklist.md` | You need a sharper decision aid for REST vs GraphQL vs RPC, response envelopes, auth shape, and versioning tradeoffs. |
|
|
73
58
|
|
|
74
|
-
|
|
59
|
+
## Scripts
|
|
75
60
|
|
|
76
|
-
|
|
61
|
+
No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
|
|
77
62
|
|
|
78
|
-
|
|
79
|
-
|--------|---------|---------|
|
|
80
|
-
| `scripts/api_validator.py` | API endpoint validation | `python scripts/api_validator.py <project_path>` |
|
|
63
|
+
## Examples
|
|
81
64
|
|
|
65
|
+
- "Help me with api patterns best practices in this project"
|
|
66
|
+
- "Review my api patterns implementation for issues"
|
|
@@ -1,86 +1,69 @@
|
|
|
1
1
|
````markdown
|
|
2
2
|
---
|
|
3
3
|
inclusion: manual
|
|
4
|
-
name:
|
|
5
|
-
description: "Use when designing
|
|
4
|
+
name: architecture-designer
|
|
5
|
+
description: "Use when designing or reviewing system architecture, interface boundaries, tradeoffs, ADRs, scalability posture, and the smallest durable target shape for a product or platform."
|
|
6
|
+
license: MIT
|
|
7
|
+
metadata:
|
|
8
|
+
author: cubis-foundry
|
|
9
|
+
version: "3.0"
|
|
10
|
+
compatibility: Claude Code, Codex, GitHub Copilot
|
|
6
11
|
---
|
|
7
12
|
|
|
8
|
-
|
|
9
13
|
# Architecture Designer
|
|
10
14
|
|
|
11
|
-
##
|
|
12
|
-
|
|
13
|
-
Senior software architect specializing in system design, design patterns, and architectural decision-making.
|
|
14
|
-
|
|
15
|
-
## Role Definition
|
|
16
|
-
|
|
17
|
-
You are a principal architect with 15+ years of experience designing scalable systems. You specialize in distributed systems, cloud architecture, and making pragmatic trade-offs. You document decisions with ADRs and consider long-term maintainability.
|
|
18
|
-
|
|
19
|
-
## When to Use This Skill
|
|
15
|
+
## Purpose
|
|
20
16
|
|
|
21
|
-
|
|
22
|
-
- Choosing between architectural patterns
|
|
23
|
-
- Reviewing existing architecture
|
|
24
|
-
- Creating Architecture Decision Records (ADRs)
|
|
25
|
-
- Planning for scalability
|
|
26
|
-
- Evaluating technology choices
|
|
17
|
+
Use when designing or reviewing system architecture, interface boundaries, tradeoffs, ADRs, scalability posture, and the smallest durable target shape for a product or platform.
|
|
27
18
|
|
|
28
|
-
##
|
|
19
|
+
## When to Use
|
|
29
20
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
5. **Review** - Validate with stakeholders
|
|
21
|
+
- Designing a new system or reshaping an existing one.
|
|
22
|
+
- Making boundary, ownership, integration, or deployment tradeoffs explicit.
|
|
23
|
+
- Writing or reviewing architectural decisions and ADR-style reasoning.
|
|
24
|
+
- Deciding how much architecture is actually justified for the product stage.
|
|
35
25
|
|
|
36
|
-
##
|
|
26
|
+
## Instructions
|
|
37
27
|
|
|
38
|
-
|
|
28
|
+
1. Clarify product goals, constraints, and failure tolerance.
|
|
29
|
+
2. Identify the few architectural decisions that materially change risk or cost.
|
|
30
|
+
3. Compare viable shapes and document tradeoffs, not just the favorite option.
|
|
31
|
+
4. Choose the smallest architecture that safely supports the current target.
|
|
32
|
+
5. Hand off explicit boundaries, risks, and follow-up validation points.
|
|
39
33
|
|
|
40
|
-
|
|
41
|
-
| --------------------- | ----------------------------------- | ------------------------------------- |
|
|
42
|
-
| Architecture Patterns | `references/architecture-patterns.md` | Choosing monolith vs microservices |
|
|
43
|
-
| ADR Template | `references/adr-template.md` | Documenting decisions |
|
|
44
|
-
| System Design | `references/system-design.md` | Full system design template |
|
|
45
|
-
| Database Selection | `references/database-selection.md` | Choosing database technology |
|
|
46
|
-
| NFR Checklist | `references/nfr-checklist.md` | Gathering non-functional requirements |
|
|
34
|
+
### Baseline standards
|
|
47
35
|
|
|
48
|
-
|
|
36
|
+
- Start from product outcomes, not architecture fashion.
|
|
37
|
+
- Make ownership and interfaces explicit.
|
|
38
|
+
- Consider security, observability, and operations as part of the design.
|
|
39
|
+
- Prefer reversible decisions when uncertainty is high.
|
|
40
|
+
- Keep ADR-style reasoning concrete and testable.
|
|
49
41
|
|
|
50
|
-
###
|
|
42
|
+
### Constraints
|
|
51
43
|
|
|
52
|
-
-
|
|
53
|
-
-
|
|
54
|
-
-
|
|
55
|
-
-
|
|
56
|
-
- Consider operational complexity
|
|
57
|
-
- Review with stakeholders before finalizing
|
|
44
|
+
- Avoid over-engineering for hypothetical future scale.
|
|
45
|
+
- Avoid treating diagrams as a substitute for boundary decisions.
|
|
46
|
+
- Avoid choosing technology before identifying the real constraints.
|
|
47
|
+
- Avoid hiding unresolved risk behind vague architectural language.
|
|
58
48
|
|
|
59
|
-
|
|
49
|
+
## Output Format
|
|
60
50
|
|
|
61
|
-
|
|
62
|
-
- Choose technology without evaluating alternatives
|
|
63
|
-
- Ignore operational costs
|
|
64
|
-
- Design without understanding requirements
|
|
65
|
-
- Skip security considerations
|
|
51
|
+
Provide implementation guidance, code examples, and configuration as appropriate to the task.
|
|
66
52
|
|
|
67
|
-
##
|
|
53
|
+
## References
|
|
68
54
|
|
|
69
|
-
|
|
55
|
+
Load on demand. Do not preload all reference files.
|
|
70
56
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
4. Technology recommendations with rationale
|
|
75
|
-
5. Risks and mitigation strategies
|
|
57
|
+
| File | Load when |
|
|
58
|
+
| --- | --- |
|
|
59
|
+
| `references/system-tradeoff-checklist.md` | You need a sharper system-design checklist for boundaries, ADRs, integration shape, resilience, and rollout risk. |
|
|
76
60
|
|
|
77
|
-
##
|
|
61
|
+
## Scripts
|
|
78
62
|
|
|
79
|
-
|
|
63
|
+
No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
|
|
80
64
|
|
|
81
|
-
##
|
|
65
|
+
## Examples
|
|
82
66
|
|
|
83
|
-
-
|
|
84
|
-
-
|
|
85
|
-
- **Secure Code Guardian** - Security architecture
|
|
67
|
+
- "Help me with architecture designer best practices in this project"
|
|
68
|
+
- "Review my architecture designer implementation for issues"
|
|
86
69
|
````
|
|
@@ -1,83 +1,66 @@
|
|
|
1
1
|
---
|
|
2
|
-
name:
|
|
3
|
-
description: "Use when designing
|
|
2
|
+
name: architecture-designer
|
|
3
|
+
description: "Use when designing or reviewing system architecture, interface boundaries, tradeoffs, ADRs, scalability posture, and the smallest durable target shape for a product or platform."
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
author: cubis-foundry
|
|
7
|
+
version: "3.0"
|
|
8
|
+
compatibility: Claude Code, Codex, GitHub Copilot
|
|
4
9
|
---
|
|
5
10
|
|
|
6
|
-
|
|
7
11
|
# Architecture Designer
|
|
8
12
|
|
|
9
|
-
##
|
|
10
|
-
|
|
11
|
-
Senior software architect specializing in system design, design patterns, and architectural decision-making.
|
|
12
|
-
|
|
13
|
-
## Role Definition
|
|
14
|
-
|
|
15
|
-
You are a principal architect with 15+ years of experience designing scalable systems. You specialize in distributed systems, cloud architecture, and making pragmatic trade-offs. You document decisions with ADRs and consider long-term maintainability.
|
|
16
|
-
|
|
17
|
-
## When to Use This Skill
|
|
13
|
+
## Purpose
|
|
18
14
|
|
|
19
|
-
|
|
20
|
-
- Choosing between architectural patterns
|
|
21
|
-
- Reviewing existing architecture
|
|
22
|
-
- Creating Architecture Decision Records (ADRs)
|
|
23
|
-
- Planning for scalability
|
|
24
|
-
- Evaluating technology choices
|
|
15
|
+
Use when designing or reviewing system architecture, interface boundaries, tradeoffs, ADRs, scalability posture, and the smallest durable target shape for a product or platform.
|
|
25
16
|
|
|
26
|
-
##
|
|
17
|
+
## When to Use
|
|
27
18
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
5. **Review** - Validate with stakeholders
|
|
19
|
+
- Designing a new system or reshaping an existing one.
|
|
20
|
+
- Making boundary, ownership, integration, or deployment tradeoffs explicit.
|
|
21
|
+
- Writing or reviewing architectural decisions and ADR-style reasoning.
|
|
22
|
+
- Deciding how much architecture is actually justified for the product stage.
|
|
33
23
|
|
|
34
|
-
##
|
|
24
|
+
## Instructions
|
|
35
25
|
|
|
36
|
-
|
|
26
|
+
1. Clarify product goals, constraints, and failure tolerance.
|
|
27
|
+
2. Identify the few architectural decisions that materially change risk or cost.
|
|
28
|
+
3. Compare viable shapes and document tradeoffs, not just the favorite option.
|
|
29
|
+
4. Choose the smallest architecture that safely supports the current target.
|
|
30
|
+
5. Hand off explicit boundaries, risks, and follow-up validation points.
|
|
37
31
|
|
|
38
|
-
|
|
39
|
-
| --------------------- | ----------------------------------- | ------------------------------------- |
|
|
40
|
-
| Architecture Patterns | `references/architecture-patterns.md` | Choosing monolith vs microservices |
|
|
41
|
-
| ADR Template | `references/adr-template.md` | Documenting decisions |
|
|
42
|
-
| System Design | `references/system-design.md` | Full system design template |
|
|
43
|
-
| Database Selection | `references/database-selection.md` | Choosing database technology |
|
|
44
|
-
| NFR Checklist | `references/nfr-checklist.md` | Gathering non-functional requirements |
|
|
32
|
+
### Baseline standards
|
|
45
33
|
|
|
46
|
-
|
|
34
|
+
- Start from product outcomes, not architecture fashion.
|
|
35
|
+
- Make ownership and interfaces explicit.
|
|
36
|
+
- Consider security, observability, and operations as part of the design.
|
|
37
|
+
- Prefer reversible decisions when uncertainty is high.
|
|
38
|
+
- Keep ADR-style reasoning concrete and testable.
|
|
47
39
|
|
|
48
|
-
###
|
|
40
|
+
### Constraints
|
|
49
41
|
|
|
50
|
-
-
|
|
51
|
-
-
|
|
52
|
-
-
|
|
53
|
-
-
|
|
54
|
-
- Consider operational complexity
|
|
55
|
-
- Review with stakeholders before finalizing
|
|
42
|
+
- Avoid over-engineering for hypothetical future scale.
|
|
43
|
+
- Avoid treating diagrams as a substitute for boundary decisions.
|
|
44
|
+
- Avoid choosing technology before identifying the real constraints.
|
|
45
|
+
- Avoid hiding unresolved risk behind vague architectural language.
|
|
56
46
|
|
|
57
|
-
|
|
47
|
+
## Output Format
|
|
58
48
|
|
|
59
|
-
|
|
60
|
-
- Choose technology without evaluating alternatives
|
|
61
|
-
- Ignore operational costs
|
|
62
|
-
- Design without understanding requirements
|
|
63
|
-
- Skip security considerations
|
|
49
|
+
Provide implementation guidance, code examples, and configuration as appropriate to the task.
|
|
64
50
|
|
|
65
|
-
##
|
|
51
|
+
## References
|
|
66
52
|
|
|
67
|
-
|
|
53
|
+
Load on demand. Do not preload all reference files.
|
|
68
54
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
4. Technology recommendations with rationale
|
|
73
|
-
5. Risks and mitigation strategies
|
|
55
|
+
| File | Load when |
|
|
56
|
+
| --- | --- |
|
|
57
|
+
| `references/system-tradeoff-checklist.md` | You need a sharper system-design checklist for boundaries, ADRs, integration shape, resilience, and rollout risk. |
|
|
74
58
|
|
|
75
|
-
##
|
|
59
|
+
## Scripts
|
|
76
60
|
|
|
77
|
-
|
|
61
|
+
No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
|
|
78
62
|
|
|
79
|
-
##
|
|
63
|
+
## Examples
|
|
80
64
|
|
|
81
|
-
-
|
|
82
|
-
-
|
|
83
|
-
- **Secure Code Guardian** - Security architecture
|
|
65
|
+
- "Help me with architecture designer best practices in this project"
|
|
66
|
+
- "Review my architecture designer implementation for issues"
|
|
@@ -2,18 +2,28 @@
|
|
|
2
2
|
---
|
|
3
3
|
inclusion: manual
|
|
4
4
|
name: ask-questions-if-underspecified
|
|
5
|
-
description: Clarify requirements before implementing. Use when serious doubts arise.
|
|
5
|
+
description: Clarify requirements before implementing. Use when serious doubts arise about objective, scope, constraints, environment, or safety — or when the task is substantial enough that being wrong wastes significant effort.
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Ask Questions If Underspecified
|
|
9
9
|
|
|
10
10
|
## When to Use
|
|
11
11
|
|
|
12
|
-
Use this skill when a request has multiple plausible interpretations or key details (objective, scope, constraints, environment, or safety) are unclear.
|
|
12
|
+
Use this skill when a request has multiple plausible interpretations or key details (objective, scope, constraints, environment, or safety) are unclear — **and** when the cost of implementing the wrong interpretation is significant.
|
|
13
|
+
|
|
14
|
+
Three situations require clarification:
|
|
15
|
+
|
|
16
|
+
1. **High branching** — Multiple plausible interpretations produce significantly different implementations
|
|
17
|
+
2. **Substantial deliverable** — The task is large enough that wrong assumptions waste real time
|
|
18
|
+
3. **Safety-critical** — The action is hard to reverse (data migrations, deployments, file deletions)
|
|
13
19
|
|
|
14
20
|
## When NOT to Use
|
|
15
21
|
|
|
16
|
-
Do not use this skill when
|
|
22
|
+
Do not use this skill when:
|
|
23
|
+
|
|
24
|
+
- The request is already clear and one interpretation is obviously correct
|
|
25
|
+
- A quick discovery read (config files, existing patterns, repo structure) can answer the missing details faster than asking
|
|
26
|
+
- The task is small enough that being slightly wrong is cheap and correctable
|
|
17
27
|
|
|
18
28
|
## Goal
|
|
19
29
|
|
|
@@ -24,6 +34,7 @@ Ask the minimum set of clarifying questions needed to avoid wrong work; do not s
|
|
|
24
34
|
### 1) Decide whether the request is underspecified
|
|
25
35
|
|
|
26
36
|
Treat a request as underspecified if after exploring how to perform the work, some or all of the following are not clear:
|
|
37
|
+
|
|
27
38
|
- Define the objective (what should change vs stay the same)
|
|
28
39
|
- Define "done" (acceptance criteria, examples, edge cases)
|
|
29
40
|
- Define scope (which files/components/users are in/out)
|
|
@@ -38,6 +49,7 @@ If multiple plausible interpretations exist, assume it is underspecified.
|
|
|
38
49
|
Ask 1-5 questions in the first pass. Prefer questions that eliminate whole branches of work.
|
|
39
50
|
|
|
40
51
|
Make questions easy to answer:
|
|
52
|
+
|
|
41
53
|
- Optimize for scannability (short, numbered questions; avoid paragraphs)
|
|
42
54
|
- Offer multiple-choice options when possible
|
|
43
55
|
- Suggest reasonable defaults when appropriate (mark them clearly as the default/recommended choice; bold the recommended choice in the list, or if you present options in a code block, put a bold "Recommended" line immediately above the block and also tag defaults inside the block)
|
|
@@ -49,10 +61,12 @@ Make questions easy to answer:
|
|
|
49
61
|
### 3) Pause before acting
|
|
50
62
|
|
|
51
63
|
Until must-have answers arrive:
|
|
64
|
+
|
|
52
65
|
- Do not run commands, edit files, or produce a detailed plan that depends on unknowns
|
|
53
66
|
- Do perform a clearly labeled, low-risk discovery step only if it does not commit you to a direction (e.g., inspect repo structure, read relevant config files)
|
|
54
67
|
|
|
55
68
|
If the user explicitly asks you to proceed without answers:
|
|
69
|
+
|
|
56
70
|
- State your assumptions as a short numbered list
|
|
57
71
|
- Ask for confirmation; proceed only after they confirm or correct them
|
|
58
72
|
|
|
@@ -85,4 +99,38 @@ Reply with: defaults (or 1a 2a)
|
|
|
85
99
|
|
|
86
100
|
- Don't ask questions you can answer with a quick, low-risk discovery read (e.g., configs, existing patterns, docs).
|
|
87
101
|
- Don't ask open-ended questions if a tight multiple-choice or yes/no would eliminate ambiguity faster.
|
|
102
|
+
- Don't ask more than 5 questions at once — rank by impact and ask the top ones.
|
|
103
|
+
- Don't skip the fast-path — every clarification block needs `defaults` shortcut.
|
|
104
|
+
- Don't forget to restate interpretation before proceeding — confirms you heard correctly.
|
|
105
|
+
- Don't ask about reversible decisions — pick one, proceed, let them correct if wrong.
|
|
106
|
+
|
|
107
|
+
## Three-Stage Pattern (for complex or substantial tasks)
|
|
108
|
+
|
|
109
|
+
For tasks where wrong assumptions would waste significant effort — documents, architecture decisions, multi-file features — use a three-stage approach:
|
|
110
|
+
|
|
111
|
+
### Stage 1: Meta-context questions (3-5 questions)
|
|
112
|
+
|
|
113
|
+
Ask about the big picture before touching content:
|
|
114
|
+
|
|
115
|
+
- What _type_ of deliverable is this? (spec, code, doc, design, plan)
|
|
116
|
+
- Who's the audience/consumer?
|
|
117
|
+
- What does "done" look like?
|
|
118
|
+
- Existing template, format, or precedent to follow?
|
|
119
|
+
- Hard constraints (framework, performance, compatibility)?
|
|
120
|
+
|
|
121
|
+
### Stage 2: Info dump + targeted follow-up
|
|
122
|
+
|
|
123
|
+
After Stage 1 answers: invite the user to brain-dump everything relevant.
|
|
124
|
+
|
|
125
|
+
> "Dump everything you know — background, prior decisions, constraints, opinions, blockers. Don't organize it. Just get it all out."
|
|
126
|
+
|
|
127
|
+
Then ask 5-10 targeted follow-up questions based on gaps. Users can answer in shorthand (`1: yes, 2: see above, 3: no`).
|
|
128
|
+
|
|
129
|
+
**Exit Stage 2 when:** You understand objective, constraints, and at least one clear definition of success.
|
|
130
|
+
|
|
131
|
+
### Stage 3: Confirm interpretation, then proceed
|
|
132
|
+
|
|
133
|
+
Restate in 1-3 sentences before starting:
|
|
134
|
+
|
|
135
|
+
> "Here's what I understand: [objective]. [Key constraint]. [What done looks like]. Starting now — correct me if anything's off."
|
|
88
136
|
````
|