MelozWrite

Project kits · spec, plan, article, memo, review, status

How agents and humans share a project.

MelozWrite is not a chat pad. A Project is a durable markdown kit — specs, plans, articles, memos, reviews, or weekly status — plus MCP tools for bots and a portal where humans edit and approve. This page is the full loop.

1. What a structured Project is

A Project is a living markdown kit — an overview plus focused sections — not a chat transcript. Specs, plans, articles, memos, reviews, and weekly status share the same outline shape:

My Plan/
  SPEC.md
  sections/
    goal.md
    timeline.md
    risks.md

SPEC.md is the spine. Everything else lives under sections/. The store is the Project itself. Signed-in users get a demo Project to try the loop.

2. How an agent connects

MCP is the capability contract. The MelozWrite skill is the behavioral contract. Every tool run is bound to one signed-in account or agent workspace.

  • Human: Gearu Hosted UI (https://auth.gearu.biz) → httpOnly session → POST /api/mcp. Agents can also send a Cognito JWT as Bearer.
  • Agent: opaque or HMAC API key plus required X-Agent-Id on POST /mcp. Keys cannot switch workspaces.
  • Schema list GET /mcp/tools is public. No handler runs without auth.
  • project_list
  • project_create
  • project_open
  • structure_get
  • section_read
  • section_write
  • suggest
  • await_hitl
  • credits_summary

3. Tool sequence

Agents read, then propose. Humans decide. Writes happen on approve or an explicit section_write with apply: true.

  1. 1 · project_create / project_list

    Create or list

    Create a spec, plan, article, memo, review, or status in this workspace, or list the caller's projects only.

  2. 2 · project_open

    Open the project

    Open a project by id (or matching owner/repo). Missing and foreign ids share the same access-denied error.

  3. 3 · structure_get

    Walk the outline

    List the overview and section files. Titles come from the first heading or the file name.

  4. 4 · section_read

    Read a section

    Load one kit path. Path escape is path_forbidden. The agent does not get a raw filesystem path.

  5. 5 · suggest

    Propose a change

    Draft markdown and persist a pending HITL proposal. Kit files stay unchanged. Live calls cost 1 credit.

  6. 6 · HITL approve

    Human gate

    A signed-in human reviews /app/hitl. Approve writes the section. Reject does not. Agents cannot decide.

  7. 7 · section_write / credits_summary

    Apply and meter

    Approve already writes. If the human never used the inbox, section_write apply:true is the explicit write. credits_summary is the workspace credit ledger.

Loop
flowchart TD
  A[Agent or human] --> L[project_list / project_create]
  L --> B[project_open]
  B --> C[structure_get]
  C --> D[section_read]
  D --> E[suggest]
  E --> F[Pending proposal JSON]
  F --> G{Human in /app/hitl}
  G -->|Approve| H[Kit markdown written]
  G -->|Reject| I[Kit unchanged]
  D --> J[Portal editor]
  J -->|Save apply:true| H
  J -->|Propose apply:false| F
  E -.->|live model: 1 credit| K[credits_summary]
  A --> K

Mermaid source for the same loop. The cards above are the rendered explanation — tools are not invented.

After suggest, the agent polls await_hitl with the proposalId. That call is a short status check, not a long-poll. If pending is still true, wait and call again.

4. How specs are used downstream

  • Living outline. structure_get is the map agents and the portal share. New sections stay markdown in sections/.
  • Requirements sections. Humans keep requirements, risks, and notes in focused files. The editor saves them; agents propose diffs against the same paths.
  • HITL as gate. Pending proposals wait in the inbox. Nothing from a bot lands in the kit until a human approves.
  • Credits as meter. Only live model suggest spends. Fixture drafts stay free so the loop can be taught offline.

5. Try it

  1. Sign in with Gearu identity.
  2. Open /app and enter the demo project.
  3. In the editor, change a section and Save — or enter a prompt and Suggest.
  4. Approve or reject in /app/hitl.
Sign inPortalPortal How-to