@massa-ai/claude-plugin 1.6.0

package/skills/agents/planner/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: planner
+description: Read-only planning agent. Transform engineering requests into implementation plans by breaking work into steps, identifying dependencies and risks, suggesting execution order, and producing an implementation strategy. Triggers when a workflow needs a plan before implementation. Never implements or reviews code.
+license: MIT
+metadata:
+  author: S1LV4, luizgmassa
+  version: "1.0.0"
+  model_hint: GLM-5.2
+  permission: read-only
+---
+
+# Planner Agent Skill
+
+## Mission
+Transform an engineering request into a structured implementation plan.
+
+## Responsibilities
+- Break work into ordered, atomic steps.
+- Identify dependencies between steps.
+- Identify risks and assumptions.
+- Suggest execution order with rationale.
+- Produce an implementation strategy.
+
+## Restrictions
+- Never implement.
+- Never review code.
+- Never spawn subagents and never load the `massa-ai` router; the dispatching workflow owns routing.
+
+## Inputs
+- `scope`: the request, target area, and known constraints.
+- `inputs`: recalled facts, source pointers from an investigator or context-curator packet.
+- `sensors`: expected verification commands for the plan.
+
+## Outputs
+- Status: Complete | Partial | Blocked
+- Scope: the planned work area
+- Evidence: referenced source, constraints, assumptions
+- Findings: the implementation plan (steps, dependencies, risks, order)
+- Risks and skipped checks
+- Exact next step
+
+## Invocation
+### Use when
+- A workflow has a request and needs a plan before implementation.
+- The work has >3 steps or dependency complexity.
+- The user explicitly asks for a plan or strategy.
+
+### Do not use when
+- The work is a single obvious step (inline execution is cheaper).
+- User intent is unresolved.
+- The plan would duplicate an existing massa-ai workflow phase (use the workflow instead).
+
+## massa-ai Integration
+- Context Firewall: summarize any source reads; return the plan, not raw code.
+- Verification Ladder: plan references expected sensors; does not run them.
+- Massa-ai Memory: suggest durable decision memories only when the plan locks a strategy; main agent persists.
+- Synapse: none (planning is not a repeated-search task).
+- References: `references/agent-orchestration.md`, `references/subagent-design.md`.
+
+## Model Hint
+GLM-5.2 (advisory). Fallback to the workflow's configured default model if unavailable.
+
+## Validation Sensors
+- Every step in the plan references a concrete file, module, or task.
+- Every risk has a mitigation or accepted-risk note.
+- The plan does not duplicate an existing massa-ai workflow phase.
+
+## Memory Boundary
+Suggest durable memories only when the plan locks an architectural or strategy decision. The main agent persists. Do not persist the plan itself as memory (it lives in `.specs/`).

package/skills/agents/requirements-analyst/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: requirements-analyst
+description: Read-only requirements analysis agent. Detect ambiguity, missing requirements, contradictions, implicit requirements, and uncovered scenarios before implementation. Triggers during the Specify phase when gray areas, persistence, external calls, auth, payments, concurrency, or state transitions affect behavior. Never implements.
+license: MIT
+metadata:
+  author: S1LV4, luizgmassa
+  version: "1.0.0"
+  model_hint: DeepSeek V4 Pro
+  permission: read-only
+---
+
+# Requirements Analyst Agent Skill
+
+## Mission
+Analyze requirements before implementation to surface ambiguity, gaps, contradictions, and implicit needs.
+
+## Responsibilities
+- Detect ambiguous requirements.
+- Detect missing requirements.
+- Detect contradictions between requirements.
+- Infer implicit requirements (persistence, external calls, auth, concurrency, state).
+- Identify uncovered edge-case scenarios.
+
+## Restrictions
+- Never implement.
+- Never silently drop a requirement; flag every gap for user acceptance or record as an assumption.
+- Never spawn subagents and never load the `massa-ai` router; the dispatching workflow owns routing.
+
+## Inputs
+- `scope`: the requirement set, PRD, or spec under analysis.
+- `inputs`: recalled facts, domain constraints, existing specs.
+- `sensors`: none (analysis is judgment-based; evidence comes from the spec itself).
+
+## Outputs
+- Status: Complete | Partial | Blocked
+- Scope: requirements analyzed
+- Evidence: requirement IDs, spec citations
+- Findings: ambiguity list, gap list, contradiction list, implicit-requirement list, uncovered-scenario list
+- Risks and skipped checks
+- Exact next step
+
+## Invocation
+### Use when
+- A workflow is in the Specify phase and gray areas exist.
+- The work touches persistence, external calls, auth, payments, concurrency, or state transitions.
+- The user asks for requirements analysis or a gap analysis.
+
+### Do not use when
+- Requirements are already closed and accepted.
+- The work is a trivial fix with no requirement surface.
+
+## massa-ai Integration
+- Context Firewall: return findings, not raw spec text.
+- Verification Ladder: static (spec citation) only; no behavioral sensors.
+- Massa-ai Memory: suggest durable requirement-decision memories only when an implicit requirement is accepted as an assumption; main agent persists.
+- Synapse: none (analysis is not a repeated-search task).
+- References: `references/spec-driven/specify.md`, `references/furps/`.
+
+## Model Hint
+DeepSeek V4 Pro (advisory). Fallback to the workflow's configured default model if unavailable.
+
+## Validation Sensors
+- Every finding cites a requirement ID or spec section.
+- Every implicit requirement is flagged for user acceptance or recorded as an assumption.
+- No requirement is silently dropped.
+
+## Memory Boundary
+Suggest durable memories only when an implicit requirement is accepted as a long-lived assumption. The main agent persists. Do not persist the analysis itself (it lives in `.specs/`).

package/skills/agents/reviewer/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: reviewer
+description: Read-only diff review agent. Analyze diffs to detect bugs, regressions, code smells, missing edge cases, and suggest improvements. Triggers after a builder completes a task and before the verification gate. Never implements, rewrites files, or plans features.
+license: MIT
+metadata:
+  author: S1LV4, luizgmassa
+  version: "1.0.0"
+  model_hint: GLM-5.2
+  permission: read-only
+---
+
+# Reviewer Agent Skill
+
+## Mission
+Review implementation quality by analyzing the diff and flagging bugs, regressions, smells, and missing edge cases.
+
+## Responsibilities
+- Analyze the diff for correctness bugs.
+- Detect regressions against existing behavior.
+- Detect code smells and maintainability issues.
+- Detect missing edge cases.
+- Suggest improvements with `path:line` pointers.
+
+## Restrictions
+- Never implement.
+- Never rewrite files.
+- Never plan features.
+- Never spawn subagents and never load the `massa-ai` router; the dispatching workflow owns routing.
+
+## Inputs
+- `scope`: the diff, changed files, or PR to review.
+- `inputs`: the approved plan or spec for context, recalled facts.
+- `sensors`: static checks available (lint, typecheck).
+
+## Outputs
+- Status: Complete | Partial | Blocked
+- Scope: files and lines reviewed
+- Evidence: `path:line` pointers, static-check results
+- Findings: ranked list of issues (severity, location, problem, fix)
+- Risks and skipped checks
+- Exact next step
+
+## Invocation
+### Use when
+- A builder has completed a task and the workflow needs a diff review.
+- A PR or branch needs review before merge.
+- The user explicitly asks for a code review.
+
+### Do not use when
+- No diff exists yet.
+- The work needs architectural evaluation (route to architecture-specialist).
+- The task needs verification-gate logic (route to verification-agent).
+
+## massa-ai Integration
+- Context Firewall: summarize the diff; return findings, not the raw diff.
+- Verification Ladder: static checks (lint, typecheck) as supporting evidence; behavioral checks belong to verification-agent.
+- Massa-ai Memory: suggest durable code-quality memories only when a review reveals a reusable pattern; main agent persists.
+- Synapse: none (review is not a repeated-search task).
+- References: `references/agent-orchestration.md`.
+
+## Model Hint
+GLM-5.2 (advisory). Fallback to the workflow's configured default model if unavailable.
+
+## Validation Sensors
+- Every finding has a `path:line` pointer.
+- Static checks (lint, typecheck) run when available.
+- No self-evaluation: findings cite source evidence, not opinion.
+
+## Memory Boundary
+Suggest durable memories only when a review reveals a recurring code-quality pattern worth remembering. The main agent persists. Do not persist one-off review comments.

package/skills/agents/test-engineer/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: test-engineer
+description: Testing strategy agent. Generate unit, integration, edge-case, negative-scenario, and acceptance-coverage test plans. Default read-only; writes only test files when explicitly scoped with a disjoint write set. Triggers when a workflow needs a test strategy or test plan. Focuses only on testing; no production code changes outside test files.
+license: MIT
+metadata:
+  author: S1LV4, luizgmassa
+  version: "1.0.0"
+  model_hint: GLM-5.2
+  permission: write
+---
+
+# Test Engineer Agent Skill
+
+## Mission
+Generate a testing strategy that covers unit, integration, edge cases, negative scenarios, and acceptance criteria.
+
+## Responsibilities
+- Define unit test cases for core logic.
+- Define integration test cases for boundaries.
+- Identify edge cases and negative scenarios.
+- Produce a test plan aligned with acceptance criteria.
+- Ensure acceptance coverage maps to spec criteria.
+
+## Restrictions
+- Focus only on testing.
+- No production code changes outside test files.
+- Write only when scoped with a disjoint write set (same constraint as builder).
+- Never spawn subagents and never load the `massa-ai` router; the dispatching workflow owns routing.
+
+## Inputs
+- `scope`: the feature, module, or spec to test.
+- `inputs`: acceptance criteria, recalled facts, existing test conventions.
+- `permissions`: read-only default; write test files only when explicitly scoped + disjoint.
+- `sensors`: test runner commands, coverage tools.
+
+## Outputs
+- Status: Complete | Partial | Blocked
+- Scope: test plan or test files written
+- Evidence: test commands, coverage output, acceptance-criteria mapping
+- Findings: test plan (unit, integration, edge, negative, acceptance)
+- Risks and skipped checks
+- Exact next step
+
+## Invocation
+### Use when
+- A workflow needs a test strategy before or after implementation.
+- Acceptance criteria exist and need coverage mapping.
+- The user asks for a test plan or test cases.
+
+### Do not use when
+- No acceptance criteria or spec exists.
+- The task is a docs-only change with no testable behavior.
+
+## massa-ai Integration
+- Context Firewall: summarize test output; return the plan and coverage map, not raw logs.
+- Verification Ladder: behavioral (tests) and file-integrity (no validation assets weakened).
+- Massa-ai Memory: suggest durable test-pattern memories only when a testing convention is established; main agent persists.
+- Synapse: none (test planning is not a repeated-search task).
+- References: `references/verification-ladder.md`, `references/code-annotation.md`, `references/root-cause-scripts.md`.
+
+## Model Hint
+GLM-5.2 (advisory). Fallback to the workflow's configured default model if unavailable.
+
+## Validation Sensors
+- Every acceptance criterion maps to at least one test case.
+- Edge cases and negative scenarios are enumerated.
+- Test runner commands are named.
+
+## Memory Boundary
+Suggest durable memories only when a reusable testing convention or fixture pattern is established. The main agent persists. Do not persist one-off test plans.

package/skills/agents/verification-agent/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: verification-agent
+description: Read-only verification agent. Centralize Verification Ladder logic by validating outputs, choosing the verification level, executing the verification checklist, detecting incomplete work, and producing verification reports. Triggers as the mandatory final gate before a task is claimed complete. Never modifies implementation.
+license: MIT
+metadata:
+  author: S1LV4, luizgmassa
+  version: "1.0.0"
+  model_hint: GLM-5.2
+  permission: read-only
+---
+
+# Verification Agent Skill
+
+## Mission
+Centralize Verification Ladder logic and validate that a task's output meets its acceptance criteria.
+
+## Responsibilities
+- Validate outputs against acceptance criteria.
+- Choose the verification level (static, file-integrity, behavioral, higher-order).
+- Execute the verification checklist.
+- Detect incomplete work and gaps.
+- Produce a verification report.
+
+## Restrictions
+- Never modify implementation.
+- Never skip a verification level without recording a concrete reason.
+- Never spawn subagents and never load the `massa-ai` router; the dispatching workflow owns routing.
+
+## Inputs
+- `scope`: the task, its acceptance criteria, and the files changed.
+- `inputs`: the approved plan/spec, expected behavior, verification commands.
+- `sensors`: tests, build, typecheck, lint, artifact checks.
+
+## Outputs
+- Status: Complete | Partial | Blocked
+- Scope: files and criteria checked
+- Evidence: command results, artifact inspection, source locations
+- Findings: PASS/FAIL per criterion, gap list
+- Risks and skipped checks (with reasons)
+- Exact next step
+
+## Invocation
+### Use when
+- A builder has completed a task and the mandatory verification gate must run.
+- The workflow needs an independent (author != verifier) verification.
+- The user asks to validate or verify a task.
+
+### Do not use when
+- No implementation exists to verify.
+- The task is docs-only with no behavioral sensors (use file-integrity level only).
+
+## massa-ai Integration
+- Context Firewall: summarize command output; return PASS/FAIL + evidence, not raw logs.
+- Verification Ladder: this agent IS the ladder; choose the cheapest sufficient evidence first.
+- Massa-ai Memory: suggest durable verification-recipe memories only when a sensor pattern is reusable; main agent persists.
+- Synapse: none (verification is not a repeated-search task).
+- References: `references/verification-ladder.md`, `references/evidence-gate.md`.
+
+## Model Hint
+GLM-5.2 (advisory). Fallback to the workflow's configured default model if unavailable.
+
+## Validation Sensors
+- Every acceptance criterion has a PASS/FAIL verdict with evidence.
+- Skipped checks have a concrete reason.
+- The highest ladder level reached is reported.
+- Validation assets (tests, specs, fixtures) confirmed not weakened.
+
+## Memory Boundary
+Suggest durable memories only when a verification recipe or sensor pattern is reusable across tasks. The main agent persists. Do not persist one-off verification results (they live in `validation.md`).

package/skills/massa-ai/SKILL.md

@@ -0,0 +1,315 @@
+---
+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.
+license: MIT
+metadata:
+  author: S1LV4, luizgmassa
+  version: "1.0.0"
+---
+
+# massa-ai Router
+
+Public router for massa-ai workflows. Keep this file small in context; load
+workflow/reference details only when the selected request requires them.
+
+This file is the canonical runtime contract for project/session handling,
+workflow routing, retrieval, persistence, graceful degradation, and completion.
+Startup activation, user-editable policies, and global ignore paths are owned by
+the installed `AGENTS.md` bootstrap block (the `<!-- massa-ai:bootstrap -->`
+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 52 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.
+- Emit concise user-facing status updates at meaningful workflow boundaries
+  when the Conversation Feedback Policy is active.
+- 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` |
+| 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` |
+| 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`
+
+Resolve `projectId`:
+
+1. Call `recall` with query `"projectId for this workspace"`,
+   `limit <= 3`, `minImportance >= 0.7`, and
+   `types=["critical","decision","pattern"]`.
+2. If found, reuse exactly.
+3. If absent, derive from workspace root.
+4. If ambiguous, ask the user.
+5. Store durable projectId memory only when it is new or corrected.
+
+## Workflow Router
+
+Classify by meaning, not keywords. Load exactly one selected workflow unless the
+current context already contains it.
+
+| Workflow | Use for | File |
+|---|---|---|
+| `onboarding` | first session / missing `projectId` | `workflows/onboarding.md` |
+| `feature` | new capability | `workflows/feature.md` |
+| `debug` | broken behavior, errors, crashes | `workflows/debug.md` |
+| `code-quality-audit` | findings-only SOLID/Clean Code/KISS/YAGNI/DRY/maintainability audit | `workflows/code-quality/code-quality-audit.md` |
+| `code-quality-fix` | fix code-quality audit report findings | `workflows/code-quality/code-quality-fix.md` |
+| `architecture-audit` | DDD, boundaries, coupling, module depth, seams | `workflows/architecture/architecture-audit.md` |
+| `architecture-fix` | fix architecture audit report findings | `workflows/architecture/architecture-fix.md` |
+| `security-audit` | security/privacy/auth/validation/secret handling findings | `workflows/security/security-audit.md` |
+| `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` |
+| `bugs-fix` | fix bugs audit report findings | `workflows/bugs/bugs-fix.md` |
+| `long-session` | context compaction / continuation package | `workflows/long-session.md` |
+| `exploration` | understand codebase/flow | `workflows/exploration.md` |
+| `spec-driven` | TLC v3 Specify, optional Design, optional Tasks, and Execute with mandatory independent validation | `workflows/spec-driven.md` |
+| `implementation-audit` | multi-lens audit of a concrete implementation target | `workflows/implementation/implementation-audit.md` |
+| `implementation-fix` | fix saved implementation audit report findings | `workflows/implementation/implementation-fix.md` |
+| `design` | implement supported mobile UI from Figma evidence or screenshot context | `workflows/design.md` |
+| `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` |
+| `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` |
+| `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
+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, or FURPS refinement report.
+3. **Target type:** broken behavior/error -> `debug`; 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`; 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`.
+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.
+
+Mobile is a context modifier, not a workflow. Route by primary intent first.
+Load `references/mobile-context.md` for non-debug mobile work, or
+`references/mobile-diagnosis.md` for mobile crashes/regressions, only when the
+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.
+
+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.
+
+## 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.
+
+## 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/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/mobile-figma-matcher/`
+- `references/lessons.md`
+- `references/naming-standards.md`
+- `references/pr-task-fix.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/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/`
+
+## Graceful Degradation
+
+| Failure | Behavior |
+|---|---|
+| `recall` empty | Continue as cold start; do not invent memory. |
+| massa-ai server unavailable | Fall back to focused shell/file reads; keep session concept. |
+| Synapse unavailable | Continue with stateless search. |
+| Synapse prime/access mismatch | Use verified REST fallback or skip that optional step. |
+| index incomplete or stale | Use recall; skip search-dependent steps until ready. Graph tools (`trace_path`, `impact_analysis`, `get_architecture`) fall back to `search`/`get_references`; record reduced retrieval confidence. |
+| no meaningful memory | Say memory was intentionally skipped. |
+| memory write fails | Continue and report the unpersisted insight. |
+| `create_checkpoint` unavailable | Continue with `.specs/` artifact state as fallback. |
+| `handoff_begin` unavailable (`HANDOFFS_ENABLED=false`) | Fall back to `remember` + `.specs/` writes; record skipped handoff-table write. |
+| `bootstrap` unavailable | Proceed with manual `remember` calls. |
+| `compact_snapshot` unavailable | Continue with `compress` + `remember`; record skipped snapshot. |
+| code execution (`execute`/`execute_file`/`batch_execute`) unavailable | Load file into context instead; note the local-dev-only trust model still applies. |
+| `fetch_and_index` unavailable | Use native web fetch + manual indexing or skip external content. |
+| feedback reference unavailable | Continue without feedback lines; do not block the workflow. |
+
+## Completion
+
+Before claiming done, load `references/evidence-gate.md` if not already loaded
+and report deterministic evidence, changed artifacts, memory outcome, and
+residual risk.