📖 [Docs]: Git Worktree added to the Dictionary and framed as local agentic development#41
Merged
Marius Storhaug (MariusStorhaug) merged 1 commit intoJul 13, 2026
Conversation
Marius Storhaug (MariusStorhaug)
added
the
documentation
Copilot started reviewing on behalf of
Marius Storhaug (MariusStorhaug)
July 13, 2026 10:30
View session
Marius Storhaug (MariusStorhaug)
marked this pull request as ready for review
July 13, 2026 10:30
There was a problem hiding this comment.
Pull request overview
This PR updates the documentation structure so Git Worktrees are defined in the Dictionary and presented as the local implementation detail of Agentic Development, rather than a standalone “Ways of Working” item—while keeping existing URLs intact.
Changes:
- Added a Git Worktree term to the Dictionary with a pointer to the full Git Worktrees guide.
- Reframed Git Worktrees and Agentic Development pages to cross-link and clarify “local-only” worktree semantics.
- Updated site/navigation and regenerated the Ways of Working index so Git Worktrees is nested under Agentic Development.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| src/zensical.toml | Nests “Git Worktrees” under “Agentic Development” in navigation and removes the previous flat nav entry. |
| src/docs/Ways-of-Working/index.md | Regenerated index table to place “Git Worktrees” directly after “Agentic Development” with updated description. |
| src/docs/Ways-of-Working/Git-Worktrees.md | Rewrites intro/description to frame worktrees as the local mechanics of agentic development; adds “Where this connects”. |
| src/docs/Ways-of-Working/Agentic-Development.md | Adds a bridging paragraph and cross-link to Git Worktrees in the “workspace bootstrap” section. |
| src/docs/Dictionary/index.md | Adds “Git Worktree” definition between “Directive” and “Initiative”, linking to the guide. |
| # Git Worktrees | ||
|
|
||
| All repositories are set up as **bare clones with worktrees**. This enables parallel work — multiple agents (or a human and an agent) can work on different issues in the same repository simultaneously without conflicts, stashing, or context-switching. | ||
| Git worktrees are how [agentic development](Agentic-Development.md) is implemented on a local machine. They are purely a **local development** convenience: a way for one person — or a person and an agent, or several agents — to work on multiple issues in the same repository at the same time, without stashing, committing half-finished work, or switching branches. They change nothing about how a repository is built, reviewed, or shipped — that still happens through branches and pull requests, exactly as it would with an ordinary clone. |
|
|
||
| Each clone carries repository-local git config only, so the workspace never modifies the global git config or the repository the agent is working in — git still reads them, but only repository-local config is written. The setup is one idempotent script — [`bootstrap/Initialize-MsxWorkspace.ps1`](https://github.com/MSXOrg/docs/blob/main/bootstrap/Initialize-MsxWorkspace.ps1) — that clones what is missing and attempts to fast-forward the rest, leaving a repository as-is if it cannot. This keeps "start at the same point" literal: every agent, in every repository, begins from the same local docs and memory. | ||
|
|
||
| The workspace makes the *central* context present locally; the same local-first stance shapes how each working repository is laid out. Repositories are cloned as [git worktrees](Git-Worktrees.md) — one working directory per branch — so a person and an agent, or several agents, can work on multiple issues in the same repository at once without stashing or switching branches. |
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Jul 13, 2026
) ## What Adds a **"Why this matters: working agentically in parallel"** section to the Git Worktrees page, stating plainly why the bare-clone + worktree layout is the default for local development: running several agents at once, each on a different issue in its own worktree. ## Why Follow-up to #41. That page covered the mechanics (layout, remotes, setup, cleanup) but under-stated *why* worktrees are the default rather than an occasional convenience. Reviewing how `ai-platform` uses worktrees in practice — its `buildit` orchestrator fans out one worktree per topic and dispatches builder agents **in parallel**, integrating through the normal branch/PR flow — the defining value is parallel agentic work on multiple issues at the same time. This makes that explicit. ## Change - New section framing worktrees around parallelism: one worktree per issue / one agent per worktree; no stashing, branch-switching, or waiting; fan out then integrate. - Reuses the existing `#42`/`#99` worktree examples and links to Agentic Development and Branching and Merging. - No nav or structural changes; existing content untouched. Index check, link check, and markdownlint all pass locally.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Readers and agents now find Git worktree defined in the Dictionary, and the Git Worktrees guide is presented as part of Agentic Development — the local mechanics behind how the framework runs on a developer's machine — rather than as a standalone way of working. Worktrees are clarified as a purely local convenience for working on several things at once; they change nothing about how repositories are built, reviewed, or shipped.
New: "Git Worktree" in the Dictionary
The Dictionary gains a Git Worktree entry (alphabetically, between Directive and Initiative): a checkout of a branch in its own directory, backed by a single shared bare clone, used purely as a local development convenience for working on multiple issues in parallel. It links to the full Git Worktrees guide.
Changed: Git Worktrees now sits with Agentic Development
The Git Worktrees page is reframed as how agentic development is implemented locally and is nested under Agentic Development in the navigation (and grouped with it in the Ways of Working index). Agentic Development and Git Worktrees now link to each other, so the connection between the framework and its local implementation is explicit. The page keeps its address, so existing links and bookmarks continue to work.
Technical Details
src/docs/Dictionary/index.md— new Git Worktree term, linking to the Git Worktrees guide.src/docs/Ways-of-Working/Git-Worktrees.md— rewritten intro anddescriptionto frame worktrees as the local implementation of agentic development and emphasise their local-only, parallel-work purpose; added a Where this connects section.src/docs/Ways-of-Working/Agentic-Development.md— added a bridging paragraph in The workspace bootstrap and a Where this connects bullet pointing to Git Worktrees.src/zensical.toml— Git Worktrees is nested under the Agentic Development nav entry, reusing the existingnavigation.indexeslanding-page pattern (mirroringPrinciples); the flat entry is removed.src/docs/Ways-of-Working/index.md— regenerated byUpdate-DocumentationIndex.ps1; Git Worktrees now orders directly after Agentic Development.Ways-of-Working/so its URL and every inbound link (Branching-and-Merging,Fleet-Orchestration,Workflow,Agents/implement, rootAGENTS.md) keep working; the "move" is expressed through nav nesting and reframing. A full physical move into anAgentic-Development/subsection is a possible follow-up if preferred.Update-DocumentationIndex.ps1 -Check,Test-DocumentationLink.ps1, and markdownlint all pass. Localzensical buildcould not run (the pinned0.0.46is unavailable on this machine's package index), so the CI Build job is the authoritative render check.Related issues