Skill: Codebase

Manage code repositories within harvis workspace. Keeps code separate from context/planning.

Implementation details: See references/implementation.md for bash pseudocode.

Key Principles

Canonical is read-only: _repo/ at project level is only for cloning and serving as worktree base.
All changes in worktrees: Each bead context gets its own worktree via contexts/<bead-id>/_repo/.
Always fresh: Sync canonical (fetch + fast-forward) before worktree/analyze/status.

Structure

projects/<project>/
├── repo.yaml              # Repository registry
├── _repo/                  # Gitignored - canonical clones (READ-ONLY)
│   └── <name>/
├── _shared/                # Gitignored - shared repo clones (via project-share)
│   └── <name>/             # Canonical (same rules as _repo/)
└── contexts/<bead-id>/
    ├── _repo/              # Gitignored - worktrees (for development)
    │   └── <name>/
    ├── _shared/            # Gitignored - shared repo worktrees
    │   └── <name>/
    └── code-context.md     # Analysis output

Commands

Registry

Command	Purpose
`add <name> <url>`	Register repo in repo.yaml
`remove <name>`	Unregister (doesn't delete files)
`list`	Show repos with clone/worktree status

Project-Level

Command	Purpose
`clone [name]`	Clone to `project/_repo/<name>/`
`sync [name]`	Fetch + fast-forward canonical
`status`	Show clone and worktree status

Context-Level

Command	Purpose
`worktree [name]`	Create `contexts/<bead-id>/_repo/<name>/` worktree from latest main
`worktree [--shared] [name]`	Create `contexts/<bead-id>/_shared/<name>/` worktree for shared repos
`worktree-remove [name]`	Remove worktree (warns on dirty state)
`sync-deps [name]`	Symlink/copy/install dev dependencies
`pr [name]`	Push branch + create GitHub PR
`analyze [name]`	Generate `code-context.md` from code analysis

repo.yaml Format

repos:
  frontend:
    url: git@github.com:org/frontend.git
    default_branch: main
    description: React web application
    key_paths: [src/components/, src/services/]
    deps:
      symlink: [node_modules]
      copy: [.env.example:.env]

Workflow Summary

# One-time project setup
/codebase add frontend git@github.com:org/frontend.git
/codebase clone

# Per-bead development
/codebase worktree frontend    # Creates worktree from latest main
/codebase sync-deps frontend   # Symlink node_modules, copy .env
# ... make changes ...
/codebase pr frontend          # Push + create PR

# Analysis only (no changes)
/codebase analyze frontend     # Generates code-context.md

Shared Repos (`_shared/`)

_shared/ repos (created by /project-share) follow the same canonical/worktree pattern as _repo/:

Canonical: projects/<project>/_shared/<name>/ (read-only, managed by project-share)
Worktree: contexts/<bead-id>/_shared/<name>/ (for development)
Auto-detected: if repo is in _shared/, worktree goes to contexts/<bead-id>/_shared/
clone/sync: recognize repos already in _shared/ (no need to re-clone)
pr: works the same from _shared/ worktrees

Use --shared flag or the skill auto-detects from path.

Tips

Code changes happen in contexts/<bead-id>/_repo/ or contexts/<bead-id>/_shared/ only
Context, specs, decisions stay in harvis repo
Use standard git commands for commits within worktrees
Always create PRs for non-harvis repos — never push directly to main
Always include GitHub URLs with line numbers in code-context.md

codebase