Repository navigation
Publish an agent integration guide and workflow examples #8
Description
Activity
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.
What to build
Publish a copyable agent integration guide that teaches coding agents how to use mdcode safely and predictably in a repository workflow.
Acceptance criteria
Blocked by