# Task Validation Loop

> This skill should be used when the task list is complete to run multi-agent verification ensuring tasks cover PRD, follow architecture, and respect design system

- **Type:** Skill
- **Install:** `agentstack add skill-etr-groundwork-task-validation-loop`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [etr](https://agentstack.voostack.com/s/etr)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [etr](https://github.com/etr)
- **Source:** https://github.com/etr/groundwork/tree/main/skills/task-validation-loop

## Install

```sh
agentstack add skill-etr-groundwork-task-validation-loop
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Task Validation Loop Skill

Autonomous verification loop that runs 3 specialized agents to validate task list completeness and alignment before implementation begins.

## Pre-flight: Model Recommendation

**Your current effort level is `{{effort_level}}`.**

Skip this step silently if effort is `high`, `xhigh`, or `max` (the scale is `low`  "You're working from `` (inside **[cwd-project]**), but the selected Groundwork project is **[selected-project]** (`[selected-project-path]/`). What would you like to do?"
     > - "Switch to [cwd-project]"
     > - "Stay with [selected-project]"
     If the user switches, invoke `Skill(skill="groundwork:select-project")`.
   - If CWD doesn't match any project → proceed without warning (shared directory).
3. Proceed with the resolved project context. All `{{specs_dir}}/` paths will resolve to the correct location.

## Prerequisites

Before invoking this skill, ensure:
- Task list is complete ({{specs_dir}}/tasks/ directory or {{specs_dir}}/tasks.md exists)
- PRD exists ({{specs_dir}}/product_specs.md)
- Architecture exists ({{specs_dir}}/architecture.md)
- User has approved the task breakdown

## Workflow

### 1. Gather Context

Collect inputs for the agents:

```
task_list     ← Read {{specs_dir}}/tasks.md (or {{specs_dir}}/tasks/ directory)
product_specs ← Read {{specs_dir}}/product_specs.md (or {{specs_dir}}/product_specs/ directory)
architecture  ← Read {{specs_dir}}/architecture.md (or {{specs_dir}}/architecture/ directory)
design_system ← Read {{specs_dir}}/design_system.md (if exists, optional)
```

**Detection:** Check for file first (takes precedence), then directory. When reading a directory, aggregate all `.md` files recursively.

### 1.5. Determine Active Agents

| Agent | Skip when |
|---|---|
| `design-task-alignment-checker` | No `design_system` found AND no UI/frontend tasks in task list |

`prd-task-alignment-checker` and `architecture-task-alignment-checker` always run (their inputs are prerequisites).

Record skipped agents with verdict `skipped`.

### 2. Launch Validation Agents

Use Agent tool to launch all 3 agents in parallel:

| Agent (`subagent_type`) | Context to Provide |
|-------------------------|-------------------|
| `groundwork:prd-task-alignment-checker:prd-task-alignment-checker` | task_list, product_specs |
| `groundwork:architecture-task-alignment-checker:architecture-task-alignment-checker` | task_list, architecture |
| `groundwork:design-task-alignment-checker:design-task-alignment-checker` | task_list, design_system |

Each returns JSON:
```json
{
  "summary": "One-sentence assessment",
  "score": 0-100,
  "findings": [{"severity": "critical|major|minor", "category": "...", "task_reference": "TASK-NNN", "finding": "...", "recommendation": "..."}],
  "verdict": "approve|request-changes"
}
```

### 3. Aggregate Results

Present results in table format:

```markdown
## Task List Validation Report

| Agent | Score | Verdict | Critical | Major | Minor |
|-------|-------|---------|----------|-------|-------|
| PRD Alignment | 92 | approve | 0 | 1 | 2 |
| Architecture Alignment | 88 | approve | 0 | 1 | 1 |
| Design Alignment | 85 | approve | 0 | 2 | 1 |

**Overall:** PASS / NEEDS FIXES
```

### 4. Autonomous Fix-and-Retry Loop

**Rule**: Continue this loop until ALL agents return `approve`.

**On any `request-changes` verdict:**

1. **Log Iteration**
   ```markdown
   ## Validation Iteration [N]
   | Agent | Verdict | Findings |
   |-------|---------|----------|
   | ... | ... | ... |
   Fixing [X] issues...
   ```

2. **Fix Each Finding** - Apply each critical/major recommendation
   - Modify the relevant task file in {{specs_dir}}/tasks/ (or {{specs_dir}}/tasks.md if single-file)
   - Track what was changed
   - Note which finding each fix addresses

   Fix types:
   - **requirement-not-tasked**: Add new task for the requirement
   - **component-mismatch**: Update task's Component field
   - **accessibility-missing**: Add acceptance criteria to task
   - **over-tasked**: Remove task or add requirement to PRD (user decision)

3. **Re-run Agent Validation** — Re-launch ONLY agents that returned `request-changes`. Agents that approved retain their verdict unless the fix changed content in their domain:
   - **PRD alignment checker**: re-run if tasks were added/removed or requirements mapping changed
   - **Architecture alignment checker**: re-run if component assignments or technology references changed
   - **Design alignment checker**: re-run if accessibility criteria or design token references changed

   For agents NOT re-run, carry forward their previous `approve` verdict and score.

4. **Check Results**
   - ALL approve → **PASS**, return success
   - Any request-changes → Return to step 1

### 5. Stuck Detection

Track findings by key: `[Agent]-[Category]-[TaskRef]`

If same finding appears **3 times**:

```markdown
## Stuck - Need User Input

Issue persists after 3 attempts:

**[Agent] Finding description**
- Task: TASK-NNN
- Category: [category]
- Attempts:
  1. [what was tried]
  2. [what was tried]
  3. [what was tried]

I need clarification: [specific question]
```

- Use AskUserQuestion for guidance
- Apply fix based on user input
- Continue loop

Also escalate when:
- Conflicting requirements between PRD and architecture
- Missing information to create required task
- Scope decisions needed (add to PRD vs. remove task)

### 6. Return Result

**On PASS:**
```markdown
## Task List Validation PASSED

All 3 agents approved after [N] iteration(s).

| Agent | Score | Verdict | Summary |
|-------|-------|---------|---------|
| PRD Alignment | 95 | APPROVE | All requirements covered |
| Architecture Alignment | 92 | APPROVE | Tasks follow architecture |
| Design Alignment | 90 | APPROVE | UI tasks include a11y |

Issues fixed:
- [Iteration N] Agent: Description

Coverage Summary:
- PRD Requirements: [X]% covered
- Architecture Components: All referenced
- Design System: [Applied/N/A]

Minor suggestions (optional):
- ...
```

Return control to calling skill (tasks skill).

## Severity Reference

| Level | Action |
|-------|--------|
| critical | Must fix, loop continues |
| major | Must fix, loop continues |
| minor | Optional, does not block |

## Edge Cases

**No design system:**
- Design agent still runs (checks accessibility)
- Note in summary: "Design system not found"

**Agent returns error:**
- Log the error
- Retry once
- If still fails, escalate to user

**All agents approve immediately:**
- Log success
- Return without iteration

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [etr](https://github.com/etr)
- **Source:** [etr/groundwork](https://github.com/etr/groundwork)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-etr-groundwork-task-validation-loop
- Seller: https://agentstack.voostack.com/s/etr
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.