detections/.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)	—
2.5	Glossary & Architecture Vision	(inline, no sub-skill)	Steps 1–5
3	Status	monorepo-status/SKILL.md	Sections 1–5
4	Document Sync	monorepo-document/SKILL.md	Phase 1–7 (conditional on doc drift)
4.5	Integration Test Sync	monorepo-e2e/SKILL.md	Phase 1–6 (conditional on suite-e2e drift; skipped if suite_e2e: block absent in config)
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 2.5 (Glossary & Architecture Vision).
• 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 2.5 — Glossary & Architecture Vision (one-shot)

Condition (folder fallback): _docs/_repo-config.yaml exists AND confirmed_by_user: true AND (_docs/glossary.md does NOT exist OR the cross-cutting architecture doc identified in docs.cross_cutting does NOT contain a ## Architecture Vision section). State-driven: reached by auto-chain from Step 2 (user picked A).

Goal: Capture meta-repo-wide terminology and the user's architecture vision once, after the config is confirmed but before any sync skill runs. Without this, monorepo-document will faithfully propagate per-component changes but never surface a unified mental model of the meta-repo to the user, and the AI will keep re-inferring the same project terminology on every invocation.

Why inline (no sub-skill): monorepo-discover is hard-guarded to write only _repo-config.yaml; monorepo-document only edits existing docs. Glossary and architecture-vision creation is a first-time, user-confirmed write that crosses both guarantees, so it lives directly in the flow.

Inputs:

• _docs/_repo-config.yaml (component list, doc map, conventions, assumptions log)
• Cross-cutting docs listed under docs.cross_cutting (existing architecture doc, if any)
• Each component's primary_doc (read-only, for terminology + responsibility extraction)
• Root README.md if repo.root_readme is referenced

Outputs:

• _docs/glossary.md (or <docs.root>/glossary.md if docs.root ≠ _docs/) — NEW
• The cross-cutting architecture doc updated in place: a ## Architecture Vision section is prepended (or merged into an existing "Vision" / "Overview" heading)
• One new entry appended to _docs/_repo-config.yaml under assumptions_log: recording the run
• A new top-level config entry: glossary_doc: <path> so future monorepo-status and monorepo-document runs treat the glossary as a known cross-cutting doc

Procedure:

1. Draft glossary from _repo-config.yaml + each component's primary doc. Include:

   • Component codenames as they appear in the config (name field) and any rename pairs the user noted in unresolved: resolutions
   • Domain terms that recur across ≥2 component docs
   • Acronyms / abbreviations
   • Convention names from conventions: (e.g., commit prefix, deployment tier names)
   • Stakeholder personas if cross-cutting docs reference them Each entry: one-line definition + source (source: components.<name>.primary_doc or source: _repo-config.yaml conventions). Skip generic terms.

2. Draft architecture vision from the meta-repo perspective:

   • One paragraph: what the system as a whole is, what each component contributes, the runtime topology (one binary / N services / N clients + 1 server / hybrid), how components communicate (REST / gRPC / queue / DB-shared / file-shared)
   • Components & responsibilities (one-line each), pulled directly from _repo-config.yaml components: list
   • Cross-cutting concerns ownership: which doc owns which concern (auth, schema, deployment, etc.) — pulled from docs.cross_cutting[].owns
   • Architectural principles / non-negotiables the user has implied across components (e.g., "all components share a single Postgres", "submodules own their own CI", "deployment is per-tier, not per-component")
   • Open questions / structural drift signals: components missing from docs.cross_cutting, components in registry but not in config (registry mismatch), or contradictions between component primary docs

3. Present condensed view to the user (NOT the full draft files):

   ══════════════════════════════════════
    REVIEW: Meta-Repo Glossary + Architecture Vision
   ══════════════════════════════════════
    Glossary (N terms drafted from config + component docs):
      - <Term>: <one-line definition>
      - ...
   
    Architecture Vision — meta-repo level:
      <one-paragraph synopsis>
   
      Components / responsibilities:
        - <component>: <one-line>
        - ...
   
      Cross-cutting ownership:
        - <concern> → <doc>
        - ...
   
      Principles / non-negotiables:
        - <principle>
        - ...
   
      Open questions / drift signals:
        - <q1>
        - <q2>
   ══════════════════════════════════════
    A) Looks correct — write the files
    B) Add / correct entries (provide diffs)
    C) Resolve open questions / drift signals first
   ══════════════════════════════════════
    Recommendation: pick C if drift signals exist;
                    otherwise B if components or principles
                    don't match your intent; A only when
                    the inferred vision is exactly right.
   ══════════════════════════════════════
   

4. Iterate:

   • On B → integrate the user's diffs/additions, re-present, loop until A.
   • On C → ask the listed open questions in one batch, integrate answers, re-present.
   • Do NOT proceed to step 5 until the user picks A.

5. Save:

   • Write _docs/glossary.md (alphabetical) with **Status**: confirmed-by-user + date.
   • Update the cross-cutting architecture doc identified in docs.cross_cutting (or create one at _docs/00_architecture.md if none exists and the user's option-B input named one): prepend ## Architecture Vision with the confirmed paragraph + components + ownership + principles. Preserve every existing H2 below verbatim.
   • Append to _docs/_repo-config.yaml:
     • Top-level glossary_doc: <path-relative-to-repo-root> (sibling of docs.root)
     • New assumptions_log: entry: { date: <today>, skill: autodev-meta-repo Step 2.5, run_notes: "Captured glossary + architecture vision", assumptions: [...] }
   • Do NOT flip any confirmed: false → confirmed: true in the config; this step writes its own confirmed artifact, it does not retroactively confirm config inferences.

Self-verification:

• Every glossary entry traces to either the config or a component primary doc
• Every component listed in the vision matches a components: entry in the config
• All open questions are answered or explicitly deferred (with the user's acknowledgement)
• The cross-cutting architecture doc still contains every H2 it had before this step
• User picked option A on the latest condensed view

Idempotency: if both _docs/glossary.md exists AND the architecture doc already has a ## Architecture Vision section, this step is skipped on re-invocation. To refresh, the user invokes /autodev after deleting glossary.md (or running monorepo-discover with structural changes that justify a re-confirmation).

After completion, auto-chain to Step 3 (Status).

---

Step 3 — Status

Condition (folder fallback): _docs/_repo-config.yaml exists AND confirmed_by_user: true AND (_docs/glossary.md exists OR glossary_doc: is recorded in the config). State-driven: reached by auto-chain from Step 2.5, 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 suite-e2e drift → auto-chain to Step 4.5 (Integration Test Sync)
• Else if the status report ALSO flagged CI drift → auto-chain to Step 5 (CICD Sync)
• Else → end cycle, report done

---

Step 4.5 — Integration Test Sync

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

Skip condition: if _docs/_repo-config.yaml has no suite_e2e: block, this step is skipped entirely — there's no harness to sync. The status report should not flag suite-e2e drift in that case; if it does, that's a status-skill bug.

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

The skill:

1. Verifies every path under suite_e2e.* exists (binary fixtures excepted — see the skill's Phase 1)
2. Classifies each flagged change against the suite-e2e impact table
3. Applies edits to e2e/docker-compose.suite-e2e.yml, e2e/fixtures/init.sql, e2e/fixtures/expected_detections.json metadata, and e2e/runner/tests/*.spec.ts selectors as needed
4. Bumps baseline fixture_version with a -stale suffix and appends a _docs/_process_leftovers/ entry whenever the detection model revision changes (binary fixture cannot be regenerated automatically)
5. Reports synced files; does not run the suite e2e itself

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/suite-e2e drift), Step 4, or Step 4.5.

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

After completion, end cycle. Report files updated across doc, suite-e2e, 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 → Glossary & Architecture Vision (2.5)
Config Review (2, user picked B)	Session boundary — end session, await re-invocation
Glossary & Architecture Vision (2.5)	Auto-chain → Status (3)
Status (3, doc drift)	Auto-chain → Document Sync (4)
Status (3, suite-e2e drift only)	Auto-chain → Integration Test Sync (4.5)
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) + suite-e2e drift pending	Auto-chain → Integration Test Sync (4.5)
Document Sync (4) + CI drift only pending	Auto-chain → CICD Sync (5)
Document Sync (4) + no further drift	Cycle complete
Integration Test Sync (4.5) + CI drift pending	Auto-chain → CICD Sync (5)
Integration Test Sync (4.5) + 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)
2.5	Glossary & Architecture Vision	SKIPPED (already captured)
3	Status	DONE (no drift), DONE (N drifts)
4	Document Sync	DONE (N docs), SKIPPED (no doc drift)
4.5	Integration Test Sync	DONE (N files), SKIPPED (no suite-e2e drift), SKIPPED (no suite_e2e config block)
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 2.5, 4, 4.5, and 5 additionally accept SKIPPED.

Row rendering format:

 Step 1     Discover                          [<state token>]
 Step 2     Config Review                     [<state token>]
 Step 2.5   Glossary & Architecture Vision    [<state token>]
 Step 3     Status                            [<state token>]
 Step 4     Document Sync                     [<state token>]
 Step 4.5   Integration Test Sync             [<state token>]
 Step 5     CICD Sync                         [<state token>]

Notes for the meta-repo flow

• No session boundary except Step 2 and Step 2.5: unlike existing-code flow (which has boundaries around decompose), meta-repo flow only pauses at config review and the one-shot glossary/vision capture. Once both are confirmed, syncing is fast enough to complete in one session and Step 2.5 idempotently no-ops on every subsequent invocation.
• 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).