You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
4
+
5
+
## Why worktrees
6
+
7
+
| Problem with traditional clones | How worktrees solve it |
| Only one branch checked out at a time | Each issue gets its own worktree — parallel by default |
10
+
| Switching branches requires clean state | Worktrees are independent — no stashing or committing WIP |
11
+
| Agent work blocks human work on same repo | Different worktrees, no interference |
12
+
| Default branch gets dirty during development |`main/` worktree is always a clean reference |
13
+
14
+
## Repository layout
15
+
16
+
```text
17
+
<repo-root>/
18
+
├── .bare/ # bare git data (the actual repository)
19
+
├── .git # file containing: gitdir: ./.bare
20
+
├── main/ # worktree: default branch (always clean, never worked in directly)
21
+
├── 42-add-pagination/ # worktree: issue #42 in progress
22
+
└── 99-fix-null-ref/ # worktree: issue #99 in progress
23
+
```
24
+
25
+
-**`.bare/`** — the shared git object store. All worktrees share this.
26
+
-**`.git`** — a file (not a directory) that points git tooling to `.bare/`.
27
+
-**`main/`** — the default branch worktree. Kept as a clean reference. Used for diffing, reading docs, running comparisons. Never directly committed to.
28
+
-**`<N>-<slug>/`** — one worktree per issue in flight. Named by issue number and a short slug. Branch name matches the folder name.
29
+
30
+
## Remotes
31
+
32
+
Every repository has exactly two remotes (or one, if it is not a fork):
|**`origin`**| Our copy on the server | Always | Push branches, open PRs, CI runs against this. |
37
+
|**`upstream`**| The parent repo (forks only) | Forks | Track upstream changes, sync the default branch. |
38
+
39
+
No other remotes are added. This keeps the model simple and predictable for both humans and agents.
40
+
41
+
### How it works in practice
42
+
43
+
-**Non-fork repos** — only `origin` exists. Branches are pushed to `origin`, PRs are opened against `origin`.
44
+
-**Forked repos** — `origin` is our fork, `upstream` is the original repository. The default branch tracks `upstream` for syncing; feature branches are pushed to `origin` and PRs are opened from `origin` into `upstream`.
45
+
46
+
### Fetch configuration
47
+
48
+
Both remotes are configured with full refspecs so `git fetch --all --prune` keeps everything current:
> The [Checkout-GitHubRepo](https://github.com/MariusStorhaug/.dev/blob/main/.github/Checkout-GitHubRepo.ps1) script automates this for all repositories.
78
+
79
+
## Working on an issue
80
+
81
+
```powershell
82
+
# From the repo root (where .bare/ lives)
83
+
git -C .bare worktree add ../42-add-pagination -b 42-add-pagination main
84
+
85
+
# Open in VS Code
86
+
code 42-add-pagination
87
+
```
88
+
89
+
Then follow the normal Implement flow: initial commit → push → draft PR → build → finalize.
90
+
91
+
## Cleanup after merge
92
+
93
+
```powershell
94
+
# Remove the worktree
95
+
git -C .bare worktree remove 42-add-pagination
96
+
97
+
# Prune if needed (removes stale worktree references)
98
+
git -C .bare worktree prune
99
+
```
100
+
101
+
The sync script handles this automatically — worktrees whose branch no longer exists on any remote are removed during the next sync.
102
+
103
+
## Parallel agents
104
+
105
+
The worktree model enables multiple agents to work in the same repository at the same time:
106
+
107
+
- Each agent operates in its own worktree (its own issue folder).
108
+
- No merge conflicts during development — conflicts only surface at PR merge time.
109
+
- The default branch worktree provides a stable reference for all agents to read from.
110
+
- CI runs independently per PR, so agents don't block each other.
111
+
112
+
```text
113
+
Agent A: working in 42-add-pagination/
114
+
Agent B: working in 43-fix-auth-flow/
115
+
Human: reviewing in main/ or reading docs
116
+
```
117
+
118
+
## VS Code integration
119
+
120
+
-**Open the worktree folder directly** — VS Code's Git extension auto-detects the git context.
121
+
-**Multi-root workspace** — add multiple worktrees to one window (`File → Add Folder to Workspace`) to reference `main/` while coding in another.
122
+
-**Terminal cwd** — ensure the integrated terminal is in the worktree folder, not the bare root.
123
+
124
+
## Rules
125
+
126
+
1.**Never commit directly to the default branch worktree.** It exists for reference only.
127
+
2.**One worktree per issue.** The folder name matches the branch name: `<N>-<slug>`.
128
+
3.**Clean up after merge.** Remove the worktree and let the sync script prune stale branches.
129
+
4.**All git config lives in `.bare/`** — it applies to every worktree automatically.
130
+
5.**Only `origin` and `upstream` remotes.** No other remotes. `upstream` only exists for forks.
Copy file name to clipboardExpand all lines: docs/Agents/Workflow.md
+69-72Lines changed: 69 additions & 72 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,78 +7,74 @@ How the agent roles connect across the **Context Development Lifecycle (CDLC)**
7
7
The CDLC and the SDLC run side by side. The CDLC keeps **context** evergreen — issues, decisions, READMEs, docs. The SDLC delivers **software** — code, tests, releases. Each iteration of one feeds the other.
> A richer visual version of this diagram lives in Figma (linked from the homepage). Mermaid covers the structure; the Figma version covers the relationships between CDLC, SDLC, and operations.
48
+
## The agents
44
49
45
-
##The roles in order
50
+
### Define
46
51
47
-
### 1. Capture — Ideator
52
+
Combines **capture**, **refine**, and **plan** into a single flow. Takes any input — a desire, a bug, a signal — and produces a planned, actionable issue.
48
53
49
-
A desire becomes a real, actionable item. Could be a feature request, a bug, an improvement, a triaged piece of external feedback, or a signal from production. Output: an issue with Section 1 only.
54
+
**Output is one of:**
50
55
51
-
### 2. Refine — Clarifier
56
+
- A single Task with Sections 1–3 (context, decisions, checklist).
57
+
- A decomposed PBI or Epic with structured sub-issues, each scoped to one PR.
52
58
53
-
The desire is grounded. Assumptions surfaced. Acceptance criteria sharpened to be testable. Section 1 becomes unambiguous. No solutioning yet.
59
+
See [Issue Format](Issue-Format.md) and [Issue Hierarchy](Issue-Hierarchy.md) for the structure.
54
60
55
-
### 3. Plan — Planner
61
+
### Implement
56
62
57
-
The work is decided and (often) decomposed.
63
+
Takes a planned issue and delivers a merge-ready pull request. Owns the full loop:
58
64
59
-
-**Task** — one deliverable, one PR. Sections 2 and 3 populated.
-**Epic** — several PBIs. Top-level co-planning artifact, often paired with an OKR.
65
+
1.**Orient** — read the issue, README, contribution guide, and standards.
66
+
2.**Branch and draft PR** — create a [worktree](Git-Worktrees.md) for the issue, push early so CI attaches and progress is visible. Assign to the user. Link to the issue.
67
+
3.**Build** — micro-commits, one logical change each. Update the issue as each task completes (not in bulk).
68
+
4.**Respond** — process reviewer feedback and CI failures. One thread at a time.
69
+
5.**Finalize** — update PR title, labels, and description as a user-facing release note.
62
70
63
-
Issue hierarchy is described in [Issue Hierarchy](Issue-Hierarchy.md).
71
+
See [Git Worktrees](Git-Worktrees.md), [PR Format](PR-Format.md), [Commit Conventions](Commit-Conventions.md), and [Standards](Standards/index.md).
64
72
65
-
### 4. Build — Builder
73
+
### Reviewer
66
74
67
-
Code is written. The Task issue is the contract. Standards come from [Standards](Standards/index.md); linter rules in the repo win. Commits are small and descriptive.
75
+
Reviews someone else's PR. Checks delivery against the linked issue, good taste, security, and undiscussed decisions.
68
76
69
-
### 5. Ship — Shipper
70
-
71
-
The branch becomes a draft PR with a release-note style description. Issue linked, labels applied, reviewers requested.
72
-
73
-
### 6. Review — Reviewer
74
-
75
-
Someone other than the author reads the PR with intent: does it deliver the issue, is the code in good taste, are the security best practices respected, are there undiscussed decisions hiding in the diff?
76
-
77
-
### 7. Respond — Responder
78
-
79
-
The author closes the loop. One thread at a time: read, evaluate, fix or defer, reply, resolve. CI failures handled similarly. Repeat until the loop converges.
80
-
81
-
After merge, the change runs in production. Signals — errors, logs, user feedback, alerts — feed back into the Ideator. The loop never really stops.
77
+
See [Review Etiquette](Review-Etiquette.md).
82
78
83
79
## Three horizons of planning
84
80
@@ -96,18 +92,19 @@ Borrowed from [Principles → Roadmapping](Principles.md#roadmapping). The plann
0 commit comments