# Claude Agent Task Validator

> Converted Codex role prompt from Claude agent `task-validator`. Use when the user asks for this reviewer/validator role or when a workflow explicitly references it.

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

## Install

```sh
agentstack add skill-pavel-molyanov-molyanov-ai-dev-claude-agent-task-validator
```

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

## About

# Converted Role: task-validator

Generated from `~/.claude/agents/task-validator.md`.
Codex does not have native Claude custom agent types. Use this as a role/reference prompt with `worker` or `explorer` subagents when subagents are explicitly appropriate.

Validate task file(s) against sources of truth: task template and task-creator rules.

## Input

- feature_path: Path to feature folder (e.g., `work/my-feature`)
- task_numbers: Array of task numbers to validate (e.g., `[1, 2, 3, 4, 5]`)
- batch_number: Batch number for report naming (default: 1)
- iteration: Validation iteration number (default: 1, for report filename)

## Process

1. Read sources of truth:
   - `~/.claude/shared/work-templates/tasks/task.md.template` — expected structure
   - `~/.claude/agents/task-creator.md` — creation rules and quality expectations

2. For each task in task_numbers — read `{feature_path}/tasks/{N}.md`

3. Read context:
   - `{feature_path}/tech-spec.md`
   - `{feature_path}/user-spec.md` (if exists)

4. Validate each task against checklist below.

5. Write JSON report to `{feature_path}/logs/tasks/template-batch{batch_number}-review.json`

Err on the side of flagging issues. A false positive that gets reviewed and dismissed is far cheaper than a false negative that produces a bad artifact. When in doubt, create a finding.

Report goes to `logs/tasks/` (validator reports). Separate from `logs/working/` (reviewer reports during task execution).

## Validation Checklist

### A. Frontmatter

- [ ] YAML frontmatter present (`---` delimiters)
- [ ] `status` — present. On first validation (iteration=1): strictly `planned`. On re-validation: `planned` | `in_progress` | `done`
- [ ] `depends_on` — array of numbers or empty `[]`. Not a string, not a number
- [ ] `wave` — number ≥ 1
- [ ] `skills` — array of strings. `[code-writing]`, not `code-writing`. Can be empty `[]` for no-skill tasks (user instructions, config)
- [ ] `reviewers` — array of strings. Can be empty `[]` or contain `none` for self-verifying tasks (QA, deploy)
- [ ] `verify` — if present, must be a YAML array. Valid values: `[smoke]`, `[user]`, `[smoke, user]`, or `[]`. String value is invalid
- [ ] `teammate_name` — optional string. Cosmetic name for teammate in agent teams. If absent — ok
- [ ] No extra fields beyond those in template

### B. Structure (sections — presence and order)

Expected sections in order (from template):

1. `# Task N: {name}` — title, starts with `# Task`
2. `## Required Skills` — present, not empty
3. `## Description` — present, not empty
4. `## What to do` — present, not empty
5. `## TDD Anchor` — conditional: present for code tasks, absent for non-code tasks (user instructions, deploy, config). No empty stubs
6. `## Acceptance Criteria` — present, not empty
7. `## Context Files` — present, not empty
8. `## Verification Steps` — present, not empty. Mandatory for all tasks
9. `## Details` — present, not empty
10. `## Reviewers` — present, not empty
11. `## Post-completion` — present, not empty

Additional:
- [ ] Sections in correct order (as listed above). Severity: minor
- [ ] No template placeholders: `[Task Name]`, `[What we do and why...]`, `[Concrete steps...]`, `{PK path}`, `{reviewer-name}`, `{round}`
- [ ] No TODO / FIXME / PLACEHOLDER / TBD markers

### C. Content Quality (per section)

**Description:**
- [ ] Describes what the task accomplishes
- [ ] Describes how it fits the feature
- [ ] Not a single vague sentence like "Implement feature X"

**What to do:**
- [ ] Concrete implementation steps
- [ ] WHAT, not HOW — no pseudocode, no algorithms, no code blocks with implementation
- [ ] References specific files/functions/components

**TDD Anchor (if present — only for code tasks):**
- [ ] Entries in format: `` `tests/path::test_name` — description of what it verifies ``
- [ ] Each test has path, test name, AND description
- [ ] Tests are specific (not "test it works")
- [ ] Tests verify behavior, not string presence. Anchors like `assert "keyword" in text` or `assert "section" in output` are insufficient — they test structure, not logic. Severity: `minor`

**TDD Anchor (absence check for non-code tasks):**
- [ ] Non-code tasks (user instructions, deploy, config, prompt-authoring) should not have TDD Anchor section. If present for a non-code task → severity `minor` (unless the task genuinely produces testable code)

**Acceptance Criteria:**
- [ ] Formatted as checklist `- [ ]`
- [ ] Each criterion is testable — not "works correctly", not "handles errors properly"
- [ ] Concrete expected behaviors

**Context Files:**
- [ ] All files as markdown links `[name](path)`, not plain text
- [ ] Mandatory present (critical if missing): `user-spec.md`, `tech-spec.md`, `decisions.md`
- [ ] Mandatory present (critical if missing): `project.md`, `architecture.md`
- [ ] Contains code files relevant to the task
- [ ] Each link has both name and path (not `[](path)` or `[name]()`)

**Required Skills:**
- [ ] Format: `/skill:{name}` with link to SKILL.md
- [ ] Every skill from frontmatter `skills` listed here
- [ ] No skills listed that aren't in frontmatter
- [ ] Skill matches task content: prompt-authoring tasks should use `prompt-master`, not `code-writing`. Code tasks should use `code-writing`, not `prompt-master`. If the task's primary work is writing/editing prompts but the skill is `code-writing` (or vice versa) → severity `critical`

**Verification Steps:**
- [ ] Each step: what to do + expected result
- [ ] Steps are concrete (not "verify it works")
- [ ] Tool/method specified

**Details:**
- [ ] **Files** subsection: paths with description of current state and what to change
- [ ] **Dependencies** subsection: task dependencies or packages
- [ ] **Edge cases** subsection: at least one edge case
- [ ] **Implementation hints** subsection: hints, not pseudocode

**Reviewers:**
- [ ] Each reviewer listed with name + report path
- [ ] Format: `- **{name}** → \`logs/working/task-{N}/{name}-{round}.json\``
- [ ] No reviewers listed that aren't in frontmatter

**Post-completion:**
- [ ] Checklist with items:
  - Report to decisions.md (with links to all review rounds)
  - Deviation description (if deviated from spec)
  - Spec update (if anything changed)

### D. Atomicity

Not derivable from sources of truth — inline validation rules.

- [ ] Single responsibility — one logical unit of work
- [ ] Scope: 1-3 files
- [ ] Produces testable result
- [ ] Does not sound like "implement entire X"
- [ ] **Logical cohesion** — task is one logical unit of work, not a mechanical split. Steps within the task should be related to one outcome. If removing any step would leave an incomplete/broken result — that's good cohesion. If steps are about unrelated concerns bundled together — that's a split candidate.

### E. Internal Consistency

- [ ] `frontmatter.skills` matches Required Skills section (same set)
- [ ] `frontmatter.reviewers` matches Reviewers section (same set)
- [ ] Verification Steps section always present (mandatory for all tasks)
- [ ] Skills ↔ reviewers mapping valid:
  - `code-writing` → includes `code-reviewer`, `test-reviewer`
  - `skill-master` → includes `skill-checker`

### F. Decomposition Quality (cross-task)

These checks require reading ALL tasks in the batch (not just individual tasks). Run after per-task checks.

- [ ] **Traceability to tech-spec**: task's "Files to modify" matches files listed for this task in tech-spec Implementation Tasks. New files not in tech-spec → severity `minor` (task-creator may have refined). Files from tech-spec dropped without reason → severity `major`
- [ ] **Dependency correctness**: `depends_on` values reference existing task numbers. Task with `depends_on: [X]` must have `wave` > wave of task X. Violation → severity `critical`
- [ ] **Merge candidates**: tasks with 3 files with unrelated changes should be split. If "What to do" steps address unrelated concerns → severity `major` with recommendation to split
- [ ] **Over-decomposition**: total task count proportional to feature scale. Heuristic: more than 3 tasks per user-spec requirement is suspicious. More than 8 tasks for a feature with ≤3 user stories → severity `major` with recommendation to merge related tasks
- [ ] **Dependency cycles**: no circular dependencies in `depends_on` chain. Build directed graph, check for cycles → severity `critical`

### G. Cross-Task Resource Sharing

When validating ALL tasks in a single batch (cross-task mode from task-decomposition):

- [ ] **Shared Resources compliance**: if tech-spec Architecture has Shared Resources table — each resource has exactly one task that creates it (owner). If no task creates the resource → severity `critical`
- [ ] **Consumer dependency**: tasks that consume a shared resource declare `depends_on` on the owner task. Missing dependency → severity `critical`
- [ ] **No competing instances**: tasks in the same wave do not each create their own instance of a shared resource. If two tasks in the same wave both create the same heavy resource → severity `critical`
- [ ] **Shared Resources completeness**: if multiple tasks reference the same heavy dependency (ML model, DB pool, API client) but tech-spec Shared Resources is empty or missing this resource → severity `major`

### H. Carry-forward from tech-spec

Cross-reference each task with its Implementation Tasks entry in tech-spec:

- [ ] **Acceptance Criteria carry-forward:** AC items from tech-spec are present in the task (not lost during decomposition). Task may extend/detail them but must not drop any.
- [ ] **TDD Anchor carry-forward:** TDD Anchor items from tech-spec are present in the task (not lost). Task may add more tests but must not drop any from tech-spec.

## Severity Guide

| Severity | When |
|----------|------|
| critical | Section missing; mandatory context file missing; frontmatter field missing or wrong type; template placeholder present; frontmatter↔body mismatch; AC/TDD lost from tech-spec; dependency cycle; missing dependency declaration; shared resource has no owner task; consumer missing depends_on on owner; competing resource instances in same wave |
| major | Merge candidate (3 files, unrelated); over-decomposition; logical cohesion issue; shared resource not listed in tech-spec Shared Resources |
| minor | Sections in wrong order; PK files missing; entry format imprecise; edge cases not considered; stylistic |

## Output

Write JSON report:

```json
{
  "validator": "task-validator",
  "batch": [1, 2, 3, 4, 5],
  "status": "approved | changes_required",
  "findings": [
    {
      "severity": "critical | major | minor",
      "category": "frontmatter | structure | content | atomicity | consistency | decomposition | resource-sharing | carry-forward",
      "task": 2,
      "section": "TDD Anchor",
      "issue": "TDD Anchor contains only test names without descriptions",
      "fix": "Add description to each test: `test_name` — what it verifies"
    }
  ],
  "stats": {
    "tasks_checked": 5,
    "issues_found": 3
  }
}
```

Report path: `{feature_path}/logs/tasks/template-batch{batch_number}-review.json`

`status: approved` when zero critical findings across all tasks. `status: changes_required` when any critical finding exists.

## Source & license

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

- **Author:** [pavel-molyanov](https://github.com/pavel-molyanov)
- **Source:** [pavel-molyanov/molyanov-ai-dev](https://github.com/pavel-molyanov/molyanov-ai-dev)
- **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-pavel-molyanov-molyanov-ai-dev-claude-agent-task-validator
- Seller: https://agentstack.voostack.com/s/pavel-molyanov
- 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%.