How to Use Agile V Skills: Turning AI Coding into Verifiable Engineering

A practical tutorial for using Agile V Skills to make AI-generated software traceable, testable, and reviewable — not just impressive-looking.

AI coding tools are excellent at producing working-looking code quickly.

But there is a problem: working-looking code is not the same as verified engineering work.

A typical AI workflow often looks like this:

Prompt → code → maybe tests → ship

That can be fine for prototypes. But for production systems, regulated environments, embedded software, lab automation, internal platforms, or anything that needs long-term maintenance, this is not enough.

You need to know:

• What requirement does this code satisfy?
• How was it tested?
• Who reviewed it?
• What assumptions were made?
• What risks remain?
• What changed between versions?
• Can another engineer understand and verify the result?

That is where Agile V Skills come in.

Agile V Skills are designed to make AI-assisted engineering more inspectable. The goal is not to make AI output look better. The goal is to check how good the output really is.

The core idea

Agile V combines agile iteration with V-model-style verification.

Instead of letting an AI agent jump directly into code, Agile V guides the agent through a controlled engineering workflow:

Intent
→ Requirements
→ Requirement validation
→ Build
→ Independent test design
→ Red Team verification
→ Evidence records
→ Human approval

The output is not only source code.

The output is source code plus evidence:

requirements
tests
build manifest
validation summary
traceability matrix
decision log
risk register
approval records

This makes the work easier to review, audit, maintain, and improve.

When should you use Agile V Skills?

Use Agile V Skills when the work needs more than quick code generation.

Good use cases include:

• production features;
• firmware and embedded software;
• lab or manufacturing tools;
• medical, pharma, GxP, or other regulated environments;
• internal systems that need maintenance;
• security-sensitive features;
• multi-cycle change requests;
• code that must be reviewed or audited later.

You may not need the full Agile V workflow for:

• throwaway scripts;
• quick prototypes;
• simple UI mockups;
• low-risk experiments.

For small tasks, use a lightweight version:

Requirements → Build → Test → Validation Summary

For serious engineering work, use the full workflow.

The main Agile V Skills

The Agile V Skills library contains specialized skills for different parts of the workflow.

SkillPurposeagile-v-coreCore process rules, traceability, state, human gatesrequirement-architectTurns product intent into formal requirementslogic-gatekeeperChecks requirements for ambiguity and conflictsbuild-agentBuilds implementation from approved requirementstest-designerDesigns tests from requirements onlyred-team-verifierIndependently verifies the implementationcompliance-auditorCreates traceability, decision logs, and validation evidencedocumentation-agentGenerates structured project documentation

There are also domain-specific build agents:

domains/build-agent-python/
domains/build-agent-js/
domains/build-agent-dart/
domains/build-agent-embedded/
domains/build-agent-nestjs/

Use these when the language or framework is known.

Examples:

Project typeSkills to usePython API or CLIbuild-agent + build-agent-pythonReact, Next.js, Node.jsbuild-agent + build-agent-jsFlutter appbuild-agent + build-agent-dartEmbedded C/C++build-agent + build-agent-embeddedNestJS backendbuild-agent + build-agent-nestjs

Step 1: Install the skills

Claude Code

In Claude Code, install the plugin:

/plugin install agile-v-skills

Or install directly from GitHub:

/plugin install https://github.com/Agile-V/agile_v_skills

For project-specific use, you can also copy the CLAUDE.md file into your project root.

Cursor

For Cursor, copy the skills into your project:

mkdir -p .cursor/skills
cp -r agile-v-core .cursor/skills/
cp -r requirement-architect .cursor/skills/
cp -r logic-gatekeeper .cursor/skills/
cp -r build-agent .cursor/skills/
cp -r test-designer .cursor/skills/
cp -r red-team-verifier .cursor/skills/
cp -r compliance-auditor .cursor/skills/

For a JavaScript or TypeScript project:

cp -r domains/build-agent-js .cursor/skills/

For a Python project:

cp -r domains/build-agent-python .cursor/skills/

For embedded work:

cp -r domains/build-agent-embedded .cursor/skills/

VS Code / GitHub Copilot

For global skills:

mkdir -p ~/.copilot/skills
cp -r agile-v-core ~/.copilot/skills/
cp -r requirement-architect ~/.copilot/skills/
cp -r logic-gatekeeper ~/.copilot/skills/
cp -r build-agent ~/.copilot/skills/
cp -r test-designer ~/.copilot/skills/
cp -r red-team-verifier ~/.copilot/skills/
cp -r compliance-auditor ~/.copilot/skills/

For project-level skills, use a repository folder such as:

.github/skills/
.claude/skills/
.agents/skills/

depending on your agent environment.

Step 2: Set up the Agile V evidence directory

Agile V works best when evidence is persisted in the project.

Create a directory:

mkdir -p .agile-v

A typical Agile V project will contain:

.agile-v/
  STATE.md
  REQUIREMENTS.md
  BUILD_MANIFEST.md
  TEST_SPEC.md
  VALIDATION_SUMMARY.md
  DECISION_LOG.md
  TRACEABILITY_MATRIX.md
  RISK_REGISTER.md
  CHANGE_LOG.md
  APPROVALS.md

You do not need to create all files manually. The agent can create them as the process runs.

But it helps to tell the agent:

Use .agile-v/ as the persistent Agile V evidence directory.

Step 3: Start with intent, not code

Do not begin by saying:

Build this feature.

Start with product intent and require the agent to create requirements first.

Example prompt:

Use Agile V.

Product intent:
Build a browser-based TimeTracker app.

The app shall:
- create projects,
- start and stop timers,
- store entries locally,
- show total time per project,
- prevent invalid input,
- work without a backend.

First, invoke the requirement-architect.
Create .agile-v/REQUIREMENTS.md with REQ-XXXX IDs and acceptance criteria.
Do not implement yet.

This should produce formal requirements such as:

REQ-0001: Project creation

The system shall allow the user to create a project with a non-empty name.

Acceptance criteria:
- Given a valid name, a project is created.
- Given an empty name, the system rejects the input.
- Given a name longer than the allowed limit, the system rejects the input.

The key rule:

No requirement, no code.

Step 4: Validate the requirements

Before implementation, use the Logic Gatekeeper.

Example prompt:

Use the logic-gatekeeper skill.

Review .agile-v/REQUIREMENTS.md for:
- ambiguity,
- missing acceptance criteria,
- conflicting requirements,
- unrealistic assumptions,
- unclear runtime constraints,
- missing definition of done.

Do not implement yet.

A useful result may be a halt condition:

HALT CONDITION:
REQ-0004 says “fast response time,” but no measurable threshold is defined.

Please clarify:
- maximum response time,
- target browser/device,
- expected data size.

This is a good sign.

Agile V is working when the agent stops instead of guessing.

Step 5: Approve requirements at Human Gate 1

Once the requirements are clear, approve them.

Example prompt:

Human Gate 1 approval:

I approve .agile-v/REQUIREMENTS.md as the source of truth for this cycle.

Proceed with:
1. independent test design from requirements only,
2. implementation from requirements,
3. evidence generation.

For serious work, record approval in:

.agile-v/APPROVALS.md

Step 6: Design tests before building

This is important.

If you are running everything in one chat or one agent environment, ask the Test Designer to create the tests before the Build Agent writes code.

Why?

Because the Test Designer should derive tests from requirements only, not from the implementation.

Example prompt:

Use the test-designer skill.

Read only .agile-v/REQUIREMENTS.md.
Do not inspect or infer from implementation code.

Create .agile-v/TEST_SPEC.md with test cases linked to REQ-XXXX IDs.

Include:
- positive tests,
- negative tests,
- edge cases,
- persistence tests,
- regression tests if applicable.

Expected output:

TC-0001 → REQ-0001: Create project with valid name
TC-0002 → REQ-0001: Reject empty project name
TC-0003 → REQ-0001: Reject overlong project name

This avoids the common AI failure mode where the same agent writes both the code and tests, and the tests only confirm the implementation’s assumptions.

Step 7: Build from approved requirements

Now run the Build Agent.

For JavaScript or TypeScript:

Use build-agent and domains/build-agent-js.

Implement the system according to .agile-v/REQUIREMENTS.md.
Use .agile-v/TEST_SPEC.md as the expected verification target.

Rules:
- Link every source file or major function to REQ-XXXX.
- Create .agile-v/BUILD_MANIFEST.md.
- Do not silently change requirements.
- If a requirement is unclear, halt and ask.

For Python:

Use build-agent and domains/build-agent-python.

Implement the approved requirements in Python.
Create clear module structure, tests, and build manifest.
Every artifact must link to REQ-XXXX.

The build manifest should map artifacts to requirements:

ART-0001: src/timer.js
Implements: REQ-0002, REQ-0003

ART-0002: src/storage.js
Implements: REQ-0005

Step 8: Run independent Red Team verification

After implementation, use the Red Team Verifier.

Example prompt:

Use red-team-verifier.

Verify the implementation against:
- .agile-v/REQUIREMENTS.md
- .agile-v/TEST_SPEC.md
- .agile-v/BUILD_MANIFEST.md

Perform independent verification.

Look for:
- missing requirement coverage,
- broken behavior,
- weak validation,
- security problems,
- placeholder code,
- TODOs,
- hardcoded secrets,
- untested edge cases,
- traceability gaps.

Write results to .agile-v/VALIDATION_SUMMARY.md.

A good Red Team result is not always “everything passed.”

A good Red Team result is honest.

Example:

VER-0001: FAIL
Requirement: REQ-0004
Issue: Timer allows stopping before start.
Severity: MAJOR
Required action: Build Agent must add state validation.

This is the heart of Agile V.

The goal is not to make the work look good.

The goal is to find out how good it really is.

Step 9: Rework based on Red Team findings

If Red Team finds problems, send them back to the Build Agent.

Example prompt:

Use build-agent.

Read .agile-v/VALIDATION_SUMMARY.md.
Fix all CRITICAL and MAJOR findings.
Do not modify approved requirements unless a change request is created.
Update .agile-v/BUILD_MANIFEST.md after changes.

Then verify again:

Use red-team-verifier.

Re-run verification after the fixes.
Append new results to .agile-v/VALIDATION_SUMMARY.md.
Do not overwrite previous findings.

A practical rule:

CRITICAL: must be fixed
MAJOR: must be fixed or formally deferred
MINOR: may be accepted with rationale

Step 10: Generate traceability and evidence records

After verification, use the Compliance Auditor.

Example prompt:

Use compliance-auditor.

Create or update:
- .agile-v/TRACEABILITY_MATRIX.md
- .agile-v/DECISION_LOG.md
- .agile-v/RISK_REGISTER.md
- .agile-v/VALIDATION_SUMMARY.md

Ensure every requirement links to:
- implementation artifact,
- test case,
- verification result,
- unresolved risk if any.

Expected traceability structure:

REQ-0001 → ART-0001 → TC-0001 → VER-0001 PASS
REQ-0002 → ART-0002 → TC-0004 → VER-0004 PASS
REQ-0003 → ART-0003 → TC-0008 → VER-0008 FAIL

This is where Agile V becomes valuable.

It shows what is verified, what is not verified, and what still needs attention.

Step 11: Human Gate 2

Before release or merge, require final approval.

Example prompt:

Prepare Human Gate 2 evidence summary.

Include:
- scope,
- requirements covered,
- tests executed,
- pass/fail summary,
- known defects,
- risks,
- decisions,
- traceability status,
- release recommendation.

Do not mark the work approved. Await explicit human approval.

Example output:

Human Gate 2 Evidence Summary

Scope:
Timer feature, project creation, local persistence.

Requirements:
7 total, 7 implemented, 7 verified.

Verification:
24 test cases, 23 pass, 1 minor finding accepted.

Risks:
RISK-0002 accepted with mitigation.

Recommendation:
Ready for approval with minor known limitation.

Status:
Awaiting human approval.

Then approve or reject:

Human Gate 2 approval:

I approve release of this cycle.
Record approval in .agile-v/APPROVALS.md.

Working with existing codebases

If you are changing an existing system, add a Gate 0 understanding phase.

Use skills such as:

system-understanding-agent
impact-analysis-agent
graph-traceability-agent
regression-selection-agent
diff-evidence-agent

Example prompt:

Use Agile V Gate 0.

Analyze the existing codebase before proposing changes.

Create:
- .agile-v/SYSTEM_OVERVIEW.md
- .agile-v/IMPACT_MAP.md
- .agile-v/REGRESSION_PLAN.md

Then convert the change request into formal requirements.

For a change request:

Change request:
Add export to CSV for all time entries.

Use impact-analysis-agent to identify:
- affected files,
- affected requirements,
- affected tests,
- regression risks,
- data-format risks.

Then proceed through the normal Agile V workflow.

Multi-cycle workflow

Agile V supports repeated cycles.

Use this when you add changes after the first validated build.

Example:

Start Cycle 2.

Change request:
Add project color labels.

Create CR-0001.
Identify impacted requirements.
Mark requirements as:
- new,
- modified,
- unchanged,
- deprecated,
- superseded.

Preserve Cycle 1 evidence.

Recommended structure:

.agile-v/
  cycles/
    C1/
      REQUIREMENTS.md
      VALIDATION_SUMMARY.md
      TRACEABILITY_MATRIX.md
    C2/
      REQUIREMENTS.md
      VALIDATION_SUMMARY.md
      TRACEABILITY_MATRIX.md
  CHANGE_LOG.md

The key rule:

Do not lose old evidence when creating new evidence.

Minimal Agile V for small tasks

For small tasks, use a compressed version:

1. Create 3–7 requirements.
2. Validate ambiguity.
3. Generate tests from requirements.
4. Build.
5. Verify.
6. Produce a short validation summary.

Example prompt:

Use a lightweight Agile V workflow.

Create concise requirements, tests, implementation, and validation summary.
Keep evidence minimal but traceable.

This avoids unnecessary process overhead while keeping the core quality controls.

Full Agile V for serious tasks

For production, regulated, or long-lived work, use the full workflow:

Gate 0: Understand existing system
Gate 1: Approve requirements
Independent test design
Build from approved requirements
Red Team verification
Rework loop
Compliance evidence
Gate 2: Approve release
Cycle archive

Use the full workflow when:

• people will maintain the result;
• there are audit or compliance expectations;
• defects have high cost;
• requirements may change;
• safety, security, or data integrity matter.

How to know Agile V is working

Agile V is active if you see these behaviors:

Requirements before code

The agent refuses to implement before requirements exist.

Good sign:

HALT CONDITION: No requirement specification found.

Traceability everywhere

Files and functions reference requirement IDs.

Example:

// ART-0002: Timer state manager
// Implements: REQ-0003, REQ-0004

Independent verification

The Build Agent does not grade itself.

The Red Team Verifier checks the output separately.

Evidence files appear

You see files like:

.agile-v/REQUIREMENTS.md
.agile-v/TEST_SPEC.md
.agile-v/BUILD_MANIFEST.md
.agile-v/VALIDATION_SUMMARY.md
.agile-v/TRACEABILITY_MATRIX.md
.agile-v/DECISION_LOG.md

Human gates happen

The agent stops before major approval points.

Good sign:

Awaiting Human Gate 2 approval.

Common mistakes

Mistake 1: Starting with implementation

Bad:

Build this feature now.

Better:

Create requirements first. Do not implement until Gate 1 approval.

Mistake 2: Letting the Build Agent write its own tests only

Bad:

Build the feature and test it.

Better:

Run test-designer first. It must create tests from requirements only.
Then run build-agent.
Then run red-team-verifier independently.

Mistake 3: Treating evidence as decoration

Bad:

Generate docs after the code is done.

Better:

Maintain requirements, decisions, traceability, and validation evidence throughout the cycle.

Mistake 4: Ignoring failed evidence checks

Bad:

The app works, so ship it.

Better:

The app works, but traceability is incomplete.
Fix traceability or record a formal acceptance decision.

Practical checklist

Before starting:

[ ] Skills installed in your agent/editor
[ ] agile-v-core available
[ ] requirement-architect available
[ ] logic-gatekeeper available
[ ] build-agent available
[ ] test-designer available
[ ] red-team-verifier available
[ ] compliance-auditor available
[ ] domain-specific build agent copied if needed
[ ] .agile-v/ directory ready

Before implementation:

[ ] REQUIREMENTS.md exists
[ ] Every requirement has REQ-XXXX ID
[ ] Every requirement has acceptance criteria
[ ] Logic Gatekeeper reviewed requirements
[ ] Human Gate 1 approval recorded
[ ] Test Designer created TEST_SPEC.md

Before release:

[ ] Build manifest maps artifacts to requirements
[ ] Red Team verification completed
[ ] All CRITICAL findings fixed
[ ] MAJOR findings fixed or formally dispositioned
[ ] Traceability matrix complete
[ ] Decision log updated
[ ] Risk register updated
[ ] Validation summary complete
[ ] Human Gate 2 approval recorded

Final thought

Without Agile V, an AI coding workflow often looks like this:

Prompt → code → maybe tests

With Agile V, the workflow becomes:

Intent
→ requirements
→ approval
→ independent tests
→ build
→ Red Team verification
→ evidence
→ approval

That difference matters.

The future of AI engineering is not only about generating code faster.

It is about knowing whether the generated work is actually good.