/sync-knowledge — Auto-Generate Knowledge YAML

Explores a repo's codebase and synthesizes a knowledge YAML file. Keeps agents productive without manual documentation.

Usage

/sync-knowledge my-api           # Sync one repo
/sync-knowledge --all            # Sync all repos in repos.json
/sync-knowledge                  # Sync current repo (if in a sub-repo)

---

Step 1 — Identify Target Repos

Single repo

ls repos/<repo-name>/   # Verify the repo is cloned

If not cloned: bun run repo init --human first.

All repos (--all)

cat repos/repos.json   # Get the full list

Process each repo sequentially (not in parallel — each is a full codebase exploration).

---

Step 2 — Spawn Explore Agent

For each target repo, spawn an Explore subagent:

Explore the repository at repos/<repo-name>/ and answer these questions:

1. What does this repo do? (2-3 sentence overview)
2. What is the directory structure? (top 2 levels, key directories only)
3. What is the tech stack? (runtime, framework, key libraries with versions from package.json)
4. What are the main entry points? (e.g., src/index.ts, src/App.tsx, src/server.ts)
5. What are the key architectural patterns? (e.g., repository pattern, hooks-based state, event-driven)
6. What is the error handling convention? (throw vs return result, error types used)
7. What is the module organization? (how are files grouped, naming conventions)
8. What is the authentication/authorization approach? (if applicable)
9. What are the 5-10 most important files? (with brief description of each)
10. What are the integration points with other systems? (API contracts, shared types, events)
11. What has changed recently? (run: git log --oneline -20 in the repo)
12. What are the test patterns? (test framework, file naming, what gets tested)
13. What are the coding conventions? (commit format, branch naming, PR requirements from CONTRIBUTING.md or AGENTS.md)

Be specific — include real file paths, function names, and type names.
Max 400 lines in your response.

---

Step 3 — Synthesize YAML

From the Explore agent's findings, write knowledge/repos/<repo-name>.yaml:

# knowledge/repos/<repo-name>.yaml
# Auto-generated by /sync-knowledge
# Last updated: <ISO date>
# Commit: <git rev-parse HEAD of repo>

overview:
  name: <repo-name>
  description: >
    <2-3 sentence description of what the repo does>
  purpose: <backend | frontend | library | infrastructure | tooling>
  tech_stack:
    runtime: <node | bun | python | go | ...>
    framework: <express | next | fastapi | ...>
    language: <typescript | python | go | ...>
    key_libraries:
      - <name>: <version> — <purpose>

architecture:
  structure: |
    src/
      api/        REST endpoint handlers
      hooks/      React hooks (frontend)
      types/      Shared TypeScript interfaces
      utils/      Pure utility functions
      components/ UI components (frontend)
  entry_points:
    - <path>: <description>
  key_components:
    - <name>: <file path> — <description>

patterns:
  error_handling: >
    <describe the pattern: throw vs Result type, error classes used>
  state_management: >
    <describe: Redux / Zustand / hooks / context, etc.>
  module_organization: >
    <describe file grouping and naming conventions>
  authentication: >
    <describe auth approach if applicable>
  testing: >
    <framework, test file naming, what's covered>

conventions:
  commit_format: "<type>(<scope>): <description>"
  branch_naming: "<type>/<task-id>-<description>"
  pr_requirements:
    - All CI checks pass
    - At least one approval
    - Tests cover new code
  coding_standards:
    - TypeScript strict mode
    - No 'any' without justification comment
    - Error boundaries on all async operations

integration_points:
  apis:
    - endpoint: <path>
      method: <GET|POST|...>
      request: <type>
      response: <type>
      notes: <any important constraints>
  shared_types:
    - name: <TypeName>
      file: <path>
      consumers: [<other-repo>]
  events:
    - name: <event-name>
      producer: <repo>
      consumer: <repo>
      payload: <type or description>

key_files:
  - path: <relative file path>
    description: <what this file does and why it matters>
    key_exports:
      - <function/type name>: <brief description>

recent_changes:
  - <commit hash short>: <description> (<date>)
  - <commit hash short>: <description> (<date>)
  # (last 5-10 significant changes)

Max 400 lines. If the repo is large, prioritize depth over breadth — cover the most-used patterns fully rather than every file shallowly.

---

Step 4 — Update MEMORY.md Index

If using the harness's auto-memory system, update the index:

# Note the new file in memory index if a MEMORY.md index exists
echo "- [$(repo-name) knowledge](knowledge/repos/$(repo-name).yaml) — $(date)" >> ~/.claude/memory/MEMORY.md

---

Step 5 — Report

✓ knowledge/repos/my-api.yaml generated
  Lines: 187
  Sections: overview, architecture, patterns, conventions, integration_points (3 endpoints), key_files (8), recent_changes (10)
  Commit distance: 0 (fresh)

Next: run /ask to query this knowledge, or /go to start work.

If --all:

✓ Synced 3 repos:
  - knowledge/repos/my-api.yaml       (187 lines)
  - knowledge/repos/my-frontend.yaml  (212 lines)
  - knowledge/repos/my-infra.yaml     (94 lines)

---

Staleness Tracking

The YAML file stores the commit hash at generation time:

# Commit: abc1234f

The /ask command uses this to compute commit distance and warn when >50 commits behind. Run /sync-knowledge <repo> any time significant architecture changes are made.