# Moltch Shared

> Shared execution and communication contract for boilermolt + boilerclaw in BoilerHAUS/moltch, optimized for autonomous coordination with minimal human relay.

- Skill: `boilerhaus/moltch-shared` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add boilerhaus/moltch-shared`
- Raw SKILL.md: https://api.skillmd.com/api/skills/boilerhaus/moltch-shared/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: BoilerHAUS (https://skillmd.com/u/boilerhaus)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/boilerhaus/moltch-shared

---


Apply this skill as the default contract for both agents in `BoilerHAUS/moltch`.

## contract metadata
- skill_version: v1.3.0
- last_updated_utc: 2026-03-17T01:40:00Z

## activation boundary
- active for all work in `BoilerHAUS/moltch`
- active for issue-linked workstreams that modify moltch docs/process/implementation artifacts

## source of truth
- repository docs: `https://github.com/BoilerHAUS/moltch/tree/main/docs`
- workflow contract overrides ad-hoc execution unless human explicitly supersedes

## autonomy default + no-relay rule
- agents coordinate directly by default on linked issues/PRs
- do not ask human to relay messages between agents unless tooling/channel is unavailable
- when tooling is unavailable, escalate once with concise context and continue once channel is restored

## single-thread communication default
- keep agent-to-agent coordination in the same issue/PR thread by default for one visible audit trail
- use side-channel/private messaging only for sensitive context
- after side-channel use, post an in-thread non-sensitive summary

## mandatory workflow
1. start with an Issue
2. work in fork branch (`<actor>/issue-<id>-<slug>`)
3. open PR to `BoilerHAUS/moltch:main`
4. include `Closes #<issue>` when fully delivered (`Refs #<issue>` when partial)
5. wait for human approval before merge
6. sync fork after merge

Hard rules:
- no direct pushes to `main`
- respect CODEOWNERS and required checks
- keep PRs narrowly scoped and reversible

## mandatory pre-PR conformance gate (moltch)
Before opening or updating any PR in `BoilerHAUS/moltch`, run this sequence and fix failures first:

1. `npm --prefix <changed_package_if_any> run check` (when package-level scripts exist)
2. `bash scripts/docs/check_docs.sh`
3. `git status --short` and remove unintended generated drift
4. verify issue linkage in PR body (`Closes #<id>` for complete, `Refs #<id>` for partial)
5. verify rollback note exists in PR body

If any step fails, do not open/update PR until resolved.

## auto-remediation rules (required)
When conformance checks fail, apply deterministic fixes before asking humans:

- **roadmap mapping failures** (`check_docs.sh`):
  - update `docs/product/ROADMAP_V1.md` open-issues mapping/exclusions to match live open issues
  - remove closed issues from open mapping table
  - rerun checks

- **generated artifact drift** from local validation/build scripts:
  - discard unintended generated file changes unless the issue explicitly targets those artifacts
  - rerun checks on clean tree

- **issue linkage/body hygiene**:
  - ensure PR body has `Closes`/`Refs` correctness + rollback note + run instructions
  - patch PR body immediately if malformed

## human-opened issue/PR normalization
If the human opens an issue/PR that is non-conformant to moltch rules:
- post a concise correction comment with exact required format
- if quick to fix, open a narrow docs/process PR that normalizes the artifact
- link the normalization change back to the original issue/PR for traceability

## role lanes + cross-review
Primary lanes:
- **boilermolt**: product, governance, commercial, docs
- **boilerclaw**: technical architecture, deploy, repo plumbing

Cross-review:
- both agents review/comment on any PR
- anchor feedback to issue acceptance criteria + source-of-truth docs
- propose edits, avoid unilateral lane takeover

## discussion and implementation modes
- `discussion_only`: planning/architecture/policy; no implementation PR creation
- `implementation_allowed`: direct inter-agent execution is allowed without extra human relay

When mode is ambiguous, default to `discussion_only` and ask human to confirm transition.

## handoff SLA + template
SLA windows:
- active window: first response <= 30 minutes
- low-activity window: first response <= 12 hours

Required handoff block:
- objective
- current state
- exact ask
- expected output / acceptance check
- due window

## escalation threshold
Escalate with `needs-human` when any condition is true:
- SLA breach after 2 unanswered pings in active window
- policy ambiguity blocks safe execution
- blocker unresolved >15 minutes despite attempts

Escalation message MUST include:
- blocker
- attempts
- 2-3 options
- recommendation

## coordination heartbeat
For active execution issues/PRs, post concise in-thread updates:
- done
- next
- blocked

## priority taxonomy (moltch)
Use this shared priority scale for issue creation, triage, roadmap updates, and review sequencing in `BoilerHAUS/moltch`:

- `priority:p0` — immediate blocker / merge-critical / active outage
  - interrupts normal queue
  - expected response: now
  - requires explicit in-thread blocker summary
- `priority:p1` — current hands-on queue; do next
  - the active execution lane once p0 work is absent
  - use for the next issue/PR an agent should pick up
- `priority:p2` — ready after current slot; near-term committed
  - prepared work that should follow p1 without major reprioritization
- `priority:p3` — important queued work; not immediate
  - legitimate planned work, but not in the next execution slot
- `priority:p4` — planned later; strategic but not near-term
  - known future work that should stay visible without competing with the near-term queue
- `priority:p5` — parked / icebox / revisit later
  - not abandoned, but intentionally out of the active queue

### behavioral rules
- every open `moltch` issue should carry exactly one granular `priority:p*` label once the taxonomy is adopted
- when priorities conflict, agents should sequence work by the highest-priority issue first, then by dependency/mergeability
- `priority:p1` and `priority:p2` items should generally have a visible next execution step or linked PR plan
- `priority:p4` and `priority:p5` items should not be pulled into active execution without an explicit reprioritization signal

### transition guidance for legacy labels
During migration, treat legacy labels as follows:
- `priority:now` -> usually `priority:p0` or `priority:p1`
- `priority:next` -> usually `priority:p2`
- `priority:later` -> usually `priority:p4` or `priority:p5`

Do not rely on the legacy label alone when opening new issues. Prefer the granular `priority:p*` scale.

### when to explain a priority change in-thread
Post a brief in-thread explanation when:
- an issue is promoted into `priority:p0` or `priority:p1`
- an issue is demoted from `priority:p1`/`priority:p2` to `priority:p4`/`priority:p5`
- reprioritization changes the expected execution order in a way a human reviewer would otherwise miss

Keep the explanation short and operational:
- what changed
- why priority changed
- what this displaces or unblocks

## merge-readiness gate
Before final merge request, verify and record:
- mergeability is clean
- required checks are passing
- issue linkage is correct (`Closes`/`Refs`)
- rollback note exists in PR body

## docs and decision hygiene
- use deterministic language for policy-sensitive sections
- governance/product/operations docs include:
  - `version`
  - `owner_role`
  - `review_cadence`
  - `next_review_due`

## operational KPI
Track weekly:
- `human_relay_touches_per_issue` (target: down week-over-week)

## skill change management
This skill is a living contract; update via Issue + PR only.

Versioning policy:
- **patch**: wording/clarity only
- **minor**: additive process guidance/lane clarifications
- **major**: breaking workflow contract changes

Skill-update PRs must include:
- rationale
- behavior changes
- migration notes for both agents