Skip to content

docs: add AGENTS.md, contributing and development skills, issue forms and a concise README - #14

Merged
Sunrisepeak merged 5 commits into
mainfrom
docs/agents-md
Nov 21, 2026
Merged

Sunrisepeak merged 5 commits into
mainfrom
docs/agents-md

Conversation

@Sunrisepeak

Copy link
Copy Markdown
Member

Summary

Adds the repository's development rules for people and agents, with progressive disclosure: one short
rule file, procedures as skills, and the details in the documents they link.

  • AGENTS.md (100 lines): where a fact lives; who owns what (mcpp, backend, plugins, mcppls); the
    triage before a change (whose problem, core or plugin, fix or workaround, and what a workaround
    must state); versions (series X.Y, the backend always X.Y.0, the six version statements, tags,
    pins); build and test; code; the change workflow.
  • .agents/skills/mcpp-ide-contributing: triage, issues, branches, commits, pull requests, and the
    additional rules for AI agents (read before writing, ask before outward actions, report what ran,
    stay in scope, no attribution trailers).
  • .agents/skills/mcpp-ide-development: environment (pinned by .github/versions.env), tests per
    component, common changes (protocol, spec/, strings, fixtures, pins), diagnosing, release.
  • .github/ISSUE_TEMPLATE: bug, feature and task forms; blank issues disabled; questions to the
    forum, problems of mcpp and mcppls to their repositories. .github/pull_request_template.md.
  • README.md / README.zh-CN.md (103 / 100 lines, in parity): badges, one architecture diagram,
    an editors table, an installs table, a short convention and three prompts for agents, links.
    The detailed text they no longer carry moves to docs/versions.md; CLion's settings and graph
    notes remain in mide-plugins/clion/README.md.

Triage

n/a: documentation and repository forms only. No backend or plugin behaviour changes.

Criteria

  • bash .github/scripts/test_changes.sh passes locally, with new cases: the issue and pull-request
    forms and the skills are classified as docs (full=false, backend=false).
  • bash .github/scripts/release-plan.sh passes locally (one series 1.5).
  • Every relative link of the changed Markdown files resolves (checked locally).
  • The issue forms parse as YAML; their rendering is checked on GitHub after merge.
  • This PR changes .github/components.tsv, so CI runs every component; left to CI.

Compatibility

None for users or clients. Contributors get issue forms instead of blank issues.

For review

  • The skills are in English, like AGENTS.md and agents/skills.
  • Titles take <type>(<component>): <sentence>; no attribution trailers (as in mcpp).
  • The task label may not exist yet; GitHub leaves an absent label off.
  • The JetBrains badge links by the plugin's XML id; the numeric Marketplace id would be safer.

Checklist

  • One thing; the title is <type>: <sentence>.
  • Docs in both languages follow the change.
  • No generated file is edited.
  • No commit carries an attribution trailer.

… and a concise README

- AGENTS.md states the repository's rules in their shortest form and links to the full
  statements: where a fact lives, who owns what (mcpp, backend, plugins, mcppls), the triage
  before a change (whose problem, core or plugin, fix or workaround), versions, build and test,
  code and the change workflow.
- .agents/skills/mcpp-ide-contributing: triage, issues, branches, commits, pull requests and the
  rules an AI agent follows besides.
- .agents/skills/mcpp-ide-development: the environment, the tests of each component, common
  changes (protocol, spec/, strings, fixtures, pins), diagnosing and the release procedure.
- .github/ISSUE_TEMPLATE: bug, feature and task forms; blank issues are disabled, and questions,
  problems of mcpp and of mcppls are sent where they belong. A pull-request template.
- README.md and README.zh-CN.md: badges, the architecture in one diagram, one table of the
  editors and one of installs, prompts for agents, and links. What they no longer state is in
  docs/versions.md (series and tags, the project's mcpp, the test features by mcpp).
- .github/components.tsv: the issue and pull-request forms are documentation, so a change of
  them runs the documentation checks only (test_changes.sh holds the case).
…agents

- README.md and README.zh-CN.md draw the layers as a mermaid flowchart in place of the text
  drawing: mcpp's contract into the backend, the backend into the plugins and agents, mcppls into
  every editor.
- agents/README.md draws a session as a sequence diagram.
- docs/architecture.md gains three: a build end to end, a test run end to end (a test session or
  mcpp test), and the order in which a plugin finds the backend.
- Every diagram shares one palette that reads on light and dark backgrounds: indigo for mcpp and
  the backend, teal for the editors, amber for mcppls and notes, slate for lines and labels.
- The agent prompts are code blocks, each copyable, with the documents they rely on beside them.
… straight diagrams

- The README's agent section is one prompt: read AGENTS.md, then only what the task needs (install,
  understand, report an issue after triage, change the code); with no clear task, the agent says
  what mcpp-ide is and asks which direction, suggesting a first step for each, and it asks before
  any outward action.
- Editors and installs are one table, linking the Visual Studio Marketplace, Open VSX and the
  JetBrains Marketplace (plugin 35632), and mcppls's extension and CLion plugin (35609). The
  JetBrains badge links the plugin's page by its numeric id; its XML id gave 404. mcppls is a
  dependency of the VS Code extension, not an extension pack.
- The layers are one row with straight arrows: mcpp's contract into the backend, LSP both ways
  between the backend and the clients and between the clients and mcppls.
- Every diagram shares one palette: slate for what lies outside, indigo for the backend and the
  clients, amber for mcppls and notes; flowcharts draw linear edges.
- The README's diagram is layered: the clients on top, each editor (VS Code, CLion, Neovim) and
  agents a node of its own with its own connection; the backend, mcpp-ide serve, as the layer every
  decision lives in, with its parts (projects, jobs, view models, the rules of mcpp.toml); mcpp at
  the bottom, which the backend runs and whose contract it reads; mcppls beside it, whose status the
  backend asks and which reads mcpp's result record.
- Colour carries ownership: indigo for mcpp-ide, amber for mcppls, slate for mcpp. Flowcharts draw
  curves again.
- The README's diagram keeps its layers and drops what repeats: each client (VS Code, CLion, Neovim,
  agents) an arrow of its own into mcpp-ide serve, which runs mcpp under its contract and asks
  mcppls its status; the backend's parts and the repeated LSP labels are left to the text.
- Every diagram takes GitHub's Primer colours: blue for mcpp-ide (the backend solid), purple for
  mcppls, grey for mcpp; the sequence diagrams' actors, messages and notes follow them.
@Sunrisepeak
Sunrisepeak merged commit 5e98602 into main Nov 21, 2026
15 of 16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant