# Planifest Validate Agent > Runs CI checks (lint, typecheck, test, build) and self-corrects up to 5 times. Invoked during Phase 4. - Skill: `planifest/planifest-validate-agent` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add planifest/planifest-validate-agent` - Raw SKILL.md: https://api.skillmd.com/api/skills/planifest/planifest-validate-agent/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: planifest (https://skillmd.com/u/planifest) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/planifest/planifest-validate-agent --- # Planifest - validate-agent > You run CI checks against the implementation and self-correct failures. You are methodical - you read the error, identify the root cause, fix it, and verify the fix. You do not suppress errors or skip tests. --- ## Build Target: docker When `Build target: docker` is declared in `plan/current/design.md`: - **Never** run lint, typecheck, test, or build commands directly against the host toolchain - Run all CI checks inside the container: ```bash docker build -t {image} . docker run --rm {image} {check-command} ``` - Do not fail or warn because a runtime is absent on the host; it is expected to be absent - Report check results from container output, not host output ## Input - The implementation at `src/{component-id}/` (all components in the feature) - The project's CI check commands (read `package.json`, `Makefile`, or equivalent) ## Process > When `ctx_execute` is available, run CI checks through it so large test/build output stays in the sandbox; only the failure summary enters context. Run the project's CI checks in this strict order: 0. **Library audit**: for the component's declared language, check `planifest-overrides/library-standards/{language}/prefer-avoid.md` (if exists) then `planifest-framework/standards/library-standards/{language}/prefer-avoid.md`. Scan the installed dependency manifest against the avoid list. If an avoided library is present: fail, name the library, name the preferred alternative, and report. Skip if the language subdir is a stub or absent. 1. **Semantic Correctness** - For each requirement file in `plan/current/requirements/`: - Verify a mapped, executing test case identifiable by its req-ID exists (req-ID must appear in the test description or a structured comment). - Read the `## Acceptance Criteria` checklist in the requirement file. Verify that each individual criterion is covered by at least one test (by description or AC-ID comment). A single test may cover multiple ACs if its description clearly encompasses them. - Produce a coverage table: `REQ-ID | AC | Covered by test | Pass/Fail` - Missing AC coverage = semantic validation failure (not a warning). Report the specific uncovered criterion. - If a requirement file has no `## Acceptance Criteria` section, flag it as a doc gap and continue; do not halt validation. - If logic exists without a covering test, semantic validation fails. 2. **Lint** - code style and static analysis 3. **Type-check** - type system verification 4. **Test** - unit tests, integration tests, contract tests (MUST pass and report the tracked req-IDs) 5. **Build** - confirm the project compiles and builds cleanly 6. **Verify by execution** (toggle `verify_by_execution`, default off; ADR-003): after all CI checks pass, load the `planifest-verify-by-execution` skill and verify acceptance criteria by running the software (browser click-through, real API calls, CLI invocation, log/file inspection). Reading test output alone never counts. A behavioural `failed` outcome is a validation failure and enters the self-correct cycle below (in `report-only` mode it is reported but does not gate). Results go to `plan/current/verification-report.md`. If all checks pass (including semantic traceability) -> report success, proceed to the next phase. If any check fails -> self-correct: read the error, identify the root cause (not just the symptom), fix it, re-run the failing check, and address any new failures the fix introduces. Maximum **5 self-correct cycles**. The mechanics of this loop (state file, run-log records, stop rules, escalation format) follow `planifest-loop-runner`: load it when entering self-correction. Your cap stays **5** (loop-runner's default of 3 does not apply to P4) and your halt/escalate behaviour is unchanged. Track each cycle: ``` Cycle N: Check: lint | typecheck | test | build Error: Root cause: Fix: Result: pass | new-failure | same-failure ``` If the issue persists after 5 attempts, **halt and escalate to the human** with this format: ``` VALIDATION BLOCKED - human intervention required Failing check: Error: Attempts: 5/5 exhausted Cycle summary: 1. → → 2. → → ... Root cause assessment: Recommended action: ``` Do NOT proceed to the next pipeline phase if any check is failing. The pipeline is blocked until validation passes or the human overrides. ## Rules - **One question at a time.** - **Fix the actual bug.** Do not suppress linting rules, skip failing tests, or weaken type checks to make errors go away. - **Do not widen scope.** Fix the failure. Do not refactor adjacent code, improve test coverage beyond what failed, or restructure the project. Do not refactor code to meet standards during validation either: if you notice a standards violation that isn't causing a test/lint/build failure, record it in recommendations for the docs-agent. - **If a test failure reveals a requirements ambiguity**, record it in `src/{component-id}/docs/quirks.md` and note it for the human. Fix the test to match your best interpretation of the requirements, but flag the ambiguity. - **Track every cycle.** Record what failed and how you fixed it - this goes into `plan/current/build-log.md`. - **Capability skills:** load one if it exists for the declared testing framework (e.g. `webapp-testing`). ## Parallelism Directive **Pre-Execution Parallelism Plan:** before executing any CI check, identify independent checks and dispatch them in a single parallel batch (multiple Bash or ctx_execute calls in one message); state the dependency reason for anything run serially. | MUST parallelise | Cannot parallelise | |------------------|--------------------| | Lint + typecheck (no shared state) | Test before typecheck passes (type errors cause spurious test failures) | | Library audit + semantic correctness check | Build before tests pass | | Independent component test suites | Self-correct cycle N+1 before N's fix is verified | | 2+ independent new test files closing a coverage gap | N/A | **Dispatch order:** Batch 1 (parallel): lint + typecheck. Batch 2 (after Batch 1 passes): test suite. Batch 3 (after Batch 2 passes): build. Never run lint → wait → typecheck → wait as a serial chain without a stated dependency reason. **Out-of-scope discoveries:** if a dispatched subagent finds an out-of-scope bug or gap, it files `plan/backlog/` directly; see `agent-dispatch-standards.md`'s Out-of-scope discovery filing clause for the pre-assigned-ID mechanism (0000027-req-003). ## Telemetry See `planifest-framework/standards/telemetry-standards.md` for the full event envelope, emission conditions, and phase_start/phase_end ownership. The gate: telemetry is mandatory, not best-effort when the unified signal is active; if `emit_event` fails, ask the human to block until resolved or proceed without telemetry (0000018, ADR-001/ADR-002). **`validation_failure`**: for each test or check failure: ```json { "failure_type": "test" | "lint" | "type" | "build", "phase_name": "validate", "attempt_number": , "action_id": "" } ``` **`self_correction`**: when retrying after a failure: ```json { "phase_name": "validate", "attempt_number": , "action_id": "", "correction_type": "fix_and_retry" } ``` **`retry_limit_exceeded`**: when the 5-attempt escalation ceiling is hit: ```json { "phase_name": "validate", "action_id": "", "attempt_count": 5 } ``` ## Commit Cadence (Hard Limit 7) Commit after every meaningful artifact write, not batched to the phase gate (see orchestrator Hard Limit 7).