Skip to content

SPEC.md

Latest commit

 

History

History
164 lines (129 loc) · 5.71 KB

SPEC.md

File metadata and controls

164 lines (129 loc) · 5.71 KB
Raw

MARCHESE.md Specification (v1.0.0)

The Efficiency & Orchestration Contract Format

A MARCHESE.md file is a Markdown document with YAML frontmatter that declares context budgets, input compression rules, Minimum Viable Model (MVM) mappings, script bindings, gotchas, 4-block orchestration loops, session reminders, and human validation zones.

Canonical machine schema: packages/core/schema.json (mirrored at spec/schema.json and sdks/python/src/marchese_md/schema.json).

Equation

Compute Used = Tokens Consumed × Model Cost

Every Marchese control optimizes tokens, model tier, or both.

Frontmatter schema (summary)

---
marchese_version: "1.0"          # required, enum: "1.0"
name: my-agent-system            # required, ^[a-z0-9][a-z0-9-_]*$

efficiency:
  context_limit_tokens: 150000
  compact_threshold_percent: 60  # 10..90
  output_mode: concise           # concise | caveman | standard
  rtk_compression: true
  effort_level: medium           # low | medium | high
  claude_md_max_lines: 200

models:
  default_mvm: claude-haiku-4-5
  frontier_model: claude-sonnet-4-5
  task_routes:
    - task: parsing
      model: claude-haiku-4-5
    - task: architecture
      model: claude-sonnet-4-5
      fork_context: true

skills_config:
  ask_user_formatting: true
  scripts_dir: ./scripts
  init_templates: [nextjs]

gotchas:
  - id: GOTCHA-001
    title: ...
    issue: ...
    resolution: ...
    skill: optional-skill-id
    tags: [optional]

orchestration:
  loops:
    - name: feature-loop
      trigger: manual
      execution_skill: feature-builder
      verification_gate: npm test
      history_log: .history.jsonl
      training_mode: true
      max_iterations: 3

session_reminders:
  - day: friday                  # monday..sunday | daily
    message: Run marchese audit
    skill: optional

human_validation_zones:
  - name: production-deploy
    reason: High cost of error
    require_approval: true

knowledge:
  enabled: true
  root_dir: ./knowledge
  raw_dir: ./knowledge/raw       # ingested source material
  wiki_dir: ./knowledge/wiki     # curated TOC + pages
  sources: [repo, claude-md, marchese, history, gotchas, manual]

improvement:
  enabled: true
  loop_name: improve-system
  change_log: ./knowledge/change-log.md
  outputs_dir: ./knowledge/outputs
  protected_paths: [CLAUDE.md, knowledge/wiki, .claude/skills]
  auto_approve: [broken-wiki-link, missing-toc-entry, empty-raw-stub]
  sign_off_required:
    [new-skill-candidate, skill-edit, wiki-structural-rewrite, contradiction, bloat-removal]
---

Semantics

Token budget & context hygiene

  • CLAUDE.md should stay under claude_md_max_lines (default 200).
  • At compact_threshold_percent (default 60), agents should /compact or /clear.
  • RTK compression strips redundant whitespace/log noise from tool payloads.

Minimum Viable Model routing

Resolve order: exact task_routes → partial match → heuristic (lint/parse/test → MVM; architecture/security/plan → frontier) → default_mvm.

MVM routing

Gotchas ledger

Append-only edge-case memory. Unique id values required. Inject matching gotchas into skill context when symptoms reappear.

4-block orchestration loops

trigger → execution_skill → verification_gate → history_log

Training mode (default) records history without executing the shell gate. Pass --run-gate / runGate: true for live verification. History is append-only JSONL.

Middle-to-middle

Human frames the goal, agent executes the middle ~95%, human validates zones listed in human_validation_zones before high-risk mutations.

Middle-to-middle

Self-improvement lifecycle (BASE → UPLOAD → INFLOW → LOOP → DRIVE)

The knowledge block declares a self-seeded knowledge base (raw/ ingested material, wiki/ curated TOC) populated by marchese knowledge init && marchese knowledge ingest from the repo itself — no external data dump required. The improvement block declares the LOOP: marchese improve applies checked review items from the previous run, scans knowledge + repo, and buckets every proposal:

  • AUTO-APPROVE (kinds in auto_approve): applied directly, appended to change_log. Mechanically-resolvable stubs carry an autoFix (e.g. an empty raw/ file is deleted so it stops re-reporting).
  • NEEDS SIGN-OFF (kinds in sign_off_required): written to outputs_dir/review-*.md as checkboxes; applied only on the next run after the human checks them. If the proposal carries a stored autoFix, checking the box applies that edit (not just logs approval). Applied review files are retired to *.applied.md. protected_paths are never auto-modified for sign-off items.
  • MORE CONTEXT: written to outputs_dir/needs-context-*.md as questions.

Both auto_approve and sign_off_required accept any improvement kind, so a kind such as missing-toc-entry can be gated behind sign-off instead of applied automatically. Proposal ids are content-derived and stable across runs, so two coexisting review files never collide.

Self-improvement lifecycle

Tooling surface

Surface Commands / tools
CLI marchese validate, audit, init, optimize, gotcha, loop, status, rtk, route, knowledge, improve, image, models
MCP marchese_audit_context, marchese_validate_spec, marchese_mvm_route, marchese_run_loop, marchese_log_gotcha, marchese_write_history, marchese_ask_user, marchese_interview_user, marchese_codex_route, marchese_rtk_status, marchese_improve_system, marchese_knowledge
Python marchese_md parse, parse_marchese_spec, validate

Conformance

npm run test:fixtures

Fixtures live in spec/fixtures/valid and spec/fixtures/invalid.