Monospecs Multi-Repository Management Guide

Overview

Monospecs is a multi-repository management solution provided by HagiCode. It tracks and manages multiple sub-repositories through the monospecs.yaml configuration file. This solution can be applied to any project that needs unified management of multiple independent repositories.

Core Concepts

Configuration File

monospecs.yaml is the core of the entire management solution, defining:

• List and location of sub-repositories
• Git URL for each repository
• Display name and icon
• Integration behavior with OpenSpec

Differences from Regular Repositories

Feature	Regular Repository	Monospecs Managed Project
OpenSpec Location	Root directory’s openspec/	Main repository root directory’s openspec/
Change Scope	Limited to current repository	Can involve multiple sub-repositories
Sub-repository Purity	Specs mixed with code	Specs established in main repository, sub-repositories are cleaner
Archive Auto-commit	Needs manual spec commits	commit_when_archive: true automatically commits specs to main repository

Why Use Monospecs?

• Unified Management: Manage all sub-repositories in one configuration file
• Automation Support: Provides repository metadata for scripts and tools
• AI Friendliness: Structured configuration helps AI Agent understand repository relationships
• OpenSpec Integration: Seamless integration with the change management workflow
• Cleaner Sub-repositories: Specs are kept in main repo, sub-repositories only contain actual code

Applicable Scenarios

Monospecs is particularly suitable for the following scenarios:

1. Multi-Repository Collaborative Development When a project is split into multiple independent repositories:

• Frontend application, backend service, and desktop app developed separately
• Need to coordinate versions and dependencies across repositories
• Documentation and helper projects separate from main code

2. Auxiliary Project Management Use Monospecs to manage:

• Documentation project
• Official website
• Build tools and scripts
• Each repository maintains its own version control

3. Cross-Repository Feature Development A feature that requires changes across multiple repositories:

• Need to track changes in which repositories
• Automatically commit specs to correct target repository
• Coordinate version updates and dependencies

Quick Start

Initialization

Follow these steps to complete monospecs initialization:

1. Create Empty git Repository

Create an empty git folder in your main repository (note: this is git, not repos/ - this is the monospecs convention):

mkdir git
cd git
git init
cd ..

2. Configure monospecs File

Create the monospecs.yaml configuration file in your main repository root directory:

version: "1.0"
commit_when_archive: true

repositories:
  - path: "repos/frontend"
    url: "https://github.com/your-org/frontend.git"
    displayName: "Frontend App"
    icon: "🌐"

  - path: "repos/backend"
    url: "https://github.com/your-org/backend.git"
    displayName: "Backend Service"
    icon: "⚙️"

Configuration Items:

Configuration Item	Type	Required	Description
version	string	Yes	Configuration file version
commit_when_archive	boolean	No	Whether to auto-commit specs when archiving (don’t commit sub-repo code)
repositories	array	Yes	Repository configuration list
repositories[].path	string	Yes	Repository path (relative to project root)
repositories[].url	string	Yes	Git repository URL
repositories[].displayName	string	No	Repository display name
repositories[].icon	string	No	Repository icon (emoji)

Add Sub-Repositories to Main Repository

Add all sub-repositories to the repos/ directory. This directory must be excluded from the main repository’s Git version control to avoid tracking sub-repository content:

# Exclude all sub-repositories
repos/

3. Add Parent Repository to HagiCode

If you use the HagiCode desktop application, open the app and add your main repository as a project. Click the “Add Project” or ”+” button on the home screen, select your main repository folder, and you will see all sub-repositories and their status information.

4. Clone Sub-Repositories

Use the monospecs.yaml configuration to clone all configured sub-repositories to the repos/ directory:

This will clone all sub-repositories based on the URLs specified in the configuration file.

Configuration File Structure

Root Level Configuration

version: "1.0"
commit_when_archive: true

repositories:
  # ... repository configurations

Repository Level Configuration

Each sub-repository can have:

• OpenSpec change folder (openspec/)
• Independent .git/ directory
• Optional AGENTS.md for AI Agent configuration

Repository Management Operations

Add New Repository

When adding a new sub-repository to the monospecs.yaml repositories array:

repositories:
  - path: "repos/new-service"
    url: "https://github.com/HagiCode-org/new-service.git"
    displayName: "New Service"
    icon: "🆕"

Update Repository Configuration

When repository URLs or metadata change:

1. Edit monospecs.yaml to update corresponding entries
2. Verify YAML syntax is correct
3. If syncing changes, manually update local repository configuration

AI Agent Configuration Support

AGENTS.md

The AGENTS.md file provides repository-specific guidance for the AI Agent:

Technical Stack Information

• Framework and build tools
• Code conventions and naming practices
• Version management and deployment configuration

Project-Specific Behaviors

• Configuration extensions and special requirements
• OpenSpec integration patterns
• Cross-repository coordination needs

AI Benefits

Using AGENTS.md enables the AI Agent to:

• Understand repository relationships and dependencies
• Generate code and refactor across multiple repositories
• Maintain consistency in version control and configurations

OpenSpec Integration

How Monospecs Works with OpenSpec

Whether managing a monospecs managed project or a regular repository, you can use HagiCode’s OpenSpec workflow:

Regular Repository:

• OpenSpec in root openspec/ directory
• Changes only affect current repository

Monospecs Managed Project:

• OpenSpec reads monospecs.yaml configuration
• Changes tracked by sub-repository
• Specs automatically committed to correct targets

Archive Behavior

When commit_when_archive: true:

• Specs are automatically committed to the main repository
• Sub-repositories’ code is not committed (remains separate)
• Simplifies specs management - no manual spec commits needed for sub-repositories

Manual Sub-Repository Commits

Sub-repositories maintain independent version control:

• Commit actual code changes to their own repositories
• Specs are committed separately (from main repository when archiving)

Best Practices

Repository Naming Conventions

• Use kebab-case (lowercase letters and hyphens) for repository paths
• Use simple, descriptive display names in Chinese
• Use relevant emojis as icons

Display Name Guidelines

• Keep it concise and descriptive
• Use consistent naming across similar repositories
• Select icons that represent the repository’s purpose

Configuration Maintenance

Sync Configuration with Actual Status

• Regularly verify monospecs.yaml reflects actual repository structure
• Update or remove entries when repositories are added or removed
• Test changes to ensure configuration validity

Version Control for Configuration

• Track configuration file changes with git
• Document reasons for major configuration changes
• Tag configuration file versions for easy rollback

Troubleshooting

Configuration File Not Found

If the monospecs.yaml file is not found in the project root:

1. Check if the file exists in the correct location
2. Verify you’re in the correct working directory
3. Check for typos in the configuration file name

YAML Syntax Errors

Common YAML syntax issues:

• Incorrect indentation (use spaces, not tabs)
• Missing or extra quotes around strings
• Invalid data types (strings need quotes, numbers don’t)
• Missing required fields (like path or url)

Repository Not Detected

If a newly added repository is not appearing:

1. Check the path is correct in monospecs.yaml
2. Verify the repository was cloned successfully
3. Check if the repository exists in the expected location

Clone Failures

If repository cloning fails:

1. Check network connection
2. Verify Git repository URL is correct
3. Check for authentication issues
4. Review Docker container status
5. Check disk space availability

---

For more detailed information, refer to the monospecs documentation and check the Hagicode repository for configuration examples.