repo-context-sync

name	repo-context-sync
description	Produces grounding context summaries — directory structure, recent diffs, and file patterns — from local repository state, enabling more accurate architectural and implementation decisions. Use when: "extract context from this repo", "what changed since last session", "understand the repo structure before writing a prompt", "ground a refactor in actual code state".

Repo Context Sync

Efficiently sync with relevant parts of local repositories to ground reasoning in actual codebase state. This skill enables context-aware architectural decisions, refactoring, and implementation prompt writing by providing tools to clone, track changes, and extract patterns from repos.

I. The Philosophy: Grounding in Reality

Architectural decisions made in a vacuum are fragile. Implementation prompts written without understanding existing patterns create friction. The Repo Context Sync skill embodies grounding in reality — the practice of syncing with the actual codebase state before making decisions or writing specifications.

This is not about reading every file, but about surgical context extraction: identifying what matters for the task at hand, syncing only those parts, and integrating that context into reasoning. It transforms vague architectural discussions into grounded, actionable decisions.

II. When to Use This Skill

Trigger this skill when:

• User mentions "repo", "repository", "codebase", "sync", "what changed"
• Starting a conversation about refactoring, architecture, or design
• Writing implementation prompts that need to follow existing patterns
• User asks about specific repo directories (e.g., /00_Roadmap/, /02_Specs/)
• Need to understand current state of a local codebase before a sprint

III. Core Workflow

1. Identify Context Need

Parse the user's request to determine:

• Which repo(s) are relevant
• Which directories matter for the task
• What keywords indicate focus areas

Common patterns:

• "refactor the agent routing" → Need /02_Specs/, /04_System/
• "write implementation prompt for X" → Need existing code patterns
• "what changed in the backend" → Need diff since last sync

2. Sync Repo State

Use the appropriate script based on repo state:

If repo not yet cloned:

bash {SKILLS_ROOT}/repo-context-sync/scripts/smart_clone.sh \
  <repo_url> \
  <local_path> \
  [dir1] [dir2] ...

Example:

bash {SKILLS_ROOT}/repo-context-sync/scripts/smart_clone.sh \
  https://github.com/TresPies-source/dojo-genesis \
  <your-local-repos-path>/dojo-genesis \
  /00_Roadmap/ /02_Specs/ /04_System/

This uses sparse checkout to only pull specified directories, saving time and space.

If repo already cloned:

The script automatically detects existing repos and runs git fetch && git pull instead.

3. Track Changes

Generate a diff summary to see what changed since last sync:

python3 {SKILLS_ROOT}/repo-context-sync/scripts/diff_tracker.py \
  <repo_path> \
  [last_commit_hash]

Example:

python3 {SKILLS_ROOT}/repo-context-sync/scripts/diff_tracker.py \
  <your-local-repos-path>/dojo-genesis \
  abc123

This generates a markdown summary showing:

• Added, modified, deleted files
• Commit messages
• Summary statistics

The summary is both printed and saved to .diff_summary.md in the repo.

4. Generate Context Map

Create a comprehensive overview of the codebase:

python3 {SKILLS_ROOT}/repo-context-sync/scripts/context_mapper.py \
  <repo_path> \
  [focus_keywords...]

Example:

python3 {SKILLS_ROOT}/repo-context-sync/scripts/context_mapper.py \
  <your-local-repos-path>/dojo-genesis \
  agent routing supervisor

This generates:

• File tree structure
• Detected languages and frameworks
• Files matching focus keywords
• Summaries of relevant files
• Pattern extraction

The summary is saved to .context_summary.md in the repo.

5. Integrate Context

Read the generated summaries and integrate into reasoning:

1. Read the context summary to understand repo structure
2. Read relevant files identified by the mapper
3. Check reference docs for patterns:
   • {SKILLS_ROOT}/repo-context-sync/references/file_hierarchy_patterns.md
   • {SKILLS_ROOT}/repo-context-sync/references/zenflow_repo_patterns.md
4. Ground architectural decisions in actual code state

IV. Script Reference

smart_clone.sh

Purpose: Efficient sparse checkout of relevant directories

Usage:

bash smart_clone.sh <repo_url> <local_path> [dir1] [dir2] ...

Behavior:

• If repo doesn't exist: Clone with sparse checkout
• If repo exists: Fetch and pull latest changes
• Only downloads specified directories (if provided)

Storage location: A local directory of your choosing, e.g. <your-local-repos-path>/{repo_name}/

diff_tracker.py

Purpose: Track and summarize changes since last sync

Usage:

python3 diff_tracker.py <repo_path> [last_commit_hash]

Output:

• Markdown summary of changes
• List of modified/added/deleted files
• Commit messages
• Saved to <repo_path>/.diff_summary.md

Default behavior: If no commit hash provided, compares last 10 commits

context_mapper.py

Purpose: Generate codebase overview for task context

Usage:

python3 context_mapper.py <repo_path> [focus_keywords...]

Output:

• File tree structure (max depth 3)
• Detected languages and frameworks
• Files matching keywords (via git grep)
• Summaries of top 5 relevant files
• Saved to <repo_path>/.context_summary.md

Pattern detection:

• Languages by file extensions
• Frameworks by config files (package.json, requirements.txt, etc.)
• File hierarchy patterns (numbered directories like /00_Roadmap/)

V. Reference Documents

file_hierarchy_patterns.md

Describes the standard "Planning with Files" hierarchy used in Dojo Genesis and related repos:

• /00_Roadmap/ - High-level goals and task_plan.md
• /01_PRDs/ - Product Requirement Documents
• /02_Specs/ - Technical specifications
• /03_Prompts/ - Local prompt library
• /04_System/ - AI Personas and system prompts
• /05_Logs/ - Dev traces, JOURNAL.md, AUDIT_LOG.md

Read this when:

• Understanding repo structure
• Determining which directories to sync
• Writing files that follow conventions

implementation_agent_patterns.md

Describes how to work with implementation agents' workflows:

• Task artifact structure (e.g., .zenflow/tasks/{task_id}/ for Zenflow)
• Built-in workflow types (Quick Change, Fix Bug, Spec and Build, Full SDD)
• Best practices for reading existing codebases
• Integration with standard file hierarchy

Read this when:

• Writing implementation prompts
• Understanding task artifacts
• Following existing codebase patterns

VI. Common Use Cases

Use Case 1: Starting a Refactoring Conversation

User says: "Let's refactor the agent routing logic"

Workflow:

1. Identify relevant repo: dojo-genesis
2. Identify relevant dirs: /02_Specs/, /04_System/
3. Run smart_clone.sh with those dirs
4. Run context_mapper.py with keywords: "agent", "routing", "supervisor"
5. Read generated context summary
6. Read relevant spec files
7. Ground refactoring suggestions in actual code

Use Case 2: Writing an Implementation Prompt

User says: "Write an implementation prompt to implement the Trail of Thought visualization"

Workflow:

1. Identify relevant repo: dojo-genesis
2. Run smart_clone.sh to get latest code
3. Run context_mapper.py with keywords: "visualization", "trace", "component"
4. Read implementation_agent_patterns.md for best practices
5. Extract existing patterns (naming, imports, structure)
6. Write prompt that says "Follow existing patterns in /src/components/"
7. Reference specific files and conventions

Use Case 3: Tracking Evolution

User says: "What changed in the backend since last session?"

Workflow:

1. Identify relevant repo: dojo-genesis
2. Load last sync commit hash from state (if available)
3. Run diff_tracker.py with that commit
4. Read generated diff summary
5. Highlight architectural implications
6. Summarize for user

VII. State Management

Track sync state in a .repo-sync-state.json file at a stable location in your workspace (e.g., your project root or a dedicated config directory):

{
  "repos": {
    "TresPies-source/dojo-genesis": {
      "last_sync": "2026-01-28T17:48:00Z",
      "commit_hash": "abc123",
      "local_path": "<your-local-repos-path>/dojo-genesis",
      "tracked_dirs": ["/00_Roadmap/", "/02_Specs/"]
    }
  }
}

Update this file after each sync to enable diff tracking. Store it at your project root or another stable path — not at a platform-specific location.

VIII. Integration with Implementation Agents

When working with implementation agents (Zenflow, Claude Code, etc.):

1. Read existing codebase first - Use context_mapper.py before generating code
2. Follow existing patterns - Extract conventions from context summary
3. Reference standard hierarchy - Use file_hierarchy_patterns.md as guide
4. Integrate cleanly - Minimize refactoring, extend existing components

Implementation agents typically have full repo access, so prompts should leverage that:

• "Read /src/components/ to understand component patterns"
• "Follow the same naming conventions as existing files"
• "Integrate with existing state management in /src/store/"

IX. Best Practices

Efficiency

• Only sync directories relevant to the task
• Use sparse checkout for large repos
• Cache context summaries (invalidate on sync)

Accuracy

• Always fetch latest changes before generating context
• Verify commit hashes in diff tracking
• Cross-reference multiple files for patterns

Transparency

• Show user what's being synced and why
• Surface generated summaries for review
• Log sync operations to session

Integration

• Read reference docs to understand patterns
• Follow existing conventions in repos
• Update state file after each sync

X. Limitations

What This Skill Does

• Efficiently clone/sync relevant repo parts locally
• Track changes and generate diffs
• Extract patterns and conventions
• Provide grounded context for reasoning

What This Skill Doesn't Do

• Automatically modify code
• Make architectural decisions
• Execute implementation tasks
• Replace manual code review
• Store full repo history (only relevant parts)
• Push or sync state to remote services — all operations are local

XI. Troubleshooting

Issue: Sparse checkout not working

Solution: Ensure Git version is 2.25+ (sparse-checkout v2 feature)

Issue: Context mapper finds too many files

Solution: Use more specific keywords or limit to specific directories

Issue: Diff tracker shows no changes

Solution: Verify last_commit_hash is correct and repo has been fetched

Issue: Scripts fail with permission errors

Solution: Ensure scripts are executable (chmod +x)

Output

• .diff_summary.md in the repo root: markdown summary of changes since the last sync (added, modified, deleted files; commit messages; statistics).
• .context_summary.md in the repo root: file tree, detected stack, keyword-matched files, and summaries of top relevant files.
• Updated .repo-sync-state.json at your workspace root recording the commit hash and sync timestamp.

Examples

Scenario 1: "Understand the Gateway repo structure before writing a spec" → sparse checkout of /02_Specs/ and /04_System/, context_mapper run with keywords "gateway routing middleware", .context_summary.md produced and read to ground the spec. Scenario 2: "What changed in the backend since last session?" → diff_tracker run against the stored commit hash, .diff_summary.md produced showing 3 modified files in the routing layer and 1 new migration, architectural implications surfaced.

Edge Cases

• If no commit hash is stored in .repo-sync-state.json, diff_tracker defaults to comparing the last 10 commits — note this default explicitly in the output so the user knows the baseline.
• If sparse checkout pulls more files than expected (e.g., a directory contains deeply nested subdirectories), the context map may be large — apply keyword filtering to keep output focused.

Anti-Patterns

• Running context_mapper without first fetching latest changes — generates context from a stale local clone, which can produce misleading architectural suggestions.
• Using this skill as a replacement for reading the actual code — context summaries are grounding artifacts, not substitutes for reading critical files directly.

Quality Checklist

Before delivering a context summary, confirm:

• git fetch (or smart_clone.sh) ran successfully before context_mapper was invoked — no stale local state
• The directories synced match the task (not a blanket full-repo clone when only 2 dirs are relevant)
• .diff_summary.md baseline noted explicitly when no prior commit hash was stored
• .context_summary.md keyword filter is specific enough to keep output focused (not 50+ matching files)
• .repo-sync-state.json updated with the current commit hash and timestamp after sync
• Critical files identified by context_mapper were read directly (not inferred from summaries alone)
• Architectural decisions made after this sync are grounded in the actual code state shown — not memory from a prior session

Related Skills

• semantic-clusters — after syncing repo context, use this skill to map the behavioral architecture (what the system does) rather than just the directory tree (where files live)
• status-template — repo context sync feeds Sections 3 (Directory Structure) and 10 (Aggregate Statistics) of the status document
• repo-status — the parent skill that uses repo-context-sync as one phase in a broader repository health workflow