Create and manage long-running agent task workspaces for cross-codebase work. Use when: (1) Starting a new long-running task that spans multiple repos (e.g., "document all services"), (2) Tracking progress on bulk operations (fix all Sentry issues, handle Renovate PRs), (3) Resuming work on a previously started cross-codebase task, (4) Organizing work that shouldn't pollute individual repo git histories. Location: ~/git/agent-workspace/<task-name>/
Workspaces provide isolated tracking for long-running, cross-codebase agent tasks without polluting individual repository git histories.
NEVER start creating a workspace without user input. If the user provides only a task name (e.g., "create acd-documentation"), you MUST ask them for the required information before proceeding.
Ask the user these questions before creating the workspace:
User: create acd-documentation workspace
Agent: I'll help you set up the ACD documentation workspace. First, I need to understand the task:
1. **Goal**: What should these ACD documents contain? (e.g., architecture overview, data flows, dependencies)
2. **Scope**: Which organizations/repos? All of dxp? Specific services only?
3. **Output**: Where should the docs live? (e.g., `docs/ARCHITECTURE.md` in each repo, PRs)
4. **Validation**: What makes an ACD "complete"? (e.g., specific sections required, review needed)
Only after receiving answers, create the workspace with the README and tasklist.
~/git/agent-workspace/
├── <task-name>/
│ ├── README.md # Task definition (answers all required questions)
│ └── tasklist.md # Progress tracking with validation status
└── ...
mkdir -p ~/git/agent-workspace/<task-name>
The README must answer all these questions before work begins:
# <Task Name>
## Goal
<One sentence describing what success looks like>
## Required Questions
### What repos need to be cloned?
- [ ] List all repositories required for this task
- [ ] Specify organization (dxp, hyperspace, platform-mesh, openmfp)
- [ ] Note any repos that must be at specific branches
| Repo | Org | Branch | Purpose |
|------|-----|--------|---------|
| repo-name | dxp | main | <why needed> |
### Where should the task be performed?
- **Working directory**: <where agent should cd to for each item>
- **Output location**: <where artifacts are created>
- PRs to target repos
- Docs to specific locations
- Reports to workspace
### What needs to be performed?
For each item in the tasklist:
1. <Specific step 1>
2. <Specific step 2>
3. <Specific step 3>
### Which claude-knowledge agents/skills should be used?
Reference agents from `~/git/dxp/claude-knowledge/.claude/agents/`:
| Agent | When to Use |
|-------|-------------|
| repo-analyzer | First pass to understand each repo |
| repo-documenter | Generate documentation |
| developer | Make code changes |
| git | Commit and create PRs |
Reference skills from `~/git/dxp/claude-knowledge/.claude/skills/`:
| Skill | When to Use |
|-------|-------------|
| /commit | Creating commits |
| /pr-review | Reviewing changes |
### How is completion validated?
**Per-item validation** (checked after each item):
- [ ] <Validation criterion 1>
- [ ] <Validation criterion 2>
- [ ] <Validation criterion 3>
**Task-level validation** (checked at end):
- [ ] <Overall success criterion>
## Scope
- **Included**: <what qualifies>
- **Excluded**: <what is explicitly out of scope>
## Context
<Background information for resuming work>
## Notes
<Running notes added during execution>
# <Task Name> - Task List
## Status Legend
| Symbol | Meaning |
|--------|---------|
| `[ ]` | Not started |
| `[~]` | In progress |
| `[x]` | Complete - validated |
| `[?]` | Complete - needs validation |
| `[!]` | Blocked |
| `[-]` | Skipped (with reason) |
## Summary
- **Total**: X items
- **Complete**: Y items
- **Validated**: Z items
- **Remaining**: W items
- **Last updated**: YYYY-MM-DD
## Items
### <Category>
| Status | Item | Validation | Notes |
|--------|------|------------|-------|
| [ ] | item-name | | |
| [x] | done-item | PR #123 merged | Validated 2024-01-15 |
| [?] | needs-check | PR #456 open | Needs review |
| [!] | blocked-item | | Waiting on X |
[x] with validation evidence[?] with what's pending[?] items needing validation first[?] items before starting new work[ ] item to start[x] or [-]# List all repos in an org
gh repo list dxp --limit 1000 --json name,isArchived \
--jq '.[] | select(.isArchived == false) | .name' \
--hostname github.tools.sap
Use mcp__sentry__list_issues to get issues, add to tasklist with issue URLs.
gh search prs --owner dxp --author "renovate[bot]" --state open \
--json repository,number,title --hostname github.tools.sap
# ACD Documentation for DXP Services
## Goal
Create Architecture Concept Documents for all DXP microservices.
## Required Questions
### What repos need to be cloned?
| Repo | Org | Branch | Purpose |
|------|-----|--------|---------|
| iam-service | dxp | main | Document this service |
| extension-manager-service | dxp | main | Document this service |
| claude-knowledge | dxp | main | Reference for agents/templates |
### Where should the task be performed?
- **Working directory**: Each target repo (`~/git/dxp/<repo>/`)
- **Output location**: PR to each repo adding `docs/ARCHITECTURE.md`
### What needs to be performed?
For each service:
1. Clone/update the repo
2. Run repo-analyzer agent to understand structure
3. Run repo-documenter agent with ACD template
4. Create PR with the documentation
5. Validate against checklist
### Which claude-knowledge agents/skills should be used?
| Agent | When to Use |
|-------|-------------|
| repo-analyzer | Understand repo structure and purpose |
| repo-documenter | Generate the ACD document |
| git | Create branch and PR |
### How is completion validated?
**Per-item validation:**
- [ ] `docs/ARCHITECTURE.md` exists in PR
- [ ] Document covers: Purpose, Components, Dependencies, Data Flow
- [ ] PR CI passes
- [ ] No placeholder text remaining
**Task-level validation:**
- [ ] All non-archived services have ACDs
- [ ] Consistent format across all documents
# ACD Documentation - Task List
## Summary
- **Total**: 15 services
- **Complete**: 3
- **Validated**: 2
- **Remaining**: 12
- **Last updated**: 2024-01-15
## Items
### Core Services
| Status | Item | Validation | Notes |
|--------|------|------------|-------|
| [x] | iam-service | PR #45 merged | |
| [x] | extension-manager-service | PR #112 merged | |
| [?] | portal-service | PR #78 open | Awaiting review |
| [ ] | content-service | | |
### Operators
| Status | Item | Validation | Notes |
|--------|------|------------|-------|
| [ ] | flux-operator | | |
| [ ] | account-operator | | |
[?] for unvalidated work[?] items on resume - Validate pending items before new workNEVER spawn more than 5 agents in parallel per main task. Exceeding this limit will crash Claude.
<!-- ✅ CORRECT: 5 or fewer parallel agents -->
Spawning agents for: repo-1, repo-2, repo-3, repo-4, repo-5
[Wait for completion]
Spawning agents for: repo-6, repo-7, repo-8
<!-- ❌ FORBIDDEN: More than 5 parallel agents -->
Spawning agents for: repo-1, repo-2, repo-3, repo-4, repo-5, repo-6, repo-7, repo-8
[CRASH]
When processing many items, batch them into groups of 5:
## Batch Execution
### Batch 1 (items 1-5)
- [ ] item-1 → agent spawned
- [ ] item-2 → agent spawned
- [ ] item-3 → agent spawned
- [ ] item-4 → agent spawned
- [ ] item-5 → agent spawned
[Wait for all to complete before continuing]
### Batch 2 (items 6-10)
- [ ] item-6 → agent spawned
- [ ] item-7 → agent spawned
...