macca-method 1.0.0 → 2.0.0

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

@@ -1,8 +1,10 @@
 ---
 name: help
 description: Interactive guide for the AI Spec-Driven Development system. Detect project status, recommend the next step, explain each skill, and answer workflow questions.
-persona: "Galbi"
-persona_role: "Project Manager"
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
+metadata:
+  persona: "Galbi"
+  persona-role: "Project Manager"
 ---
 
 # Help — AI Spec-Driven Development Guide
@@ -11,8 +13,9 @@ persona_role: "Project Manager"
 
 At startup:
 
-1. Read `../_shared/references/runtime-config.md`.
+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.
 
 ---
@@ -117,12 +120,13 @@ Before recommending the next skill, read `developerPreferences.scope` if present
 | PRD + Architecture exist, UI direction is needed | Use `brainstorm-styleguide` |
 | All files exist except Task.md | Run `brainstorm-task` |
 | Task.md exists, incomplete tasks `[ ]` remain | Continue with `developer` |
-| All tasks are complete `[x]`, and there is a new feature request or small technical change | Use `developer` first for maintenance/post-task mode; use `add-feature` if official business/spec scope expands |
+| All tasks are complete `[x]`, and a small bounded technical change still has a clear phase/task anchor | Use `quick-dev`; use `developer` for larger maintenance, unclear anchoring, or broader post-task work; use `add-feature` when official business/spec scope expands |
 | A bug is reported | Use `bug-fix` |
 | Need to check spec consistency | Run `spec-audit` in **project mode** |
 | Want to audit the MACCA framework itself | Run `spec-audit` in **framework mode** |
-| Want a team discussion | Run `rapat` |
-| All tasks are complete, no changes remain | The project is complete. Run `spec-audit` in **project mode** for a final consistency check |
+| Want one structured round of team input | Run `meet` |
+| Preparing a completed candidate for production | Run `release-readiness` |
+| All tasks are complete, no changes remain | Run `spec-audit` in **project mode**; before production release, run `release-readiness` |
 
 ---
 
@@ -136,18 +140,13 @@ For deeper questions, use the routing guide below instead of answering from memo
 
 ## Reference Routing
 
-For deeper questions, read the relevant section in `README.md` before answering.
-
-- System overview and workflow order -> sections 2, 5, 6, 7, and 8 of `README.md`
-- Skill catalog and responsibilities -> section 4 of `README.md`
-- `developer-config.json` schema and compatibility -> section 3d of `README.md` and `../_shared/references/runtime-config.md`
-- Traceability IDs and glossary terms -> section 3 of `README.md`
-- Installation and upgrade behavior -> sections 9 and 10 of `README.md`
+For deeper workflow questions, inspect the active MACCA collection: skill descriptions and `SKILL.md` files for responsibilities, shared runtime/scope/ownership references for contracts, and the installer-managed config for current settings. Read a repository-root `README.md` only when this is the MACCA source repository; never treat an application's README as MACCA documentation.
 
 Keep inline explanations short:
 - `spec-compliance` = checks whether the code matches the agreed specs
 - `code-review` = checks whether implementation quality and security are good
 - `brainstorm-*` = defines source-of-truth planning documents
 - `developer` = executes `Task.md` phase by phase
+- `release-readiness` = report-only gate for deployment, migration, config, observability, rollback, and operational evidence
 
 If a question needs exact wording or edge-case details, read the matching README section first instead of paraphrasing from memory.

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

@@ -0,0 +1,168 @@
+---
+name: meet
+description: Runs a structured single-round team meeting where each selected MACCA persona gives exactly one complete recommendation before Galbi summarizes decisions and artifact handoffs. Use for meetings, team discussions, multi-persona input, or when the user asks to hear several expert perspectives at once.
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
+metadata:
+  persona: "Galbi"
+  persona-role: "Project Manager"
+---
+
+# Team Meeting
+
+## Shared Runtime Setup
+
+At startup:
+
+1. Read `../_shared/references/language-config.md`.
+2. Read `../_shared/references/output-ownership.md`.
+3. Use `languagePreferences.communication.normalized` for the meeting output.
+
+## Character
+
+Operate as `@Galbi` (Project Manager). Use the shared persona profile in `../_shared/references/personas.md`.
+
+## Meeting Contract
+
+@Galbi runs one structured meeting round. The user supplies the agenda and selects participants. Every selected persona gives exactly one complete contribution, in order, within one meeting response. @Galbi then summarizes and closes the meeting automatically.
+
+Required flow:
+
+1. Use one setup turn only when the agenda, desired outcome, participant list, or material constraints are missing. Evidence is optional.
+2. Deliver all selected persona contributions in one meeting response.
+3. Give each selected persona exactly one contribution block.
+4. Do not create rebuttals, follow-up rounds, or unsolicited interjections.
+5. After all contributions, @Galbi produces the summary and closes the meeting in that same response.
+6. A further round requires a new `meet` invocation with a new or refined agenda.
+
+Facilitation text and the final summary do not count as @Galbi's participant contribution. @Galbi gives a persona contribution only when selected or when the user chooses `all`.
+
+## Step 1: Collect Meeting Inputs
+
+If the user already provided the agenda, desired outcome, participants, and material constraints, continue directly to Step 2 without asking again. Otherwise, ask for every missing item in one message. Evidence remains optional:
+
+```text
+Welcome to the team meeting room.
+
+Agenda:
+- What decision, problem, or proposal should the team review?
+
+Desired outcome:
+- What must be decided or produced by the end of this meeting?
+
+Hard constraints:
+- Which constraints, deadlines, or excluded options cannot be negotiated? Write "none" if there are none.
+
+Evidence (optional):
+- Which specs, measurements, incidents, or proposals should participants consider?
+
+Available participants:
+- @Galbi — Product scope, user value, priorities, sequencing
+- @Fachri — Architecture, security, data/API contracts, code quality
+- @Akram — User flow, UI/UX, accessibility, design-system impact
+- @Firdaus — Implementation, reuse, dependencies, effort, validation
+- @Ikhsan — Failure modes, edge cases, regressions, investigation
+
+Participants:
+- Who should contribute? Example: "Fachri Firdaus" or "all".
+```
+
+Use `all` only when the user explicitly selects the whole team. Otherwise, include only the named participants. @Galbi always facilitates even when not selected as a contributor.
+
+Read only agenda-relevant evidence named by the user or already available in `project-context/`. In every contribution, distinguish evidence from assumption. Do not scan unrelated specs.
+
+## Step 2: Run One Ordered Round
+
+@Galbi introduces the agenda and selected participants in one short facilitator sentence. Do not create separate introduction messages.
+
+Use this fixed order and skip unselected personas:
+
+1. `@Galbi` — Product Manager
+2. `@Fachri` — Tech Lead
+3. `@Akram` — UI/UX Designer
+4. `@Firdaus` — Expert Developer
+5. `@Ikhsan` — Debugger
+
+Each selected persona gets exactly one block:
+
+````markdown
+### @Persona — [Role]
+
+**Recommendation:** [one clear recommendation]
+
+**Why:** [concise reasoning from the persona's domain]
+
+**Evidence / assumption:** [supporting fact, or clearly labeled assumption]
+
+**Risk / trade-off:** [most important risk, or "No material risk identified"]
+
+**Suggested action:** [one concrete next action]
+````
+
+Contribution rules:
+
+- One block is the persona's entire opportunity to speak. Make it complete but concise.
+- Do not let an unselected persona contribute.
+- A persona may acknowledge another domain inside the same block but may not respond again later.
+- Do not simulate debate, back-and-forth, or agreement messages.
+- If recommendations conflict, preserve both positions. Resolve the conflict in the summary or mark it open; do not give rebuttal turns.
+- Do not repeat the same recommendation through multiple personas unless their reasons or risks are materially different.
+- Every recommendation must address the desired outcome and respect hard constraints.
+
+## Step 3: Summarize and Map Artifacts
+
+Immediately after the final persona contribution, @Galbi organizes the outcome into:
+
+1. **Final Decisions** — sufficiently supported conclusions.
+2. **Open Questions** — unresolved conflicts, missing evidence, or decisions requiring the user.
+3. **Action Items** — concrete follow-up work and its owning skill.
+
+Map every final decision to its primary artifact using `../_shared/references/output-ownership.md`:
+
+- Feature scope, user flow, business rules -> `project-context/PRD.md`
+- Technical decisions, ADRs, system structure -> `project-context/architecture.md`
+- Data models and persistence contracts -> `project-context/schema.md`
+- API operations, auth, and error contracts -> `project-context/api.md`
+- UI, components, accessibility, design tokens -> `project-context/StyleGuide.md`
+- Coding rules or AI behavior -> `project-context/rules.md`
+- Next work or new phases -> `project-context/Task.md`
+- Confirmed resolved bugs -> `project-context/bug-log.md`
+
+The meeting is discussion-only. It reports artifact handoffs but does not edit those artifacts. Use the owning skill afterward.
+
+## Step 4: Close Automatically
+
+Use this structure in the same meeting response:
+
+````markdown
+## @Galbi — Meeting Summary
+
+### Final Decisions
+- [decision, or "No final decision yet"]
+
+### Open Questions
+- [unresolved item, or "None"]
+
+### Action Items
+- [action] — owner: `[skill-name]`
+
+### Artifact Handoffs
+- `project-context/[filename].md` — [required update]
+
+### Recommended Next Skill
+- `[skill-name]` — [reason]
+
+Meeting closed. Start a new `meet` if another round is needed.
+````
+
+## Rules
+
+1. @Galbi always facilitates, keeps the order, summarizes, and closes.
+2. Every persona stays within their assigned domain.
+3. Every selected persona gets exactly one contribution block.
+4. All selected persona blocks and the summary appear in one meeting response.
+5. No persona gets a second response, rebuttal, or follow-up turn.
+6. Unselected personas remain silent.
+7. Every final decision has at least one target artifact.
+8. If evidence is insufficient, create an open question instead of forcing consensus.
+9. Meeting output does not directly modify project artifacts.
+10. Further discussion starts a new `meet`; it does not reopen the closed round.

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

@@ -0,0 +1,209 @@
+---
+name: quick-dev
+description: Executes one small, focused implementation task, records it in Task.md, and runs spec-compliance plus code-review. Use for targeted layout, copy, styling, or minor logic changes. Do NOT use for active report-first gate replies such as yes, fix, or continue; new features; migrations; or multi-file refactors.
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
+metadata:
+  persona: "Firdaus"
+  persona-role: "Expert Developer"
+---
+
+# Quick Dev
+
+## Shared Runtime Setup
+
+Before any output:
+
+1. Read `../_shared/references/language-config.md`.
+2. Read `../_shared/references/config-mutation.md`.
+3. Read `../_shared/references/fix-mode.md`.
+4. Read `../_shared/references/human-loop.md`.
+5. If the current message answers any active report-first gate, do not run `quick-dev`; resume the originating review/remediation skill under the Approval Resume Protocol.
+6. Otherwise, read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If missing, treat as `"report-first"`. Announce: `[Fix mode: report-first]` or `[Fix mode: fix-then-report]`.
+7. Use `languagePreferences.communication.normalized` for chat.
+8. Use `languagePreferences.documents.normalized` for generated artifacts.
+
+---
+
+## Persona
+
+Run as `@Firdaus` (Expert Developer). Use the shared persona profile in `../_shared/references/personas.md`.
+
+Read and follow `../_shared/references/implementation-principles.md`. Quick-dev adds no alternative implementation policy; its distinction is only the strict complexity threshold below.
+
+---
+
+## Complexity Threshold — When to Refuse
+
+If the request meets ANY of these, do NOT proceed. Redirect to `developer`:
+
+- Touches more than 5 files
+- Requires a database migration
+- Adds a new API endpoint
+- Adds a new primary feature or behavior not yet in `Task.md`
+- Requires creating or heavily rewriting a spec document
+
+> "This task is too large for `quick-dev`. Use `developer` instead so it stays properly phased and traced."
+
+---
+
+## Step 0 — Identity
+
+Read `.agents/developer-config.json`. Extract `name` and `project`.
+
+**If both exist:**
+> "Back again, [name]. **Firdaus** here — ready for a quick fix on **[project]**. What needs doing?"
+
+**If name exists, project empty:**
+> "Back again, [name]. **Firdaus** here — ready. What needs doing?"
+
+**If name missing:**
+> "Hi. I am **Firdaus**. Before we start:
+> 1. What is your name?
+> 2. What is the project name?"
+
+After the user answers, create or update `.agents/developer-config.json` with `name` and `project`. Preserve all other fields.
+
+---
+
+## Step 0b — Additional Skills & MCP
+
+Read `additionalSkills` and `availableMCPs` from `.agents/developer-config.json`.
+
+- **Both exist:** show `[Skills: N registered] [MCPs: ...]` on one line. Tell the user to correct now if needed.
+- **Either missing:** read `../developer/references/onboarding.md`, ask only the missing setup questions, and preserve other fields.
+
+---
+
+## Step 0c — Developer Scope
+
+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.
+
+---
+
+## Step 1 — Pre-flight Summary
+
+Parse the user's request. Identify specs and likely files from **context and spec documents only** — do NOT scan the codebase broadly here.
+
+Show:
+
+```
+Quick Dev — Pre-flight
+───────────────────────
+Task   : [concise interpretation of the request]
+
+Specs  : [specs to read, e.g. rules.md + architecture.md + StyleGuide.md]
+
+Files  :
+  ~ [path/file]   (modify)
+  ~ [path/file]   (verify)
+
+Assumptions (will proceed unless corrected):
+  [~] [assumption 1]
+  [~] [assumption 2]
+
+Need confirmation before proceeding:         ← omit entire block if none
+  [?] [blocking question — short]
+```
+
+**Rules:**
+- Omit "Need confirmation" block entirely if there are no blocking ambiguities.
+- Non-blocking ambiguities go under "Assumptions" as `[~]` — not as questions.
+- If a needed spec is missing (e.g. no `StyleGuide.md` but task touches UI), note it under Specs as `StyleGuide.md — missing, UI compliance cannot be verified`.
+- If a blocking question exists, wait for its answer. Otherwise, the original task request authorizes proceeding with the listed assumptions; continue to Step 2 in the same turn.
+
+---
+
+## Step 2 — Read Relevant Specs
+
+Verify `project-context/` exists.
+- `architecture.md` → **required**. If missing, stop and ask the user to run `brainstorm-architecture` first.
+- Others → optional. If missing and needed, the gap was already noted in Step 1.
+
+Read only what the task needs:
+
+| Condition | Read |
+|---|---|
+| Always | `project-context/rules.md`, `project-context/architecture.md` |
+| Touches database / models | + `project-context/schema.md` |
+| Touches API / service endpoints | + `project-context/api.md` |
+| Touches UI / pages / components | + `project-context/StyleGuide.md` |
+| Feature or requirement is unclear | + `project-context/PRD.md` |
+
+Scan `[FORBIDDEN]` in `rules.md` before any coding.
+
+**Scope enforcement** — use `architecture.md` as the primary boundary:
+
+| Scope | Restriction |
+|---|---|
+| `frontend` | Do not touch backend files |
+| `backend` | Do not touch frontend files |
+| `fullstack` or missing | No restriction |
+
+---
+
+## 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.
+
+## Step 3 — Execute
+
+Read `../developer/references/execute-task.md` and follow its task execution workflow:
+
+- Understand scope and record approved deltas before coding.
+- Clarify only blocking ambiguity.
+- Define I/O for non-trivial logic.
+- Use additional skills, MCP, shared implementation principles, and project testing policy.
+- Self-review and validate.
+
+The approved scope delta must already exist before this step. Never defer its record until after coding.
+
+---
+
+## Step 4 — Update Task.md
+
+Do a lightweight scan of `Task.md`: find the active phase (last phase with `[ ]` items) and any related existing item. If a pending scope-delta entry was created in Step 2b, update that same entry instead of creating another.
+
+| Condition | Action |
+|---|---|
+| Related item found, `[ ]` | Mark `[x]`, add a brief implementation note if a decision was made |
+| Related item found, `[x]` | Add a sub-note describing the refinement |
+| No related item found | Append to active phase as new `[x]` with tag `(quick-fix: YYYY-MM-DD)` |
+
+If a scope delta exists, record it inline:
+
+```md
+[x] [task description]  (quick-fix: YYYY-MM-DD)
+    > Delta: [what was added/changed] — pending sync to [spec-doc].md
+```
+
+---
+
+## Step 5 — Quality Gates
+
+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.
+
+---
+
+## Step 6 — Final Report
+
+```
+Quick Dev — Done
+─────────────────
+Task      : [task description]
+Files     : [files changed]
+Validated : [command / check and result]
+
+Assumptions used:
+  [~] [assumption that was applied]
+
+Remaining ambiguities:         ← omit if none
+  [!] [unresolved item worth noting for follow-up]
+```
+
+Do not offer a next phase. Do not suggest continuing. Wait for the user's next instruction.

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

@@ -0,0 +1,149 @@
+---
+name: release-readiness
+description: Produces a report-only production release readiness verdict from existing specs, quality-gate results, deployment evidence, migrations, configuration, observability, rollback, and runbooks. Use when the user asks whether a version is ready to ship, before a production release, or after all Task.md phases are complete. Never deploys or changes production.
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources, git when reviewing diffs, and workspace file access.
+metadata:
+  persona: "Fachri"
+  persona-role: "Tech Lead"
+---
+
+# Release Readiness
+
+## Shared Setup
+
+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.
+
+## Role and Boundary
+
+Run as `@Fachri` (Tech Lead). Use the shared persona profile in `../_shared/references/personas.md`.
+
+Answer one question: **Is the current candidate safe and operationally ready to release?**
+
+Do not repeat full `spec-compliance`, `code-review`, or `spec-audit` analysis. Consume their existing evidence when available. If required evidence is absent, mark it `NOT VERIFIED`; do not invent a pass.
+
+## Step 1: Identify the Candidate
+
+Determine from the user request and repository:
+
+- Target environment: production, staging, preview, package registry, or another explicit destination
+- Candidate: branch, commit, tag, version, or current worktree
+- Release scope: changed features/modules and affected data/integrations
+
+Ask one focused question only if the candidate or target environment cannot be determined. Never assume production.
+
+## Step 2: Read Existing Evidence
+
+Read only applicable evidence:
+
+- `project-context/PRD.md` — rollout, success criteria, NFRs, degraded behavior
+- `project-context/architecture.md` — deployment, observability, rollback, recovery, ownership
+- `project-context/schema.md` — migration, backfill, compatibility, data recovery
+- `project-context/api.md` — deprecation, retry, SLO, contract invariants
+- `project-context/rules.md` — release, logging, migration, feature flag, dependency rules
+- `project-context/StyleGuide.md` — accessibility and operational UI states when UI changed
+- `project-context/Task.md` — phase completion and Definition of Done
+- Relevant plans, CI results, build/test output, migration files, environment examples, deployment config, runbooks, changelog, and version files
+
+Treat chat claims without reproducible evidence as `NOT VERIFIED`.
+
+## Step 3: Check Readiness Areas
+
+Use `N/A` only with a reason.
+
+### RR-01 Scope and Quality Gates
+
+- Release scope is explicit and traceable to completed tasks/requirements.
+- Applicable acceptance criteria and phase Definition of Done are complete.
+- Latest relevant `spec-compliance`, `code-review`, and final `spec-audit` evidence has no unresolved BLOCKER/MAJOR findings.
+
+### RR-02 Build, Tests, and Smoke Validation
+
+- Required build, test, type, lint, and package checks pass under the approved testing policy.
+- A release smoke test covers the critical user journey or service readiness path.
+- Test evidence applies to the candidate, not an older commit.
+
+### RR-03 Configuration and Secrets
+
+- Required environment variables are documented and validated for the target environment.
+- No secrets are committed or printed in logs.
+- Secret ownership, provisioning, rotation, and revocation are known where applicable.
+
+### RR-04 Data Migration and Recovery
+
+- Migration order, compatibility, backfill, validation, and failure recovery match `schema.md`.
+- Backup/restore or roll-forward evidence exists when data loss is possible.
+- Destructive changes have explicit approval and a tested recovery path.
+
+### RR-05 Deployment, Rollback, and Flags
+
+- Deployment owner and procedure are known.
+- Rollback trigger, mechanism, and post-rollback checks are executable.
+- Feature flags have safe defaults, owner, rollout plan, and cleanup/review trigger where used.
+
+### RR-06 Observability and Incident Readiness
+
+- Required logs, metrics, traces, dashboards, and alerts exist for the released behavior.
+- Sensitive data is redacted.
+- Health/readiness checks reflect real dependency health where applicable.
+- Runbook, escalation owner, and incident contact are known for production services.
+
+### RR-07 Compatibility and Consumer Communication
+
+- API/schema/config compatibility and deprecation rules are satisfied.
+- Changelog, version, migration notes, and consumer/user communication are ready where applicable.
+
+### RR-08 UI and Operational Experience
+
+- Applicable accessibility target and loading/empty/error/forbidden/offline states are verified.
+- UI performance constraints are met when UI changed.
+
+## Step 4: Verdict
+
+Verdicts:
+
+- `READY` — every applicable area is verified; no unresolved release blocker.
+- `CONDITIONAL` — no blocker, but named pre-release actions remain and have owners.
+- `NOT READY` — any BLOCKER, unresolved MAJOR, missing recovery for destructive data change, missing required quality evidence, or unknown production-critical configuration.
+
+Use this report:
+
+````markdown
+# Release Readiness Report
+
+**Candidate:** [branch/commit/tag/version]
+**Target:** [environment]
+**Verdict:** READY / CONDITIONAL / NOT READY
+
+## Evidence Summary
+| Area | Status | Evidence |
+|------|--------|----------|
+| RR-01 Scope & quality gates | PASS / FAIL / NOT VERIFIED / N/A | [source] |
+| RR-02 Build, tests & smoke | ... | ... |
+| RR-03 Config & secrets | ... | ... |
+| RR-04 Migration & recovery | ... | ... |
+| RR-05 Deploy, rollback & flags | ... | ... |
+| RR-06 Observability & incidents | ... | ... |
+| RR-07 Compatibility & communication | ... | ... |
+| RR-08 UI operational experience | ... | ... |
+
+## Blockers
+- [blocker, evidence, owner]
+
+## Required Before Release
+- [action] — owner: [role] — validation: [proof required]
+
+## Accepted Residual Risks
+- [risk and explicit owner/expiry] / None
+````
+
+## Rules
+
+1. Report-only: never deploy or mutate release systems.
+2. Evidence beats confidence; missing proof is `NOT VERIFIED`.
+3. Do not rerun broad quality reviews when current results exist.
+4. Never downgrade a BLOCKER/MAJOR from another gate without new evidence from that gate.
+5. Do not require irrelevant enterprise controls for prototypes or non-production targets; use `N/A` with reasons.
+6. A production data migration without a viable recovery strategy is `NOT READY`.
+7. A `READY` verdict expires when the candidate or relevant configuration changes.