# Meta-Repo Workflow

Workflow for **meta-repositories** — repos that aggregate multiple components via git submodules, npm/cargo/pnpm/go workspaces, or ad-hoc conventions. The meta-repo itself has little or no source code of its own; it orchestrates cross-cutting documentation, CI/CD, and component registration.

This flow differs fundamentally from `greenfield` and `existing-code`:

- **No problem/research/plan phases** — meta-repos don't build features, they coordinate existing ones
- **No test spec / implement / run tests** — the meta-repo has no code to test
- **No `_docs/00_problem/` artifacts** — documentation target is `_docs/*.md` unified docs, not per-feature `_docs/NN_feature/` folders
- **Primary artifact is `_docs/_repo-config.yaml`** — generated by `monorepo-discover`, read by every other step

## Step Reference Table

| Step | Name | Sub-Skill | Internal SubSteps |
|------|------|-----------|-------------------|
| 1 | Discover | monorepo-discover/SKILL.md | Phase 1–10 |
| 2 | Config Review | (human checkpoint, no sub-skill) | — |
| 3 | Status | monorepo-status/SKILL.md | Sections 1–5 |
| 4 | Document Sync | monorepo-document/SKILL.md | Phase 1–7 (conditional on doc drift) |
| 5 | CICD Sync | monorepo-cicd/SKILL.md | Phase 1–7 (conditional on CI drift) |
| 6 | Loop | (auto-return to Step 3 on next invocation) | — |

**Onboarding is NOT in the auto-chain.** Onboarding a new component is always user-initiated (`monorepo-onboard` directly, or answering "yes" to the optional onboard branch at end of Step 5). The autodev does NOT silently onboard components it discovers.

## Detection Rules

**Resolution**: when a state file exists, `state.step` + `state.status` drive detection and the conditions below are not consulted. When no state file exists (cold start), walk the rules in order — first match wins. Meta-repo uses `_docs/_repo-config.yaml` (and its `confirmed_by_user` flag) as its primary folder-probe signal rather than per-step artifact folders.

---

**Step 1 — Discover**

Condition: `_docs/_repo-config.yaml` does NOT exist

Action: Read and execute `.cursor/skills/monorepo-discover/SKILL.md`. After completion, auto-chain to **Step 2 (Config Review)**.

---

**Step 2 — Config Review** (session boundary)

Condition: `_docs/_repo-config.yaml` exists AND top-level `confirmed_by_user: false`

Action: This is a **hard session boundary**. The skill cannot proceed until a human reviews the generated config and sets `confirmed_by_user: true`. Present using Choose format:

```
══════════════════════════════════════
 DECISION REQUIRED: Config review pending
══════════════════════════════════════
 _docs/_repo-config.yaml was generated by monorepo-discover
 but has confirmed_by_user: false.

 A) I've reviewed — proceed to Status
 B) Pause — I'll review the config and come back later
══════════════════════════════════════
 Recommendation: B — review the inferred mappings (tagged
 `confirmed: false`), unresolved questions, and assumptions
 before flipping confirmed_by_user: true.
══════════════════════════════════════
```

- If user picks A → verify `confirmed_by_user: true` is now set in the config. If still `false`, re-ask. If true, auto-chain to **Step 3 (Status)**.
- If user picks B → mark Step 2 as `in_progress`, update state file, end the session. Tell the user to invoke `/autodev` again after reviewing.

**Do NOT auto-flip `confirmed_by_user`.** Only the human does that.

---

**Step 3 — Status**

Condition (folder fallback): `_docs/_repo-config.yaml` exists AND `confirmed_by_user: true`.
State-driven: reached by auto-chain from Step 2 (user picked A), or entered on any re-invocation after a completed cycle.

Action: Read and execute `.cursor/skills/monorepo-status/SKILL.md`.

The status report identifies:
- Components with doc drift (commits newer than their mapped docs)
- Components with CI coverage gaps
- Registry/config mismatches
- Unresolved questions

Based on the report, auto-chain branches:

- If **doc drift** found → auto-chain to **Step 4 (Document Sync)**
- Else if **CI drift** (only) found → auto-chain to **Step 5 (CICD Sync)**
- Else if **registry mismatch** found (new components not in config) → present Choose format:

```
══════════════════════════════════════
 DECISION REQUIRED: Registry drift detected
══════════════════════════════════════
 Components in registry but not in config: <list>
 Components in config but not in registry: <list>

 A) Run monorepo-discover to refresh config
 B) Run monorepo-onboard for each new component (interactive)
 C) Ignore for now — continue
══════════════════════════════════════
 Recommendation: A — safest; re-detect everything, human reviews
══════════════════════════════════════
```

- Else → **workflow done for this cycle**. Report "No drift. Meta-repo is in sync." Loop waits for next invocation.

---

**Step 4 — Document Sync**

State-driven: reached by auto-chain from Step 3 when the status report flagged doc drift.

Action: Read and execute `.cursor/skills/monorepo-document/SKILL.md` with scope = components flagged by status.

The skill:
1. Runs its own drift check (M7)
2. Asks user to confirm scope (components it will touch)
3. Applies doc edits
4. Skips any component with unconfirmed mapping (M5), reports

After completion:
- If the status report ALSO flagged CI drift → auto-chain to **Step 5 (CICD Sync)**
- Else → end cycle, report done

---

**Step 5 — CICD Sync**

State-driven: reached by auto-chain from Step 3 (when status report flagged CI drift and no doc drift) or from Step 4 (when both doc and CI drift were flagged).

Action: Read and execute `.cursor/skills/monorepo-cicd/SKILL.md` with scope = components flagged by status.

After completion, end cycle. Report files updated across both doc and CI sync.

---

**Step 6 — Loop (re-entry on next invocation)**

State-driven: all triggered steps completed; the meta-repo cycle has finished.

Action: Update state file to `step: 3, status: not_started` so that next `/autodev` invocation starts from Status. The meta-repo flow is cyclical — there's no terminal "done" state, because drift can appear at any time as submodules evolve.

On re-invocation:
- If config was updated externally and `confirmed_by_user` flipped back to `false` → go back to Step 2
- Otherwise → Step 3 (Status)

## Explicit Onboarding Branch (user-initiated)

Onboarding is not auto-chained. Two ways to invoke:

**1. During Step 3 registry-mismatch handling** — if user picks option B in the registry-mismatch Choose format, launch `monorepo-onboard` interactively for each new component.

**2. Direct user request** — if the user says "onboard <name>" during any step, pause the current step, save state, run `monorepo-onboard`, then resume.

After onboarding completes, the config is updated. Auto-chain back to **Step 3 (Status)** to catch any remaining drift the new component introduced.

## Auto-Chain Rules

| Completed Step | Next Action |
|---------------|-------------|
| Discover (1) | Auto-chain → Config Review (2) |
| Config Review (2, user picked A, confirmed_by_user: true) | Auto-chain → Status (3) |
| Config Review (2, user picked B) | **Session boundary** — end session, await re-invocation |
| Status (3, doc drift) | Auto-chain → Document Sync (4) |
| Status (3, CI drift only) | Auto-chain → CICD Sync (5) |
| Status (3, no drift) | **Cycle complete** — end session, await re-invocation |
| Status (3, registry mismatch) | Ask user (A: discover, B: onboard, C: continue) |
| Document Sync (4) + CI drift pending | Auto-chain → CICD Sync (5) |
| Document Sync (4) + no CI drift | **Cycle complete** |
| CICD Sync (5) | **Cycle complete** |

## Status Summary — Step List

Flow name: `meta-repo`. Render using the banner template in `protocols.md` → "Banner Template (authoritative)".

Flow-specific slot values:
- `<header-suffix>`: empty.
- `<current-suffix>`: empty.
- `<footer-extras>`: add a single line:
  ```
   Config:  _docs/_repo-config.yaml [confirmed_by_user: <true|false>, last_updated: <date>]
  ```

| # | Step Name        | Extra state tokens (beyond the shared set) |
|---|------------------|--------------------------------------------|
| 1 | Discover         | — |
| 2 | Config Review    | `IN PROGRESS (awaiting human)` |
| 3 | Status           | `DONE (no drift)`, `DONE (N drifts)` |
| 4 | Document Sync    | `DONE (N docs)`, `SKIPPED (no doc drift)` |
| 5 | CICD Sync        | `DONE (N files)`, `SKIPPED (no CI drift)` |

All rows accept the shared state tokens (`DONE`, `IN PROGRESS`, `NOT STARTED`, `FAILED (retry N/3)`); rows 4 and 5 additionally accept `SKIPPED`.

Row rendering format:

```
 Step 1   Discover          [<state token>]
 Step 2   Config Review     [<state token>]
 Step 3   Status            [<state token>]
 Step 4   Document Sync     [<state token>]
 Step 5   CICD Sync         [<state token>]
```

## Notes for the meta-repo flow

- **No session boundary except Step 2**: unlike existing-code flow (which has boundaries around decompose), meta-repo flow only pauses at config review. Syncing is fast enough to complete in one session.
- **Cyclical, not terminal**: no "done forever" state. Each invocation completes a drift cycle; next invocation starts fresh.
- **No tracker integration**: this flow does NOT create Jira/ADO tickets. Maintenance is not a feature — if a feature-level ticket spans the meta-repo's concerns, it lives in the per-component workspace.
- **Onboarding is opt-in**: never auto-onboarded. User must explicitly request.
- **Failure handling**: uses the same retry/escalation protocol as other flows (see `protocols.md`).