MARSHAIL v1.0.0

MARSHAIL v1.0.0

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

MARSHAIL = Method for AI-assisted Requirements and Software Engineering, with Human Approval and Incremental Learning.

The first stable release of MARSHAIL — a practical operating model for AI-assisted software delivery.
A change moves through explicit, optional-by-default stages, each producing durable artifacts that feed the next, with human approval gates where they matter and curated learning that feeds back into the system.

Highlights

• One canonical flow. Specification → Intake → Analysis → Architecture → Plan → Implementation round (Implement → Verify → Review/PR) → Rollout → Learn. Every stage emits explicit artifacts that the next stage consumes.
• Scales with the change. Only Plan is mandatory; every other stage is skipped when it would not add value — a typo and a risky feature run the same pipeline at different depths.
• The plan is the source of truth. delivery-plan.md is authoritative; an agent's built-in "plan mode" is only a scratchpad for shaping it.
• Human approval gates that are never bypassed, even in autonomous modes.
• Agent-managed knowledge layer that captures durable repo facts across changes and narrows future code searches.
• Curated learning that promotes only generalizable lessons back into rules, skills, agents, and knowledge.

What's included

The process spec

• marshail.md — the canonical specification and single source of truth for the method: the artifact chain, the 4-level plan hierarchy, status markers, parallelism tags, the implementation round and implementation cycles, replanning rules, and the full stage lifecycle.

Stages and artifacts

The full per-change artifact chain lives in a transient, gitignored working folder under .marshail/work/<change-id>/, with a logs/ resume contract so any session can pick up from disk.

Stage	Artifact	Required?
1. Specification	specification.md	optional
2. Intake	change-brief.md	optional
3. Analysis	repo-recon.md	optional
4. Architecture	architecture-notes.md	optional
5. Plan	delivery-plan.md	mandatory
6. Implementation round	code, implementation-report.md, verification-report.md, PR	per change
7. Rollout	rollout-note.md	optional
8. Learn	learning-rollup.md, knowledge updates	optional

Agents and skills

Each stage is owned by a marshail-* subagent (the single source of truth for that role), with matching skills: a marshail-delegate-to-* wrapper for tools with subagent support, and a full inline marshail-* fallback for tools without it.

• 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 across all modes) and marshail-researcher (read-only, source-linked deep dives).
• Orchestration / help: marshail-driver (runs the process end to end) and marshail-helper (procedural and conceptual questions).

Communication models

Two supported ways to drive MARSHAIL, mixable across a change:

1. Direct — call a specialist agent (or its marshail-delegate-to-* skill) for a single stage.
2. Driver-mediated — talk only to marshail-driver as a single point of contact, from hands-off to collaborative.

Knowledge layer

An agent-managed knowledge tree under .marshail/knowledge/, loaded through progressive disclosure (always-loaded root index → per-folder indexes → topic files), kept in sync after each implementation cycle, and used to narrow code searches. The representation is exchangeable: the general contract lives in knowledge-contract.md and the default implementation, MARSHAIL Markdown Spine, in knowledge-markdown-spine.md.

Installation and config sync

• scripts/install-marshail.sh — idempotent installer that fetches the marshail-files/ subtree into .marshail/, installs cyncia if missing, runs the sync when an .agent-config/ source tree is present, and records the installed ref in .marshail/VERSION.
• The marshail-init skill owns repo integration: merging the MARSHAIL entry-point into AGENTS.md, wiring durable assets into .agent-config/, updating .gitignore, and offering the initial knowledge bootstrap.
• Durable assets fan out to native AI-assistant layouts (Cursor, Claude Code, GitHub Copilot, VS Code, JetBrains Junie, Codex, …) via cyncia.

Extensions

Repo-specific extensions (mx--prefixed rules, skills, and agents) live under .marshail/extensions/ and survive MARSHAIL upgrades, drafted by marshail-learner or by hand.

Examples

A worked example under examples/snippets-api/ shows what a consumer repo looks like with MARSHAIL installed — a filled-in knowledge tree, an ADR, and repo-specific extensions.

Install

From the root of your target repo:

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

Then run the marshail-init skill once to integrate MARSHAIL into the repo.

License

MARSHAIL is licensed under the MIT License.