Up-to-Date Docs with Agentic Automation

At Medusa, we’ve continuously built tools to automate different areas of our documentation. That includes API references, OpenAPI spec generations, and some how-to guides and tutorials. These tools saved us time and resources, and ensured our users have reliable documentation.

Our latest addition to this tooling is a documentation agentic automation that keeps Medusa’s docs in sync with code changes across our products. It detects documentation-relevant code changes, determines which documentation projects are affected, and makes the updates automatically.

This automation solves a long-standing problem that teams face ensuring the documentation isn’t stale as products rapidly change. It aligns with our broader mission to build the most AI-native commerce platform in the market, which is supported by previous initiatives and projects such as Bloom, agentic skills, and more.

Docs Setup Overview

Our documentation covers different products in our ecosystem. In the context of the agentic automation system, our products can be put into two categories:

• Medusa’s core and open source products. The codebase is stored in the medusajs/medusa repository alongside the documentation. So, our agentic flow can access both the code and documentation at once to decide what changes are needed.
• Medusa Cloud. The codebase is hosted in a separate, private repository. So, our agentic flow needs to be handle the distributed nature of the source code and documentation to decide on the changes needed.

To automate products falling into both categories, we added two separate pipelines that rely on the same tooling that analyzes changes to update the necessary documentation.

Automation for Medusa Core Docs

The documentation automation for Medusa’s core open source is straightforward since the docs live in the same repository. We built the following flow within a GitHub action that is triggered whenever a change is merged:

1. Analyze the commit for doc-relevant files. It checks services, models, workflows, and more for user-facing changes.
2. Identify the documentation project and area that needs to be updated. For example, a new CLI option means the CLI reference needs to be updated, whereas a change in the admin dashboard requires updating the user guide.
3. Pass the changes to Claude Code with instructions on how to make documentation changes. We added a Copy to clipboard/writing-docs skill that covers our documentation structure, conventions, constraints, and more.
4. Open a pull request with the changes made to the documentation.

Our documentation team reviews the pull request and can merge it when the next release is live.

Automation for Medusa Cloud Docs

Automating the documentation for Medusa Cloud is more complex since the source code and documentation live in different repositories. So, we built a flow that spans across systems.

When a new Medusa Cloud deployment is triggered, we run the following flow in the Cloud repository:

1. Retrieve all commits since the last deployment and filter out user-facing changes only.
2. Run Claude Code to translate these changes to natural language that another agent can use to make the documentation changes. For example, if we add a new button, Claude Code will specify where this button is added, what happens if a user clicks it, and any other user relevant changes.
3. Trigger the documentation automation action in the core Medusa repository where the documentation lives, passing it Claude Code’s summary.

Then, the action in the core Medusa repository runs the next flow:

1. Pass the natural-language changes to Claude Code with instructions on how to make documentation changes. It uses the same Copy to clipboard/writing-docs skill from the previous flow.
2. Open a pull request with the changes made to the documentation.

Similarly, our documentation team reviews the changes and merges them to put the documentation changes live.

Result: Automated Documentation Changes

With these flows in place, we now have automated pull requests that make changes to the documentation as necessary. These changes follow our guidelines for writing documentation, making the review process easier and avoiding AI slop.

This automation ensures our users always have documentation that is up-to-date with product releases, which is essential to provide a great developer and learning experience.

View Automation Flow

Our documentation automation flow is part of our open source repository. It relies on a docs-automator tool that is part of our documentation toolkit. This tool handles analyzing made changes for both flows, and drafting the prompt for Claude to make the necessary changes.

Get Started with Medusa

If you're new to Medusa, check out the documentation, where you'll get a more in-depth understanding of what Medusa is, the commerce features it provides, and how to deploy Medusa to Cloud.