macca-method 2.1.1 → 2.1.2

package/README.md

@@ -2,7 +2,7 @@
 
 **MACCA** is an AI-based software development system that works from **written specifications**, not guesses. Before a single line of code exists, all important decisions are already documented. AI reads those documents before coding, then verifies the result after coding.
 
-> **Macca** comes from Bugis and means *smart, intelligent, capable*. In Bugis-Makassar philosophy, intelligence is always paired with noble character — a moral identity carried everywhere.
+> **Macca** comes from Bugis and means _smart, intelligent, capable_. In Bugis-Makassar philosophy, intelligence is always paired with noble character — a moral identity carried everywhere.
 
 ![MACCA Method](image-macca-method.webp)
 
@@ -55,6 +55,7 @@ All planning output documents are stored in `project-context/` in your project.
 ## 3. Planning Skills
 
 Planning skills run as evidence-first interview sessions. AI reads applicable upstream specs first and asks only material decisions that are still unknown. At the start of each session, AI announces the topic count, then asks two things if not already saved:
+
 1. **Pacing**: (A) one by one · (B) three at a time · (C) all at once
 2. **Recommendations**: should AI provide suggested answers for each question?
 
@@ -80,6 +81,7 @@ Depth is inferred from existing context and can be overridden; it does not add a
 **Topic count:** 15 topics
 
 **Topics covered:**
+
 1. Project Goal — long-term vision and what makes the project unique
 2. Target Users — user personas, demographics, pain points
 3. Problem Being Solved — real problem, current workaround, and its cost/limitations
@@ -90,13 +92,14 @@ Depth is inferred from existing context and can be overridden; it does not add a
 8. Non-Functional Requirements — performance, security, scalability, accessibility, availability
 9. Success Metrics & Rollout — baseline, target, timeframe, measurement source, owner, launch strategy
 10. Acceptance Criteria — concrete conditions for each feature
-11. Non-Goals — what will *not* be built
+11. Non-Goals — what will _not_ be built
 12. Assumptions — unverified conditions
 13. User Stories — prioritized workflows from the user perspective
 14. Stakeholders — owners and responsibilities
 15. Open Questions — unresolved decisions and risks
 
 **Important behavior:**
+
 - Use `Traceability ID` (`FEAT-*`, `BR-*`, `AC-*`, `NFR-*`, `US-*`) so each requirement can be traced to tasks and code
 - Do not overwrite existing files without confirmation
 
@@ -118,6 +121,7 @@ Depth is inferred from existing context and can be overridden; it does not add a
 **Topic count:** 10 topics
 
 **Topics covered:**
+
 1. System Context — systems and external services that interact
 2. Tech Stack — frontend, backend, database, hosting, CI/CD, plus strategic dependency/license/health/lock-in/exit evaluation
 3. Folder Structure — project file and directory organization
@@ -130,6 +134,7 @@ Depth is inferred from existing context and can be overridden; it does not add a
 10. Architecture Decision Records — major decisions and their reasoning
 
 **Important behavior:**
+
 - Every decision must be defensible with reasoning
 - The `Tech Stack` and `Folder Structure` fields are mandatory references for `spec-compliance` (SC-02) and `developer` (Step 2)
 
@@ -151,6 +156,7 @@ Depth is inferred from existing context and can be overridden; it does not add a
 **Topic count:** 5 topics
 
 **Topics covered:**
+
 1. Persistence Conventions — identity, naming, audit/version metadata, deletion, retention
 2. Entity/Storage Map — relational, document, key-value, graph, event-store, or mixed
 3. Fields & Data Types — datastore-native validation, PII, volume, growth, payload size
@@ -158,6 +164,7 @@ Depth is inferred from existing context and can be overridden; it does not add a
 5. Access Patterns & Evolution — indexes/projections, consistency, migration, backfill, compatibility, recovery
 
 **Important behavior:**
+
 - Give each persisted entity a `Traceability ID` (`DATA-*`)
 - Datastore-native names, tenancy, concurrency, retention, and migration constraints are verified by `spec-compliance` (SC-03)
 
@@ -179,6 +186,7 @@ Depth is inferred from existing context and can be overridden; it does not add a
 **Topic count:** 5 topics
 
 **Topics covered:**
+
 1. Entry Point, Versioning, Deprecation & Auth — protocol-native compatibility and lifecycle
 2. Error Catalog — protocol-native errors, retryability, timeout interaction, client action
 3. Operations — REST endpoints, GraphQL operations, RPC procedures, events, or mixed contracts
@@ -186,6 +194,7 @@ Depth is inferred from existing context and can be overridden; it does not add a
 5. Flow & Reliability — pagination/streaming, rate limits, retries, SLOs, and contract-test invariants
 
 **Important behavior:**
+
 - Give each operation a `Traceability ID` (`API-*`)
 - Agreed request and response formats are a **contract** verified by `spec-compliance` (SC-04) during coding
 
@@ -207,6 +216,7 @@ Depth is inferred from existing context and can be overridden; it does not add a
 **Topic count:** 8 topics
 
 **Topics covered:**
+
 1. CSS Framework — Tailwind CSS (v3/v4), Bootstrap, CSS Modules, or custom
 2. Color Palette — primary, secondary, accent, status colors (error/success/warning/info), dark mode
 3. Typography — font family, heading and body sizes, line height, font weight
@@ -217,6 +227,7 @@ Depth is inferred from existing context and can be overridden; it does not add a
 8. Accessibility, Localization & Operational States — keyboard/focus/screen reader/reduced motion; loading/empty/error/forbidden/offline; locales/RTL; UI performance
 
 **Important behavior:**
+
 - Agreed colors and spacing are a **contract** — `spec-compliance` (SC-06) flags arbitrary values outside this list
 
 </details>
@@ -237,6 +248,7 @@ Depth is inferred from existing context and can be overridden; it does not add a
 **Topic count:** 7 topics
 
 **Topics covered:**
+
 1. AI Persona & Tech Stack — main technologies, preferred libraries, favored and avoided patterns
 2. Naming Conventions — variables, functions, components, files, folders, constants
 3. Code Style — formatting (Prettier/ESLint), max function length, `console.log` rules, early return
@@ -248,6 +260,7 @@ Depth is inferred from existing context and can be overridden; it does not add a
 Conditional rules are generated only when applicable: structured logging, migrations, feature flags, generated code, and secret rotation.
 
 **Important behavior:**
+
 - The `[FORBIDDEN]` section is the first thing `developer` reads before coding
 - If the `[FORBIDDEN]` section is missing, `spec-compliance` records it as a MINOR finding
 
@@ -269,16 +282,19 @@ Conditional rules are generated only when applicable: structured logging, migrat
 **User clarification count:** 3 topics plus one automatic document-completeness check
 
 **Clarification topics:**
+
 1. Phase Priority Order — implementation order, which features must finish first
 2. Task Granularity — how small should tasks be? One file, one endpoint, or one full feature?
 3. Execution Rules — stop for confirmation after each task, or continue automatically by phase?
 4. Verify Available Documents — AI checks spec completeness itself before creating `Task.md`
 
 **Two operation modes:**
+
 - **Generate New** — create `Task.md` from scratch based on all available specs
 - **Add Phase Mode** — append a new phase below existing `Task.md` content (called by `add-feature`, does not overwrite old content)
 
 **Important behavior:**
+
 - Tasks are **not created from guesses** — all tasks are derived from the spec documents
 - Every task has concrete, verifiable `Acceptance Criteria`
 - Testing order follows `rules.md`: test-first when explicitly selected, otherwise test-with-change or the project's approved workflow
@@ -307,18 +323,21 @@ Read `.agents/developer-config.json`. If `name` or `project` is missing, AI asks
 
 **Additional skills & MCP setup** (`references/onboarding.md`)
 
-*Additional Skills:*
+_Additional Skills:_
+
 - If `additionalSkills` already exists in config → use it directly
-- If not → AI asks once: *"Are there any additional skills for this project?"*
+- If not → AI asks once: _"Are there any additional skills for this project?"_
 - For every named skill, AI **first searches the workspace itself** (`.agents/skills/`, `.github/skills/`, `.opencode/skills/`). It only asks you for the path if the skill is not found.
 - When working on a relevant task, AI **must read** `SKILL.md` from that skill before writing code.
 
-*MCP (Model Context Protocol):*
+_MCP (Model Context Protocol):_
+
 - If `availableMCPs` already exists in config → use it directly
-- If not → AI asks once: *"Which MCPs are available in your workspace?"*
+- If not → AI asks once: _"Which MCPs are available in your workspace?"_
 - Only listed MCPs will be used.
 
 **Developer scope** (`references/onboarding.md`)
+
 - If `developerPreferences.scope` already exists → use it directly
 - If not → AI asks once:
   ```
@@ -330,6 +349,7 @@ Read `.agents/developer-config.json`. If `name` or `project` is missing, AI asks
 - This scope is enforced in every phase: AI will not create/change files outside the scope.
 
 **Work mode** (`references/onboarding.md`)
+
 - If `developerPreferences.workMode` already exists → use it directly
 - If not → AI asks once:
   ```
@@ -346,19 +366,20 @@ Read `.agents/developer-config.json`. If `name` or `project` is missing, AI asks
 
 **Selecting relevant specs** (`references/execute-task.md`)
 
-| Condition | Read |
-|---------|--------|
-| All tasks (always) | `rules.md`, `architecture.md` |
-| Task touches database/model | + `schema.md` |
-| Task touches API/endpoint | + `api.md` |
-| Task touches UI/component | + `StyleGuide.md` |
-| Requirement is unclear | + `PRD.md` |
+| Condition                   | Read                          |
+| --------------------------- | ----------------------------- |
+| All tasks (always)          | `rules.md`, `architecture.md` |
+| Task touches database/model | + `schema.md`                 |
+| Task touches API/endpoint   | + `api.md`                    |
+| Task touches UI/component   | + `StyleGuide.md`             |
+| Requirement is unclear      | + `PRD.md`                    |
 
 Scope enforcement: if `scope=frontend`, AI does not touch backend files. If `scope=backend`, AI does not touch frontend files.
 
 **Executing tasks** (`references/execute-task.md`)
 
 For each task:
+
 1. Understand the task and acceptance criteria
 2. Check the ladder: does it need to be built? Does it already exist in the codebase? Is it in the standard library? (YAGNI)
 3. Write an I/O contract for non-trivial functions
@@ -372,11 +393,13 @@ For each task:
 6. Run validation, update `Task.md` (`[ ]` → `[x]`)
 
 Developer loads workflow references by state, not all at once:
+
 - `onboarding.md` only for missing setup or plan-first
 - `execute-task.md` only for the current task
 - `close-phase.md` only when closing a phase/project
 
 **Closing a phase** (`references/close-phase.md`)
+
 1. Show a phase summary
 2. Verify the applicable Phase Definition of Done; mark genuine non-applicable items with a reason
 3. If there is a plan file for this phase → update plan status: `in-progress` → `code-review`
@@ -385,6 +408,7 @@ Developer loads workflow references by state, not all at once:
 6. Complete quality-gate DoD items, then offer the next phase
 
 **MCPs used (if listed in `availableMCPs`):**
+
 - `context7` or equivalent docs MCP — current installed-version library documentation
 - `codebase-memory-mcp` or equivalent graph/symbol tooling — codebase discovery and relationships
 - Other registered MCPs only when relevant to the current task
@@ -410,9 +434,10 @@ Same as `developer`. Reads `.agents/developer-config.json`, greets by name and p
 **Step 0b & 0c — Additional Skills, MCP, Scope**
 Same setup policy as `developer`. Reads from config if already set and asks only for missing required setup.
 
-**Step 1 — Pre-flight summary** *(unique to quick-dev)*
+**Step 1 — Pre-flight summary** _(unique to quick-dev)_
 
 Before any code is written, AI shows:
+
 ```
 Quick Dev — Pre-flight
 ───────────────────────
@@ -425,6 +450,7 @@ Assumptions (will proceed unless corrected):
 Need confirmation before proceeding:   ← omit if none
   [?] [blocking question]
 ```
+
 - Non-blocking ambiguities go under "Assumptions", not as questions
 - Missing specs (e.g. no `StyleGuide.md` but task touches UI) are flagged here
 - Waits only when a blocking ambiguity exists; otherwise proceeds in the same turn with listed assumptions
@@ -437,11 +463,11 @@ Loads the same task-execution workflow as `developer`: scope check → delta app
 
 **Step 4 — Update Task.md**
 
-| Condition | Action |
-|---|---|
-| Related item found, `[ ]` | Mark `[x]`, add brief note |
-| Related item found, `[x]` | Add sub-note about the refinement |
-| No related item | Append to active phase as `[x]` with tag `(quick-fix: YYYY-MM-DD)` |
+| Condition                 | Action                                                             |
+| ------------------------- | ------------------------------------------------------------------ |
+| Related item found, `[ ]` | Mark `[x]`, add brief note                                         |
+| Related item found, `[x]` | Add sub-note about the refinement                                  |
+| No related item           | Append to active phase as `[x]` with tag `(quick-fix: YYYY-MM-DD)` |
 
 **Step 5 — Quality gates**
 Runs full `spec-compliance` then `code-review`. Both follow `fixMode` from config.
@@ -449,6 +475,7 @@ Runs full `spec-compliance` then `code-review`. Both follow `fixMode` from confi
 **Important behavior:** quick-dev is a bounded router, not a separate implementation philosophy. It follows the same shared implementation principles, testing policy, and approval gates as `developer`, but only for small, clearly anchored work. Anything broader routes back to `developer`.
 
 **Step 6 — Final report**
+
 ```
 Quick Dev — Done
 ─────────────────
@@ -473,16 +500,16 @@ Remaining ambiguities:   ← omit if none
 
 **Checklist (8 items):**
 
-| ID | Aspect | Documents Read |
-|----|-------|---------------------|
-| SC-01 | PRD Compliance | scope, business rules, acceptance/NFR, metrics/rollout and degraded behavior when applicable |
-| SC-02 | Architecture Compliance | stack, boundaries, patterns, auth, observability/rollback/recovery when touched |
-| SC-03 | Schema Compliance | datastore-native names, validation, tenancy, concurrency, retention and evolution |
-| SC-04 | API Compliance | protocol-native operations, errors, auth, reliability, lifecycle and contract invariants |
-| SC-05 | Rules Compliance | `[FORBIDDEN]`, naming, security, testing and applicable operational conventions |
-| SC-06 | StyleGuide Compliance | tokens, responsive behavior, accessibility, localization and operational states |
-| SC-07 | Task Completion | acceptance criteria, traceability and applicable Phase Definition of Done |
-| SC-08 | Scope Compliance | `developer-config.json` — frontend/backend scope respected, no files outside scope |
+| ID    | Aspect                  | Documents Read                                                                               |
+| ----- | ----------------------- | -------------------------------------------------------------------------------------------- |
+| SC-01 | PRD Compliance          | scope, business rules, acceptance/NFR, metrics/rollout and degraded behavior when applicable |
+| SC-02 | Architecture Compliance | stack, boundaries, patterns, auth, observability/rollback/recovery when touched              |
+| SC-03 | Schema Compliance       | datastore-native names, validation, tenancy, concurrency, retention and evolution            |
+| SC-04 | API Compliance          | protocol-native operations, errors, auth, reliability, lifecycle and contract invariants     |
+| SC-05 | Rules Compliance        | `[FORBIDDEN]`, naming, security, testing and applicable operational conventions              |
+| SC-06 | StyleGuide Compliance   | tokens, responsive behavior, accessibility, localization and operational states              |
+| SC-07 | Task Completion         | acceptance criteria, traceability and applicable Phase Definition of Done                    |
+| SC-08 | Scope Compliance        | `developer-config.json` — frontend/backend scope respected, no files outside scope           |
 
 **Severity:** `💥 BLOCKER` → fix now, re-run | `🔴 MAJOR` → fix before the next phase | `⚠️ MINOR` → discuss | `✅ PASS` → continue to `code-review`
 
@@ -500,39 +527,42 @@ Remaining ambiguities:   ← omit if none
 **Called when:** Automatically after `spec-compliance` is clean. Can also be called manually any time.
 
 **Fix mode (runtime default + can be set in config):**
+
 ```
 A) Report first — show all findings, wait for confirmation before fixing
 B) Fix now      — automatically fix BLOCKER/MAJOR, full report at the end
 ```
+
 If this field is missing, the default is `report-first`. To change it, the user or config workflow can set `codeReviewPreferences.fixMode` in `developer-config.json`.
 
 **Phase 1 — 27-Item Code Quality:**
 
-| Tier | Item |
-|------|------|
-| 💥 BLOCKER | CR-01 Wrong imports · CR-02 Runtime errors · CR-03 Null/undefined · CR-04 SQL injection · CR-05 Deprecated methods |
-| 🔴 MAJOR | CR-06 Duplicate function · CR-07 Unused code · CR-08 Duplicate logic · CR-09 Obsolete code · CR-10 Inconsistent naming · CR-11 Ignoring existing code · CR-12 Missing dependency · CR-13 Dependency conflict · CR-14 Memory leaks · CR-15 Security ignored · CR-16 Missing required rate-limit handling · CR-17 Missing tests required by `rules.md` |
-| ⚠️ MINOR | CR-18 Edge cases · CR-19 Happy path only · CR-20 Performance · CR-21 Outdated pattern · CR-22 Under-engineering · CR-23 Over-engineering · CR-24 Environment assumptions |
-| ℹ️ INFO | CR-25 Missing comments · CR-26 Jargon · CR-27 Comment quality |
+| Tier       | Item                                                                                                                                                                                                                                                                                                                                                 |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 💥 BLOCKER | CR-01 Wrong imports · CR-02 Runtime errors · CR-03 Null/undefined · CR-04 SQL injection · CR-05 Deprecated methods                                                                                                                                                                                                                                   |
+| 🔴 MAJOR   | CR-06 Duplicate function · CR-07 Unused code · CR-08 Duplicate logic · CR-09 Obsolete code · CR-10 Inconsistent naming · CR-11 Ignoring existing code · CR-12 Missing dependency · CR-13 Dependency conflict · CR-14 Memory leaks · CR-15 Security ignored · CR-16 Missing required rate-limit handling · CR-17 Missing tests required by `rules.md` |
+| ⚠️ MINOR   | CR-18 Edge cases · CR-19 Happy path only · CR-20 Performance · CR-21 Outdated pattern · CR-22 Under-engineering · CR-23 Over-engineering · CR-24 Environment assumptions                                                                                                                                                                             |
+| ℹ️ INFO    | CR-25 Missing comments · CR-26 Jargon · CR-27 Comment quality                                                                                                                                                                                                                                                                                        |
 
 **Phase 2 — 10 Security Essentials:**
 
-| ID | Aspect |
-|----|-------|
-| SEC-01 | Injection Prevention — SQL, shell, eval |
-| SEC-02 | Authentication — password hashing, cookie attributes |
-| SEC-03 | Authorization — deny-by-default, ownership checks, mass assignment |
-| SEC-04 | XSS Prevention — innerHTML, dangerouslySetInnerHTML |
-| SEC-05 | API Security — rate limiting, CORS, JWT verification |
-| SEC-06 | Data Protection & Logging — no sensitive logs, no hardcoded secrets |
-| SEC-07 | Error Handling Security — fail-closed, no swallowed exceptions |
-| SEC-08 | Input Validation — body/params/query/headers/cookies |
+| ID     | Aspect                                                                                                                                                                                                                                                                                                                                      |
+| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SEC-01 | Injection Prevention — SQL, shell, eval                                                                                                                                                                                                                                                                                                     |
+| SEC-02 | Authentication — password hashing, cookie attributes                                                                                                                                                                                                                                                                                        |
+| SEC-03 | Authorization — deny-by-default, ownership checks, mass assignment                                                                                                                                                                                                                                                                          |
+| SEC-04 | XSS Prevention — innerHTML, dangerouslySetInnerHTML                                                                                                                                                                                                                                                                                         |
+| SEC-05 | API Security — rate limiting, CORS, JWT verification                                                                                                                                                                                                                                                                                        |
+| SEC-06 | Data Protection & Logging — no sensitive logs, no hardcoded secrets                                                                                                                                                                                                                                                                         |
+| SEC-07 | Error Handling Security — fail-closed, no swallowed exceptions                                                                                                                                                                                                                                                                              |
+| SEC-08 | Input Validation — body/params/query/headers/cookies                                                                                                                                                                                                                                                                                        |
 | SEC-09 | Framework-Specific Security — AI reads `architecture.md` to detect the framework: **Next.js** (`NEXT_PUBLIC_*`, Server Actions, middleware, wildcard image domains), **Laravel** (CSRF, Eloquent, `.env`), **Django** (`ALLOWED_HOSTS`, `DEBUG`, `SECRET_KEY`), **Express/NestJS** (`helmet`, CORS, body limits), **Rails** (strong params) |
-| SEC-10 | Dependency Vulnerabilities — packages with critical/high CVEs (`npm audit`, `pip audit`, `composer audit`, etc.) |
+| SEC-10 | Dependency Vulnerabilities — packages with critical/high CVEs (`npm audit`, `pip audit`, `composer audit`, etc.)                                                                                                                                                                                                                            |
 
 **Format for each finding:** Where? → If not fixed? → If fixed? → Recommended fix
 
 **Update plan after review completes** (if a plan file exists for this phase):
+
 - **Plan-level deviation exists** (wrong library, pattern not followed, scope changed, approach differs from the plan) → add a note to the plan + change status: `code-review` → `done`
 - **No plan deviation** (only code quality issues: naming, formatting, security hardening) → change status only: `code-review` → `done`, with no note
 
@@ -558,6 +588,7 @@ If this field is missing, the default is `report-first`. To change it, the user
 - Plans in `project-context/plans/` — list all plan files and their statuses (`review` / `in-progress` / `code-review` / `done`)
 
 **Output format:**
+
 ```
 Checking your project now...
 
@@ -594,6 +625,7 @@ Recommended next steps: ...
 **Called when:** A bug needs to be fixed.
 
 **Workflow:**
+
 1. You describe the bug (symptoms, location, reproduction steps, error message)
 2. AI checks `bug-log.md` — has it happened before?
    - **Identical** → apply the same fix (ask for confirmation first)
@@ -618,6 +650,7 @@ Recommended next steps: ...
 **Called when:** A new feature needs to be added to an existing project.
 
 **Workflow:**
+
 1. You describe the new feature (name, function, users, reason)
 2. AI reads all specs in `project-context/`
 3. AI shows an impact analysis — which documents are affected (including `plans/`)
@@ -642,10 +675,10 @@ Recommended next steps: ...
 **Two modes:**
 
 **Project Mode** — audit `project-context/`
-Checks consistency *between* documents: persisted entities with no supporting operation? Features with no task? PRD metrics with no observability signal? Rollout without rollback? Architecture decisions conflicting with rules? Traceability IDs referenced but missing?
+Checks consistency _between_ documents: persisted entities with no supporting operation? Features with no task? PRD metrics with no observability signal? Rollout without rollback? Architecture decisions conflicting with rules? Traceability IDs referenced but missing?
 
 **Framework Mode** — audit MACCA itself
-Checks consistency *between* skill instructions: are README, skill docs, and workflow aligned, or do they conflict?
+Checks consistency _between_ skill instructions: are README, skill docs, and workflow aligned, or do they conflict?
 
 **What it checks:** direct conflicts → workflow drift → inconsistencies → ambiguities
 
@@ -663,6 +696,7 @@ Checks consistency *between* skill instructions: are README, skill docs, and wor
 **Called when:** The project already exists but has no spec documents yet.
 
 **Two modes:**
+
 ```
 Mode A — Batch Generate: scan the full codebase, generate everything at once.
 Mode B — Guided Generate: one document → you review → confirm → continue.
@@ -673,8 +707,9 @@ Mode B — Guided Generate: one document → you review → confirm → continue
 `PRD.md` is created last because it is synthesized from observed behavior, not guessed intent.
 
 **Each generated document includes:**
+
 - **Evidence Inputs** — files/sources used as the basis for each claim
-- **Confidence Level** per claim: *High* (seen directly in code) / *Medium* (strong inference) / *Low* (guess, needs verification)
+- **Confidence Level** per claim: _High_ (seen directly in code) / _Medium_ (strong inference) / _Low_ (guess, needs verification)
 - **Confidence Summary** — summary of strong facts, inferences, and what still needs manual verification
 - **Missing Decisions** — choices that cannot be proven from code, with the recommended owning brainstorm skill
 
@@ -692,6 +727,7 @@ Mode B — Guided Generate: one document → you review → confirm → continue
 **How it works:** Provide agenda, desired outcome, hard constraints, optional evidence, and participants in one setup. In one response, every selected persona gives exactly one evidence/assumption-labeled recommendation in a fixed order. @Galbi then summarizes decisions, open questions, action items, and artifact handoffs before closing automatically. A second round requires a new `meet` invocation.
 
 **Available personas:**
+
 - `@Galbi` — Project Manager: scope, priorities, business impact
 - `@Fachri` — Tech Lead: technical decisions, trade-offs, security
 - `@Akram` — UI/UX Designer: usability, visual consistency, accessibility
@@ -730,13 +766,13 @@ Verdicts: `READY`, `CONDITIONAL`, or `NOT READY`. Missing required evidence is `
 
 ## 6. The MACCA AI Team
 
-| Persona | Role | Skills |
-|---------|------|--------|
-| **@Galbi** | Project Manager | `brainstorm-prd`, `brainstorm-task`, `add-feature`, `help`, `meet` |
-| **@Fachri** | Tech Lead | `brainstorm-architecture`, `brainstorm-api`, `brainstorm-schema`, `brainstorm-rules`, `spec-init`, `spec-audit`, `spec-compliance`, `code-review`, `release-readiness` |
-| **@Akram** | UI/UX Designer | `brainstorm-styleguide` |
-| **@Firdaus** | Expert Developer | `developer`, `quick-dev` |
-| **@Ikhsan** | Debugger | `bug-fix` |
+| Persona      | Role             | Skills                                                                                                                                                                 |
+| ------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **@Galbi**   | Project Manager  | `brainstorm-prd`, `brainstorm-task`, `add-feature`, `help`, `meet`                                                                                                     |
+| **@Fachri**  | Tech Lead        | `brainstorm-architecture`, `brainstorm-api`, `brainstorm-schema`, `brainstorm-rules`, `spec-init`, `spec-audit`, `spec-compliance`, `code-review`, `release-readiness` |
+| **@Akram**   | UI/UX Designer   | `brainstorm-styleguide`                                                                                                                                                |
+| **@Firdaus** | Expert Developer | `developer`, `quick-dev`                                                                                                                                               |
+| **@Ikhsan**  | Debugger         | `bug-fix`                                                                                                                                                              |
 
 > **Persona Rule:** Do not swap the persona assigned to a skill. Its instructions, tone, and responsibilities are designed for that role.
 
@@ -932,13 +968,13 @@ Use the skill help
 
 You normally do not need to remember skill names. OpenCode and Copilot advertise each skill's `name` and `description`, then the model selects a relevant skill. Requests that can mutate broad source-of-truth documents or start implementation require clear user intent; read-only routing and bounded workflows may activate automatically.
 
-| Invocation policy | Skills |
-|---|---|
-| Explicit intent | `brainstorm-prd`, `brainstorm-architecture`, `brainstorm-schema`, `brainstorm-api`, `brainstorm-styleguide`, `brainstorm-rules`, `add-feature`, `spec-init` |
-| Explicit implementation intent | `developer` — phrases such as "implement Phase 2" are sufficient; the skill name is not required |
-| Model-auto router | `quick-dev` for bounded small implementation requests that still map clearly to the current project context |
-| Both direct and automatic/orchestrated | `brainstorm-task`, `bug-fix`, `code-review`, `spec-audit`, `release-readiness`, `help`, `meet` |
-| Primarily orchestrated | `spec-compliance`, called by execution/remediation workflows |
+| Invocation policy                      | Skills                                                                                                                                                      |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Explicit intent                        | `brainstorm-prd`, `brainstorm-architecture`, `brainstorm-schema`, `brainstorm-api`, `brainstorm-styleguide`, `brainstorm-rules`, `add-feature`, `spec-init` |
+| Explicit implementation intent         | `developer` — phrases such as "implement Phase 2" are sufficient; the skill name is not required                                                            |
+| Model-auto router                      | `quick-dev` for bounded small implementation requests that still map clearly to the current project context                                                 |
+| Both direct and automatic/orchestrated | `brainstorm-task`, `bug-fix`, `code-review`, `spec-audit`, `release-readiness`, `help`, `meet`                                                              |
+| Primarily orchestrated                 | `spec-compliance`, called by execution/remediation workflows                                                                                                |
 
 Agent Skills has no portable `user-invocable` or `disable-model-invocation` field. Copilot VS Code supports these as vendor extensions, but OpenCode ignores them. MACCA therefore keeps canonical frontmatter portable and enforces intent through descriptions, scope checks, and confirmation gates. Host-specific slash commands or permissions may be added as optional adapters, never as the only safety mechanism.
 
@@ -982,17 +1018,17 @@ your-project/
 
 Each installed skills folder contains `_shared` plus these 18 MACCA skills: `add-feature`, `brainstorm-api`, `brainstorm-architecture`, `brainstorm-prd`, `brainstorm-rules`, `brainstorm-schema`, `brainstorm-styleguide`, `brainstorm-task`, `bug-fix`, `code-review`, `developer`, `help`, `meet`, `quick-dev`, `release-readiness`, `spec-audit`, `spec-compliance`, and `spec-init`.
 
-| AI Tool | Skills Folder |
-|---------|---------------|
-| GitHub Copilot | `.github/skills/` |
-| Cursor | `.cursor/skills/` |
-| Claude Code | `.claude/skills/` |
-| Windsurf | `.windsurf/skills/` |
-| Gemini CLI | `.gemini/skills/` |
-| OpenCode | `.opencode/skills/` |
-| Kilo Code | `.kilo/skills/` |
-| Codex (OpenAI) | `.agents/skills/` |
-| Kimi CLI | `.agents/skills/` |
+| AI Tool        | Skills Folder       |
+| -------------- | ------------------- |
+| GitHub Copilot | `.github/skills/`   |
+| Cursor         | `.cursor/skills/`   |
+| Claude Code    | `.claude/skills/`   |
+| Windsurf       | `.windsurf/skills/` |
+| Gemini CLI     | `.gemini/skills/`   |
+| OpenCode       | `.opencode/skills/` |
+| Kilo Code      | `.kilo/skills/`     |
+| Codex (OpenAI) | `.agents/skills/`   |
+| Kimi CLI       | `.agents/skills/`   |
 
 The installer validates path containment, refuses symlink escapes and unowned collisions, preserves `developer-config.json`, detects local drift through SHA-256 hashes, and journals install/upgrade transactions for recovery. CI runs the full package/install/upgrade suite on Ubuntu, Windows, and macOS with Node 18 and 22.
 
@@ -1046,19 +1082,19 @@ The `.agents/developer-config.json` file is shared config across skills. All ski
 }
 ```
 
-| Field | Filled by | Description |
-|-------|--------------------|------------|
-| `name` | `developer` (Step 0) | Asked once |
-| `project` | `developer` (Step 0) | Asked once |
-| `languagePreferences` | installer / first skill | Communication language and document language |
-| `developerPreferences.workMode` | `developer` (`references/onboarding.md` § Work Mode) | `"direct"` or `"plan-first"` |
-| `developerPreferences.scope` | `developer` (`references/onboarding.md` § Developer Scope) | `"frontend"`, `"backend"`, or `"fullstack"` |
-| `brainstormPreferences.discussionMode` | brainstorm-* skills | `"one-by-one"`, `"three-at-a-time"`, or `"all-at-once"` |
-| `brainstormPreferences.recommendations` | brainstorm-* skills | `true` = AI gives suggested answers for each question |
-| `brainstormPreferences.discoveryDepth` | brainstorm-* skills | `"quick"`, `"standard"`, or `"critical"`; inferred when absent, user-overridable |
-| `codeReviewPreferences.fixMode` | user / config runtime | `"report-first"` or `"fix-then-report"` |
-| `additionalSkills` | `developer` (`references/onboarding.md` § Additional Skills and MCPs) | AI searches for the path in the workspace first, then asks only if it is not found |
-| `availableMCPs` | `developer` (`references/onboarding.md` § Additional Skills and MCPs) | Available MCPs; only listed MCPs are used |
+| Field                                   | Filled by                                                             | Description                                                                        |
+| --------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `name`                                  | `developer` (Step 0)                                                  | Asked once                                                                         |
+| `project`                               | `developer` (Step 0)                                                  | Asked once                                                                         |
+| `languagePreferences`                   | installer / first skill                                               | Communication language and document language                                       |
+| `developerPreferences.workMode`         | `developer` (`references/onboarding.md` § Work Mode)                  | `"direct"` or `"plan-first"`                                                       |
+| `developerPreferences.scope`            | `developer` (`references/onboarding.md` § Developer Scope)            | `"frontend"`, `"backend"`, or `"fullstack"`                                        |
+| `brainstormPreferences.discussionMode`  | brainstorm-* skills                                                   | `"one-by-one"`, `"three-at-a-time"`, or `"all-at-once"`                            |
+| `brainstormPreferences.recommendations` | brainstorm-* skills                                                   | `true` = AI gives suggested answers for each question                              |
+| `brainstormPreferences.discoveryDepth`  | brainstorm-* skills                                                   | `"quick"`, `"standard"`, or `"critical"`; inferred when absent, user-overridable   |
+| `codeReviewPreferences.fixMode`         | user / config runtime                                                 | `"report-first"` or `"fix-then-report"`                                            |
+| `additionalSkills`                      | `developer` (`references/onboarding.md` § Additional Skills and MCPs) | AI searches for the path in the workspace first, then asks only if it is not found |
+| `availableMCPs`                         | `developer` (`references/onboarding.md` § Additional Skills and MCPs) | Available MCPs; only listed MCPs are used                                          |
 
 **Rule:** all skills must **merge**, not overwrite the file. Unknown fields must be preserved.
 
@@ -1069,39 +1105,39 @@ The `.agents/developer-config.json` file is shared config across skills. All ski
 <details>
 <summary><strong>Glossary & Traceability ID</strong></summary>
 
-| Term | Explanation |
-|---------|------------|
-| **Skill** | Full instructions for AI — like an SOP for AI |
-| **Spec** | Planning document containing all decisions before coding |
-| **Subagent** | Helper agent for focused exploration/analysis |
-| **project-context/** | Folder where all spec documents are stored |
-| **[FORBIDDEN]** | Section in `rules.md` — technical prohibitions scanned by AI before coding |
-| **[SELF-REVIEW]** | Short developer reflection after each task: security risk, performance, spec assumption |
-| **Traceability ID** | Stable label (`FEAT-01`, `API-03`) for tracing requirements from PRD to implementation |
-| **Acceptance Criteria** | Concrete conditions for a task to be considered done |
-| **scope** | Developer work boundary: frontend-only, backend-only, or fullstack |
-| **fixMode** | `code-review` preference: report first or fix immediately |
-| **discoveryDepth** | Brainstorm detail level independent from question batching: quick/standard/critical |
-| **availableMCPs** | MCPs listed and available for use in this project |
-| **Confidence Level** | In `spec-init`: High/Medium/Low for claims derived from codebase analysis |
-| **Evidence Inputs** | In `spec-init`: files/sources used as evidence for a claim |
-| **Plan status** | Plan file lifecycle status: `review` → `in-progress` → `code-review` → `done` |
-| **Plan deviation** | Implementation drift from decisions in the plan (library, pattern, scope) — recorded by `code-review` if found |
-| **Definition of Done** | Phase-level evidence checklist derived from applicable specs and quality gates |
-| **Release readiness** | Report-only operational verdict for a specific candidate and target environment |
+| Term                    | Explanation                                                                                                    |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------- |
+| **Skill**               | Full instructions for AI — like an SOP for AI                                                                  |
+| **Spec**                | Planning document containing all decisions before coding                                                       |
+| **Subagent**            | Helper agent for focused exploration/analysis                                                                  |
+| **project-context/**    | Folder where all spec documents are stored                                                                     |
+| **[FORBIDDEN]**         | Section in `rules.md` — technical prohibitions scanned by AI before coding                                     |
+| **[SELF-REVIEW]**       | Short developer reflection after each task: security risk, performance, spec assumption                        |
+| **Traceability ID**     | Stable label (`FEAT-01`, `API-03`) for tracing requirements from PRD to implementation                         |
+| **Acceptance Criteria** | Concrete conditions for a task to be considered done                                                           |
+| **scope**               | Developer work boundary: frontend-only, backend-only, or fullstack                                             |
+| **fixMode**             | `code-review` preference: report first or fix immediately                                                      |
+| **discoveryDepth**      | Brainstorm detail level independent from question batching: quick/standard/critical                            |
+| **availableMCPs**       | MCPs listed and available for use in this project                                                              |
+| **Confidence Level**    | In `spec-init`: High/Medium/Low for claims derived from codebase analysis                                      |
+| **Evidence Inputs**     | In `spec-init`: files/sources used as evidence for a claim                                                     |
+| **Plan status**         | Plan file lifecycle status: `review` → `in-progress` → `code-review` → `done`                                  |
+| **Plan deviation**      | Implementation drift from decisions in the plan (library, pattern, scope) — recorded by `code-review` if found |
+| **Definition of Done**  | Phase-level evidence checklist derived from applicable specs and quality gates                                 |
+| **Release readiness**   | Report-only operational verdict for a specific candidate and target environment                                |
 
 **Traceability ID Scheme:**
 
-| Prefix | Used for |
-|--------|----------------|
-| `FEAT-01` | Main feature in `PRD.md` |
-| `BR-01` | Business rule in `PRD.md` |
-| `NFR-01` | Non-functional requirement in `PRD.md` |
-| `AC-01` | Acceptance Criteria in `PRD.md` |
-| `US-01` | User story in `PRD.md` |
+| Prefix    | Used for                                                           |
+| --------- | ------------------------------------------------------------------ |
+| `FEAT-01` | Main feature in `PRD.md`                                           |
+| `BR-01`   | Business rule in `PRD.md`                                          |
+| `NFR-01`  | Non-functional requirement in `PRD.md`                             |
+| `AC-01`   | Acceptance Criteria in `PRD.md`                                    |
+| `US-01`   | User story in `PRD.md`                                             |
 | `DATA-01` | Datastore-native entity/aggregate/collection/stream in `schema.md` |
-| `API-01` | REST/GraphQL/RPC/event operation in `api.md` |
-| `RULE-01` | Rule in `rules.md` referenced across documents |
+| `API-01`  | REST/GraphQL/RPC/event operation in `api.md`                       |
+| `RULE-01` | Rule in `rules.md` referenced across documents                     |
 
 </details>
 
@@ -1163,12 +1199,12 @@ No. Scope, work mode, additional skills, MCPs, review mode, brainstorm pacing, r
 
 When you choose `plan-first`, AI creates a plan file in `project-context/plans/phase-[N]-[slug].md` before coding starts. The plan has a status header that is updated automatically through this lifecycle:
 
-| Status | Meaning |
-|--------|---------|
-| `review` | The plan was just created — you read and review it first. Type `start` if you agree. |
-| `in-progress` | Coding starts after you type `start`. |
-| `code-review` | All tasks in the phase are complete and are being reviewed by `code-review`. |
-| `done` | Code review is complete. If implementation deviated from the plan (wrong library, different pattern), AI adds a note to the plan. If there is no deviation, status changes to `done` with no note. |
+| Status        | Meaning                                                                                                                                                                                            |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `review`      | The plan was just created — you read and review it first. Type `start` if you agree.                                                                                                               |
+| `in-progress` | Coding starts after you type `start`.                                                                                                                                                              |
+| `code-review` | All tasks in the phase are complete and are being reviewed by `code-review`.                                                                                                                       |
+| `done`        | Code review is complete. If implementation deviated from the plan (wrong library, different pattern), AI adds a note to the plan. If there is no deviation, status changes to `done` with no note. |
 
 Plans are also recognized by `help` (displayed with status) and `add-feature` (updated if the phase is affected).