René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Document the `managed:` repository field and `--no-managed` workspace sync flag","articleBody":"## Summary\n\nThe `managed:` field on `repositories[]` in `workspace.yaml`, and the matching `--no-managed` flag on `allagents workspace sync`, are real features in the code (v1.7.2) but are not documented in any user-facing surface I could find. This issue asks for them to be added to the docs.\n\n## What the feature does\n\nFrom `dist/index.js` (v1.7.2):\n\n```javascript\n// shouldClone / shouldPull gatekeepers\nfunction shouldClone(managed) {\n  if (managed === undefined || managed === false) return false;\n  return true;\n}\nfunction shouldPull(managed) {\n  if (managed === true || managed === \"sync\") return true;\n  return false;\n}\n\n// processManagedRepos — called during `allagents workspace sync`\nasync function processManagedRepos(repositories, workspacePath, options2 = {}) {\n  if (options2.skipManaged || options2.offline || options2.dryRun) return [];\n  const managed = repositories.filter((r) =\u003e r.managed);\n  if (managed.length === 0) return [];\n  for (const repo of managed) {\n    // ...\n    if (!existsSync(absolutePath)) {\n      if (!shouldClone(repo.managed)) { /* skip */ continue; }\n      await cloneRepo(url, absolutePath, repo.branch);\n    } else if (shouldPull(repo.managed)) {\n      await pullRepo(absolutePath, repo.branch);\n    }\n  }\n}\n```\n\nSo in practice:\n\n- A `repositories[]` entry with `managed: true` causes `allagents workspace sync` to **`git clone`** the repo from `source` / `repo` into `path` if the path doesn't exist, and **`git pull`** it if it does exist and is clean.\n- `managed: \"sync\"` behaves like `true` for both clone and pull.\n- A truthy-but-not-`true` value (anything that passes the generic filter) causes a clone on first run but no subsequent pull.\n- Omitting `managed:` (or setting it to `false`) causes `allagents workspace sync` to leave the repo entirely alone.\n- Passing `--no-managed` to `workspace sync` sets `skipManaged: true` and short-circuits the whole function, regardless of what any repo has in its `managed:` field.\n\n## Where it's currently surfaced\n\n| Surface | Status |\n|---|---|\n| `allagents workspace sync --help` | ✅ Flag shown: `--no-managed  - Skip managed repository clone/pull operations [optional]` |\n| `dist/index.js` source | ✅ First-class flag, `flag({ long: \"no-managed\", ... })` |\n| https://allagents.dev (public docs site) | ❌ Not found on any page I could reach |\n| `docs/src/content/docs/docs/reference/cli.mdx` in the repo | ❌ No mention of `--no-managed` |\n| `docs/src/content/docs/docs/reference/configuration.mdx` | ❌ No mention of `managed:` on `repositories[]` |\n| `docs/src/content/docs/docs/guides/workspaces.mdx` | ❌ The example `repositories:` block omits `managed:` entirely |\n\n## Why this matters\n\nThe behavior is security- and correctness-relevant for anyone using allagents in a pipeline where another tool is already materializing repositories:\n\n- In a CI job that pre-downloads a pinned snapshot into a workspace directory, then calls `allagents workspace sync` to install skills/plugins/MCP servers, any stray `managed: true` entry silently causes allagents to overwrite the pre-materialized repo with `git clone` or mutate it with `git pull`. That's a real footgun — a copy-pasted YAML from another project could silently drift a pipeline's pinned source code to upstream HEAD.\n- Downstream users reading the docs have no way to discover either the feature (when they want it) or the escape hatch (when they explicitly don't). Today the only way to learn about it is reading the CLI `--help` output or the source.\n- Undocumented CLI flags are a semver hazard. If a future release renames `--no-managed` or folds it into a different flag, any downstream pipeline relying on the current name breaks with an \"unknown flag\" error. Documenting it means it becomes part of the published contract.\n\n## Suggested doc additions\n\n### 1. `docs/src/content/docs/docs/reference/configuration.mdx` — add `managed:` to the `repositories[]` schema\n\nSomething like:\n\n```yaml\nrepositories:\n  - path: ../my-project\n    source: github\n    repo: myorg/my-project\n    managed: true        # optional — see below\n```\n\n\u003e **`managed`** *(optional, default: omitted)*\n\u003e\n\u003e Controls whether `allagents workspace sync` clones or pulls this repository.\n\u003e\n\u003e - **Omitted** or **`false`** — allagents never touches the repository. Use this when another tool is responsible for materializing the source tree (e.g. a CI script that downloads a pinned snapshot).\n\u003e - **`true`** — allagents will `git clone` the repository from `source`/`repo` into `path` if it does not exist, and `git pull` it on subsequent syncs if the working tree is clean and on the expected branch.\n\u003e - **`\"sync\"`** — equivalent to `true`.\n\u003e\n\u003e The `source` and `repo` fields are required when `managed` is truthy.\n\n### 2. `docs/src/content/docs/docs/reference/cli.mdx` — document `--no-managed` under `workspace sync`\n\n```\nallagents workspace sync [--no-managed]\n\n  --no-managed   Skip git clone/pull operations for all repositories,\n                 regardless of their managed: field. Use this when\n                 another tool is responsible for populating repository\n                 directories and allagents should only handle plugins,\n                 skills, and AGENTS.md sync.\n```\n\n### 3. `docs/src/content/docs/docs/guides/workspaces.mdx` — add a short section on the managed vs unmanaged model\n\nA paragraph explaining the \"who owns the repo directory\" split would help downstream users reason about it:\n\n\u003e By default, allagents treats `repositories[]` entries as references only — it uses them for AGENTS.md / CLAUDE.md propagation and skill discovery, but it does not clone or pull the underlying git repository. To have allagents manage the repository directory itself, set `managed: true` on the entry. To explicitly disable repository management for a single sync run (for example, when a CI job has already populated the directory), pass `--no-managed` to `allagents workspace sync`.\n\n## Happy to contribute\n\nI can put up a docs PR with the three changes above if that would help — just confirm the desired wording and I'll follow the existing docs voice.\n\n## Context\n\nI hit this while wiring up a pinned per-year snapshot artifact pipeline in `WiseTechGlobal/WTG.AI.Prompts` ([PR #536](https://github.com/WiseTechGlobal/WTG.AI.Prompts/pull/536)). Our CI materializes each eval workspace at an optional pinned commit before calling `allagents workspace sync` to install skills, and I went looking for a documented way to make sure allagents could never clobber the pre-materialized tree. I found `--no-managed` in the CLI `--help` output but couldn't find any mention of it (or the corresponding `managed:` field) in the allagents.dev docs or the reference docs in this repo.","author":{"url":"https://github.com/christso","@type":"Person","name":"christso"},"datePublished":"2026-04-10T23:16:58.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/362/allagents/issues/362"}