MARSHAIL v1.0.1

MARSHAIL v1.0.1

Deeper, code-derived knowledge with a tunable scan depth.

A focused patch release that makes the MARSHAIL knowledge layer a real, code-derived artifact rather than a thin per-module snapshot transcribed from existing docs.
The point of the knowledge layer is to cache hard-won understanding of a repo so future changes don't pay for the same code scan twice — this release makes that cache earn its keep.

What changed

• Knowledge is now code-derived.
  init and rebuild read the system from its entrypoints inward, verify every claim against the actual code, and cache the result — so the knowledge layer can save future costly code scans instead of restating existing docs.
• Depth is decided locally.
  Each area expands to whatever depth it warrants, decided per node, with multiple levels expected for genuinely complex components, algorithms, and end-to-end flows; trivial areas stay shallow.
• New knowledge.scan_depth knob (shallow / standard / deep).
  It sets the baseline for how far a scan expands beyond a flat per-subsystem map; the local per-node depth decision still applies on top. Wired into the installer's config reconcile schema, so existing installs pick it up on upgrade. Defaults to standard.

Where it landed

• knowledge-contract.md — code derivation and locally-decided depth are now required, representation-agnostic goals of any knowledge implementation.
• knowledge-markdown-spine.md — new Depth and code derivation section, required repo_paths for code-derived topics, a deepened illustrative layout, and stronger init / rebuild update paths.
• marshail-knowledge-curator.md — depth/derivation policy, context-safe delegation by judgment, and rewritten init / rebuild / rescan workflows.
• config.yml and install-marshail.sh — the knowledge.scan_depth knob and its installer reconcile entry.
• marshail.md — carries the concept in the canonical spec; the mechanics stay linked in the references.

Upgrade notes

No breaking changes.
Re-run the installer to pick up the new knowledge.scan_depth property — it defaults to standard, preserving prior behavior.
Choose deep for large or complex repos where re-scanning the code later is expensive, or shallow for small repos and quick first passes.

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.

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.