crestreach / marshail

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

MARSHAIL (pronounced MAR-shuhl, /ˈmɑːr.ʃəl/) = Method for AI-assisted Requirements and Software Engineering, with Human Approval and Incremental Learning. A single canonical flow moves a change through explicit, optional-by-default stages, each producing durable artifacts that feed the next, with human approval gates at the points that matter and curated learning that feeds back into the process.

View on GitHub Get install command

The flow

  • Specification
  • Intake
  • Analysis
  • Architecture
  • Plan
  • Implementation
  • Rollout
  • Learn

The Plan stage is mandatory; every other stage is run when it would add value. Scale the pipeline with the change.

Why it exists

AI can write code quickly, but unguided AI-assisted work fails in predictable ways. MARSHAIL counters each failure mode with a single canonical flow recorded as artifacts a human can inspect and approve. The result is human-approved AI software engineering wrapped in a curated learning loop that closes after every change, so the loop gets sharper as the work continues.

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.

Principles

The ideas that hold the whole flow together.

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.

Curated, agent-managed learning

Each phase emits generalizable lessons; durable ones are promoted into rules, skills, agents, and knowledge.

The process

A change moves through explicit stages, each producing a durable artifact. The whole per-change artifact chain lives in .marshail/work/<change-id>/.

Inside Implement, work runs in small implementation cycles, and 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.

Stage Purpose Artifact Required?
1. Specification Clarify what is being asked specification.md optional
2. Intake Frame the change and its acceptance criteria change-brief.md optional
3. Analysis Targeted recon of the affected code repo-recon.md optional
4. Architecture Shape the solution when it is not obvious architecture-notes.md optional
5. Plan The canonical plan for the change delivery-plan.md mandatory
6. Implementation round Implement → Verify → Review/PR, once or per phase code, implementation-report.md, verification-report.md, PR per change
7. Rollout Release / migration notes rollout-note.md optional
8. Learn Promote generalizable lessons learning-rollup.md, knowledge updates optional

Knowledge layer

MARSHAIL pairs the process with an agent-managed knowledge layer under .marshail/knowledge/. Where the artifact chain captures this change, knowledge captures durable facts about the repo.

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, then loaded through progressive disclosure from an always-loaded root index 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; the default is the MARSHAIL Markdown Spine.

Agents and skills

Each stage is owned by a marshail-* subagent, the single source of truth for that role, with matching skills that match user intent and dispatch the work. When a subagent-spawn tool is available, stage agents are always launched as real, fresh-context subagents, never emulated inline.

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 the process end to end
  • marshail-helper - procedural and conceptual questions

Two ways to drive it

Direct - call a specialist agent 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.

Install

From the root of your target repo, run the install script. It is idempotent, so re-run it any time to update. 

curl -fsSL https://raw.githubusercontent.com/crestreach/marshail/main/scripts/install-marshail.sh | bash

What the script owns

Installation - fetching and updating .marshail/ (including marshail.md) and the repo-root LICENSE, reconciling config.yml, recording VERSION, and installing cyncia if it is missing.

What marshail-init owns

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

Your knowledge tree, per-change work tree, marshail-override.md, your per-agent tool grants in agent-tools.yml, and your per-agent model assignments in agent-models.yml are never overwritten. Run with --help for options (--ref, --marshail-dir, --agent-config, --no-cyncia, --no-sync).

Contact

LinkedIn: artur-olszak

License

MIT.