| name | massa-th0th |
| 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 th0th 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. |
massa-th0th Router
Public router for massa-th0th 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
AGENTS.md.
Dedupe Guard
Before reading any massa-th0th file:
- In a new coding conversation, load this router once before using dedupe.
- After that initial load, reuse already-loaded
massa-th0th, 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
th0th_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
th0th_recall as an artifact loader. Exact project, restart,
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 th0th_search.sessionId.
Never pass workflowSessionId in that field.
- Prefer the shared v2 retrieval order; fall back gracefully if th0th or
Synapse is unavailable.
- Persist only durable, useful knowledge. Do not fabricate memories to satisfy
process.
- 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/th0th-tools.md |
| Multi-search Synapse lifecycle and fallback | references/synapse-policy.md |
| Install/config/deployment | references/th0th-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:
- Classify the workflow.
- Infer the main entity.
- Generate a stable id:
<workflow>-<entity>.
- Reuse it for the whole conversation.
Examples:
debug-login-crashfeature-user-onboardingrefactor-auth-modulespec-billing-workflowadr-postgres-migration
Resolve projectId:
- Call
th0th_recall with query "projectId for this workspace",
limit <= 3, minImportance >= 0.7, and
types=["critical","decision","pattern"].
- If found, reuse exactly.
- If absent, derive from workspace root.
- If ambiguous, ask the user.
- 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 |
restart-save | preserve canonical th0th restart state for a clean/new chat | workflows/restart-save.md |
restart-load | load canonical th0th restart state in a clean/new chat | workflows/restart-load.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 |
agent-handoff | agent-to-agent transfer | workflows/agent-handoff.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:
- Explicit route: user names a massa-th0th workflow, report family, saved finding type, restart save/load procedure, or asks for a direct challenge.
- Requested artifact: ADR, RFC, TDD, Jira ticket, commit, handoff, restart state, audit report, implementation audit report, mobile Figma report, or FURPS refinement report.
- 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.
- Primary verb: save/preserve/prepare clean chat restart state ->
restart-save; load/resume/continue from saved restart state -> restart-load; 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.
- 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.
- 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
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
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 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 subagent spawning is unavailable or platform policy forbids it, run
a strict standalone fresh-eyes local critique and report the skipped delegation
reason. Reuse The Fool context when it is already loaded.
Retrieval And Synapse
Use this default retrieval sequence when it matches the task:
th0th_list_projects or equivalent freshness evidence before relying on indexed project state.th0th_project_map for one-shot architecture orientation when the index is fresh for the current repository path and worktree state.th0th_search(responseMode="summary", maxResults=10) for broad discovery.th0th_search(responseMode="enriched", maxResults=3) for targeted deep reads; use maxResults=5 only when the user named 4-5 concrete files, symbols, or findings.- Symbol navigation and
th0th_read_file for exact definitions, usages, and
line ranges.
th0th_optimized_context for compact synthesized context when available.- Focused shell/file fallback when th0th is unavailable, stale, incomplete, or misses
obvious local truth.
th0th_project_map, th0th_search, and th0th_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.
Load references/synapse-policy.md when the planned investigation includes
two or more related th0th_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 th0th 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.mdreferences/subagent-design.mdreferences/adr-authoring.mdreferences/audit-scope.mdreferences/audit-report-io.mdreferences/hook-enforcement.mdreferences/codebase-investigation.mdreferences/debug-diagnosis-loop.mdreferences/mobile-context.mdreferences/mobile-diagnosis.mdreferences/mobile-figma-matcher/references/lessons.mdreferences/naming-standards.mdreferences/pr-task-fix.mdreferences/handoff-package.mdreferences/restart-state.mdreferences/architecture-lenses.mdreferences/architecture-domain-lens.mdreferences/architecture-coupling-lens.mdreferences/architecture-deepening-lens.mdreferences/the-fool/references/verification-ladder.mdreferences/context-firewall.mdreferences/conversation-feedback.mdreferences/maestro.mdreferences/maestro/references/synapse-policy.mdreferences/tdd/references/rfc/references/ticket/references/spec-driven/references/furps/
Graceful Degradation
| Failure | Behavior |
|---|
th0th_recall empty | Continue as cold start; do not invent memory. |
| th0th unavailable | Fall back to focused shell/file reads; keep session concept. |
| Synapse unavailable | Continue with stateless th0th search. |
| Synapse prime/access mismatch | Use verified REST fallback or skip that optional step. |
| index incomplete | Use recall; skip search-dependent steps until ready. |
| no meaningful memory | Say memory was intentionally skipped. |
| memory write fails | Continue and report the unpersisted insight. |
| 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.
