@leejungkiin/awkit 1.4.3 → 1.5.1

package/skill-packs/superpowers/skills/single-flow-task-execution/SKILL.md

@@ -3,407 +3,108 @@ name: single-flow-task-execution
 description: Use when executing implementation plans, handling multiple independent tasks, or doing structured task-by-task development with review gates in Antigravity.
 ---
 
-# Single-Flow Task Execution
+# Single-Flow Task Execution — Router
 
 Execute plans by working through one task at a time with two-stage review after each: spec compliance review first, then code quality review.
 
 **Core principle:** One task at a time + two-stage review (spec then quality) = high quality, disciplined iteration.
 
-## Antigravity Execution Model
-
-Antigravity does NOT support parallel coding subagents. All work happens in a single execution thread.
-
-**Rules:**
-
-1. **One active task only** — never work on multiple tasks simultaneously.
-2. **One execution thread only** — no parallel dispatch.
-3. **No parallel coding subagents** — Antigravity does not have `Task(...)`.
-4. **Browser automation** may use `browser_subagent` in isolated steps.
-5. **Track progress** via Symphony task system. Update task status at each state change.
-6. **Use `task_boundary`** to clearly delineate each unit of work.
-
-## When to Use
-
-```dot
-digraph when_to_use {
-    "Have implementation plan?" [shape=diamond];
-    "Tasks mostly independent?" [shape=diamond];
-    "Multiple problems to solve?" [shape=diamond];
-    "single-flow-task-execution" [shape=box];
-    "executing-plans" [shape=box];
-    "Manual execution or brainstorm first" [shape=box];
-
-    "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
-    "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
-    "Tasks mostly independent?" -> "single-flow-task-execution" [label="yes"];
-    "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
-    "Multiple problems to solve?" -> "single-flow-task-execution" [label="yes - work through them sequentially"];
-    "Multiple problems to solve?" -> "Manual execution or brainstorm first" [label="no - single task"];
-}
-```
+## Topic Index
 
-**Use when:**
+| Topic | When to Load | File |
+|-------|--------------|------|
+| Example full execution cycle and task brief template | When you need a concrete reference pattern | `examples/workflow-example.md` |
 
-- You have an implementation plan with multiple independent tasks
-- 2+ test files failing with different root causes (work through them one at a time)
-- Multiple subsystems broken independently
-- Each problem can be understood without context from others
-- Structured execution with quality gates is needed
+## Antigravity Execution Model
 
-**Don't use when:**
+1. **One active task only** — never work on multiple tasks simultaneously
+2. **One execution thread** — no parallel dispatch, no `Task(...)`
+3. **Browser automation** may use `browser_subagent` in isolated steps
+4. **Track progress** via Symphony task system
+5. **Use `task_boundary`** to delineate each unit of work
 
-- Failures are related (fix one might fix others) — investigate together first
-- Tasks are tightly coupled and need full system understanding
-- Single simple task that doesn't need review structure
+## When to Use / Don't Use
 
-**vs. Executing Plans (worktree-based):**
+**Use:** Implementation plan with multiple independent tasks | 2+ test files failing different causes | Structured execution with quality gates
 
-- Same session (no context switch)
-- Fresh `task_boundary` per task (clean scope)
-- Two-stage review after each task: spec compliance first, then code quality
-- Faster iteration (no human-in-loop between tasks)
+**Don't:** Related failures (fix one → fix others) | Tightly coupled tasks | Single simple task
 
 ## The Process
 
-```dot
-digraph process {
-    rankdir=TB;
-
-    subgraph cluster_per_task {
-        label="Per Task";
-        "Execute implementation (./implementer-prompt.md)" [shape=box];
-        "Questions about requirements?" [shape=diamond];
-        "Answer questions, provide context" [shape=box];
-        "Implement, test, commit, self-review" [shape=box];
-        "Run spec compliance review (./spec-reviewer-prompt.md)" [shape=box];
-        "Spec confirms code matches spec?" [shape=diamond];
-        "Fix spec gaps" [shape=box];
-        "Run code quality review (./code-quality-reviewer-prompt.md)" [shape=box];
-        "Code quality approved?" [shape=diamond];
-        "Fix quality issues" [shape=box];
-        "Mark task complete via Symphony" [shape=box];
-    }
-
-    "Read plan, extract all tasks with full text, note context" [shape=box];
-    "More tasks remain?" [shape=diamond];
-    "Run final code review for entire implementation" [shape=box];
-    "Complete Symphony task and present next steps" [shape=box style=filled fillcolor=lightgreen];
-
-    "Read plan, extract all tasks with full text, note context" -> "Execute implementation (./implementer-prompt.md)";
-    "Execute implementation (./implementer-prompt.md)" -> "Questions about requirements?";
-    "Questions about requirements?" -> "Answer questions, provide context" [label="yes"];
-    "Answer questions, provide context" -> "Execute implementation (./implementer-prompt.md)";
-    "Questions about requirements?" -> "Implement, test, commit, self-review" [label="no"];
-    "Implement, test, commit, self-review" -> "Run spec compliance review (./spec-reviewer-prompt.md)";
-    "Run spec compliance review (./spec-reviewer-prompt.md)" -> "Spec confirms code matches spec?";
-    "Spec confirms code matches spec?" -> "Fix spec gaps" [label="no"];
-    "Fix spec gaps" -> "Run spec compliance review (./spec-reviewer-prompt.md)" [label="re-review"];
-    "Spec confirms code matches spec?" -> "Run code quality review (./code-quality-reviewer-prompt.md)" [label="yes"];
-    "Run code quality review (./code-quality-reviewer-prompt.md)" -> "Code quality approved?";
-    "Code quality approved?" -> "Fix quality issues" [label="no"];
-    "Fix quality issues" -> "Run code quality review (./code-quality-reviewer-prompt.md)" [label="re-review"];
-    "Code quality approved?" -> "Mark task complete via Symphony" [label="yes"];
-    "Mark task complete via Symphony" -> "More tasks remain?";
-    "More tasks remain?" -> "Execute implementation (./implementer-prompt.md)" [label="yes"];
-    "More tasks remain?" -> "Run final code review for entire implementation" [label="no"];
-    "Run final code review for entire implementation" -> "Complete Symphony task and present next steps";
-}
+```text
+Read plan → Extract tasks → [Per task loop]:
+  1. Execute implementation (./implementer-prompt.md)
+  2. Questions? → Ask & wait → Re-execute
+  3. Implement, test, commit, self-review
+  4. Run spec compliance review (./spec-reviewer-prompt.md)
+     → Issues? Fix → Re-review until approved
+  5. Run code quality review (./code-quality-reviewer-prompt.md)
+     → Issues? Fix → Re-review until approved
+  6. Mark task complete via Symphony
+  7. More tasks? → Loop | No → Final code review → Complete
 ```
 
-## UI-First Task Ordering (Gate 4 Three-Phase — v12.3)
+## UI-First Task Ordering (Gate 4 Three-Phase)
 
-When a task set includes UI components (COMPLEX or MODERATE), tasks MUST be ordered in three phases:
+When tasks include UI components (COMPLEX/MODERATE):
 
-### Phase A: Infrastructure Tasks
-```
-Priority: Execute FIRST
-Examples:
-  - Add dependencies (Gradle, SPM, CocoaPods)
-  - Create project structure (packages, modules, DI)
-  - Set up navigation skeleton (NavGraph, Router)
-  - Configure build variants, signing
-Gate: App MUST build successfully → proceed
-```
+| Phase | Priority | Examples | Gate |
+|-------|----------|----------|------|
+| **A: Infrastructure** | FIRST | Dependencies, DI, nav skeleton | App MUST build |
+| **B: UI Shell** | SECOND | All screens with mock data | User or auto checkpoint |
+| **C: Logic** | LAST | Real API/DB, business logic | Per-feature checkpoint |
 
-### Phase B: UI Shell Tasks (Mock Data)
-```
-Priority: Execute SECOND, BEFORE any logic tasks
-Examples:
-  - Build all screen layouts with static/mock data
-  - Implement navigation between screens
-  - Add animations, transitions, loading/empty/error states
-  - Wire up UI components (no real API/DB calls)
-Gate: 🧪 USER TEST CHECKPOINT — user must test UI on device
-  → Present test guidance (see symphony-enforcer TP1.7)
-  → User confirms UI OK → proceed to Phase C
-  → User reports issue → fix → re-checkpoint
-```
-
-### Phase C: Logic Tasks (Per Feature)
-```
-Priority: Execute LAST, after UI is confirmed
-Examples:
-  - Replace mock data with real API/DB calls
-  - Implement business logic, validation
-  - Add error handling, retry, offline support
-  - Wire up hardware features (camera, GPS, sensors)
-Gate: 🧪 USER TEST CHECKPOINT per feature (batch small ones)
-  → Especially important for hardware-dependent features
-```
+**Auto checkpoint:** Check `.project-identity` → `autoVerification: true` = Maestro auto-test, `false` = wait for user.
 
 ### Task Sorting Rule
-```
-When creating task list from implementation plan:
-1. Tag each task: [INFRA] [UI] [LOGIC]  
+
+1. Tag each task: `[INFRA]` `[UI]` `[LOGIC]`
 2. Sort: INFRA first → UI second → LOGIC last
 3. Within each phase: respect dependency ordering
-4. Between phases: MANDATORY checkpoint where indicated
-```
 
 ## Task Decomposition
 
-When facing multiple problems (e.g., 5 test failures across 3 files):
-
-### 1. Identify Independent Domains
-
-Group failures by what's broken:
-
-- File A tests: User authentication flow
-- File B tests: Data validation logic
-- File C tests: API response handling
-
-Each domain is independent — fixing authentication doesn't affect validation tests.
-
-### 2. Create Task Units
-
-Each task gets:
-
-- **Specific scope:** One test file or subsystem
-- **Clear goal:** Make these tests pass / implement this feature
-- **Constraints:** Don't change unrelated code
-- **Expected output:** Summary of what changed and verification results
-
-### 3. Execute Sequentially with Review
-
-Work through each task one at a time using the full review cycle.
-
-### 4. Review and Integrate
-
-After all tasks:
-
-- Run full test suite to verify no regressions
-- Check for conflicts between task changes
-- Run final code review on entire implementation
-
-## Task Brief Structure
-
-For each task, prepare:
-
-```
-task_boundary:
-  description: "Implement Task N: [task name]"
-  prompt: |
-    ## Task Description
-    [FULL TEXT of task from plan — paste it here]
-
-    ## Context
-    [Where this fits, dependencies, architectural context]
-
-    ## Constraints
-    - Only modify [specific files/directories]
-    - Follow existing patterns in the codebase
-    - Write tests for new functionality
-
-    ## Verification
-    - Run: [specific test command]
-    - Expected: [what success looks like]
-```
-
-**Key:** Provide full task text and context upfront. Don't make the task boundary re-read the plan file.
+1. **Identify independent domains** — Group failures by what is broken
+2. **Create task units** — Specific scope, clear goal, constraints, expected output
+3. **Execute sequentially** with full review cycle
+4. **Review and integrate** — Full test suite, check conflicts
 
 ## Review Templates
 
-This skill includes prompt templates for structured reviews:
-
-- **`./implementer-prompt.md`** — Template for implementation task boundaries
-- **`./spec-reviewer-prompt.md`** — Template for spec compliance review (did we build what was requested?)
-- **`./code-quality-reviewer-prompt.md`** — Template for code quality review (is it well-built?)
+- `./implementer-prompt.md` — Implementation structure
+- `./spec-reviewer-prompt.md` — Did we build what was requested?
+- `./code-quality-reviewer-prompt.md` — Is it well-built?
 
-**Review order matters:** Always run spec compliance FIRST, then code quality. There's no point reviewing code quality if the implementation doesn't match the spec.
+**Order:** Always spec compliance first, then code quality.
 
 ## Checkpoint Pattern
 
-At logical boundaries (after each task, at major milestones), report:
-
-- **What changed** — files modified, features implemented
-- **What verification ran** — test results, lint results
-- **What remains** — remaining tasks, known issues
-
-Update Symphony task progress with current status.
-
-## Common Mistakes
-
-**Task scoping:**
-
-- **Bad:** "Fix all the tests" — loses focus
-- **Good:** "Fix user-auth.test.ts failures" — clear scope
-
-**Context:**
-
-- **Bad:** "Fix the validation bug" — unclear where
-- **Good:** Paste error messages, test names, relevant code paths
-
-**Constraints:**
+Report at logical boundaries:
 
-- **Bad:** No constraints — task might refactor everything
-- **Good:** "Only modify src/auth/ directory"
+- **What changed**
+- **What verification ran**
+- **What remains**
 
-**Output:**
-
-- **Bad:** "Fix it" — no visibility into what changed
-- **Good:** "Report: root cause, changes made, test results"
-
-**Reviews:**
-
-- **Bad:** "It works, move on" — quality debt
-- **Good:** Implement then spec review then quality review then next task
-
-## Example Workflow
-
-```
-You: I'm using single-flow-task-execution to execute this plan.
-
-[Read plan file: docs/plans/feature-plan.md]
-[Extract all 5 tasks with full text and context]
-[Create Symphony tasks for tracking]
-
---- Task 1: Hook installation script ---
-
-[Prepare task brief with full text + context]
-[Execute implementation following ./implementer-prompt.md structure]
-
-Questions: "Should the hook be installed at user or system level?"
-Answer: "User level (~/.config/superpowers/hooks/)"
-
-Implementation:
-  - Implemented install-hook command
-  - Added tests, 5/5 passing
-  - Self-review: Found I missed --force flag, added it
-  - Committed
-
-[Run spec compliance review following ./spec-reviewer-prompt.md]
-Spec review: Spec compliant — all requirements met, nothing extra
-
-[Run code quality review following ./code-quality-reviewer-prompt.md]
-Code review: Strengths: Good test coverage, clean. Issues: None. Approved.
-
-[Mark Task 1 complete in Symphony]
-
---- Task 2: Recovery modes ---
-
-[Prepare task brief with full text + context]
-[Execute implementation]
-
-Implementation:
-  - Added verify/repair modes
-  - 8/8 tests passing
-  - Self-review: All good
-  - Committed
-
-[Run spec compliance review]
-Spec review: Issues found:
-  - Missing: Progress reporting (spec says "report every 100 items")
-  - Extra: Added --json flag (not requested)
-
-[Fix issues: remove --json flag, add progress reporting]
-[Run spec compliance review again]
-Spec review: Spec compliant now
-
-[Run code quality review]
-Code review: Issue (Important): Magic number (100) should be a constant
-
-[Fix: extract PROGRESS_INTERVAL constant]
-[Run code quality review again]
-Code review: Approved
-
-[Mark Task 2 complete in Symphony]
-
-... [Continue through remaining tasks] ...
-
-[After all tasks complete]
-[Run final code review on entire implementation]
-Final review: All requirements met, ready to merge
-
-[Complete Symphony task and present next steps]
-Done!
-```
+Update Symphony task progress after each meaningful boundary.
 
 ## Red Flags
 
-**Never:**
-
-- Start implementation on main/master branch without explicit user consent
-- Skip reviews (spec compliance OR code quality)
-- Proceed with unfixed review issues
-- Work on multiple tasks simultaneously
-- Skip scene-setting context (task needs to understand where it fits)
-- Accept "close enough" on spec compliance (reviewer found issues = not done)
-- Skip review loops (reviewer found issues = fix = review again)
-- Let self-review replace actual review (both are needed)
-- **Start code quality review before spec compliance passes** (wrong order)
-- Move to next task while either review has open issues
-
-**If you have questions about requirements:**
-
-- Ask clearly and wait for answers
-- Don't guess or make assumptions
-- Better to ask upfront than rework later
-
-**If reviewer finds issues:**
-
-- Fix them
-- Run reviewer again
-- Repeat until approved
-- Don't skip the re-review
+**Never:** Start on main without consent | Skip reviews | Work on multiple tasks | Accept "close enough" | Start quality review before spec passes | Skip re-review after fixes
 
 ## Completion
 
-Before claiming all work is done:
-
-1. Ensure all Symphony tasks are marked `done` or `cancelled`
-2. Run full test/validation command
-3. Verify no regressions across all tasks
-4. Summarize evidence (test output, review approvals)
-
-## Advantages
-
-**Structured execution:**
-
-- Clear task boundaries prevent scope creep
-- Review gates catch issues early (cheaper than debugging later)
-- Progress tracking provides visibility
-
-**Quality gates:**
-
-- Self-review catches obvious issues before handoff
-- Two-stage review: spec compliance prevents over/under-building, code quality ensures maintainability
-- Review loops ensure fixes actually work
-
-**Efficiency:**
-
-- Provide full task text upfront (no re-reading plan files)
-- Controller curates exactly what context is needed
-- Questions surfaced before work begins (not after)
-- Sequential execution avoids conflicts between tasks
+1. All Symphony tasks marked `done` or `cancelled`
+2. Full test or validation command ran
+3. No regressions across all tasks
+4. Evidence summarized
 
 ## Integration
 
-**Required workflow skills:**
+- `symphony-orchestrator`
+- `symphony-enforcer`
+- `test-driven-development` when strict TDD is needed
+- `verification-before-completion` when using the full `superpowers` pack
 
-- **`~/.gemini/antigravity/skills/symphony-orchestrator/SKILL.md`** — Task tracking and lifecycle
-- **`~/.gemini/antigravity/skills/symphony-enforcer/SKILL.md`** — Enforce task discipline
-
-**Should also use:**
+---
 
-- **test-driven-development** — Follow TDD for each task
-- **verification-before-completion** — Final verification checklist
+*single-flow-task-execution — Lean Router Architecture*