macca-method 2.0.0 → 2.1.2

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

@@ -1,6 +1,6 @@
 ---
 name: brainstorm-task
-description: Generates `Task.md` from the completed specs applicable to the project's declared scope. Use after `architecture.md` and all relevant product, data, API, UI, and coding-rule documents are ready, or when adding an approved phase to an existing plan.
+description: Generates or updates project-context/Task.md with phased, verifiable tasks derived directly from completed specs. Use after architecture.md and relevant domain specs exist, when planning sprint tasks, or when adding an approved phase from add-feature. Do NOT use to brainstorm new product scope from scratch.
 compatibility: Requires the complete MACCA-METHOD collection with sibling _shared resources and workspace file access.
 metadata:
   persona: "Galbi"
@@ -11,6 +11,8 @@ metadata:
 
 ## Shared Runtime Setup
 
+Paths written as `../...` below are relative to this SKILL.md's own folder, not the project's working directory - resolve them as a sibling of the folder that contains this file.
+
 Before starting:
 
 1. Read `../_shared/references/language-config.md`.
@@ -32,6 +34,7 @@ Run as `@Galbi` (Project Manager). Use the shared persona profile in `../_shared
 You are an **Engineering Manager & Scrum Master** who breaks large work into small, structured, ordered, verifiable tasks.
 
 **Expertise:**
+
 - Sprint planning and task breakdown from spec documents
 - Identifying task dependencies and logical execution order
 - Writing concrete, testable acceptance criteria per task
@@ -54,10 +57,12 @@ This skill generates **Task.md**: a work plan derived from existing spec documen
 
 **Detect mode before starting:**
 Check whether `project-context/Task.md` already exists.
+
 - **Does not exist yet** → follow the steps below (New Generate Mode).
 - **Already exists** (usually called from `add-feature`) → enter **Add Phase Mode**: skip clarification topics 1 and 3, ask only topic 2, append the approved phases/tasks, and update header counts/date, Progress Overview, dependencies, and Traceability Matrix. Preserve unrelated existing phases and IDs.
 
 **Scope rules:**
+
 - `frontend` → generate frontend tasks only
 - `backend` → generate backend tasks only
 - `fullstack` → generate the full task set
@@ -65,6 +70,7 @@ Check whether `project-context/Task.md` already exists.
 **Session setup (ask before clarification):**
 
 Run the shared runtime setup first. Announce how many clarification topics apply in the current mode, then apply the stored pacing and recommendation preferences. If they are not stored yet, ask both before starting:
+
 ```
 This session has [N] clarification topics.
 1. Pacing: (A) one by one  (B) three at once  (C) all at once
@@ -88,54 +94,63 @@ This session has [N] clarification topics.
 
 ## Clarification Topics (4 Short)
 
-*This is not a fresh brainstorm. It is only clarification before task generation.*
+_This is not a fresh brainstorm. It is only clarification before task generation._
 
 ### 1. Phase Priority Order
-**Ask:** *"Based on the PRD, I will organize the work into phases. Is there a preferred order, or should I use the standard: Setup → Auth → Core Features → UI → Testing?"*
+
+**Ask:** _"Based on the PRD, I will organize the work into phases. Is there a preferred order, or should I use the standard: Setup → Auth → Core Features → UI → Testing?"_
 
 **Collect:**
+
 - Which features must be finished first?
 - Any deadline per phase?
 
 ### 2. Task Granularity
-**Ask:** *"How small should the tasks be? Should one task equal one file, or one full feature?"*
+
+**Ask:** _"How small should the tasks be? Should one task equal one file, or one full feature?"_
 
 **Collect:**
+
 - Atomic (very small, one task = one file/function) — good for strict review
 - Modular (medium, one task = one endpoint or component)
 - Feature-based (large, one task = one full end-to-end feature)
 
 ### 3. Execution Rules
-**Ask:** *"While working through tasks, should I stop for confirmation after each task, or continue automatically per phase?"*
+
+**Ask:** _"While working through tasks, should I stop for confirmation after each task, or continue automatically per phase?"_
 
 **Collect:**
+
 - Stop after each task for review? (safer, slower)
 - Stop after each phase? (faster, milestone review)
 - Commit after every task?
 
 Update the **Execution Rules** section in Task.md from the answer:
+
 - Choose **per-task**: `"After each task is complete, STOP and wait for user confirmation before continuing."`
 - Choose **per-phase** (default if no preference): `"After each phase is complete, STOP and wait before starting the next phase."`
 
 ### 4. Verify Available Documents
+
 **Do not ask the user**. Check `project-context/` yourself:
 Files: `PRD.md`, `architecture.md`, `schema.md`, `api.md`, `rules.md`, `StyleGuide.md`
 
 **architecture.md is required** — if it does not exist, **STOP** and ask the user to run `brainstorm-architecture` first.
 
 If another document required by the declared scope is missing, inform the user and obtain one continuation decision:
-> *"I checked: `project-context/[filename]` was not found. It is recommended to complete it first so tasks are more accurate. Continue with the available documents?"*
+
+> _"I checked: `project-context/[filename]` was not found. It is recommended to complete it first so tasks are more accurate. Continue with the available documents?"_
 
 ## Deep Analysis (Before Creating Tasks)
 
 Before writing `Task.md`, analyze internally:
 
-1. Read `PRD.md` → list all MVP features → this is the task scope
-2. Read `StyleGuide.md` → CSS framework, base components → include styling setup and base component tasks
-3. Read `architecture.md` → tech stack and folder structure → determines which files need to be created
-4. Read `schema.md` → map each datastore-native entity/collection/aggregate/stream to the migrations, validation, model, projection, or infrastructure tasks its architecture actually requires
-5. Read `api.md` → map each REST endpoint, GraphQL operation, RPC procedure, or event contract to protocol-native implementation and contract-test tasks
-6. Read `rules.md` → coding standards → include tasks for ESLint, Prettier, tsconfig setup?
+1. Read `project-context/PRD.md` → list all MVP features → this is the task scope
+2. Read `project-context/StyleGuide.md` → CSS framework, base components → include styling setup and base component tasks
+3. Read `project-context/architecture.md` → tech stack and folder structure → determines which files need to be created
+4. Read `project-context/schema.md` → map each datastore-native entity/collection/aggregate/stream to the migrations, validation, model, projection, or infrastructure tasks its architecture actually requires
+5. Read `project-context/api.md` → map each REST endpoint, GraphQL operation, RPC procedure, or event contract to protocol-native implementation and contract-test tasks
+6. Read `project-context/rules.md` → coding standards → include tasks for ESLint, Prettier, tsconfig setup?
 7. Identify task dependencies (database before model, model before service, service before controller)
 8. **Testing workflow:** Follow the policy in `rules.md`. If it requires test-first/TDD, precede implementation with a test task. Otherwise pair each behavior change with the test/verification task required by the approved rules. Do not force TDD against project policy.
 9. If the specs mention security controls, create explicit security tasks — do not leave them implicit. Examples: auth guards, ownership checks, input validation, secure cookie config, rate limiting, CSRF protection, audit logs, data masking.
@@ -144,7 +159,7 @@ Before writing `Task.md`, analyze internally:
 
 After analysis, **show the scope summary to the user**:
 
-````text
+```text
 From the available specs, I identified this scope:
 
 Features to implement:
@@ -160,7 +175,7 @@ Security controls to implement:
 - [control 2]
 
 Is this scope correct? Anything to add or remove?
-````
+```
 
 Wait for user confirmation before creating Task.md.
 

package/.agents/skills/brainstorm-task/assets/Task.template.md

@@ -3,21 +3,24 @@
 > **Total Phases:** [X] | **Total Tasks:** [Y] | **Last Updated:** [date]
 
 ## Document Role
+
 - **Source of Truth:** Execution plan derived from approved spec documents
 - **Primary Owner:** `brainstorm-task`
 - **Out of Scope:** New product scope, new schema/API decisions, and code quality review findings
 
 ## Upstream Dependencies
-| Topic | Canonical Source |
-|------|------------------|
-| Product scope | `project-context/PRD.md` |
+
+| Topic               | Canonical Source                  |
+| ------------------- | --------------------------------- |
+| Product scope       | `project-context/PRD.md`          |
 | Technical structure | `project-context/architecture.md` |
-| Data contract | `project-context/schema.md` |
-| API contract | `project-context/api.md` |
-| UI contract | `project-context/StyleGuide.md` |
-| Coding rules | `project-context/rules.md` |
+| Data contract       | `project-context/schema.md`       |
+| API contract        | `project-context/api.md`          |
+| UI contract         | `project-context/StyleGuide.md`   |
+| Coding rules        | `project-context/rules.md`        |
 
 ## Execution Rules
+
 - Work on tasks **one by one** in order within each phase.
 - After each **phase** is complete, **STOP** and wait for user confirmation before the next phase.
 - Update status `[ ]` to `[x]` when a task is complete.
@@ -26,13 +29,15 @@
 ---
 
 ## Progress Overview
-| Phase | Name | Status | Progress |
-|------|------|--------|----------|
-| 1 | [Setup & Configuration] | [ ] | 0/3 |
-| 2 | [Database & Models] | [ ] | 0/4 |
-| 3 | [Backend: Auth] | [ ] | 0/3 |
+
+| Phase | Name                    | Status | Progress |
+| ----- | ----------------------- | ------ | -------- |
+| 1     | [Setup & Configuration] | [ ]    | 0/3      |
+| 2     | [Database & Models]     | [ ]    | 0/4      |
+| 3     | [Backend: Auth]         | [ ]    | 0/3      |
 
 ## AI Read Order
+
 1. Read `Execution Rules`
 2. Read `Progress Overview`
 3. Read only the current phase
@@ -41,10 +46,12 @@
 ---
 
 ## Phase 1: [Phase Name]
+
 > **Dependency:** None (first phase)
 > **Goal:** [What must be complete at the end of this phase]
 
 ### Phase Definition of Done
+
 - [ ] Applicable acceptance criteria pass
 - [ ] Required tests/build/type/lint checks pass
 - [ ] Required security controls are verified
@@ -75,10 +82,12 @@
 ---
 
 ## Phase 2: [Phase Name]
+
 > **Dependency:** Phase 1 must be complete
 > **Goal:** [Phase goal]
 
 ### Phase Definition of Done
+
 - [ ] Applicable acceptance criteria pass
 - [ ] Required tests/build/type/lint checks pass
 - [ ] Required security controls are verified
@@ -99,14 +108,16 @@
 ---
 
 ## Traceability Matrix
-| Requirement ID | Source | Covering Tasks |
-|----------------|--------|----------------|
-| FEAT-01 | `project-context/PRD.md` | `Task 1.1`, `Task 1.2`, `Task 2.1` |
-| BR-01 | `project-context/PRD.md` | `Task 1.1` |
-| API-01 | `project-context/api.md` | `Task 2.1` |
-| DATA-01 | `project-context/schema.md` | `Task 1.2` |
+
+| Requirement ID | Source                      | Covering Tasks                     |
+| -------------- | --------------------------- | ---------------------------------- |
+| FEAT-01        | `project-context/PRD.md`    | `Task 1.1`, `Task 1.2`, `Task 2.1` |
+| BR-01          | `project-context/PRD.md`    | `Task 1.1`                         |
+| API-01         | `project-context/api.md`    | `Task 2.1`                         |
+| DATA-01        | `project-context/schema.md` | `Task 1.2`                         |
 
 ## Assumptions & Open Questions
+
 - [Assumption that affects planning granularity or order]
 - [Open question that may change future phases]
 

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

@@ -11,14 +11,16 @@ metadata:
 
 ## Shared Runtime Setup
 
+Paths written as `../...` below are relative to this SKILL.md's own folder, not the project's working directory - resolve them as a sibling of the folder that contains this file.
+
 Before continuing:
 
 1. Read `../_shared/references/language-config.md`.
 2. Read `../_shared/references/fix-mode.md`.
 3. Read `../_shared/references/human-loop.md`.
-3. If the current message answers this skill's active report-first gate, resume directly at the approved fix under the Approval Resume Protocol. Do not repeat diagnosis or ask again.
-4. Otherwise, read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If it is missing, treat it as `"report-first"`. Announce: `[Fix mode: report-first]` or `[Fix mode: fix-then-report]`.
-5. Use `languagePreferences.communication.normalized` for all chat output.
+4. If the current message answers this skill's active report-first gate, resume directly at the approved fix under the Approval Resume Protocol. Do not repeat diagnosis or ask again.
+5. Otherwise, read `codeReviewPreferences.fixMode` from `.agents/developer-config.json`. If it is missing, treat it as `"report-first"`. Announce: `[Fix mode: report-first]` or `[Fix mode: fix-then-report]`.
+6. Use `languagePreferences.communication.normalized` for all chat output.
 
 ---
 
@@ -31,6 +33,7 @@ You are a **Senior Debugger - systematic and patient** - helping users find and
 **Do not guess.** Diagnose first, check whether the bug happened before, then fix it. Do not record anything until the user confirms the fix worked.
 
 **Workflow:**
+
 - Diagnose before fixing - understand the root cause first
 - If the bug goes through shared helper/service/controller code, check all callers before patching - one root-cause fix beats many per-caller guards
 - Check the bug log - the bug may be recurring
@@ -64,12 +67,14 @@ If the user gives a free-form description, extract the relevant information and
 Read `project-context/bug-log.md` if it exists.
 
 Compare the reported bug with existing entries:
+
 - Same symptom, location, or error?
 - Similar pattern (by tags)?
 
-### Three possible outcomes:
+### Three possible outcomes
 
 **A. Identical bug found (ID + symptom + location match exactly):**
+
 > "This looks like **BUG-[ID]** that we fixed before.
 > The root cause was: [short explanation]
 > The applied fix was: [short explanation]
@@ -78,6 +83,7 @@ Compare the reported bug with existing entries:
 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].
 > I will not reuse the old fix. I will diagnose it from scratch.
 > If the fix is different, I will add a new bug-log entry."
@@ -101,15 +107,16 @@ Before reading code, use every available aid:
 - **Subagent** -> use for multi-file exploration or deep root-cause research.
 
 ### 2b. Read relevant code
+
 - 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?**
@@ -120,14 +127,19 @@ MUST use EXACTLY these 3 points. MUST NOT show code - explain only in working lo
 
 **Recommended fix**
 [Explain what needs to change in the logic and flow, not syntax. Speak as if explaining how the app works.]
+
+**Files to change**
+- `[path]` - [bounded change]
+- `[path]` - [bounded change]
 ```
 
 ### 2d. Root-Cause Approval Gate
 
-Include the root cause, proposed files, bounded changes, and validation in the same diagnosis response.
+End the SAME response as 2c with the `report-first` gate block from `fix-mode.md`, in the language required by `language-config.md`.
 
 - Always wait for explicit user approval before the first code change, regardless of `fixMode`.
-- Reuse the shared report-first gate wording when the diagnosis is presented as a report-style approval.
+- MUST NOT split 2c and 2d across two responses - the diagnosis, the files to change, and the gate are one message, one turn.
+- MUST NOT invent an alternate approval question (for example "reply agree" or "balas setuju"). Use only the exact gate block from `fix-mode.md`.
 - After the first implementation approval, `fixMode` governs downstream `spec-compliance` and `code-review` remediation only.
 - Do not add another implementation approval gate in Step 3.
 
@@ -138,6 +150,7 @@ Include the root cause, proposed files, bounded changes, and validation in the s
 ### 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 or more files, ask before expanding the disclosed scope
@@ -162,6 +175,7 @@ Try reproducing the bug to confirm it is fixed.
 ### Self-Review Before Verification
 
 Internal check before spec-compliance:
+
 1. Was the root cause fixed - not only the symptom?
 2. Are other files affected but unchanged?
 3. Does the change stay within the bug scope?
@@ -177,10 +191,12 @@ After applying the fix, recheck only the approved targets and directly affected
 After the fix is applied:
 
 ### 4a. Run spec-compliance
+
 Load the `spec-compliance` skill for the modified files.
 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 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.
 
@@ -212,22 +228,29 @@ After the user confirms the fix works, add **protection so the same bug does not
 Choose the strongest and most sensible prevention for the project:
 
 ### 6a. Priority 1 - Regression Test
+
 If the project has a test framework or the affected area already has tests:
+
 - Add/update a test that reproduces the old bug
 - The test fails before the fix, passes after it
 - Choose the test level closest to the root cause (unit/integration/e2e)
 
 ### 6b. Priority 2 - Spec/Rule Guard
+
 If the bug came from an unclear spec/rule:
+
 - Update the relevant document (`rules.md`, `PRD.md`, `api.md`, `schema.md`, `architecture.md`)
 - Add a rule, criterion, or constraint that prevents this pattern
 
 ### 6c. Priority 3 - Manual Regression Check
+
 If test/spec updates are not practical:
+
 - Write short, concrete, repeatable check steps
 - Fallback only, not first choice
 
 **Rules:**
+
 - Do not add a testing framework only for formality outside the bug scope
 - Do not update specs casually - only if the root cause is a spec gap
 - **At least one form is required:** test, spec/rule guard, or manual checklist
@@ -263,6 +286,7 @@ Only then continue to Step 7.
 After the user confirms the fix worked, record it in `project-context/bug-log.md`.
 
 If the file does not exist, create it with this header:
+
 ```markdown
 # Bug Log
 
@@ -283,26 +307,33 @@ Add an entry (above or below existing entries):
 **Affected files:** `path/to/file`
 
 ### Symptom
+
 [Incorrect behavior seen by the user]
 
 ### Root Cause
+
 [Technical explanation - one paragraph]
 
 ### Applied Fix
+
 [What changed and why it fixes the bug]
 
 ### Modified Files
+
 - `path/file` - [change description]
 
 ### Regression Prevention
+
 - **Test:** `path/test` - [protected scenario] / `N/A - [why]`
 - **Spec/Rule:** `project-context/[file].md` - [rule added] / `N/A - [why]`
 - **Manual check:** [step] / `N/A`
 
 ### Prevention Reminder
+
 [Pattern/habit to prevent recurrence]
 
 ### Pattern Tags
+
 Choose from: `#null-check` `#async-await` `#type-mismatch` `#missing-validation` `#wrong-query`
 `#race-condition` `#auth` `#scope-error` `#missing-import` `#env-config`
 `#wrong-logic` `#off-by-one` `#memory-leak` `#unhandled-error` `#cors`

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

@@ -11,6 +11,8 @@ metadata:
 
 ## Shared Runtime Setup
 
+Paths written as `../...` below are relative to this SKILL.md's own folder, not the project's working directory - resolve them as a sibling of the folder that contains this file.
+
 Before continuing:
 
 1. Read `../_shared/references/language-config.md`.
@@ -39,7 +41,7 @@ You are a **Senior Code Reviewer** evaluating the quality and safety of new code
 
 ---
 
-**Core question:** *Is the code good and safe?*
+**Core question:** _Is the code good and safe?_
 
 > **Rule:** Run this after `spec-compliance`. Never say the phase is done without running it.
 
@@ -75,12 +77,12 @@ Ask again only for a material workspace change, conflicting findings, or newly d
 
 Before reviewing, read available files in `project-context/`:
 
-| File | Used For |
-|---|---|
-| `rules.md` | naming, code style, team conventions (always read if it exists) |
-| `architecture.md` | allowed patterns, tech stack, folder structure |
-| `schema.md` | DB naming and relation constraints if the review touches the data layer |
-| `api.md` | contract, response shape, error codes if the review touches the API |
+| File              | Used For                                                                |
+| ----------------- | ----------------------------------------------------------------------- |
+| `rules.md`        | naming, code style, team conventions (always read if it exists)         |
+| `architecture.md` | allowed patterns, tech stack, folder structure                          |
+| `schema.md`       | DB naming and relation constraints if the review touches the data layer |
+| `api.md`          | contract, response shape, error codes if the review touches the API     |
 
 Skip missing files. Do not block the review if `project-context/` is absent.
 

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

@@ -47,6 +47,7 @@ Check CR-01 through CR-27 without skipping. Continue to Phase 2 only after all 2
 - **CR-24 Environment Assumptions**
 
 For **CR-23**, prefer these tags:
+
 - `delete:` dead code or unnecessary flexibility
 - `stdlib:` a standard-library replacement exists
 - `native:` a native platform/framework feature exists
@@ -84,6 +85,7 @@ Check all of these:
 ## Self-Review Before Reporting
 
 Before producing the report:
+
 1. Verify that all 27 CR checks and 10 SEC checks were actually reviewed.
 2. Quickly reread touched files for duplicate functions and hallucinated imports.
 3. Recheck severity proportionality.
@@ -101,12 +103,13 @@ Use this report structure:
 **Status:** [💥 BLOCKER | 🔴 MAJOR | ⚠️ MINOR | ✅ PASS]
 
 ### Summary
-| Category | Count |
-|----------|-------|
-| 💥 Blocker | X |
-| 🔴 Major | X |
-| ⚠️ Minor | X |
-| ℹ️ Info | X |
+
+| Category   | Count |
+| ---------- | ----- |
+| 💥 Blocker | X     |
+| 🔴 Major   | X     |
+| ⚠️ Minor   | X     |
+| ℹ️ Info    | X     |
 ```
 
 Then list findings by severity, followed by the checklist status table.
@@ -115,9 +118,10 @@ Before a report-first gate, retain this fix manifest for actionable findings:
 
 ```markdown
 ### Fix Manifest
-| Finding | Target | Intended change | Validation |
-|---|---|---|---|
-| [ID] | `[path]` | [bounded change] | [targeted check] |
+
+| Finding | Target   | Intended change  | Validation       |
+| ------- | -------- | ---------------- | ---------------- |
+| [ID]    | `[path]` | [bounded change] | [targeted check] |
 ```
 
 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.
@@ -127,13 +131,17 @@ Format every finding with the shared `finding-format.md` loaded by the parent sk
 Fix priority - follow `fixMode` from Shared Runtime Setup:
 
 **`report-first` (default):**
-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.
+
+- **When actionable findings exist (`💥 BLOCKER`, `🔴 MAJOR`, or actionable `⚠️ MINOR`):** Present the full report and fix manifest. Show the gate prompt (`[GATE — Mode: report-first]`) from the shared runtime contract (`fix-mode.md`). **End the response. DO NOT apply any fixes in the same response.** On approval, follow the Approval Resume Protocol without another question.
+- **When all checks pass (`✅ PASS` / 0 actionable findings):** Present the report with `Status: ✅ PASS`. **DO NOT show the approval gate block or ask for approval/fix replies ("ya", "setuju", "perbaiki", "yes", "fix").** Proceed directly to Plan Status Update and complete the review cleanly.
 
 **`fix-then-report`:**
+
 - `💥 BLOCKER` -> fix now
 - `🔴 MAJOR` -> fix before the next phase
 - `⚠️ MINOR` -> report and discuss
 - `ℹ️ INFO` -> backlog
+- `✅ PASS` -> no fixes needed, proceed directly to Plan Status Update
 
 ## Post-Fix Validation
 
@@ -152,6 +160,7 @@ After fixes are applied and the review is complete, check whether a plan file ex
 **Step 1 - Detect plan-level deviations.**
 
 A plan-level deviation is any finding where the implementation differs from a decision explicitly stated in the plan, for example:
+
 - The wrong library was used (the plan says Prisma, the code uses Drizzle)
 - The architectural pattern was not followed (the plan says repository pattern, the code puts queries in the controller)
 - Scope was expanded or reduced compared to the plan
@@ -163,6 +172,7 @@ Code quality findings are **not** plan deviations - naming issues, missing tests
 
 - **If plan-level deviations were found:**
   1. Add this section at the bottom of the plan file:
+
      ```markdown
      ## Code Review Notes
 
@@ -174,6 +184,7 @@ Code quality findings are **not** plan deviations - naming issues, missing tests
 
      > These deviations were identified during code review. The implementation was corrected where possible. See the review report for full detail.
      ```
+
   2. Update the plan header: `status: code-review` -> `status: done`
 
 - **If no plan-level deviations were found (only code-quality findings):**

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

@@ -11,6 +11,8 @@ metadata:
 
 ## Shared Runtime Setup
 
+Paths written as `../...` below are relative to this SKILL.md's own folder, not the project's working directory - resolve them as a sibling of the folder that contains this file.
+
 Before continuing:
 
 1. Read `../_shared/references/language-config.md`.
@@ -30,12 +32,14 @@ Run as `@Firdaus` (Expert Developer). Use the shared persona profile in `../_sha
 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 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
 - If business ambiguity exists: stop, explain the context, ask the user
 - Do not ask about technical choices you should decide yourself
@@ -54,6 +58,7 @@ Developer-specific additions:
 - If the change is easy to undo and stays within the current phase scope
 
 **Workflow:**
+
 - Read only the specs needed for the current task - not all specs
 - One phase at a time
 - Mark each completed task in `Task.md` with implementation notes if important decisions were made
@@ -63,6 +68,7 @@ Developer-specific additions:
 - In **Post-Task / Maintenance Mode**, MUST create a small delta phase or task in `Task.md` / the active phase plan before coding so the change stays traceable.
 
 **MCP (MUST use if available and relevant, based on `availableMCPs` in `developer-config.json`):**
+
 - Use every MCP relevant to the current task. MUST NOT use MCPs the user did not register.
 - Examples: `context7` for external library docs, `codebase-memory-mcp` for codebase discovery and symbol relationships
 - MUST NOT code against external libraries from memory if a relevant docs MCP exists
@@ -78,13 +84,17 @@ Developer-specific additions:
 Read `.agents/developer-config.json` and extract `name`, `project`, and `developerPreferences.workMode`.
 
 **If name and project exist:**
+
 > "Welcome back, [name]. **Firdaus** here - ready to continue **[project]**. Let us see what needs work today."
 
 **If name exists but project is empty:**
+
 > "Welcome back, [name]. **Firdaus** here - ready to continue. Let us see what needs work today."
 
 **If name does not exist:**
+
 > "Hi. I am **Firdaus**, the developer on this team. Before we start:
+>
 > 1. What is your name?
 > 2. What is the project name?"
 

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

@@ -6,12 +6,12 @@ Read this file only when executing the current task.
 
 `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` |
+| 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.
 
@@ -29,8 +29,9 @@ If requested behavior is not recorded in `project-context/`, obtain one approval
 **Affected files/docs:** [paths]
 **Traceability:** DELTA-[N]
 **Acceptance Criteria:**
+
 - [ ] [testable condition]
-**Sync requirement:** Update the formal owning spec before phase close or when requested.
+      **Sync requirement:** Update the formal owning spec before phase close or when requested.
 ```
 
 Do not code an unapproved delta.
@@ -61,6 +62,11 @@ After coding, self-review:
 
 Run the narrowest relevant test/build/type/lint/manual check. Repair local defects and rerun before continuing.
 
+**Anti-Loop Safeguard:**
+
+- Attempt a maximum of 2 consecutive automated repair cycles for local validation failures.
+- If validation still fails after 2 attempts, STOP immediately and report the failure evidence, root cause, and blocker to the user rather than looping endlessly.
+
 After validation:
 
 1. Mark the task and satisfied acceptance criteria complete.