brownfield

/ouroboros:brownfield

Scan a root directory for existing git repositories and linked worktrees, then manage default repos used as context in interviews.

Usage

ooo brownfield                # Scan repos and set defaults
ooo brownfield scan           # Scan only (no default selection)
ooo brownfield defaults       # Show current defaults
ooo brownfield set 6,18,19   # Set defaults by repo numbers
ooo brownfield detect [path]  # Author mechanical.toml via one AI call

Trigger keywords: "brownfield", "scan repos", "default repos", "brownfield scan", "mechanical detect"

---

How It Works

Default flow (ooo brownfield with no args)

Step 1: Scan

Show scanning indicator:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Scanning for Existing Projects...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Looking for git repositories and worktrees up to two directories below the scan root.
Local repos and repos with any remote name are eligible.
This may take a moment...

Implementation — use MCP tools only, do NOT use CLI or Python scripts:

CRITICAL — deferred-schema guard (prevents "Invalid tool parameters"): This skill can call ouroboros_brownfield across multiple turns (scan, set_defaults, defaults, and set). A deferred schema loaded for one turn is NOT guaranteed to remain loaded for the next. Immediately before EVERY ouroboros_brownfield call, re-run tool discovery query: "+ouroboros brownfield" (idempotent — a no-op when already loaded). If the load returns no matching tool (and the tool is not already callable — an empty load for an already-exposed tool is an expected no-op, not absence), stop with the MCP-not-available message instead of retrying the failing call.

1. Load the brownfield MCP tool: tool discovery query: "+ouroboros brownfield"
2. Call scan+register:

   Tool: ouroboros_brownfield
   Arguments: { "action": "scan" }
   

   This walks scan_root (up to two directory levels deep) for valid seed repos/worktrees and registers them in DB. Each repo or worktree found directly by the walk is registered self-only — Git worktree families are not expanded, so worktrees outside the depth-bounded walk (e.g. under .ouroboros/worktrees) are not pulled in. Existing defaults are preserved.

The scan response text already contains a pre-formatted numbered list with [default] markers. Do NOT make any additional MCP calls to list or query repos.

Display the repos in a plain-text 2-column grid (NOT a markdown table). Use a code block so columns align. Example:

Scan complete. 8 repositories registered.

 1. repo-alpha                   5. repo-epsilon
 2. repo-bravo *                 6. repo-foxtrot
 3. repo-charlie                 7. repo-golf *
 4. repo-delta                   8. repo-hotel

Include * markers for defaults exactly as they appear in the scan response.

If no repos found, show:

No git repositories or worktrees found.

Then stop.

Scan boundaries

• The filesystem walk starts at scan_root; when omitted, scan_root defaults to the current user's home directory.
• Repositories are discovered by walking directories inside scan_root, at most two levels deep (so ~/repo and ~/group/repo are found; deeper nesting is not).
• Dot-prefixed directories and known noisy directories such as node_modules are not walked as seed locations.
• Both normal repos (.git directory) and linked worktrees (.git file) are registered when the walk reaches them. Git worktree families are NOT expanded — a worktree is only registered if the walk finds it directly, not because its main repo's Git metadata reports it.
• Local repos, repos without remotes, and repos whose remotes are not named origin are all eligible.

Step 2: Default Selection

IMMEDIATELY after showing the list, use AskUserQuestion with the current default numbers from the scan response.

If defaults exist, show them as the recommended option:

{
  "questions": [{
    "question": "Which repos to set as default for interviews? Enter numbers like '6, 18, 19'.",
    "header": "Default Repos",
    "options": [
      {"label": "<current default numbers> (Recommended)", "description": "<current default names>"},
      {"label": "None", "description": "No default repos — interviews will run in greenfield mode"}
    ],
    "multiSelect": false
  }]
}

If no defaults exist, do NOT show a "(Recommended)" option — offer "None" and "Select repos" instead:

{
  "questions": [{
    "question": "Which repos to set as default for interviews? Enter numbers like '6, 18, 19'.",
    "header": "Default Repos",
    "options": [
      {"label": "None", "description": "No default repos — interviews will run in greenfield mode"},
      {"label": "Select repos", "description": "Type repo numbers to set as default"}
    ],
    "multiSelect": false
  }]
}

The user can select the recommended defaults (if any), choose "None", or type custom numbers.

After the user responds, re-run tool discovery query: "+ouroboros brownfield", then use ONE MCP call to update all defaults at once:

Tool: ouroboros_brownfield
Arguments: { "action": "set_defaults", "indices": "<comma-separated IDs>" }

Example: if the user picks IDs 6, 18, 19 → { "action": "set_defaults", "indices": "6,18,19" }

This clears all existing defaults and sets the selected repos as default in one call.

If "None" → { "action": "set_defaults", "indices": "" } to clear all defaults.

Step 3: Confirmation

Brownfield defaults updated!
Defaults: grape, podo-app, podo-backend

These repos will be used as context in interviews.

Or if "None" selected:

No default repos set. Interviews will run in greenfield mode.
You can set defaults anytime with: ooo brownfield

---

Subcommand: scan

Scan only, no default selection prompt. Show the numbered list and stop.

---

Subcommand: defaults

Re-run tool discovery query: "+ouroboros brownfield", then call:

Tool: ouroboros_brownfield
Arguments: { "action": "scan" }

Display only the repos marked with * (defaults). If none, show:

No default repos set. Run 'ooo brownfield' to configure.

---

Subcommand: set <indices>

Directly set defaults without scanning. Parse the comma-separated indices from the user's input, re-run tool discovery query: "+ouroboros brownfield", and call:

Tool: ouroboros_brownfield
Arguments: { "action": "set_defaults", "indices": "<indices>" }

Show confirmation with updated defaults.

---

Subcommand: detect [path]

Runs one AI call against the target directory (defaults to the user's cwd) and writes .ouroboros/mechanical.toml with validated lint / build / test / static / coverage commands. Stage 1 of evaluation reads this file verbatim, so the toml is the authoritative Stage 1 contract — no hardcoded language presets exist anymore.

Ouroboros auto-runs this detect the first time ouroboros_evaluate is invoked without a toml present, so most users never need to call it directly. Run it explicitly when:

• you want to pre-author the toml before the first evaluate,
• you moved to a new build tool and want to refresh (--force),
• you want to review/edit the commands before Stage 1 trusts them.

Implementation: invoke the CLI via Bash.

uvx --from ouroboros-ai ouroboros detect [path]
# or, if already installed:
ouroboros detect [path] [--force]

Then print the resulting .ouroboros/mechanical.toml contents so the user can confirm the proposed commands or hand-edit them.

If detect reports "could not propose any verifiable commands", surface the reason (no manifests found, LLM unavailable, every proposal dropped) and suggest the user write a minimal toml by hand — any single entry like test = "pytest -q" is enough to opt back in to Stage 1 for that check.

RFC #1392 State Breadcrumb Footer

Your final response MUST end with exactly one breadcrumb footer line:

◆ <current state> → next: <recommended action>

Derive <current state> from live session state via ouroboros_session_status when that MCP projection is available; otherwise derive it from this skill's actual outcome. Never use a linear Step N of M footer because Ouroboros is an evolutionary loop. When the next action is genuinely a choice, list 2-3 honest options in the next: clause. The breadcrumb line must be the last line of the response.