macca-method 2.1.2 → 3.0.0-rc.1

package/docs/configuration.md

@@ -0,0 +1,174 @@
+# Configuration
+
+[README](../README.md) · [Workflows](workflows.md) · [Troubleshooting](troubleshooting.md)
+
+MACCA shares preferences across AI hosts through `.agents/developer-config.json`. Configuration is optional for ordinary work. Use [setup-macca-method](../.agents/skills/setup-macca-method/SKILL.md), operated by Galbi, when you explicitly want to inspect or save preferences.
+
+## Show, set up, or change one preference
+
+| Request | Result |
+| --- | --- |
+| “Show my MACCA settings.” | Read-only summary of saved values, effective defaults **not saved**, session-only choices, and unconfigured choices. An absent file stays absent. |
+| “Set up MACCA preferences.” | Ask only for missing preferences you want to choose. Name/project are optional; skipped choices and inferred defaults are not saved. |
+| “Set only document language to English.” | Update only that channel's `raw` and `normalized` leaves, preserving its extensions and every unrelated setting. Exact intent already supplies consent. |
+| “Use English for this reply.” | Session-only instruction, not a request to persist a preference. |
+
+Setup alone does not create specs or begin implementation. `help` reads and routes settings requests to setup. Other workflows may save a specific explicitly chosen preference under the same mutation contract, without starting a full setup interview.
+
+Preference changes apply on the next config read. Restart the AI host when installing/upgrading skill files so it can discover those files; that is separate from reading a changed preference.
+
+## Supported fields: an example, not a required form
+
+This is documentation of supported shapes, **not a JSON Schema file**. Every top-level field is optional; known fields that are present must have the expected types and values. The shared validator accepts unknown extensions without rewriting them. This illustrative configuration is not a list of installed or automatically authorized tools in your project:
+
+```json
+{
+  "name": "Your name",
+  "project": "Project name",
+  "languagePreferences": {
+    "communication": {
+      "raw": "Bahasa Indonesia",
+      "normalized": "indonesian"
+    },
+    "documents": {
+      "raw": "English",
+      "normalized": "english"
+    }
+  },
+  "developerPreferences": {
+    "workMode": "direct",
+    "scope": "fullstack"
+  },
+  "brainstormPreferences": {
+    "discussionMode": "one-by-one",
+    "recommendations": true,
+    "discoveryDepth": "standard"
+  },
+  "codeReviewPreferences": {
+    "fixMode": "report-first"
+  },
+  "additionalSkills": [
+    {
+      "name": "laravel-best-practices",
+      "purpose": "Use when writing Laravel code",
+      "paths": {
+        "copilot": ".github/skills/laravel-best-practices/SKILL.md",
+        "opencode": ".opencode/skills/laravel-best-practices/SKILL.md",
+        "codex": ".agents/skills/laravel-best-practices/SKILL.md"
+      }
+    }
+  ],
+  "availableMCPs": ["context7", "supabase"]
+}
+```
+
+| Field | Accepted shape and meaning |
+| --- | --- |
+| `name`, `project` | Optional strings; save labels only when chosen. |
+| `languagePreferences.communication`, `.documents` | Objects with optional string `raw` and `normalized` fields; resolution is described below. |
+| `developerPreferences.workMode` | `direct` or `plan-first`. With no saved mode, explicit task intent can resolve the current mode without saving it. |
+| `developerPreferences.scope` | `frontend`, `backend`, or `fullstack`. Architecture defines file boundaries; missing scope is not unrestricted implementation permission. |
+| `brainstormPreferences.discussionMode` | `one-by-one`, `three-at-a-time`, or `all-at-once`; controls question batching. |
+| `brainstormPreferences.recommendations` | Boolean; `false` is a valid saved choice, not a missing value. |
+| `brainstormPreferences.discoveryDepth` | `quick`, `standard`, or `critical`; controls depth independently of pacing. Evidence can escalate session depth without saving an inferred preference. |
+| `codeReviewPreferences.fixMode` | `report-first` or `fix-then-report`; missing means effective `report-first`. Existing workflow approval gates still apply. |
+| `additionalSkills` | Array of objects with a nonempty `name`, optional string `purpose`, optional `paths` object with string values under host keys, and optional string legacy path fields. |
+| `availableMCPs` | Array of nonempty tool-name strings, or legacy string `"none"`. It records authorization restrictions, not proof of availability. |
+
+See [workflow gates](workflows.md#understand-the-two-quality-gates) and the [brainstorm policy](../.agents/skills/_shared/references/brainstorm-session.md) for how preferences affect execution.
+
+## Languages resolve independently
+
+For each channel, readers trim and case-fold `normalized`, try `raw` if it is missing or unrecognized, then fall back to Indonesian. They do not copy the other channel's value.
+
+| Language | Recognized equivalents |
+| --- | --- |
+| Indonesian | `indonesian`, `id`, `indo`, `indonesia`, `bahasa indonesia` |
+| English | `english`, `en`, `eng`, `inggris`, `bahasa inggris` |
+
+New saved choices use canonical `indonesian` or `english`. Existing aliases, empty strings, and unknown strings are reader-resolution concerns; they do not trigger an on-disk rewrite. A fallback is shown as an **effective default (not saved)**. Filenames, IDs, config keys, and code literals remain unchanged. See [language-config.md](../.agents/skills/_shared/references/language-config.md).
+
+The **installer's bootstrap defaults** are distinct: on a fresh interactive install, Enter selects Indonesian communication and documents matching the chosen communication language. A fresh unattended install uses those defaults unless flags override them. The setup skill does not materialize skipped defaults, and later runtime language reads remain independent. See [installer options](troubleshooting.md#commands-and-accepted-options).
+
+## Additional skills and MCP authorization
+
+Distinguish **installed** (on disk), **available** (exposed/resolvable in the host), and **allowed** (authorized for the task and permitted by the host). Discovery does not execute or install a discovered skill/tool, register an entire scan, or override host permissions.
+
+- Missing `additionalSkills` or `availableMCPs` means not configured, not blanket permission. Applicable user/host instructions still determine authorization.
+- `additionalSkills: []` explicitly authorizes no additional skills.
+- `availableMCPs: []` and `availableMCPs: "none"` explicitly deny MCP use. The string `"none"` is a compatibility form for MCPs, not for `additionalSkills`.
+- Save only explicitly authorized names and resolved paths. Do not invent another host's path or remove a restriction because a tool is unavailable today.
+
+Canonical additional-skill paths use `paths[currentHost]`. Readers fall back to `path`, then the matching legacy field: `githubPath`, `opencodePath`, `claudePath`, `cursorPath`, `windsurfPath`, `geminiPath`, `kiloPath`, `kimiPath`, or `codexPath`. Preserve legacy paths and other host entries during unrelated updates. A skill list is an array of objects, not an array of strings or a keyed object.
+
+For a needed user-named skill with an unresolved path, permitted discovery checks supported workspace locations and global locations such as `~/.config/opencode/skills/`, `~/.claude/skills/`, and `~/.agents/skills/` before asking for its location. Uninspectable locations are unverified, not absent. Details: [additional-skills.md](../.agents/skills/_shared/references/additional-skills.md).
+
+## Settings versus installed host files
+
+The MACCA installer places the complete skill collection, including `_shared`, into the selected project-local destinations:
+
+| AI host | CLI key (accepted alias) | Skills folder |
+| --- | --- | --- |
+| GitHub Copilot | `copilot` (`github-copilot`) | `.github/skills/` |
+| Cursor | `cursor` | `.cursor/skills/` |
+| Claude Code | `claude` (`claude-code`) | `.claude/skills/` |
+| Windsurf | `windsurf` | `.windsurf/skills/` |
+| Gemini CLI | `gemini` (`gemini-cli`) | `.gemini/skills/` |
+| OpenCode | `opencode` | `.opencode/skills/` |
+| Kilo Code | `kilo` (`kilo-code`) | `.kilo/skills/` |
+| Codex | `codex` (`openai-codex`) | `.agents/skills/` |
+| Kimi CLI | `kimi` (`kimi-cli`) | `.agents/skills/` |
+
+These folders hold instructions, not per-host copies of developer preferences. The shared `.agents/` metadata includes selected hosts (`macca-tools.txt`), managed skill names (`macca-managed-skills.txt`), the package/payload lock (`macca-lock.json`), metadata fingerprints (`macca-state.json`), and a transaction journal during an interrupted update (`macca-transaction.json`). They serve installation and recovery, not user preference editing.
+
+Changing `additionalSkills` or `availableMCPs` does not install host files or configure an MCP server. Use `install` to add a supported host destination and restart that host. Project specs, task plans, and confirmed bug logs are created later by their owning workflows in `project-context/`.
+
+## Validation, preservation, and privacy
+
+The [config-mutation contract](../.agents/skills/_shared/references/config-mutation.md) requires:
+
+```text
+Validate existing config → merge only authorized leaves → validate full candidate
+→ recheck current target identity/content → guarded write → validate final file
+```
+
+An invalid existing file stops an update unchanged; a setting request does not authorize replacing it with defaults. Unknown and unrelated fields survive at every level, including language-channel extensions, testing preferences, and legacy paths. Concurrent changes must be preserved, not overwritten by a stale candidate.
+
+Store no API keys, passwords, tokens, connection credentials, or environment secrets in this file. Settings display uses the validated allowlisted summary described below. Diagnostics report field/type errors, not source excerpts.
+
+### Safe preference reader
+
+Every skill loads the [safe preference reader](../.agents/skills/_shared/scripts/read-preferences.js) by default through [language-config.md](../.agents/skills/_shared/references/language-config.md):
+
+```bash
+node .agents/skills/_shared/scripts/read-preferences.js .agents/developer-config.json
+```
+
+Replace `.agents/skills` with the selected host's installed skills folder. The reader requires its sibling `config-validator.js` and emits a JSON summary with a **closed vocabulary**: fixed keys, canonical languages, finite preference choices, booleans, counts, and `null`; **no free-form strings** from configuration are returned.
+
+- Each language channel returns `configured`, `effective` (`indonesian` or `english`), and `source` (`normalized`, `raw`, or `default`). The `raw` source label never includes the saved raw text.
+- Known developer, brainstorm, and review fields return `{ configured, value }`. Missing choices are `null`; `false` stays `false`.
+- Identity returns only `nameSet` and `projectSet`. Additional skills and MCPs return only configured/count indicators, plus MCP `denied`. Names, purposes, paths, tool names, and unknown extension keys/values are withheld.
+- Exit **0** with `absent: true` means config is missing; effective language defaults are **not saved**, and no file or parent directory is created. A present valid file has `absent: false`.
+- Exit **1** reports a redacted error for invalid/unreadable input, a symlink/nonregular file, input over 1 MiB, or unavailable safe reading/validation. Reads do not write or change permissions.
+
+If the helper, sibling validator, Node.js runtime, safe file-reading support, or permitted execution is unavailable, stop affected **config-dependent work** and report that preferences could not be checked. There is **no raw-file fallback**, and helper failure must not be presented as absent config. Work independent of those preferences can continue; optional config need not be created.
+
+The summary intentionally cannot resolve a skill path or identify an allowed tool. An already-authorized targeted lookup may validate and inspect the necessary field locally under the [config-mutation contract](../.agents/skills/_shared/references/config-mutation.md), returning only a safe boolean/status or performing the permitted local resolution. It must retain regular-file, no-symlink, bounded-read protections and never print raw names, paths, entries, or configuration.
+
+### Optional technical detail: validator module and CLI
+
+The installed [shared validator](../.agents/skills/_shared/scripts/config-validator.js) exports:
+
+- `validateConfig(value)` → an array of redacted `{ field, message }` errors.
+- `assertValidConfig(value, label)` → throws on invalid input.
+
+Its read-only CLI takes exactly one config-file path:
+
+```bash
+node .agents/skills/_shared/scripts/config-validator.js .agents/developer-config.json
+```
+
+Replace `.agents/skills` with your host's installed skills folder when needed. Exit **0** means valid; **1** means missing, unreadable, or invalid input. It neither writes nor migrates configuration and has no `--stdin` option. It validates shapes, not whether a listed tool is installed or permitted.
+
+The validator's API and accepted shapes are unchanged by the reader; language normalization and summary filtering belong to the reader. Saved mutations require Node.js and the shared validator. If either is unavailable, mutation stops; read-only show additionally requires the safe reader and never bypasses validation. Normal work does not require creating optional config merely to satisfy the validator. For installation/runtime issues and migration, use [Troubleshooting](troubleshooting.md#migrate-from-2x-to-the-3x-candidate).

package/docs/troubleshooting.md

@@ -0,0 +1,180 @@
+# Installation and troubleshooting
+
+[README](../README.md) · [Workflows](workflows.md) · [Configuration](configuration.md)
+
+Use a local project directory, Node.js **22+** with `npx`, and a supported AI host. Start diagnosis with the target path and the reported error, rather than adding `--force` to every retry.
+
+## Install into the intended project
+
+From the target project's working directory:
+
+```bash
+npx macca-method@latest --list-tools
+npx macca-method@latest install
+```
+
+Or specify the path explicitly; quote paths containing spaces:
+
+```bash
+npx macca-method@latest install --directory "/path/to/my project" --tool copilot --tool codex --communication-language English --document-language English --yes
+```
+
+On a fresh interactive install, the CLI asks for hosts, communication language (Enter: Indonesian), and document language (Enter: chosen communication language). Saved channels and supplied flags are reused. Name and project are optional flags, not an identity interview.
+
+Installation places skills, shared preferences, and installer metadata in the selected host folders and `.agents/`. **It does not generate `project-context/` specs, `Task.md`, phase plans, or a bug log.** Those come from the [project workflows](workflows.md). Restart the AI host after installation/upgrade to discover the files.
+
+Use the MACCA installer for the complete collection. Individual skill folders depend on sibling `_shared` resources and shared preferences; generic single-skill installation is not supported for this release.
+
+## Commands and accepted options
+
+| Command | Purpose |
+| --- | --- |
+| `install` | Install/reinstall the collection, select hosts, and bootstrap or explicitly update installer-supported preferences. |
+| `upgrade` | Refresh an existing installation using its recorded hosts and managed-skill metadata. |
+| `doctor` | Read-only local installation diagnosis. |
+| `help`, `--help`, `-h` | Show command help. |
+| `--list-tools` | List supported host keys and aliases. |
+| `--version`, `-v` | Show the invoked package version. |
+
+With no command, help is shown. The current parser accepts the following option spellings; “Used by” identifies where they have an effect. Install-only flags are not preference updates when passed to `upgrade` or `doctor`.
+
+| Option | Used by | Behavior |
+| --- | --- | --- |
+| `--directory`, `-d` | install, upgrade, doctor | Target path; defaults to the current working directory. |
+| `--tool`, `--tools`, `-t` | install | Repeatable or comma-separated host selection; supported keys/aliases are in [Configuration](configuration.md#settings-versus-installed-host-files). Existing recorded hosts are retained. |
+| `--communication-language` | install | Set communication language. |
+| `--document-language`, `--documents-language` | install | Set document language separately. |
+| `--name`, `--project` | install | Save optional labels when supplied. |
+| `--yes`, `-y` | install | Skip prompts. Fresh defaults: Codex if no host selected, Indonesian communication, documents matching communication. Reinstall reuses existing settings unless explicitly overridden. |
+| `--force`, `-f` | install, upgrade | Allow replacement of locally modified managed skills/metadata after review. Does not bypass config validation, unowned collisions, or path/recovery safety. |
+
+Value-bearing long options also accept `--option=value`, including both tool and document-language aliases. Short value options use a separate argument. Boolean flags are standalone; combined short flags and invented options are not supported. Use `--directory` for the project path, not a second positional argument.
+
+`doctor` takes `--directory` for its target and produces text output. There is **no `--json` option and no CLI `config` command**. For saved settings use the [setup skill or shared validator](configuration.md).
+
+## Update a published installation
+
+```bash
+npx macca-method@latest upgrade --directory "/path/to/project"
+```
+
+`@latest` resolves the latest **published npm package**. A GitHub push or local source edit does not update npm. To test repository changes, invoke the source CLI (for example `node bin/macca-method.js --help` from the source checkout); that is different from testing a published package. Pin a published version for reproducible bootstrap/CI.
+
+### Migrate from 2.x to the 3.x candidate
+
+This source tree identifies **3.0.0-rc.1**, a **prerelease candidate** designated for the npm `next` channel, not a stable release. The `@latest` commands in this guide refer to the stable channel. Check availability with `npm view macca-method dist-tags`; when published, use `npx macca-method@3.0.0-rc.1 install` (or `upgrade`) to select this exact candidate, or `@next` for the current prerelease. See the [candidate changelog](../CHANGELOG.md).
+
+1. Back up the target project before upgrading, including locally modified skills, `.agents/` preferences/metadata, and any pending transaction recovery files. Review local edits before deciding which managed copies to replace.
+2. Move to **Node.js 22+** before invoking the candidate. Dropping runtimes below 22 is a breaking change from 2.x; the configured CI matrix uses **22 and 24**. Other accepted majors do not have that matrix coverage.
+3. Use an inspected **physical local path** for the target. Symlinked ancestors, Windows UNC/network paths, and device paths are rejected; see [path restrictions](#path-restrictions). A lexical `/tmp` or `/var` path on macOS may resolve through a symlink.
+4. From the source checkout, inspect with `node bin/macca-method.js doctor --directory "/physical/path/to/project"`, then run `node bin/macca-method.js upgrade --directory "/physical/path/to/project"` when ready. Do not add `--force` by default. It permits replacing reviewed managed edits, not invalid config, unowned folders, unsafe paths, or inconsistent recovery evidence.
+5. Preserve valid existing preferences, unknown extensions, and accepted legacy fields. Invalid config now blocks writes instead of being replaced with defaults; correct only the reported fields locally. Install the complete collection so the safe preference reader and sibling validator are available to every host. Missing helpers block affected config-dependent work, with no raw-file fallback; see [safe preference reading](configuration.md#safe-preference-reader).
+6. If setup created only a config file, follow [incomplete setup](#config-only-or-incomplete-setup). For older unmarked payloads, follow [legacy migration](#upgrade-from-110); modified or unknown copies require inspection, not automatic adoption. Restart the AI host after updating, then run doctor again.
+
+**Version comparison:** downgrade protection follows SemVer precedence, including prereleases. Stable `3.0.0` is newer than `3.0.0-rc.1`; `rc.10` is newer than `rc.2`. Build metadata does not affect ordering. Invalid recorded versions stop the operation for inspection. Version ordering is not evidence of release readiness; inspect the candidate's validation results separately.
+
+Upgrade uses `.agents/macca-tools.txt`, the managed manifest, and lock/ownership evidence. An older package is refused when the installed version is newer, including an unpublished local build. Check the invoked version before retrying with a different package.
+
+Ordinary upgrade refreshes managed skills and metadata without generating project specs or rewriting developer preferences. **Recovery is a separate step:** a pending transaction from an interrupted install can restore config and metadata before upgrade proceeds. Read the reported change stage; do not assume config could never change during a recovery attempt.
+
+### Config-only or incomplete setup
+
+The setup skill may have created only `.agents/developer-config.json`. That is a valid preferences file, but not a complete installer-managed installation. If upgrade reports missing `macca-tools.txt`, run `install` with the desired host to establish installation metadata. Existing valid preferences are preserved unless explicitly overridden; invalid config must be corrected first.
+
+### Upgrade from 1.1.0
+
+The updater compares unmarked legacy skill payloads with fingerprints of the official published `1.1.0` collection. Byte-identical copies can be adopted automatically, including the previous OpenCode `.opencode/skill/` location and meeting-skill rename. Modified or unknown folders are refused: back them up, inspect them, and move conflicting copies aside when appropriate before retrying. `--force` does not turn an unowned folder into a verified official payload.
+
+Legacy global Kimi copies are reported, not deleted automatically. Verify the new project-local `.agents/skills/` installation before manually removing obsolete global copies that your host still discovers.
+
+## Run read-only diagnosis
+
+```bash
+npx macca-method@latest doctor --directory "/path/to/project"
+```
+
+Doctor inspects runtime compatibility, target/path safety, config validity with values hidden, selected hosts, manifest/lock consistency, payload/reference integrity, local drift, and pending transactions.
+
+| Output | Interpretation |
+| --- | --- |
+| `OK` | The reported check succeeded. |
+| `WARN` | A limitation or drift needs review; warnings alone return exit **0**. |
+| `FAIL` | A failed check was found; doctor returns exit **1**. |
+
+Doctor does not write files, repair installation state, or recover transactions. Missing state or older locks without payload fingerprints limit integrity verification; an exit 0 containing warnings is not proof of full integrity. A successful filesystem check also does not establish AI-host/model behavior.
+
+## Match the symptom to a safe next step
+
+Install/upgrade errors show a code, affected path, change stage, and next action. Preserve those details when seeking help, with private paths or values redacted as needed.
+
+| Symptom | What to check first |
+| --- | --- |
+| Host cannot find MACCA skills | Confirm the CLI's target directory and selected host folder, then restart the host. Confirm the complete collection includes `_shared`; use doctor to check payloads. |
+| `MACCA_NODE_UNSUPPORTED` | Switch to Node.js 22 or 24 and retry; versions below 22 are rejected. |
+| Unverified-runtime notice | Another major at or above 22 is allowed but outside the configured 22/24 matrix. Use a matrix version for that coverage. |
+| Unknown option / unexpected positional argument | Compare with the option table; use `--directory`, and do not pass `--json` or a `config` command. |
+| `MACCA_CONFIG_INVALID` | Back up the file, correct the reported fields locally, and validate it. Do not share raw config or replace unrelated values with defaults. `--force` cannot bypass validation. |
+| Preference reader/helper unavailable | Restore the complete `_shared` installation, Node.js runtime, and permitted safe execution. Stop affected config-dependent work; do not dump raw config or treat helper failure as absent config. |
+| `EACCES`, `EPERM`, or `EBUSY` | Check ownership, permissions, and file locks; close the program holding the path or use the intended writable directory. |
+| Read-only filesystem / `ENOSPC` | Use a writable volume or free space. Preserve transaction evidence before retrying. |
+| `ENOENT` / missing packaged payload | Check the path and parent; restore a complete package or install into an uninitialized target. |
+| Local managed-skill or metadata drift | Back up and inspect the changed content and ownership marker. Decide whether to retain it or explicitly replace managed edits; do not begin with `--force`. |
+| Unowned skill-folder collision | Preserve and inspect the folder; move it aside if appropriate or choose a clean target. Force does not authorize its overwrite. |
+| Newer installed version than invoked package | Check package versions and use an appropriate release/local build; upgrade refuses a silent downgrade. |
+| `MACCA_INPUT_ERROR` | Use a working terminal, or an unattended install with `--yes` and explicit flags. |
+| Pending transaction / recovery refusal | Follow the recovery steps below; retain the journal and backups. |
+
+### Path restrictions
+
+- Windows UNC/network and device paths are rejected (`MACCA_UNSUPPORTED_PATH`). Use a local drive path such as `"C:\projects\my app"`.
+- Symlinked target ancestors are conservatively rejected. This includes macOS aliases such as `/tmp` and `/var`, and the same restriction applies on other systems.
+- For an existing directory, resolve its physical path, inspect the result, and pass that path to `--directory`. For example on macOS/Linux:
+
+```bash
+node -p 'require("node:fs").realpathSync("/tmp/my-project")'
+```
+
+The command only prints a path. Use the returned physical path explicitly; keep quotes around paths with spaces.
+
+### Cancellation and interrupted transactions
+
+Ctrl+C or EOF **during interactive setup** returns exit **130** (`MACCA_CANCELLED`) before ordinary writes or transaction recovery. This prompt-stage guarantee does not promise rollback of a process interrupted after writes begin.
+
+If `.agents/macca-transaction.json` remains:
+
+1. Back up and inspect the project, journal, and associated recovery files.
+2. Run doctor to inspect the state without changing it.
+3. Resolve the reported cause, then rerun install/upgrade for validated recovery.
+4. If recovery refuses modified or inconsistent evidence, preserve it and investigate the reported path rather than deleting the journal or forcing past the check.
+
+Recovery verifies transaction entries and config candidates before rollback/cleanup. It may restore earlier files or finish cleanup of a committed transaction. A later error can therefore follow recovery changes; the CLI's change-stage report is important.
+
+## Runtime and platform evidence limits
+
+The configured CI matrix is **Ubuntu, Windows, and macOS × Node.js 22 and 24**. The release-triggered workflow is configured to smoke-test the exact published release version on that matrix. This is configuration, not evidence that every run or device has passed. Corresponding run logs are required for platform/version claims; local Linux validation alone does not verify Windows or macOS.
+
+## Maintainer checks from a source checkout
+
+Maintainer validation requires **Node.js 22+ and Python 3**. Run from the repository root:
+
+```bash
+npm run validate
+```
+
+The validation script combines syntax checks, skill structure/reference validation, static workflow checks, package checks, installer/config/safety tests, legacy upgrade tests, and an npm pack dry run. Useful focused commands are:
+
+```bash
+node scripts/run-skill-validator.js
+node scripts/validate-skill-behavior.js
+npm run test:config
+npm run test:preferences
+npm run test:cli
+npm run test:safety
+npm run test:upgrade:legacy
+```
+
+The Python-backed skill validator checks skill structure and references. `validate-skill-behavior.js` checks static Markdown contracts, including default preference loading through `language-config.md`; passing it does not execute AI conversations or prove agent behavior. `test:preferences` exercises closed-summary output, redaction, missing/invalid config, bounded reads, and read-only behavior without reading live user preferences. Package/installer tests establish their own bounded evidence, not universal host compatibility.
+
+Root `.agents/developer-config.json`, generated `/evals/results/`, and `/evals/*-workspace/` directories are ignored as local artifacts. Evaluation definitions and preparation scripts remain repository resources. Ignore rules do not untrack existing files or stage tracked deletions; review those separately before any later commit.
+
+Live-agent scenarios and their evidence protocol are **repository resources**, not part of the installed skill payload: [workflow evaluations](https://github.com/firdaus12p/MACCA-METHOD/blob/main/evals/README.md). Definitions and prepared fixtures remain `NOT RUN` until exercised; they are not passing results, measured token savings, or a release-stability claim.

package/docs/workflows.md

@@ -0,0 +1,175 @@
+# Workflows
+
+[README and 19-skill catalog](../README.md) · [Configuration](configuration.md) · [Troubleshooting](troubleshooting.md)
+
+Start with the state of your project and the outcome you want. MACCA's planning skills write decisions into `project-context/`; execution skills implement authorized work and check it against those decisions. Installing MACCA does not generate these project documents.
+
+## Choose a starting point
+
+| Your situation | Useful request |
+| --- | --- |
+| New idea, no usable specs | “Use brainstorm-prd to plan an appointment-booking app for a small clinic.” |
+| Existing code, missing or placeholder-only specs | “Use spec-init in guided mode to document this codebase. Preserve existing documents unless I approve their replacement.” |
+| Existing spec needs one decision completed | “Complete only the retention-policy Missing Decision in schema.md; preserve the baseline evidence and other unknowns.” |
+| Approved work is ready | “Implement Phase 2 from Task.md, following its execution rules.” |
+| Unsure what is next | “Use help to recommend the next step from the current project evidence.” |
+
+Natural-language intent is enough; `Use the skill <name>` is also explicit. You do not need to address a persona. Roles are assigned by each skill, not selected as a prerequisite to ordinary work. See the README catalog for all 19 skills rather than treating every skill as a required step.
+
+## New project: plan only applicable domains
+
+Follow this order for new planning:
+
+```text
+PRD → architecture → applicable schema → applicable API → applicable StyleGuide
+    → rules → spec-audit (recommended) → Task → authorized implementation
+```
+
+| Decision | Owner and output | When it applies |
+| --- | --- | --- |
+| Product scope and outcomes | `brainstorm-prd` → `PRD.md` | Establish approved requirements first. |
+| Technical boundaries and operations | `brainstorm-architecture` → `architecture.md` | Required before domain design and implementation. |
+| Persistence | `brainstorm-schema` → `schema.md` | Only for persisted data within scope. |
+| Exposed or consumed contracts | `brainstorm-api` → `api.md` | REST, GraphQL, RPC, events, or integrations actually needed. |
+| UI/UX | `brainstorm-styleguide` → `StyleGuide.md` | Only for in-scope UI; branches from architecture and feeds rules. |
+| Coding and testing conventions | `brainstorm-rules` → `rules.md` | After architecture and all applicable domain inputs. |
+| Verifiable tasks and phases | `brainstorm-task` → `Task.md` | Derive work from applicable approved specs. |
+
+**A backend does not automatically need persistence.** A stateless provider API needs architecture and an API contract; schema can be `N/A — no in-scope persistence`. A frontend consuming an external API can document its consumer contract without designing backend storage. StyleGuide does not replace data/API decisions or rules. See the [API planning contract](../.agents/skills/brainstorm-api/SKILL.md).
+
+Use `N/A` with a reason only for genuinely inapplicable inputs. An applicable but missing decision is unresolved, not `N/A`. Plan the smallest sufficient solution while retaining necessary security, accessibility, integrity, validation, and recovery controls; template examples are not automatic features or infrastructure.
+
+Planning reuses saved pacing and recommendations, including `recommendations: false`. Discussion depth is independent: brief (`quick`) only for explicitly disposable prototypes, normal (`standard`) for production by default, and very thorough (`critical`) for material risk such as payments or sensitive data. Greater depth means better risk questions, not automatically more components. See [planning modes and discussion policy](../.agents/skills/_shared/references/brainstorm-session.md).
+
+## Existing project: establish an evidence-backed baseline
+
+[spec-init](../.agents/skills/spec-init/SKILL.md) documents what exists. An empty `project-context/` directory or template placeholders do not count as usable specs.
+
+1. Choose **batch** (all applicable documents together) or **guided** (one document, review, then continue).
+2. Generate in evidence order: `architecture.md` → applicable `schema.md` → applicable `api.md` → applicable `StyleGuide.md` → `rules.md` → `PRD.md`. PRD comes last because it is synthesized from observed behavior.
+3. Review `Input Evidence`, `Confidence Summary`, assumptions, and `Missing Decisions`.
+4. Complete selected or blocking Missing Decisions through their owning brainstorm skill, then check consistency with `spec-audit`.
+5. Ask `brainstorm-task` to plan approved remaining work. Start `developer` only with implementation authorization.
+
+Confidence means **High** for direct source evidence, **Medium** for a stated strong inference, and **Low** for a weak inference requiring verification. It is not proof that acceptance tests passed or that product policy was approved.
+
+Task planning distinguishes:
+
+- **Existing verified:** retain completion and its evidence.
+- **Existing unverified:** plan verification or decision work, not replacement by default.
+- **Gaps:** plan implementation only for demonstrated, approved differences from requirements.
+
+Baseline approval does not authorize rebuilding existing features or implementing every observed gap. `spec-init` does not author `Task.md`; that belongs to [brainstorm-task](../.agents/skills/brainstorm-task/SKILL.md).
+
+### Complete or update an existing spec without regenerating it
+
+Name the document and the selected decision or section:
+
+> Use brainstorm-prd to complete only the rollout Missing Decision. Keep Input Evidence, Confidence Summary, stable IDs, unrelated text, and all other unresolved decisions.
+
+The owner asks targeted questions and obtains approval for the bounded update, reusing approval already covering that exact change. A newly approved policy does not turn into a claim that existing code implements it. Full regeneration requires an explicit request and approval naming the files to replace, including placeholders. See [bounded completion](../.agents/skills/_shared/references/brainstorm-session.md) and [output ownership](../.agents/skills/_shared/references/output-ownership.md).
+
+## Implement a task or phase
+
+[developer](../.agents/skills/developer/SKILL.md) needs clear implementation intent. Existing tasks alone do not start execution. Before code changes, `architecture.md` and `rules.md` are required; read schema, API, and UI contracts when relevant, and PRD when product behavior needs clarification. Scan applicable `[FORBIDDEN]` rules and respect the authorized file/scope boundary.
+
+### Direct, plan-first, and execution cadence
+
+- **Direct:** implement the authorized task using the applicable specs and validation policy.
+- **Plan-first:** write `project-context/plans/phase-[N]-[slug].md` with goal, scope, files, risks, and validation. It starts at `status: review`; after the user's `start`, it becomes `in-progress`.
+- **Execution cadence:** `Task.md` separately determines whether to stop after each task or after a phase. Work mode does not erase those stops or authorize the next phase.
+
+Plan status follows `review → in-progress → code-review → done`. The developer owns the final transition after all phase tasks, applicable Definition of Done, formal spec synchronization, and both quality gates have evidence. A passing task or standalone review does not close a phase.
+
+Practical requests:
+
+> Implement Task 2.1 only, then stop. Use the testing workflow in rules.md.
+
+> Plan Phase 3 first. I want to review the files, risks, and validation before coding.
+
+Per task: understand acceptance criteria → reuse existing capabilities → implement under the testing policy → internal self-review → validate → record progress. Test-first is required when `rules.md` selects it; it is not imposed on every project. Source details: [task execution](../.agents/skills/developer/references/execute-task.md), [planning](../.agents/skills/developer/references/onboarding.md), and [phase closure](../.agents/skills/developer/references/close-phase.md).
+
+### Small changes and approved technical deltas
+
+Use [quick-dev](../.agents/skills/quick-dev/SKILL.md) for a small, clearly anchored layout, copy, styling, or minor logic change. It records the task and runs the same two gates at task scope. New features, migrations, new API endpoints, changes exceeding five files, or work without a current task/phase anchor route to developer. Broader post-task maintenance stays with developer and receives a traceable delta task/phase.
+
+An approved technical change not yet in formal specs needs one `## Approved Scope Delta` record **before coding**:
+
+- Plan-first: use the active phase plan.
+- Quick-dev: use a lightweight entry under the related task in `Task.md`.
+- Direct: use `Task.md` or a minimal active phase plan.
+
+Record approval, task/phase anchor, `DELTA-*` ID, bounded change, affected files/specs, acceptance criteria, validation, and owning-skill sync checklist. The explicit bounded request can supply approval; new business decisions still need their owner.
+
+Quick-dev can finish a verified task with **pending formal spec sync** visible. Before phase closure, developer collects deltas from both locations, completes the named updates through the owning skills, and validates the affected document pairs. Unresolved sync blocks phase closure. See the [scope-delta contract](../.agents/skills/_shared/references/scope-delta.md).
+
+## Understand the two quality gates
+
+```text
+Implementation and validation → spec-compliance → code-review → origin's result
+```
+
+1. [spec-compliance](../.agents/skills/spec-compliance/SKILL.md) checks implementation against applicable requirements, contracts, rules, acceptance criteria, and scope (SC-01–SC-08).
+2. [code-review](../.agents/skills/code-review/SKILL.md) checks code quality and security. Its [canonical checklist](../.agents/skills/code-review/references/review-checklist.md) contains the 27 CR checks and 10 SEC checks.
+
+Both use the same review unit: task, phase, or bug. Unfinished sibling tasks do not block an otherwise complete task review. `spec-audit` serves a different purpose: consistency between documents, rather than implementation against documents.
+
+**Read the result accurately:** `N/A` means a check does not apply, with a reason. `NOT VERIFIED` means required evidence is missing. Zero findings is not a verified pass when evidence is absent. Clean child reviews feed one combined result at the originating workflow; concise output does not remove checks.
+
+`codeReviewPreferences.fixMode` controls remediation:
+
+| Mode | Behavior |
+| --- | --- |
+| `report-first` (default) | Report evidenced fixes, then wait before applying them. A correction gate requires a **non-empty actionable fix manifest** with IDs, targets, bounded changes, and validation. |
+| `fix-then-report` | Apply authorized actionable BLOCKER/MAJOR fixes, validate, then report. MINOR findings are discussed; INFO is report-only. |
+
+Clean and INFO-only reports do not ask for repair approval. Missing evidence alone does not justify invented fixes or a correction gate. A reply such as `yes`, `fix`, or `continue` approves the active manifest; named IDs approve only those fixes. The workflow resumes at its recorded return step rather than restarting setup. Bug implementation approval and other scope/destructive-change gates still apply. Exact gate text and resume rules live in [fix-mode.md](../.agents/skills/_shared/references/fix-mode.md).
+
+## Fix a bug, including prevention
+
+> Use bug-fix: submitting an empty quantity crashes the order form. It should show a validation error. Reproduce with these steps: …
+
+[bug-fix](../.agents/skills/bug-fix/SKILL.md) follows this sequence:
+
+```text
+Bug-log check → diagnosis and related-pattern/caller checks
+→ root cause + fix/prevention manifest → explicit implementation approval
+→ fix and prevention → regression validation → spec-compliance → code-review
+→ user confirms checked result → append bug-log
+```
+
+The first implementation approval is required regardless of fix mode. Prevention is disclosed with the fix: a focused test, a justified spec/rule guard, or repeatable manual steps. Validate affected behavior and preserve safe fail-before/pass-after evidence where feasible; disclose any limitation.
+
+After regression validation and both gates pass, the user confirms whether the checked result works. Only then is `project-context/bug-log.md` created/appended. New code, tests, or guards discovered after confirmation require new bounded approval, validation, both gates, and confirmation of the revised result before logging.
+
+## Expand product scope
+
+> Use add-feature to add customer CSV export. Show the impact on existing specs and plans before updating them.
+
+[add-feature](../.agents/skills/add-feature/SKILL.md) analyzes every document's applicability and impact, obtains approval, then updates every affected spec and existing phase plan while preserving unrelated content and IDs. It delegates **all `Task.md` authoring to `brainstorm-task`**, whether the file exists or is missing. The task-planning handoff prepares work; implementation starts with separate authorization to developer.
+
+## Discuss a decision with the team
+
+> Use meet. Agenda: choose a rollout approach. Outcome: one recommendation and unresolved risks. Participants: Fachri, Firdaus, Ikhsan. Constraints: one maintainer and no extra infrastructure. Evidence: the rollout section of PRD.md.
+
+[meet](../.agents/skills/meet/SKILL.md) is one structured, discussion-only round. It reuses the agenda, desired outcome, and constraints supplied or clearly inferable from context, asking only material gaps rather than repeating a form; evidence is optional. Available participants are Galbi (product), Fachri (technical design), Akram (UI/UX), Firdaus (implementation), and Ikhsan (failure analysis).
+
+Name participants, explicitly choose `all`, or delegate selection to Galbi, who chooses relevant roles and briefly explains why. Without selection or delegation, Galbi recommends a bounded set of roles and asks one participant choice; it never defaults to all. Only selected participants contribute, each exactly once, in the fixed order above, with explicit evidence/assumption labels. Contributions stay complete and concise; five subheadings per persona are not required. Galbi always facilitates and summarizes in the same response, contributing as a participant only when selected. There are no rebuttals or fabricated consensus.
+
+The summary separates recommendations from **user-approved decisions**, each tied to its exact user approval source and scope. Team agreement is not authorization. Open questions and next steps appear only when useful; omit empty fields and status gates. No-change conclusions and general discussion need no artifact, task, or next skill. Artifact handoffs are conditional on a concrete in-scope persistent change and report the target, owning skill, bounded change, and approval or pending choice. MACCA preferences belong to `setup-macca-method`, not `rules.md`.
+
+The meeting is report-only: it makes no file writes or status changes and executes no follow-up skills. Later authorized writes go to the appropriate owner. It closes automatically; a clear natural-language request such as “continue discussing the rollout risks” can start one new round with a new or refined agenda, reusing still-applicable context and participant choices. The literal skill name is not required. It does not automatically reopen indefinitely; a vague continuation needs only the material clarification.
+
+## Check release readiness
+
+> Use release-readiness for commit `<candidate>` targeting staging. Report the evidence and blockers.
+
+After completed phases, check final document consistency with `spec-audit`; before release, use [release-readiness](../.agents/skills/release-readiness/SKILL.md). It consumes existing quality evidence and checks candidate-specific build/smoke results, configuration, applicable migration/recovery, rollback, observability, compatibility, and UI evidence.
+
+The verdict is `READY`, `CONDITIONAL`, or `NOT READY`; missing required evidence remains `NOT VERIFIED`. This is a report-only audit: it does not deploy, publish, apply migrations, rotate secrets, or change infrastructure. A verdict applies to the checked candidate and relevant configuration.
+
+## Follow the trace without duplicating it
+
+Stable IDs connect requirements to contracts, tasks, and evidence: `FEAT-*`, `BR-*`, `AC-*`, `NFR-*`, and `US-*` for product requirements; `DATA-*` for persisted entities; `API-*` for operations; `RULE-*` for rules; `DELTA-*` for approved technical changes. Preserve existing IDs rather than renumbering during updates.
+
+Use the [ownership matrix](../.agents/skills/_shared/references/output-ownership.md), [task-authoring rules](../.agents/skills/brainstorm-task/SKILL.md), and [interaction contract](../.agents/skills/_shared/references/interaction-contract.md) for exact handoffs. These guides summarize the workflow; the linked skill instructions and checklists carry its detailed requirements.

package/package.json

@@ -1,10 +1,17 @@
 {
   "name": "macca-method",
-  "version": "2.1.2",
+  "version": "3.0.0-rc.1",
   "description": "CLI installer for MACCA AI spec-driven development skills.",
   "license": "MIT",
   "scripts": {
-    "validate": "node --check ./bin/macca-method.js && node --check ./scripts/test-install.js && node --check ./scripts/test-upgrade-legacy.js && node --check ./scripts/run-skill-validator.js && node --check ./scripts/validate-skill-behavior.js && node ./scripts/run-skill-validator.js && node ./scripts/validate-skill-behavior.js && npm run test:install && npm run test:upgrade:legacy && npm pack --dry-run",
+    "validate": "node --check ./bin/macca-method.js && node --check ./scripts/test-install.js && node --check ./scripts/test-upgrade-legacy.js && node --check ./scripts/run-skill-validator.js && node --check ./scripts/validate-package.js && node --check ./scripts/validate-docs.js && node --check ./scripts/validate-skill-behavior.js && node --check ./.agents/skills/_shared/scripts/config-validator.js && node --check ./.agents/skills/_shared/scripts/read-preferences.js && node --check ./scripts/lib/npm-command.js && node --check ./scripts/test-config.js && node --check ./scripts/test-preferences.js && node --check ./scripts/test-package-safety.js && node --check ./scripts/test-cli-setup.js && node --check ./scripts/test-npm-command.js && node ./scripts/run-skill-validator.js && node ./scripts/validate-skill-behavior.js && node ./scripts/validate-docs.js && npm run test:npm && npm run test:package && npm run test:config && npm run test:preferences && npm run test:cli && npm run test:safety && npm run test:install && npm run test:upgrade:legacy && npm pack --dry-run --ignore-scripts",
+    "prepublishOnly": "npm run validate",
+    "test:package": "node scripts/test-package-safety.js",
+    "test:config": "node scripts/test-config.js",
+    "test:preferences": "node --check .agents/skills/_shared/scripts/config-file.js && node scripts/test-preferences.js",
+    "test:cli": "node scripts/test-cli-setup.js",
+    "test:npm": "node scripts/test-npm-command.js",
+    "test:safety": "node scripts/test-installer-safety.js",
     "test:install": "node ./scripts/test-install.js",
     "test:install:published": "node ./scripts/test-install.js --published",
     "test:upgrade:legacy": "node ./scripts/test-upgrade-legacy.js"
@@ -14,18 +21,55 @@
   },
   "files": [
     "bin/",
-    ".agents/",
+    ".agents/legacy-payloads.json",
+    ".agents/macca-lock.json",
+    ".agents/macca-managed-skills.txt",
+    ".agents/skills/_shared/",
+    ".agents/skills/_shared/scripts/config-validator.js",
+    ".agents/skills/_shared/scripts/read-preferences.js",
+    ".agents/skills/add-feature/",
+    ".agents/skills/brainstorm-api/",
+    ".agents/skills/brainstorm-architecture/",
+    ".agents/skills/brainstorm-prd/",
+    ".agents/skills/brainstorm-rules/",
+    ".agents/skills/brainstorm-schema/",
+    ".agents/skills/brainstorm-styleguide/",
+    ".agents/skills/brainstorm-task/",
+    ".agents/skills/bug-fix/",
+    ".agents/skills/code-review/",
+    ".agents/skills/developer/",
+    ".agents/skills/help/",
+    ".agents/skills/meet/",
+    ".agents/skills/quick-dev/",
+    ".agents/skills/release-readiness/",
+    ".agents/skills/setup-macca-method/",
+    ".agents/skills/spec-audit/",
+    ".agents/skills/spec-compliance/",
+    ".agents/skills/spec-init/",
     "scripts/test-install.js",
+    "scripts/test-installer-safety.js",
+    "scripts/test-package-safety.js",
+    "scripts/test-config.js",
+    "scripts/test-preferences.js",
+    "scripts/test-cli-setup.js",
+    "scripts/test-npm-command.js",
+    "scripts/lib/npm-command.js",
     "scripts/test-upgrade-legacy.js",
     "scripts/run-skill-validator.js",
     "scripts/validate-skill-behavior.js",
+    "scripts/validate-package.js",
+    "scripts/validate-docs.js",
     "flow.webp",
     "image-macca-method.webp",
     "README.md",
+    "CHANGELOG.md",
+    "docs/workflows.md",
+    "docs/configuration.md",
+    "docs/troubleshooting.md",
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "keywords": [
     "ai",