tas/Codewalkers
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: Rename agent modes breakdown→plan, decompose→detail

Browse Source 
Full rename across the codebase for clarity:
- breakdown (initiative→phases) is now "plan"
- decompose (phase→tasks) is now "detail"

Updates schema enums, TypeScript types, events, prompts, output handler,
tRPC procedures, CLI commands, frontend components, tests, and docs.
Also fixes 0022 migration multi-statement issue (adds statement-breakpoint markers).
This commit is contained in:
Lukas May
2026-02-10 10:51:42 +01:00
parent f9f8b4c185
commit 0407f05332
51 changed files with 551 additions and 483 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/agent.md
View File

@@ -9,7 +9,7 @@
| `types.ts` | Core types: `AgentInfo`, `AgentManager` interface, `SpawnOptions`, `StreamEvent` |
| `manager.ts` | `MultiProviderAgentManager` — main orchestrator class |
| `process-manager.ts` | `AgentProcessManager` — worktree creation, command building, detached spawn |
| `output-handler.ts` | `OutputHandler` — JSONL stream parsing, completion detection, proposal creation |
| `output-handler.ts` | `OutputHandler` — JSONL stream parsing, completion detection, proposal creation, task dedup |
| `file-tailer.ts` | `FileTailer` — watches output files, emits line events |
| `file-io.ts` | Input/output file I/O: frontmatter writing, signal.json reading, tiptap conversion |
| `markdown-to-tiptap.ts` | Markdown to Tiptap JSON conversion using MarkdownManager |
@@ -24,7 +24,7 @@
| `accounts/` | Account discovery, config dir setup, credential management, usage API |
| `credentials/` | `AccountCredentialManager` — credential injection per account |
| `lifecycle/` | `LifecycleController` — retry policy, signal recovery, missing signal instructions |
| `prompts/` | Mode-specific prompt builders (execute, discuss, breakdown, decompose, refine) |
| `prompts/` | Mode-specific prompt builders (execute, discuss, plan, detail, refine) |
## Key Flows

4
docs/cli-config.md
View File

@@ -65,8 +65,8 @@ Uses **Commander.js** for command parsing.
| Command | Description |
|---------|-------------|
| `discuss <initiativeId> [-c context]` | Start discussion agent |
| `breakdown <initiativeId> [-s summary]` | Start breakdown agent |
| `decompose <phaseId> [-t taskName] [-c context]` | Decompose phase into tasks |
| `plan <initiativeId> [-s summary]` | Start plan agent |
| `detail <phaseId> [-t taskName] [-c context]` | Detail phase into tasks |
### Phase (`cw phase`)
| Command | Description |

7
docs/database.md
View File

@@ -20,7 +20,7 @@ All adapters use nanoid() for IDs, auto-manage timestamps, and use Drizzle's `.r
| name | text NOT NULL | |
| status | text enum | 'active' \| 'completed' \| 'archived', default 'active' |
| mergeRequiresApproval | integer/boolean | default true |
| mergeTarget | text nullable | target branch for merges |
| branch | text nullable | auto-generated initiative branch (e.g., 'cw/user-auth') |
| createdAt, updatedAt | integer/timestamp | |
### phases
@@ -46,7 +46,7 @@ All adapters use nanoid() for IDs, auto-manage timestamps, and use Drizzle's `.r
| name | text NOT NULL | |
| description | text nullable | |
| type | text enum | 'auto' \| 'checkpoint:human-verify' \| 'checkpoint:decision' \| 'checkpoint:human-action' |
| category | text enum | 'execute' \| 'research' \| 'discuss' \| 'breakdown' \| 'decompose' \| 'refine' \| 'verify' \| 'merge' \| 'review' |
| category | text enum | 'execute' \| 'research' \| 'discuss' \| 'plan' \| 'detail' \| 'refine' \| 'verify' \| 'merge' \| 'review' |
| priority | text enum | 'low' \| 'medium' \| 'high' |
| status | text enum | 'pending_approval' \| 'pending' \| 'in_progress' \| 'completed' \| 'blocked' |
| requiresApproval | integer/boolean nullable | null = inherit from initiative |
@@ -68,7 +68,7 @@ All adapters use nanoid() for IDs, auto-manage timestamps, and use Drizzle's `.r
| provider | text NOT NULL | default 'claude' |
| accountId | text nullable FK → accounts (set null) | |
| status | text enum | 'idle' \| 'running' \| 'waiting_for_input' \| 'stopped' \| 'crashed' |
| mode | text enum | 'execute' \| 'discuss' \| 'breakdown' \| 'decompose' \| 'refine' |
| mode | text enum | 'execute' \| 'discuss' \| 'plan' \| 'detail' \| 'refine' |
| pid | integer nullable | OS process ID |
| exitCode | integer nullable | |
| outputFilePath | text nullable | |
@@ -122,6 +122,7 @@ All adapters use nanoid() for IDs, auto-manage timestamps, and use Drizzle's `.r
| id | text PK | |
| name | text NOT NULL UNIQUE | |
| url | text NOT NULL UNIQUE | git repo URL |
| defaultBranch | text NOT NULL | default 'main' |
| createdAt, updatedAt | integer/timestamp | |
### initiative_projects (junction)

2
docs/dispatch-events.md
View File

@@ -32,7 +32,7 @@
AgentSpawnedEvent { agentId, name, taskId, worktreeId, provider }
AgentStoppedEvent { agentId, name, taskId, reason }
// reason: 'user_requested'|'task_complete'|'error'|'waiting_for_input'|
// 'context_complete'|'breakdown_complete'|'decompose_complete'|'refine_complete'
// 'context_complete'|'plan_complete'|'detail_complete'|'refine_complete'
AgentWaitingEvent { agentId, name, taskId, sessionId, questions[] }
AgentOutputEvent { agentId, stream, data }
TaskCompletedEvent { taskId, agentId, success, message }

10
docs/frontend.md
View File

@@ -63,7 +63,7 @@ The initiative detail page has three tabs managed via local state (not URL param
|-----------|---------|
| `ExecutionTab` | Main execution view container |
| `ExecutionContext` | React context for execution state |
| `PhaseDetailPanel` | Phase detail with tasks, dependencies, breakdown |
| `PhaseDetailPanel` | Phase detail with tasks, dependencies, plan |
| `PhaseSidebar` | Phase list sidebar |
| `TaskDetailPanel` | Task detail with agent status, output |
@@ -88,7 +88,7 @@ shadcn/ui components: badge, button, card, dialog, dropdown-menu, input, label,
| Hook | Purpose |
|------|---------|
| `useRefineAgent` | Manages refine agent lifecycle for initiative |
| `useDecomposeAgent` | Manages decompose agent for phase breakdown |
| `useDetailAgent` | Manages detail agent for phase planning |
| `useAgentOutput` | Subscribes to live agent output stream |
## tRPC Client
@@ -120,9 +120,9 @@ Configured in `src/lib/trpc.ts`. Uses `@trpc/react-query` with TanStack Query fo
3. Approve phases → queue for dispatch
4. Tasks auto-queued when phase starts
### Decomposing Phases
1. Select phase → "Breakdown" button
2. `spawnArchitectDecompose` mutation → agent creates task proposals
### Detailing Phases
1. Select phase → "Detail" button
2. `spawnArchitectDetail` mutation → agent creates task proposals
3. Accept proposals → tasks created under phase
4. View tasks in phase detail panel

10
docs/server-api.md
View File

@@ -87,7 +87,7 @@ Each procedure uses `require*Repository(ctx)` helpers that throw `TRPCError(INTE
| listInitiatives | query | Filter by status |
| getInitiative | query | With projects array |
| updateInitiative | mutation | Name, status |
| updateInitiativeMergeConfig | mutation | mergeRequiresApproval, mergeTarget |
| updateInitiativeConfig | mutation | mergeRequiresApproval, executionMode |
### Phases
| Procedure | Type | Description |
@@ -98,7 +98,7 @@ Each procedure uses `require*Repository(ctx)` helpers that throw `TRPCError(INTE
| updatePhase | mutation | Name, content, status |
| approvePhase | mutation | Validate and approve |
| deletePhase | mutation | Cascade delete |
| createPhasesFromBreakdown | mutation | Bulk create from agent output |
| createPhasesFromPlan | mutation | Bulk create from agent output |
| createPhaseDependency | mutation | Add dependency edge |
| removePhaseDependency | mutation | Remove dependency edge |
| listInitiativePhaseDependencies | query | All dependency edges |
@@ -111,15 +111,15 @@ Each procedure uses `require*Repository(ctx)` helpers that throw `TRPCError(INTE
| queuePhase | mutation | Queue approved phase |
| dispatchNextPhase | mutation | Start next ready phase |
| getPhaseQueueState | query | Queue state |
| createChildTasks | mutation | Create tasks from decompose parent |
| createChildTasks | mutation | Create tasks from detail parent |
### Architect (High-Level Agent Spawning)
| Procedure | Type | Description |
|-----------|------|-------------|
| spawnArchitectDiscuss | mutation | Discussion agent |
| spawnArchitectBreakdown | mutation | Breakdown agent (generates phases). Passes full initiative context (existing phases, tasks, pages) |
| spawnArchitectPlan | mutation | Plan agent (generates phases). Passes full initiative context (existing phases, tasks, pages) |
| spawnArchitectRefine | mutation | Refine agent (generates proposals) |
| spawnArchitectDecompose | mutation | Decompose agent (generates tasks). Passes full initiative context (sibling phases, tasks, pages) |
| spawnArchitectDetail | mutation | Detail agent (generates tasks). Passes full initiative context (sibling phases, tasks, pages) |
### Dispatch
| Procedure | Type | Description |

4
docs/testing.md
View File

@@ -22,8 +22,8 @@ Located alongside source files (`*.test.ts`):
| File | Scenarios |
|------|-----------|
| `happy-path.test.ts` | Single task, parallel, complex flows |
| `architect-workflow.test.ts` | Discussion + breakdown agent workflows |
| `decompose-workflow.test.ts` | Task decomposition with child tasks |
| `architect-workflow.test.ts` | Discussion + plan agent workflows |
| `detail-workflow.test.ts` | Task detail with child tasks |
| `phase-dispatch.test.ts` | Phase-level dispatch with dependencies |
| `recovery-scenarios.test.ts` | Crash recovery, agent resume |
| `edge-cases.test.ts` | Boundary conditions |