docs: define repository-group scoped execution with add-dir launch

Author: kdy1

docs/api.md

@@ -112,6 +112,12 @@ Request:
 Response:
 - `group: RepositoryGroup`
 
+Rules:
+
+1. `repository_ids` must contain at least one repository.
+2. `repository_ids` order is preserved exactly as provided.
+3. the first repository becomes the primary execution repository for agent runs.
+
 ### UpdateRepositoryGroup
 
 Request:
@@ -122,6 +128,12 @@ Request:
 Response:
 - `group: RepositoryGroup`
 
+Rules:
+
+1. when `repository_ids` is updated, it must contain at least one repository.
+2. execution order is updated to the new list order.
+3. the first repository in the updated list becomes the primary execution repository.
+
 ### DeleteRepositoryGroup
 
 Request:
@@ -193,6 +205,7 @@ Usage rule:
 2. request uses `type = PR_CREATE`
 3. prompt is `Create A PR` for the default PR creation action
 4. subtask execution output must include real git commits (one or more) when code changes exist
+5. execution resolves RepositoryGroup repositories, creates worktrees for each repo, and launches agent in the first repository with additional repositories attached via `--add-dir` (or equivalent option)
 
 ### ListSubTasks
 

docs/design.md

@@ -105,6 +105,7 @@ Core entities:
 ### UnitTask
 
 UnitTask is the top-level user-visible work item.
+Execution scope is one RepositoryGroup.
 
 ### SubTask
 
@@ -143,11 +144,20 @@ DeliDev does not support editing directly against arbitrary local folders.
 All code execution paths must:
 
 1. resolve repository through workspace-scoped repository settings
-2. materialize task-specific git worktree
-3. execute agent operations in that worktree
+2. materialize task-specific git worktrees for each repository in the target RepositoryGroup
+3. execute agent operations from the first repository worktree and attach other repository worktrees via `--add-dir` or equivalent option
 4. persist real git commit chain and commit metadata
 5. cleanup or archive worktree by retention policy
 
+## RepositoryGroup Execution Rule
+
+RepositoryGroup is the execution unit for agent runs.
+
+1. Worker creates one worktree per repository in the group.
+2. Repository order is preserved from `repositoryIds`.
+3. Agent process starts in the first repository worktree.
+4. Additional repositories are passed as extra directories using `--add-dir` (or agent-equivalent flags).
+
 ## PR Management
 
 PR management is part of the standard lifecycle:

docs/entities.md

@@ -183,10 +183,18 @@ enum StreamEventType {
 | id | UUID | Y | Group ID |
 | workspaceId | UUID | Y | Parent workspace |
 | name | string | Y | Group name |
-| repositoryIds | UUID[] | Y | Included repositories |
+| repositoryIds | UUID[] | Y | Ordered repositories (first item is primary execution repository) |
 | createdAt | timestamp | Y | Created time |
 | updatedAt | timestamp | Y | Updated time |
 
+RepositoryGroup execution semantics:
+
+1. RepositoryGroup is the unit of task execution scope.
+2. `repositoryIds` order is significant.
+3. repository group must contain at least one repository.
+4. the first repository is the primary execution repository.
+5. remaining repositories are attached as additional working directories for agent execution.
+
 ### UnitTask
 
 | Field | Type | Required | Description |

docs/main-server.md

@@ -55,14 +55,15 @@ Main server stores and owns:
 
 1. workspace records
 2. repository metadata and grouping
-3. UnitTask and SubTask state machines
-4. SubTask commit-chain metadata and commit ancestry
-5. AgentSession metadata and log pointers
-6. PR tracking state and auto-fix counters
-7. review assist items
-8. badge theme settings
-9. notification records
-10. event sequence offsets
+3. ordered RepositoryGroup membership and primary repository selection (first repository in group)
+4. UnitTask and SubTask state machines
+5. SubTask commit-chain metadata and commit ancestry
+6. AgentSession metadata and log pointers
+7. PR tracking state and auto-fix counters
+8. review assist items
+9. badge theme settings
+10. notification records
+11. event sequence offsets
 
 ## Task Orchestration Flow
 

docs/user-guide.md

@@ -17,6 +17,7 @@ This guide explains the DeliDev user workflow.
 1. open Repositories
 2. add repository remote URLs
 3. create RepositoryGroup for related repositories
+4. order repositories intentionally (first repository becomes primary agent execution repository)
 
 ## 3. Create a UnitTask
 

docs/worker-server.md

@@ -13,7 +13,7 @@ Worker Server executes SubTasks using AI coding agents in isolated worktree envi
 ## Execution Principles
 
 1. worktree-only execution
-2. one SubTask execution context per worktree
+2. one SubTask execution context per RepositoryGroup
 3. one or more AgentSession runs per SubTask
 4. deterministic cleanup policy by outcome
 
@@ -39,18 +39,20 @@ Worker Server executes SubTasks using AI coding agents in isolated worktree envi
 
 ## Worktree Lifecycle
 
-1. resolve repository from workspace and repository group context
-2. ensure repository cache is up to date
-3. create task-specific worktree path
-4. execute agent sessions in that worktree
-5. create and persist real git commits in branch history
-6. export patch and metadata derived from commits
-7. cleanup according to retention policy
+1. resolve ordered repositories from workspace and repository group context
+2. ensure each repository cache is up to date
+3. create task-specific worktree path for every repository in the group
+4. choose the first repository worktree as primary execution directory
+5. execute agent sessions in the primary directory
+6. pass remaining repository worktrees as `--add-dir` (or equivalent agent options)
+7. create and persist real git commits in branch history
+8. export patch and metadata derived from commits
+9. cleanup according to retention policy
 
 Path convention:
 
 - cache: `~/.delidev/repo-cache/<repo-hash>/`
-- worktree: `~/.delidev/worktrees/<unit-task-id>/<sub-task-id>/`
+- worktree: `~/.delidev/worktrees/<unit-task-id>/<sub-task-id>/<repo-id>/`
 
 ## SubTask and Session Flow
 
@@ -90,6 +92,14 @@ Worker output must be a real git commit chain.
 4. patch artifacts are generated from those commits for diff views
 5. PR creation and Commit to Local must consume commit-chain metadata, not patch-only output
 
+## Primary Repository Launch Rule
+
+Agent process launch uses the RepositoryGroup ordering rule.
+
+1. first repository in `repositoryIds` is the launch directory
+2. all other repositories are attached using `--add-dir` (or equivalent option per agent adapter)
+3. adapter command builders must preserve directory order when constructing arguments
+
 ## Agent Abstraction
 
 Worker uses adapter interfaces for multiple agents.
@@ -158,6 +168,7 @@ Emit structured logs for:
 5. artifact export
 6. usage checkpoints and final cost summary
 7. cancellation checkpoints
+8. primary repository selection and add-dir argument mapping
 
 ## Security Baseline