Human-approved AI software engineering with a curated learning loop.

Without a process

• Context gets polluted by broad, unfocused searches.
• Coding starts before the change is framed.
• Plan and code drift until the plan is fiction.
• Review feedback is ad-hoc and inconsistent.
• Lessons are lost, or overfit to a single case.

With MARSHAIL

• Focused code analysis instead of broad searches.
• Structured planning before controlled execution.
• Explicit verification and review discipline.
• Release discipline at integration boundaries.
• Curated learning promoted into durable rules and knowledge.

One canonical flow

Every stage emits explicit artifacts, durable context that the next stage consumes.

The plan is the source of truth

An agent's built-in "plan mode" is only a helper; delivery-plan.md is authoritative.

Scale with the change

Skip stages for a typo; run the whole pipeline for a risky feature. The Plan stage is mandatory; the rest run when they add value.

Small, reviewable slices

Small slices by default; larger PRs only at integration boundaries.

Human approval gates

Approval gates where they matter, never bypassed, even in autonomous modes.

Close the feedback loop

An agent that produces something runs it (tests, build, the code, the app, the UI flow) and verifies its own result before handing back; human verification covers only what the agent genuinely cannot reach.

Curated learning

Each phase emits generalizable lessons only; durable ones are promoted into rules, skills, agents, and knowledge, and case-specific noise is dropped.

Agent-managed knowledge

A durable, agent-maintained memory of repo facts, rationale, and decisions that also narrows future code searches.

Implementation cycles

Inside Implement, work runs in small implementation cycles. The human can inspect intermediate results and give feedback at any cycle, folded back into the work (and the plan, when it changes scope) before the cycle closes.

Integration branches

A PR may target the final branch directly or an integration branch; in the latter case a final round (Implement → Verify → Review/PR) promotes the integration branch to the release / main branch and reviews the change as a whole.

Run logs as a cross-run cache

Each agent keeps its own run log in the working folder: the history of what it did plus cached research, findings, and decisions, so the next fresh-context run can read them instead of repeating the work. The price of isolated contexts is paid once, not per run.

Drops the stages, not the discipline

Every task in a round (research, coding, tests, checks, reviews) still runs in its own fresh context and only the needed result comes back; knowledge is used and kept in sync; every round's result is verified by the agent that produced it; and a PR coming out of a session is still preceded by Verify.

Logged and resumable

The session is logged under .marshail/work/wb-<date>-<slug>/ (workbench-session.md, resume.md with Mode: workbench) and can be picked up again later.

Promote or detour

A session can be promoted into a staged change when it outgrows a session, and a staged change can hand a stretch of exploratory rework to a session as a detour, recorded in the plan and folded back when the session ends.

Durable repo facts

Architecture, logic, conventions, and decisions that survive across changes, derived from the code itself, scanned from the entrypoints inward and analyzed as deep as each area needs (a trivial module stays one short topic; complex areas expand into deeper, multi-level nodes), so agents don't re-scan the same code each time. Loaded through progressive disclosure from an always-loaded root index, via per-folder indexes, down to topic files.

Kept in sync, used to narrow searches

Synchronized after each implementation cycle and used to narrow code searches instead of re-deriving the same facts every time. The representation is exchangeable: a general knowledge contract, and a default implementation, the MARSHAIL Markdown Spine, split into a short reading guide every agent loads and a maintenance guide only knowledge-maintaining agents load.

Stage agents

• marshail-specifier
• marshail-framer
• marshail-code-archaeologist
• marshail-architect
• marshail-planner
• marshail-implementer
• marshail-verifier
• marshail-reviewer
• marshail-releaser
• marshail-learner

Knowledge

• marshail-knowledge-curator - maintenance in all modes
• marshail-researcher - read-only, source-linked deep dives

Orchestration / help

• marshail-driver - runs a staged change end to end
• marshail-workbench-driver - interactive orchestrator of a workbench session, round by round
• marshail-helper - procedural and conceptual questions

Main-session skills

• marshail-init
• marshail-load
• marshail-promote-assets
• marshail-drive and marshail-workbench - run the two conversational roles inline when you are not already in a direct session with them (and ask first when the intent is unclear)
• marshail-delegate-to-driver - spawns the driver only for a hands-off end-to-end run (no-subagent fallback: marshail-drive-end-to-end)

How an agent runs

As the session agent (you select it as your chat agent and talk to it directly, fully interactive), as a subagent (spawned for a bounded task; runs to completion and returns a result, cannot talk to you), or inline (your chat agent follows the agent's file itself).

Spawn for bounded tasks, never for a conversation: the conversational roles (marshail-driver, marshail-workbench-driver, and the implementer in collaborative cycles) belong in a direct session or inline; task roles are spawned. Switching between the driver and the workbench driver is a session handover (state on disk plus a one-line prompt), not a spawn.

Two ways to drive a staged change

Direct - call a specialist agent (or its marshail-delegate-to-* skill) for a single focused stage when you know the process.

Driver-mediated - talk only to marshail-driver as a single point of contact; it coordinates the specialists and keeps you oriented, from hands-off to collaborative, inferred from your prompt and the autonomy setting and adjustable at any stage boundary. The two can be mixed.

For iterative, plan-less work, talk to marshail-workbench-driver round by round instead; see Workbench mode.

What the script owns

Installation - fetching and updating .marshail/ (including marshail.md) and the repo-root LICENSE, reconciling config.yml (defaults on a fresh install; on an update, new properties are added and your existing values are left alone), recording VERSION, installing cyncia if it is missing (committed into the repo, not a git submodule), and running the cyncia sync when an .agent-config/ source tree is present.

What marshail-init owns

Repo integration - merging the MARSHAIL entry-point into your AGENTS.md, wiring durable assets into .agent-config/ via marshail-promote-assets, updating .gitignore, and offering the initial knowledge bootstrap. Run the script first, then marshail-init once.