backend-worker

name	backend-worker
description	Implements Python code for the VibeGuard security scanner using TDD — writes tests first, then implements CLI, config, stack detection, rules, engines, reports, auto-fix, and LLM integration.

Backend Worker

Implements Python source code for the VibeGuard security scanner. Follows strict TDD (Red-Green-Refactor) and verifies all work via pytest, mypy, ruff, and manual CLI execution.

When to Use This Skill

• Implementing new scanner features (rules, engines, CLI commands, config, reports)
• Adding or modifying Python modules under vibeguard/
• Writing or updating tests under tests/
• Fixing bugs or refactoring existing scanner code
• Integrating LLM-powered analysis into scan rules
• Building auto-fix or report generation functionality

Required Skills

None

Work Procedure

1. Read the Feature Description and Preconditions

• Read the task description carefully. Identify which modules, rules, or subsystems are affected.
• Check for any preconditions (e.g., "stack detection must work before rules can run").
• Review docs/vibeguard-spec.json for architectural context and rule definitions.

2. Read Existing Code to Understand Patterns

• Read vibeguard/__init__.py for package version and structure.
• Read pyproject.toml for dependencies, tool config (ruff, mypy, pytest), and entry points.
• Read existing modules in the area you're modifying to match coding style, import conventions, and typing patterns.
• Use Grep and Glob to find related code, existing tests, and usage patterns.
• Key conventions:
  • Python 3.10+ with strict mypy typing
  • Click-based CLI (vibeguard/cli.py)
  • Rich for terminal output
  • PyYAML for config
  • httpx for HTTP (async)
  • Jinja2 for HTML report templates
  • ruff line-length: 100
  • pytest with asyncio_mode = "auto"

3. Write Failing Tests FIRST (Red Phase)

• Create or update test files in the appropriate tests/ subdirectory:
  • tests/test_rules/ — rule unit tests
  • tests/test_live/ — live scanner tests (use respx for HTTP mocking)
  • tests/test_fix/ — auto-fix tests
  • tests/test_reports/ — report generation tests
  • tests/test_integration/ — end-to-end scan tests
• Write tests that describe the expected behavior. Each test should fail because the implementation doesn't exist yet.
• Test both positive cases (vulnerability detected) and negative cases (clean code passes).
• Run tests to confirm they fail:

python -m pytest tests/ -v --tb=short -x

4. Implement Code to Make Tests Pass (Green Phase)

• Implement the minimum code needed to make all new tests pass.
• Place code in the correct module per the architecture:
  • vibeguard/core/ — scanner orchestrator, findings model, severity
  • vibeguard/source/ — AST engine, pattern engine, LLM engine, rules
  • vibeguard/live/ — header checker, TLS, bundle analyzer, path prober
  • vibeguard/stacks/ — stack-specific detection and checks
  • vibeguard/fix/ — fixer, branch manager, patch generator
  • vibeguard/report/ — JSON, Markdown, HTML, SARIF reporters
  • vibeguard/factory/ — Factory/Droid integration
• Follow existing patterns: use dataclasses or Pydantic for models, type annotations everywhere, docstrings on public functions.

5. Run Full Verification Suite

Run all three checks and fix any issues before proceeding:

# Install dev dependencies if needed (run once per session if imports fail)
pip install -e ".[dev]"

# Unit tests — all must pass
python -m pytest tests/ -v --tb=short

# Type checking — must pass with strict mode
python -m mypy vibeguard/

# Linting — must pass with zero violations
python -m ruff check vibeguard/ tests/

If any check fails, fix the issues and re-run until all three pass cleanly.

6. Manual CLI Verification

Run the VibeGuard CLI against test fixtures to verify end-to-end behavior:

# Scan a vulnerable fixture and verify findings are reported
vibeguard scan tests/fixtures/vulnerable_flask_app
vibeguard scan tests/fixtures/vulnerable_nextjs_app
vibeguard scan tests/fixtures/vulnerable_supabase_app

# Verify the output includes expected vulnerability categories
# Verify no crashes, clean exit code

If the CLI is not yet functional for the feature being built, note this in the handoff and skip this step.

7. Commit Changes

Stage and commit all new and modified files with a descriptive message:

git add -A
git commit -m "feat(<scope>): <concise description of what was implemented>"

Example Handoff

{
  "salientSummary": "Implemented Rule C (Exposed Secrets) with 12 regex patterns covering OpenAI, Stripe, SendGrid, AWS, and Supabase service_role keys. Pattern engine matches secrets in both Python and JavaScript source files.",
  "whatWasImplemented": [
    "vibeguard/source/rules/exposed_secrets.py — Rule C with 12 secret patterns",
    "vibeguard/source/pattern_engine.py — added multi-file regex scanning support",
    "tests/test_rules/test_exposed_secrets.py — 8 test cases (6 positive, 2 negative)"
  ],
  "whatWasLeftUndone": [
    "Remaining 138+ secret patterns not yet added (only 12 of 150+ implemented)",
    "JS bundle analysis for live scanning not yet connected to Rule C"
  ],
  "verification": {
    "commandsRun": [
      "python -m pytest tests/ -v --tb=short — 8/8 passed, 0 failed",
      "python -m mypy vibeguard/ — Success: no issues found",
      "python -m ruff check vibeguard/ tests/ — All checks passed"
    ],
    "interactiveChecks": [
      "vibeguard scan tests/fixtures/vulnerable_supabase_app — correctly reported 2 CRITICAL exposed secret findings",
      "vibeguard scan tests/fixtures/vulnerable_flask_app — correctly reported 1 CRITICAL exposed secret finding"
    ]
  },
  "tests": {
    "added": [
      "tests/test_rules/test_exposed_secrets.py::test_detects_openai_key",
      "tests/test_rules/test_exposed_secrets.py::test_detects_stripe_secret_key",
      "tests/test_rules/test_exposed_secrets.py::test_detects_aws_access_key",
      "tests/test_rules/test_exposed_secrets.py::test_detects_supabase_service_role",
      "tests/test_rules/test_exposed_secrets.py::test_detects_sendgrid_key",
      "tests/test_rules/test_exposed_secrets.py::test_detects_multiple_secrets_in_one_file",
      "tests/test_rules/test_exposed_secrets.py::test_ignores_placeholder_keys",
      "tests/test_rules/test_exposed_secrets.py::test_no_false_positive_on_clean_code"
    ]
  },
  "discoveredIssues": [
    "pattern_engine.py had no way to exclude .env files from secret scanning (they are covered by Rule I instead) — added exclude_patterns parameter to avoid double-reporting"
  ]
}

When to Return to Orchestrator

• All new tests pass (green)
• pytest, mypy, and ruff all pass cleanly
• Manual CLI verification confirms expected behavior (or noted as not yet applicable)
• Changes are committed
• Handoff summary is complete with all fields populated
• If blocked (e.g., missing fixture, dependency issue, architectural question), return immediately with a clear description of the blocker in discoveredIssues