Quick Start

Get up and running with lg5-spring-agent-os in your microservice repository. This guide will walk you through integrating the Agent OS so you can start leveraging its capabilities.

Prerequisites

• A Java microservice project based on the lg5-spring framework.
• Git initialized in your repository.
• An AI-powered coding assistant (e.g., OpenCode) configured in your environment.

Integration Steps

The bundle is consumed as a Git submodule mounted at .agent-os/ in your consumer repository. The submodule itself is the source of truth—artifacts are not copied. An installation script materializes a .opencode/ directory of relative symlinks that point back into .agent-os/, which is what your agent actually loads at runtime.

1. Add the Submodule

Navigate to the root of your microservice repository and run the following command to add the Agent OS bundle as a submodule.

By default, we use the HTTPS URL to avoid SSH authentication issues:

git submodule add -b main git@github.com:lg-labs-pentagon/lg5-spring-agent-os.git .agent-os

(Note: If you have SSH keys configured and prefer SSH, you can use git@github.com:lg-labs-pentagon/lg5-spring-agent-os.git instead).

This command tracks the main branch, which is suitable for development. For production, you should pin to a specific release tag.

2. Pin to a Specific Version (Recommended)

To ensure stability, check out a specific, tagged release. You can find the latest release version on the GitHub repository's releases page.

# Example for version v1.0.0
git -C .agent-os checkout v1.0.0

3. Run the Installation Script

The installation script wires the Agent OS into your local development environment by creating the necessary symlinks inside the .opencode/ directory.

.agent-os/scripts/install.sh

This script is idempotent, meaning you can safely run it multiple times. It will also add the .opencode/ directory to your .gitignore file to prevent the generated links from being committed.

4. Commit the Integration

Once the submodule is added and the installation script has been run, commit the changes to your repository. This records the Agent OS version your service depends on.

git add .gitmodules .agent-os .gitignore
git commit -m "chore(agent-os): [LG-89] Integrate lg5-spring-agent-os"

Keeping Agent OS Up to Date

Starting from v4.5.0, you can easily upgrade the Agent OS bundle in your repository using the built-in upgrade command. This is the recommended way to stay current with the latest stable features, rules, and skills.

The Upgrade Command

To update the .agent-os submodule to the latest stable tag (e.g., from v4.5.0 to v4.6.0) and refresh all symlinks in a single step, run:

.agent-os/scripts/install.sh --upgrade

What this does:

1. Fetches tags: Connects to the upstream repository to find the latest v* release.
2. Checkouts: Moves the .agent-os submodule to that latest tag.
3. Refreshes: Re-runs the installation logic to ensure all new skills, commands, and subagents are correctly linked in your .opencode/ folder.

After running the upgrade, remember to commit the submodule change:

git add .agent-os
git commit -m "chore(agent-os): upgrade bundle to latest release"

---

What's Next?

Your agent is now equipped with the full lg5-spring-agent-os!

You can now start using the Spec-Driven Development workflow. Try asking your agent:

Can you orchestrate the '001-loyalty-ledger' spec?

Or, for a new feature:

I want to create a new feature. Can you create an intent for 'user-profile-management' using /sdd-intent?

Explore the Reference sections to see the full list of available commands, skills, and rules.