Skip to content

vt-c-repo-init

Initialize unified repo governance with partition boundaries, Git LFS, sparse-checkout profiles, and deployment integrity rules. Run once per project.

Plugin: core-standards
Category: Governance
Command: /vt-c-repo-init

/vt-c-repo-init — Initialize Unified Repo Governance

Workflow: /vt-c-scaffold → /vt-c-repo-init → project ready for design or development

Reference: docs/unified repo approach.md

Purpose

Sets up .repo-manifest.yaml and supporting infrastructure (Git LFS, sparse-checkout, .gitattributes) to enforce the Unified AI-Repository Governance model. This ensures:

  • Production Firewall — deployable code is separated from design/AI context
  • Binary Management — large files routed to Git LFS automatically
  • View Filtering — developers and designers see only relevant files
  • Self-Correction — hooks and audits detect and fix partitioning violations

When to Use

  • After /vt-c-scaffold when creating a new project
  • When adopting unified governance on an existing repository
  • Run once per project — subsequent runs update the manifest

Invocation

/vt-c-repo-init                    # Interactive setup with defaults
/vt-c-repo-init --adopt            # Adopt governance on existing project (scans artifacts, gradual enforcement)
/vt-c-repo-init --profile full     # Skip questions, use full profile

Execution Steps

Step 0: Adoption Scan (existing projects)

Triggers when: --adopt flag is used, OR Step 1 detects existing artifacts (code in src//apps/, specs files, .design-state.yaml, .specify/, git history with >0 commits).

If no existing artifacts are detected, skip to Step 1.

0a: Scan for Existing Artifacts

Scan for:
  [  ] .design-state.yaml           → Design workflow state
  [  ] specs directories          → 05-specs/, 05-specs/, docs/specs/, specs/
  [  ] .specify/ or specs/            → SpecKit directories
  [  ] PRD files                     → PRD.md, 03-PRD/PRD.md, 01-docs/PRD*.md, prd.md
  [  ] Source code                   → src/, apps/, packages/, scripts/ (with code files)
  [  ] Prototype directories         → prototype/, 04-prototyp/, sandbox/
  [  ] Dependency manifests          → package.json, requirements.txt, go.mod, Cargo.toml
  [  ] Existing .gitattributes       → Pre-existing LFS config
  [  ] Git history                   → commit count, earliest commit date

0b: Infer Project Phase

Based on scan results, classify: - design-complete — specs exist, PRD exists, no/minimal code (V004-Handbuch, P01) - development-active — code in src/apps/, active commits, may or may not have design artifacts (V024) - prototype-refinement — prototype/ exists with code, no production src/ yet (C035) - early-setup — minimal artifacts, single-digit commits (recruiting-dev)

0c: Auto-Map Partitions

Map detected directories to partitions using heuristics:

Deployable (production code):
  - Directories containing package.json + code files, or apps/ with build configs
  - src/, apps/, packages/, scripts/ (when containing .ts/.js/.py/.go files)
  - migrations/, supabase/

Context (design/AI artifacts — never deployed):
  - PRD files and their parent directories
  - specs directories (any naming variant)
  - .specify/, specs/, .design-state.yaml
  - docs/, 01-docs/, 02-Knowledge/, 02-Dokumente/, journal/
  - Meeting notes, inbox folders (00-inbox/, 01-Meetings_Protokolle/)
  - *.md files at root matching context patterns (PRD.md, PID.md, PRODUCT-VISION.md)

Sandbox (draft code — needs promotion):
  - prototype/, 04-prototyp/, sandbox/

0d: Show Adoption Profile

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Adoption Scan Results
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Project Phase: [inferred phase]
Git History:   [N] commits since [earliest date]

Existing Artifacts:
  - [list each detected artifact with path]

Partition Mapping:
  Deployable: [detected paths or "(none yet)"]
  Context:    [detected paths]
  Sandbox:    [detected paths or "(none)"]

Traceability:
  Mode: "new-only" (pre-governance commits exempt)
  Cutoff: [current date]
  Pre-governance commits: [count]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Use AskUserQuestion to confirm: - Accept adoption profile (Recommended) — proceed with detected mapping - Customize — adjust partitions, traceability mode, or paths

Then continue to Step 3 (Create .repo-manifest.yaml) with the adoption-specific values.

0e: Adoption-Specific Manifest Fields

When creating .repo-manifest.yaml in adoption mode, add:

traceability:
  require_spec_reference: "new-only"
  intent_tags_prefix: "SPEC-"
  cutoff_date: "{current date}"

adoption:
  adopted_at: "{current ISO timestamp}"
  pre_governance_commits: {count}
  cutoff_commit: "{SHA of HEAD at adoption time}"

0f: LFS for Existing Repos

When adopting (existing repo with git history): 1. Set up .gitattributes for future files (same as greenfield) 2. Scan for existing large files NOT tracked by LFS 3. Report but do NOT auto-migrate: 

Found [N] files exceeding [max_file_size_kb]KB not tracked by LFS:
  - [path] ([size]KB)
  ...
These files are already in git history. Retroactive LFS migration
requires `git lfs migrate` which rewrites history.
Recommendation: Track new files via LFS going forward.
To migrate existing: git lfs migrate import --include='*.png,*.jpg'
4. Proceed to Step 5 (skip Step 4 LFS init — handled here)

Step 1: Detect Project Structure

Scan the current directory to determine project type:

Check for indicators:
- 03-PRD/, 04-prototyp/, 05-specs/  → design project (OneDrive structure)
- src/, tests/, package.json            → coding project
- Both present                          → unified/mixed project
- .design-state.yaml                    → design workflow active

Report detected type to user.

Step 2: Confirm Partition Configuration

Use AskUserQuestion to confirm or customize partitions:

Detected project type: [type]

Default partition configuration:
  Deployable: src/, tests/, scripts/, migrations/
  Context:    docs/, 02-Knowledge/, 03-PRD/, 05-specs/
  Sandbox:    04-prototyp/, sandbox/

Accept defaults or customize?
  - Accept defaults (Recommended)
  - Customize partitions

If customizing, ask for each partition's paths.

Step 3: Create .repo-manifest.yaml

Copy from template and customize:

cp templates/vt-c-scaffold/base/.repo-manifest-template.yaml .repo-manifest.yaml

Adjust paths based on Step 2 answers. If project has non-standard paths, update accordingly.

Step 4: Initialize Git LFS

# Check if git lfs is available
command -v git-lfs &>/dev/null

# If available:
git lfs install

# Create .gitattributes for tracked extensions
# Based on binary_rules.lfs_extensions from manifest

Generate .gitattributes: 

*.png filter=lfs diff=lfs merge=lfs -text
*.jpg filter=lfs diff=lfs merge=lfs -text
*.jpeg filter=lfs diff=lfs merge=lfs -text
*.gif filter=lfs diff=lfs merge=lfs -text
*.svg filter=lfs diff=lfs merge=lfs -text
*.pdf filter=lfs diff=lfs merge=lfs -text
*.psd filter=lfs diff=lfs merge=lfs -text
*.sketch filter=lfs diff=lfs merge=lfs -text
*.fig filter=lfs diff=lfs merge=lfs -text
*.mp4 filter=lfs diff=lfs merge=lfs -text
*.zip filter=lfs diff=lfs merge=lfs -text

If git-lfs is not available: 

⚠ Git LFS not installed. Binary management rules are defined but not enforced.
  Install: brew install git-lfs
  Then run: git lfs install

Step 5: Update .gitignore

Add context-partition awareness to .gitignore if not already present:

# Unified Repo Governance — context partitions excluded from build
# These paths contain design/AI context and are never deployed
# Managed by .repo-manifest.yaml

Verify that node_modules/, dist/, build/, .env are already excluded.

Step 6: Create Sparse-Checkout Documentation

Create .sparse-checkout-profiles.md in project root documenting how developers can filter their view:

# Sparse Checkout Profiles

This project uses unified repo governance. Developers and designers
can filter their working copy to see only relevant files.

## Developer Profile
git clone --filter=blob:none --sparse <url>
git sparse-checkout set src/ tests/ scripts/ migrations/ .github/ CLAUDE.md

## Designer Profile
git clone --filter=blob:none --sparse <url>
git sparse-checkout set docs/ 02-Knowledge/ 03-PRD/ 04-prototyp/ 05\ specs/

## Full Profile (default)
git sparse-checkout disable

Step 7: Validate Setup

Run validation checks:

✅ .repo-manifest.yaml created and valid
✅ Git LFS initialized (or ⚠ not available)
✅ .gitattributes configured for binary extensions
✅ .gitignore includes standard exclusions
✅ Sparse-checkout profiles documented

Step 8: Display Summary

Unified Repo Governance initialized!

Partitions:
  🟢 Deployable: src/, tests/, scripts/, migrations/
  🔵 Context:    docs/, 02-Knowledge/, 03-PRD/, 05-specs/
  🟡 Sandbox:    04-prototyp/, sandbox/

Enforcement:
  - partition-guard.sh hook enforces write boundaries
  - commit-size-monitor.sh warns on oversized commits
  - /vt-c-repo-audit scans for violations before deployment
  - /vt-c-5-finalize runs governance audit automatically

Next steps:
  - /vt-c-pd-0-start  → start product design workflow
  - /vt-c-0-start     → start development workflow
  - /vt-c-repo-audit  → run integrity audit anytime
  - /vt-c-repo-health → quick governance health check