macca-method 2.1.2 → 3.0.0-rc.1

package/.agents/skills/add-feature/SKILL.md

@@ -9,6 +9,8 @@ metadata:
 
 # Add Feature
 
+Read `../_shared/references/planning-principles.md` before impact analysis and recommendations. Add only the approved feature and necessary supporting controls, not speculative infrastructure or adjacent features. Deferred suggestions are not task authorization.
+
 ## Shared Runtime Setup
 
 Paths written as `../...` below are relative to this SKILL.md's own folder, not the project's working directory - resolve them as a sibling of the folder that contains this file.
@@ -18,7 +20,9 @@ At startup:
 1. Read `../_shared/references/language-config.md`.
 2. Read `../_shared/references/output-ownership.md`.
 3. Read `../_shared/references/scope-rules.md`.
-4. Use `languagePreferences.communication.normalized` for feature analysis and reports.
+4. Use the resolved communication language from `language-config.md` for feature analysis and reports.
+
+Follow `interaction-contract.md`, loaded automatically through `language-config.md`, for compact reports and handoff context. Reuse cached reads only when unchanged and backed by current evidence; refresh changed, stale, or uncertain applicable sections.
 
 ---
 
@@ -34,10 +38,10 @@ You are a **Product Engineer** adding features to a running project. Do not star
 
 **Workflow:**
 
-- Read all existing specs first
+- Establish fresh evidence for applicable spec sections and their material dependencies
 - Identify the impact on each document
 - Update ALL impacted specs (required)
-- Add a phase and tasks to Task.md
+- Delegate all Task.md authoring to `brainstorm-task`
 - Hand off to `developer`
 - Use a subagent for deep codebase analysis or implementation-pattern research
 
@@ -45,7 +49,7 @@ You are a **Product Engineer** adding features to a running project. Do not star
 
 ## Step 0: Get the Feature Description
 
-Ask the user:
+Reuse the supplied feature description and current approval first. On an approval reply such as "oke mari perbaiki", resume the approved bounded update without onboarding or asking for the description again. Ask only missing material information:
 
 ```
 Describe the new feature:
@@ -55,13 +59,13 @@ Describe the new feature:
 - Why it is needed: [problem it solves]
 ```
 
-If the user gives a free-form description, extract the relevant information and confirm understanding before continuing.
+If the user gives a free-form description, extract the relevant information; clarify only gaps or conflicts. Use the impact-analysis approval for confirmation rather than adding a redundant gate.
 
 ---
 
-## Step 1: Read All Existing Specs
+## Step 1: Establish Fresh Applicable Spec Context
 
-Read every existing file in `project-context/`:
+Inventory document roles, then read fresh applicable sections and dependencies from `project-context/`:
 
 - `PRD.md`
 - `architecture.md`
@@ -71,7 +75,7 @@ Read every existing file in `project-context/`:
 - `StyleGuide.md`
 - `Task.md` _(if it exists; otherwise it will be created by brainstorm-task)_
 
-Read everything that exists. Skip nothing. Note the ID patterns in use (`FEAT-*`, `BR-*`, `DATA-*`, `API-*`, etc.).
+Assess every document's applicability and potential impact, but do not indiscriminately reread unrelated text. Reuse cached reads only when unchanged and backed by current evidence; refresh affected or uncertain sections. Note the ID patterns in use (`FEAT-*`, `BR-*`, `DATA-*`, `API-*`, etc.) and existing completion evidence. Resolve scope from explicit user context or saved scope; if absent, announce the fullstack working default without persisting it as consent. Persist only user-provided scope through `config-mutation.md`, clarifying conflicts first.
 
 ---
 
@@ -104,7 +108,7 @@ Impact analysis for "[feature name]":
    New phase: Phase [N+1] — [phase name]
 ```
 
-Pause for user confirmation. If the user corrects the analysis, adjust it before continuing.
+Obtain approval of the bounded impact analysis before writing. Reuse an explicit approval already covering that same scope; pause only for a materially new decision, changed scope, or conflict. If the user corrects the analysis, adjust it before continuing.
 
 ---
 
@@ -127,7 +131,7 @@ For each **IMPACTED** document, update it in this order:
 - **Make additions clear** — place them logically; no special tags are needed
 - **Preserve old IDs** — assign new IDs for new items using the existing pattern
 
-After each update:
+After the bounded updates, report changed sections and IDs together rather than repeating a report after every file:
 
 ```
 ✅ PRD.md updated
@@ -142,9 +146,9 @@ After each update:
 
 Call `brainstorm-task` to add a phase and tasks to `Task.md`.
 
-**Do not create tasks manually.** The `brainstorm-task` skill:
+**Delegate all Task.md authoring to brainstorm-task**, whether the file exists or is missing. Do not create tasks manually, edit existing tasks, or update counts/traceability here. The `brainstorm-task` skill:
 
-- Performs deep analysis of the updated specs
+- Analyzes fresh applicable sections of the updated specs and their material dependencies
 - Ensures task dependencies are ordered correctly
 - Creates testable acceptance criteria
 - Preserves consistency with existing phases
@@ -152,7 +156,9 @@ Call `brainstorm-task` to add a phase and tasks to `Task.md`.
 Provide context:
 
 - If `Task.md` exists: "Add a new phase for this feature (do not rewrite everything)"
-- If `Task.md` does not exist: "Create Task.md from scratch using all specs"
+- If `Task.md` does not exist: "Create `project-context/Task.md` using applicable approved specs and brownfield classification; do not recreate existing verified work"
+- In both cases carry **approved scope, IDs, changed sections, evidence freshness**, current input evidence, unresolved decisions, preserved completion history, and the exact Task-authoring authorization. Include settled priority/granularity/execution preferences so the receiver asks only missing material questions.
+- The receiver validates freshness and reads affected sections and dependencies; unchanged current evidence may be reused. New decisions or conflicts return to the owner. A task-planning handoff is not implementation authorization.
 
 Reference format (informational only; `brainstorm-task` decides the actual tasks):
 
@@ -179,9 +185,9 @@ After everything is complete:
 Feature "[name]" is ready to build.
 
 Updated Specs:
-- ✅ PRD.md — [change summary]
-- ✅ schema.md — [change summary]
-- ✅ api.md — [change summary]
+- ✅ `project-context/PRD.md` — [change summary]
+- ✅ `project-context/schema.md` — [change summary]
+- ✅ `project-context/api.md` — [change summary]
 
 New Tasks:
 - Phase [N]: [name] — [number of tasks] tasks
@@ -193,9 +199,9 @@ To start building, call `developer`.
 
 ## Required Rules
 
-1. **Read all specs before impact analysis** — no assumptions
+1. **Establish fresh applicable evidence before impact analysis** — assess each document's impact, reuse unchanged current evidence, and refresh affected sections
 2. **Every impacted spec MUST be updated** — no exceptions
-3. **Get user approval after impact analysis** — before making changes
+3. **Get user approval after impact analysis** — before making changes; reuse an existing explicit approval for the same bounded scope
 4. **Preserve unrelated content** — update stale affected statements instead of appending contradictions
 5. **Update Task.md last** — via `brainstorm-task` after all specs are done
 6. **Acceptance criteria must be testable** — not vague descriptions

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

@@ -1,6 +1,6 @@
 ---
 name: brainstorm-api
-description: Interviews users and generates `api.md` for REST, GraphQL, RPC/tRPC, event-driven, or mixed contracts, including lifecycle and reliability. Use only when the user explicitly requests an API contract after applicable architecture/data decisions.
+description: Creates or updates `api.md` for REST, GraphQL, RPC/tRPC, event-driven, or mixed contracts, including lifecycle and reliability. Use after applicable architecture/data decisions for explicit API planning, targeted completion/update user intent, or an authorized owner handoff, including spec-init Missing Decisions and approved technical sync.
 compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
 metadata:
   persona: "Fachri"
@@ -43,21 +43,21 @@ Before any interview:
 2. Read `../_shared/references/config-mutation.md`.
 3. Read `../_shared/references/brainstorm-session.md`.
 4. Read `../_shared/references/scope-rules.md`.
-5. Use `languagePreferences.communication.normalized` for chat.
-6. Use `languagePreferences.documents.normalized` for the final `project-context/api.md`.
+5. Use the resolved communication language from `language-config.md` for chat.
+6. Use the resolved document language from `language-config.md` for the final `project-context/api.md`.
 7. Apply `brainstormPreferences.discussionMode`, `recommendations`, and `discoveryDepth` using the shared session policy.
 
 ---
 
 ## How to Use This Skill
 
-1. Load after the schema is complete, or right after architecture if user scope = `frontend` and the API is documented only as a consumer contract.
+1. Select the mode in `../_shared/references/brainstorm-session.md` before startup questions. Baseline-completion, targeted update, and approved technical sync take precedence over the new-document interview below. **Architecture is required; schema is required only for a persisted-data dependency in scope.** Otherwise record schema as `N/A`: a stateless provider API is valid without schema, as is a frontend consumer contract. If an applicable dependency is unresolved, route that decision to its owner rather than inventing a schema or silently bypassing it.
 
 2. **Read existing project-context**:
    - `project-context/PRD.md` — features that need endpoints
    - `project-context/architecture.md` — tech stack and API pattern (REST/GraphQL/tRPC)
-   - `project-context/schema.md` — tables and fields available for endpoints
-   - If `.agents/developer-config.json` exists, read `developerPreferences.scope`
+   - `project-context/schema.md` — read relevant entities and fields only when the API has a persisted-data dependency in scope; provider/full mode alone does not require schema
+   - Read the configured scope value from the safe preference summary under `language-config.md`
 
 3. Determine API contract mode from scope:
    - `frontend` → **consumer contract mode**
@@ -73,12 +73,16 @@ Before any interview:
 
 6. Run the interview in the chosen mode. Wait for answers.
 
-7. After all topics, create `project-context/api.md`.
-
-   > ⚠️ **If the file already exists:** "(A) Overwrite all, (B) Cancel and review first."
+7. In new-document mode, complete applicable discovery and create `project-context/api.md`. For an existing file, follow the selected bounded mode; retain evidence, confidence, IDs, unrelated unknowns, and unrelated text. Regenerate only on an explicit request with approval of the named replacement.
 
 8. Summarize the result and suggest next steps based on scope.
 
+## Domain Applicability: Smallest Sufficient Contract
+
+Apply the shared planning principles loaded by `brainstorm-session.md`. Reuse the approved architecture and one adequate existing protocol. Additional protocols/components need a current requirement, why native/existing alternatives are insufficient, implementation/operating cost, and a concrete escalation trigger. Base choices on actual consumers, expected scale, team, budget, and operations.
+
+Derive operations only from approved flows, not automatic CRUD for every entity. Do not add speculative versions, webhooks, pagination, queues, or endpoints for possible future consumers. Critical depth means deeper contract/failure questions, not more infrastructure. Use native limits, retries, and idempotency where actual abuse, duplicate effects, or delivery risks demand them; retain required authentication, authorization, validation, and recovery safeguards. Missing mandatory decisions stay unresolved rather than `N/A`.
+
 ## Interview Topics (5 Topics)
 
 Ask all five topics using the selected batch size. First determine the API style from `architecture.md`: REST, GraphQL, tRPC/RPC, event-driven, or mixed. Use protocol-neutral terms until that choice is known.
@@ -93,17 +97,17 @@ Protocol mapping:
 
 ### 1. Entry Point, Versioning, Auth & Contract Status
 
-_"What is the API entry point and protocol? How is compatibility/versioning handled? How do users authenticate? Is the contract confirmed, proposed, or mock-only?"_
+_"What existing entry point and protocol serve the approved consumers? What compatibility and access requirements apply? Is the contract confirmed, proposed, or mock-only?"_
 
 Collect:
 
 - Entry point appropriate to the selected protocol (base URL, GraphQL endpoint, RPC router, channel/broker)
-- Compatibility/versioning strategy appropriate to the protocol
-- Deprecation policy for external consumers: support window, notice channel, replacement operation, and sunset criteria
-- Authentication/identity transport appropriate to the protocol
+- Compatibility requirements; explicit versioning only where consumer lifecycle requires it
+- Deprecation policy when external consumer commitments require one: support window, notice channel, replacement operation, and sunset criteria
+- Authentication/identity transport when required by access rules
 - Does cookie/session auth need CSRF protection?
-- Token lifetime, refresh, rotation, logout behavior
-- Standard response wrapper format (for example `{ success, data, message, meta }`)
+- Token lifetime, refresh, rotation, logout behavior when the chosen auth contract uses them
+- Existing/protocol-native response shape; custom wrappers only for an approved contract need
 - Contract status by area: `confirmed`, `proposed`, `mock-only`, `backend-owned`, `pending backend confirmation`
 
 ### 2. Error Catalog
@@ -113,7 +117,7 @@ _"What is the error format for the selected protocol? For REST, which HTTP statu
 Collect:
 
 - Consistent error response structure
-- Meaning of HTTP status codes:
+- For REST, select only applicable HTTP status codes; this is a reference menu:
   - `400` Bad Request — input validation failed
   - `401` Unauthorized — not logged in / token expired
   - `403` Forbidden — logged in but lacks permission
@@ -145,7 +149,7 @@ Collect by selected protocol:
 - **GraphQL:** operation name/type, arguments, selection/result type, union/error behavior
 - **RPC/tRPC:** procedure type/name, typed input/output, typed errors
 - **Event-driven:** channel/topic, producer/consumer, payload, key/order, delivery and retry semantics
-- **All modes:** field constraints, authorization/ownership, idempotency/replay, upload/payload limits, and real examples
+- **All modes:** field constraints, applicable authorization/ownership, and real examples; idempotency/replay and upload/payload limits as actual risks require
 
 ### 5. Pagination, Filtering, Rate Limiting & Abuse Protection
 
@@ -168,15 +172,12 @@ Adapt only sections that are applicable and preserve every required contract fro
 ## After api.md Is Created
 
 1. Confirm the file was created successfully
-2. Ask about UI/style guide:
-   - _"Does this project have a UI? Define a style guide?"_
-   - If yes and scope includes frontend/UI: `brainstorm-styleguide` → `brainstorm-rules` → `brainstorm-task`
-   - If no: `brainstorm-rules` → `brainstorm-task`
+2. Reuse known UI applicability; ask only if unresolved. Recommend one next step using `brainstorm-session.md`: applicable unfinished StyleGuide, then rules after all applicable inputs, then tasks. For bounded updates, return approved scope, IDs, changed sections, and evidence freshness to the caller.
 
 ## Important Notes
 
 - **Error Catalog (topic 2) and security/abuse protection (topic 5)** are often skipped. Do not skip them.
 - Ask by resource, not all endpoints at once.
-- Always ask for real JSON examples. AI infers structure from examples.
-- If the user is unclear, suggest standard CRUD endpoints from `schema.md`.
+- Ask for real protocol-native examples where they clarify the contract; do not impose JSON on every protocol.
+- If the user is unclear and recommendations are enabled, suggest operations from approved requirements and applicable evidence. Use `schema.md` only for persisted-data dependencies; do not invent CRUD or persistence for a stateless API.
 - Render the final document in the configured document language

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

@@ -1,5 +1,7 @@
 # API Documentation
 
+> **Authoring note:** This is a placeholder menu, not a checklist to build. Keep only contracts required by approved current flows and security/recovery obligations; prune inapplicable sections or mark `N/A` with a reason. Unknown mandatory decisions remain open, not `N/A`. Reuse the approved architecture and one adequate existing protocol. No automatic CRUD, versioning, webhooks, pagination, queues, or future-consumer endpoints. New components need a current requirement, why native/existing options are insufficient, cost within scale/team/budget/operations constraints, and a concrete escalation trigger. Critical depth deepens questions; native limits, retries, and idempotency apply where actual risk demands them.
+
 ## Document Role
 
 - **Source of Truth:** External API or integration contract for this project
@@ -22,14 +24,14 @@
 
 - **Style:** REST / GraphQL / RPC-tRPC / Event-driven / Mixed
 - **Entry Point:** [base URL / endpoint / router / broker/topic namespace]
-- **Versioning:** [strategy and current version]
-- **Deprecation:** [notice channel, support window, replacement, sunset criteria]
+- **Compatibility / Versioning:** [actual consumer commitments; explicit versions only if needed]
+- **Deprecation:** [notice/support/replacement/sunset only when consumer commitments require them]
 
 ## Authentication and Security Controls
 
 - **Authentication:** [method and transport]
 - **Authorization:** [role/ownership summary]
-- **Sensitive Operations:** [login / password reset / upload / webhook / payment / admin actions]
+- **Sensitive Operations:** [actual approved operations requiring protection]
 - **CSRF / Replay / Signature / Idempotency:** [applicable controls]
 - **Rate / Concurrency Limits:** [limit and client-visible signals]
 
@@ -41,7 +43,7 @@
 
 ## Reliability and SLO
 
-- **Latency Target:** [p95/p99 or N/A]
+- **Latency Target:** [approved relevant NFR; unknown required target remains an open decision]
 - **Availability/Error Target:** [target or inherited NFR]
 - **Timeout Ownership:** [client/server/gateway/consumer]
 - **Retry Policy:** [which failures, backoff, max attempts]
@@ -61,27 +63,13 @@
 
 | Environment | Base URL                            |
 | ----------- | ----------------------------------- |
-| Development | `http://localhost:3000/api/v1`      |
-| Staging     | `https://staging-api.domain.com/v1` |
-| Production  | `https://api.domain.com/v1`         |
+| [Actual environment] | [Existing/approved base URL; no presumed /v1] |
 
 ### Standard Response Format
 
-```json
-{
-  "success": true,
-  "data": {},
-  "message": "string (optional)",
-  "meta": {
-    "page": 1,
-    "limit": 20,
-    "total": 100,
-    "hasNext": true
-  }
-}
-```
-
-### Pagination and Filtering
+[Actual existing/protocol-native response example. Add an envelope or pagination metadata only when the approved contract requires it.]
+
+### Pagination and Filtering (Only When Required by Access Patterns)
 
 - **Type:** Offset-based / Cursor-based
 - **Defaults:** [limit/page or cursor rules]
@@ -107,7 +95,7 @@
 
 ### Endpoint and Transport
 
-- **Endpoint:** `/graphql`
+- **Endpoint:** [existing/approved endpoint]
 - **Realtime:** Subscriptions / polling / none
 
 ### Operation: [Query / Mutation / Subscription Name]

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

@@ -1,6 +1,6 @@
 ---
 name: brainstorm-architecture
-description: Interviews users and generates `architecture.md` with stack, boundaries, operations, observability, recovery, security, and ADRs. Use only when the user explicitly wants architecture decisions documented after the PRD.
+description: Creates or updates `architecture.md` with stack, boundaries, operations, observability, recovery, security, and ADRs. Use after applicable PRD decisions for explicit architecture planning, targeted completion/update user intent, or an authorized owner handoff, including spec-init Missing Decisions and approved technical sync.
 compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
 metadata:
   persona: "Fachri"
@@ -27,9 +27,9 @@ You are **@Fachri — Tech Lead**, a **Senior Software Architect** who designs s
 - Cloud infrastructure, CI/CD, deployment strategies
 - Architecture Decision Records (ADR) to document decisions and their rationale
 
-**Mindset:** Architecture is about trade-offs, not perfection. Every decision must be defensible. Think long term: code that is easy today can become tomorrow's technical debt.
+**Mindset:** Architecture is about trade-offs, not perfection. Meet approved current needs and preserve mature decisions; record evidence-based escalation triggers instead of building for hypothetical demand.
 
-**Priority:** Maintainability → security → scalability → simplicity (YAGNI).
+**Priority:** Security and correctness → smallest sufficient design → maintainability → scaling justified by expected demand.
 
 ---
 
@@ -43,20 +43,20 @@ Before any interview:
 2. Read `../_shared/references/config-mutation.md`.
 3. Read `../_shared/references/brainstorm-session.md`.
 4. Read `../_shared/references/scope-rules.md`.
-5. Use `languagePreferences.communication.normalized` for chat.
-6. Use `languagePreferences.documents.normalized` for the final `project-context/architecture.md`.
+5. Use the resolved communication language from `language-config.md` for chat.
+6. Use the resolved document language from `language-config.md` for the final `project-context/architecture.md`.
 7. Apply `brainstormPreferences.discussionMode`, `recommendations`, and `discoveryDepth` using the shared session policy.
 
 ---
 
 ## How to Use This Skill
 
-1. Load after `PRD.md` is complete.
+1. Select the mode in `../_shared/references/brainstorm-session.md` before startup questions. Baseline-completion, targeted update, and approved technical sync take precedence over the new-document interview below. New architecture planning follows usable PRD decisions; bounded work needs only its applicable inputs.
 
 2. **Read existing project-context**:
    - `project-context/PRD.md` — features, users, constraints
 
-3. If `.agents/developer-config.json` exists, read `developerPreferences.scope`.
+3. Read the configured scope value from the safe preference summary under `language-config.md`.
    - `frontend` → architecture.md MUST focus on frontend architecture and backend/API dependencies only
    - `backend` → architecture.md MUST focus on backend architecture, service/data/auth, and consumer dependencies only
    - `fullstack` → full architecture.md
@@ -65,12 +65,16 @@ Before any interview:
 
 5. Run the interview in the chosen mode. Wait for answers.
 
-6. After all topics, create `project-context/architecture.md`.
-
-   > ⚠️ **If the file already exists:** "(A) Overwrite all, (B) Cancel and review first."
+6. In new-document mode, complete applicable discovery and create `project-context/architecture.md`. For an existing file, follow the selected bounded mode; retain evidence, confidence, IDs, unrelated unknowns, and unrelated text. Regenerate only on an explicit request with approval of the named replacement.
 
 7. Summarize the result and suggest next steps.
 
+## Domain Applicability: Smallest Sufficient Architecture
+
+Apply the shared planning principles loaded by `brainstorm-session.md`. Ground decisions in approved requirements, security/recovery obligations, expected scale, team capacity, budget, and operational constraints. Prefer native capabilities and the existing approved architecture; do not rewrite a mature system merely to label it simpler. A new component needs a current requirement, evidence that simpler options are insufficient, its implementation/operating cost, and a concrete future escalation trigger. No topology or technology is universally required or prohibited.
+
+Critical depth means deeper questions about risks and failure behavior, not automatically more components. Controller/service/repository layers and dependency injection are optional tools for demonstrated boundaries. Start state handling with native/existing facilities; add auth only where access requirements demand it. Preserve required security safeguards and recovery behavior regardless of component count.
+
 ## Interview Topics (10 Topics)
 
 Ask the topics in order and wait after each selected batch, not after every topic when batching is enabled.
@@ -81,23 +85,21 @@ _"What systems and external services interact with this project?"_
 
 Collect:
 
-- System users (end users, admins, etc.)
-- External services (payments, email, SMS, maps, OAuth)
+- Actual users from approved requirements
+- Existing external services and integrations required by approved flows
 - Internal system connections
 - Incoming/outgoing data flows
 
 ### 2. Tech Stack
 
-_"What is the tech stack: frontend, backend, database, hosting, CI/CD?"_
+_"What must the system do, what already runs it, and what scale, team, budget, or operational limits constrain the choices?"_
 
 Collect:
 
-- Frontend: framework & version
-- Backend: language, framework & version
-- Database: type & version
-- ORM/ODM
-- Hosting platform
-- Specific versions (for example Next.js 14 App Router, React 18)
+- Existing languages, runtime/framework versions, persistence and hosting where applicable
+- Approved needs not met by the current stack or native capabilities
+- Expected workload, team skills/capacity, budget, and operational ownership
+- Additional libraries or tooling only when a demonstrated gap justifies them
 - For each strategic dependency/vendor: existing/native alternative, runtime compatibility, maintenance health, license, security advisories, operational cost, lock-in, migration path, and removal/exit path
 
 ### 3. State Management
@@ -106,51 +108,47 @@ _"If there is a frontend, how is state managed?"_
 
 Collect:
 
-- Client state: Redux, Zustand, Jotai, Recoil, Context API
-- Server state: React Query, SWR, or built-in
-- Form state: React Hook Form, Formik, or native
-- State persistence (localStorage, sessionStorage)?
+- Client, server, and form state actually needed by approved flows
+- Native/framework/existing facilities first; additional state libraries only for demonstrated limitations
+- Persistence only for a required state lifetime, with sensitive-data protection
 
 ### 4. API Design
 
-_"How does frontend-backend communication work: REST, GraphQL, tRPC, or something else?"_
+_"Which interactions cross system boundaries, and can the existing communication contract satisfy them?"_
 
 Collect:
 
-- API pattern (REST, GraphQL, tRPC, or a combination)
-- Real-time needs? (WebSocket, SSE, long polling)
-- Microservice communication?
+- One adequate existing protocol; additional protocols only for justified requirements
+- Required latency/delivery behavior; real-time or inter-service communication only where needed
 
 ### 5. Folder Structure
 
-_"What folder structure do you want: framework default or custom?"_
+_"What structure already exists, and do actual responsibilities require any changes?"_
 
 Collect:
 
-- Framework default or custom approach
-- Feature-based (by feature) or layer-based (controller/service/model)
+- Existing/framework-native structure first
+- Additional folders or layers only for demonstrated responsibilities
 - Any reference structure
 
 ### 6. Design Pattern
 
-_"What architecture pattern do you want: MVC, Clean Architecture, modular, or something else?"_
+_"Which responsibilities need separate boundaries, and how does the existing structure support them?"_
 
 Collect:
 
-- Main pattern (MVC, Feature-based, Clean Architecture, Hexagonal)
-- Separation of concerns (routes → controller → service → repository)
-- Dependency injection approach
+- Existing approved pattern and boundaries required by actual responsibilities
+- Additional layers or dependency injection only where their benefit exceeds their cost
 
 ### 7. Authentication & Authorization
 
-_"What auth method is used: JWT, session, OAuth? How are roles and permissions enforced?"_
+_"Does any approved flow need identity or restricted access? If so, how does the existing platform authenticate and enforce access?"_
 
 Collect:
 
-- Authentication (JWT, Session cookies, OAuth2)
-- Provider (Google, GitHub, custom)
-- RBAC (Role-Based Access Control)?
-- Token storage (recommended httpOnly cookie vs localStorage)
+- Required identity, ownership, and permission checks; roles only if required
+- Existing authentication/provider facilities and secure credential/session lifecycle
+- Storage and transport safeguards appropriate to the platform and threat model
 
 ### 8. Security & Abuse Cases
 
@@ -170,7 +168,7 @@ _"Where will this run? Are staging and production separate?"_
 
 Collect:
 
-- Hosting platform (Vercel, Railway, Fly.io, Docker+VPS, AWS, GCP)
+- Existing hosting/runtime or smallest sufficient deployment supported by current constraints
 - Environment separation (dev, staging, prod)?
 - CI/CD strategy
 - Domain and SSL
@@ -178,7 +176,7 @@ Collect:
 - Operational owner, support/runbook expectations, and capacity constraints
 - Logs, metrics, traces, dashboards, alert thresholds, and retention required by PRD success/NFR targets
 - Deployment rollback trigger, mechanism, validation, and data compatibility
-- For critical depth: backup/restore ownership, tested restore process, RPO, RTO, and regional/dependency failure behavior
+- Recovery obligations at every depth; at critical depth probe backup/restore ownership, tested restore process, required RPO/RTO, and applicable regional/dependency failures more deeply
 
 ### 10. Architecture Decision Records (ADR)
 
@@ -186,7 +184,7 @@ _"Are there key architecture decisions whose rationale should be documented?"_
 
 Collect:
 
-- Non-obvious decisions (why PostgreSQL vs MongoDB)
+- Non-obvious decisions and the current requirement each serves
 - Structural decisions with hidden rationale
 - Trade-offs considered
 - Revisit/exit trigger for strategic libraries and vendors
@@ -201,12 +199,7 @@ Adapt only sections that are applicable and preserve every required contract fro
 ## After architecture.md Is Created
 
 1. Confirm the file was created successfully
-2. Suggest the next workflow:
-   1. **`brainstorm-schema`** ← database design next (only if scope includes backend/data)
-   2. `brainstorm-api` → endpoints after schema, or consumer contract for frontend
-   3. `brainstorm-styleguide` → optional if scope includes UI
-   4. `brainstorm-rules` → coding standards
-   5. `brainstorm-task` → work plan
+2. Recommend one next step using the applicability-aware priority in `brainstorm-session.md`: schema for in-scope persistence, otherwise API if exposed/consumed, then in-scope UI, then rules after all applicable inputs, then tasks. A stateless provider API does not require schema. For bounded updates, return approved scope, IDs, changed sections, and evidence freshness to the caller.
 
 ## Important Notes
 

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

@@ -1,5 +1,7 @@
 # Architecture
 
+> **Authoring note:** This is a placeholder menu, not a checklist to build. Keep only sections justified by approved current requirements and security/recovery obligations; prune inapplicable sections or mark `N/A` with a reason. Unknown mandatory decisions remain open, not `N/A`. Reuse mature approved architecture and native/existing capabilities. Critical depth adds questions, not components. New components need a current requirement, why simpler options are insufficient, cost within scale/team/budget/operations constraints, and a concrete future escalation trigger; no topology or technology is mandatory by default.
+
 > **Version:** 1.0 | **Date:** [date]
 
 ## Document Role
@@ -23,7 +25,7 @@
 
 ## 1. System Context
 
-**Users:** [End Users, Admins, etc.]
+**Users:** [Actual users from approved requirements]
 
 **External Services:**
 
@@ -41,18 +43,24 @@
 | ORM      | [ORM]       | [Version] | [Notes] |
 | Language | [Language]  | [Version] | [Notes] |
 
+Include only layers actually needed; an ORM or separate frontend/backend is not presumed.
+
+**Constraints:** [expected workload, team capacity, budget, operational ownership]
+
 ### Strategic Dependency Evaluation
 
 | Dependency/Vendor | Why Needed | Native/Existing Alternative | License & Health | Lock-in / Exit Path | Decision            |
 | ----------------- | ---------- | --------------------------- | ---------------- | ------------------- | ------------------- |
 | [name]            | [reason]   | [alternative]               | [evidence]       | [migration/removal] | Accepted / Proposed |
 
+For each new component, record the approved requirement, evidence that native/existing options are insufficient, implementation/operating cost, and future escalation trigger.
+
 ## 3. State Management
 
-- **Client State:** [Zustand / Redux / Context API]
-- **Server State:** [TanStack Query / SWR]
-- **Forms:** [React Hook Form / Formik]
-- **Persistence:** [localStorage / sessionStorage / none]
+- **Client State:** [needed state and native/existing mechanism]
+- **Server State:** [needed synchronization and native/existing mechanism]
+- **Forms:** [needed behavior and native/existing mechanism]
+- **Persistence:** [required lifetime and safe storage, only if needed]
 
 ## 4. API Design
 
@@ -73,17 +81,16 @@
 
 ## 6. Design Pattern
 
-- **Main Pattern:** MVC / Feature-based / Clean Architecture
-- **Layers:** routes → controller → service → repository
+- **Main Pattern:** [existing approved pattern or justified minimal structure]
+- **Boundaries:** [actual responsibilities; controller/service/repository layers and DI only if justified]
 - **Notes:** [Special rules]
 
 ## 7. Authentication & Authorization
 
-- **Method:** JWT / Session / OAuth
-- **Provider:** Google / GitHub / Custom
-- **Token Storage:** httpOnly cookie
-- **RBAC:** Yes / No
-- **Roles:** [List with access levels]
+- **Access Requirement:** [approved restricted actions/data, or N/A with reason]
+- **Method / Provider:** [existing/native mechanism if required]
+- **Credential / Session Protection:** [platform-appropriate storage, transport, and lifecycle]
+- **Authorization:** [required ownership/permission checks; roles only if needed]
 
 ## 8. Security & Abuse Cases
 
@@ -97,10 +104,10 @@
 
 ## 9. Deployment & Infrastructure
 
-- **Platform:** Vercel / Railway / Docker+VPS / etc.
-- **Environments:** development → staging → production
-- **CI/CD:** GitHub Actions / etc.
-- **CDN/Storage:** Cloudflare / S3 / etc.
+- **Platform:** [existing or justified runtime/hosting]
+- **Environments:** [only those needed for approved delivery and recovery]
+- **CI/CD:** [existing or justified delivery mechanism]
+- **CDN/Storage:** [only if required, with justification]
 - **Domain:** [Planned domain]
 
 ### Operations & Observability
@@ -140,6 +147,7 @@
 - **Rationale:** [Why this option]
 - **Trade-off:** [Accepted downside]
 - **Rejected Alternatives:** [What else was considered and why it was rejected]
+- **Cost / Escalation Trigger:** [implementation/operations burden and evidence threshold for a more complex design]
 
 ---