Detailed changes
@@ -228,6 +228,15 @@ Token breakdown:
───────────────────────────────────────────────
Total: 1069 tokens
+=== managing-and-navigating-worktrees ===
+
+Token breakdown:
+ Name: 32 tokens
+ Description: 110 tokens
+ Body: 1785 tokens (92 lines)
+ ───────────────────────────────────────────────
+ Total: 1927 tokens
+
=== querying-documentation ===
Token breakdown:
@@ -297,10 +306,10 @@ Token breakdown:
SUMMARY
============================================================
-Skills: 12
-Metadata: 1686 tokens
-Combined bodies: 18552 tokens
-Overall: 123887 tokens
+Skills: 13
+Metadata: 1828 tokens
+Combined bodies: 20337 tokens
+Overall: 125814 tokens
Validation errors: 0
Largest skills (by total tokens):
@@ -315,6 +324,7 @@ Largest skills (by total tokens):
Some other tools if these interested you
+- [wt](https://git.secluded.site/wt) - CLI for managing git worktrees
- [formatted-commit](https://git.secluded.site/formatted-commit) - CLI that turns LLM input into well-formatted Conventional Commits
-- [lune](https://git.secluded.site/lune) - CLI and MCP server for Lunatask integration
- [garble](https://git.secluded.site/garble) - transform stdin with an LLM (fix typos, translate, reformat)
+- [lune](https://git.secluded.site/lune) - CLI and MCP server for [Lunatask.app](https://lunatask.app)
@@ -0,0 +1,101 @@
+---
+name: managing-and-navigating-worktrees
+description: Manages git worktrees and repos using the wt CLI. Use when cloning or creating new repos, adding worktrees, switching branches or branches, when the user mentions wt or worktrees.
+compatibility: Requires wt CLI, git, and gum
+license: AGPL-3.0-or-later
+metadata:
+ author: Amolith <amolith@secluded.site>
+---
+
+# Managing Git Worktrees with wt
+
+`wt` manages git repositories using a bare repository structure:
+
+- `.bare/` contains the actual git repository
+- `.git` is a file pointing to `.bare/`
+- Each branch lives in its own directory as sibling worktrees
+
+## Quick Reference
+
+| Command | Purpose |
+| --------------- | --------------------------------------- |
+| `wt c <url>` | Clone repo into bare structure |
+| `wt n <name>` | Create new project |
+| `wt a <branch>` | Add worktree for branch |
+| `wt r <branch>` | Remove worktree |
+| `wt l` | List worktrees with status |
+| `wt f` | Fetch all remotes |
+| `wt init` | Convert existing repo to bare structure |
+
+## Common Workflows
+
+### Start a new project
+
+```bash
+wt n my-project --remote github
+cd my-project/main
+```
+
+### Clone and start working
+
+```bash
+wt c https://github.com/user/repo.git
+cd repo/main
+```
+
+### Create feature branch
+
+From inside any worktree:
+
+```bash
+wt a feature/new-thing -b main
+cd ../feature/new-thing
+```
+
+### Switch between branches
+
+Just `cd` to the worktree directory—no checkout needed:
+
+```bash
+cd ../main # switch to main
+cd ../feature/x # switch to feature branch
+```
+
+If the branch already exists in a remote, but doesn't yet have a local worktree, use `wt a branch` to fetch and create it.
+
+### Clean up finished work
+
+```bash
+wt r feature/old -b # remove worktree AND delete branch
+```
+
+### Convert existing repo
+
+```bash
+cd existing-repo
+wt init # --dry-run to preview, -y to skip prompt
+```
+
+## Command Details
+
+- **New project**: See [refs/new-project.md](refs/new-project.md) for remote templates
+- **Cloning**: See [refs/cloning.md](refs/cloning.md) for remote configuration and own vs contributor mode
+- **Adding worktrees**: See [refs/adding.md](refs/adding.md) for hooks and branch creation
+- **Converting repos**: See [refs/converting.md](refs/converting.md) for `wt init` details
+- **Config files**: See [refs/config.md](refs/config.md) for `.wt.lua` and global config
+
+If you lack context, READ THESE instead of immediately trying to use `wt` or relying on `-h` output. The refs might just give you the answer without you needing to fumble and find them.
+
+## Working Directory
+
+`wt` works from either the project root or any worktree. Run `wt l` to determine context:
+
+- **In a worktree**: Current worktree shows `./` in the Path column
+- **At project root**: All paths are relative names (e.g., `main`, `feature/foo`)
+
+From project root, `wt a` skips hooks. From a worktree, hooks trigger.
+
+## Key Behaviors
+
+1. **Hooks only trigger from worktrees**: Running `wt a` from project root skips hooks
+2. **Branch paths**: `feature/foo` becomes `project/feature/foo` (nested) or `project_feature_foo` (flat, if configured)
@@ -0,0 +1,70 @@
+# Adding Worktrees
+
+## Basic Usage
+
+```bash
+wt a <branch> [-b [<start-point>]]
+```
+
+## Examples
+
+```bash
+wt a main # checkout existing branch
+wt a feature/new -b # create new branch from HEAD
+wt a feature/new -b main # create new branch from main
+wt a feature/new -b v1.0.0 # create new branch from tag
+```
+
+## Hooks
+
+When `wt a` runs **from inside an existing worktree**, hooks from `.wt.lua` are applied to the new worktree.
+
+Running from project root skips hooks with a warning.
+
+### Hook Types
+
+| Hook | Purpose |
+| --------- | ---------------------------------------- |
+| `copy` | Copy files from source worktree |
+| `symlink` | Create symlinks to source worktree files |
+| `run` | Execute shell commands in new worktree |
+
+### Example `.wt.lua`
+
+```lua
+return {
+ hooks = {
+ copy = {"Makefile", "*.mk"},
+ symlink = {".env", "config.toml", "node_modules"},
+ run = {"make setup", "npm install"}
+ }
+}
+```
+
+### Hook Permissions
+
+First time hooks run in a project, `wt` prompts for permission via `gum confirm`. Permissions stored in `~/.local/share/wt/hook-dirs.lua`.
+
+## Branch Resolution
+
+When adding without `-b`:
+
+1. Checks local branches
+2. Checks all remotes
+3. Fails if branch exists on multiple remotes (ambiguous)
+
+## Path Styles
+
+Configured in `~/.config/wt/config.lua`:
+
+| Style | Example Branch | Result Path |
+| ------------------ | -------------- | --------------------- |
+| `nested` (default) | `feature/foo` | `project/feature/foo` |
+| `flat` | `feature/foo` | `project_feature_foo` |
+
+```lua
+return {
+ branch_path_style = "flat",
+ flat_separator = "_"
+}
+```
@@ -0,0 +1,59 @@
+# Cloning Repositories
+
+## Basic Usage
+
+```bash
+wt c <url> [--remote name]... [--own]
+```
+
+## Remote Configuration
+
+Configure remotes in `~/.config/wt/config.lua`:
+
+```lua
+return {
+ remotes = {
+ github = "git@github.com:myuser/${project}.git",
+ gitlab = "git@gitlab.com:myuser/${project}.git"
+ },
+ default_remotes = {"github"} -- or "prompt" to ask each time
+}
+```
+
+Use `--remote` to add configured remotes:
+
+```bash
+wt c https://github.com/user/repo.git --remote github --remote gitlab
+```
+
+## Contributor vs Own Mode
+
+### Contributor mode (default)
+
+For contributing to others' projects:
+
+- `origin` renamed to `upstream`
+- Selected remotes added from config
+- Pushes default branch to ALL selected remotes (creates fork copies)
+
+```bash
+wt c https://github.com/user/repo.git --remote github
+# origin → upstream
+# github remote added pointing to your fork
+```
+
+### Own mode (`--own`)
+
+For your own projects:
+
+- First selected remote becomes `origin`
+- Additional remotes added as mirrors
+- Pushes only to additional remotes, not the first
+
+```bash
+wt c git@github.com:me/my-project.git --remote github --remote gitlab --own
+# github → origin
+# gitlab added as mirror
+```
+
+
@@ -0,0 +1,47 @@
+# Configuration
+
+## Global Config
+
+Location: `~/.config/wt/config.lua`
+
+```lua
+return {
+ -- Path style for worktree directories
+ branch_path_style = "nested", -- or "flat"
+ flat_separator = "_", -- separator for flat style
+
+ -- Remote URL templates (${project} is substituted)
+ remotes = {
+ github = "git@github.com:myuser/${project}.git",
+ gitlab = "git@gitlab.com:myuser/${project}.git",
+ codeberg = "git@codeberg.org:myuser/${project}.git"
+ },
+
+ -- Which remotes to add by default
+ -- "prompt" = ask each time
+ -- {"github", "gitlab"} = use these automatically
+ -- nil = prompt if remotes exist
+ default_remotes = "prompt"
+}
+```
+
+## Project Config
+
+Location: `.wt.lua` in project root (alongside `.bare/`)
+
+```lua
+return {
+ hooks = {
+ -- Files to copy from source worktree
+ copy = {"Makefile", "*.mk", ".tool-versions"},
+
+ -- Files to symlink from source worktree
+ symlink = {".env", ".env.local", "node_modules"},
+
+ -- Commands to run in new worktree
+ run = {"make deps", "npm install"}
+ }
+}
+```
+
+
@@ -0,0 +1,38 @@
+# Converting Existing Repos
+
+```bash
+wt init [--dry-run] [-y]
+```
+
+Converts a standard git repository to bare worktree structure.
+
+## Options
+
+| Flag | Purpose |
+|------|---------|
+| `--dry-run` | Show what would happen without making changes |
+| `-y` | Skip confirmation prompt |
+
+## What It Does
+
+1. Moves `.git/` to `.bare/`
+2. Creates `.git` file pointing to `.bare/`
+3. Creates worktree for current branch
+4. Removes orphaned files from project root
+
+## Example
+
+```bash
+cd ~/repos/existing-project
+wt init --dry-run # preview changes
+wt init -y # convert without prompting
+```
+
+After conversion:
+
+```
+existing-project/
+├── .bare/ # was .git/
+├── .git # file pointing to .bare/
+└── main/ # worktree with your files
+```
@@ -0,0 +1,32 @@
+# Creating New Projects
+
+```bash
+wt n <project-name> [--remote name]...
+```
+
+Creates a fresh project with bare worktree structure:
+
+```
+my-project/
+├── .bare/ # git repository
+├── .git # file pointing to .bare/
+└── main/ # default worktree
+```
+
+## With Remotes
+
+Add configured remotes from `~/.config/wt/config.lua`:
+
+```bash
+wt n my-project --remote github --remote gitlab
+```
+
+Remotes use URL templates with `${project}` substituted:
+
+```lua
+remotes = {
+ github = "git@github.com:myuser/${project}.git"
+}
+```
+
+Results in remote URL `git@github.com:myuser/my-project.git`.