Aiwg flow-guided-implementation
Orchestrate autonomous issue-to-code implementation using existing tools and agents with bounded iteration
install
source · Clone the upstream repo
git clone https://github.com/jmagly/aiwg
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/jmagly/aiwg "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.agents/skills/flow-guided-implementation" ~/.claude/skills/jmagly-aiwg-flow-guided-implementation && rm -rf "$T"
manifest:
.agents/skills/flow-guided-implementation/SKILL.mdsource content
/flow-guided-implementation
Orchestrate autonomous issue-to-code implementation using existing tools and agents with bounded iteration.
Usage
/flow-guided-implementation [issue-description] /flow-guided-implementation --issue <url> /flow-guided-implementation --max-retries 5
Parameters
| Parameter | Default | Description |
|---|---|---|
| - | Natural language description of what to implement |
| - | GitHub/Gitea issue URL to fetch |
| 3 | Maximum iterations per task before escalating |
| false | Skip code review (faster, less safe) |
| false | Plan only, don't execute changes |
Design Principles
From issue requirements:
- Run to completion - Minimal user interaction during execution
- Complement existing tools - Use Grep, Glob, Edit, TodoWrite, Task
- Bounded iteration - Auto-retry up to N times, then escalate
- Autonomous decision-making - Don't ask unless truly blocked
Workflow
┌─────────────────────────────────────────────────────────────────┐ │ PHASE 1: ANALYSIS │ │ Tools: Read, Grep, Glob │ ├─────────────────────────────────────────────────────────────────┤ │ 1. Parse issue/requirement │ │ 2. Extract keywords and intent │ │ 3. Search codebase for relevant files: │ │ - Grep for keywords in file contents │ │ - Glob for naming patterns │ │ 4. Read top candidate files for context │ │ 5. Rank files by relevance (keyword density + path match) │ └─────────────────────────────────────────────────────────────────┘ │ v ┌─────────────────────────────────────────────────────────────────┐ │ PHASE 2: TASK DECOMPOSITION │ │ Tool: TodoWrite │ ├─────────────────────────────────────────────────────────────────┤ │ 1. Create task per file to modify │ │ 2. Include task dependencies (e.g., types before implementation)│ │ 3. Order by dependency graph │ │ 4. Estimate complexity per task │ └─────────────────────────────────────────────────────────────────┘ │ v ┌─────────────────────────────────────────────────────────────────┐ │ PHASE 3: ITERATIVE CODING │ │ Tools: Edit, Bash, Task(agents) │ │ Skill: iteration-control │ ├─────────────────────────────────────────────────────────────────┤ │ FOR EACH task (respecting dependencies): │ │ iteration = 0 │ │ │ │ LOOP while iteration < max_retries: │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ STEP 1: LOCATE │ │ │ │ - Grep for specific patterns in target file │ │ │ │ - Read surrounding context │ │ │ │ - Identify line ranges for modification │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ │ v │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ STEP 2: GENERATE │ │ │ │ Simple change: Edit tool directly │ │ │ │ Complex change: Task(software-implementer) │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ │ v │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ STEP 3: VALIDATE │ │ │ │ - Bash: Run tests (npm test, pytest, etc.) │ │ │ │ - If tests fail: Task(debugger) for diagnosis │ │ │ │ - If tests pass && !skip_review: Task(code-reviewer) │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ │ v │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ STEP 4: DECIDE (iteration-control skill) │ │ │ │ │ │ │ │ IF pass + approved: mark task complete, BREAK │ │ │ │ IF fail + iteration < max: retry with feedback │ │ │ │ IF fail + iteration >= max: ESCALATE to user │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ Mark task complete in TodoWrite │ └─────────────────────────────────────────────────────────────────┘ │ v ┌─────────────────────────────────────────────────────────────────┐ │ PHASE 4: INTEGRATION │ │ Tools: Bash (git) │ ├─────────────────────────────────────────────────────────────────┤ │ 1. Verify all tasks complete │ │ 2. Run full test suite │ │ 3. Stage changes: git add │ │ 4. Generate commit message from tasks │ │ 5. Commit (or prompt user for /commit-and-push) │ └─────────────────────────────────────────────────────────────────┘
Agents Used
| Agent | When | Purpose |
|---|---|---|
| Complex code generation | TDD cycle, multi-file changes |
| After code passes tests | Quality, security, style review |
| When tests fail | Root cause analysis |
| If tests need creation | Generate test coverage |
Example Session
User: /flow-guided-implementation Add refresh token support to authentication Claude: Starting guided implementation... ## Phase 1: Analysis Searching for authentication-related files... - Found: src/auth/authService.ts (high relevance) - Found: src/auth/tokenService.ts (high relevance) - Found: src/types/auth.ts (medium relevance) - Found: src/routes/auth.ts (medium relevance) ## Phase 2: Task Decomposition Creating tasks: [1/4] [ ] Add RefreshToken type to src/types/auth.ts [2/4] [ ] Add refresh config to src/config/auth.ts [3/4] [ ] Implement refresh in src/auth/tokenService.ts (depends: 1,2) [4/4] [ ] Add /refresh endpoint to src/routes/auth.ts (depends: 3) ## Phase 3: Iterative Coding ### Task 1: Add RefreshToken type Locating insertion point... line 15 Generating type definition... Running tests... PASS [1/4] [✓] Add RefreshToken type ### Task 2: Add refresh config Locating config section... line 8 Adding refreshTokenExpiry config... Running tests... PASS [2/4] [✓] Add refresh config ### Task 3: Implement refresh in tokenService Locating token generation... lines 20-35 Generating refresh token logic... Running tests... FAIL - refreshToken is undefined Iteration 1/3: Retrying with feedback... Fixed: Added refreshToken to return object Running tests... PASS Code review... APPROVED [3/4] [✓] Implement refresh in tokenService ### Task 4: Add /refresh endpoint Locating routes... line 45 Adding POST /refresh handler... Running tests... PASS Code review... APPROVED [4/4] [✓] Add /refresh endpoint ## Phase 4: Integration All tasks complete. Running full test suite... PASS Changes ready to commit. Generated commit message: feat(auth): add refresh token support - Add RefreshToken type - Configure refresh token expiry - Implement token refresh in tokenService - Add POST /refresh endpoint Run /commit-and-push to commit, or review changes with `git diff`.
Escalation Example
### Task 3: Implement refresh (iteration 3/3) Running tests... FAIL - userId format mismatch ESCALATION: Max iterations reached After 3 attempts, the test still fails: - Iter 1: refreshToken undefined - Iter 2: refreshToken missing userId - Iter 3: userId format mismatch (string vs number) The implementation uses: { userId: "123" } (string) The test expects: { userId: 123 } (number) Which format should be used? 1. String - I'll update the test 2. Number - I'll update the implementation
Progress Tracking
Progress tracked via TodoWrite. Check status anytime:
User: What's the implementation status? Claude: [1/4] [✓] Add RefreshToken type (1 iteration) [2/4] [✓] Add refresh config (1 iteration) [3/4] [..] Implement refresh in tokenService (iteration 2/3) [4/4] [ ] Add /refresh endpoint (pending) Current: Task 3, waiting for test fix
Traceability
- @research @.aiwg/research/REF-004-magis-multi-agent-issue-resolution.md
- @skill @$AIWG_ROOT/agentic/code/addons/guided-implementation/skills/iteration-control/SKILL.md
References
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/agents/software-implementer.md
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/agents/code-reviewer.md
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/agents/debugger.md