macca-method 1.1.0 → 2.0.0

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

@@ -1,8 +1,10 @@
 ---
 name: brainstorm-architecture
-description: Interview users and generate `architecture.md` (System Architecture). Use after `PRD.md` is complete to define the tech stack, structure, and architecture decisions.
-persona: "Fachri"
-persona_role: "Tech Lead"
+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.
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
+metadata:
+  persona: "Fachri"
+  persona-role: "Tech Lead"
 ---
 
 # Brainstorm Architecture
@@ -34,12 +36,13 @@ You are **@Fachri — Tech Lead**, a **Senior Software Architect** who designs s
 
 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/architecture.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.
 
 ---
 
@@ -55,7 +58,7 @@ Before any interview:
     - `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. For this skill, ask whether to cover the 10 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.
 
@@ -67,7 +70,7 @@ Before any interview:
 
 ## Interview Topics (10 Topics)
 
-Ask the topics in order. Wait for the answer before moving on.
+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?"*
@@ -88,6 +91,7 @@ Collect:
 - ORM/ODM
 - Hosting platform
 - Specific versions (for example Next.js 14 App Router, React 18)
+- 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?"*
@@ -150,6 +154,10 @@ Collect:
 - CI/CD strategy
 - Domain and SSL
 - CDN or object storage needs?
+- 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
 
 ### 10. Architecture Decision Records (ADR)
 *"Are there key architecture decisions whose rationale should be documented?"*
@@ -158,128 +166,14 @@ Collect:
 - Non-obvious decisions (why PostgreSQL vs MongoDB)
 - Structural decisions with hidden rationale
 - Trade-offs considered
+- Revisit/exit trigger for strategic libraries and vendors
 - If the user has no ADRs, help identify them from topics 1-9
 
-## architecture.md Output Format
+## architecture.md Output
 
-````markdown
-# Architecture
+After discovery is complete and immediately before generating `project-context/architecture.md`, read `assets/architecture.template.md`.
 
-> **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` |
-
----
-
-## 1. System Context
-
-**Users:** [End Users, Admins, etc.]
-
-**External Services:**
-| Service | Purpose | Protocol |
-|---------|---------|----------|
-| [Service] | [Purpose] | REST / SDK / OAuth |
-
-## 2. Tech Stack
-| Layer | Technology | Version | Notes |
-|-------|------------|---------|-------|
-| Frontend | [Framework] | [Version] | [Notes] |
-| Backend | [Framework] | [Version] | [Notes] |
-| Database | [Database] | [Version] | [Notes] |
-| ORM | [ORM] | [Version] | [Notes] |
-| Language | [Language] | [Version] | [Notes] |
-
-## 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
-- **Real-time:** WebSocket / SSE / No
-- **Base Path:** `/api/v1`
-
-## 5. Folder Structure
-```
-[Project Root]
-├── [folder 1]/         # [description]
-│   ├── [subfolder]/    # [description]
-│   └── [file]
-├── [folder 2]/         # [description]
-└── [folder 3]/         # [description]
-```
-
-## 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
-- **RBAC:** Yes / No
-- **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.]
-- **Required Controls:**
-   - [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.
-- **CDN/Storage:** Cloudflare / S3 / etc.
-- **Domain:** [Planned domain]
-
-## 10. Canonical Terminology
-| Term | Definition |
-|------|------------|
-| [Term] | [Definition in the project context] |
-
-## 11. Architecture Decision Records (ADR)
-
-### ADR Index
-| 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]
-- **Trade-off:** [Accepted downside]
-- **Rejected Alternatives:** [What else was considered and why it was rejected]
-
----
-
-## 12. Assumptions & Open Questions
-
-### Assumptions
-- [Assumption the architecture depends on]
-
-### Open Questions
-- [Question that is still unresolved]
-````
+Adapt only sections that are applicable and preserve every required contract from the interview. Do not load the template during early discovery.
 
 ## After architecture.md Is Created
 
@@ -296,6 +190,7 @@ Collect:
 - **System Context (topic 1)** is the highest level. Start here before technical detail.
 - **Threat modeling (topic 8)** is required before implementation.
 - **ADR (topic 10)** helps prevent accidental reversal of mature decisions.
+- 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

@@ -0,0 +1,135 @@
+# Architecture
+
+> **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` |
+
+---
+
+## 1. System Context
+
+**Users:** [End Users, Admins, etc.]
+
+**External Services:**
+| Service | Purpose | Protocol |
+|---------|---------|----------|
+| [Service] | [Purpose] | REST / SDK / OAuth |
+
+## 2. Tech Stack
+| Layer | Technology | Version | Notes |
+|-------|------------|---------|-------|
+| Frontend | [Framework] | [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 |
+
+## 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]
+│   ├── [subfolder]/    # [description]
+│   └── [file]
+├── [folder 2]/         # [description]
+└── [folder 3]/         # [description]
+```
+
+## 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
+- **RBAC:** Yes / No
+- **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.]
+- **Required Controls:**
+   - [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.
+- **CDN/Storage:** Cloudflare / S3 / etc.
+- **Domain:** [Planned domain]
+
+### Operations & Observability
+- **Operational Owner:** [team/role]
+- **Runbook / Support:** [location and escalation]
+- **Logs:** [events, redaction, retention]
+- **Metrics & Traces:** [signals tied to NFR/success metrics]
+- **Alerts:** [threshold, owner, escalation]
+
+### Rollback and Recovery
+- **Rollback Trigger:** [condition]
+- **Rollback Mechanism:** [deployment/data strategy]
+- **Post-Rollback Validation:** [checks]
+- **Backup / Restore:** [scope and test cadence]
+- **RPO / RTO:** [critical systems only]
+
+## 10. Canonical Terminology
+| Term | Definition |
+|------|------------|
+| [Term] | [Definition in the project context] |
+
+## 11. Architecture Decision Records (ADR)
+
+### ADR Index
+| 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]
+- **Trade-off:** [Accepted downside]
+- **Rejected Alternatives:** [What else was considered and why it was rejected]
+
+---
+
+## 12. Assumptions & Open Questions
+
+### Assumptions
+- [Assumption the architecture depends on]
+
+### Open Questions
+- [Question that is still unresolved]

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

@@ -1,8 +1,10 @@
 ---
 name: brainstorm-prd
-description: Interview users and generate `PRD.md` (Product Requirements Document). Use when creating a PRD or starting a new project.
-persona: "Galbi"
-persona_role: "Project Manager"
+description: Interviews users and generates `PRD.md` with scope, outcomes, metrics, rollout, business rules, and traceability. Use only when the user explicitly wants to define a new product or create/recreate its PRD.
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
+metadata:
+  persona: "Galbi"
+  persona-role: "Project Manager"
 ---
 
 # Brainstorm PRD
@@ -34,12 +36,13 @@ You are an experienced **Product Manager** who turns raw ideas into clear, actio
 
 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/PRD.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.
 
 ---
 
@@ -55,7 +58,7 @@ Before any interview:
    - `backend` → PRD MUST focus on business rules, service/API/data/auth, and consumer dependencies
    - `fullstack` → full PRD
 
-4. Run the shared runtime setup above. For this skill, ask whether to cover the 15 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 the answer before continuing.
 
@@ -90,6 +93,7 @@ Collect:
 
 Collect:
 - Current condition without this project
+- Current workaround and its time, cost, or reliability impact
 - Main pain points
 - Why existing solutions are not enough
 
@@ -117,6 +121,7 @@ Collect:
 - Step-by-step user journey
 - Different flows for different roles
 - Happy path vs error scenarios
+- Expected degraded behavior when data or an external dependency is unavailable
 
 ### 7. Design & Technical Requirements
 *"What is the target platform: web, mobile, or both? Any design references or technical preferences?"*
@@ -142,8 +147,10 @@ Collect:
 
 Collect:
 - MVP criteria
-- Success metrics
+- Success metrics with baseline, target, timeframe, measurement source, and owner
 - Timeline/deadline
+- Product rollout: pilot/beta/phased/full launch, target audience, and readiness criteria
+- Analytics events needed to measure the selected metrics, only when behavioral measurement is relevant
 
 ### 10. Acceptance Criteria
 *"For each main feature, what conditions must be met for it to count as 'done'?"*
@@ -202,101 +209,11 @@ All requirements must have stable Traceability IDs:
 
 Do not renumber old IDs in future updates; append new IDs sequentially.
 
-## PRD.md Output Format
+## PRD.md Output
 
-````markdown
-# PRD: [Project Name]
+After discovery is complete and immediately before generating `project-context/PRD.md`, read `assets/PRD.template.md`.
 
-> **Version:** 1.0 | **Date:** [date] | **Status:** Draft
-
-## Document Role
-- **Source of Truth:** Product scope, user intent, business rules, and success criteria
-- **Primary Owner:** `brainstorm-prd`
-- **Out of Scope:** API payload details, schema column definitions, code patterns, and implementation order
-
-## Canonical Terminology
-| Term | Meaning |
-|------|---------|
-| [Term] | [Exact meaning in this project] |
-
----
-
-## 1. Project Goal
-[Goal and vision — 1-2 paragraphs]
-
-## 2. Target Users
-| Persona | Description | Role |
-|---------|-------------|------|
-| [Persona 1] | [Description] | End User / Admin / etc |
-
-## 3. Problem Statement
-[Problem being solved]
-
-## 4. Core Features
-### MVP (Release 1)
-| ID | Feature | Description | Priority |
-|----|---------|-------------|----------|
-| FEAT-01 | [Feature] | [Description] | High |
-
-### Future Enhancements
-- **FEAT-02:** [Feature] — [Description]
-
-## 5. Business Rules
-- **BR-01:** [Rule]
-- **BR-02:** [Rule]
-
-## 6. User Flow
-### [Persona 1]
-1. [Step 1]
-2. [Step 2]
-
-## 7. Design & Technical Requirements
-- **Platform:** Web / Mobile / Desktop
-- **UI Reference:** [Link or name]
-- **Tech Stack (preferred):** [If any]
-- **Integrations:** [Third-party services]
-
-## 8. Non-Functional Requirements
-| ID | Category | Requirement | Target |
-|----|----------|-------------|--------|
-| NFR-01 | Performance | Page load time | < 3 seconds |
-| NFR-02 | Security | [Requirement] | [Target] |
-| NFR-03 | Scalability | Concurrent users | [Count] |
-| NFR-04 | Accessibility | [Requirement] | [Target] |
-
-## 9. Success Criteria (Minimum)
-- [ ] [Criterion 1]
-- [ ] [Criterion 2]
-
-## 10. Acceptance Criteria
-### FEAT-01: [Feature Name]
-- **AC-01:** **Given** [starting condition], **When** [user action], **Then** [expected result]
-
-## 11. Non-Goals / Out of Scope
-- [What will NOT be done]
-
-## 12. Assumptions
-- [Assumption 1]
-- [Assumption 2]
-
-## 13. User Stories
-- **US-01:** As a **[role]**, I want **[feature]** so that **[benefit]**
-
-## 14. Stakeholders
-| Name/Role | Responsibility |
-|-----------|----------------|
-| [Name] | [Role] |
-
-## 15. Open Questions
-| Question | Status | Owner |
-|----------|--------|-------|
-| [Question] | Pending | [Who] |
-
-## Reading Guide for AI
-- If this PRD conflicts with detailed implementation documents, the PRD wins on business intent and scope.
-- If a term is ambiguous, prioritize the definition in `Canonical Terminology`.
-- Use `Non-Goals / Out of Scope`, `Assumptions`, and `Open Questions` to avoid building more than necessary.
-````
+Adapt only sections that are applicable and preserve every required contract from the interview. Do not load the template during early discovery.
 
 ## After PRD.md Is Created
 

package/.agents/skills/brainstorm-prd/assets/PRD.template.md

@@ -0,0 +1,106 @@
+# PRD: [Project Name]
+
+> **Version:** 1.0 | **Date:** [date] | **Status:** Draft
+
+## Document Role
+- **Source of Truth:** Product scope, user intent, business rules, and success criteria
+- **Primary Owner:** `brainstorm-prd`
+- **Out of Scope:** API payload details, schema column definitions, code patterns, and implementation order
+
+## Canonical Terminology
+| Term | Meaning |
+|------|---------|
+| [Term] | [Exact meaning in this project] |
+
+---
+
+## 1. Project Goal
+[Goal and vision — 1-2 paragraphs]
+
+## 2. Target Users
+| Persona | Description | Role |
+|---------|-------------|------|
+| [Persona 1] | [Description] | End User / Admin / etc |
+
+## 3. Problem Statement
+[Problem being solved]
+
+### Current Workaround
+- **How users handle it now:** [workaround]
+- **Cost / limitation:** [time, money, risk, or reliability impact]
+
+## 4. Core Features
+### MVP (Release 1)
+| ID | Feature | Description | Priority |
+|----|---------|-------------|----------|
+| FEAT-01 | [Feature] | [Description] | High |
+
+### Future Enhancements
+- **FEAT-02:** [Feature] — [Description]
+
+## 5. Business Rules
+- **BR-01:** [Rule]
+- **BR-02:** [Rule]
+
+## 6. User Flow
+### [Persona 1]
+1. [Step 1]
+2. [Step 2]
+
+### Failure and Degraded Behavior
+| Situation | Expected User Experience | Recovery |
+|-----------|--------------------------|----------|
+| [Dependency/data unavailable] | [behavior] | [retry/fallback/support] |
+
+## 7. Design & Technical Requirements
+- **Platform:** Web / Mobile / Desktop
+- **UI Reference:** [Link or name]
+- **Tech Stack (preferred):** [If any]
+- **Integrations:** [Third-party services]
+
+## 8. Non-Functional Requirements
+| ID | Category | Requirement | Target |
+|----|----------|-------------|--------|
+| NFR-01 | Performance | Page load time | < 3 seconds |
+| NFR-02 | Security | [Requirement] | [Target] |
+| NFR-03 | Scalability | Concurrent users | [Count] |
+| NFR-04 | Accessibility | [Requirement] | [Target] |
+
+## 9. Success Metrics and Rollout
+| Metric | Baseline | Target | Timeframe | Measurement Source | Owner |
+|--------|----------|--------|-----------|--------------------|-------|
+| [Metric] | [current/unknown] | [target] | [period] | [analytics/report] | [owner] |
+
+**Rollout:** [pilot / beta / phased / full]
+**Target Audience:** [initial cohort]
+**Readiness Criteria:** [conditions before expansion]
+**Analytics Events:** [only events required to measure the metrics]
+
+## 10. Acceptance Criteria
+### FEAT-01: [Feature Name]
+- **AC-01:** **Given** [starting condition], **When** [user action], **Then** [expected result]
+
+## 11. Non-Goals / Out of Scope
+- [What will NOT be done]
+
+## 12. Assumptions
+- [Assumption 1]
+- [Assumption 2]
+
+## 13. User Stories
+- **US-01:** As a **[role]**, I want **[feature]** so that **[benefit]**
+
+## 14. Stakeholders
+| Name/Role | Responsibility |
+|-----------|----------------|
+| [Name] | [Role] |
+
+## 15. Open Questions
+| Question | Status | Owner |
+|----------|--------|-------|
+| [Question] | Pending | [Who] |
+
+## Reading Guide for AI
+- If this PRD conflicts with detailed implementation documents, the PRD wins on business intent and scope.
+- If a term is ambiguous, prioritize the definition in `Canonical Terminology`.
+- Use `Non-Goals / Out of Scope`, `Assumptions`, and `Open Questions` to avoid building more than necessary.