diff --git a/src/docs/Dictionary/index.md b/src/docs/Dictionary/index.md index 23d3c1e..c93a066 100644 --- a/src/docs/Dictionary/index.md +++ b/src/docs/Dictionary/index.md @@ -41,6 +41,10 @@ The *how* of a capability: the approach and the thing built, kept beside its spe Guidance written to be declarative and directional — it states what must be true and the direction to move, and leaves the *how* to the doer. Standards, principles, and specs are written as directives. +### Git Worktree + +A checkout of a branch in its own directory, backed by a single bare clone that every worktree shares — so several branches are checked out at once, each in its own folder. It is purely a *local development* convenience: it lets one person, a person and an agent, or several agents work on multiple issues in the same repository in parallel, with no stashing or branch-switching. It changes nothing about how a repository is built, reviewed, or shipped. See [Git Worktrees](../Ways-of-Working/Git-Worktrees.md). + ### Initiative A product that makes the vision real — a framework, a set of reusable actions, or an editor extension. See [Initiatives](../Initiatives/index.md). diff --git a/src/docs/Ways-of-Working/Agentic-Development.md b/src/docs/Ways-of-Working/Agentic-Development.md index 6a17ea8..184f70d 100644 --- a/src/docs/Ways-of-Working/Agentic-Development.md +++ b/src/docs/Ways-of-Working/Agentic-Development.md @@ -86,8 +86,11 @@ The workspace is a git-isolated clone of the central repositories under `~/.msx` 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. + ## Where this connects +- [Git Worktrees](Git-Worktrees.md) — how this framework is implemented on a local machine, so several pieces of work run in parallel. - [Documentation Model](Documentation-Model.md) — the discipline this specification follows. - [Principles](Principles/index.md) — the beliefs this specification rests on, including the three-layer agent context model. - [README-Driven Context](Readme-Driven-Context.md) — why the repository's own context comes first. diff --git a/src/docs/Ways-of-Working/Git-Worktrees.md b/src/docs/Ways-of-Working/Git-Worktrees.md index 69f19fd..e0f6efa 100644 --- a/src/docs/Ways-of-Working/Git-Worktrees.md +++ b/src/docs/Ways-of-Working/Git-Worktrees.md @@ -1,11 +1,13 @@ --- title: Git Worktrees -description: Bare-clone and worktree layout for parallel, conflict-free work. +description: How agentic development is implemented locally — a bare-clone and worktree layout for working on several things at once. --- # 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. + +All repositories are set up as **bare clones with worktrees**. Each piece of work gets its own worktree — an independent working directory for one branch — so parallel work never collides. ## Why worktrees @@ -117,3 +119,9 @@ git -C .bare branch -D 42-add-pagination # Prune if needed (removes stale worktree references) git -C .bare worktree prune ``` + +## Where this connects + +- [Agentic Development](Agentic-Development.md) — the framework these worktrees implement locally, so several pieces of work run in parallel. +- [Branching and Merging](Branching-and-Merging.md) — the branch-per-issue model each worktree holds. +- [Workflow](Workflow.md) — where creating a worktree fits in the flow from issue to delivery. diff --git a/src/docs/Ways-of-Working/index.md b/src/docs/Ways-of-Working/index.md index 74e1608..b1fa8c1 100644 --- a/src/docs/Ways-of-Working/index.md +++ b/src/docs/Ways-of-Working/index.md @@ -22,6 +22,7 @@ This section documents the principles, processes, and norms that every contribut | [Spec-Driven Development](Spec-Driven-Development.md) | The specification is the source of truth — the spec (why and what), its design (how), and how a change moves from need to shipped. | | [Evolutionary Development](Evolutionary-Development.md) | Grow software as bets under selection — variation, feedback, and survival of the fittest, run as one tight loop. | | [Agentic Development](Agentic-Development.md) | How ways of working, standards, and documentation are authored once and consumed by both humans and agents. | +| [Git Worktrees](Git-Worktrees.md) | How agentic development is implemented locally — a bare-clone and worktree layout for working on several things at once. | | [Organization Standard](Organization-Standard.md) | What every initiative organization must define centrally so humans and agents share the same expectations. | | [Repository Standard](Repository-Standard.md) | The baseline files and behaviours every repository must expose so it is understandable, secure, and maintainable. | | [Principles](Principles/index.md) | The foundational beliefs and product mindset behind every decision. | @@ -36,7 +37,6 @@ This section documents the principles, processes, and norms that every contribut | [Review Etiquette](Review-Etiquette.md) | Tone, scope, severity, and how to disagree well. | | [Repository Segmentation](Repository-Segmentation.md) | What belongs in a repository, and when to split or combine. | | [README-Driven Context](Readme-Driven-Context.md) | Why the README is the front door and the source of truth. | -| [Git Worktrees](Git-Worktrees.md) | Bare-clone and worktree layout for parallel, conflict-free work. | | [Continuous Practices](Continuous-Practices.md) | The Continuous X family, Continuous AI, and the DevOps Dojo pillars. | | [DevOps Reference](DevOps-Reference.md) | A curated reading list and the principles behind how we work. | diff --git a/src/zensical.toml b/src/zensical.toml index 7b33d0e..e45e900 100644 --- a/src/zensical.toml +++ b/src/zensical.toml @@ -31,7 +31,10 @@ nav = [ {"Documentation Model" = "Ways-of-Working/Documentation-Model.md"}, {"Spec-Driven Development" = "Ways-of-Working/Spec-Driven-Development.md"}, {"Evolutionary Development" = "Ways-of-Working/Evolutionary-Development.md"}, - {"Agentic Development" = "Ways-of-Working/Agentic-Development.md"}, + {"Agentic Development" = [ + "Ways-of-Working/Agentic-Development.md", + {"Git Worktrees" = "Ways-of-Working/Git-Worktrees.md"}, + ]}, {"Organization Standard" = "Ways-of-Working/Organization-Standard.md"}, {"Repository Standard" = "Ways-of-Working/Repository-Standard.md"}, {"Principles" = [ @@ -54,7 +57,6 @@ nav = [ {"Review Etiquette" = "Ways-of-Working/Review-Etiquette.md"}, {"Repository Segmentation" = "Ways-of-Working/Repository-Segmentation.md"}, {"README-Driven Context" = "Ways-of-Working/Readme-Driven-Context.md"}, - {"Git Worktrees" = "Ways-of-Working/Git-Worktrees.md"}, {"Continuous Practices" = "Ways-of-Working/Continuous-Practices.md"}, {"DevOps Reference" = "Ways-of-Working/DevOps-Reference.md"}, ]},