cfsa-antigravity 2.19.0 → 2.19.2

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.
Files changed (200) hide show
  1. package/package.json +1 -1
  2. package/template/.agent/kit-sync.md +3 -3
  3. package/template/.claude/commands/audit-ambiguity-execute.md +6 -0
  4. package/template/.claude/commands/audit-ambiguity-rubrics.md +6 -0
  5. package/template/.claude/commands/audit-ambiguity.md +6 -0
  6. package/template/.claude/commands/bootstrap-agents-fill.md +6 -0
  7. package/template/.claude/commands/bootstrap-agents-provision.md +6 -0
  8. package/template/.claude/commands/bootstrap-agents.md +6 -0
  9. package/template/.claude/commands/create-prd-architecture.md +6 -0
  10. package/template/.claude/commands/create-prd-compile.md +6 -0
  11. package/template/.claude/commands/create-prd-design-system.md +6 -0
  12. package/template/.claude/commands/create-prd-security.md +6 -0
  13. package/template/.claude/commands/create-prd-stack.md +6 -0
  14. package/template/.claude/commands/decompose-architecture-structure.md +6 -0
  15. package/template/.claude/commands/decompose-architecture-validate.md +6 -0
  16. package/template/.claude/commands/evolve-contract.md +6 -0
  17. package/template/.claude/commands/evolve-feature-cascade.md +6 -0
  18. package/template/.claude/commands/evolve-feature-classify.md +6 -0
  19. package/template/.claude/commands/evolve-feature.md +6 -0
  20. package/template/.claude/commands/ideate-discover.md +6 -0
  21. package/template/.claude/commands/ideate-extract.md +6 -0
  22. package/template/.claude/commands/ideate-validate.md +6 -0
  23. package/template/.claude/commands/implement-slice-setup.md +6 -0
  24. package/template/.claude/commands/implement-slice-tdd.md +6 -0
  25. package/template/.claude/commands/plan-phase-preflight.md +6 -0
  26. package/template/.claude/commands/plan-phase-write.md +6 -0
  27. package/template/.claude/commands/propagate-decision-apply.md +6 -0
  28. package/template/.claude/commands/propagate-decision-scan.md +6 -0
  29. package/template/.claude/commands/propagate-decision.md +6 -0
  30. package/template/.claude/commands/remediate-pipeline-assess.md +6 -0
  31. package/template/.claude/commands/remediate-pipeline-execute.md +6 -0
  32. package/template/.claude/commands/remediate-pipeline.md +6 -0
  33. package/template/.claude/commands/remediate-shard-split.md +6 -0
  34. package/template/.claude/commands/resolve-ambiguity.md +6 -0
  35. package/template/.claude/commands/setup-workspace-cicd.md +6 -0
  36. package/template/.claude/commands/setup-workspace-data.md +6 -0
  37. package/template/.claude/commands/setup-workspace-hosting.md +6 -0
  38. package/template/.claude/commands/setup-workspace-scaffold.md +6 -0
  39. package/template/.claude/commands/sync-kit.md +6 -0
  40. package/template/.claude/commands/update-architecture-map.md +6 -0
  41. package/template/.claude/commands/validate-phase-quality.md +6 -0
  42. package/template/.claude/commands/validate-phase-readiness.md +6 -0
  43. package/template/.claude/commands/verify-infrastructure.md +6 -0
  44. package/template/.claude/commands/write-architecture-spec-deepen.md +6 -0
  45. package/template/.claude/commands/write-architecture-spec-design.md +6 -0
  46. package/template/.claude/commands/write-be-spec-classify.md +6 -0
  47. package/template/.claude/commands/write-be-spec-write.md +6 -0
  48. package/template/.claude/commands/write-fe-spec-classify.md +6 -0
  49. package/template/.claude/commands/write-fe-spec-write.md +6 -0
  50. package/template/.claude/skills/accessibility/SKILL.md +522 -0
  51. package/template/.claude/skills/accessibility/references/WCAG.md +162 -0
  52. package/template/.claude/skills/accessibility/references/ia-spec-checklist.md +35 -0
  53. package/template/.claude/skills/adversarial-review/SKILL.md +90 -0
  54. package/template/.claude/skills/antigravity-workflows/SKILL.md +81 -0
  55. package/template/.claude/skills/antigravity-workflows/resources/implementation-playbook.md +36 -0
  56. package/template/.claude/skills/api-design-principles/SKILL.md +169 -0
  57. package/template/.claude/skills/api-design-principles/assets/api-design-checklist.md +155 -0
  58. package/template/.claude/skills/api-design-principles/assets/rest-api-template.py +182 -0
  59. package/template/.claude/skills/api-design-principles/references/graphql-schema-design.md +583 -0
  60. package/template/.claude/skills/api-design-principles/references/rest-best-practices.md +408 -0
  61. package/template/.claude/skills/api-design-principles/resources/implementation-playbook.md +513 -0
  62. package/template/.claude/skills/api-versioning/SKILL.md +166 -0
  63. package/template/.claude/skills/api-versioning/references/typescript.md +157 -0
  64. package/template/.claude/skills/architecture-mapping/SKILL.md +219 -0
  65. package/template/.claude/skills/bootstrap-agents/SKILL.md +258 -0
  66. package/template/.claude/skills/brainstorming/SKILL.md +177 -0
  67. package/template/.claude/skills/brand-guidelines/SKILL.md +44 -0
  68. package/template/.claude/skills/clean-code/SKILL.md +196 -0
  69. package/template/.claude/skills/clean-code/references/typescript.md +126 -0
  70. package/template/.claude/skills/code-review-pro/SKILL.md +152 -0
  71. package/template/.claude/skills/concise-planning/SKILL.md +107 -0
  72. package/template/.claude/skills/cross-layer-consistency/SKILL.md +117 -0
  73. package/template/.claude/skills/database-schema-design/SKILL.md +205 -0
  74. package/template/.claude/skills/database-schema-design/references/relational.md +228 -0
  75. package/template/.claude/skills/deployment-procedures/SKILL.md +241 -0
  76. package/template/.claude/skills/design-anti-cliche/SKILL.md +159 -0
  77. package/template/.claude/skills/design-direction/SKILL.md +45 -0
  78. package/template/.claude/skills/error-handling-patterns/SKILL.md +226 -0
  79. package/template/.claude/skills/error-handling-patterns/references/go.md +162 -0
  80. package/template/.claude/skills/error-handling-patterns/references/python.md +262 -0
  81. package/template/.claude/skills/error-handling-patterns/references/rust.md +112 -0
  82. package/template/.claude/skills/error-handling-patterns/references/typescript.md +178 -0
  83. package/template/.claude/skills/find-skills/SKILL.md +145 -0
  84. package/template/.claude/skills/git-advanced/SKILL.md +972 -0
  85. package/template/.claude/skills/git-workflow/SKILL.md +420 -0
  86. package/template/.claude/skills/idea-extraction/SKILL.md +644 -0
  87. package/template/.claude/skills/logging-best-practices/SKILL.md +192 -0
  88. package/template/.claude/skills/logging-best-practices/references/go.md +49 -0
  89. package/template/.claude/skills/logging-best-practices/references/python.md +52 -0
  90. package/template/.claude/skills/logging-best-practices/references/typescript.md +215 -0
  91. package/template/.claude/skills/migration-management/SKILL.md +200 -0
  92. package/template/.claude/skills/migration-management/references/relational.md +214 -0
  93. package/template/.claude/skills/minimalist-surgical-development/SKILL.md +135 -0
  94. package/template/.claude/skills/parallel-agents/SKILL.md +165 -0
  95. package/template/.claude/skills/parallel-debugging/SKILL.md +135 -0
  96. package/template/.claude/skills/parallel-feature-development/SKILL.md +157 -0
  97. package/template/.claude/skills/performance-budgeting/SKILL.md +144 -0
  98. package/template/.claude/skills/pipeline-rubrics/SKILL.md +51 -0
  99. package/template/.claude/skills/pipeline-rubrics/references/architecture-rubric.md +19 -0
  100. package/template/.claude/skills/pipeline-rubrics/references/be-rubric.md +21 -0
  101. package/template/.claude/skills/pipeline-rubrics/references/fe-rubric.md +20 -0
  102. package/template/.claude/skills/pipeline-rubrics/references/ia-rubric.md +19 -0
  103. package/template/.claude/skills/pipeline-rubrics/references/scoring.md +32 -0
  104. package/template/.claude/skills/pipeline-rubrics/references/vision-rubric.md +12 -0
  105. package/template/.claude/skills/prd-templates/SKILL.md +107 -0
  106. package/template/.claude/skills/prd-templates/references/architecture-completeness-checklist.md +28 -0
  107. package/template/.claude/skills/prd-templates/references/architecture-design-template.md +88 -0
  108. package/template/.claude/skills/prd-templates/references/be-spec-classification.md +41 -0
  109. package/template/.claude/skills/prd-templates/references/be-spec-template.md +107 -0
  110. package/template/.claude/skills/prd-templates/references/bootstrap-verification-protocol.md +50 -0
  111. package/template/.claude/skills/prd-templates/references/constraint-exploration.md +41 -0
  112. package/template/.claude/skills/prd-templates/references/data-placement-template.md +74 -0
  113. package/template/.claude/skills/prd-templates/references/decision-confirmation-protocol.md +68 -0
  114. package/template/.claude/skills/prd-templates/references/decision-propagation.md +121 -0
  115. package/template/.claude/skills/prd-templates/references/decomposition-templates.md +226 -0
  116. package/template/.claude/skills/prd-templates/references/deep-ideation-loading-protocol.md +114 -0
  117. package/template/.claude/skills/prd-templates/references/design-system-decisions.md +198 -0
  118. package/template/.claude/skills/prd-templates/references/design-system-prerequisite-check.md +18 -0
  119. package/template/.claude/skills/prd-templates/references/domain-exhaustion-criteria.md +37 -0
  120. package/template/.claude/skills/prd-templates/references/engagement-tier-protocol.md +58 -0
  121. package/template/.claude/skills/prd-templates/references/engineering-standards-template.md +126 -0
  122. package/template/.claude/skills/prd-templates/references/evolution-layer-guidance.md +91 -0
  123. package/template/.claude/skills/prd-templates/references/expansion-modes.md +27 -0
  124. package/template/.claude/skills/prd-templates/references/fe-classification-procedures.md +47 -0
  125. package/template/.claude/skills/prd-templates/references/fe-spec-template.md +90 -0
  126. package/template/.claude/skills/prd-templates/references/feature-ledger-protocol.md +149 -0
  127. package/template/.claude/skills/prd-templates/references/folder-seeding-protocol.md +77 -0
  128. package/template/.claude/skills/prd-templates/references/fractal-cx-template.md +58 -0
  129. package/template/.claude/skills/prd-templates/references/fractal-feature-template.md +93 -0
  130. package/template/.claude/skills/prd-templates/references/fractal-node-index-template.md +55 -0
  131. package/template/.claude/skills/prd-templates/references/gate-applicability.md +92 -0
  132. package/template/.claude/skills/prd-templates/references/ideation-crosscut-template.md +36 -0
  133. package/template/.claude/skills/prd-templates/references/ideation-index-template.md +111 -0
  134. package/template/.claude/skills/prd-templates/references/ideation-meta-template.md +126 -0
  135. package/template/.claude/skills/prd-templates/references/infrastructure-report-template.md +71 -0
  136. package/template/.claude/skills/prd-templates/references/input-classification.md +23 -0
  137. package/template/.claude/skills/prd-templates/references/map-guard-protocol.md +65 -0
  138. package/template/.claude/skills/prd-templates/references/operational-templates.md +116 -0
  139. package/template/.claude/skills/prd-templates/references/persona-completeness-gate.md +20 -0
  140. package/template/.claude/skills/prd-templates/references/placeholder-guard-template.md +21 -0
  141. package/template/.claude/skills/prd-templates/references/placeholder-workflow-mapping.md +50 -0
  142. package/template/.claude/skills/prd-templates/references/shard-boundary-analysis.md +103 -0
  143. package/template/.claude/skills/prd-templates/references/shard-split-remediation.md +157 -0
  144. package/template/.claude/skills/prd-templates/references/skill-loading-protocol.md +36 -0
  145. package/template/.claude/skills/prd-templates/references/slice-completion-gates.md +29 -0
  146. package/template/.claude/skills/prd-templates/references/spec-coverage-sweep.md +44 -0
  147. package/template/.claude/skills/prd-templates/references/surface-model.md +61 -0
  148. package/template/.claude/skills/prd-templates/references/tdd-testing-policy.md +39 -0
  149. package/template/.claude/skills/prd-templates/references/vision-template.md +57 -0
  150. package/template/.claude/skills/prd-templates/references/workflow-checkpoint-protocol.md +112 -0
  151. package/template/.claude/skills/prd-templates/references/write-verification-protocol.md +57 -0
  152. package/template/.claude/skills/prompt-engineer/SKILL.md +203 -0
  153. package/template/.claude/skills/regex-patterns/SKILL.md +333 -0
  154. package/template/.claude/skills/regex-patterns/references/go.md +44 -0
  155. package/template/.claude/skills/regex-patterns/references/javascript.md +63 -0
  156. package/template/.claude/skills/regex-patterns/references/python.md +77 -0
  157. package/template/.claude/skills/regex-patterns/references/rust.md +43 -0
  158. package/template/.claude/skills/resolve-ambiguity/SKILL.md +278 -0
  159. package/template/.claude/skills/security-scanning-security-hardening/SKILL.md +231 -0
  160. package/template/.claude/skills/session-continuity/SKILL.md +732 -0
  161. package/template/.claude/skills/session-continuity/protocols/01-session-resumption.md +38 -0
  162. package/template/.claude/skills/session-continuity/protocols/02-progress-generation.md +85 -0
  163. package/template/.claude/skills/session-continuity/protocols/03-progress-update.md +70 -0
  164. package/template/.claude/skills/session-continuity/protocols/04-pattern-extraction.md +60 -0
  165. package/template/.claude/skills/session-continuity/protocols/05-session-close.md +37 -0
  166. package/template/.claude/skills/session-continuity/protocols/06-decision-analysis.md +84 -0
  167. package/template/.claude/skills/session-continuity/protocols/07-spec-pipeline-generation.md +48 -0
  168. package/template/.claude/skills/session-continuity/protocols/08-spec-pipeline-update.md +55 -0
  169. package/template/.claude/skills/session-continuity/protocols/09-parallel-claim.md +122 -0
  170. package/template/.claude/skills/session-continuity/protocols/10-placeholder-verification-gate.md +83 -0
  171. package/template/.claude/skills/session-continuity/protocols/11-parallel-synthesis.md +21 -0
  172. package/template/.claude/skills/session-continuity/protocols/ambiguity-gates.md +48 -0
  173. package/template/.claude/skills/skill-creator/SKILL.md +203 -0
  174. package/template/.claude/skills/skill-creator/references/.gitkeep +0 -0
  175. package/template/.claude/skills/skill-creator/scripts/.gitkeep +0 -0
  176. package/template/.claude/skills/spec-writing/SKILL.md +110 -0
  177. package/template/.claude/skills/systematic-debugging/CREATION-LOG.md +119 -0
  178. package/template/.claude/skills/systematic-debugging/SKILL.md +297 -0
  179. package/template/.claude/skills/systematic-debugging/condition-based-waiting-example.ts +158 -0
  180. package/template/.claude/skills/systematic-debugging/condition-based-waiting.md +115 -0
  181. package/template/.claude/skills/systematic-debugging/defense-in-depth.md +122 -0
  182. package/template/.claude/skills/systematic-debugging/find-polluter.sh +63 -0
  183. package/template/.claude/skills/systematic-debugging/root-cause-tracing.md +169 -0
  184. package/template/.claude/skills/systematic-debugging/test-academic.md +14 -0
  185. package/template/.claude/skills/systematic-debugging/test-pressure-1.md +58 -0
  186. package/template/.claude/skills/systematic-debugging/test-pressure-2.md +68 -0
  187. package/template/.claude/skills/systematic-debugging/test-pressure-3.md +69 -0
  188. package/template/.claude/skills/tdd-workflow/SKILL.md +186 -0
  189. package/template/.claude/skills/tdd-workflow/references/typescript.md +231 -0
  190. package/template/.claude/skills/tech-stack-catalog/SKILL.md +49 -0
  191. package/template/.claude/skills/tech-stack-catalog/references/constraint-questions.md +237 -0
  192. package/template/.claude/skills/tech-stack-catalog/references/dev-tooling-decisions.md +37 -0
  193. package/template/.claude/skills/tech-stack-catalog/references/surface-decision-tables.md +69 -0
  194. package/template/.claude/skills/technical-writer/SKILL.md +242 -0
  195. package/template/.claude/skills/testing-strategist/SKILL.md +319 -0
  196. package/template/.claude/skills/testing-strategist/references/typescript.md +328 -0
  197. package/template/.claude/skills/verification-before-completion/SKILL.md +97 -0
  198. package/template/.claude/skills/workflow-automation/SKILL.md +166 -0
  199. package/template/.claude/skills/workflow-automation/references/inngest.md +88 -0
  200. package/template/.claude/skills/workflow-automation/references/temporal.md +64 -0
@@ -0,0 +1,107 @@
1
+ ---
2
+ name: concise-planning
3
+ description: "Use when a user asks for a plan for a coding task, to generate a clear, actionable, and atomic checklist."
4
+ version: 2.0.0
5
+ source: self
6
+ date_added: "2026-02-27"
7
+ date_rewritten: "2026-03-14"
8
+ ---
9
+
10
+ # Concise Planning
11
+
12
+ Generate focused, actionable implementation plans that eliminate ambiguity and prevent scope creep.
13
+
14
+ ## When to Use
15
+
16
+ - User asks "how should I approach this?" or "can you make a plan for X?"
17
+ - Task involves multiple files or components
18
+ - Work spans more than ~3 logical steps
19
+ - You need to communicate a proposed sequence before executing
20
+
21
+ ## When NOT to Use
22
+
23
+ - Task is a single-step operation (just do it)
24
+ - User gave an explicit command with clear intent (just execute)
25
+ - During `/plan-phase` or `/implement-slice` (those have their own planning structure)
26
+
27
+ ## Workflow
28
+
29
+ ### 1. Scan Context (30 seconds, not 5 minutes)
30
+
31
+ Read only what's necessary:
32
+ - **Project structure** — `ls` the relevant directories
33
+ - **Existing patterns** — check one similar file for conventions
34
+ - **Constraints** — look for test frameworks, linters, type systems in use
35
+
36
+ Do NOT read every file in the project. Do NOT generate a 500-line analysis. Scan, not study.
37
+
38
+ ### 2. Ask or Assume
39
+
40
+ - **0 questions** if the task is clear and you have enough context
41
+ - **1 question max** if there's a genuinely blocking ambiguity
42
+ - **Never more than 2** — if you need more, you don't understand the codebase well enough. Go read more code instead of asking.
43
+
44
+ For non-blocking unknowns, state your assumption:
45
+ > "Assuming we want this as a new utility in `lib/` rather than inline — will adjust if you prefer otherwise."
46
+
47
+ ### 3. Generate Plan
48
+
49
+ Use this exact structure:
50
+
51
+ ```markdown
52
+ ## Approach
53
+
54
+ [1-3 sentences: what you'll do and why this approach over alternatives]
55
+
56
+ ## Scope
57
+
58
+ **In:**
59
+ - [Specific deliverable 1]
60
+ - [Specific deliverable 2]
61
+
62
+ **Out:**
63
+ - [Explicitly excluded item — prevents scope creep]
64
+
65
+ ## Steps
66
+
67
+ 1. [Verb] [specific target] — [why, if non-obvious]
68
+ 2. [Verb] [specific target]
69
+ 3. [Verb] [specific target]
70
+ 4. [Verb] [specific target]
71
+ 5. Validate: [specific validation command or check]
72
+
73
+ ## Assumptions
74
+
75
+ - [Assumption 1 — what you decided without asking]
76
+ ```
77
+
78
+ ### Plan Quality Rules
79
+
80
+ | Rule | Why |
81
+ |------|-----|
82
+ | **6-10 steps** | Fewer = too vague. More = over-planned. |
83
+ | **Verb-first steps** | "Add", "Create", "Refactor", "Test" — not "The component should..." |
84
+ | **Name files and functions** | "Add `validateEmail()` to `lib/validators.ts`" not "add validation" |
85
+ | **One validation step minimum** | Every plan ends with proof it works |
86
+ | **Explicit "Out" scope** | Prevents the plan from growing mid-execution |
87
+ | **No nested sub-plans** | If a step needs sub-steps, it's too big — split it |
88
+
89
+ ### Anti-Patterns
90
+
91
+ | Don't | Do |
92
+ |-------|-----|
93
+ | "Research best practices for X" | Just apply the best practice directly in a step |
94
+ | "Consider whether to use A or B" | Pick one, state why, move on |
95
+ | "Set up the project structure" | "Create `src/validators/` with `index.ts` and `email.ts`" |
96
+ | "Write tests" | "Add tests for `validateEmail`: valid input, empty string, missing @, >254 chars" |
97
+ | 20-step plan | 8-step plan with clear scope boundaries |
98
+ | Plan that describes what might happen | Plan that describes what WILL happen |
99
+
100
+ ## Output Format
101
+
102
+ Always present the plan in a markdown code block or as structured markdown. Never as prose paragraphs.
103
+
104
+ After presenting the plan, ask one question:
105
+ > "Ready to execute, or want to adjust anything?"
106
+
107
+ Then execute on confirmation — don't re-plan.
@@ -0,0 +1,117 @@
1
+ ---
2
+ name: cross-layer-consistency
3
+ description: Systematic methodology for verifying that IA, BE, and FE specification layers are mutually consistent. Covers coverage matrices, field mapping checks, error code propagation, access control consistency, and data contract drift detection.
4
+ ---
5
+
6
+ # Cross-Layer Consistency
7
+
8
+ This skill provides the systematic consistency verification pass run by `audit-ambiguity-execute`, `remediate-pipeline-execute`, `propagate-decision-scan`, and `evolve-feature-cascade`, and its output is a set of labeled consistency issues with layer attribution.
9
+
10
+ ## When to Use
11
+
12
+ - After all three spec layers (IA, BE, FE) have at least one document written
13
+ - As part of every audit, every remediation, every decision propagation, and every feature evolution cascade
14
+ - As a standalone pre-gate check before advancing any pipeline stage
15
+
16
+ ## Instructions
17
+
18
+ ### 1. IA → BE Coverage Matrix
19
+
20
+ Open `docs/plans/ia/index.md` to enumerate all IA shards. For each shard, read its data model and state transition sections. Then open `docs/plans/be/` and verify:
21
+
22
+ - Every IA data model entity has a corresponding BE spec section describing its schema, storage contract, and CRUD operations.
23
+ - Every IA state transition has a corresponding BE endpoint that drives it.
24
+ - Every IA user action (described in the interactions section) has a corresponding API contract in the BE spec.
25
+
26
+ Build a coverage table:
27
+
28
+ | IA Shard | IA Section | BE Spec Section | Status |
29
+ |----------|-----------|-----------------|--------|
30
+ | [name] | [section] | [BE section] | ✅ / ❌ |
31
+
32
+ Document each gap as:
33
+
34
+ ```
35
+ COVERAGE GAP: IA shard [name] § [section] → no corresponding BE spec section found.
36
+ ```
37
+
38
+ ### 2. BE → FE Field Mapping Check
39
+
40
+ For every BE endpoint documented in `docs/plans/be/`, enumerate all response fields. For each field, verify it appears in `docs/plans/fe/` — in a component prop definition, a display element, a table column, or an explicit "field not rendered" exclusion.
41
+
42
+ Then for each FE component, verify every input prop maps to a BE request field.
43
+
44
+ Build a mapping table:
45
+
46
+ | BE Endpoint | Field | FE Spec Location | Status |
47
+ |-------------|-------|-------------------|--------|
48
+ | [endpoint] | [field] | [FE location] | ✅ / ❌ |
49
+
50
+ Document each gap as:
51
+
52
+ ```
53
+ MAPPING GAP: BE endpoint [name] field [field] → not referenced in FE spec.
54
+ ```
55
+
56
+ ### 3. Error Code Consistency Cross-Reference
57
+
58
+ Build an error code table across layers: for every HTTP status code and application error type defined in BE specs, create a row. Then for each row, identify the FE spec location that handles it (error boundary, toast handler, inline error state, retry logic).
59
+
60
+ | BE Endpoint | Error Code | FE Handler | FE Spec Location | Status |
61
+ |-------------|-----------|------------|-------------------|--------|
62
+ | [endpoint] | [code] | [handler] | [location] | ✅ / ❌ |
63
+
64
+ Any BE error code with no corresponding FE entry is a gap. Document as:
65
+
66
+ ```
67
+ CONSISTENCY ISSUE: BE § [endpoint] error [code] ↔ FE — no handling found — remediation: add [code] handler to [FE spec section].
68
+ ```
69
+
70
+ ### 4. Access Control Propagation Check
71
+
72
+ For every access control rule defined in IA shards (role-resource-operation triplets), verify the rule appears in both:
73
+
74
+ - **BE**: as a middleware guard, route-level permission check, or explicit authorization step in the endpoint contract.
75
+ - **FE**: as a conditional render, route guard, or disabled state on the triggering UI element.
76
+
77
+ A rule missing from either layer is a gap. Document as:
78
+
79
+ ```
80
+ CONSISTENCY ISSUE: IA § [access control section] permission [role→resource:operation] ↔ [BE or FE] — not found — remediation: add guard to [target layer § section].
81
+ ```
82
+
83
+ ### 5. Data Contract Drift Detection
84
+
85
+ When invoked in the context of a schema change (e.g., after `evolve-contract` or a `propagate-decision` run), scan all files under `docs/plans/` for references to the changed type, field name, or validation rule. Check for:
86
+
87
+ - Field name string matches
88
+ - Type annotation references
89
+ - Validation rule references
90
+
91
+ For each file that references the old definition and has not been updated, document as:
92
+
93
+ ```
94
+ CONSISTENCY ISSUE: [source layer] § [section] ↔ [target file] § [section] — [field/type] changed in source but not reflected in target — remediation: update [target] to match [source].
95
+ ```
96
+
97
+ ### 6. Documenting Inconsistencies
98
+
99
+ All consistency issues must be written using this exact format:
100
+
101
+ ```
102
+ CONSISTENCY ISSUE: [source layer] § [section] ↔ [target layer] § [section] — [what is inconsistent] — [remediation: update [target] to match [source] OR raise for user decision]
103
+ ```
104
+
105
+ - **Source layer** is the authoritative layer (the one that should not change).
106
+ - **Target layer** is the one that needs updating.
107
+ - When it is unclear which layer is authoritative, write `raise for user decision` as the remediation and present both versions to the user. Never silently pick one.
108
+
109
+ ## Anti-Patterns
110
+
111
+ - **One-direction-only checking** — Checking only one direction of the matrix (IA→BE but not BE→IA). Coverage gaps exist in both directions.
112
+ - **Skipping the error code table** — Skipping the error code table because "the FE will just show a generic error." Every BE error code must have an explicit FE handling specification.
113
+ - **Treating access control propagation as optional** — Treating access control propagation as optional when the spec "looks simple." Missing FE route guards are a security gap, not a style preference.
114
+
115
+ ## Related Skills
116
+
117
+ - **`resolve-ambiguity`** — Hand off to `resolve-ambiguity` when a consistency issue cannot be resolved by simply updating the target layer to match the source. Specifically: when both layers present plausible but conflicting definitions and it is unclear which is authoritative, or when the inconsistency reveals a gap that requires new information from the user. This skill detects *what is inconsistent*; `resolve-ambiguity` determines *what the correct answer should be* through its tiered information-gathering methodology.
@@ -0,0 +1,205 @@
1
+ ---
2
+ name: database-schema-design
3
+ description: Design database schemas with normalization, relationships, and constraints. Use when creating new database schemas, designing tables, or planning data models for any database paradigm.
4
+ ---
5
+
6
+ # Database Schema Design
7
+
8
+ ## Overview
9
+
10
+ Design scalable, well-structured database schemas with proper relationships, constraints, and data types. This skill covers universal data modeling principles. For paradigm-specific patterns, see references.
11
+
12
+ ## When to Use
13
+
14
+ - New database schema design
15
+ - Data model planning
16
+ - Relationship design (1:1, 1:N, N:N, graph edges)
17
+ - Normalization or denormalization analysis
18
+ - Constraint and validation planning
19
+ - Performance optimization at schema level
20
+ - Cross-store entity consistency
21
+
22
+ ## Paradigm-Specific References
23
+
24
+ After reading the methodology below, read the reference matching your surface's Databases column in the surface stack map (`.agent/instructions/tech-stack.md`):
25
+
26
+ | Paradigm | Reference | Example Stores |
27
+ |----------|-----------|----------------|
28
+ | Relational | `references/relational.md` | PostgreSQL, MySQL, SQLite |
29
+ | Document | `references/document.md` | MongoDB, Firestore, CouchDB |
30
+ | Graph | `references/graph.md` | SurrealDB, Neo4j, ArangoDB |
31
+ | Key-Value | `references/key-value.md` | Redis, DynamoDB, Memcached |
32
+
33
+ ---
34
+
35
+ ## Universal Data Modeling Principles
36
+
37
+ ### 1. Entity Identification
38
+
39
+ Start with the domain:
40
+ 1. **Identify nouns** — these become entities/tables/collections
41
+ 2. **Identify relationships** — how entities connect
42
+ 3. **Identify attributes** — what data each entity holds
43
+ 4. **Identify cardinality** — one-to-one, one-to-many, many-to-many
44
+
45
+ ### 2. Normalization vs Denormalization
46
+
47
+ **Normalization** reduces data duplication at the cost of join complexity:
48
+ - **1NF** — Eliminate repeating groups (no arrays/CSVs in a single field)
49
+ - **2NF** — Remove partial dependencies (every non-key attribute depends on the WHOLE key)
50
+ - **3NF** — Remove transitive dependencies (non-key attributes don't depend on each other)
51
+
52
+ **Denormalization** trades storage for read performance:
53
+ - Embed frequently co-read data together
54
+ - Pre-compute aggregates for dashboards
55
+ - Duplicate data intentionally (with consistency strategy)
56
+
57
+ **Decision framework:**
58
+ - Write-heavy, consistency-critical → normalize
59
+ - Read-heavy, latency-sensitive → denormalize
60
+ - Mixed → normalize core, denormalize read models
61
+
62
+ ### 3. Relationship Patterns
63
+
64
+ | Pattern | Relational | Document | Graph |
65
+ |---------|-----------|----------|-------|
66
+ | **One-to-One** | Foreign key with UNIQUE | Embed subdocument | Edge with cardinality constraint |
67
+ | **One-to-Many** | Foreign key on child | Embed array OR reference | Edge from parent to children |
68
+ | **Many-to-Many** | Junction/join table | Array of references on both sides | Direct edges |
69
+ | **Hierarchical** | Self-referencing FK | Nested documents | Recursive graph traversal |
70
+
71
+ ### 4. Access Pattern Design
72
+
73
+ Schema design is driven by how data is **queried**, not just how it's structured:
74
+
75
+ 1. **List your read queries** — what does the UI need to display?
76
+ 2. **List your write queries** — what creates/updates data?
77
+ 3. **Design schema to serve the reads** — not the other way around
78
+ 4. **Index for query patterns** — not for every possible query
79
+
80
+ ### 5. Constraint Strategy
81
+
82
+ Every schema must enforce:
83
+ - **Required fields** — NOT NULL / required validators
84
+ - **Uniqueness** — unique constraints on natural keys (email, SKU, slug)
85
+ - **Referential integrity** — foreign keys, references, or application-level checks
86
+ - **Domain constraints** — CHECK constraints, enums, value ranges
87
+ - **Cascade behavior** — what happens when parent is deleted (CASCADE, SET NULL, RESTRICT)
88
+
89
+ ### 6. ID Strategy
90
+
91
+ | Strategy | When to Use |
92
+ |----------|-------------|
93
+ | **UUID v4** | Default choice. No ordering, globally unique, no collision |
94
+ | **UUID v7** | When you need time-sortable UUIDs (better index performance) |
95
+ | **Auto-increment** | Simple cases, single-database, non-distributed |
96
+ | **ULID** | Time-sortable, lexicographically sortable, URL-safe |
97
+ | **Natural key** | When domain provides a unique identifier (ISBN, SSN) — use with caution |
98
+
99
+ ---
100
+
101
+ ## Schema Design Checklist
102
+
103
+ - [ ] Identify entities and relationships
104
+ - [ ] Choose ID strategy
105
+ - [ ] Apply normalization rules (or consciously denormalize with rationale)
106
+ - [ ] Define primary keys for all entities
107
+ - [ ] Create foreign keys / references for relationships
108
+ - [ ] Add constraints for data integrity
109
+ - [ ] Select appropriate data types
110
+ - [ ] Plan indexes for common queries
111
+ - [ ] Design for scalability
112
+ - [ ] Document entity purposes and relationships
113
+ - [ ] Plan for schema evolution
114
+
115
+ ## Common Pitfalls
116
+
117
+ ❌ Don't skip normalization for convenience
118
+ ❌ Don't use unbounded text types for all string fields
119
+ ❌ Don't forget referential integrity constraints
120
+ ❌ Don't use mutable natural keys as primary keys
121
+ ❌ Don't store computed values without a cache invalidation strategy
122
+ ❌ Don't design schema without knowing query patterns
123
+
124
+ ✅ DO use UUIDs or equivalent for primary keys
125
+ ✅ DO normalize data unless you have a measured performance reason not to
126
+ ✅ DO add validation constraints at the schema level
127
+ ✅ DO index foreign keys and common query fields
128
+ ✅ DO use timestamps for audit trails
129
+
130
+ ---
131
+
132
+ ## Persistence Map Interview
133
+
134
+ This interview runs during `/create-prd-stack` Sub-steps A–E. It maps every feature to its query types, then selects the right store for each query type.
135
+
136
+ ### Sub-step A — Feature-to-Query Table
137
+
138
+ Walk through every major feature in `ideation-index.md` and ask: "What does this feature need to find, store, relate, and rank/search?"
139
+
140
+ Build the following table:
141
+
142
+ | Feature | Find | Store | Relate | Rank/Search |
143
+ |---------|------|-------|--------|-------------|
144
+ | (from ideation-index.md) | … | … | … | … |
145
+
146
+ Present and confirm the table with the user before proceeding to Sub-step B.
147
+
148
+ ### Sub-step B — Registry-First Skill Search
149
+
150
+ Before presenting any store options, read `.agent/skills/find-skills/SKILL.md` and run `npx skills find [query type or store name]` for each query type that appeared in the table.
151
+
152
+ If the registry returns a skill, install it first. The bundled skill library is a fallback only.
153
+
154
+ ### Sub-step C — Store Selection Per Query Type
155
+
156
+ Present store options only for query types that appeared in the table:
157
+
158
+ - Skip `DATABASE_VECTOR` if no Rank/Search requirement appeared.
159
+ - Skip `DATABASE_GRAPH` if no Relate requirement appeared.
160
+
161
+ Use constraint-first per-axis flow: constraint questions → filter → present → confirm.
162
+
163
+ ### Sub-step D — Bootstrap Per Confirmed Store
164
+
165
+ For each confirmed store, fire bootstrap with its specific sub-key:
166
+
167
+ - e.g., `DATABASE_PRIMARY=PostgreSQL`, `DATABASE_VECTOR=Qdrant`
168
+ - One bootstrap call per sub-key.
169
+ - Each confirmation adds a database skill to the Databases column of the relevant surface row in the surface stack map.
170
+
171
+ ### Sub-step E — Write Persistence Map
172
+
173
+ After all stores are confirmed, write to `docs/plans/architecture-draft.md` as a locked section titled `## Persistence Map`.
174
+
175
+ Must include:
176
+ - The feature-to-query table from Sub-step A
177
+ - A mapping of each query type to its canonical store with rationale
178
+
179
+ ---
180
+
181
+ ## Cross-Store Entity Consistency Protocol
182
+
183
+ ### Triggering Rule
184
+
185
+ This protocol runs for every entity that spans more than one store.
186
+
187
+ ### The 4 Questions
188
+
189
+ For each cross-store entity, answer the following in order:
190
+
191
+ 1. **Canonical ID** — Single identifier tying representations together. Must be the primary store's UUID stored as a property in every other store — never the graph store's or vector store's internal ID.
192
+
193
+ 2. **Creation sequence** — Which store is written first. Recovery mechanism for partial write failures (Saga pattern, compensating transaction, or async retry queue — name which).
194
+
195
+ 3. **Deletion cascade** — Cleanup order, mechanism (application-layer sequential deletes, DB-level triggers, or background job — name which).
196
+
197
+ 4. **Read strategy** — Whether a read requires data from multiple stores. Name the application-layer join pattern explicitly.
198
+
199
+ ### Skill Instruction
200
+
201
+ Read all database skills listed in the Databases column of the surface stack map (`.agent/instructions/tech-stack.md`) for advice on each store's transaction semantics and consistency guarantees before completing this step.
202
+
203
+ ### Output
204
+
205
+ Write the completed cross-store consistency table to `architecture-draft.md` as part of the `## Data Strategy` section.
@@ -0,0 +1,228 @@
1
+ # Relational Database Schema Patterns
2
+
3
+ Paradigm-specific patterns for the `database-schema-design` skill. Read `SKILL.md` first for universal methodology.
4
+
5
+ Covers: **PostgreSQL**, **MySQL**, **SQLite**
6
+
7
+ ---
8
+
9
+ ## Normalization Examples
10
+
11
+ ### First Normal Form (1NF) — Eliminate Repeating Groups
12
+
13
+ ```sql
14
+ -- NOT 1NF: repeating group in single column
15
+ CREATE TABLE orders_bad (
16
+ id UUID PRIMARY KEY,
17
+ customer_name VARCHAR(255),
18
+ product_ids VARCHAR(255) -- "1,2,3" - repeating group
19
+ );
20
+
21
+ -- 1NF: separate table for repeating data
22
+ CREATE TABLE orders (
23
+ id UUID PRIMARY KEY,
24
+ customer_name VARCHAR(255),
25
+ created_at TIMESTAMP DEFAULT NOW()
26
+ );
27
+
28
+ CREATE TABLE order_items (
29
+ id UUID PRIMARY KEY,
30
+ order_id UUID NOT NULL,
31
+ product_id UUID NOT NULL,
32
+ quantity INTEGER NOT NULL,
33
+ FOREIGN KEY (order_id) REFERENCES orders(id) ON DELETE CASCADE
34
+ );
35
+ ```
36
+
37
+ ### Second Normal Form (2NF) — Remove Partial Dependencies
38
+
39
+ ```sql
40
+ -- 2NF: separate tables for partial deps
41
+ CREATE TABLE enrollments (
42
+ id UUID PRIMARY KEY,
43
+ student_id UUID NOT NULL,
44
+ course_id UUID NOT NULL,
45
+ FOREIGN KEY (student_id) REFERENCES students(id),
46
+ FOREIGN KEY (course_id) REFERENCES courses(id),
47
+ UNIQUE(student_id, course_id)
48
+ );
49
+
50
+ CREATE TABLE courses (
51
+ id UUID PRIMARY KEY,
52
+ name VARCHAR(255),
53
+ professor_id UUID NOT NULL,
54
+ FOREIGN KEY (professor_id) REFERENCES professors(id)
55
+ );
56
+ ```
57
+
58
+ ### Third Normal Form (3NF) — Remove Transitive Dependencies
59
+
60
+ ```sql
61
+ -- 3NF: separate lookup tables
62
+ CREATE TABLE states (
63
+ id UUID PRIMARY KEY,
64
+ code VARCHAR(2) UNIQUE,
65
+ name VARCHAR(100),
66
+ tax_rate DECIMAL(5,3)
67
+ );
68
+
69
+ CREATE TABLE orders (
70
+ id UUID PRIMARY KEY,
71
+ customer_city VARCHAR(100),
72
+ state_id UUID NOT NULL,
73
+ FOREIGN KEY (state_id) REFERENCES states(id)
74
+ );
75
+ ```
76
+
77
+ ---
78
+
79
+ ## Relationship Patterns
80
+
81
+ ### One-to-Many
82
+
83
+ ```sql
84
+ CREATE TABLE users (
85
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
86
+ email VARCHAR(255) UNIQUE NOT NULL,
87
+ name VARCHAR(255) NOT NULL,
88
+ created_at TIMESTAMP DEFAULT NOW()
89
+ );
90
+
91
+ CREATE TABLE orders (
92
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
93
+ user_id UUID NOT NULL,
94
+ order_date TIMESTAMP DEFAULT NOW(),
95
+ total DECIMAL(10,2),
96
+ FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
97
+ );
98
+ CREATE INDEX idx_orders_user_id ON orders(user_id);
99
+ ```
100
+
101
+ ### One-to-One
102
+
103
+ ```sql
104
+ CREATE TABLE user_profiles (
105
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
106
+ user_id UUID UNIQUE NOT NULL,
107
+ bio TEXT,
108
+ avatar_url VARCHAR(500),
109
+ FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
110
+ );
111
+ ```
112
+
113
+ ### Many-to-Many (Junction Table)
114
+
115
+ ```sql
116
+ CREATE TABLE course_enrollments (
117
+ id UUID PRIMARY KEY,
118
+ student_id UUID NOT NULL,
119
+ course_id UUID NOT NULL,
120
+ enrolled_at TIMESTAMP DEFAULT NOW(),
121
+ FOREIGN KEY (student_id) REFERENCES students(id) ON DELETE CASCADE,
122
+ FOREIGN KEY (course_id) REFERENCES courses(id) ON DELETE CASCADE,
123
+ UNIQUE(student_id, course_id)
124
+ );
125
+ ```
126
+
127
+ ---
128
+
129
+ ## Constraint Strategy
130
+
131
+ ```sql
132
+ -- NOT NULL, UNIQUE, CHECK, DEFAULT
133
+ CREATE TABLE products (
134
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
135
+ name VARCHAR(255) NOT NULL,
136
+ sku VARCHAR(100) NOT NULL UNIQUE,
137
+ price DECIMAL(10,2) NOT NULL CHECK (price > 0),
138
+ status VARCHAR(20) NOT NULL CHECK (status IN ('active', 'archived', 'draft'))
139
+ );
140
+
141
+ CREATE TABLE audit_logs (
142
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
143
+ table_name VARCHAR(100) NOT NULL,
144
+ operation VARCHAR(10) NOT NULL,
145
+ user_id UUID,
146
+ timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP
147
+ );
148
+ ```
149
+
150
+ ---
151
+
152
+ ## Data Type Selection
153
+
154
+ ### PostgreSQL
155
+
156
+ ```sql
157
+ CREATE TABLE users (
158
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
159
+ email VARCHAR(255),
160
+ name TEXT,
161
+ age SMALLINT,
162
+ balance DECIMAL(15,2), -- Financial data (precise)
163
+ is_active BOOLEAN DEFAULT true,
164
+ birth_date DATE,
165
+ last_login TIMESTAMP WITH TIME ZONE,
166
+ created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
167
+ metadata JSONB,
168
+ tags TEXT[] DEFAULT ARRAY[]::TEXT[] -- PostgreSQL arrays
169
+ );
170
+ ```
171
+
172
+ ### MySQL
173
+
174
+ ```sql
175
+ CREATE TABLE users (
176
+ id CHAR(36) PRIMARY KEY, -- UUID as CHAR
177
+ email VARCHAR(255),
178
+ name VARCHAR(255),
179
+ age TINYINT UNSIGNED,
180
+ balance DECIMAL(15,2),
181
+ is_active BOOLEAN DEFAULT true,
182
+ birth_date DATE,
183
+ last_login TIMESTAMP,
184
+ created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
185
+ metadata JSON,
186
+ KEY idx_email (email)
187
+ );
188
+ ```
189
+
190
+ ---
191
+
192
+ ## Schema Evolution
193
+
194
+ ```sql
195
+ -- Add column with default (backward compatible)
196
+ ALTER TABLE users ADD COLUMN phone VARCHAR(20);
197
+
198
+ -- Add constraint on new column
199
+ ALTER TABLE orders ADD CONSTRAINT check_notes CHECK (LENGTH(notes) <= 500);
200
+
201
+ -- Deprecate column safely
202
+ ALTER TABLE users RENAME COLUMN old_field TO old_field_deprecated;
203
+ ```
204
+
205
+ ---
206
+
207
+ ## Performance: Partitioning
208
+
209
+ ```sql
210
+ -- PostgreSQL: Partition by date range for time-series data
211
+ CREATE TABLE events (
212
+ id UUID PRIMARY KEY,
213
+ user_id UUID NOT NULL,
214
+ event_type VARCHAR(100),
215
+ created_at TIMESTAMP NOT NULL
216
+ ) PARTITION BY RANGE (DATE_TRUNC('month', created_at));
217
+
218
+ CREATE TABLE events_2024_01 PARTITION OF events
219
+ FOR VALUES FROM ('2024-01-01') TO ('2024-02-01');
220
+ ```
221
+
222
+ ---
223
+
224
+ ## Resources
225
+
226
+ - [PostgreSQL Data Types](https://www.postgresql.org/docs/current/datatype.html)
227
+ - [MySQL Data Types](https://dev.mysql.com/doc/refman/8.0/en/data-types.html)
228
+ - [Database Normalization Guide](https://en.wikipedia.org/wiki/Database_normalization)