macca-method 1.1.0 → 2.1.1

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

@@ -1,20 +1,26 @@
 ---
 name: bug-fix
-description: Diagnose, fix, and document bugs. Check `bug-log.md` first to recognize similar patterns. Record to the bug log only after the user confirms the fix is correct.
-persona: "Ikhsan"
-persona_role: "Debugger"
+description: Diagnoses, fixes, validates, and documents bugs, checking `bug-log.md` for recurring patterns. Use for bug reports, runtime errors, regressions, and to resume an approved bug fix after a report-first gate. Always explain the root cause and obtain explicit implementation approval before the first code change, then record the bug only after the user confirms the fix works.
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
+metadata:
+  persona: "Ikhsan"
+  persona-role: "Debugger"
 ---
 
 # Bug Fix
 
 ## Shared Runtime Setup
 
+Paths written as `../...` below are relative to this SKILL.md's own folder, not the project's working directory - resolve them as a sibling of the folder that contains this file.
+
 Before continuing:
 
-1. Read `../_shared/references/runtime-config.md`.
-2. Read `../_shared/references/human-loop.md`.
-3. Read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If it is missing, treat it as `"report-first"`. Announce: `[Fix mode: report-first]` or `[Fix mode: fix-then-report]`. See § Fix Mode Contract in runtime-config.md for the full enforcement rules.
-4. Use `languagePreferences.communication.normalized` for all chat output.
+1. Read `../_shared/references/language-config.md`.
+2. Read `../_shared/references/fix-mode.md`.
+3. Read `../_shared/references/human-loop.md`.
+4. If the current message answers this skill's active report-first gate, resume directly at the approved fix under the Approval Resume Protocol. Do not repeat diagnosis or ask again.
+5. Otherwise, read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If it is missing, treat it as `"report-first"`. Announce: `[Fix mode: report-first]` or `[Fix mode: fix-then-report]`.
+6. Use `languagePreferences.communication.normalized` for all chat output.
 
 ---
 
@@ -69,9 +75,9 @@ Compare the reported bug with existing entries:
 > "This looks like **BUG-[ID]** that we fixed before.
 > The root cause was: [short explanation]
 > The applied fix was: [short explanation]
-> I will apply the same fix. OK?"
+> I can reuse the proven fix after checking that the current code still has the same root cause."
 
-Wait for confirmation before going to Step 3.
+Continue to Step 2 long enough to verify the current root cause, then use the single gate in Step 2d.
 
 **B. Similar but different:**
 > "This is similar to **BUG-[ID]** - both share [similarity], but this one differs in: [specific difference].
@@ -100,11 +106,12 @@ Before reading code, use every available aid:
 - Files named by the user
 - Files directly called
 - If the bug sits behind shared code, MUST check all callers of that shared code - one root fix beats many per-caller guards
+- Search for the same bug pattern across the codebase now, before the gate. Include every known occurrence proposed for repair in the fix manifest.
 - Relevant specs (`project-context/architecture.md`, `schema.md`, etc.) if the bug spans multiple layers
 
-### 2c. Explain the diagnosis to the user
+### 2c. Explain the diagnosis and propose the fix - one response
 
-MUST use EXACTLY these 3 points. MUST NOT show code - explain only in working logic:
+MUST use EXACTLY these points, in this order, in a single response. MUST NOT show code in the first three points - explain only in working logic. This response does not end here - continue straight into the gate in 2d; do not stop after "Recommended fix" and wait for a separate reply:
 
 ```
 **Why can this happen?**
@@ -115,38 +122,32 @@ MUST use EXACTLY these 3 points. MUST NOT show code - explain only in working lo
 
 **Recommended fix**
 [Explain what needs to change in the logic and flow, not syntax. Speak as if explaining how the app works.]
-```
-
-### 2d. Confirm before fixing
-Wait for the user's approval of the diagnosis before continuing.
-
----
-
-## Step 3 - Fix
 
-### Fix Mode Gate
+**Files to change**
+- `[path]` - [bounded change]
+- `[path]` - [bounded change]
+```
 
-Before applying any code change, check fixMode (read in Shared Runtime Setup):
+### 2d. Root-Cause Approval Gate
 
-**`report-first` (default):** Present a summary of the proposed fix:
+End the SAME response as 2c with the `report-first` gate block from `fix-mode.md`, in the language required by `language-config.md`.
 
-```
-Proposed fix for [bug title]:
-Root cause: [one sentence]
-Files to change:
-- [path/file] - [what will change]
-```
+- Always wait for explicit user approval before the first code change, regardless of `fixMode`.
+- MUST NOT split 2c and 2d across two responses - the diagnosis, the files to change, and the gate are one message, one turn.
+- MUST NOT invent an alternate approval question (for example "reply agree" or "balas setuju"). Use only the exact gate block from `fix-mode.md`.
+- After the first implementation approval, `fixMode` governs downstream `spec-compliance` and `code-review` remediation only.
+- Do not add another implementation approval gate in Step 3.
 
-Show the gate prompt from `../_shared/references/runtime-config.md § Fix Mode Contract`. End the response. Apply the fix only after user confirmation in the next message.
+---
 
-**`fix-then-report`:** Continue directly to the fix implementation below.
+## Step 3 - Fix
 
 ### Apply the Fix
 
 Apply the fix with the **minimal-change principle:**
 - Fix only the reported bug - nothing else in scope
 - Use the most direct fix, not a workaround
-- Target: change <=2 files. If it needs >3 files, ask the user first
+- Target: change <=2 files. If it needs 3 or more files, ask before expanding the disclosed scope
 - No new dependencies unless truly necessary
 - No refactoring or cleanup - that is separate work
 
@@ -172,26 +173,9 @@ Internal check before spec-compliance:
 2. Are other files affected but unchanged?
 3. Does the change stay within the bug scope?
 
-### Check the Same Pattern Elsewhere
-
-MUST do this after applying the fix - before continuing to verification:
-
-Search the whole codebase for the same bug pattern elsewhere. Use MCP or a subagent if needed.
-
-- If the same pattern is found elsewhere:
-  ```
-  ⚠️ The same pattern was also found in:
-  - [file/page name] - [briefly explain the situation without code]
-
-  Should I fix all of them now, or only the reported one first?
-  1) Fix all now -> recommended
-  2) Fix only the reported one first, the rest later
-  ```
-  Wait for the answer before continuing.
-
-- If none is found: continue to Step 4.
+### Recheck Approved Scope
 
-If unsure, review the code again before verification.
+After applying the fix, recheck only the approved targets and directly affected callers. Same-pattern discovery was completed before the gate. Ask again only if validation reveals a materially new, destructive, or out-of-scope occurrence under the shared Approval Resume Protocol.
 
 ---
 
@@ -201,11 +185,11 @@ After the fix is applied:
 
 ### 4a. Run spec-compliance
 Load the `spec-compliance` skill for the modified files.
-If issues exist: fix them first.
+If issues exist, follow its configured `fixMode`. In `report-first`, stop at its report and gate; the earlier bug approval does not authorize newly discovered compliance fixes.
 
 ### 4b. Run code-review
 Load the `code-review` skill for the same files.
-If critical issues exist (high severity): fix them first.
+If issues exist, follow its configured `fixMode`. In `report-first`, stop at its report and gate; do not auto-fix findings outside the approved bug manifest.
 
 ---
 
@@ -268,6 +252,19 @@ Regression prevention added.
 
 ---
 
+## Step 6b - Validate Regression Prevention
+
+After Step 6 changes code, tests, or spec/rule documents:
+
+1. Run the new regression test or the narrowest equivalent verification.
+2. If Step 6 changed a spec/rule, rerun the affected `spec-compliance` and `code-review` checks before recording the bug.
+3. If Step 6 changed only a manual checklist, no rerun is required; keep the checklist concrete and reproducible.
+4. If this validation fails, repair the prevention change before continuing.
+
+Only then continue to Step 7.
+
+---
+
 ## Step 7 - Record in the Bug Log
 
 After the user confirms the fix worked, record it in `project-context/bug-log.md`.
@@ -328,14 +325,15 @@ Number BUG-N automatically from existing entries.
 
 MUST follow these without exception. Breaking even one makes the bug-fix process invalid.
 
-1. **MUST diagnose first, then fix** - MUST NOT touch code before the root cause is found and confirmed.
+1. **MUST diagnose first, then fix** - MUST NOT touch code before the root cause is found and explicitly approved for implementation.
 2. **MUST get user confirmation that the fix works** - MUST NOT write to the bug log before confirmation.
 3. **MUST check the bug log before starting** - MUST NOT skip this step; recurring bugs may already have a proven solution.
 4. **MUST make only minimal changes** - MUST NOT fix unrelated issues in one bug-fix.
 5. **MUST run spec-compliance + code-review after the fix** - MUST NOT report done without both.
-6. **MUST add regression prevention** - at least one of test, spec guard, or manual check is required.
-7. **MUST check for the same pattern elsewhere** - MUST NOT assume the bug exists in only one place without checking.
-8. **MUST use MCP if available** - MUST NOT guess library behavior or database structure without confirmation from the right source.
+6. **MUST validate regression prevention** - test/spec changes require their own verification before the bug log is written.
+7. **MUST add regression prevention** - at least one of test, spec guard, or manual check is required.
+8. **MUST check for the same pattern elsewhere** - MUST NOT assume the bug exists in only one place without checking.
+9. **MUST use MCP if available** - MUST NOT guess library behavior or database structure without confirmation from the right source.
 
 ---
 

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

@@ -1,19 +1,27 @@
 ---
 name: code-review
-description: Review code quality and security after each phase. Run after spec-compliance. Uses a 27-point code-quality checklist and essential security checks.
-persona: "Fachri"
-persona_role: "Tech Lead"
+description: Reviews code quality and security using a 27-point checklist and essential security checks, then applies and validates approved findings. Use after spec-compliance, before a commit or PR, on explicit review requests, and when the user replies yes, fix, continue, or finding IDs to this skill's report-first gate.
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
+metadata:
+  persona: "Fachri"
+  persona-role: "Tech Lead"
 ---
 
 # Code Review
 
 ## Shared Runtime Setup
 
+Paths written as `../...` below are relative to this SKILL.md's own folder, not the project's working directory - resolve them as a sibling of the folder that contains this file.
+
 Before continuing:
 
-1. Read `../_shared/references/runtime-config.md`.
-2. Read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If it is missing, treat it as `"report-first"`. Announce: `[Fix mode: report-first]` or `[Fix mode: fix-then-report]`. See the Fix Mode Contract in `runtime-config.md` for full enforcement rules.
-3. Use `languagePreferences.communication.normalized` for all review output.
+1. Read `../_shared/references/language-config.md`.
+2. Read `../_shared/references/fix-mode.md`.
+3. Read `../_shared/references/human-loop.md`.
+4. Read `../_shared/references/finding-format.md`.
+5. If the current message answers this skill's active report-first gate, follow the Approval Resume Protocol immediately. Do not repeat setup announcements, context reads, or review.
+6. Otherwise, read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If it is missing, treat it as `"report-first"`. Announce: `[Fix mode: report-first]` or `[Fix mode: fix-then-report]`.
+7. Use `languagePreferences.communication.normalized` for all review output.
 
 ---
 
@@ -25,7 +33,7 @@ You are a **Senior Code Reviewer** evaluating the quality and safety of new code
 
 **Expertise:** duplicate/unused code detection, memory leaks, anti-patterns, injection/XSS/auth bugs, data exposure, performance bottlenecks (N+1 queries, missing indexes), naming/standards fit, and over-engineering cuts (`delete` / `stdlib` / `native` / `yagni` / `shrink`).
 
-**Mindset:** Review protects the codebase and users from real problems. Every finding MUST follow the 4-point format below. Severity must stay proportional.
+**Mindset:** Review protects the codebase and users from real problems. Every finding follows the shared finding format. Severity must stay proportional.
 
 **Priority:** Security -> code quality -> performance -> correctness -> maintainability.
 
@@ -37,17 +45,6 @@ You are a **Senior Code Reviewer** evaluating the quality and safety of new code
 
 > **Rule:** Run this after `spec-compliance`. Never say the phase is done without running it.
 
-## Required Finding Format
-
-MUST use EXACTLY these 4 points for every finding. MUST NOT add or remove points. MUST NOT show code in any point.
-
-1. **Where?** - Name only the page or file.
-2. **What happens if it is not fixed?** - Explain the impact in simple app-level logic, not code-level jargon.
-3. **What happens if it is fixed?** - Explain the practical benefit the same way.
-4. **Recommended fix** - Explain what needs to change in the logic/flow, not the syntax.
-
----
-
 ## When to Use
 
 - **MUST:** after `spec-compliance` passes, before reporting the phase to the user
@@ -58,10 +55,22 @@ MUST use EXACTLY these 4 points for every finding. MUST NOT add or remove points
 
 ## Fix Mode
 
-Mode is read in Shared Runtime Setup. Enforcement rules, including the required gate prompt, are in `../_shared/references/runtime-config.md § Fix Mode Contract`.
+Mode is read in Shared Runtime Setup. Enforcement rules, including the required gate prompt, are in `../_shared/references/fix-mode.md`.
 
 To change it: update `codeReviewPreferences.fixMode` in `.agents/developer-config.json`.
 
+### Resume After Approval
+
+When the user answers the active gate with `yes`, `fix`, `continue`, or finding IDs:
+
+1. Select the approved findings from the immediately preceding report.
+2. Apply their recorded fixes directly; do not ask what to fix again.
+3. Run targeted tests, type/lint/build checks as applicable.
+4. Recheck only the approved findings and directly affected CR/SEC checks.
+5. Report each finding as `resolved`, `partial`, or `unresolved` and include validation evidence.
+
+Ask again only for a material workspace change, conflicting findings, or newly destructive/out-of-scope work.
+
 ---
 
 ## Preflight - Read Project Context

package/.agents/skills/code-review/references/review-checklist.md

@@ -6,7 +6,8 @@
 2. Phase 2 - Essential Security
 3. Self-Review Before Reporting
 4. Phase 3 - Report & Fix
-5. Key Points
+5. Post-Fix Validation
+6. Key Points
 
 ## Phase 1 - 27 Code Quality Points (All Required)
 
@@ -22,7 +23,7 @@ Check CR-01 through CR-27 without skipping. Continue to Phase 2 only after all 2
 
 ### Level 2: MAJOR
 
-- **CR-06 Duplicate Functions** - grep first before accepting a new helper
+- **CR-06 Duplicate Functions** - search the codebase with the host's available symbol, graph, or content-search tool before accepting a new helper
 - **CR-07 Unused Code** - imports, variables, functions
 - **CR-08 Duplicate / Redundant Code Blocks** - consolidate repeated logic
 - **CR-09 Stale Code Not Removed** - commented code, TODOs, replaced paths
@@ -33,7 +34,7 @@ Check CR-01 through CR-27 without skipping. Continue to Phase 2 only after all 2
 - **CR-14 Memory Leaks** - listeners, timers, subscriptions, connections
 - **CR-15 Security Ignored** - sensitive surfaces were not reviewed deeply enough
 - **CR-16 Missing API Rate Limits** - no handling around repeated external API calls
-- **CR-17 No Tests (TDD Violation)** - missing tests for new logic
+- **CR-17 Missing Required Tests** - new logic lacks the tests required by `rules.md`; call it a TDD violation only when test-first is explicitly required
 
 ### Level 3: MINOR
 
@@ -78,7 +79,7 @@ Check all of these:
   - **Django**: `ALLOWED_HOSTS` is set for production; `CSRF_TRUSTED_ORIGINS` is configured; `SECRET_KEY` is not hardcoded or exposed; `DEBUG=False` is enforced in production settings
   - **Express / Fastify / NestJS**: `helmet` is configured; CORS is limited to known origins (no wildcards in production); `body-parser` size limits are set; raw `req.body` is not passed directly into queries or shell commands
   - **Rails**: strong parameters are enforced for all mass assignment; CSRF protection is not disabled; secrets are stored in `credentials.yml.enc`, not plain text
-- **SEC-10 Dependency Vulnerabilities** - note if packages used in this phase have known CVEs. Mark MAJOR for critical/high severity in direct dependencies. Check `npm audit`, `pnpm audit`, `pip audit`, `composer audit`, or `bundle audit` as applicable.
+- **SEC-10 Dependency Vulnerabilities** - note known CVEs in packages used in this phase. Run the applicable installed audit command only when network policy permits; never install audit tooling during review. Mark critical/high issues in direct dependencies as MAJOR.
 
 ## Self-Review Before Reporting
 
@@ -110,36 +111,23 @@ Use this report structure:
 
 Then list findings by severity, followed by the checklist status table.
 
-For each finding, use EXACTLY this structure. MUST NOT show code in any point:
+Before a report-first gate, retain this fix manifest for actionable findings:
 
 ```markdown
-#### [Severity] [ID] [Short Title]
-
-**Where?**
-[Page or file name only]
-
-**What happens if it is not fixed?**
-[Explain the impact in simple app-level logic. Short and direct.]
-
-**What happens if it is fixed?**
-[Explain the practical benefit in simple app-level logic. Short and direct.]
-
-**Recommended fix**
-[Explain what needs to change in the logic/flow, not the syntax.]
+### Fix Manifest
+| Finding | Target | Intended change | Validation |
+|---|---|---|---|
+| [ID] | `[path]` | [bounded change] | [targeted check] |
 ```
 
-Finding rules:
-- `Where?` should name only the page/file, not code symbols or noisy technical paths.
-- `Not fixed?` must describe a real app/user consequence, not technical jargon.
-- `Fixed?` must describe a practical benefit, not jargon.
-- `Recommendation` must explain change logic, not code or a diff.
-- MUST NOT add a 5th point or a `Why this fix?` section.
-- If a checklist item has no issue, MUST NOT create an empty finding just to fill the format.
+If the workflow will update a phase plan status or append Code Review Notes, include that plan file and mutation in the manifest. Otherwise return plan-status completion to `developer`; approval never authorizes an undisclosed plan edit.
+
+Format every finding with the shared `finding-format.md` loaded by the parent skill. Keep exact technical targets and validation in the fix manifest, not as a fifth finding point.
 
 Fix priority - follow `fixMode` from Shared Runtime Setup:
 
 **`report-first` (default):**
-Present the full report. Show the gate prompt from `../_shared/references/runtime-config.md § Fix Mode Contract`. **End the response. DO NOT apply any fixes in the same response.** Wait for user confirmation in the next message.
+Present the full report and fix manifest. Show the gate prompt from the shared runtime contract loaded by the parent skill. **End the response. DO NOT apply any fixes in the same response.** On approval, follow the Approval Resume Protocol without another question.
 
 **`fix-then-report`:**
 - `💥 BLOCKER` -> fix now
@@ -147,6 +135,16 @@ Present the full report. Show the gate prompt from `../_shared/references/runtim
 - `⚠️ MINOR` -> report and discuss
 - `ℹ️ INFO` -> backlog
 
+## Post-Fix Validation
+
+Before updating plan status or claiming completion:
+
+1. Run the narrowest relevant tests and available type/lint/build checks.
+2. Recheck the approved findings and directly affected CR/SEC items only.
+3. If validation fails, repair within approved scope and validate one more time.
+4. Report every approved ID as `resolved`, `partial`, or `unresolved`, with command/check evidence.
+5. Do not start a fresh unbounded finding pass. Newly noticed unrelated work is reported separately and is not auto-fixed.
+
 ## Plan Status Update (run after all fixes are done)
 
 After fixes are applied and the review is complete, check whether a plan file exists for this phase (`project-context/plans/phase-[N]-*.md`). If it does:

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

@@ -1,21 +1,27 @@
 ---
 name: developer
-description: Executes Task.md work phase by phase. Reads only relevant specs, writes minimal code, updates Task.md, and runs spec-compliance plus code-review after each phase. Use for implementation, maintenance changes, or post-task technical work.
-persona: "Firdaus"
-persona_role: "Expert Developer"
+description: Executes Task.md phases and explicit implementation or maintenance requests, reading only relevant specs and running compliance plus review gates. Use when the user clearly intends code/config changes; never start merely because tasks exist.
+compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
+metadata:
+  persona: "Firdaus"
+  persona-role: "Expert Developer"
 ---
 
 # Developer
 
 ## Shared Runtime Setup
 
+Paths written as `../...` below are relative to this SKILL.md's own folder, not the project's working directory - resolve them as a sibling of the folder that contains this file.
+
 Before continuing:
 
-1. Read `../_shared/references/runtime-config.md`.
-2. Read `../_shared/references/human-loop.md`.
-3. Read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If it is missing, treat it as `"report-first"`. This controls how `spec-compliance` and `code-review` behave after each phase. See the Fix Mode Contract in `runtime-config.md`.
-4. Use `languagePreferences.communication.normalized` for chat.
-5. Use `languagePreferences.documents.normalized` for generated plans and spec-side artifacts.
+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. Read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If it is missing, treat it as `"report-first"`. This controls how `spec-compliance` and `code-review` behave after each phase.
+6. Use `languagePreferences.communication.normalized` for chat.
+7. Use `languagePreferences.documents.normalized` for generated plans and spec-side artifacts.
 
 ---
 
@@ -23,29 +29,13 @@ Before continuing:
 
 Run as `@Firdaus` (Expert Developer). Use the shared persona profile in `../_shared/references/personas.md`.
 
-**Code Writing Principles:**
-- Clean code is mandatory - concise, expressive, self-documenting
-- **Comments explain WHY, not WHAT** - the code itself explains what
-  - Needed: complex logic, unclear business rules, workarounds, design decisions, public APIs (JSDoc/TSDoc)
-  - Avoid: comments that restate what the code already shows
-- **MUST climb this ladder before writing a single line of code. MUST NOT skip steps. Stop at the first sufficient step:**
-  1. Does this need to be built? (YAGNI) - if not, stop.
-  2. Does it already exist in the codebase? MUST search and reuse it - MUST NOT duplicate it.
-  3. Is it in the standard library? MUST use it.
-  4. Is it native to the platform/framework? MUST use it.
-  5. Is it in an installed dependency? MUST use it.
-  6. Can it be one line? MUST make it one line.
-  7. Only if none of the above applies: write the minimum working code.
-- This ladder runs after understanding the problem, NOT instead of reading the task.
-- MUST NOT add a new library if steps 1-6 already solve it. Every new library MUST include an explicit reason and user confirmation before installation.
-- Evaluate new libraries: active maintenance, good security record, not over-engineered for the problem size
-- Use modern, proven patterns for correctness, not trends
-- **Bug fixes = root cause, not symptoms:** grep all callers of touched functions, then fix at the source
-- Deletion > addition. Boring > clever. Fewest files. Shortest working diff wins.
+Before implementation, read and follow `../_shared/references/implementation-principles.md`.
+
+Developer-specific additions:
+- Use modern, proven patterns for correctness, not trends.
 - Never simplify trust-boundary validation, data-loss prevention, accessibility basics, or explicitly requested behavior.
-- Mark intentional simplifications with a `tradeoff:` comment - note the ceiling and the upgrade trigger.
-- Technical decisions (library choice, code patterns, local structure): decide them yourself by best practice.
-- Business logic or scope changes: ask the user first.
+- Mark intentional simplifications with a `tradeoff:` comment that states the ceiling and upgrade trigger.
+- Architecture-level library/vendor changes require an approved ADR; bounded local package choices follow `rules.md` and require permission before installation.
 
 **Communication:**
 - Use analogies when helpful
@@ -104,14 +94,12 @@ After the user answers, **create or update `.agents/developer-config.json`** wit
 
 ---
 
-## Execution Workflow Reference
+## Conditional Workflow References
+
+Load only the current state:
 
-Read `references/execution-workflow.md` and follow it for:
+- Missing config, scope, work mode, or starting plan-first: read `references/onboarding.md`. If adding skill paths, also read `../_shared/references/additional-skills.md`.
+- Executing a task: read `references/execute-task.md`.
+- Closing a completed phase/project: read `references/close-phase.md`.
 
-- Step 0b - Check Additional Skills
-- Step 1 - Read `Task.md` and present the phase summary
-- Step 1b - Choose Work Mode
-- Step 2 - Choose Relevant Specs
-- Step 3 - Execute Tasks One by One
-- Step 4 - After All Phase Tasks Are Complete
-- Step 5 - Project Complete
+Do not load all three by default.

package/.agents/skills/developer/references/close-phase.md

@@ -0,0 +1,25 @@
+# Developer Phase Close
+
+Read this file only after every task in the active phase is complete.
+
+## Close the Phase
+
+1. Show the phase summary.
+2. Read the phase Definition of Done. Complete every applicable implementation-side item; mark inapplicable items `N/A` with a reason.
+3. If a phase plan exists, set `status: code-review`.
+4. Run `spec-compliance` using configured fix mode.
+5. Only after compliance passes, run `code-review` using configured fix mode.
+6. Mark quality-gate Definition of Done items complete only after both pass.
+7. Offer the next phase and wait according to Task.md execution rules.
+
+In report-first mode, stop at the active gate. Do not invoke the next gate in the same response.
+
+## Project Complete
+
+When all phases are complete:
+
+1. Show the project summary.
+2. Recommend final project-mode `spec-audit`.
+3. Before a production release, recommend `release-readiness`.
+4. For later small technical maintenance, create a traceable delta task/phase and remain in developer.
+5. Route significant business scope expansion to `add-feature`.

package/.agents/skills/developer/references/execute-task.md

@@ -0,0 +1,69 @@
+# Developer Task Execution
+
+Read this file only when executing the current task.
+
+## Select Relevant Specs
+
+`architecture.md` is required. Read `rules.md` and architecture for every task, then conditionally:
+
+| Condition | Additional source |
+|---|---|
+| Database/data | `schema.md` |
+| API/integration | `api.md` |
+| UI | `StyleGuide.md` |
+| Product behavior unclear | `PRD.md` |
+
+Scan `[FORBIDDEN]` in rules before coding. Enforce `developerPreferences.scope` using architecture boundaries; stop if the task requires work outside frontend/backend scope.
+
+## Understand and Protect Scope
+
+Read the task, acceptance criteria, traceability, and Definition of Done. Follow the shared implementation principles loaded by the parent skill.
+
+If requested behavior is not recorded in `project-context/`, obtain one approval and record an `## Approved Scope Delta` in the active phase plan before coding:
+
+```markdown
+## Approved Scope Delta
+
+**Approved:** [YYYY-MM-DD]
+**Source:** User request
+**Affected files/docs:** [paths]
+**Traceability:** DELTA-[N]
+**Acceptance Criteria:**
+- [ ] [testable condition]
+**Sync requirement:** Update the formal owning spec before phase close or when requested.
+```
+
+Do not code an unapproved delta.
+
+## Clarify and Define Behavior
+
+Ask one focused question only for unresolved material ambiguity. For non-trivial business logic, transformation, calculation, or validation, define representative input/output and one edge case before implementation.
+
+## Implement
+
+Before coding:
+
+1. Read relevant registered additional skills.
+2. Use relevant registered MCPs; use current documentation for external APIs.
+3. Apply the shared implementation-principles ladder.
+4. Follow the testing workflow selected in `rules.md`.
+
+After coding, self-review:
+
+```text
+[SELF-REVIEW] Task: [name]
+1. Security risk: [risk or none identified]
+2. Performance bottleneck: [risk or none identified]
+3. Spec assumption: [assumption or none]
+```
+
+## Validate and Record
+
+Run the narrowest relevant test/build/type/lint/manual check. Repair local defects and rerun before continuing.
+
+After validation:
+
+1. Mark the task and satisfied acceptance criteria complete.
+2. Add a short implementation note only when useful.
+3. Do not mark phase Definition of Done items complete until evidence exists.
+4. Report files and validation evidence, then follow Task.md execution cadence.

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

@@ -0,0 +1,47 @@
+# Developer Onboarding and Planning
+
+Read this file only when identity/config/work mode is incomplete or plan-first must start.
+
+## Additional Skills and MCPs
+
+If `additionalSkills` is missing:
+
+1. Ask once whether the project uses framework/domain skills.
+2. For each named skill, search every MACCA tool destination: `.agents/skills/` (codex/kimi), `.github/skills/` (copilot), `.opencode/skills/`, `.claude/skills/`, `.cursor/skills/`, `.windsurf/skills/`, `.gemini/skills/`, `.kilo/skills/`. If none match, also check the global equivalents `~/.config/opencode/skills/`, `~/.claude/skills/`, and `~/.agents/skills/`. Only then fall back to matching workspace folders.
+3. If found, record its path. If absent, ask for the path or allow `skip`.
+4. Before saving, load `../../_shared/references/additional-skills.md` and use its canonical `paths` shape.
+
+When an additional skill is relevant to a task, read it before coding.
+
+If `availableMCPs` is missing, ask once which MCPs are available or `none`. Save while preserving unrelated config. Use only registered MCPs that help the current task.
+
+## Developer Scope
+
+If `developerPreferences.scope` exists, use it. Otherwise ask once:
+
+```text
+A) Frontend only
+B) Backend only
+C) Fullstack
+```
+
+Save `frontend`, `backend`, or `fullstack` through the shared config-mutation contract.
+
+## Work Mode
+
+If `developerPreferences.workMode` exists, use it. Otherwise ask once:
+
+```text
+A) Code now — direct
+B) Plan first — review a phase plan before coding
+```
+
+Save `direct` or `plan-first`.
+
+For `plan-first`:
+
+1. Read the relevant phase, architecture, PRD, and rules.
+2. Create `project-context/plans/phase-[N]-[slug].md` with `status: review`.
+3. Include Goal, Scope, Files, Risks, and Validation.
+4. Review it against Task.md and specs.
+5. Wait for `start`; then set `status: in-progress`.