macca-method 1.0.0

package/.agents/macca-managed-skills.txt

@@ -0,0 +1,17 @@
+_shared
+add-feature
+brainstorm-api
+brainstorm-architecture
+brainstorm-prd
+brainstorm-rules
+brainstorm-schema
+brainstorm-styleguide
+brainstorm-task
+bug-fix
+code-review
+developer
+help
+rapat
+spec-audit
+spec-compliance
+spec-init

package/.agents/skills/_shared/references/brainstorm-session.md

@@ -0,0 +1,84 @@
+# Brainstorm Session Policy
+
+## Purpose
+
+This file defines shared session behavior for all `brainstorm-*` skills.
+
+The caller skill must read `runtime-config.md` before this file.
+
+## Shared Preferences
+
+Brainstorm skills may use `brainstormPreferences` in
+`.agents/developer-config.json` to persist session behavior across sessions.
+
+Currently supported fields:
+
+```json
+{
+  "brainstormPreferences": {
+    "discussionMode": "one-by-one",
+    "recommendations": true
+  }
+}
+```
+
+Accepted `discussionMode` values: `"one-by-one"`, `"three-at-a-time"`, `"all-at-once"`.
+
+## Interview Pace
+
+Brainstorm skills may batch questions when the user explicitly wants faster progress. This is separate from approval gates in execution skills.
+
+Allowed pace strategies:
+
+- `one-by-one` — one topic per turn
+- `three-at-a-time` — three topics in one message
+- `all-at-once` — all topics in one message; the user answers all of them, then the AI writes the document
+
+### Important Difference
+
+- Interview pace is for discovery-heavy `brainstorm-*` workflows.
+- Approval and risk confirmation in `developer`, `bug-fix`, `spec-init`, and similar skills must still stay limited to one decision topic per pause.
+
+## Recommendations Toggle
+
+Use `brainstormPreferences.recommendations` as a persistent preference:
+
+- `true` — research first, then present recommendations with reasoning
+- `false` — ask questions without recommendations
+
+## Session Setup Rules
+
+When a brainstorming skill starts:
+
+1. Read `languagePreferences` via `runtime-config.md`.
+2. Read `brainstormPreferences` if present.
+3. **Announce the session** before asking anything:
+   - If preferences are already saved — show a short confirmation and allow changes:
+     ```
+     This session has [N] topics.
+     Saved preferences: [pacing] | recommendations: [on/off]
+     Continue with these settings? Or type the changes you want.
+     ```
+   - If no preferences are saved — ask both before starting:
+     ```
+     This session has [N] topics. Two things before we start:
+     1. Pace: (A) one by one  (B) three at a time  (C) all at once
+     2. Answer recommendations: should the AI suggest answers for each question? (Y/N)
+     ```
+4. Save the chosen preferences. Preserve all unrelated config fields when writing the update.
+
+## Recommended Prompt Patterns
+
+For pace:
+
+```text
+This session has [N] topics. Do you want to discuss them one by one or three at a time?
+```
+
+For recommendations:
+
+```text
+Should I provide recommendations based on current best practices?
+```
+
+Use brief questions. These settings should speed up the session, not add friction.

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

@@ -0,0 +1,55 @@
+# Human-in-the-Loop Policy
+
+## Purpose
+
+This file defines shared pause-and-confirm behavior across MACCA skills.
+
+## Two Distinct Interaction Types
+
+### 1. Interview Pace
+
+Used by `brainstorm-*` skills to control how many discovery questions are asked per turn.
+
+### 2. Confirmation Gates
+
+Used by execution, audit, and bug-fix skills when a decision is risky, destructive, ambiguous, or materially changes scope.
+
+Do not mix these two patterns.
+
+## When Confirmation Is Required
+
+Pause and ask before continuing when:
+
+- there are multiple materially different paths and the spec does not resolve the choice
+- the change is destructive or hard to undo
+- the user's instruction is ambiguous in a way that changes scope or business behavior
+- documents conflict and the conflict changes the next action
+
+## When Confirmation Is Not Required
+
+Continue without pausing when:
+
+- the answer is already explicit in the spec or config
+- the decision is a low-risk technical implementation detail
+- the change is reversible and does not change business scope
+
+## Shared Prompt Shape
+
+Use this structure when a skill needs confirmation:
+
+```text
+I need confirmation before continuing.
+
+[one brief summary of the issue]
+
+Options:
+1. [recommended default]
+2. [alternative]
+3. [other / explain]
+```
+
+Keep one decision topic per pause.
+
+## Resume Rule
+
+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 changes.

package/.agents/skills/_shared/references/output-ownership.md

@@ -0,0 +1,31 @@
+# Output Ownership Matrix
+
+## Purpose
+
+This file defines which skill primarily owns each persistent output, so skills do not quietly compete to create the same artifact.
+
+## Primary Owners
+
+| Output | Primary Owner | Secondary / Limited Authors |
+|---|---|---|
+| `project-context/PRD.md` | `brainstorm-prd` | `add-feature`, `spec-init` |
+| `project-context/architecture.md` | `brainstorm-architecture` | `add-feature`, `spec-init` |
+| `project-context/schema.md` | `brainstorm-schema` | `add-feature`, `spec-init` |
+| `project-context/api.md` | `brainstorm-api` | `add-feature`, `spec-init` |
+| `project-context/StyleGuide.md` | `brainstorm-styleguide` | `add-feature`, `spec-init` |
+| `project-context/rules.md` | `brainstorm-rules` | `add-feature`, `spec-init` |
+| `project-context/Task.md` | `brainstorm-task` | `developer` only updates progress; `add-feature` must hand off to `brainstorm-task` |
+| `project-context/bug-log.md` | `bug-fix` | none |
+| `project-context/plans/*.md` | `developer` | `add-feature`, `code-review` limited updates per workflow |
+
+## Ownership Rules
+
+- `help` explains and routes. It does not create project spec files.
+- `rapat` facilitates decisions and maps them to target artifacts. It does not replace the primary owner of spec files.
+- `spec-audit` and `spec-compliance` report findings. They do not rewrite spec artifacts unless the user explicitly asks for follow-up fix work.
+- `code-review` reports code issues. It does not own spec documents.
+- `spec-init` is the bootstrap exception for existing codebases without specs.
+
+## Drift Rule
+
+If two skills appear to write the same artifact for the same purpose, prefer the primary owner and change the other skill to handoff or delta-update language only.

package/.agents/skills/_shared/references/personas.md

@@ -0,0 +1,39 @@
+# Persona Profiles
+
+## Table of Contents
+
+1. @Galbi
+2. @Fachri
+3. @Akram
+4. @Firdaus
+5. @Ikhsan
+
+## @Galbi
+
+- Role: Project Manager
+- Tone: calm, guiding, structured
+- Best for: status checks, next-step guidance, feature scope, task planning, meeting facilitation
+
+## @Fachri
+
+- Role: Tech Lead
+- Tone: precise, analytical, high standard
+- Best for: architecture, API/schema/rules design, spec consistency, implementation compliance, code review
+
+## @Akram
+
+- Role: UI/UX Designer
+- Tone: design-focused, clarity first, consistency-minded
+- Best for: style guides, interface systems, component appearance, accessibility-aware UI direction
+
+## @Firdaus
+
+- Role: Expert Developer
+- Tone: pragmatic, implementation-focused, quality-conscious
+- Best for: task execution, coding, behavior validation, spec integration
+
+## @Ikhsan
+
+- Role: Debugger
+- Tone: systematic, patient, root-cause-focused
+- Best for: bug reproduction, root-cause isolation, minimal fixes, regression prevention

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

@@ -0,0 +1,171 @@
+# Runtime Config Contract
+
+## Table of Contents
+
+1. Purpose
+2. Required Read Order
+3. Language Preferences
+4. Stable Shared Fields
+5. Fix Mode Contract
+6. `additionalSkills` Compatibility
+7. Mutation Rules
+
+## Purpose
+
+This file is the source of truth for how MACCA skills read and update `.agents/developer-config.json`.
+
+Treat `developer-config.json` as a stable public contract. Do not make breaking schema changes that force existing users to edit the file manually after an upgrade.
+
+## Required Read Order
+
+Before any user-facing output or config mutation:
+
+1. Read `.agents/developer-config.json` if it exists.
+2. Preserve unknown fields when writing updates.
+3. Merge changes into the existing object. Never replace the whole file unless the file does not exist yet.
+
+## Language Preferences
+
+Use this field if present:
+
+```json
+{
+  "languagePreferences": {
+    "communication": {
+      "raw": "Indonesian",
+      "normalized": "indonesian"
+    },
+    "documents": {
+      "raw": "Indonesian",
+      "normalized": "indonesian"
+    }
+  }
+}
+```
+
+### Accepted Compatibility Values
+
+Readers must accept long and short normalized forms:
+
+- Indonesian: `indonesian`, `id`
+- English: `english`, `en`
+
+Writers should preserve known values when possible. If a skill must write a new normalized value, use the installer's canonical form unless the installer is updated to a new canonical form first.
+
+### Output Rules
+
+- Use `languagePreferences.communication.normalized` for chat output, reports, prompts, and confirmations.
+- Use `languagePreferences.documents.normalized` for generated project documents.
+- Never translate file names, traceability IDs, config keys, or code literals.
+
+## Stable Shared Fields
+
+These fields are part of the stable contract and must remain backward compatible:
+
+- `name`
+- `project`
+- `languagePreferences`
+- `developerPreferences.workMode`
+- `developerPreferences.scope`
+- `brainstormPreferences`
+- `additionalSkills`
+- `availableMCPs`
+- `codeReviewPreferences.fixMode`
+
+## Fix Mode Contract
+
+`codeReviewPreferences.fixMode` is a **binding setting for review/remediation skills**.
+`developer`, `bug-fix`, `spec-compliance`, `code-review`, and `spec-audit` MUST follow this field before they fix findings or change files in a review/remediation workflow.
+
+Brainstorming/document-generation skills such as `brainstorm-*`, `add-feature`, and `spec-init` are NOT required to use `fixMode`, because they do not run a report-findings-then-fix workflow.
+
+### Read and Announce at Startup
+
+Every covered review/remediation skill must read `fixMode` during Shared Runtime Setup — **before any analysis or action begins**:
+
+1. Read `codeReviewPreferences.fixMode` from `developer-config.json`.
+2. If it is missing, treat it as `"report-first"` — do not ask the user.
+3. Announce it at the top of the output: `[Fix mode: report-first]` or `[Fix mode: fix-then-report]`.
+
+### Values
+
+| Value | Behavior |
+|-------|----------|
+| `"report-first"` | **Default.** Run all analysis. Present the full findings report. Show the gate prompt below. **End the response.** Wait for user confirmation in the next message before touching any files. |
+| `"fix-then-report"` | Automatically apply BLOCKER/MAJOR fixes. Present the full report at the end. |
+
+### Required Gate Prompt (`report-first` only)
+
+After presenting all findings, the skill must display this block **verbatim**, then **end the response immediately**:
+
+```
+---
+[GATE — Fix mode: report-first]
+All findings have been reported. No files were changed.
+Reply "yes" / "fix" / "continue" to apply all fixes,
+or name which findings you want to fix.
+---
+```
+
+**Critical rule:** DO NOT apply any fixes, edit any files, run any sub-skill, or add follow-up text in the same response. The response ends at the gate prompt. Act only after the user's next message confirms.
+
+### Default
+
+If `codeReviewPreferences.fixMode` is missing from `developer-config.json`, always treat it as `"report-first"`. Do not ask the user — just use the default and announce it.
+
+## `additionalSkills` Compatibility
+
+> **Internal contract only.** These forms exist for backward compatibility across different AI hosts (Copilot, OpenCode, Codex, etc.), each of which stores skill files in different paths. Users do not choose the form — skills always write the canonical extensible form when saving. Readers must tolerate all three forms.
+
+Readers must support all of these forms:
+
+### Legacy Single-Path Form
+
+```json
+{
+  "name": "frontend-react-best-practices",
+  "path": ".agents/skills/frontend-react-best-practices/SKILL.md",
+  "purpose": "Use when working on React UI code."
+}
+```
+
+### Legacy Host-Specific Form
+
+```json
+{
+  "name": "frontend-react-best-practices",
+  "opencodePath": ".opencode/skill/frontend-react-best-practices/SKILL.md",
+  "githubPath": ".github/skills/frontend-react-best-practices/SKILL.md",
+  "purpose": "Use when working on React UI code."
+}
+```
+
+### Canonical Extensible Form
+
+```json
+{
+  "name": "frontend-react-best-practices",
+  "purpose": "Use when working on React UI code.",
+  "paths": {
+    "copilot": ".github/skills/frontend-react-best-practices/SKILL.md",
+    "opencode": ".opencode/skill/frontend-react-best-practices/SKILL.md",
+    "codex": ".agents/skills/frontend-react-best-practices/SKILL.md"
+  }
+}
+```
+
+### Read Fallback Order
+
+When selecting a skill path for the current host, use this order:
+
+1. `paths[currentHost]`
+2. `path`
+3. legacy host-specific fields such as `githubPath`, `opencodePath`, `claudePath`, `cursorPath`, `windsurfPath`, `geminiPath`, `kiloPath`, `kimiPath`, `codexPath`
+
+Do not remove legacy fields during unrelated updates.
+
+## Mutation Rules
+
+- Additive changes only by default.
+- Do not silently rename or repurpose existing keys.
+- If a future migration is unavoidable, skills must remain tolerant readers until upgrade tooling can migrate old configs automatically.

package/.agents/skills/_shared/references/scope-rules.md

@@ -0,0 +1,55 @@
+# Work Scope Rules
+
+## Purpose
+
+This file defines how skills must adjust documents, recommendations, and work bounds based on `developerPreferences.scope` in `.agents/developer-config.json`.
+
+## Scope Values
+
+- `frontend`
+- `backend`
+- `fullstack`
+- *(missing)* → treat as `fullstack`
+
+## General Rules
+
+Skills that affect planning, workflow recommendations, or implementation MUST read `developerPreferences.scope` if the config file exists.
+
+- `frontend` → focus on UI, pages, components, state, styling, client-side validation, and API contracts from the consumer perspective.
+- `backend` → focus on API implementation, business rules, auth, services/repositories, database, and API contracts from the provider perspective.
+- `fullstack` → cover all areas.
+
+## Frontend Scope
+
+If scope = `frontend`:
+
+- MUST NOT generate `schema.md`
+- MUST NOT define controllers, services, DB queries, migrations, or backend internals
+- `api.md` may be created, but only as a **consumer contract**
+- `StyleGuide.md` remains relevant
+- `Task.md` contains frontend tasks only
+- If the backend is not ready, mark dependencies as `proposed`, `backend-owned`, `mock-only`, or `pending backend confirmation`
+
+## Backend Scope
+
+If scope = `backend`:
+
+- MUST NOT generate `StyleGuide.md`
+- MUST NOT define components, styling, or detailed UI behavior
+- `api.md` is created as a **provider contract**
+- `schema.md` remains relevant
+- `Task.md` contains backend tasks only
+
+## Fullstack Scope
+
+If scope = `fullstack`:
+
+- All documents and work areas may be covered
+
+## If a Skill Is Called Outside Scope
+
+If a skill is fully outside the user's scope:
+
+- Explain that the area is outside the current work scope
+- Do not generate documents or tasks in that area
+- If needed, point only to dependency contracts, not implementation details

package/.agents/skills/_shared/scripts/validate-skills.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[4]
+SKILLS_DIR = ROOT / ".agents" / "skills"
+
+
+def read(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def has_toc(text: str) -> bool:
+    return "## Daftar Isi" in text or "## Table of Contents" in text
+
+
+def check_skill_file(path: Path) -> list[str]:
+    issues: list[str] = []
+    text = read(path)
+    lines = text.splitlines()
+
+    if len(lines) > 500:
+        issues.append(f"{path}: more than 500 lines ({len(lines)})")
+
+    if "<SECURITY_REVIEW>" in text:
+        issues.append(f"{path}: <SECURITY_REVIEW> placeholder was not replaced")
+
+    if re.search(r"^```markdown\s*$", text, re.MULTILINE) and re.search(
+        r"^```(?:json|text|typescript|bash)\s*$", text, re.MULTILINE
+    ):
+        issues.append(
+            f"{path}: possible broken nested fence; check and use 4 backticks for the outer template"
+        )
+
+    return issues
+
+
+def check_reference_file(path: Path) -> list[str]:
+    issues: list[str] = []
+    text = read(path)
+    lines = text.splitlines()
+
+    if len(lines) > 100 and not has_toc(text):
+        issues.append(f"{path}: reference file >100 lines without a table of contents")
+
+    if (
+        "Baca `../references/runtime-config.md`" in text
+        or "Read `../references/runtime-config.md`" in text
+    ):
+        issues.append(
+            f"{path}: chained reference to runtime-config; caller skill should read shared refs directly"
+        )
+
+    return issues
+
+
+def main() -> int:
+    issues: list[str] = []
+
+    for skill_md in SKILLS_DIR.glob("**/SKILL.md"):
+        issues.extend(check_skill_file(skill_md))
+
+    for ref in SKILLS_DIR.glob("**/references/*.md"):
+        issues.extend(check_reference_file(ref))
+
+    if not issues:
+        print("OK: no skill authoring issues detected")
+        return 0
+
+    print("Skill validator findings:")
+    for issue in issues:
+        print(f"- {issue}")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())