Blueprints/Monorepo Hierarchy

Monorepo Hierarchy

Organize multiple AGENTS.md files in monorepo structures with parent-child relationships using ha_ hierarchies.

Overview

Large monorepos often have multiple AGENTS.md files at different levels—a root file with organization-wide rules, and package-specific files with additional context. LynxPrompt groups these into hierarchies (identified by ha_ IDs) that you can pull and sync as a unit.

my-monorepo/
├── AGENTS.md              ← Root blueprint (organization rules)
├── packages/
│   ├── core/
│   │   └── AGENTS.md      ← Child blueprint (core-specific)
│   ├── web/
│   │   └── AGENTS.md      ← Child blueprint (web-specific)
│   └── mobile/
│       └── AGENTS.md      ← Child blueprint (mobile-specific)
└── services/
    ├── api/
    │   └── AGENTS.md      ← Child blueprint (api-specific)
    └── worker/
        └── AGENTS.md      ← Child blueprint (worker-specific)

→ All grouped under hierarchy: ha_xyz123

ID Formats

bp_abc123

Blueprint ID

Individual AGENTS.md file. Pull one file with lynxp pull bp_xxx

ha_xyz789

Hierarchy ID

Group of related blueprints. Pull entire tree with lynxp pull ha_xxx

Hierarchy Naming

When you create a hierarchy, the name defaults to the folder name where your root AGENTS.md is located. You can change it later via the API or CLI.

Default Name

If you push from /projects/my-monorepo/AGENTS.md, the hierarchy will be named my-monorepo automatically.

Rename via API

PATCH /api/v1/hierarchies/ha_xyz789
{
  "name": "My Custom Name",
  "description": "Optional description"
}

Pushing to a Hierarchy

When you push AGENTS.md files, the CLI auto-detects the repository and creates/joins a hierarchy:

1. Push root AGENTS.md (creates hierarchy)

cd my-monorepo
lynxp push AGENTS.md --name "My Org Rules"

# ✅ Created blueprint "My Org Rules"
#    ID: bp_abc123
#    Hierarchy: ha_xyz789  ← New hierarchy created

2. Push child AGENTS.md (joins hierarchy)

cd my-monorepo/packages/core
lynxp push AGENTS.md --name "Core Package Rules"

# ✅ Created blueprint "Core Package Rules"
#    ID: bp_def456
#    Hierarchy: ha_xyz789  ← Same hierarchy
#    Path: packages/core/AGENTS.md
#    ↳ Linked to parent: bp_abc123

Pulling a Hierarchy

Pull an entire hierarchy to recreate the directory structure with all AGENTS.md files:

# Pull entire hierarchy
lynxp pull ha_xyz789

# 📥 Downloading blueprints...
#   ✓ AGENTS.md
#   ✓ packages/core/AGENTS.md
#   ✓ packages/web/AGENTS.md
#   ✓ services/api/AGENTS.md
# ✅ Downloaded 4 blueprint(s)

# Preview first
lynxp pull ha_xyz789 --preview

Listing Hierarchies

lynxp hierarchies

# 📁 Your Hierarchies (2 total)
#
#   my-monorepo
#     ID: ha_xyz789
#     Blueprints: 6
#
#   other-project
#     ID: ha_abc456
#     Blueprints: 3

Conflict Detection

LynxPrompt uses optimistic locking to prevent accidental overwrites when collaborating:

How it works

• Each blueprint has a content_checksum
• When you push, the expected checksum is sent
• If someone else pushed in between, you get a 409 Conflict
• Pull latest changes, resolve, then push again

# Conflict detected
lynxp push AGENTS.md

# ⚠ Conflict: Blueprint has been modified
#   Someone else may have pushed changes.
#
# Options:
#   1. lynxp pull bp_xxx (get latest)
#   2. lynxp push --force (overwrite)

API Reference

Access hierarchies programmatically via the v1 API:

List hierarchies

GET /api/v1/hierarchies
Authorization: Bearer lp_xxx

# Response:
{
  "hierarchies": [
    {
      "id": "ha_xyz789",
      "name": "my-monorepo",
      "repository_root": "abc123...",
      "blueprint_count": 6
    }
  ]
}

Get hierarchy with blueprints

GET /api/v1/hierarchies/ha_xyz789
Authorization: Bearer lp_xxx

# Response includes:
# - hierarchy metadata
# - blueprints array (flat list)
# - tree structure (nested for traversal)

Create blueprint with hierarchy

POST /api/v1/blueprints
{
  "name": "Core Package",
  "content": "...",
  "visibility": "PRIVATE",
  "hierarchy_id": "ha_xyz789",
  "repository_path": "packages/core/AGENTS.md",
  "parent_id": "bp_abc123"
}

Update with conflict detection

PUT /api/v1/blueprints/bp_def456
{
  "content": "...",
  "expected_checksum": "abc123def456"
}

# 200 OK → Success
# 409 Conflict → Someone else modified it

Dashboard View

In your dashboard, hierarchical blueprints are shown in a collapsible "Hierarchical Blueprints" section. Click on a hierarchy to expand and see all its AGENTS.md files with their paths.

Hierarchical Blueprints6 files

my-monorepo (ha_xyz789)

AGENTS.md

└─ packages/core/AGENTS.md

└─ packages/web/AGENTS.md

└─ services/api/AGENTS.md

← Variables Marketplace →