macca-method 2.0.0 → 2.1.2

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

@@ -1,27 +1,32 @@
 # API Documentation
 
 ## Document Role
+
 - **Source of Truth:** External API or integration contract for this project
 - **Primary Owner:** `brainstorm-api`
 - **Out of Scope:** Internal service architecture, DB migration details, and UI copy
 
 ## Scope Summary
-| Area | Status | Notes |
-|------|--------|-------|
+
+| Area                | Status                       | Notes        |
+| ------------------- | ---------------------------- | ------------ |
 | [resource / module] | Covered / Planned / Deferred | [short note] |
 
 ## Canonical Terminology
-| Term | Meaning |
-|------|---------|
+
+| Term   | Meaning                                   |
+| ------ | ----------------------------------------- |
 | [term] | [exact meaning used in this API contract] |
 
 ## Protocol Profile
+
 - **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]
 
 ## Authentication and Security Controls
+
 - **Authentication:** [method and transport]
 - **Authorization:** [role/ownership summary]
 - **Sensitive Operations:** [login / password reset / upload / webhook / payment / admin actions]
@@ -29,11 +34,13 @@
 - **Rate / Concurrency Limits:** [limit and client-visible signals]
 
 ## Error Catalog
-| Protocol Code | Internal Code | Meaning | Retryable | Client Action |
-|---------------|---------------|---------|-----------|---------------|
-| [400 / UNAUTHENTICATED / EVENT_RETRY / etc.] | `[CODE]` | [meaning] | Yes / No | [action] |
+
+| Protocol Code                                | Internal Code | Meaning   | Retryable | Client Action |
+| -------------------------------------------- | ------------- | --------- | --------- | ------------- |
+| [400 / UNAUTHENTICATED / EVENT_RETRY / etc.] | `[CODE]`      | [meaning] | Yes / No  | [action]      |
 
 ## Reliability and SLO
+
 - **Latency Target:** [p95/p99 or N/A]
 - **Availability/Error Target:** [target or inherited NFR]
 - **Timeout Ownership:** [client/server/gateway/consumer]
@@ -41,22 +48,25 @@
 - **Contract Test Invariants:** [critical examples/compatibility rules]
 
 ## Operation Inventory
-| ID | Operation Type | Name / Path / Topic | Auth | Trace to |
-|----|----------------|---------------------|------|----------|
-| API-01 | [REST GET / GraphQL query / RPC procedure / Event publish] | [identifier] | Required / Public | `FEAT-01` |
+
+| ID     | Operation Type                                             | Name / Path / Topic | Auth              | Trace to  |
+| ------ | ---------------------------------------------------------- | ------------------- | ----------------- | --------- |
+| API-01 | [REST GET / GraphQL query / RPC procedure / Event publish] | [identifier]        | Required / Public | `FEAT-01` |
 
 ---
 
 ## REST Section (include only for REST or Mixed)
 
 ### Environments
-| Environment | Base URL |
-|-------------|----------|
-| Development | `http://localhost:3000/api/v1` |
-| Staging | `https://staging-api.domain.com/v1` |
-| Production | `https://api.domain.com/v1` |
+
+| Environment | Base URL                            |
+| ----------- | ----------------------------------- |
+| Development | `http://localhost:3000/api/v1`      |
+| Staging     | `https://staging-api.domain.com/v1` |
+| Production  | `https://api.domain.com/v1`         |
 
 ### Standard Response Format
+
 ```json
 {
   "success": true,
@@ -72,14 +82,17 @@
 ```
 
 ### Pagination and Filtering
+
 - **Type:** Offset-based / Cursor-based
 - **Defaults:** [limit/page or cursor rules]
 - **Sorting/Filtering:** [query parameters]
 
 ### Resource: [Resource Name]
+
 **Trace to:** [FEAT-01 / AC-01]
 
 #### API-01 — [METHOD] /[path]
+
 - **Description:** [what it does]
 - **Auth:** [Required / Public]
 - **Authorization:** [rule]
@@ -93,10 +106,12 @@
 ## GraphQL Section (include only for GraphQL or Mixed)
 
 ### Endpoint and Transport
+
 - **Endpoint:** `/graphql`
 - **Realtime:** Subscriptions / polling / none
 
 ### Operation: [Query / Mutation / Subscription Name]
+
 **Trace to:** [FEAT-01 / AC-01]
 
 - **Type:** Query / Mutation / Subscription
@@ -111,9 +126,11 @@
 ## RPC / tRPC Section (include only for RPC or Mixed)
 
 ### Router / Namespace
+
 - **Entry Point:** [router/namespace]
 
 ### Procedure: [Name]
+
 **Trace to:** [FEAT-01 / AC-01]
 
 - **Type:** Query / Mutation / Subscription / Procedure
@@ -128,10 +145,12 @@
 ## Event-Driven Section (include only for Event-driven or Mixed)
 
 ### Channel Topology
+
 - **Broker / Bus:** [service]
 - **Topics / Streams / Queues:** [list]
 
 ### Event Contract: [Topic / Event Name]
+
 **Trace to:** [FEAT-01 / AC-01]
 
 - **Producer:** [service/component]
@@ -143,5 +162,6 @@
 - **Security / Signature / Replay:** [controls]
 
 ## Assumptions & Open Questions
+
 - [Unresolved API assumption or question]
 - [Decision still pending confirmation]

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

@@ -20,6 +20,7 @@ Run as `@Fachri` (Tech Lead). Use the shared persona profile in `../_shared/refe
 You are **@Fachri — Tech Lead**, a **Senior Software Architect** who designs scalable, maintainable, secure systems.
 
 **Expertise:**
+
 - System design and tech stack selection for the project
 - Design patterns (MVC, Clean Architecture, Feature-based, Hexagonal)
 - Architecture-level scalability, reliability, and security
@@ -34,15 +35,17 @@ You are **@Fachri — Tech Lead**, a **Senior Software Architect** who designs s
 
 ## 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.
+
 Before any interview:
 
 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/architecture.md`.
-6. Apply `brainstormPreferences.discussionMode`, `recommendations`, and `discoveryDepth` using the shared session policy.
+5. Use `languagePreferences.communication.normalized` for chat.
+6. Use `languagePreferences.documents.normalized` for the final `project-context/architecture.md`.
+7. Apply `brainstormPreferences.discussionMode`, `recommendations`, and `discoveryDepth` using the shared session policy.
 
 ---
 
@@ -51,12 +54,12 @@ Before any interview:
 1. Load after `PRD.md` is complete.
 
 2. **Read existing project-context**:
-    - `project-context/PRD.md` — features, users, constraints
+   - `project-context/PRD.md` — features, users, constraints
 
 3. If `.agents/developer-config.json` exists, read `developerPreferences.scope`.
-    - `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
+   - `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
 
 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.
 
@@ -73,18 +76,22 @@ Before any interview:
 Ask the topics in order and wait after each selected batch, not after every topic when batching is enabled.
 
 ### 1. System Context
-*"What systems and external services interact with this project?"*
+
+_"What systems and external services interact with this project?"_
 
 Collect:
+
 - System users (end users, admins, etc.)
 - External services (payments, email, SMS, maps, OAuth)
 - Internal system connections
 - Incoming/outgoing data flows
 
 ### 2. Tech Stack
-*"What is the tech stack: frontend, backend, database, hosting, CI/CD?"*
+
+_"What is the tech stack: frontend, backend, database, hosting, CI/CD?"_
 
 Collect:
+
 - Frontend: framework & version
 - Backend: language, framework & version
 - Database: type & version
@@ -94,51 +101,63 @@ Collect:
 - 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
-*"If there is a frontend, how is state managed?"*
+
+_"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)?
 
 ### 4. API Design
-*"How does frontend-backend communication work: REST, GraphQL, tRPC, or something else?"*
+
+_"How does frontend-backend communication work: REST, GraphQL, tRPC, or something else?"_
 
 Collect:
+
 - API pattern (REST, GraphQL, tRPC, or a combination)
 - Real-time needs? (WebSocket, SSE, long polling)
 - Microservice communication?
 
 ### 5. Folder Structure
-*"What folder structure do you want: framework default or custom?"*
+
+_"What folder structure do you want: framework default or custom?"_
 
 Collect:
+
 - Framework default or custom approach
 - Feature-based (by feature) or layer-based (controller/service/model)
 - Any reference structure
 
 ### 6. Design Pattern
-*"What architecture pattern do you want: MVC, Clean Architecture, modular, or something else?"*
+
+_"What architecture pattern do you want: MVC, Clean Architecture, modular, or something else?"_
 
 Collect:
+
 - Main pattern (MVC, Feature-based, Clean Architecture, Hexagonal)
 - Separation of concerns (routes → controller → service → repository)
 - Dependency injection approach
 
 ### 7. Authentication & Authorization
-*"What auth method is used: JWT, session, OAuth? How are roles and permissions enforced?"*
+
+_"What auth method is used: JWT, session, OAuth? How are roles and permissions enforced?"_
 
 Collect:
+
 - Authentication (JWT, Session cookies, OAuth2)
 - Provider (Google, GitHub, custom)
 - RBAC (Role-Based Access Control)?
 - Token storage (recommended httpOnly cookie vs localStorage)
 
 ### 8. Security & Abuse Cases
-*"What data is sensitive, and what attacks must the architecture prevent?"*
+
+_"What data is sensitive, and what attacks must the architecture prevent?"_
 
 Collect:
+
 - Sensitive data types (PII, tokens, payment data, documents)
 - Critical actions (login, password reset, payment, file upload, admin actions)
 - Abuse scenarios: brute force, spam, IDOR, privilege escalation, CSRF, replay, webhook forgery, file abuse
@@ -146,9 +165,11 @@ Collect:
 - Audit log requirements
 
 ### 9. Deployment & Infrastructure
-*"Where will this run? Are staging and production separate?"*
+
+_"Where will this run? Are staging and production separate?"_
 
 Collect:
+
 - Hosting platform (Vercel, Railway, Fly.io, Docker+VPS, AWS, GCP)
 - Environment separation (dev, staging, prod)?
 - CI/CD strategy
@@ -160,9 +181,11 @@ Collect:
 - For critical depth: backup/restore ownership, tested restore process, RPO, RTO, and regional/dependency failure behavior
 
 ### 10. Architecture Decision Records (ADR)
-*"Are there key architecture decisions whose rationale should be documented?"*
+
+_"Are there key architecture decisions whose rationale should be documented?"_
 
 Collect:
+
 - Non-obvious decisions (why PostgreSQL vs MongoDB)
 - Structural decisions with hidden rationale
 - Trade-offs considered
@@ -193,5 +216,4 @@ Adapt only sections that are applicable and preserve every required contract fro
 - Use the strategic dependency checklist only for architecture-level choices; local packages remain a `developer` decision.
 - Render the final document in the configured document language
 
-
 ---

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

@@ -3,19 +3,21 @@
 > **Version:** 1.0 | **Date:** [date]
 
 ## Document Role
+
 - **Source of Truth:** System design, technical constraints, and architecture decisions
 - **Primary Owner:** `brainstorm-architecture`
 - **Out of Scope:** Detailed API payload schemas, per-table database columns, UI design tokens, and task sequencing
 
 ## System Boundaries
-| Topic | Canonical Document |
-|-------|--------------------|
-| Product scope and business intent | `project-context/PRD.md` |
-| Data model and field-level contracts | `project-context/schema.md` |
-| Endpoint contracts and error payloads | `project-context/api.md` |
-| UI language and component styling | `project-context/StyleGuide.md` |
-| Coding standards and AI behavior | `project-context/rules.md` |
-| Execution order and implementation plan | `project-context/Task.md` |
+
+| Topic                                   | Canonical Document              |
+| --------------------------------------- | ------------------------------- |
+| Product scope and business intent       | `project-context/PRD.md`        |
+| Data model and field-level contracts    | `project-context/schema.md`     |
+| Endpoint contracts and error payloads   | `project-context/api.md`        |
+| UI language and component styling       | `project-context/StyleGuide.md` |
+| Coding standards and AI behavior        | `project-context/rules.md`      |
+| Execution order and implementation plan | `project-context/Task.md`       |
 
 ---
 
@@ -24,36 +26,42 @@
 **Users:** [End Users, Admins, etc.]
 
 **External Services:**
-| Service | Purpose | Protocol |
-|---------|---------|----------|
+
+| Service   | Purpose   | Protocol           |
+| --------- | --------- | ------------------ |
 | [Service] | [Purpose] | REST / SDK / OAuth |
 
 ## 2. Tech Stack
-| Layer | Technology | Version | Notes |
-|-------|------------|---------|-------|
+
+| Layer    | Technology  | Version   | Notes   |
+| -------- | ----------- | --------- | ------- |
 | Frontend | [Framework] | [Version] | [Notes] |
-| Backend | [Framework] | [Version] | [Notes] |
-| Database | [Database] | [Version] | [Notes] |
-| ORM | [ORM] | [Version] | [Notes] |
-| Language | [Language] | [Version] | [Notes] |
+| Backend  | [Framework] | [Version] | [Notes] |
+| Database | [Database]  | [Version] | [Notes] |
+| ORM      | [ORM]       | [Version] | [Notes] |
+| Language | [Language]  | [Version] | [Notes] |
 
 ### 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 |
+
+| Dependency/Vendor | Why Needed | Native/Existing Alternative | License & Health | Lock-in / Exit Path | Decision            |
+| ----------------- | ---------- | --------------------------- | ---------------- | ------------------- | ------------------- |
+| [name]            | [reason]   | [alternative]               | [evidence]       | [migration/removal] | Accepted / Proposed |
 
 ## 3. State Management
+
 - **Client State:** [Zustand / Redux / Context API]
 - **Server State:** [TanStack Query / SWR]
 - **Forms:** [React Hook Form / Formik]
 - **Persistence:** [localStorage / sessionStorage / none]
 
 ## 4. API Design
+
 - **Type:** REST / GraphQL / tRPC / Event-driven / Mixed
 - **Primary Entry Point:** [base path / endpoint / router / broker namespace]
 - **Realtime / Delivery:** WebSocket / SSE / queue / stream / none
 
 ## 5. Folder Structure
+
 ```
 [Project Root]
 ├── [folder 1]/         # [description]
@@ -64,11 +72,13 @@
 ```
 
 ## 6. Design Pattern
+
 - **Main Pattern:** MVC / Feature-based / Clean Architecture
 - **Layers:** routes → controller → service → repository
 - **Notes:** [Special rules]
 
 ## 7. Authentication & Authorization
+
 - **Method:** JWT / Session / OAuth
 - **Provider:** Google / GitHub / Custom
 - **Token Storage:** httpOnly cookie
@@ -76,15 +86,17 @@
 - **Roles:** [List with access levels]
 
 ## 8. Security & Abuse Cases
+
 - **Sensitive Data:** [PII, tokens, payment data, etc.]
 - **Critical Actions:** [Login, password reset, admin actions, upload, payment, etc.]
 - **Abuse Cases:**
-   - [Brute force, spam, IDOR, CSRF, privilege escalation, replay, upload abuse, etc.]
+  - [Brute force, spam, IDOR, CSRF, privilege escalation, replay, upload abuse, etc.]
 - **Required Controls:**
-   - [Rate limiting, ownership checks, CSRF protection, audit logs, signed webhooks, secure session expiry]
+  - [Rate limiting, ownership checks, CSRF protection, audit logs, signed webhooks, secure session expiry]
 - **Audit Logs:** [Which events must be recorded]
 
 ## 9. Deployment & Infrastructure
+
 - **Platform:** Vercel / Railway / Docker+VPS / etc.
 - **Environments:** development → staging → production
 - **CI/CD:** GitHub Actions / etc.
@@ -92,6 +104,7 @@
 - **Domain:** [Planned domain]
 
 ### Operations & Observability
+
 - **Operational Owner:** [team/role]
 - **Runbook / Support:** [location and escalation]
 - **Logs:** [events, redaction, retention]
@@ -99,6 +112,7 @@
 - **Alerts:** [threshold, owner, escalation]
 
 ### Rollback and Recovery
+
 - **Rollback Trigger:** [condition]
 - **Rollback Mechanism:** [deployment/data strategy]
 - **Post-Rollback Validation:** [checks]
@@ -106,18 +120,21 @@
 - **RPO / RTO:** [critical systems only]
 
 ## 10. Canonical Terminology
-| Term | Definition |
-|------|------------|
+
+| Term   | Definition                          |
+| ------ | ----------------------------------- |
 | [Term] | [Definition in the project context] |
 
 ## 11. Architecture Decision Records (ADR)
 
 ### ADR Index
-| ADR ID | Title | Status | Summary |
-|--------|-------|--------|---------|
+
+| ADR ID  | Title   | Status              | Summary           |
+| ------- | ------- | ------------------- | ----------------- |
 | ADR-001 | [Title] | Accepted / Proposed | [One-line reason] |
 
 ### ADR-001: [Title]
+
 - **Context:** [Situation that led to the decision]
 - **Decision:** [What was decided]
 - **Rationale:** [Why this option]
@@ -129,7 +146,9 @@
 ## 12. Assumptions & Open Questions
 
 ### Assumptions
+
 - [Assumption the architecture depends on]
 
 ### Open Questions
+
 - [Question that is still unresolved]