Add new skills and utilities for enhanced writing and testing
- Introduced graphviz conventions for visualizing process flows in writing skills. - Added a comprehensive guide on persuasion principles to improve skill design effectiveness. - Implemented a script to render graphviz diagrams from markdown files to SVG format. - Created a detailed reference for testing skills with subagents, emphasizing TDD principles. - Established a task tracker template for live task management. - Developed a shell script to check the integrity of the antigravity profile and required files. - Added test scripts to validate the initialization of agent projects. - Created workflows for brainstorming, executing plans, and writing plans to streamline processes.
This commit is contained in:
spaceman1412
365
templates/.agent/skills/single-flow-task-execution/SKILL.md
Normal file
365
templates/.agent/skills/single-flow-task-execution/SKILL.md
Normal file
@@ -0,0 +1,365 @@
|
||||
---
|
||||
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
|
||||
|
||||
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** by updating `<project-root>/docs/plans/task.md` at each state change (table-only tracker).
|
||||
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"];
|
||||
}
|
||||
```
|
||||
|
||||
**Use when:**
|
||||
|
||||
- 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
|
||||
|
||||
**Don't use when:**
|
||||
|
||||
- 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
|
||||
|
||||
**vs. Executing Plans (worktree-based):**
|
||||
|
||||
- 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)
|
||||
|
||||
## 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 in docs/plans/task.md" [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];
|
||||
"Use finishing-a-development-branch skill" [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 in docs/plans/task.md" [label="yes"];
|
||||
"Mark task complete in docs/plans/task.md" -> "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" -> "Use finishing-a-development-branch skill";
|
||||
}
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
## 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?)
|
||||
|
||||
**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.
|
||||
|
||||
## 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 `docs/plans/task.md` 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:**
|
||||
|
||||
- **Bad:** No constraints — task might refactor everything
|
||||
- **Good:** "Only modify src/auth/ directory"
|
||||
|
||||
**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]
|
||||
[Update docs/plans/task.md with all tasks as 'not_started']
|
||||
|
||||
--- 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 docs/plans/task.md]
|
||||
|
||||
--- 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 docs/plans/task.md]
|
||||
|
||||
... [Continue through remaining tasks] ...
|
||||
|
||||
[After all tasks complete]
|
||||
[Run final code review on entire implementation]
|
||||
Final review: All requirements met, ready to merge
|
||||
|
||||
[Use finishing-a-development-branch skill]
|
||||
Done!
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
## Completion
|
||||
|
||||
Before claiming all work is done:
|
||||
|
||||
1. Ensure all task entries in `docs/plans/task.md` are `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
|
||||
|
||||
## Integration
|
||||
|
||||
**Required workflow skills:**
|
||||
|
||||
- **using-git-worktrees** — Set up isolated workspace before starting
|
||||
- **writing-plans** — Creates the plan this skill executes
|
||||
- **requesting-code-review** — Code review template for quality reviews
|
||||
- **finishing-a-development-branch** — Complete development after all tasks
|
||||
|
||||
**Should also use:**
|
||||
|
||||
- **test-driven-development** — Follow TDD for each task
|
||||
- **verification-before-completion** — Final verification checklist
|
||||
|
||||
**Alternative workflow:**
|
||||
|
||||
- **executing-plans** — Use for worktree-based parallel session execution
|
||||
@@ -0,0 +1,20 @@
|
||||
# Code Quality Reviewer Prompt Template
|
||||
|
||||
Use this template when running a code quality review step in single-flow mode.
|
||||
|
||||
**Purpose:** Verify implementation is well-built (clean, tested, maintainable)
|
||||
|
||||
**Only proceed after spec compliance review passes.**
|
||||
|
||||
```
|
||||
task_boundary:
|
||||
Use template at requesting-code-review/code-reviewer.md
|
||||
|
||||
WHAT_WAS_IMPLEMENTED: [from implementer's report]
|
||||
PLAN_OR_REQUIREMENTS: Task N from [plan-file]
|
||||
BASE_SHA: [commit before task]
|
||||
HEAD_SHA: [current commit]
|
||||
DESCRIPTION: [task summary]
|
||||
```
|
||||
|
||||
**Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessment
|
||||
@@ -0,0 +1,78 @@
|
||||
# Implementer Task Template
|
||||
|
||||
Use this template when executing an implementation task in single-flow mode.
|
||||
|
||||
```
|
||||
task_boundary:
|
||||
description: "Implement Task N: [task name]"
|
||||
prompt: |
|
||||
You are implementing Task N: [task name]
|
||||
|
||||
## Task Description
|
||||
|
||||
[FULL TEXT of task from plan - paste it here]
|
||||
|
||||
## Context
|
||||
|
||||
[Scene-setting: where this fits, dependencies, architectural context]
|
||||
|
||||
## Before You Begin
|
||||
|
||||
If you have questions about:
|
||||
- The requirements or acceptance criteria
|
||||
- The approach or implementation strategy
|
||||
- Dependencies or assumptions
|
||||
- Anything unclear in the task description
|
||||
|
||||
**Ask them now.** Raise any concerns before starting work.
|
||||
|
||||
## Your Job
|
||||
|
||||
Once you're clear on requirements:
|
||||
1. Implement exactly what the task specifies
|
||||
2. Write tests (following TDD if task says to)
|
||||
3. Verify implementation works
|
||||
4. Commit your work
|
||||
5. Self-review (see below)
|
||||
6. Report back
|
||||
|
||||
Work from: [directory]
|
||||
|
||||
**While you work:** If you encounter something unexpected or unclear, **ask questions**.
|
||||
It's always OK to pause and clarify. Don't guess or make assumptions.
|
||||
|
||||
## Before Reporting Back: Self-Review
|
||||
|
||||
Review your work with fresh eyes. Ask yourself:
|
||||
|
||||
**Completeness:**
|
||||
- Did I fully implement everything in the spec?
|
||||
- Did I miss any requirements?
|
||||
- Are there edge cases I didn't handle?
|
||||
|
||||
**Quality:**
|
||||
- Is this my best work?
|
||||
- Are names clear and accurate (match what things do, not how they work)?
|
||||
- Is the code clean and maintainable?
|
||||
|
||||
**Discipline:**
|
||||
- Did I avoid overbuilding (YAGNI)?
|
||||
- Did I only build what was requested?
|
||||
- Did I follow existing patterns in the codebase?
|
||||
|
||||
**Testing:**
|
||||
- Do tests actually verify behavior (not just mock behavior)?
|
||||
- Did I follow TDD if required?
|
||||
- Are tests comprehensive?
|
||||
|
||||
If you find issues during self-review, fix them now before reporting.
|
||||
|
||||
## Report Format
|
||||
|
||||
When done, report:
|
||||
- What you implemented
|
||||
- What you tested and test results
|
||||
- Files changed
|
||||
- Self-review findings (if any)
|
||||
- Any issues or concerns
|
||||
```
|
||||
@@ -0,0 +1,61 @@
|
||||
# Spec Compliance Reviewer Prompt Template
|
||||
|
||||
Use this template when running a spec compliance review step in single-flow mode.
|
||||
|
||||
**Purpose:** Verify implementer built what was requested (nothing more, nothing less)
|
||||
|
||||
```
|
||||
task_boundary:
|
||||
description: "Review spec compliance for Task N"
|
||||
prompt: |
|
||||
You are reviewing whether an implementation matches its specification.
|
||||
|
||||
## What Was Requested
|
||||
|
||||
[FULL TEXT of task requirements]
|
||||
|
||||
## What Implementer Claims They Built
|
||||
|
||||
[From implementer's report]
|
||||
|
||||
## CRITICAL: Do Not Trust the Report
|
||||
|
||||
The implementer finished suspiciously quickly. Their report may be incomplete,
|
||||
inaccurate, or optimistic. You MUST verify everything independently.
|
||||
|
||||
**DO NOT:**
|
||||
- Take their word for what they implemented
|
||||
- Trust their claims about completeness
|
||||
- Accept their interpretation of requirements
|
||||
|
||||
**DO:**
|
||||
- Read the actual code they wrote
|
||||
- Compare actual implementation to requirements line by line
|
||||
- Check for missing pieces they claimed to implement
|
||||
- Look for extra features they didn't mention
|
||||
|
||||
## Your Job
|
||||
|
||||
Read the implementation code and verify:
|
||||
|
||||
**Missing requirements:**
|
||||
- Did they implement everything that was requested?
|
||||
- Are there requirements they skipped or missed?
|
||||
- Did they claim something works but didn't actually implement it?
|
||||
|
||||
**Extra/unneeded work:**
|
||||
- Did they build things that weren't requested?
|
||||
- Did they over-engineer or add unnecessary features?
|
||||
- Did they add "nice to haves" that weren't in spec?
|
||||
|
||||
**Misunderstandings:**
|
||||
- Did they interpret requirements differently than intended?
|
||||
- Did they solve the wrong problem?
|
||||
- Did they implement the right feature but wrong way?
|
||||
|
||||
**Verify by reading code, not by trusting report.**
|
||||
|
||||
Report:
|
||||
- ✅ Spec compliant (if everything matches after code inspection)
|
||||
- ❌ Issues found: [list specifically what's missing or extra, with file:line references]
|
||||
```
|
||||
Reference in New Issue
Block a user