DevGuardAI

AI-powered Cursor IDE plugin that validates whether your code changes fully satisfy a given requirement document (FSD / PRD / checklist). Built on markdown-first agents, skills, and workflows — no hardcoded static analysis engine inside.

What it does

Give DevGuardAI a requirement file and your code changes (git diff). It will:

1. Extract structured requirements from the document
2. Analyse the code diff (current branch vs main)
3. Identify impacted APIs, DTOs, validations
4. Map each requirement point to implementation evidence (full / partial / missing)
5. Detect gaps, risks, and missing edge cases
6. Generate a final AI Validation Report with coverage %, findings, and suggested tests

Every step is self-evaluated (scoring, retry, clarification) and every artifact is persisted under a unique transaction folder.

Install

cd /path/to/DevGuardAI
npm install
npx DevGuardAI install

Then restart Cursor (or Reload Window).

CLI commands: install | update | uninstall | status | help

How to trigger the pipeline

Option 1: Just type naturally (recommended)

Open your application repo in Cursor and type in chat:

analyse docs/sso-integration.txt check is all points covered with these changes

The bundled Cursor rule (.cursor/rules/DevGuardAI-auto-trigger.mdc, alwaysApply: true) catches phrases like "analyse", "validate", "check" + a file name and auto-routes into the full pipeline.

• Requirement file: the file you mention (e.g. docs/sso-integration.txt)
• Code changes: defaults to git diff main...HEAD (falls back to master...HEAD; asks only if neither branch exists)

Note: The rule file lives in the DevGuardAI workspace. To use it in other projects, copy it:

mkdir -p /path/to/your-app/.cursor/rules
cp .cursor/rules/DevGuardAI-auto-trigger.mdc /path/to/your-app/.cursor/rules/

Option 2: Reference the skill directly

@validate-feature analyse docs/sso-integration.txt against my current branch changes

Option 3: Explicit full instruction (most reliable, works anywhere)

Follow ~/.cursor/plugins/local/DevGuardAI/workflows/validate-feature.md

Requirement file: docs/sso-integration.txt
Changes: git diff main...HEAD

Run init-transaction.sh first, then execute all 6 phases with evaluation.
Write final report to DevGuardAI_analysis/<transid>/reports/validation-report.md

Option 4: Manual step-by-step (full control)

# 1. From your app repo root, create a transaction
~/.cursor/plugins/local/DevGuardAI/scripts/init-transaction.sh
# prints: DEV-20260514-191400-A3F1

# 2. Optionally capture the diff to a file
~/.cursor/plugins/local/DevGuardAI/scripts/git-diff-branches.sh main HEAD diff-output.txt

Then in Cursor chat:

Use DevGuardAI workflow validate-feature.md
transid: DEV-20260514-191400-A3F1
Requirement file: docs/sso-integration.txt
Diff file: diff-output.txt
Persist everything under DevGuardAI_analysis/DEV-20260514-191400-A3F1/

Prerequisites (before triggering)

| Requirement | Why | |-------------|-----| | Restart Cursor after install | So the plugin's skills and agents are loaded | | Open your app repo (not the plugin repo) | Pipeline reads code and git from the workspace you're in | | The requirement/FSD file exists in the workspace | e.g. docs/integration.txt — the file you want to validate against | | You are on a feature branch (not main) | So git diff main...HEAD produces meaningful changes | | Repo has a main or master branch | Used as the base for diff; if absent, the model asks once |

What you get after a run

All output is saved under DevGuardAI_analysis/<transid>/ in your workspace:

DevGuardAI_analysis/<transid>/
├── request/                     # What was requested (FSD path, git refs, metadata)
│   ├── request.json
│   ├── fsd.md
│   └── metadata.json
├── skills/                      # Per-phase skill artifacts
│   ├── requirement-analysis/    #   input.json, output.json, evaluation.json, ...
│   ├── code-analysis/
│   ├── api-analysis/
│   ├── mapping-analysis/
│   ├── gap-detection/
│   └── report-generation/
├── agents/                      # Per-agent I/O, confidence, retries
│   ├── requirement-agent/       #   input.json, generated-output.json, confidence.json, ...
│   ├── code-agent/
│   ├── api-agent/
│   ├── mapping-agent/
│   ├── gap-agent/
│   └── report-agent/
├── evaluations/                 # Self-evaluation scoring per phase
│   ├── requirement-eval/        #   scoring.json, recommendations.json, ...
│   ├── code-eval/
│   ├── api-eval/
│   ├── mapping-eval/
│   ├── gap-eval/
│   └── report-eval/
├── execution/                   # Temporary generated scripts + results
│   ├── generated-code/
│   ├── execution-results/
│   └── runtime-logs/
├── clarification/               # Questions asked + answers received
├── reports/                     # ★ Final output
│   ├── validation-report.md     #   The main report
│   ├── validation-report.json   #   Machine-readable mirror
│   └── summary.json             #   One-screen rollup
└── audit/                       # Execution trace, workflow state, timing
    ├── execution-trace.json
    ├── workflow-state.json
    ├── retries.json
    └── timing.json

The key file: reports/validation-report.md — contains coverage %, fully covered items, partial coverage, missing items, risks, suggested tests, and impacted APIs.

Pipeline flow

User prompt ("analyse fsd.txt against these changes")
    ↓
Auto-trigger rule matches → binds FSD file + git diff main...HEAD
    ↓
Init transaction (scripts/init-transaction.sh) → transid
    ↓
┌─────────────────────────────────────────────┐
│  Phase 1: Requirement extraction            │
│    → Evaluate → PASS / improve / clarify    │
├─────────────────────────────────────────────┤
│  Phase 2: Code diff analysis                │
│    → Evaluate → PASS / improve / clarify    │
├─────────────────────────────────────────────┤
│  Phase 3: API impact analysis               │
│    → Evaluate → PASS / improve / clarify    │
├─────────────────────────────────────────────┤
│  Phase 4: Requirement ↔ Code mapping        │
│    → Evaluate → PASS / improve / clarify    │
├─────────────────────────────────────────────┤
│  Phase 5: Gap & risk detection              │
│    → Evaluate → PASS / improve / clarify    │
├─────────────────────────────────────────────┤
│  Phase 6: Final validation report           │
│    → Evaluate → PASS / improve / clarify    │
└─────────────────────────────────────────────┘
    ↓
Final report → DevGuardAI_analysis/<transid>/reports/validation-report.md

What ships (plugin contents)

| Piece | Role | | --- | --- | | .cursor-plugin/plugin.json | Cursor plugin manifest (skills, agents) | | .cursor/rules/DevGuardAI-auto-trigger.mdc | Auto-routes informal prompts into the pipeline | | skills/*/SKILL.md | 7 phase skills + orchestrator (validate-feature) | | skills/evaluators/*/SKILL.md | 6 post-generation evaluation skills | | agents/*.md | 6 primary phase agents (requirement → report) | | agents/evaluators/*.md | 6 evaluation agents paired 1:1 with phases | | workflows/*.md | Ordered sequences: validate-feature, analyze-api-impact, analyze-requirement-coverage | | prompts/*.md | Clarification, extraction, reporting, evaluation, transaction-storage, user-intent-routing | | scripts/init-transaction.sh | Creates DevGuardAI_analysis/<transid>/ tree; prints transid | | scripts/git-diff-branches.sh | base...head or two-dot diff helper with optional output file | | scripts/save-validation-report.sh | Pipe report to validation-reports/ for sharing | | docs/ | Architecture specs: requirement.md, eval.md, trans.md |

Customize

• Add skills under skills/<id>/SKILL.md (YAML name + description required).
• Add agents as agents/<name>.md (frontmatter name, description).
• Extend bin/cli.js CONTENT_DIRS if you add new top-level folders to copy.

V1 scope

Initial stack focus: Node.js / TypeScript / Express / NestJS (per docs/requirement.md).

Non-goals for V1: no autonomous coding, no auto-PR generation, no auto-fixing, no full repository indexing, no test execution, no security scanning.

Update / Uninstall

# Update (after editing skills/agents/prompts)
npx DevGuardAI update

# Remove from Cursor
npx DevGuardAI uninstall

Always restart Cursor after install/update/uninstall.

License

MIT