Skip to content
AgentStack

Monorepo Profiles

If your team works in a monorepo, the best long-term model is to keep the profile as a self-contained subtree.

Section titled “Recommended structure”
repo/
  apps/
  packages/
  tooling/
    agentstack/
      profiles/
        mobile-default/
          agentstack.yaml
          instructions/
          skills/
          agents/
          mcps/
          env/

The important rule is simple: keep everything a profile needs close to the profile itself.

Why this matters

Section titled “Why this matters”

If prompts, wrappers, and env examples are scattered across unrelated folders, the profile stops being portable.

Keeping them inside one subtree gives you:

  • better reviewability
  • easier reuse across repos
  • fewer broken relative paths
  • a smoother migration to package-first AgentStack

Current reality

Section titled “Current reality”

Today, current v3 still centers on the manifest stored in:

~/.agentstack/profiles/<name>/agentstack.yaml

So in practice, many teams will still copy, install, or sync the profile into the local AgentStack hub.

Section titled “Recommended workflow today”
  1. Keep the canonical source in the monorepo subtree.
  2. Version all related assets next to it.
  3. Install or sync that profile into ~/.agentstack/profiles/<name>/.
  4. Activate the local profile from the AgentStack hub.

Relative paths

Section titled “Relative paths”

Prefer paths that remain valid when the profile subtree moves as a unit.

Good:

  • ./skills/core-review.md
  • ./mcps/github-wrapper.ts
  • ./instructions/global.md

Risky:

  • deep references into unrelated monorepo folders
  • paths that only work from one developer machine
  • implicit assumptions about current working directory

Direction

Section titled “Direction”

The profile-package pivot makes monorepo support a first-class goal. Until that lands fully, the safest strategy is to design your monorepo subtree as if it were already a standalone package.