macca-method 1.1.0 → 2.0.0

package/.agents/skills/brainstorm-rules/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: brainstorm-rules
-description: Interview users and generate `rules.md` (Coding Standards / Code Constitution). Use before coding to define coding rules and AI behavior guidance.
-persona: "Fachri"
-persona_role: "Tech Lead"
+description: Interviews users and generates `rules.md` for coding, security, dependency, testing, AI behavior, and conditional operational conventions. Use only when the user explicitly requests repository-wide implementation rules.
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
+metadata:
+  persona: "Fachri"
+  persona-role: "Tech Lead"
 ---
 
 # Brainstorm Rules
@@ -43,11 +45,13 @@ This skill generates **rules.md**: a "code constitution" so AI works consistentl
     - `project-context/api.md` — auth contract, rate limiting, abuse controls
 
 3. **Shared Runtime Setup** — before the interview:
-  - Read `../_shared/references/runtime-config.md`.
+  - Read `../_shared/references/language-config.md`.
+  - Read `../_shared/references/config-mutation.md`.
   - Read `../_shared/references/brainstorm-session.md`.
+  - Read `../_shared/references/scope-rules.md`.
   - Use `languagePreferences.communication.normalized` for chat.
   - Use `languagePreferences.documents.normalized` for the final `project-context/rules.md`.
-  - Apply `brainstormPreferences.discussionMode` and `brainstormPreferences.recommendations` using the shared session policy.
+  - Apply `brainstormPreferences.discussionMode`, `recommendations`, and `discoveryDepth` using the shared session policy.
   - For this skill: announce that there are 7 topics, ask for pacing (one by one / three at once / all at once), and ask for recommendation preference if it is not already stored.
 
 4. Run the interview in the selected mode. Wait for the answer before continuing.
@@ -108,6 +112,11 @@ This skill generates **rules.md**: a "code constitution" so AI works consistentl
 - CORS: which origins are allowed?
 - Secret scanning: pre-commit hooks?
 - Align with decisions in `architecture.md`, `schema.md`, `api.md` — no contradictions.
+- If architecture defines observability: structured log levels, correlation IDs, redaction, sampling, and forbidden sensitive fields
+- If schema defines migrations: naming, compatibility, destructive-change approval, transaction/backfill, and validation conventions
+- If architecture uses feature flags: naming, default/fail-safe value, owner, expiry/cleanup, and test matrix
+- If generators are used: which generated files may be edited and how regeneration is validated
+- If runtime credentials are managed: rotation and revocation expectations
 
 ### 5. AI Behavior Rules
 **Ask:** *"Are there special rules for AI? When should it ask first instead of assuming?"*
@@ -142,154 +151,11 @@ This skill generates **rules.md**: a "code constitution" so AI works consistentl
 - Minimum coverage percentage?
 - Test requirement: mandatory for every new feature?
 
-## Output Format (rules.md)
+## rules.md Output
 
-````markdown
-# Coding Standards (Rules)
+After discovery is complete and immediately before generating `project-context/rules.md`, read `assets/rules.template.md`.
 
-## Document Role
-- **Source of Truth:** Coding standards, AI behavior constraints, and implementation security rules
-- **Primary Owner:** `brainstorm-rules`
-- **Out of Scope:** Product scope decisions, schema design, endpoint payload contracts, and task sequencing
-
----
-
-## 1. AI Persona & Tech Stack
-> You are an expert developer in: [TypeScript, React, Next.js 14 App Router, Prisma, PostgreSQL, TanStack Query, Zustand].
-
-**Prioritize:**
-- [Preferred patterns]
-
-**Avoid:**
-- [Patterns to avoid]
-
----
-
-## 2. Naming Conventions
-| Type | Convention | Example |
-|------|------------|---------|
-| Variables & Functions | camelCase | `getUserData`, `isLoading` |
-| React Components | PascalCase | `UserCard`, `LoginForm` |
-| Files & Folders | kebab-case | `user-card.tsx`, `auth/` |
-| Global Constants | UPPER_CASE | `MAX_RETRIES`, `API_URL` |
-| Event Handlers | `handle` prefix | `handleSubmit`, `handleClick` |
-| Boolean | `is/has/can` prefix | `isLoading`, `hasError` |
-| Database Tables | snake_case, plural | `users`, `product_categories` |
-
----
-
-## 3. Code Style & Quality
-- **TypeScript:** Strict mode enabled. Avoid `any` and `enum` (use `as const`).
-- **Console.log:** Forbidden in production. Use a proper logger.
-- **Error Handling:** `try-catch` required for async operations. Use early returns (guard clauses).
-- **Else after return:** FORBIDDEN — use the early return pattern.
-- **Import order:** builtin → external → internal → relative → types
-- **Max function length:** [X lines]
-- **Comments:** [JSDoc required / minimal]
-- **Dependency ladder:** Reuse existing code first, then standard library, native platform, installed dependencies, and only then add new dependencies.
-- **Intentional simplification:** Mark with a `tradeoff:` comment that states the ceiling and upgrade trigger.
-- **Never simplify:** trust-boundary validation, data-loss protection, accessibility basics, or explicitly requested behavior.
-
-```typescript
-// ✅ CORRECT — early return
-function processUser(user: User | null) {
-  if (!user) return null;
-  if (!user.isActive) return null;
-  return doSomething(user);
-}
-
-// ❌ WRONG — deep nesting
-function processUser(user: User | null) {
-  if (user) {
-    if (user.isActive) {
-      return doSomething(user);
-    }
-  }
-}
-```
-
----
-
-## 4. Security Rules
-> **MANDATORY:** Before writing code involving user input, auth, file upload, or database access — check at least these 4 items and explain them briefly: input validation, secret/token protection, safe queries, and access control.
-
-- **Token Storage:** Store JWTs in **httpOnly cookies**, NOT localStorage.
-- **Input Sanitization:** Validate and sanitize all input before processing (use Zod/Joi).
-- **Environment Variables:** Never hardcode secrets. All env vars must exist in `.env.example`.
-- **Query Security:** Always use parameterized queries or an ORM. NEVER concatenate user input into SQL.
-- **XSS:** Avoid `dangerouslySetInnerHTML`. If required, sanitize with DOMPurify.
-- **CORS:** Approved origins: [origin list]. Never use `*` in production.
-- **Dependencies:** Run `npm audit` before every release. Block HIGH severity.
-
----
-
-## 5. AI Behavior Rules
-- **Comment Language:** [Indonesian / English]
-- **Error Messages (user-facing):** [Indonesian / English]
-- **When Ambiguous:** Ask the user first; do not assume.
-- **When Errors Happen:** Analyze error logs first. Do not guess.
-- **New Package Installation:** Ask permission first; state the reason.
-- **Out-of-Scope Modifications:** Forbidden without confirmation.
-- **Complex Implementations:** Show a plan/rationale before implementing.
-
-## Rule Priority
-- **Priority Order:** Security → correctness → data protection → consistency → maintainability → convenience
-- If two rules seem to conflict, choose the higher-priority rule and note the trade-off.
-- If a local exception is needed, mark it clearly with a `tradeoff:` comment and explain the upgrade trigger.
-
----
-
-## 6. Git Workflow
-**Conventional Commits** — required for all commits.
-
-| Type | When |
-|------|------|
-| `feat:` | New feature |
-| `fix:` | Bug fix |
-| `chore:` | Maintenance (update deps, config) |
-| `docs:` | Documentation changes |
-| `refactor:` | Code restructuring without feature/bug change |
-| `style:` | Formatting (no logic changes) |
-| `test:` | Add or fix tests |
-| `perf:` | Performance improvement |
-| `ci:` | CI/CD config changes |
-
-**Example:** `feat(auth): add Google OAuth login`
-
-**Branch naming:**
-- `feature/[feature-name]`
-- `fix/[bug-name]`
-- `chore/[task-name]`
-
----
-
-## 7. Linter, Formatter & Testing
-- **ESLint:** v9 (flat config — `eslint.config.js`). Rules: `eslint:recommended`, `@typescript-eslint/recommended`.
-- **Prettier:** `semi: false`, `singleQuote: true`, `tabWidth: 2`, `printWidth: 80`.
-- **.editorconfig:** `charset=utf-8`, `end_of_line=lf`, `insert_final_newline=true`.
-- **Test Framework:** [Jest / Vitest / Playwright]
-- **Minimum Coverage:** [X%]
-- **Test Requirement:** Yes — every new function/endpoint must have tests (TDD: write the test before implementation).
-
----
-
-## [FORBIDDEN]
-
-> Check this list before writing any code. Violating even one item = code rejected.
-
-| # | Forbidden | Why |
-|---|-----------|-----|
-| F-01 | NEVER use `any` (TypeScript) | Destroys type safety |
-| F-02 | NEVER hardcode secrets, URLs, or config — use env vars | Security & portability |
-| F-03 | NEVER concatenate user input into SQL/query — use parameterized queries/ORM | SQL Injection |
-| F-04 | NEVER store tokens in localStorage — use httpOnly cookies | XSS vulnerability |
-| F-05 | NEVER use `console.log` / `print` in production code | Info leaks, noise |
-| [F-06+] | [Project-specific prohibition from topics 1–7] | [Reason] |
-
-## Assumptions & Exceptions
-- [Assumption about team workflow or tooling]
-- [Temporary exception with owner / review trigger]
-````
+Adapt only sections that are applicable and preserve every required contract from the interview. Do not load the template during early discovery.
 
 ---
 

package/.agents/skills/brainstorm-rules/assets/rules.template.md

@@ -0,0 +1,127 @@
+# Coding Standards (Rules)
+
+## Document Role
+- **Source of Truth:** Coding standards, AI behavior constraints, and implementation security rules
+- **Primary Owner:** `brainstorm-rules`
+- **Out of Scope:** Product scope decisions, schema design, endpoint payload contracts, and task sequencing
+
+---
+
+## 1. AI Persona & Tech Stack
+> You are an expert developer in: [stack confirmed by architecture and user].
+
+**Prioritize:**
+- [Preferred patterns]
+
+**Avoid:**
+- [Patterns to avoid]
+
+---
+
+## 2. Naming Conventions
+| Type | Convention | Example |
+|------|------------|---------|
+| [Project symbol type] | [confirmed convention] | [stack-native example] |
+| Files & Folders | [confirmed convention] | [example] |
+| Persisted entities/fields | [datastore-native convention] | [example] |
+
+---
+
+## 3. Code Style & Quality
+- **Language-specific rules:** [rules confirmed for the selected language; omit inapplicable TypeScript examples]
+- **Production diagnostics:** [confirmed logging/telemetry rule]
+- **Error Handling:** [stack-native strategy confirmed by the project]
+- **Control flow:** [confirmed readability rule]
+- **Import/dependency order:** [confirmed convention if applicable]
+- **Max function length:** [X lines]
+- **Comments:** [JSDoc required / minimal]
+- **Dependency ladder:** Reuse existing code first, then standard library, native platform, installed dependencies, and only then add new dependencies.
+- **Intentional simplification:** Mark with a `tradeoff:` comment that states the ceiling and upgrade trigger.
+- **Never simplify:** trust-boundary validation, data-loss protection, accessibility basics, or explicitly requested behavior.
+
+Add a language-specific example only when it communicates a confirmed rule better than prose.
+
+---
+
+## 4. Security Rules
+> **MANDATORY:** Before writing code involving user input, auth, file upload, or database access — check at least these 4 items and explain them briefly: input validation, secret/token protection, safe queries, and access control.
+
+- **Token/Session Storage:** [project-specific decision; do not assume JWT or browser cookies]
+- **Input Validation:** Validate untrusted input with [existing project mechanism].
+- **Secret/Configuration Storage:** [project/platform-specific mechanism]
+- **Injection Prevention:** [safe query, shell, template, and parser rules relevant to this stack]
+- **Client Rendering Security:** [XSS/content rule only if the project renders untrusted content]
+- **Cross-Origin/Network Policy:** [only if the project exposes a network surface]
+- **Dependencies:** Run the project's available dependency audit before release when network policy permits. Block [agreed threshold].
+
+### Conditional Operational Rules
+- **Structured Logging:** [only when architecture defines observability]
+- **Migration Conventions:** [only when schema evolution applies]
+- **Feature Flag Lifecycle:** [only when architecture selects flags]
+- **Generated Code:** [editable/regenerate policy when applicable]
+- **Secret Rotation:** [when runtime credentials apply]
+
+---
+
+## 5. AI Behavior Rules
+- **Comment Language:** [Indonesian / English]
+- **Error Messages (user-facing):** [Indonesian / English]
+- **When Ambiguous:** Ask the user first; do not assume.
+- **When Errors Happen:** Analyze error logs first. Do not guess.
+- **New Package Installation:** Ask permission first; state the reason.
+- **Out-of-Scope Modifications:** Forbidden without confirmation.
+- **Complex Implementations:** Show a plan/rationale before implementing.
+
+## Rule Priority
+- **Priority Order:** Security → correctness → data protection → consistency → maintainability → convenience
+- If two rules seem to conflict, choose the higher-priority rule and note the trade-off.
+- If a local exception is needed, mark it clearly with a `tradeoff:` comment and explain the upgrade trigger.
+
+---
+
+## 6. Git Workflow
+**Commit format:** [confirmed workflow; omit this table if Conventional Commits was not selected].
+
+| Type | When |
+|------|------|
+| `feat:` | New feature |
+| `fix:` | Bug fix |
+| `chore:` | Maintenance (update deps, config) |
+| `docs:` | Documentation changes |
+| `refactor:` | Code restructuring without feature/bug change |
+| `style:` | Formatting (no logic changes) |
+| `test:` | Add or fix tests |
+| `perf:` | Performance improvement |
+| `ci:` | CI/CD config changes |
+
+**Example:** `feat(auth): add Google OAuth login`
+
+**Branch naming:**
+- `feature/[feature-name]`
+- `fix/[bug-name]`
+- `chore/[task-name]`
+
+---
+
+## 7. Linter, Formatter & Testing
+- **Linter:** [existing tool/version/config; omit if none].
+- **Formatter:** [existing tool/options; omit if none].
+- **Editor settings:** [existing settings; omit if none].
+- **Test Framework:** [existing project framework]
+- **Minimum Coverage:** [X%]
+- **Test Requirement:** [project policy: test-first, test-with-change, or another explicit workflow].
+
+---
+
+## [FORBIDDEN]
+
+> Check this list before writing any code. Violating even one item = code rejected.
+
+| # | Forbidden | Why |
+|---|-----------|-----|
+| F-01 | Never hardcode or expose secrets | Security |
+| F-02+ | [Confirmed stack/project-specific prohibition] | [Reason] |
+
+## Assumptions & Exceptions
+- [Assumption about team workflow or tooling]
+- [Temporary exception with owner / review trigger]

package/.agents/skills/brainstorm-schema/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: brainstorm-schema
-description: Interview users and generate `schema.md` (Data Model / Database Schema). Use after `architecture.md` is complete.
-persona: "Fachri"
-persona_role: "Tech Lead"
+description: Interviews users and generates `schema.md` for relational, document, key-value, graph, event-store, or mixed persistence, including evolution and recovery. Use only when the user explicitly requests data-model design after architecture.
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
+metadata:
+  persona: "Fachri"
+  persona-role: "Tech Lead"
 ---
 
 # Brainstorm Schema
@@ -34,12 +36,13 @@ You are **@Fachri — Tech Lead**, a **Senior Database Architect** who designs e
 
 Before any interview:
 
-1. Read `../_shared/references/runtime-config.md`.
-2. Read `../_shared/references/brainstorm-session.md`.
-3. Read `../_shared/references/scope-rules.md`.
+1. Read `../_shared/references/language-config.md`.
+2. Read `../_shared/references/config-mutation.md`.
+3. Read `../_shared/references/brainstorm-session.md`.
+4. Read `../_shared/references/scope-rules.md`.
 4. Use `languagePreferences.communication.normalized` for chat.
 5. Use `languagePreferences.documents.normalized` for the final `project-context/schema.md`.
-6. Apply `brainstormPreferences.discussionMode` and `brainstormPreferences.recommendations` using the shared session policy.
+6. Apply `brainstormPreferences.discussionMode`, `recommendations`, and `discoveryDepth` using the shared session policy.
 
 ---
 
@@ -53,7 +56,7 @@ Before any interview:
 
 3. If `.agents/developer-config.json` exists and `developerPreferences.scope = "frontend"`, DO NOT create `schema.md`. Explain that database and schema work is outside the current scope, and that backend dependencies should be documented only through the `api.md` consumer contract.
 
-4. Run the shared runtime setup above. For this skill, ask whether to cover the 5 global topics one by one or three at once, then apply the stored or chosen recommendation preference.
+4. Run the shared runtime setup above and apply all three pacing modes from the shared session policy. If preferences are saved, announce and proceed without another confirmation.
 
 5. Run the interview in the chosen mode. Wait for answers.
 
@@ -65,137 +68,68 @@ Before any interview:
 
 ## Interview Topics (5 Topics — All Required)
 
-Ask all five topics using the chosen pacing mode for global topics.
+Ask all five topics using the chosen pacing mode. First classify the persistence model from `architecture.md` as relational, document, key-value, graph, event store, or mixed. Adapt terminology and output to that model.
 
 ### 1. Database Conventions
 *"Before tables, let's align on conventions. Any preferences?"*
 
 Collect:
-- **ID strategy:** UUID, auto-increment, CUID?
-- **Table naming:** plural snake_case (`users`, `products`) or singular?
-- **Audit fields:** Should all tables have `created_at`, `updated_at`? Set by app or DB trigger?
-- **Soft delete:** Use `deleted_at` (soft delete) or hard delete?
+- **Identity strategy:** primary key, document ID, aggregate/stream ID, graph ID, or key format?
+- **Naming:** datastore-native naming for tables, collections, keys, node labels, streams, and fields?
+- **Audit/version metadata:** timestamps, version/revision, event metadata, or none?
+- **Deletion/retention:** hard delete, soft delete, tombstone, archival, compaction, or immutable events?
 - **Timestamp:** UTC or local timezone?
 - **Retention:** How long is data stored? Any anonymization or archival schedule?
 
-### 2. Table List
-*"What tables or collections are needed?"*
+### 2. Entity/Storage List
+*"What tables, collections, aggregates, nodes, or stores are needed?"*
 
-Collect:
-- All table names
-- Short description of each table's purpose
-- Any junction/pivot tables for many-to-many relationships?
+Collect by persistence model:
+- **Relational:** tables and junction tables
+- **Document:** collections, document roots, and embedded subdocuments
+- **Key-value:** key spaces, key format, and value shape
+- **Graph:** node labels, edge types, and key properties
+- **Event store:** aggregates, stream names, event types, and projections
+- **All modes:** purpose, ownership boundary, and source requirement for each structure
+- **Multi-tenant systems only:** tenant key/boundary, isolation enforcement, cross-tenant constraints, export/deletion, and partition strategy
 
-### 3. Columns & Data Types
-*"For each table, list the columns and data types."*
+### 3. Fields & Data Types
+*"For each data structure, list fields and datastore-native data types."*
 
-Collect per table:
-- Column names and types (VARCHAR, INTEGER, UUID, TEXT, BOOLEAN, TIMESTAMP, DECIMAL, ENUM, JSONB)
-- Constraints (NOT NULL, UNIQUE, DEFAULT, PRIMARY KEY)
+Collect per datastore-native structure:
+- Field names and datastore-native types
+- Validation/constraints appropriate to the selected model
 - Which columns contain sensitive data/PII?
 - For sensitive columns: hash, encrypt, mask, or plain text?
 - Any intentionally denormalized columns (intentionally duplicated)?
+- Expected record/document/event volume, growth rate, payload size, and retention horizon where material
 
-### 4. Relationships
-*"What relationships exist between the tables: one-to-one, one-to-many, many-to-many?"*
+### 4. Relationships and Data Placement
+*"What relationships exist, and should related data use foreign keys, references, embedding, edges, or another datastore-native pattern?"*
 
 Collect:
-- Relationship type
-- Which table stores the foreign key?
-- Delete rules (CASCADE, SET NULL, RESTRICT)?
+- **Relational:** cardinality, foreign-key owner, and cascade/set-null/restrict behavior
+- **Document:** embedding vs references, document growth, and update atomicity
+- **Key-value:** key composition, lookup direction, and secondary-index needs
+- **Graph:** edge direction/cardinality and traversal boundaries
+- **Event store:** aggregate boundaries, stream correlation, projection consistency, and event evolution
+- **All modes:** delete/retention behavior and cross-structure consistency
+- Concurrency model: transaction boundary, optimistic version, lock/contention policy, duplicate update protection, or equivalent
 
 ### 5. Indexes & Performance
-*"Which columns are often used in `WHERE`, `ORDER BY`, or `JOIN` clauses? What should be indexed?"*
+*"Which access patterns, filters, sorts, traversals, stream reads, or lookups must be efficient? What datastore-native indexes or projections support them?"*
 
 Collect:
-- Columns used in WHERE/ORDER BY
-- Columns used in JOIN
-- Large tables that need composite indexes
-
-## schema.md Output Format
-
-````markdown
-# Database Schema
-
-## Document Role
-- **Source of Truth:** Data model and persistence contract
-- **Primary Owner:** `brainstorm-schema`
-- **Out of Scope:** Endpoint behavior, UI rules, and code-level implementation details
-
-## Global Conventions
-- **Database:** PostgreSQL / MySQL / MongoDB
-- **ID Strategy:** UUID / auto-increment
-- **Table Naming:** snake_case, plural
-- **Audit Fields:** `created_at`, `updated_at` in all tables, set by [app / DB trigger]
-- **Soft Delete:** Yes — `deleted_at` column / No — hard delete
-- **Timezone:** UTC
-- **Retention/Deletion:** [How long kept, when deleted, when anonymized/archived]
-
-## Entity Map
-| Data ID | Table | Purpose | Trace to |
-|---------|-------|---------|----------|
-| DATA-01 | `[table_name]` | [short purpose] | `FEAT-01 / BR-01` |
-| DATA-02 | `[table_name_2]` | [short purpose] | `FEAT-01 / BR-02` |
-
----
-
-## Table DATA-01: `[table_name]`
-> [Short description of the table purpose]
-> **Trace to:** [FEAT-01 / BR-01]
-> **PII:** Yes — contains personal data / No
-> **Data Protection:** [hash / encrypt / mask / none]
-> **Retention:** [How long it is stored / when archived or deleted]
-
-| Column | Type | Nullable | Default | Constraint | Notes |
-|--------|------|----------|---------|------------|-------|
-| id | UUID | No | gen_random_uuid() | PRIMARY KEY | |
-| [column] | [type] | [Yes/No] | [default] | [constraint] | [notes] |
-| created_at | TIMESTAMP | No | now() | | Auto-set |
-| updated_at | TIMESTAMP | No | now() | | Auto-update |
-| deleted_at | TIMESTAMP | Yes | null | | Soft delete |
-
-**Relationships:**
-- One-to-Many to `[other_table]` via `[foreign_key]` — on delete: CASCADE / SET NULL / RESTRICT
-
-**Indexes:**
-- `[column_name]` — used in WHERE/JOIN/ORDER BY
-
----
-
-## Table DATA-02: `[table_name_2]`
-> [Description]
-> **Trace to:** [FEAT-01 / BR-02]
-> **PII:** Yes / No
-
-| Column | Type | Nullable | Default | Constraint | Notes |
-|--------|------|----------|---------|------------|-------|
-| id | UUID | No | gen_random_uuid() | PRIMARY KEY | |
-
-**Relationships:**
-- Many-to-One to `[other_table]` via `[foreign_key]`
-
-**Indexes:**
-- `[foreign_key]` — standard FK index
-
----
-
-## Intentional Denormalization
-| Table | Denormalized Column | Reason |
-|-------|---------------------|--------|
-| [table] | [column] | [Why duplicated — for example order history] |
+- Required reads/writes and expected scale
+- Datastore-native indexes, projections, partitioning, traversal, or caching needed for those access patterns
+- Consistency and latency expectations that constrain the design
+- Schema evolution: backward/forward compatibility, migration order, backfill, validation, rollback/roll-forward, and zero-downtime constraints when migrations apply
 
-## Data Protection & Retention
-| Table/Column | Category | Protection | Retention | Notes |
-|--------------|----------|------------|-----------|-------|
-| [users.email] | PII | [encrypt/mask/plain] | [retention rule] | [notes] |
+## schema.md Output
 
-## Not Yet Modeled / Deferred
-- [Data area intentionally not yet modeled]
+After discovery is complete and immediately before generating `project-context/schema.md`, read `assets/schema.template.md`.
 
-## Assumptions & Open Questions
-- [Assumption about tables, relationships, or data rules]
-- [Question that needs user confirmation]
-````
+Adapt only sections that are applicable and preserve every required contract from the interview. Do not load the template during early discovery.
 
 ## After schema.md Is Created
 

package/.agents/skills/brainstorm-schema/assets/schema.template.md

@@ -0,0 +1,109 @@
+# Database Schema
+
+## Document Role
+- **Source of Truth:** Data model and persistence contract
+- **Primary Owner:** `brainstorm-schema`
+- **Out of Scope:** Endpoint behavior, UI rules, and code-level implementation details
+
+## Persistence Profile
+- **Model:** Relational / Document / Key-value / Graph / Event store / Mixed
+- **Identity Strategy:** [UUID / key format / aggregate ID / stream ID]
+- **Naming:** [datastore-native naming rules]
+- **Audit / Version Metadata:** [timestamps/version/event metadata]
+- **Deletion / Retention:** [soft delete / archival / tombstone / immutable event / retention policy]
+- **Timezone:** [UTC/local/N/A]
+
+## Entity / Storage Map
+| Data ID | Structure | Type | Purpose | Trace to |
+|---------|-----------|------|---------|----------|
+| DATA-01 | `[name]` | Table / Collection / Key Space / Node / Stream / Aggregate | [purpose] | `FEAT-01 / BR-01` |
+
+## Global Data Protection
+| Structure/Field | Category | Protection | Retention | Notes |
+|-----------------|----------|------------|-----------|-------|
+| [users.email] | PII | [encrypt/mask/plain] | [retention rule] | [notes] |
+
+## Scale, Tenancy & Concurrency
+- **Expected Scale/Growth:** [records, payload, growth]
+- **Tenant Isolation:** [N/A or enforcement model]
+- **Concurrency Strategy:** [transaction/version/lock/idempotency]
+
+## Schema Evolution & Migration
+- **Compatibility:** [backward/forward policy]
+- **Migration Order:** [expand/backfill/switch/contract or equivalent]
+- **Backfill & Validation:** [strategy]
+- **Failure Recovery:** [rollback or roll-forward]
+- **Zero-Downtime Constraint:** [if applicable]
+
+---
+
+## Relational Section (include only for relational or mixed)
+
+### Table DATA-01: `[table_name]`
+> **Trace to:** [FEAT-01 / BR-01]
+> **PII:** Yes / No
+> **Retention:** [policy]
+
+| Column | Type | Nullable | Default | Constraint | Notes |
+|--------|------|----------|---------|------------|-------|
+| id | UUID | No | gen_random_uuid() | PRIMARY KEY | |
+| [column] | [type] | [Yes/No] | [default] | [constraint] | [notes] |
+
+**Relationships:**
+- [One-to-many / many-to-many / delete rule]
+
+**Indexes:**
+- [column/index purpose]
+
+---
+
+## Document Section (include only for document or mixed)
+
+### Collection DATA-01: `[collection_name]`
+> **Trace to:** [FEAT-01 / BR-01]
+
+- **Root Document Shape:** [summary]
+- **Embedded vs Referenced Data:** [rule]
+- **Validation:** [required/optional fields]
+- **Indexes:** [fields and reason]
+
+---
+
+## Key-Value Section (include only for key-value or mixed)
+
+### Key Space DATA-01: `[keyspace_name]`
+> **Trace to:** [FEAT-01 / BR-01]
+
+- **Key Format:** [pattern]
+- **Value Shape:** [summary]
+- **Secondary Lookup / Cache Rule:** [if any]
+
+---
+
+## Graph Section (include only for graph or mixed)
+
+### Node / Edge DATA-01: `[node_or_edge_name]`
+> **Trace to:** [FEAT-01 / BR-01]
+
+- **Node/Edge Type:** [type]
+- **Properties:** [summary]
+- **Traversal / Cardinality Rules:** [rules]
+
+---
+
+## Event Store Section (include only for event-store or mixed)
+
+### Aggregate / Stream DATA-01: `[stream_name]`
+> **Trace to:** [FEAT-01 / BR-01]
+
+- **Aggregate Boundary:** [summary]
+- **Event Types:** [list]
+- **Projection / Read Model:** [summary]
+- **Ordering / Versioning:** [rules]
+
+## Not Yet Modeled / Deferred
+- [Data area intentionally not yet modeled]
+
+## Assumptions & Open Questions
+- [Assumption about structures, relationships, or data rules]
+- [Question that needs user confirmation]