loader/.cursor/skills/autodev/flows/meta-repo.md

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 " 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).