macca-method 2.0.0 → 2.1.1

package/.agents/macca-lock.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.0.0",
+  "version": "2.1.1",
   "skills": [
     "_shared",
     "add-feature",

package/.agents/skills/_shared/references/fix-mode.md

@@ -11,7 +11,20 @@ Announce `[Fix mode: report-first]` or `[Fix mode: fix-then-report]` at the star
 
 ## Required Report-First Gate
 
-After the full report and fix manifest, print this block verbatim and end the response:
+After the full report and fix manifest, print the block below matching `languagePreferences.communication.normalized` (see `language-config.md`) and end the response. Use only one language block - never mix English and Indonesian inside it.
+
+Indonesian (`indonesian`, `id`, and any equivalent listed in `language-config.md` - also the default when the preference is missing or unrecognized):
+
+```text
+---
+[GATE — Mode: report-first]
+Semua temuan sudah dilaporkan. Belum ada file yang diubah.
+Balas "ya" / "setuju" / "lanjut" / "perbaiki" untuk menerapkan semua perbaikan,
+atau sebutkan temuan mana saja yang ingin diperbaiki.
+---
+```
+
+English (`english`, `en`):
 
 ```text
 ---
@@ -29,8 +42,10 @@ The fix manifest records each actionable finding ID, target, bounded change, and
 This takes precedence over normal routing, startup, identity, onboarding, preflight, and work-mode prompts.
 
 1. Trim and case-fold the next response.
-2. Exact `yes`, `fix`, or `continue` approves every actionable finding in the immediately preceding report, including actionable MINOR findings.
-3. Named IDs approve only those findings.
+2. Any of these approves every actionable finding in the immediately preceding report, including actionable MINOR findings:
+   - English: `yes`, `fix`, `continue`
+   - Indonesian: `ya`, `iya`, `setuju`, `lanjut`, `perbaiki`
+3. Named IDs approve only those findings, in either language.
 4. Resume directly at edits. Do not repeat analysis, the report, startup, preflight, or the same gate.
 5. Ask again only if the worktree changed materially, a target disappeared, findings conflict, or the implementation becomes destructive or exceeds disclosed scope.
 6. Run the narrowest relevant validation and one bounded verdict pass: `resolved`, `partial`, or `unresolved`.

package/.agents/skills/_shared/references/human-loop.md

@@ -54,4 +54,4 @@ Keep one decision topic per pause.
 
 After the user answers, continue from the exact paused step. Do not restart the workflow or ask for the same confirmation again unless the situation materially changes.
 
-An answer to an active gate takes precedence over normal skill startup and routing. For a report-first gate, exact `yes`, `fix`, or `continue` and finding-ID subsets follow the Approval Resume Protocol in `fix-mode.md`. Do not send them through identity setup, preflight, or a second confirmation.
+An answer to an active gate takes precedence over normal skill startup and routing. For a report-first gate, the approval tokens and finding-ID subsets defined in `fix-mode.md`'s Approval Resume Protocol take priority. Do not send them through identity setup, preflight, or a second confirmation.

package/.agents/skills/_shared/references/language-config.md

@@ -4,12 +4,14 @@ Read `.agents/developer-config.json` if it exists.
 
 Use:
 
-- `languagePreferences.communication.normalized` for chat, reports, prompts, and confirmations.
+- `languagePreferences.communication.normalized` for chat, reports, prompts, confirmations, and gate/approval text.
 - `languagePreferences.documents.normalized` for generated project documents.
 
-Accepted reader values:
+When the resolved language is Indonesian, all chat output - including report-first gates and their reply options - MUST be Indonesian. Do not mix in English sentences or fall back to English-only reply tokens.
 
-- Indonesian: `indonesian`, `id`
-- English: `english`, `en`
+Match `raw` or `normalized` case-insensitively against these equivalents (same mapping the installer's `normalizeLanguage()` uses):
 
-If missing, use Indonesian. Never translate file names, traceability IDs, config keys, or code literals.
+- Indonesian: `indonesian`, `id`, `indo`, `indonesia`, `bahasa indonesia`
+- English: `english`, `en`, `eng`, `inggris`, `bahasa inggris`
+
+If missing or unrecognized, use Indonesian. Never translate file names, traceability IDs, config keys, or code literals.

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

@@ -11,6 +11,8 @@ metadata:
 
 ## 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.
+
 At startup:
 
 1. Read `../_shared/references/language-config.md`.

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

@@ -34,15 +34,17 @@ You are **@Fachri — Tech Lead**, a **Senior API Architect** who designs clear,
 
 ## 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/api.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/api.md`.
+7. Apply `brainstormPreferences.discussionMode`, `recommendations`, and `discoveryDepth` using the shared session policy.
 
 ---
 

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

@@ -34,15 +34,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.
 
 ---
 

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

@@ -34,15 +34,17 @@ You are an experienced **Product Manager** who turns raw ideas into clear, actio
 
 ## 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/PRD.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/PRD.md`.
+7. Apply `brainstormPreferences.discussionMode`, `recommendations`, and `discoveryDepth` using the shared session policy.
 
 ---
 

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

@@ -44,7 +44,7 @@ This skill generates **rules.md**: a "code constitution" so AI works consistentl
     - `project-context/schema.md` — decisions about PII, retention, data protection
     - `project-context/api.md` — auth contract, rate limiting, abuse controls
 
-3. **Shared Runtime Setup** — before the interview:
+3. **Shared Runtime Setup** — before the interview (paths written as `../...` are relative to this SKILL.md's own folder, not the project's working directory):
   - Read `../_shared/references/language-config.md`.
   - Read `../_shared/references/config-mutation.md`.
   - Read `../_shared/references/brainstorm-session.md`.
@@ -58,7 +58,7 @@ This skill generates **rules.md**: a "code constitution" so AI works consistentl
 
 5. After all topics are complete, create `project-context/rules.md` (create `project-context/` if needed).
 
-   > ⚠️ **If the file already exists:** ask the user before overwriting — "(A) Replace the entire file, (B) cancel and review first." Wait for the answer.
+   > ⚠️ **If the file already exists:** "(A) Overwrite all, (B) Cancel and review first." Wait for the answer.
 
 6. Summarize the result and provide next steps.
 

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

@@ -34,15 +34,17 @@ You are **@Fachri — Tech Lead**, a **Senior Database Architect** who designs e
 
 ## 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/schema.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/schema.md`.
+7. Apply `brainstormPreferences.discussionMode`, `recommendations`, and `discoveryDepth` using the shared session policy.
 
 ---
 

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

@@ -43,7 +43,7 @@ This skill generates **StyleGuide.md** through an interactive interview. It prev
     - `project-context/architecture.md` — chosen frontend tech stack
     - If `.agents/developer-config.json` exists, read `developerPreferences.scope`
 
-3. **Shared Runtime Setup** — before the interview:
+3. **Shared Runtime Setup** — before the interview (paths written as `../...` are relative to this SKILL.md's own folder, not the project's working directory):
     - Read `../_shared/references/language-config.md`.
     - Read `../_shared/references/config-mutation.md`.
     - Read `../_shared/references/brainstorm-session.md`.
@@ -59,7 +59,7 @@ This skill generates **StyleGuide.md** through an interactive interview. It prev
 
 6. After all topics are complete, create `project-context/StyleGuide.md` (create `project-context/` if needed).
 
-   > ⚠️ **If the file already exists:** ask the user before overwriting — "(A) Replace the entire file, (B) cancel and review first." Wait for the answer.
+   > ⚠️ **If the file already exists:** "(A) Overwrite all, (B) Cancel and review first." Wait for the answer.
 
 7. Summarize the result and provide next steps.
 

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

@@ -11,6 +11,8 @@ metadata:
 
 ## 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 starting:
 
 1. Read `../_shared/references/language-config.md`.

package/.agents/skills/bug-fix/SKILL.md

@@ -11,14 +11,16 @@ metadata:
 
 ## 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 continuing:
 
 1. Read `../_shared/references/language-config.md`.
 2. Read `../_shared/references/fix-mode.md`.
 3. Read `../_shared/references/human-loop.md`.
-3. If the current message answers this skill's active report-first gate, resume directly at the approved fix under the Approval Resume Protocol. Do not repeat diagnosis or ask again.
-4. Otherwise, read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If it is missing, treat it as `"report-first"`. Announce: `[Fix mode: report-first]` or `[Fix mode: fix-then-report]`.
-5. Use `languagePreferences.communication.normalized` for all chat output.
+4. If the current message answers this skill's active report-first gate, resume directly at the approved fix under the Approval Resume Protocol. Do not repeat diagnosis or ask again.
+5. Otherwise, read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If it is missing, treat it as `"report-first"`. Announce: `[Fix mode: report-first]` or `[Fix mode: fix-then-report]`.
+6. Use `languagePreferences.communication.normalized` for all chat output.
 
 ---
 
@@ -107,9 +109,9 @@ Before reading code, use every available aid:
 - Search for the same bug pattern across the codebase now, before the gate. Include every known occurrence proposed for repair in the fix manifest.
 - Relevant specs (`project-context/architecture.md`, `schema.md`, etc.) if the bug spans multiple layers
 
-### 2c. Explain the diagnosis to the user
+### 2c. Explain the diagnosis and propose the fix - one response
 
-MUST use EXACTLY these 3 points. MUST NOT show code - explain only in working logic:
+MUST use EXACTLY these points, in this order, in a single response. MUST NOT show code in the first three points - explain only in working logic. This response does not end here - continue straight into the gate in 2d; do not stop after "Recommended fix" and wait for a separate reply:
 
 ```
 **Why can this happen?**
@@ -120,14 +122,19 @@ MUST use EXACTLY these 3 points. MUST NOT show code - explain only in working lo
 
 **Recommended fix**
 [Explain what needs to change in the logic and flow, not syntax. Speak as if explaining how the app works.]
+
+**Files to change**
+- `[path]` - [bounded change]
+- `[path]` - [bounded change]
 ```
 
 ### 2d. Root-Cause Approval Gate
 
-Include the root cause, proposed files, bounded changes, and validation in the same diagnosis response.
+End the SAME response as 2c with the `report-first` gate block from `fix-mode.md`, in the language required by `language-config.md`.
 
 - Always wait for explicit user approval before the first code change, regardless of `fixMode`.
-- Reuse the shared report-first gate wording when the diagnosis is presented as a report-style approval.
+- MUST NOT split 2c and 2d across two responses - the diagnosis, the files to change, and the gate are one message, one turn.
+- MUST NOT invent an alternate approval question (for example "reply agree" or "balas setuju"). Use only the exact gate block from `fix-mode.md`.
 - After the first implementation approval, `fixMode` governs downstream `spec-compliance` and `code-review` remediation only.
 - Do not add another implementation approval gate in Step 3.
 

package/.agents/skills/code-review/SKILL.md

@@ -11,6 +11,8 @@ metadata:
 
 ## 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 continuing:
 
 1. Read `../_shared/references/language-config.md`.

package/.agents/skills/developer/SKILL.md

@@ -11,6 +11,8 @@ metadata:
 
 ## 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 continuing:
 
 1. Read `../_shared/references/language-config.md`.

package/.agents/skills/developer/references/onboarding.md

@@ -7,7 +7,7 @@ Read this file only when identity/config/work mode is incomplete or plan-first m
 If `additionalSkills` is missing:
 
 1. Ask once whether the project uses framework/domain skills.
-2. For each named skill, search `.agents/skills/`, `.github/skills/`, `.opencode/skills/`, then matching workspace folders.
+2. For each named skill, search every MACCA tool destination: `.agents/skills/` (codex/kimi), `.github/skills/` (copilot), `.opencode/skills/`, `.claude/skills/`, `.cursor/skills/`, `.windsurf/skills/`, `.gemini/skills/`, `.kilo/skills/`. If none match, also check the global equivalents `~/.config/opencode/skills/`, `~/.claude/skills/`, and `~/.agents/skills/`. Only then fall back to matching workspace folders.
 3. If found, record its path. If absent, ask for the path or allow `skip`.
 4. Before saving, load `../../_shared/references/additional-skills.md` and use its canonical `paths` shape.
 

package/.agents/skills/help/SKILL.md

@@ -11,12 +11,14 @@ metadata:
 
 ## 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.
+
 At startup:
 
 1. Read `../_shared/references/language-config.md`.
 2. Read `../_shared/references/scope-rules.md`.
 3. Read `../_shared/references/invocation-policy.md` when explaining how a skill is activated.
-3. Use `languagePreferences.communication.normalized` for all chat output, reports, and guidance.
+4. Use `languagePreferences.communication.normalized` for all chat output, reports, and guidance.
 
 ---
 
@@ -46,8 +48,10 @@ You are a patient **Mentor and Guide** who explains complex systems with everyda
 
 Check whether the `project-context/` folder exists:
 - **No:** first check whether a real codebase already exists (for example `package.json`, `composer.json`, `go.mod`, `src/`, `app/`, `artisan`, `routes/`).
-  - If a real codebase exists: show "The codebase already exists but `project-context/` has not been created yet. Start with `spec-init`." Then stop.
-  - If no real codebase exists: show "No spec documents exist yet. This is a new project. Start with `brainstorm-prd` to create the PRD." Then stop.
+  - Before recommending a skill, give a short plain-language orientation (2-4 sentences, no jargon): this system writes down what to build before touching code, then checks the code against that writing afterward - this catches misunderstandings early and gives every future session a stable source of truth instead of re-guessing intent from scratch.
+  - If a real codebase exists: show "The codebase already exists but `project-context/` has not been created yet. Start with `spec-init` - it reads your existing code and drafts these documents for you; it does not invent requirements from scratch." Then stop.
+  - If no real codebase exists: show "No spec documents exist yet. This is a new project. Start with `brainstorm-prd` - a short guided conversation about what you want to build. Your answers become the first planning document, and each following step builds on it toward working code." Then stop.
+  - Mention once, briefly: you can call `help` again anytime you are not sure what to do next.
 - **Yes:** Continue and read whichever files exist.
 
 Check for the existence of:

package/.agents/skills/meet/SKILL.md

@@ -11,6 +11,8 @@ metadata:
 
 ## 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.
+
 At startup:
 
 1. Read `../_shared/references/language-config.md`.

package/.agents/skills/quick-dev/SKILL.md

@@ -11,6 +11,8 @@ metadata:
 
 ## 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 (this also applies to the `../developer/references/...` reads later in this file).
+
 Before any output:
 
 1. Read `../_shared/references/language-config.md`.
@@ -79,7 +81,7 @@ Read `additionalSkills` and `availableMCPs` from `.agents/developer-config.json`
 Read `developerPreferences.scope` from `.agents/developer-config.json`.
 
 - **Exists:** show `[Scope: frontend / backend / fullstack]`. Tell the user to correct now if needed.
-- **Missing:** ask once using the same question as `developer` Step 0c. Save answer.
+- **Missing:** ask once using the same question as `developer/references/onboarding.md` § Developer Scope. Save answer.
 
 ---
 
@@ -146,7 +148,7 @@ Scan `[FORBIDDEN]` in `rules.md` before any coding.
 
 ## Step 2b — Record an Approved Scope Delta Before Coding
 
-If the task is outside `project-context/`, follow the approval flow from `developer` Step 3a before editing code. After approval, create or update the lightweight `Task.md` entry immediately with `status: in-progress` and the delta details. If `Task.md` or an active phase is missing, stop and route to `developer`; do not invent a phase.
+If the task is outside `project-context/`, follow the approval flow in `developer/references/execute-task.md` § Understand and Protect Scope before editing code. After approval, create or update the lightweight `Task.md` entry immediately with `status: in-progress` and the delta details. If `Task.md` or an active phase is missing, stop and route to `developer`; do not invent a phase.
 
 ## Step 3 — Execute
 
@@ -186,7 +188,7 @@ If a scope delta exists, record it inline:
 1. Run `spec-compliance`. Follow `fixMode` from Shared Runtime Setup.
 2. Run `code-review`. Follow `fixMode` from Shared Runtime Setup.
 
-Both follow the same gate behavior as `developer` Step 4. Do not proceed to Step 6 until both pass.
+Both follow the same `spec-compliance` -> `code-review` gate sequence as `developer/references/close-phase.md`. Do not proceed to Step 6 until both pass.
 
 ---
 

package/.agents/skills/release-readiness/SKILL.md

@@ -11,6 +11,8 @@ metadata:
 
 ## Shared 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.
+
 1. Read `../_shared/references/language-config.md`.
 2. Use the configured communication language.
 3. This skill is report-only. Do not edit files, run deployment, publish packages, rotate secrets, apply migrations, or change infrastructure.

package/.agents/skills/spec-audit/SKILL.md

@@ -11,14 +11,16 @@ metadata:
 
 ## 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.
+
 At startup:
 
 1. Read `../_shared/references/language-config.md`.
 2. Read `../_shared/references/fix-mode.md`.
 3. Read `../_shared/references/human-loop.md`.
-3. If this message answers this skill's active correction gate, resume directly under the Approval Resume Protocol. Do not rerun startup or the audit.
-4. Otherwise, read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If it is missing, treat it as `"report-first"`. Announce: `[Fix mode: report-first]` or `[Fix mode: fix-then-report]`.
-5. Use `languagePreferences.communication.normalized` for audit reports.
+4. If this message answers this skill's active correction gate, resume directly under the Approval Resume Protocol. Do not rerun startup or the audit.
+5. Otherwise, read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If it is missing, treat it as `"report-first"`. Announce: `[Fix mode: report-first]` or `[Fix mode: fix-then-report]`.
+6. Use `languagePreferences.communication.normalized` for audit reports.
 
 ---
 

package/.agents/skills/spec-compliance/SKILL.md

@@ -11,15 +11,17 @@ metadata:
 
 ## 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 continuing:
 
 1. Read `../_shared/references/language-config.md`.
 2. Read `../_shared/references/fix-mode.md`.
 3. Read `../_shared/references/human-loop.md`.
 4. Read `../_shared/references/finding-format.md`.
-3. If this message answers this skill's active report-first gate, resume directly under the Approval Resume Protocol. Do not rerun startup or compliance analysis.
-4. Otherwise, read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If it is missing, treat it as `"report-first"`. Announce: `[Fix mode: report-first]` or `[Fix mode: fix-then-report]`.
-5. Use `languagePreferences.communication.normalized` for all user-facing reports and review output.
+5. If this message answers this skill's active report-first gate, resume directly under the Approval Resume Protocol. Do not rerun startup or compliance analysis.
+6. Otherwise, read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If it is missing, treat it as `"report-first"`. Announce: `[Fix mode: report-first]` or `[Fix mode: fix-then-report]`.
+7. Use `languagePreferences.communication.normalized` for all user-facing reports and review output.
 
 ---
 

package/.agents/skills/spec-init/SKILL.md

@@ -11,6 +11,8 @@ metadata:
 
 ## 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 starting:
 
 1. Read `../_shared/references/language-config.md`.

package/README.md

@@ -305,7 +305,7 @@ Conditional rules are generated only when applicable: structured logging, migrat
 **Step 0 — Identify name & project**
 Read `.agents/developer-config.json`. If `name` or `project` is missing, AI asks once and saves the answer.
 
-**Step 0b — Setup additional skills & MCP**
+**Additional skills & MCP setup** (`references/onboarding.md`)
 
 *Additional Skills:*
 - If `additionalSkills` already exists in config → use it directly
@@ -318,7 +318,7 @@ Read `.agents/developer-config.json`. If `name` or `project` is missing, AI asks
 - If not → AI asks once: *"Which MCPs are available in your workspace?"*
 - Only listed MCPs will be used.
 
-**Step 0c — Set developer scope**
+**Developer scope** (`references/onboarding.md`)
 - If `developerPreferences.scope` already exists → use it directly
 - If not → AI asks once:
   ```
@@ -329,7 +329,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.
 
-**Step 1b — Choose work mode**
+**Work mode** (`references/onboarding.md`)
 - If `developerPreferences.workMode` already exists → use it directly
 - If not → AI asks once:
   ```
@@ -344,7 +344,7 @@ Read `.agents/developer-config.json`. If `name` or `project` is missing, AI asks
   status: done        ← when code-review is complete
   ```
 
-**Step 2 — Select relevant specs + enforce scope**
+**Selecting relevant specs** (`references/execute-task.md`)
 
 | Condition | Read |
 |---------|--------|
@@ -356,7 +356,7 @@ Read `.agents/developer-config.json`. If `name` or `project` is missing, AI asks
 
 Scope enforcement: if `scope=frontend`, AI does not touch backend files. If `scope=backend`, AI does not touch frontend files.
 
-**Step 3 — Execute tasks one by one**
+**Executing tasks** (`references/execute-task.md`)
 
 For each task:
 1. Understand the task and acceptance criteria
@@ -376,7 +376,7 @@ Developer loads workflow references by state, not all at once:
 - `execute-task.md` only for the current task
 - `close-phase.md` only when closing a phase/project
 
-**Step 4 — After all tasks in the phase are complete**
+**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`
@@ -920,7 +920,7 @@ The updater uses the MACCA files inside `.agents/` to know which installed skill
 
 > `project-context/` and `developer-config.json` are **not touched** during upgrade.
 
-`2.0.0` is a major release because skill naming, workflow contracts, progressive disclosure, and release checks changed. The published `1.1.0` OpenCode layout is covered by an automated upgrade test. For reproducible CI/bootstrap, pin the desired version; for interactive upgrades, use `@latest` as shown above.
+`2.0.x` is the major-release line for the skill naming, workflow contract, progressive disclosure, and release-check changes. The published `1.1.0` OpenCode layout is covered by an automated upgrade test. For reproducible CI/bootstrap, pin the desired version; for interactive upgrades, use `@latest` as shown above.
 
 ### How to Call a Skill
 
@@ -1051,14 +1051,14 @@ The `.agents/developer-config.json` file is shared config across skills. All ski
 | `name` | `developer` (Step 0) | Asked once |
 | `project` | `developer` (Step 0) | Asked once |
 | `languagePreferences` | installer / first skill | Communication language and document language |
-| `developerPreferences.workMode` | `developer` (Step 1b) | `"direct"` or `"plan-first"` |
-| `developerPreferences.scope` | `developer` (Step 0c) | `"frontend"`, `"backend"`, or `"fullstack"` |
+| `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` (Step 0b) | AI searches for the path in the workspace first, then asks only if it is not found |
-| `availableMCPs` | `developer` (Step 0b) | Available MCPs; only listed MCPs are used |
+| `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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "macca-method",
-    "version": "2.0.0",
+    "version": "2.1.1",
     "description": "CLI installer for MACCA AI spec-driven development skills.",
     "license": "MIT",
     "scripts": {

package/scripts/test-install.js

@@ -10,7 +10,7 @@ const { execFileSync } = require("node:child_process");
 
 const rootDir = path.resolve(__dirname, "..");
 const mode = process.argv.includes("--published") ? "published" : "local";
-const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "macca-test-install-"));
+const tmpDir = fs.mkdtempSync(path.join(resolveTempRoot(), "macca-test-install-"));
 const projectDir = path.join(tmpDir, "project");
 const collisionDir = path.join(tmpDir, "collision-project");
 const symlinkDir = path.join(tmpDir, "symlink-project");
@@ -18,7 +18,39 @@ const driftDir = path.join(tmpDir, "drift-project");
 let packageSpec = "macca-method";
 
 function commandName(base) {
-    return process.platform === "win32" ? `${base}.cmd` : base;
+    if (process.platform !== "win32") {
+        return base;
+    }
+
+    return base === "npm" || base === "npx" ? `${base}.cmd` : base;
+}
+
+function resolveTempRoot() {
+    const tempRoot = os.tmpdir();
+    try {
+        return fs.realpathSync(tempRoot);
+    } catch {
+        return tempRoot;
+    }
+}
+
+function runNpm(args, options = {}) {
+    const npmExecPath = process.env.npm_execpath;
+    if (npmExecPath && /\.c?js$/i.test(npmExecPath)) {
+        return capture(process.execPath, [npmExecPath, ...args], options);
+    }
+
+    return capture(commandName("npm"), args, options);
+}
+
+function runNpmWithInheritedStdio(args, options = {}) {
+    const npmExecPath = process.env.npm_execpath;
+    if (npmExecPath && /\.c?js$/i.test(npmExecPath)) {
+        run(process.execPath, [npmExecPath, ...args], options);
+        return;
+    }
+
+    run(commandName("npm"), args, options);
 }
 
 function run(command, args, options = {}) {
@@ -39,22 +71,22 @@ function capture(command, args, options = {}) {
 
 function runCli(args) {
     if (mode === "published") {
-        run(commandName("npx"), ["--yes", "macca-method", ...args]);
+        runNpmWithInheritedStdio(["exec", "--yes", "--package", "macca-method", "--", "macca-method", ...args]);
         return;
     }
 
-    run(commandName("npx"), ["--yes", "--package", packageSpec, "macca-method", ...args]);
+    runNpmWithInheritedStdio(["exec", "--yes", "--package", packageSpec, "--", "macca-method", ...args]);
 }
 
 function expectCliFailure(args, expectedText) {
     try {
         if (mode === "published") {
-            capture(commandName("npx"), ["--yes", "macca-method", ...args], { cwd: rootDir, stdio: "pipe" });
+            runNpm(["exec", "--yes", "--package", "macca-method", "--", "macca-method", ...args], { cwd: rootDir, stdio: "pipe" });
         } else {
-            capture(commandName("npx"), ["--yes", "--package", packageSpec, "macca-method", ...args], { cwd: rootDir, stdio: "pipe" });
+            runNpm(["exec", "--yes", "--package", packageSpec, "--", "macca-method", ...args], { cwd: rootDir, stdio: "pipe" });
         }
     } catch (error) {
-        const output = `${error.stdout || ""}${error.stderr || ""}`;
+        const output = `${error.stdout || ""}${error.stderr || ""}${error.message || ""}`;
         if (!output.includes(expectedText)) {
             throw new Error(`Expected failed command to include ${expectedText}, got: ${output}`);
         }
@@ -109,7 +141,7 @@ function ensureExpectedTools(filePath) {
 }
 
 function resolveLocalPackage() {
-    const packOutput = capture(commandName("npm"), ["pack", "--json", "--pack-destination", tmpDir]);
+    const packOutput = runNpm(["pack", "--json", "--pack-destination", tmpDir]);
     const packageList = JSON.parse(packOutput);
 
     if (!Array.isArray(packageList) || packageList.length === 0 || !packageList[0].filename) {

package/scripts/test-upgrade-legacy.js

@@ -8,12 +8,44 @@ const path = require("node:path");
 const { execFileSync } = require("node:child_process");
 
 const rootDir = path.resolve(__dirname, "..");
-const temporaryRoot = fs.mkdtempSync(path.join(os.tmpdir(), "macca-legacy-upgrade-"));
+const temporaryRoot = fs.mkdtempSync(path.join(resolveTempRoot(), "macca-legacy-upgrade-"));
 const projectDir = path.join(temporaryRoot, "project");
 const obsoleteMeetingName = Buffer.from("cmFwYXQ=", "base64").toString("utf8");
 
 function commandName(base) {
-    return process.platform === "win32" ? `${base}.cmd` : base;
+    if (process.platform !== "win32") {
+        return base;
+    }
+
+    return base === "npm" || base === "npx" ? `${base}.cmd` : base;
+}
+
+function resolveTempRoot() {
+    const tempRoot = os.tmpdir();
+    try {
+        return fs.realpathSync(tempRoot);
+    } catch {
+        return tempRoot;
+    }
+}
+
+function captureNpm(args, options = {}) {
+    const npmExecPath = process.env.npm_execpath;
+    if (npmExecPath && /\.c?js$/i.test(npmExecPath)) {
+        return capture(process.execPath, [npmExecPath, ...args], options);
+    }
+
+    return capture(commandName("npm"), args, options);
+}
+
+function runNpm(args, options = {}) {
+    const npmExecPath = process.env.npm_execpath;
+    if (npmExecPath && /\.c?js$/i.test(npmExecPath)) {
+        run(process.execPath, [npmExecPath, ...args], options);
+        return;
+    }
+
+    run(commandName("npm"), args, options);
 }
 
 function run(command, args, options = {}) {
@@ -43,7 +75,7 @@ function assertMissing(targetPath) {
 try {
     fs.mkdirSync(projectDir, { recursive: true });
 
-    const legacyPackOutput = capture(commandName("npm"), [
+    const legacyPackOutput = captureNpm([
         "pack",
         "macca-method@1.1.0",
         "--json",
@@ -53,10 +85,12 @@ try {
     const legacyPackageList = JSON.parse(legacyPackOutput);
     const legacyPackageSpec = path.join(temporaryRoot, legacyPackageList[0].filename);
 
-    run(commandName("npx"), [
+    runNpm([
+        "exec",
         "--yes",
         "--package",
         legacyPackageSpec,
+        "--",
         "macca-method",
         "install",
         "--yes",
@@ -77,14 +111,16 @@ try {
     const legacyRoot = path.join(projectDir, ".opencode", "skill");
     assertExists(path.join(legacyRoot, obsoleteMeetingName, "SKILL.md"));
 
-    const packOutput = capture(commandName("npm"), ["pack", "--json", "--pack-destination", temporaryRoot]);
+    const packOutput = captureNpm(["pack", "--json", "--pack-destination", temporaryRoot]);
     const packageList = JSON.parse(packOutput);
     const packageSpec = path.join(temporaryRoot, packageList[0].filename);
 
-    run(commandName("npx"), [
+    runNpm([
+        "exec",
         "--yes",
         "--package",
         packageSpec,
+        "--",
         "macca-method",
         "upgrade",
         "--directory",