Publish an agent integration guide and workflow examples #8

Activity

1. adrianbrowning

   marked this as blocked by 4 issues on Aug 8, 2026

   • Add a versioned machine-readable CLI contract for agents #5
   • Harden mdcode operations for untrusted Markdown and agent execution #7
   • Define the canonical npm package identity and align metadata #3
   • Add plan, diff, apply, and check workflows for agent-driven sync #6
2. adrianbrowning

   marked this as blocking on Aug 8, 2026

   • Expose mdcode as typed MCP tools for LLM agents #9
3. adrianbrowning commented on Aug 8, 2026

   

   adrianbrowning

   on Aug 8, 2026

   OwnerAuthor

   More actions

   This was generated by AI during triage.

   Agent Brief

   Category: enhancement
   Summary: Publish a portable, copyable guide for coding agents that use mdcode safely in repository workflows.

   Current behavior:
   The repository has internal agent-process documentation only. It has no user-facing guide that explains the mdcode workflow, safety boundaries, installation, or machine-readable results to a coding agent working in an arbitrary consumer repository.

   Desired behavior:
   A standalone guide can be copied into an agent skill or repository instruction. It teaches agents to inspect first, produce a plan, review a diff, apply explicitly, and verify synchronization. Examples use the canonical @gcmdev/mdcode identity and only describe finalized public behavior.

   Key interfaces:

   • Agent workflow — inspect named blocks, obtain a non-mutating plan, review a diff, apply explicitly, and use check for freshness verification.
   • Extraction and region synchronization examples — demonstrate accurate public CLI invocations without repository-specific paths or tools.
   • Targeted selection — use stable block names from issue Add stable block identities and robust metadata syntax #16.
   • Safety model — distinguish safe inspection and planning from writes and shell execution; state when explicit approval, --apply, or --allow-shell is required.
   • Machine-readable results — show how an agent consumes the versioned JSON contract without parsing human output.

   Acceptance criteria:

   • The guide describes inspect, plan, diff, apply, and verify steps using the public CLI contract.
   • It includes concise, correct examples for extraction, region synchronization, freshness checks, and --name selection.
   • It documents the trusted-input model, allowed-base behavior, and when human approval or explicit flags are required.
   • Installation and import examples consistently use @gcmdev/mdcode.
   • The guide is self-contained enough to serve as a reusable agent skill or project instruction.
   • Every example is checked against the current public CLI and JSON contract.

   Out of scope:

   • A VS Code extension, editor diagnostics, or a runtime agent framework integration.
   • Repository-specific CI configuration.
   • Redefining the package identity, JSON response contract, sync workflow, or security rules.

   Verification status:
   Confirmed: no user-facing agent integration guide exists. This issue remains blocked by #3, #5, #6, and #7.
4. adrianbrowning

   added

   enhancementNew feature or requestNew feature or request

   ready-for-agentFully specified and ready for an AFK agentFully specified and ready for an AFK agent

   on Aug 8, 2026