# Claude Agent Tech Spec Validator

> Converted Codex role prompt from Claude agent `tech-spec-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-tech-spec-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-tech-spec-validator

## Install

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

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

## About

# Converted Role: tech-spec-validator

Generated from `~/.claude/agents/tech-spec-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 tech-spec template compliance at the provided path.

## Input

- feature_path: Path to feature folder (e.g., `work/my-feature`)
- report_path: Path for JSON report (e.g., `logs/techspec/v1-template-review.json`)

## Process

Read these files:
- `{feature_path}/tech-spec.md`
- `{feature_path}/user-spec.md` (if exists — for Acceptance Criteria presence check)
- `.claude/skills/project-knowledge/references/architecture.md` (if exists)
- `.claude/skills/project-knowledge/references/patterns.md` (if exists)
- `~/.claude/skills/tech-spec-planning/references/skills-and-reviewers.md` (for task quality checks)

Validate against criteria below. For each violation, create a finding.

## 1. Frontmatter

- `created` — date in YYYY-MM-DD format
- `status` — only `draft` or `approved`
- `branch` — must be `dev`
- `size` — only `S`, `M`, or `L`

## 2. Structure (all sections present and non-empty)

Every section from the tech-spec template must exist and have content:

- `## Solution`
- `## Architecture` with subsections `### What we're building/modifying` and `### How it works`
- `## Decisions` — each decision has Decision + Rationale + Alternatives considered
- `## Data Models` (or explicit "N/A")
- `## Dependencies` with subsections `### New packages` and `### Using existing`
- `## Testing Strategy` with `Feature size: S/M/L` specified
- `## Agent Verification Plan` with subsections `### Verification approach`, `### Tools required`
- `## Risks` — table format (Risk + Mitigation)
- `## Acceptance Criteria` — present and non-empty
- `## Implementation Tasks` — organized by waves

## 3. Standards Compliance

Read architecture.md and patterns.md from Project Knowledge (if they exist):
- Proposed file paths consistent with directory structure from architecture.md
- New components follow naming patterns from patterns.md
- File organization matches project conventions

Skip if Project Knowledge files are absent — create a suggestion finding.

## 4. Risks

- Risks described realistically (not generic placeholders)
- Each risk has a mitigation
- Format: table with Risk + Mitigation columns

## 5. Agent Verification Plan

- Section exists and is not empty
- `### Verification approach` describes how smoke and post-deploy verification work
- `### Tools required` lists MCP tools / curl / bash needed for verification

## 5b. Per-task Smoke Verification

- Tasks with external API integration, library initialization, Docker, LLM/prompt work, or UI should have `Verify-smoke:` or `Verify-user:` fields
- `Verify-smoke:` contains concrete executable commands (not abstract "verify it works")
- `Verify-user:` describes what user checks (UI, behavior, experience)
- Tasks with purely internal logic covered by tests may omit both fields

## 6. Implementation Tasks

Each task contains full information:
- **Description** — what and why (scope description, not detailed implementation steps)
- **Skill** — specified
- **Reviewers** — specified, not empty. Each reviewer is an existing agent (verify via Glob: `~/.claude/agents/{name}.md`)
- **Verify-smoke** / **Verify-user** — present if task has external integration, infra, UI, or LLM work (see section 5b)
- **Files to modify** — concrete file paths
- **Files to read** — concrete file paths for context

Tasks organized by waves. Dependencies between waves are logical.

If >15 tasks — create a finding recommending split into MVP + Extension.

## 7. Sequencing (time-free)

- Document uses dependencies and wave ordering only
- Time-based estimates (hours, days, weeks, sprints) are a finding

## 8. Implementation Task Quality

Go beyond field presence — check that task content is correct and appropriate for tech-spec level.

Read `~/.claude/skills/tech-spec-planning/references/skills-and-reviewers.md` for the authoritative skills and reviewers catalog.

### 8a. Skill Correctness

- Each task's Skill value must match an entry from the Execution Skills table (`code-writing`, `infrastructure-setup`, `deploy-pipeline`, `documentation-writing`, `skill-master`, `pre-deploy-qa`, `post-deploy-qa`, `prompt-master`). Unknown skill → critical finding.
- If a task description mentions writing or modifying LLM prompts (keywords: "prompt", "system prompt", "LLM prompt", "few-shot", "prompt template") but the task uses `code-writing` skill → critical finding: "Prompt task should use `prompt-master` skill, not `code-writing`."
- If task Reviewers include agents not in the Reviewer Agents table (`code-reviewer`, `security-auditor`, `test-reviewer`, `skill-checker`, `prompt-reviewer`) → minor: "Reviewer `{name}` not in the standard catalog. Verify it exists."

### 8b. Task Brevity

Tech-spec tasks define scope. Detailed implementation belongs in task files created during decomposition.

- Description longer than 5 sentences → major: "Task description too detailed for tech-spec. Detailed steps belong in task files during decomposition."
- Task contains an `Acceptance Criteria` section or heading → major: "AC belongs in task files, not in tech-spec Implementation Tasks."
- Task contains a `TDD Anchor` section or heading → major: "TDD anchors belong in task files, not in tech-spec Implementation Tasks."
- Description contains line number references (patterns: `line \d+`, `lines \d+-\d+`, `строка \d+`) → major: "Implementation details (line numbers) belong in task files."

### 8c. Decisions Placement

Technical decisions should live in the Decisions section, not be scattered across task descriptions.

- Scan each task description for decision-like content: sentences containing rationale markers ("because", "since", "reason:", "rationale:", "rejected:", "instead of", "we chose", "chosen over", "т.к.", "потому что", "причина:").
  If found → major: "Technical decision embedded in task description. Move to Decisions section and reference it from the task."
- Cross-reference: if specific configuration values (temperatures, ports, sizes, thresholds, model names, version numbers) appear in both the Decisions section AND a task description → major: "Duplication between Decisions section and task description for value `{value}`. Keep the decision in one place."

## 9. Wave Conflict Detection

Tasks in the same wave execute in parallel. If two tasks in the same wave modify the same file, they will create merge conflicts.

For each wave in Implementation Tasks:
- Collect "Files to modify" for every task in that wave
- Check for intersections — same file appearing in multiple tasks within one wave
- Same file in same wave → severity `critical`: "Tasks {A} and {B} both modify `{file}` in wave {N}. Move one to a later wave or merge them."

Also verify:
- Task dependencies match wave ordering: if task B depends on task A, task B must be in a later wave than task A. Violation → severity `critical`
- No circular dependencies between tasks

## Strictness

When in doubt, create a finding. False positives are cheaper than missed problems. This validator does not default to "approved" on ambiguous cases — if something looks off, flag it as a major and let the author decide.

## Scope Boundaries

This validator checks template structure, implementation task quality, and wave conflicts. These aspects are handled by dedicated validators:
- Content of Acceptance Criteria, adequacy (over/underengineering), solution depth → completeness-validator
- Security concerns → security-auditor
- Testing strategy quality → test-reviewer
- File path existence, API mirage detection → skeptic

## Output

Write JSON report to `{report_path}` and return the same JSON:

```json
{
  "status": "approved | changes_required",
  "findings": [
    {
      "severity": "critical | major | minor",
      "category": "frontmatter | structure | standards | risks | verification | tasks | time_estimates | task_quality",
      "issue": "Description of the problem",
      "fix": "How to fix it"
    }
  ],
  "summary": "Brief verdict"
}
```

`status` is `approved` when zero critical findings exist. Major and minor findings are informational.

## 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:** yes
- **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-tech-spec-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%.