@gw-tools/autonomous-workflow-agent 2.0.0 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -1,6 +1,40 @@
|
|
|
1
1
|
# @gw-tools/autonomous-workflow-agent
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Ship features while you sleep.** Give this agent a task description and walk away—it handles everything from planning to PR creation, all in an isolated Git worktree that won't touch your working branch.
|
|
4
|
+
|
|
5
|
+
```typescript
|
|
6
|
+
import { autonomousWorkflowAgent } from '@gw-tools/autonomous-workflow-agent';
|
|
7
|
+
|
|
8
|
+
// That's it. Your agent now knows how to ship complete features autonomously.
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Built on gw-tools
|
|
12
|
+
|
|
13
|
+
This agent is powered by the [gw CLI](https://github.com/mthines/gw-tools)—a Git worktree management tool that handles branch isolation, file syncing, and cleanup. The agent orchestrates `gw` commands to create isolated development environments for each task.
|
|
14
|
+
|
|
15
|
+
## The Problem
|
|
16
|
+
|
|
17
|
+
Building features with AI agents today is frustrating:
|
|
18
|
+
|
|
19
|
+
- **Context loss** — Agents forget what they're doing mid-task
|
|
20
|
+
- **No isolation** — Changes happen in your working directory, blocking your flow
|
|
21
|
+
- **Incomplete work** — You get code dumps, not tested PRs
|
|
22
|
+
- **Manual babysitting** — You're constantly re-prompting and fixing mistakes
|
|
23
|
+
|
|
24
|
+
## The Solution
|
|
25
|
+
|
|
26
|
+
This agent implements a battle-tested 8-phase workflow that turns "implement X" into a ready-to-review PR:
|
|
27
|
+
|
|
28
|
+
1. **Validates** the task with you before writing any code
|
|
29
|
+
2. **Plans** the implementation by analyzing your actual codebase
|
|
30
|
+
3. **Isolates** work in a Git worktree (your main branch stays clean)
|
|
31
|
+
4. **Implements** incrementally with logical commits
|
|
32
|
+
5. **Tests** and iterates until everything passes
|
|
33
|
+
6. **Documents** changes appropriately
|
|
34
|
+
7. **Creates** a draft PR with full context
|
|
35
|
+
8. **Cleans up** the worktree after merge
|
|
36
|
+
|
|
37
|
+
The agent tracks its own progress, recovers from errors, and knows when to stop and ask for help instead of guessing.
|
|
4
38
|
|
|
5
39
|
## Installation
|
|
6
40
|
|
|
@@ -8,16 +42,16 @@ Autonomous workflow agent for Claude Agent SDK. Executes complete feature develo
|
|
|
8
42
|
npm install @gw-tools/autonomous-workflow-agent
|
|
9
43
|
```
|
|
10
44
|
|
|
11
|
-
##
|
|
45
|
+
## Quick Start
|
|
12
46
|
|
|
13
|
-
### With Claude
|
|
47
|
+
### With Claude Code SDK
|
|
14
48
|
|
|
15
49
|
```typescript
|
|
16
50
|
import { autonomousWorkflowAgent } from '@gw-tools/autonomous-workflow-agent';
|
|
17
51
|
import { query } from '@anthropic-ai/claude-code-sdk';
|
|
18
52
|
|
|
19
53
|
for await (const message of query({
|
|
20
|
-
prompt: '
|
|
54
|
+
prompt: 'Add user authentication with JWT tokens',
|
|
21
55
|
options: {
|
|
22
56
|
agents: {
|
|
23
57
|
'autonomous-workflow': autonomousWorkflowAgent,
|
|
@@ -28,26 +62,64 @@ for await (const message of query({
|
|
|
28
62
|
}
|
|
29
63
|
```
|
|
30
64
|
|
|
31
|
-
###
|
|
65
|
+
### Custom Agent Configuration
|
|
32
66
|
|
|
33
67
|
```typescript
|
|
34
|
-
import {
|
|
68
|
+
import { autonomousWorkflowAgent } from '@gw-tools/autonomous-workflow-agent';
|
|
35
69
|
|
|
36
|
-
//
|
|
37
|
-
|
|
70
|
+
// Override defaults for your use case
|
|
71
|
+
const myAgent = {
|
|
72
|
+
...autonomousWorkflowAgent,
|
|
73
|
+
model: 'opus', // Use Opus for complex tasks
|
|
74
|
+
maxTurns: 150, // Allow more iterations
|
|
75
|
+
};
|
|
38
76
|
```
|
|
39
77
|
|
|
40
|
-
###
|
|
78
|
+
### Access the System Prompt Directly
|
|
41
79
|
|
|
42
80
|
```typescript
|
|
43
|
-
import
|
|
81
|
+
import { systemPrompt } from '@gw-tools/autonomous-workflow-agent';
|
|
44
82
|
|
|
45
|
-
//
|
|
83
|
+
// Use in your own agent framework
|
|
84
|
+
console.log(systemPrompt.length); // ~16KB of battle-tested instructions
|
|
46
85
|
```
|
|
47
86
|
|
|
87
|
+
## How It Works
|
|
88
|
+
|
|
89
|
+
### Workflow Modes
|
|
90
|
+
|
|
91
|
+
The agent automatically detects the right workflow mode:
|
|
92
|
+
|
|
93
|
+
| Mode | When | Artifacts |
|
|
94
|
+
| -------- | ---------------------------------- | -------------------------------------- |
|
|
95
|
+
| **Full** | 4+ files OR architectural changes | `task.md`, `plan.md`, `walkthrough.md` |
|
|
96
|
+
| **Lite** | 1-3 files, straightforward changes | Mental plan only |
|
|
97
|
+
|
|
98
|
+
### The 8 Phases
|
|
99
|
+
|
|
100
|
+
| Phase | Name | What Happens |
|
|
101
|
+
| ----- | -------------- | ------------------------------------------------------------------------ |
|
|
102
|
+
| **0** | Validation | Asks clarifying questions, confirms understanding, detects workflow mode |
|
|
103
|
+
| **1** | Planning | Deep codebase analysis, creates implementation plan |
|
|
104
|
+
| **2** | Worktree Setup | Creates isolated Git worktree via `gw add` |
|
|
105
|
+
| **3** | Implementation | Writes code incrementally, commits logically |
|
|
106
|
+
| **4** | Testing | Runs tests, iterates until green (no artificial limits) |
|
|
107
|
+
| **5** | Documentation | Updates README, CHANGELOG, API docs as needed |
|
|
108
|
+
| **6** | PR Creation | Pushes branch, creates draft PR with full context |
|
|
109
|
+
| **7** | Cleanup | Removes worktree after PR is merged |
|
|
110
|
+
|
|
111
|
+
### Safety Guardrails
|
|
112
|
+
|
|
113
|
+
The agent includes built-in safety mechanisms:
|
|
114
|
+
|
|
115
|
+
- **Soft limits**: ~10 commits, ~20 files (warns but continues if justified)
|
|
116
|
+
- **Hard limits**: 50+ files, 20+ test iterations (stops and asks)
|
|
117
|
+
- **Quality gates**: Can't skip phases, must pass validation checkpoints
|
|
118
|
+
- **Rollback ready**: Documented procedures for recovery
|
|
119
|
+
|
|
48
120
|
## Agent Definition
|
|
49
121
|
|
|
50
|
-
The exported
|
|
122
|
+
The exported agent conforms to the `AgentDefinition` interface:
|
|
51
123
|
|
|
52
124
|
```typescript
|
|
53
125
|
interface AgentDefinition {
|
|
@@ -57,49 +129,115 @@ interface AgentDefinition {
|
|
|
57
129
|
model?: 'sonnet' | 'opus' | 'haiku';
|
|
58
130
|
maxTurns?: number;
|
|
59
131
|
}
|
|
132
|
+
|
|
133
|
+
type ToolName = 'Read' | 'Write' | 'Edit' | 'Bash' | 'Glob' | 'Grep' | 'WebSearch' | 'Task' | 'Skill';
|
|
60
134
|
```
|
|
61
135
|
|
|
62
|
-
### Configuration
|
|
136
|
+
### Default Configuration
|
|
63
137
|
|
|
64
|
-
| Property
|
|
65
|
-
|
|
|
66
|
-
| `
|
|
67
|
-
| `tools`
|
|
68
|
-
| `model` | `sonnet` |
|
|
138
|
+
| Property | Value |
|
|
139
|
+
| -------- | -------------------------------------------------------- |
|
|
140
|
+
| `model` | `sonnet` |
|
|
141
|
+
| `tools` | `Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`, `Skill` |
|
|
69
142
|
|
|
70
|
-
##
|
|
143
|
+
## Requirements
|
|
71
144
|
|
|
72
|
-
|
|
145
|
+
- **Git** with worktree support (Git 2.5+)
|
|
146
|
+
- **[gw CLI](https://github.com/mthines/gw-tools)** for worktree management
|
|
147
|
+
- **Node.js** project (npm/pnpm/yarn)
|
|
73
148
|
|
|
74
|
-
|
|
75
|
-
| ----- | -------------- | ------------------------------------- |
|
|
76
|
-
| 0 | Validation | Ask questions, validate understanding |
|
|
77
|
-
| 1 | Planning | Analyze codebase, create plan |
|
|
78
|
-
| 2 | Worktree Setup | Create isolated worktree with `gw` |
|
|
79
|
-
| 3 | Implementation | Code changes in isolated worktree |
|
|
80
|
-
| 4 | Testing | Iterate until tests pass |
|
|
81
|
-
| 5 | Documentation | Update docs |
|
|
82
|
-
| 6 | PR Creation | Create draft PR |
|
|
83
|
-
| 7 | Cleanup | Remove worktree after merge |
|
|
149
|
+
### Installing gw CLI
|
|
84
150
|
|
|
85
|
-
|
|
151
|
+
This agent uses the `gw` CLI under the hood to manage Git worktrees. The CLI handles:
|
|
86
152
|
|
|
87
|
-
-
|
|
88
|
-
-
|
|
89
|
-
-
|
|
153
|
+
- Creating isolated worktrees (`gw checkout feat/my-feature`)
|
|
154
|
+
- Auto-copying secrets and config files to new worktrees
|
|
155
|
+
- Running post-checkout hooks (dependency installation, etc.)
|
|
156
|
+
- Navigating between worktrees (`gw cd`)
|
|
157
|
+
- Cleaning up merged worktrees (`gw clean`)
|
|
90
158
|
|
|
91
|
-
|
|
159
|
+
```bash
|
|
160
|
+
# Via npm
|
|
161
|
+
npm install -g @gw-tools/gw
|
|
92
162
|
|
|
93
|
-
|
|
163
|
+
# Via Homebrew
|
|
164
|
+
brew install mthines/tap/gw
|
|
94
165
|
|
|
95
|
-
|
|
166
|
+
# Or download from releases
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
📖 **Full CLI documentation:** [gw-tools README](https://github.com/mthines/gw-tools/tree/main/packages/gw-tool)
|
|
170
|
+
|
|
171
|
+
## Examples
|
|
172
|
+
|
|
173
|
+
### Feature Implementation
|
|
174
|
+
|
|
175
|
+
```typescript
|
|
176
|
+
await query({
|
|
177
|
+
prompt: 'Implement a caching layer for the API client with TTL support',
|
|
178
|
+
options: { agents: { 'autonomous-workflow': autonomousWorkflowAgent } },
|
|
179
|
+
});
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
The agent will:
|
|
96
183
|
|
|
97
|
-
|
|
184
|
+
1. Ask about cache invalidation strategy, TTL defaults, storage backend
|
|
185
|
+
2. Analyze existing API client code
|
|
186
|
+
3. Create `feat/api-caching` worktree
|
|
187
|
+
4. Implement caching with tests
|
|
188
|
+
5. Create PR with implementation walkthrough
|
|
189
|
+
|
|
190
|
+
### Bug Fix
|
|
191
|
+
|
|
192
|
+
```typescript
|
|
193
|
+
await query({
|
|
194
|
+
prompt: 'Fix the race condition in the WebSocket reconnection logic',
|
|
195
|
+
options: { agents: { 'autonomous-workflow': autonomousWorkflowAgent } },
|
|
196
|
+
});
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
### Refactoring
|
|
200
|
+
|
|
201
|
+
```typescript
|
|
202
|
+
await query({
|
|
203
|
+
prompt: 'Refactor the auth module to use dependency injection',
|
|
204
|
+
options: { agents: { 'autonomous-workflow': autonomousWorkflowAgent } },
|
|
205
|
+
});
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
## Why Git Worktrees?
|
|
209
|
+
|
|
210
|
+
Traditional AI coding assistants modify your working directory directly. This means:
|
|
211
|
+
|
|
212
|
+
- You can't work on other things while the agent runs
|
|
213
|
+
- Failed attempts leave your repo in a dirty state
|
|
214
|
+
- You have to manually create branches and PRs
|
|
215
|
+
|
|
216
|
+
With worktrees, the agent works in a completely separate directory. Your main checkout stays clean, and you can review the agent's work when it's ready.
|
|
217
|
+
|
|
218
|
+
## Troubleshooting
|
|
219
|
+
|
|
220
|
+
### "gw: command not found"
|
|
221
|
+
|
|
222
|
+
Install the gw CLI: `npm install -g @gw-tools/gw`
|
|
223
|
+
|
|
224
|
+
### Agent creates too many worktrees
|
|
225
|
+
|
|
226
|
+
The agent includes "smart detection" to reuse existing worktrees. If you're seeing sprawl, ensure you're cleaning up merged PRs with `gw remove <branch>`.
|
|
227
|
+
|
|
228
|
+
### Tests keep failing
|
|
229
|
+
|
|
230
|
+
The agent will iterate up to 20 times on test failures. If it's still stuck, it will stop and ask for help. Check the `task.md` file in `.gw/<branch>/` for iteration history.
|
|
98
231
|
|
|
99
232
|
## Related
|
|
100
233
|
|
|
101
|
-
- [gw-tools](https://github.com/mthines/gw-tools)
|
|
102
|
-
- [
|
|
234
|
+
- **[gw-tools](https://github.com/mthines/gw-tools)** — Git worktree workflow CLI
|
|
235
|
+
- **[Skill Documentation](https://github.com/mthines/gw-tools/tree/main/skills/autonomous-workflow)** — Full 26-file skill with all rules and templates
|
|
236
|
+
- **[Claude Code SDK](https://github.com/anthropics/claude-code-sdk)** — Official SDK for building Claude agents
|
|
237
|
+
|
|
238
|
+
## Contributing
|
|
239
|
+
|
|
240
|
+
Issues and PRs welcome at [github.com/mthines/gw-tools](https://github.com/mthines/gw-tools).
|
|
103
241
|
|
|
104
242
|
## License
|
|
105
243
|
|