marshail

MARSHAIL Implement stage. Delegate when the user asks to "implement phase X", "work on packet Y", "code this packet", "execute the plan", "start the next implementation cycle", "do the work for the current target", "write the code + tests for this", "run a Dev-QA pass", "close this cycle". Also delegate after the Plan stage (plan approved) to drive each implementation cycle, and after a verifier failure or reviewer fixup loop to resume coding. The subagent picks the cycle target, confirms / deepens the plan, executes (code + tests + Dev-QA where possible), offers the human a chance to inspect and give feedback, and closes the cycle by updating plan status, changelog, and learning files.

Copies MARSHAIL durable assets — both built-in lifecycle assets under `.marshail/{skills,skills-fallback,agents,rules}/` and repo-specific extensions under `.marshail/extensions/{skills,agents,rules}/` — into the project's config-sync source tree (default `.agent-config/`, overridable via `sync.agent_config_dir`), so the next `agent-conf-sync` run fans them out to all tool layouts. Names are preserved as-is: built-ins keep their `marshail-` prefix, extensions keep their `mx-` prefix. Use when the user asks to "promote MARSHAIL skills/agents/rules", "promote MARSHAIL extensions", "copy from .marshail to .agent-config", "wire MARSHAIL assets into the sync source", or similar — and from `marshail-init` for first-time setup.

MARSHAIL Repo recon / analysis stage. Delegate when the user asks to "analyze the repo for this change", "do recon", "narrow the search surface", "find the likely files / services / contracts", "identify invariants and test seams", "produce repo-recon.md", "what touches X in this codebase?", "where does Y live?", "scope the code areas before planning". Also delegate when change-brief.md exists and the Analysis stage is in scope, or when a planner / implementer flags they don't know enough about an area. The subagent reads the brief and existing knowledge, walks likely paths, and returns a tight repo-recon.md plus a stale-knowledge list — keeping intermediate exploration out of the parent context.

MARSHAIL Architecture / design stage. Delegate when the user asks to "design the solution", "agree the implementation concept", "discuss the architecture", "propose components / modules / APIs / schemas", "produce architecture-notes.md", "draft an ADR for this", "what's the right shape for this?", "compare design tradeoffs", "high-level layout for this change". Also delegate when change-brief.md and repo-recon.md exist and the change is large enough that the solution shape isn't obvious yet. The subagent drives the design conversation, captures rationale, and (when significant) promotes durable decisions to ADRs.

Run a whole MARSHAIL change end-to-end. Delegate when the user asks to "run MARSHAIL on this", "do a full MARSHAIL change for X", "orchestrate this change end-to-end", "drive this through MARSHAIL stages", "manage stage transitions for me", "resume this MARSHAIL change", "pick up where the change left off", "I want one orchestrator instead of juggling stages", or any high-level "do the whole thing under MARSHAIL" intent. Also delegate when starting a new change in a MARSHAIL repo (with `.marshail/` initialized) and the user wants per-stage approval gates managed automatically. The subagent agrees scope, detects current stage from on-disk artifacts, dispatches per-stage agents, and surfaces approval gates.

MARSHAIL on-demand help. Delegate when the user asks "how does MARSHAIL work?", "what does the X stage do?", "which skill / agent should I use next?", "what stage am I in?", "explain the knowledge layer", "how do I write a delivery plan?", "what goes in repo-recon.md?", "how does the config sync fit in?", "what's the difference between marshail-init and marshail-load?", "what's the marshail acronym?", "MARSHAIL?", or any procedural / conceptual question about the MARSHAIL process, the knowledge layer, the available skills / agents, or how MARSHAIL applies to the current change. Also delegate when the caller is unsure which skill / agent to use, or when another skill / agent encounters a MARSHAIL-meta question that would pollute its context. The subagent reads marshail.md and the repo's .marshail/ tree, returns a concise answer, and (when asked) hands off — read-only.

MARSHAIL Intake / framing stage. Delegate when the user asks to "frame the change", "write the change brief", "produce change-brief.md", "structure the engineering framing for this change", "list the non-goals and acceptance criteria", "convert the spec into a brief". Also delegate when the Specification stage is finished (specification.md exists) and the Intake stage is in scope, or when the user has a clear prompt but wants a structured brief before analysis/planning. The subagent turns the spec or prompt into change-brief.md (problem, scope, non-goals, acceptance criteria, constraints, rollout expectations).

Reconcile MARSHAIL knowledge files diverged on two branches. Delegate when the user asks to "merge knowledge files from two branches", "resolve a conflict in .marshail/knowledge/", "reconcile knowledge changes between feature branch and trunk", "3-way merge knowledge frontmatter and bodies", "handle overlapping repo_paths between branches", "two branches independently added domain notes — merge them". Use at merge time when both sides changed `.marshail/knowledge/`, when there's a git conflict in a knowledge file, or when both branches added content in overlapping areas without textual conflict. The subagent (curator in mode `branch-merge`) performs the merge per the autonomy mode — applying it and returning a short summary in `auto`, or returning a summary diff plus any items needing human resolution in `review`.

First-time bootstrap of the MARSHAIL knowledge layer. Delegate when the user asks to "bootstrap the knowledge layer", "initialize .marshail/knowledge/", "scan the repo and draft repo/ and domains/ knowledge files", "build initial INDEX.md files", "set up the knowledge tree from scratch", or when running marshail-init in a repo whose .marshail/knowledge/ is empty or near-empty. The subagent (curator in `init` mode) enumerates entrypoints, detects subsystems / domains, scans the code to the depth each area warrants, drafts the knowledge files, and generates indexes per the autonomy mode — writing them and returning a short summary in `auto`, or a summary diff for approval in `review`.

Maintain the MARSHAIL knowledge layer. Delegate when the user asks to "update the knowledge tree from this diff / commit range", "promote learnings from learn/inbox/", "rescan the knowledge tree", "refresh stale knowledge files", "split oversize topics", "sweep the knowledge layer", "update knowledge after this implementation cycle", "after the Learn stage promote inbox items into canonical files". Modes — `from-changes` (after an implementation cycle that changed code), `from-learning` (after the Learn stage), `rescan` (full sweep). The subagent (curator) updates topic files and indexes, splits oversize topics into sub-indexes recursively, respects autonomy mode, and returns a short summary of what changed (a full diff only in `review` mode).

Post-feature rebuild of the MARSHAIL knowledge layer. Delegate when the user asks to "rebuild the knowledge tree", "restructure domains/ after this feature", "re-derive subsystems / domains", "incorporate this feature branch into knowledge", "do a quarterly knowledge rebuild", "promote big structural changes into the knowledge layer". Use when a sizable feature lands that introduced new modules, removed modules, or significantly changed logic — heavier than maintain mode `rescan`. The subagent (curator in mode `rebuild`) re-runs init-style detection on HEAD and reconciles structure + content with the existing tree per the autonomy mode — applying changes and returning a short summary in `auto`, or a summary diff for approval in `review`.

Focused research on a topic, codebase area, or library, returning a condensed source-linked research note. Delegate when the user asks to "research X", "study how Y is wired up", "summarize the auth pipeline", "what does the Job table represent?", "deep-dive on this module", "answer this narrow question without polluting the main context", "find a fresh summary I can drop into the knowledge tree", "give me a research note I can promote later". Also delegate during the Analysis stage when repo-recon needs depth, during the Implement stage when an unknown surfaces, and any time another agent / skill suggests "research first" rather than guessing. Read-only — does not write to the knowledge tree.

MARSHAIL Learn / improve stage. Delegate when the user asks to "merge the phase learnings", "produce learning-rollup.md", "promote learnings into AGENTS.md / README / rules / skills / subagents / prompts / checklists", "draft a new rule from the learnings", "draft a new skill / subagent from the learnings", "promote durable items into the knowledge layer", "close the loop on this change", "what should we keep from this change?". Also delegate after the Rollout stage (or the PR stage if rollout was skipped) for any change with phase learning files worth promoting. The subagent merges and dedupes learnings, groups them into buckets, proposes per-bucket diffs (human-approved), and routes the knowledge bucket via marshail-knowledge-curator mode from-learning.

MARSHAIL Plan / shape stage — MANDATORY for every MARSHAIL change. Delegate whenever the user asks to "plan this change", "make a delivery plan", "produce delivery-plan.md", "shape the work", "break this into phases / packets / steps", "decide L1 / L2 / L3 / L4 depth", "decide PR boundaries", "decide rollout boundaries", "mark parallelizable work", "deepen the plan for phase X", "replan phase Y", or simply "let's plan". Also delegate at the start of any MARSHAIL change once the earlier stages (Specification through Architecture) are agreed (or skipped), and mid-change to deepen a previously high-level phase before its implementation cycle. The subagent picks the shallowest workable depth unless the user pins a target depth, and chooses a timing mode (full / staged / mixed).

MARSHAIL Review / PR / integration / merge stage. Delegate when the user asks to "open the PR", "compose the PR description", "do an AI review of this PR", "self-review before requesting human review", "review against delivery-plan.md and verification-report.md", "check the diff for plan alignment / test coverage / knowledge conflicts / risks", "handle review feedback", "convert review comments into plan FIXUP / CHANGED / ADDED entries", "promote the integration branch to main / release", "do the final review of the whole change". Also delegate any time a coherent integration boundary is ready and the Verify stage passed. The subagent composes the PR, runs structured AI review against the plan + knowledge layer, and converts feedback into plan updates rather than silent edits. Supports PRs that target an integration branch, with a final promotion round (Implement -> Verify -> Review / PR) into the release / main branch.

MARSHAIL Release / rollout stage. Delegate when the user asks to "draft the rollout note", "produce rollout-note.md", "list the toggles / properties / log changes / migrations / rollback path", "write the porting instructions", "list user-visible docs changes", "write a manual test scenario list for release", "what's the deploy plan?", "how do we roll this back?". Also delegate after merge (PR stage) or after the Verify stage if PR was skipped, for any change with operational impact. The subagent walks the change for operational shape and emits rollout-note.md.

MARSHAIL Specification / clarify stage. Delegate when the user asks to "spec out", "clarify", "frame", or "agree the intent of" a feature / bugfix / refactor / tech-debt prompt before any coding — or says things like "what exactly do you want me to build?", "let's pin down the requirements", "produce a specification.md", "ask me clarifying questions", "I have a vague idea, help me sharpen it", "list the open questions", "draft acceptance criteria". Also delegate when starting a new MARSHAIL change with an ambiguous prompt and the Specification stage is in scope. The subagent drives the clarification dialog (no assumptions, explicit disagreement, optional acceptance checklist) and writes specification.md.

MARSHAIL Verify stage — REQUIRED before any PR. Delegate when the user asks to "verify the change", "run the verification gate", "check requirements coverage", "audit the tests", "do Dev-QA", "produce verification-report.md", "is this ready for PR?", "check static / lint / typecheck / migrations / observability / security for this PR boundary". Also delegate automatically after each implementation cycle that fills a coherent PR boundary, and to re-verify after a fixup loop. The subagent walks every requirement, applies the Implement-stage testing strategy, runs Dev-QA where possible, and either passes (→ PR) or pushes back with plan updates (→ Implement).

Repo-specific playbook for adding a new HTTP endpoint to snippets-api. Delegate when the user asks to "add an endpoint", "expose a new route", "add POST/GET /snippets/...", or similar. Encodes this repo's route → service → db layering, error shape, and test expectations so a new endpoint is consistent with the existing ones.

MARSHAIL Analysis stage. Fallback skill for environments without subagent support. Triggers on "analyze the repo", "do code archaeology", "produce repo-recon.md", "find call-sites and integration points", "build a code map for this change", "what code is affected by this change?". Runs analysis inline in the current session.

MARSHAIL Architecture stage. Fallback skill for environments without subagent support. Triggers on "do the architecture step", "produce architecture-notes.md", "compare design options", "do a design conversation", "ADR-worthy decision", "draft an ADR". Runs architecture conversation inline in the current session.

MARSHAIL on-demand help. Fallback skill for environments without subagent support. Triggers on "how does MARSHAIL work?", "which skill / agent next?", "what stage am I in?", "explain the knowledge layer", "what does X stage do?", "MARSHAIL?". Answers procedural / conceptual questions about MARSHAIL inline in the current session — read-only.

MARSHAIL Implement stage. Fallback skill for environments without subagent support. Triggers on "implement the next phase", "do the next packet", "code this packet", "apply the plan", "drive the implement-verify-pr cycle", "write the code for delivery-plan.md phase N". Runs implementation cycles inline in the current session.

MARSHAIL Intake stage. Fallback skill for environments without subagent support. Triggers on "do intake", "produce change-brief.md", "frame this prompt as a change", "turn this idea / specification into a change brief", "what's the scope and risk?". Runs intake inline in the current session.

Reconcile MARSHAIL knowledge files diverged on two branches. Fallback skill for environments without subagent support. Triggers on "merge knowledge files from two branches", "resolve a knowledge conflict", "3-way merge knowledge frontmatter and bodies", "reconcile feature branch knowledge with trunk". Runs mode `branch-merge` inline in the current session.

First-time bootstrap of the MARSHAIL knowledge layer. Fallback skill for environments without subagent support. Triggers on "bootstrap the knowledge layer", "initialize .marshail/knowledge/", "scan the repo and draft repo/ + domains/ files", "build initial INDEX.md files". Runs init mode inline in the current session.

Maintain the MARSHAIL knowledge layer. Fallback skill for environments without subagent support. Triggers on "update the knowledge tree from this diff", "promote learnings from learn/inbox/", "rescan the knowledge tree", "refresh stale knowledge files", "split oversize topics", "update knowledge after this implementation cycle". Runs modes `from-changes` / `from-learning` / `rescan` inline in the current session.

Post-feature rebuild of the MARSHAIL knowledge layer. Fallback skill for environments without subagent support. Triggers on "rebuild the knowledge tree", "restructure domains/ after this feature", "re-derive subsystems / domains", "quarterly knowledge rebuild". Runs mode `rebuild` inline in the current session.

Focused research on a topic, codebase area, or library, returning a condensed source-linked markdown delta. Fallback skill for environments without subagent support. Triggers on "research X", "study how Y is wired up", "deep-dive on this module", "answer this narrow question without polluting context", "give me a delta I can promote to the knowledge tree later". Runs research inline in the current session — read-only.

MARSHAIL Learn stage. Fallback skill for environments without subagent support. Triggers on "merge the phase learnings", "produce learning-rollup.md", "promote learnings into AGENTS.md / rules / skills / agents / knowledge inbox", "draft a new rule / skill / subagent from learnings", "close the loop on this change". Runs learning rollup inline in the current session.

MARSHAIL Plan stage — MANDATORY. Fallback skill for environments without subagent support. Triggers on "produce delivery-plan.md", "plan this change", "break it into phases", "agree scope and depth (L1/L2/L3/L4)", "set timing mode (full/staged/mixed)", "do the planning stage". Runs planning inline in the current session.

MARSHAIL Review / PR / integration / merge stage. Fallback skill for environments without subagent support. Triggers on "open the PR", "compose the PR description", "do an AI review of this PR", "self-review", "review against delivery-plan.md and verification-report.md", "process review feedback as [FIXUP] / [CHANGED] / [ADDED] plan updates", "promote the integration branch to main / release", "final review of the whole change". Supports PRs that target an integration branch, with a final promotion round into the release / main branch. Runs PR composition + AI self-review inline in the current session.

MARSHAIL Rollout / release stage. Fallback skill for environments without subagent support. Triggers on "draft the rollout note", "produce rollout-note.md", "list toggles / properties / log changes / migrations / rollback path / porting instructions / user-visible docs / manual test scenarios". Runs rollout note authoring inline in the current session.

MARSHAIL Specification stage. Fallback skill for environments without subagent support. Triggers on "specify the change", "write a specification", "clarify requirements before building", "produce specification.md", "do the requirements clarification dialog", "I have a vague idea — help me sharpen it before planning". Runs the full specification dialog inline in the current session.

MARSHAIL Verify stage — REQUIRED before any PR. Fallback skill for environments without subagent support. Triggers on "verify the change", "run the verification gate", "produce verification-report.md", "is this ready for PR?", "do Dev-QA", "audit tests / static / lint / typecheck / migrations / observability / security for this PR boundary". Runs verification inline in the current session.

First-time MARSHAIL setup in a repository. Assumes scripts/install-marshail.sh has placed the durable assets under .marshail/ (and can run it if not); then does the repo integration the install needs judgment for — merging the MARSHAIL entry-point into the repo's AGENTS.md, scaffolding and populating the .agent-config/ config-sync source via marshail-promote-assets, running the cyncia sync, updating .gitignore, and offering the initial knowledge bootstrap. Idempotent.

Session bootstrap for MARSHAIL. Reads .marshail/ENTRYPOINT.md, .marshail/config.yml, the knowledge contract, the active knowledge implementation, and the root knowledge index, then reports a one-paragraph orientation so the agent can pick the right next skill with minimal extra context.

Runs the cyncia batch script (`sync-all`) to regenerate Cursor, Claude Code, GitHub Copilot, VS Code, JetBrains Junie, and Codex configuration from a generic source tree. Use when the user asks to "sync agent config", "regenerate rules/skills/agents/mcp", "update .cursor / .claude / .github / .junie / .vscode / .codex / .agents from source", "run sync-all", or similar — so they don't have to assemble CLI flags or pick Windows vs Unix scripts themselves. The skill detects the OS, finds the script, and infers `-i` / `-o` / `--tools` / `--items` / `--clean` from the natural-language request.

Delegates a side question to the `aside` subagent with a properly composed prompt so the main chat context stays clean. Use when the user says "ask aside", "side question", "delegate this", "run in a subagent", or otherwise signals they want the question answered in isolated context. Also use proactively when a request is clearly off the current work thread (research, lookups, "how does X work?") and would bloat the main context.

Write code comments like a pirate, but only in Java files.