Contributing to CGP with an Agent
Context-Generic Programming (CGP) is a Rust library for writing several implementations of a trait and choosing which one each type uses. This page is for contributors who want to change CGP itself with a coding agent's help. Your contribution might involve the library, the cargo-cgp toolchain, the agent skill, or the documentation. Before you start, you'll need to know the contribution policy and how to set up the repositories so your agent can follow their rules. This page walks through that preparation and explains how to report problems you find in the knowledge base. It assumes you already use an agent and have contributed to a Rust project through GitHub before.
Contribution policy
If an agent writes or changes code or documentation in your contribution, it must use the
CGP knowledge base. This requirement applies
to every CGP repository. Direct your agent to read the knowledge base, which is written for agents,
and to follow the AGENTS.md file of each repository it touches. These sources give it CGP's
vocabulary and current syntax, and tell it which documentation and skill updates to include with
your change.
The policy exists because an agent working from its training alone reproduces CGP's outdated syntax and invents semantics the knowledge base already records. How CGP's Documentation Is Written explains the problem and the process used to address it.
An AI-assisted pull request or issue must include the prompts used to produce it: the prompt that verified the issue, or the prompt that applied the fix. The CGP maintainers may run similar prompts themselves rather than merge a pull request directly, so the prompt can be as useful to them as the change.
The policy is deliberately light, and a more detailed one will follow. For now, it asks only that your agent use the knowledge base and that you include the prompts. You remain responsible for reviewing what your agent produces before you submit it.
Report problems in the knowledge base
Finding problems in the knowledge base is one of the most useful ways to contribute, and you can do it without setting up anything locally. Its checks can miss errors, so some documents still contain them, as its current state describes. When you find an error or an inconsistency between documents or between a document and the code, you save the project review work it would otherwise have to do itself.
File each problem on the knowledge base's issue tracker. Say which document is wrong, what it says, and what the source or another document shows instead. If an agent found or checked the problem, include the prompt you gave it, as the policy above requires.
Set up the repositories
Clone the CGP repositories next to each other under one parent directory. Their documents and rules
refer to each other by relative paths such as ../cgp, and some tests depend on that layout. Clone
the repositories your change touches, together with the knowledge base and the skill:
mkdir context-generic && cd context-generic
git clone https://github.com/contextgeneric/cgp.git
git clone https://github.com/contextgeneric/cgp-knowledge-base.git
git clone https://github.com/contextgeneric/cgp-skills.git
# as needed:
git clone https://github.com/contextgeneric/cargo-cgp.git
git clone https://github.com/contextgeneric/contextgeneric.dev.git
Some repositories have specific requirements for this layout:
- The skill. The CGP skill lives in
cgp-skills. A change to a construct must update the skill in the same contribution, so clone it besidecgp. - The
cargo-cgptests. Its UI test suite compiles fixtures against acgpcheckout at../cgp. Work on its compiler driver may also consult the Rust compiler's source, which itsAGENTS.mdexpects at../external/rust.
For the full list of repositories, including projects built with CGP, see the knowledge base's sibling-projects.md.
Follow the repository rules
Once the repositories are in place, have your agent read the AGENTS.md at the root of each one
it will work in. This should be the first file it reads in that repository. Each file gives the
repository's rules and names the guide to read for each kind of task, so your agent loads the
detailed instructions relevant to its work. In code repositories, it also points to the build and
test checks.
You can find these rules in the following repositories:
All of these repositories require you to include documentation updates in the same contribution as the change. The code is the authority, so the knowledge base, skill, and site must stay consistent with it. The updates you need depend on what you change:
- A change to a construct (its syntax, its expansion, its defaults, or its errors) updates the knowledge base's reference and implementation documents, the expansion snapshots, and the matching part of the agent skill.
- A change to
cargo-cgp's behavior updates the knowledge base'scargo-cgp/documents and the UI fixtures that pin the output. - A change to a page on this site updates the knowledge base's record of that page.
- A correction to a document starts in the knowledge base, then applies to the material written from it: the matching part of the skill and the page on this site adapted from it.
A contribution that spans repositories needs a pull request in each. Link them to each other so they can be reviewed together.
Before your agent starts, the rules ask it to load the CGP skill from
cgp-skills, so make that skill available in the
way your agent loads skills, as Installing the CGP Skill describes.
For prose, the rules also name the point-first-writing skill. That skill is optional and isn't
part of the CGP repositories, so your agent uses it only when it is available.
The rules also shape how the agent works with you. When a choice has more than one defensible answer, such as when the intended behavior is unclear, it stops and asks you. It also creates commits only when you ask, so you decide when the work is ready to commit and submit.
Use an established workflow
For common tasks, your agent can follow a complete workflow in the knowledge base. The cgp and
cargo-cgp repositories each point to one:
- Reviewing a macro. The
cgprepository's macro review workflow hardens one macro at a time by fixing bugs and corner cases, closing test gaps, checking spans and hygiene, and updating every view of the macro together. - Improving an error message. The
cargo-cgprepository's error-message loop reproduces a confusing diagnostic as a small test fixture before changing the tool, then confirms that the fixture's output improves.
Where to ask
Ask questions about a contribution in GitHub Discussions or on Discord. The author designs CGP's constructs and interfaces, so raise a change to a construct's design there before starting it. The Contribute page lists other ways to help CGP.
An AI agent wrote this page using the CGP knowledge base. See How AI is used in this project.