@massa-ai/claude-plugin 1.61.0 → 1.63.0

package/skills/massa-ai/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: massa-ai
-description: Default memory-backed workflow router for every coding, planning-before-coding, debugging, code review, refactoring, or implementation conversation. Always load it once per new coding session, select specialized workflows first, and use the general fallback otherwise. Handles massa-ai recall/search, durable memory, context compaction, handoff, audits, specs, ADR/RFC/TDD, and evidence gates. Do NOT use for generic non-coding chat or bulk-loading every workflow/reference.
+description: Default memory-backed workflow router for every coding, planning-before-coding, debugging, code review, refactoring, or implementation conversation. Always load it once per new coding session, select specialized workflows first, and work under the Core Contract without a workflow file otherwise. Handles massa-ai recall/search, durable memory, context compaction, handoff, audits, specs, ADR/RFC/TDD, and evidence gates. Do NOT use for generic non-coding chat or bulk-loading every workflow/reference.
 license: MIT
 metadata:
   author: Luiz Massa
@@ -20,106 +20,61 @@ section of `<host>/AGENTS.md`, for example `~/.claude/AGENTS.md`). Its single
 source is `skills/AGENTS.md` in the product repo; `scripts/install-skills.sh`
 copies that block out. Edit the policies there, never in a host copy.
 
-## Dedupe Guard
-
-Before reading any massa-ai file:
-
-- In a new coding conversation, load this router once before using dedupe.
-- After that initial load, reuse already-loaded `massa-ai`, workflow,
-  reference, or The Fool context.
-- Do not re-read a file only because another instruction names it.
-- Load only the missing minimum context needed to act.
-- Never load all workflows or references "just in case."
-
 ## Core Contract
 
 - Every coding/planning task uses one stable `projectId` and
   `workflowSessionId`.
-- Start with `recall` for relevant prior decisions/patterns.
-- Default startup/context recall is budgeted: use `limit <= 3`,
-  `minImportance >= 0.7`, and `types=["critical","decision","pattern"]`
-  unless the selected workflow explicitly needs a broader memory query.
-- Never use `recall` as an artifact loader. Exact project, handoff,
-  feature, and validation state must come from .specs/ files.
-- For multi-search tasks, use a separate ephemeral `synapseSessionId` according
-  to `references/synapse-policy.md`; pass it only to `search.sessionId`.
-  Never pass `workflowSessionId` in that field. Use `synapse_task_begin`/`synapse_task_end`
-  for task envelopes and `synapse_prefetch` to warm the buffer on file open.
-- Prefer the shared v2 retrieval order; fall back gracefully if the massa-ai
-  server or Synapse is unavailable. The full tool surface includes 59 tools
-  (see `references/mcp-tools.md`): indexing, search, symbol graph
-  (`trace_path`, `impact_analysis`, `get_architecture`), memory CRUD
-  (`remember`, `recall`, `memory_update`, `memory_delete`), checkpoints
-  (`create_checkpoint`/`list_checkpoints`/`restore_checkpoint`), handoffs
-  (`handoff_begin`/`accept`/`cancel`/`list_pending`), `bootstrap`,
-  `compact_snapshot`, code execution (`execute`/`execute_file`/`batch_execute`),
-  `fetch_and_index`, full Synapse lifecycle, `read_file`, `symbol_snippet`,
-  and `analytics`. Graph tools (`trace_path`, `impact_analysis`,
-  `get_architecture`) only count as evidence when the index is fresh for the
-  current repository path and commit/worktree state.
-- Persist only durable, useful knowledge. Do not fabricate memories to satisfy
-  process. Use `memory_update` to correct stale memories and `memory_delete`
-  to remove obsolete ones.
-- Expand every word abbreviation on first use in user-facing output — e.g.
-  "PR (Pull Request)", "AC (Acceptance Criteria)", "KMP (Kotlin Multiplatform)"
-  — including workflow-specific shorthands and finding-ID families.
-- Use one uniform vocabulary for separating batches of work in every workflow:
-  a **Task** is the atomic unit; a **Phase** is an ordered group of Tasks.
-  Report a phase's size as `1 Phase = X Tasks` and a plan's total as
-  `Y Phases = Z Tasks`. Do not substitute synonyms such as batch, wave, stage,
-  or chunk for these units in agent prose.
-- Emit concise user-facing status updates at meaningful workflow boundaries
-  when the Conversation Feedback Policy is active.
-- Verify, don't assume: every factual claim that drives a decision is
-  verified against current codebase/command evidence or confirmed with the
-  user. Documentation of any kind — README, docs/, inline comments, external
-  summaries, even `.specs/` prose — is a lead to verify against current
-  source, never a trustable source of truth by itself. Unverifiable claims
-  become explicit assumptions the user confirms or accepts.
-- Ask when in doubt: when genuine doubt remains after looking it up —
-  requirement meaning, scope boundaries, destructive/irreversible choices,
-  contradictory evidence — ask the user rather than choose silently. Facts
-  are looked up; decisions are asked.
-- Before writing or changing implementation code, load
-  `references/coding-guidelines.md` if not already loaded.
-- Complete Evidence Gate before claiming done.
+- Sub-agents are dispatched by bare charter name (`senior-engineer`,
+  `code-reviewer`, ...). On the Claude plugin route, dispatch the
+  plugin-namespaced `massa-ai:<name>` so a same-named agent cannot
+  intercept the dispatch.
+- Lazy charters (`designer`, `judge`, `test-engineer`) read
+  `references/agent-modes/<agent>/<mode>.md` before dispatch and inline it as
+  `mode_contract` (`judge` `plan-critique`: lite/full by `depth`); missing it
+  on a lazy mode returns `Blocked`.
+- Start with `recall` (prior decisions/patterns), budgeted: `limit <= 3`,
+  `minImportance >= 0.7`, `types=["critical","decision","pattern"]`, unless
+  the workflow needs a broader query. Never use it as an artifact loader --
+  exact project/handoff/feature/validation state comes from `.specs/` files.
+- Multi-search tasks use an ephemeral `synapseSessionId` per
+  `references/synapse-policy.md` (only `search.sessionId`, never
+  `workflowSessionId`) per `synapse_task_begin`/`synapse_task_end`.
+- The full 59-tool surface is contracted in `references/mcp-tools.md`. Graph tools (`trace_path`, `impact_analysis`, `get_architecture`) count as evidence only when fresh for the current repository path and commit/worktree state.
+- Persist only durable, useful knowledge; do not fabricate memories. Use
+  `memory_update`/`memory_delete` to correct/remove.
+- Expand abbreviations on first use; one vocabulary for batches: **Task**,
+  **Phase** (`1 Phase = X Tasks`, never batch/wave/stage/chunk). Emit concise
+  status updates at workflow boundaries when Conversation Feedback is active.
+- Verify, don't assume: claims driving a decision are verified against
+  current codebase/command evidence or the user; docs are leads, not truth.
+  Genuine doubt goes to the user, not a silent choice.
+- Before implementation edits, load `references/coding-guidelines.md` if
+  not already loaded. Complete Evidence Gate before claiming done.
 
 Use internal references only when needed:
 
 | Need | Reference |
 |---|---|
-| MCP/REST schemas, response modes, polling | `references/mcp-tools.md` |
-| Multi-search Synapse lifecycle and fallback | `references/synapse-policy.md` |
+| MCP/REST schemas, polling | `references/mcp-tools.md` |
+| Synapse lifecycle/fallback | `references/synapse-policy.md` |
 | Install/config/deployment | `references/installation.md` |
-| Importance scoring, tradeoffs, debugging | `references/decision-engine.md` |
-| Memory tiers/conflict handling | `references/memory-policy.md` |
-| Shared lesson loading/capture lifecycle | `references/lessons.md` |
-| Meaningful code and contract identifier names | `references/naming-standards.md` |
-| Chat-visible workflow status updates | `references/conversation-feedback.md` |
+| Importance scoring | `references/decision-engine.md` |
+| Memory tiers/conflicts | `references/memory-policy.md` |
+| Lesson loading/capture | `references/lessons.md` |
+| Naming standards | `references/naming-standards.md` |
+| Status updates | `references/conversation-feedback.md` |
 | Completion evidence | `references/evidence-gate.md` |
 
 ## Session And Project
 
-If no `workflowSessionId` is explicit:
-
-1. Classify the workflow.
-2. Infer the main entity.
-3. Generate a stable id: `<workflow>-<entity>`.
-4. Reuse it for the whole conversation.
-
-Examples:
-
-- `debug-login-crash`
-- `feature-user-onboarding`
-- `refactor-auth-module`
-- `spec-billing-workflow`
-- `adr-postgres-migration`
+If no `workflowSessionId` is explicit: classify the workflow, infer the main
+entity, generate a stable id `<workflow>-<entity>` (e.g.
+`debug-login-crash`), and reuse it for the whole conversation.
 
 Resolve `projectId`:
 
-1. Call `recall` with query `"projectId for this workspace"`,
-   `limit <= 3`, `minImportance >= 0.7`, and
-   `types=["critical","decision","pattern"]`.
+1. Call `recall` with query `"projectId for this workspace"` (default budget
+   above).
 2. If found, reuse exactly.
 3. If absent, derive from workspace root.
 4. If ambiguous, ask the user.
@@ -143,9 +98,6 @@ current context already contains it.
 | `security-fix` | fix security audit report findings | `workflows/security/security-fix.md` |
 | `requirements-audit` | requirements/spec/acceptance/scope alignment findings | `workflows/requirements/requirements-audit.md` |
 | `requirements-fix` | fix requirements audit report findings | `workflows/requirements/requirements-fix.md` |
-| `maestro` | implement new Maestro mobile E2E flows | `workflows/maestro/maestro.md` |
-| `maestro-audit` | run and audit existing Maestro mobile E2E flows | `workflows/maestro/maestro-audit.md` |
-| `maestro-fix` | child-only fix for saved Maestro audit findings | `workflows/maestro/maestro-fix.md` |
 | `tests-audit` | test coverage/regression/assertion/flakiness findings | `workflows/tests/tests-audit.md` |
 | `tests-fix` | fix tests audit report findings | `workflows/tests/tests-fix.md` |
 | `bugs-audit` | findings-only bug discovery | `workflows/bugs/bugs-audit.md` |
@@ -159,34 +111,33 @@ current context already contains it.
 | `mobile-figma-audit` | compare an Android, iOS, or KMP UI implementation with a Figma design | `workflows/mobile-figma/mobile-figma-audit.md` |
 | `mobile-figma-fix` | fix saved mobile Figma findings | `workflows/mobile-figma/mobile-figma-fix.md` |
 | `refactor` | behavior-preserving structural cleanup | `workflows/refactor.md` |
-| `adr` | record a finalized decision | `workflows/adr.md` |
-| `rfc` | propose a significant change | `workflows/rfc.md` |
-| `tdd` | technical design / implementation plan | `workflows/tdd.md` |
-| `ticket` | draft and create Jira Epics, issues, and sub-tasks through Atlassian MCP | `workflows/ticket.md` |
+| `create-adr` | record a finalized decision | `workflows/create-adr.md` |
+| `create-rfc` | propose a significant change | `workflows/create-rfc.md` |
+| `create-tdd` | technical design / implementation plan | `workflows/create-tdd.md` |
+| `create-ticket` | draft and create Jira Epics, issues, and sub-tasks through Atlassian MCP | `workflows/create-ticket.md` |
 | `commit` | draft or create safe Conventional Commits with Jira branch prefixes and audit report exclusions | `workflows/commit.md` |
 | `the-fool` | direct challenge, red-team, pre-mortem, evidence audit | `workflows/the-fool.md` |
 | `judge-with-debate` | standalone multi-judge debate evaluation of user-supplied artifacts | `workflows/judge-with-debate.md` |
 | `pr-review` | review a hosted GitHub PR / GitLab MR and post findings via `gh`/`glab` | `workflows/pr-review.md` |
-| `discovery` | product brainstorming / problem-space thinking partner | `workflows/discovery.md` |
-| `to-prd` | turn the current conversation into a PRD without a new interview | `workflows/to-prd.md` |
+| `product-discovery` | product brainstorming / problem-space thinking partner | `workflows/product-discovery.md` |
+| `create-prd` | turn the current conversation into a PRD without a new interview | `workflows/create-prd.md` |
 | `skill-architect` | design and build a new skill through structured conversation | `workflows/skill-architect.md` |
 | `furps-refinement` | FURPS+ refinement of a PRD and/or ADR before implementation, with The Fool pre-validation and DoR coverage | `workflows/refinement/furps-refinement.md` |
-| `general` | coding work with no more specific workflow | `workflows/general.md` |
 
 Explicitly requested workflows win. Otherwise choose the most specific matching
 workflow. Use `exploration` only for explicitly read-only understanding or flow
-mapping; route to `general` when no route's precedence key above matches. Ask
+mapping; when no route's precedence key above matches, load no workflow file. Ask
 the user only when two or more routes match the same precedence tier; a single
 match or no match is resolved deterministically without asking.
 
 Deterministic routing precedence, first match wins:
 
 1. **Explicit route:** user names a massa-ai workflow, report family, saved finding type, or asks for a direct challenge.
-2. **Requested artifact:** ADR, RFC, TDD, Jira ticket, commit, session guide, audit report, implementation audit report, mobile Figma report, FURPS refinement report, PRD synthesized from the current conversation -> `to-prd` (explicit request only; refining an existing PRD stays `furps-refinement`), or new SKILL.md / skill design -> `skill-architect`.
-3. **Target type:** broken behavior/error -> `debug`; hosted PR/MR reference (number or URL) to review with posted findings -> `pr-review` (local working diff stays with audit routes); saved audit finding -> matching `*-fix`; implementation scope review -> `implementation-audit`; Maestro E2E/device automation target -> `maestro`, `maestro-audit`, or child-only `maestro-fix` before generic tests workflows; security/privacy/auth finding -> security workflow; tests/flakes/coverage finding -> tests workflow; supplied Figma/screenshot mobile UI design -> `design`; mobile Figma compare/audit -> `mobile-figma-audit`; saved `MFM-*` findings -> `mobile-figma-fix`.
-4. **Primary verb:** create/add/implement -> `feature` unless the concrete target is new Maestro flow work, which routes to `maestro`; restructure without behavior change -> `refactor`; inspect/understand only -> `exploration`; brainstorm/explore a product problem, idea, or direction with no concrete code target -> `discovery`; record selected decision -> `adr`; compare open options -> `rfc`; design settled implementation -> `tdd`; refine/quality-check an existing PRD or ADR document (not implementation auditing) -> `furps-refinement`.
+2. **Requested artifact:** ADR, RFC, TDD, Jira ticket, commit, session guide, audit report, implementation audit report, mobile Figma report, FURPS refinement report, PRD synthesized from the current conversation -> `create-prd` (explicit request only; refining an existing PRD stays `furps-refinement`), or new SKILL.md / skill design -> `skill-architect`.
+3. **Target type:** broken behavior/error -> `debug`; hosted PR/MR reference (number or URL) to review with posted findings -> `pr-review` (local working diff stays with audit routes); saved audit finding -> matching `*-fix`; implementation scope review -> `implementation-audit`; security/privacy/auth finding -> security workflow; tests/flakes/coverage finding -> tests workflow; supplied Figma/screenshot mobile UI design -> `design`; mobile Figma compare/audit -> `mobile-figma-audit`; saved `MFM-*` findings -> `mobile-figma-fix`.
+4. **Primary verb:** create/add/implement -> `feature`; restructure without behavior change -> `refactor`; inspect/understand only -> `exploration`; brainstorm/explore a product problem, idea, or direction with no concrete code target -> `product-discovery`; record selected decision -> `create-adr`; compare open options -> `create-rfc`; design settled implementation -> `create-tdd`; refine/quality-check an existing PRD or ADR document (not implementation auditing) -> `furps-refinement`.
 5. **Risk domain escalation:** migrations, irreversible operations, auth/privacy, cross-service contracts, public compatibility, or work over 10 files routes to `spec-driven` unless the user explicitly requests a narrower workflow and accepts the containment.
-6. **General fallback:** use `general` only after a one-line General fallback preflight names the specialized workflow considered, rejected reason, and why fallback does not change verification or mutation behavior.
+6. **No match:** proceed without loading a workflow file. The main agent works under the Core Contract above (recall, verify, Evidence Gate) and states in one line which specialized workflow it considered and why none applies.
 
 Mobile is a context modifier, not a workflow. Route by primary intent first.
 Load `references/mobile-context.md` for non-debug mobile work, or
@@ -195,137 +146,40 @@ selected workflow asks for it.
 
 ## Plan Challenge Gate
 
-Read and apply the canonical Plan Challenge Policy from the installed
-`AGENTS.md` bootstrap block (single source: `skills/AGENTS.md`). Prompt-level
-user instructions override that policy for the current turn.
-
-For a low-risk plan that receives the lite gate, attempt a read-only
-`massa-ai-plan-critic` subagent with a bounded checklist packet instead of
-running the checklist in the main agent. The packet includes the proposed plan, scope,
-constraints, compact recalled facts/evidence, known risks, verification recipe,
-parent identifiers, and this output requirement:
-
-- What assumption would most likely make this fail?
-- What deterministic check would falsify success?
-- Does it touch a high-risk domain or more than 5 files/classes/modules?
-- `escalate_to_full: true|false` plus reason.
-
-Lite preserves progressive disclosure: do not load The Fool mode references
-unless the lite critique escalates to full.
+Apply the installed Plan Challenge Policy from `skills/AGENTS.md` (canonical
+source); prompt-level instructions override it for the current turn.
 
-Low-risk `feature` and `refactor` plans receive the lite gate first. Full The
-Fool stays for `spec-driven`, `design`, `adr`, `rfc`, `tdd`, explicit challenge
-requests, high-risk domains, or plans touching more than 5 files/classes/modules.
-When the policy selects the full gate, or lite escalates, load
-`workflows/the-fool.md`, select the mode in the main agent, load only the
-selected The Fool references, and attempt a read-only `massa-ai-plan-critic`
-subagent with selected mode context and a bounded critique packet. Subagents inherit
-`projectId`, parent `workflowSessionId`, workflow name, entity, and compact
-evidence; they do not receive full conversation context.
-
-If the policy file is unavailable, use the conservative fallback: run the full
-gate for high-risk domains, broad multi-module plans, explicit challenge
-requests, and planning workflows that commit to a feature, refactor, ADR, RFC,
-or TDD. If the `massa-ai-plan-critic` agent is unavailable for any reason —
-spawning forbidden, plugin not installed, unknown `subagent_type` — run a strict
-standalone fresh-eyes local critique against the same output contract and report
-the skipped delegation reason. Do not retry under a different agent name. Reuse
-The Fool context when it is already loaded.
+- **Lite** (default, low-risk `feature`/`refactor`): dispatch `judge` in `plan-critique` mode
+  (`references/agent-modes/judge/plan-critique-lite.md`) with a bounded checklist packet (failing
+  assumption, falsifying check, risk/size check, `escalate_to_full:
+  true|false` + reason); skip The Fool references unless it escalates.
+- **Full** (`spec-driven`, `design`, `create-adr`/`rfc`/`tdd`, explicit
+  challenge, high-risk domain, >5 files/modules, or lite escalation): load
+  `workflows/the-fool.md`, select the mode, dispatch `judge` in `plan-critique`
+  mode (`references/agent-modes/judge/plan-critique-full.md`) with `fool_mode` in the packet.
+- If `judge` is unavailable, run a local fresh-eyes critique and report the
+  skipped reason; never retry under a different agent name.
 
 ## Retrieval And Synapse
 
-Use this default retrieval sequence when it matches the task:
-
-1. `list_projects` or equivalent freshness evidence before relying on indexed project state.
-2. `project_map` for general architecture orientation (PageRank backbone, symbol counts) when the index is fresh for the current repository path and worktree state.
-3. `get_architecture` for architecture-specific deep maps (packages, routes, hotspots, communities, cycles) when the index is fresh.
-4. `search(responseMode="summary", maxResults=10)` for broad discovery.
-5. `search(responseMode="enriched", maxResults=3)` for targeted deep reads; use `maxResults=5` only when the user named 4-5 concrete files, symbols, or findings.
-6. Symbol navigation (`search_definitions`, `get_references`, `go_to_definition`) and `read_file` for exact definitions, usages, and line ranges.
-7. `symbol_snippet` for raw code snippets by file + line range.
-8. `trace_path` for typed-edge BFS call/data-flow path tracing (fresh index only).
-9. `impact_analysis` for git-diff centrality-ranked impact (fresh index only).
-10. `optimized_context` for compact synthesized context when available.
-11. Focused shell/file fallback when the massa-ai server is unavailable, stale, incomplete, or misses obvious local truth.
-
-`project_map`, `get_architecture`, `search`, and `optimized_context` are leads
-until their results are confirmed against current source files read in this session or returned with current freshness evidence. Current repository source
-and approved `.specs/` artifacts remain authoritative. Graph tools (`trace_path`,
-`impact_analysis`, `get_architecture`) only count as evidence when the index is
-fresh for the current repository path and commit/worktree state; fall back to
-`search`/`get_references` and record reduced retrieval confidence when stale.
-
-Load `references/synapse-policy.md` when the planned investigation includes
-two or more related `search` calls. MCP is primary; authenticated REST may
-fill missing or broken Synapse lifecycle operations once after a documented MCP
-schema or adapter failure. Keep REST-only fields out of MCP calls.
+Follow the shared order in `references/codebase-investigation.md` (schemas in
+`references/mcp-tools.md`). Index output is a lead until confirmed against
+current source; source and approved `.specs/` artifacts stay authoritative.
+Load `references/synapse-policy.md` before 2+ related `search` calls.
 
 ## Persistence
 
-Before writing memory, load `references/decision-engine.md` if scoring details
-are not already in context. Use supported massa-ai types only: `critical`,
-`conversation`, `code`, `decision`, `pattern`.
-
-Required memory tags:
-
-- `project:<projectId>`
-- `session:<workflowSessionId>`
-- `workflow:<type>`
-- `entity:<name>`
-- one of `memory:working`, `memory:episodic`, `memory:semantic`,
-  `memory:procedural`
-
-## Shared References
-
-Load only when a selected workflow asks for them:
-
-- `references/agent-orchestration.md`
-- `references/subagent-design.md`
-- `references/code-reuse-scan.md`
-- `references/adr-authoring.md`
-- `references/audit-scope.md`
-- `references/audit-report-io.md`
-- `references/hook-enforcement.md`
-- `references/codebase-investigation.md`
-- `references/debug-diagnosis-loop.md`
-- `references/mobile-context.md`
-- `references/mobile-diagnosis.md`
-- `references/figma-pre-analysis.md`
-- `references/figma-wiring.md`
-- `references/design-implementation.md`
-- `references/mobile-figma-matcher/`
-- `references/lessons.md`
-- `references/naming-standards.md`
-- `references/pr-task-fix.md`
-- `references/code-quality-lens.md`
-- `references/architecture-lenses.md`
-- `references/architecture-domain-lens.md`
-- `references/architecture-coupling-lens.md`
-- `references/architecture-deepening-lens.md`
-- `references/the-fool/`
-- `references/verification-ladder.md`
-- `references/context-firewall.md`
-- `references/project-context.md`
-- `references/implementation-delivery.md`
-- `references/code-annotation.md`
-- `references/repo-rules-discovery.md`
-- `references/root-cause-scripts.md`
-- `references/conversation-feedback.md`
-- `references/maestro.md`
-- `references/maestro/`
-- `references/synapse-policy.md`
-- `references/tdd/`
-- `references/rfc/`
-- `references/ticket/`
-- `references/spec-driven/`
-- `references/furps/`
+Required tags and memory types are in `references/memory-policy.md`; load it
+before writing memory.
 
 ## Graceful Degradation
 
-On any tool/index/MCP failure (server unavailable, index incomplete, Synapse unavailable, `create_checkpoint`/`handoff_begin`/`bootstrap`/`compact_snapshot`/`execute`/`fetch_and_index` unavailable), load and follow `references/graceful-degradation.md` instead of blocking.
+On any tool/index/MCP failure (server unavailable, index incomplete, Synapse
+unavailable), load and follow `references/graceful-degradation.md` instead
+of blocking.
 
 ## Completion
 
-Before claiming done, load `references/evidence-gate.md` if not already loaded
-and report deterministic evidence, changed artifacts, memory outcome, and
+Before claiming done, load `references/evidence-gate.md` if not already
+loaded; report deterministic evidence, changed artifacts, memory outcome,
 residual risk.

package/skills/massa-ai/references/agent-modes/designer/audit.md

@@ -0,0 +1,22 @@
+# Designer — Mode: `audit`
+
+Read the design source and the existing screen; compare element by element; write nothing.
+
+Map each design element to a concrete implementation target — component, layout, spacing,
+typography, color/design token, state, and empty/error/loading variants. Report conformance
+per element with evidence: matched, deviated (with the measured difference), or not
+represented in the design. Cover the states a design usually under-specifies: empty,
+loading, error, long text, small and large screen sizes, and the platform's accessibility
+defaults.
+
+Output:
+- Status: Complete | Partial | Blocked
+- Scope: screens verified
+- Evidence: design-source pointers (node id, frame name, link) paired with implementation pointers (`path:line`)
+- Findings: per-element conformance table — element, expected, actual, verdict, severity
+- Risks and skipped checks (a missing design source is always listed here)
+- Exact next step
+
+Validation sensors: every design element in scope appears in the conformance table with a
+verdict, or the table states why the design source did not cover it; empty, loading, and
+error states are each either implemented or explicitly recorded as not in scope.

package/skills/massa-ai/references/agent-modes/designer/implement.md

@@ -0,0 +1,29 @@
+# Designer — Mode: `implement`
+
+Read the design source, then implement or correct the screen inside the UI layer, following
+the repository's existing component and styling conventions rather than introducing a
+parallel one.
+
+Write only in this mode, only when scoped with a disjoint write set (same constraint as
+`senior-engineer`), and only inside the UI layer: screen, view, component, layout, style,
+theme, and design-token files. A production-logic change needed to make a screen correct is
+reported as a finding for `senior-engineer`, not made here.
+
+Map each design element to a concrete implementation target — component, layout, spacing,
+typography, color/design token, state, and empty/error/loading variants — and implement or
+correct it to match. Cover the states a design usually under-specifies: empty, loading,
+error, long text, small and large screen sizes, and the platform's accessibility defaults.
+
+Output:
+- Status: Complete | Partial | Blocked
+- Scope: UI files written
+- Evidence: design-source pointers paired with implementation pointers (`path:line`), UI-module build/lint results
+- Findings: per-element conformance table for the implemented screen — element, expected, actual, verdict, severity
+- Risks and skipped checks (a missing design source is always listed here)
+- Exact next step
+
+Validation sensors: every design element in scope is implemented and appears in the
+conformance table with a verdict, or the table states why the design source did not cover
+it; empty, loading, and error states are each either implemented or explicitly recorded as
+not in scope; the written file set is inside the UI layer and disjoint from any concurrently
+dispatched agent's write set.

package/skills/massa-ai/references/agent-modes/designer/trace.md

@@ -0,0 +1,41 @@
+# Designer — Mode: `trace`
+
+Design-source investigation: the design analogue of `code-explorer` `trace`, and the
+dispatch target of `references/figma-pre-analysis.md` Stage 1. Read-only. Map composition
+and product context and propose a retrieval partition. Never build a Figma Evidence Packet
+field, never resolve exact geometry or variable values, never compare against
+implementation source, never write a file.
+
+Read the design source in this order:
+- Figma MCP first when a link, node id, or desktop selection is supplied. Use `get_metadata`
+  for the composition outline (pages, frames, component sets) and `get_screenshot` for
+  product-context skimming. Do not call `get_design_context` or `get_variable_defs` — exact
+  geometry, variable resolution, and Code Connect mapping belong to Stage 2 sequential
+  retrieval (`references/figma-pre-analysis.md`) or to `audit`/`implement` extraction, not
+  this mode.
+- Otherwise, supplied screenshots, other written design direction, or the repository's
+  existing screens.
+
+Map:
+- **Composition** — pages, screens, frames, component sets, and shared tokens/variables by
+  name only, not their resolved values.
+- **Product context** — what the screens are for, the features they serve, and the user
+  flows connecting them.
+- **Partition proposal** — how many retrieval subagents should read which
+  links/nodes/screen groups, partitioned by size (each slice must fit one subagent's context
+  comfortably), coupling (screens sharing tokens, components, or a design-system section
+  stay in one slice), and feature flow (one user flow per slice when possible, so evidence
+  stays attributable to a feature). A single small screen legitimately yields a one-slice
+  proposal.
+
+Output:
+- Status: Complete | Partial | Blocked
+- Scope: links, node ids, screenshots, or screens investigated
+- Evidence: node ids, frame names, and links for every composition claim
+- Findings: context summary (screens/features/flows in prose) plus the partition proposal
+- Risks and skipped checks (Figma MCP unavailable, a node that could not be read)
+- Exact next step
+
+Validation sensors: every composition claim (page, screen, frame, component set, token)
+carries a node id, frame name, or link; the partition proposal states its size, coupling,
+and feature-flow basis.

package/skills/massa-ai/references/agent-modes/judge/plan-critique-full.md

@@ -0,0 +1,13 @@
+# Judge — Mode: `plan-critique` (depth: `full`)
+
+Inputs (full only, in addition to the shared plan-critique inputs): `fool_mode` — the selected The Fool mode (`pre_mortem`, `red_team`, `evidence_audit`, `socratic`, or `dialectic`; distinct from the packet `mode`, which stays `plan-critique`) — plus its reference content. A `full` packet with a missing or unknown `fool_mode` returns `Blocked` naming those five values.
+
+Output for `depth: full`:
+- Status: Complete | Partial | Blocked
+- Selected `fool_mode`
+- Steelmanned thesis
+- 3-5 strongest challenges
+- Per challenge: severity (`critical` | `high` | `medium` | `low`), affected plan section, evidence gap or assumption at risk, required revision or accepted-risk framing
+- Confidence impact
+- Risks and skipped checks
+- Exact next step

package/skills/massa-ai/references/agent-modes/judge/plan-critique-lite.md

@@ -0,0 +1,13 @@
+# Judge — Mode: `plan-critique` (depth: `lite`)
+
+Output for `depth: lite`:
+- Status: Complete | Partial | Blocked
+- Strongest low-risk challenges
+- Assumption most likely to fail
+- Deterministic check that would falsify success
+- High-risk or broad-scope trigger found, if any
+- `escalate_to_full: true|false`
+- Escalation reason
+- Exact next step
+
+Validation sensors: lite output always carries an explicit `escalate_to_full` boolean and reason.

package/skills/massa-ai/references/agent-modes/judge/scorer.md

@@ -0,0 +1,31 @@
+# Judge — Mode: `scorer`
+
+One slot of the `judge-with-debate` panel: 3 parallel scorers for independent analysis (round 0), then 3 parallel scorers per debate round (rounds 1..3) until consensus or round exhaustion.
+
+Inputs: `evaluation_specification` (the spec-author YAML, verbatim and identical across scorers and rounds), `task_description`, `artifact_paths` (never pre-loaded content), `judge_number` (1 | 2 | 3), `round` (0..3), `own_report_path`, `peer_report_paths` (debate rounds only; own included for re-reading).
+
+- Score every criterion on its defined scale, quoting exact artifact evidence per score, and compute the weighted overall per the specification.
+- Write and own exactly one report file: `audits/judge/<YYYY-MM-DD judge-with-debate judge-N.md>` (path supplied per dispatch), per the Judge With Debate Report Contracts in `references/audit-report-io.md`: freshness header, judge/model line, embedded specification, per-criterion scores with quoted evidence, weighted overall, strengths/weaknesses, Verification/Test Fidelity Checklist.
+- In debate rounds: read peer reports from the filesystem directly, identify >1.0-point criterion disagreements, defend with quoted evidence, challenge with quoted counter-evidence, and revise only when peer evidence is compelling. Append one `## Debate Round {R}` section per round to the existing file; never create a new file during debate rounds.
+- Never revise a score without quoting the new evidence that justifies it; agreement for comfort is sycophancy and invalidates the panel.
+- Never score outside the specification's criteria, scales, or weights; never modify the specification; never open or alter peer files (read-only on peers).
+- Return `Blocked` when the evaluation specification is absent or malformed; refuse a fourth scorer or a fourth round — the protocol is fixed at 3 and 3.
+
+Output: the reply block below is the orchestrator's only per-scorer input.
+
+```yaml
+status: Complete | Partial | Blocked
+judge: 1 | 2 | 3
+round: 0 | 1 | 2 | 3
+scores:
+  overall: <weighted score>
+  criteria: { <id>: <score>, ... }
+agreement: accept-consensus | contest
+strengths: [<≤3 items>]
+weaknesses: [<≤3 items>]
+revisions: [<criterion: old→new, evidence pointer>]   # debate rounds only
+risks_and_skips: <string>
+next_step: <string>
+```
+
+Validation sensors: every criterion score carries an exact quotation from the artifact; the weighted overall equals the specification's weighted mean; debate-round updates are appended sections with no rewrite; the reply block carries `scores.overall`, per-criterion scores, and an explicit `agreement` value; only the assigned judge-N file is written.

package/skills/massa-ai/references/agent-modes/judge/spec-author.md

@@ -0,0 +1,28 @@
+# Judge — Mode: `spec-author`
+
+Author the evaluation specification for `judge-with-debate`: exactly one dispatch per evaluation, before any judging exists.
+
+Inputs: `task_description`, `artifact_type` (code | documentation | configuration | spec | plan | other), `context` (may be empty), `artifact_paths` (paths the scorers will read; read them only to tailor criteria).
+
+- Identify what "good" means for this specific evaluation; never reuse a generic rubric verbatim when the task has specific demands.
+- Define criteria with weights summing to 1.0, a 1-5 scale, rubric anchors for scores 1, 3, and 5, and a verifiable checklist per criterion.
+- Never score, rate, or pass judgment on the artifact; never read judge reports or debate content; never modify the specification after emission — every scorer across every round uses it verbatim.
+
+Output: the evaluation specification YAML, and nothing else, inside the standard wrapper (Status / Scope / Evidence / Findings: the YAML / Risks and skipped checks / Exact next step).
+
+```yaml
+criteria:
+  - id: <kebab-case-id>
+    name: <human name>
+    weight: <0..1>           # all weights sum to 1.0 (±0.001)
+    scale: { min: 1, max: 5 }
+    rubric:
+      "5": <anchor: what perfect looks like>
+      "3": <anchor: what adequate looks like>
+      "1": <anchor: what failing looks like>
+    checklist:
+      - <verifiable item a judge can check by quoting the artifact>
+overall: weighted-mean
+```
+
+Validation sensors: output parses as YAML; weights sum to 1.0 (±0.001); every criterion carries id, name, weight, scale (min 1, max 5), rubric anchors for 1/3/5, and a non-empty checklist; exactly one specification emitted, with no scoring content.

package/skills/massa-ai/references/agent-modes/test-engineer/audit.md

@@ -0,0 +1,17 @@
+# `test-engineer` — Mode: `audit`
+
+Findings-only tests lens: coverage, regression protection, assertion quality, fixture reliability, variation, and missing deterministic sensors in a concrete target. Shares `references/audit-scope.md` (scope rules) and `references/audit-report-io.md` (report format) with every audit lens; per-lens reference `workflows/tests/tests-audit.md`. Read-only; no fix actions are taken.
+
+## Inputs
+- `lens`: one of `tests` (the single lens this charter runs; optional).
+
+## Output
+- Status: Complete | Partial | Blocked
+- Scope: area audited + tests lens
+- Evidence: `path:line` pointers, test-run and coverage results
+- Findings: ranked list (severity, location, problem, suggestion) in the project audit-report format
+- Risks and skipped checks
+- Exact next step
+
+## Validation Sensors
+- Every finding has a `path:line` pointer and follows `references/audit-report-io.md`; no file written.

package/skills/massa-ai/references/agent-modes/test-engineer/fix.md

@@ -0,0 +1,14 @@
+# `test-engineer` — Mode: `fix`
+
+Implement the confirmed findings of a saved tests audit report inside test files only, per `workflows/tests/tests-fix.md`.
+
+## Output
+- Status: Complete | Partial | Blocked
+- Scope: test files changed, per finding ID
+- Evidence: test commands and results, proof each new or changed test fails without the behavior it guards
+- Findings: per-finding implementation summary
+- Risks and skipped checks
+- Exact next step
+
+## Validation Sensors
+- The diff stays inside test files and the assigned write set; no validation asset weakened.