screw-agents

Modular secure-code-review agents built around a shared MCP server.

screw-agents provides vulnerability-specific security review knowledge as YAML agents and exposes that knowledge through a Python MCP server. The repository ships a Claude Code plugin today, but the command, agent, skill, and MCP tool semantics are intended to be host-agnostic: Codex, Gemini, local assistants, web application workers, CI, editor integrations, and future plugin hosts should be able to run the same capabilities through equivalent adapters.

The durable asset is the curated knowledge in domains/**/*.yaml. The Python server is the common backend for Claude Code, Codex, future web application integration, screw.nvim, CI, and other clients.

Status: pre-alpha research/product build. Phase 6 Move 1.5 PREP is complete (zero-touch agent onboarding infrastructure, PR-D1 → PR-D6, 2026-05-27 → 2026-05-28); Move 2 (four-agent expansion) Bucket 1 shipped PRs 1-4 and Bucket 2 (combined benchmark/gate) closed 2026-06-03. The active agents are sqli, cmdi, ssti, xss, path_traversal (v1.0.2 — go, java, python, javascript gate-backed validated; 7 other supported languages research-only — Move 1 PR-C, the project's first completed Stage-6 refinement, shipped 2026-05-29), xpath (CWE-643 XPath injection, research-only — Move 2 PR 1), deserialization (CWE-502 insecure deserialization — v1.0.1, java validated under a {tpr≥0.75, fpr≤0.25} gate, php/python/other langs research-only — Move 2 Bucket 2), ssrf (CWE-918 server-side request forgery, research-only — Move 2 PR 3 / Bucket 2: 5/7 recall, not gated), weak_crypto (CWE-327 + CWE-326 broken/risky cryptography, the cluster's first property — non-dataflow — agent, research-only — Move 2 PR 4, 2026-06-01), and ldap_injection (CWE-90 LDAP injection, research-only — Cluster 1 PR 1 of the post-Move-2 remaining-agent onboarding campaign, 2026-06-04), and nosql_injection (CWE-943 NoSQL injection, research-only — Cluster 1 PR 2, 2026-06-04; operator/type-injection vs syntax/string-injection precision split), and header_injection (CWE-113 HTTP header injection / response splitting, research-only — Cluster 1 PR 3, 2026-06-04; the platform-auto-rejection inversion — most modern runtimes already reject CRLF in header values, so the live findings are the R1–R7 residual vectors; 11 langs incl c/cpp for the raw-CGI surface), and log_injection (CWE-117 log injection / log forging, research-only — Cluster 1 PR 4, 2026-06-05, closing Cluster 1; a two-gate / two-axis agent — neutralization gate (structured-field logging is SAFE, text is REAL) AND impact gate (the cry-wolf control: every app logs user input), across the CRLF-forging and ANSI/control-char \x1b axes; the most taxonomically divergent agent — CWE-1407 not 1409, OWASP A09 not A05, no CWE-74 in related[]), and broken_access (CWE-862 missing authorization, research-only — Cluster 2 PR 1, 2026-06-05, opening the access-control & auth cluster; the campaign's first property/absence agent — the bug is a MISSING ownership/role/tenant predicate, with no syntactic sink — and the first agent with needs_related_context: true, since authorization is enforced out-of-band), and auth_failures (CWE-287 improper authentication, research-only — Cluster 2 PR 2, 2026-06-06; a MIXED-shape agent — Shape-A local-damning signals (md5'd passwords, identity from a client cookie, predictable reset tokens) emit un-gated, while Shape-B absence signals (no lockout, no session regeneration, no MFA) pass a cry-wolf gate; re-homed from protection-mechanism to access-control per CWE-1400 verification; OWASP A07:2025), and csrf (CWE-352 cross-site request forgery, research-only — Cluster 2 PR 3, 2026-06-06; the first agent in the new data-authenticity-verification domain; a property/absence agent with a platform-mitigation inversion — browsers default SameSite=Lax and frameworks ship CSRF-on, so the textbook "no token on a POST" is a false positive by default, and the real signals are explicit-disable patterns + the residual vectors; agent OWASP A01:2025), and jwt_validation (CWE-347 improper verification of a cryptographic signature, research-only — Cluster 2 PR 4, 2026-06-06, closing Cluster 2; the 2nd agent in the cryptography domain — relocated there from data-authenticity per CWE-1400 verification; a concrete-pattern agent whose precision comes from library-default knowledge of which verify/decode call actually checks the signature — covering no-verify, alg:none, HS/RS algorithm confusion, kid/jku trust, and missing claims; OWASP A04:2025), xxe (CWE-611 XML external entity injection, research-only — Cluster 3 PR 1, 2026-06-06, opening Cluster 3 (web component/integration); the 4th agent in the access-control domain — relocated there from component-interaction per CWE-1400 verification (CWE-611 ∈ CWE-1396, not CWE-1398); a taint/source→sink agent with a parser-config safe-by-default cry-wolf inversion — the parser CONFIGURATION, not the input taint, decides; 11 languages incl. c/cpp; OWASP A02:2025 Security Misconfiguration), and unsafe_reflection (CWE-470 use of externally-controlled input to select classes or code, research-only — Cluster 3 PR 2, 2026-06-06; the 2nd agent in the resource-control domain — relocated there from component-interaction per CWE-1400 verification (CWE-470 ∈ CWE-1415, same domain as deserialization, both ChildOf CWE-913, not CWE-1398); a taint/source→sink agent with the WHICH-not-WHAT principle — externally-controlled input selecting WHICH class/method/module loads with no allowlist is the finding, while reflection on a constant/config/allowlisted name is the dominant false positive; 11 languages incl. c/cpp on narrow FFI/plugin tells; needs_related_context: true; OWASP A05:2025 Injection), and file_upload (CWE-434 unrestricted upload of file with dangerous type, research-only — Cluster 3 PR 3, 2026-06-07; the FIRST agent in the ⭑new resource-lifecycle domain — relocated there from file-handling per CWE-1400 verification (CWE-434 ∈ CWE-1416, ChildOf CWE-669, not CWE-1404); a taint/source→sink agent whose universal rule is "an attacker-supplied file reaches a location where its TYPE gives it power — webshell-executable web dir / same-origin active content / attacker-named path — without a sound type allowlist + server-side content verification + safe storage," with the key thesis content inspection reduces risk; execution context decides it and a cry-wolf inversion (a properly-controlled upload is SAFE — the dominant false positive); 9 languages (no c/cpp), go/rust on honest- indirection tells; needs_related_context: true; OWASP A06:2025 Insecure Design), and open_redirect (CWE-601 URL redirection to untrusted site, research-only — Cluster 3 PR 4, 2026-06-07, closing Cluster 3; the 5th agent in the access-control domain — relocated there from exposed-resource per CWE-1400 verification (CWE-601 ∈ CWE-1396, ChildOf CWE-610 like ssrf, not CWE-1403); the browser-navigate cousin of ssrf — attacker data determines the destination HOST/SCHEME of a client-side redirect without a sound parsed-host allowlist or relative-only control, with the validator-vs-navigator soundness oracle (a startsWith/contains check is never sound — //evil.com/@/subdomain bypasses), a cry-wolf inversion (a relative/named-route/allowlisted redirect is SAFE — the dominant false positive), and the OAuth/SSO redirect_uri severity elevation (token/code theft → account takeover); 8 languages (no c/cpp); OWASP A01:2025 Broken Access Control). The remaining ~18 catalog agents are being onboarded in 7 clusters of ~4, Bucket 1 (author) first across all clusters, then Bucket 2 (benchmark/gate).

Why This Exists

General "review this code" prompts are too broad for serious security work. High-quality security review needs specialist knowledge: precise CWE/CAPEC scope, framework-specific vulnerability shapes, true-positive and false-positive discriminators, bypass patterns, and remediation guidance.

screw-agents turns that knowledge into dedicated agents that can be reused from multiple clients through the same backend.

Core goals:

Provide dedicated agents for individual vulnerability classes.
Organize coverage with CWE-1400 as the structural taxonomy.
Keep agent knowledge editable and reviewable as YAML.
Resolve scan targets consistently with tree-sitter.
Emit structured findings in machine-readable and human-readable formats.
Learn from false positives at project scope.
Support adaptive analysis for unfamiliar project-specific patterns.
Validate agent behavior with benchmark infrastructure before expanding.

Current Capabilities

Implemented today:

Python MCP server with stdio and streamable HTTP transports.
Claude Code and Codex plugin metadata for the portable assistant command/plugin surface under plugins/screw.
Universal assistant command contract for scan, learning, adaptive cleanup, challenger/provider modes, and future commands.
Universal /screw:scan command.
Five accepted vulnerability agents:
- sqli — SQL injection (CWE-89)
- cmdi — OS command injection (CWE-78)
- ssti — server-side template injection (CWE-1336)
- xss — cross-site scripting (CWE-79)
- path_traversal — directory/file path traversal (CWE-22; v1.0.2 — go, java, python, javascript gate-backed validated, 7 other languages research-only)
Target resolution for files, directories, globs, git diffs, commits, pull requests, classes, functions, and line ranges.
Supported parser languages: Python, JavaScript, TypeScript, Go, Rust, Java, Ruby, PHP, C, C#, and C++.
Output formats: JSON, Markdown, CSV, and SARIF.
Challenger run metadata in JSON, Markdown, and SARIF outputs when supplied through scan metadata.
Project-local learning through .screw/learning/exclusions.yaml.
Trust model for signed exclusions and adaptive scripts.
Adaptive script staging, review, promotion, sandboxed execution, and cleanup.
CWE-1400-native benchmark runner and controlled autoresearch workflow.
Phase 4 calibration and closure evidence for the current agent set.
Phase 5 multi-LLM challenger system signed off: provider-neutral primary scan contracts, composed primary+challenger workflows in both directions (Claude/Codex), parallel-provider reconciliation, and the provider-scan CLI surface — see PHASE_5_CLOSURE_READINESS.md.
Phase 5.5 web application integration: SynApSec (github.com/h0pes/synapsec) consumes screw-agents as an external MCP engine. All five provider modes (Codex-only, Claude-only, Codex-primary/Claude-challenger, Claude-primary/Codex-challenger, parallel) execute through the screw-agents MCP server from SynApSec's backend.
Phase 6 Move 0: capability catalog contract (get_capabilities MCP tool, catalog_schema_version: "1.0", artifact_schema_version: "1.0") plus the path_traversal pilot agent.
Phase 6 Move 1 PR-B: path_traversal Wave-A benchmark calibration (Go validated; ten other supported languages research-only).
Phase 6 Move 1.5 PREP: zero-touch agent onboarding infrastructure shipped via PR-D1 → PR-D6 (2026-05-27 → 2026-05-28). New agents reach end-to-end discovery in under a week without Python source edits beyond a one-line ACTIVE_CWES registration.
Phase 6 Move 1 PR-C (2026-05-29): path_traversal YAML v1.0.1 — the project's first completed Stage-6 refinement. Six new/widened heuristics from Tier-3 re-research + a sink-file-verified Wave-B re-benchmark flipped java, python, javascript to validated (4 of 11 languages).
Explicit challenger attachment during finalize_scan_results for configured dry-run or opt-in CLI modes.
Assistant-facing /screw:scan flags for explicit challenger review: --challenger <mode> --challenger-execution dry_run|cli.
Provider-neutral primary scan contracts and a fixture primary scanner for validating first-pass scanner output against the shared Finding schema.
Provider-neutral primary scan input assembly from selected YAML agent knowledge, resolved source chunks, target metadata, and the shared Finding output schema.
Backend generic/Claude/Codex CLI primary scanner runner plumbing with shell-free invocation, structured stdin payloads, provider-specific output normalization, validated Finding JSON output, and API-key stripping for subscription-backed CLI use.
Public provider-scan package CLI and run_provider_scan MCP tool for fixture and opt-in CLI provider-neutral primary scan execution.
Optional provider-scan finalization path that accumulates returned findings and writes normal .screw/findings/ reports with mode-aware filenames and metadata.
Backend composed primary-plus-challenger workflow that runs a configured provider primary scan, finalizes findings, and attaches configured challenger review through the normal report path.
Live composed primary-plus-challenger validation in both required directions: Codex primary with Claude challenger and Claude primary with Codex challenger.
Backend parallel primary scan workflow that runs independent provider scans and returns provider-keyed findings plus agreed/disputed/unique reconciliation summaries, with optional normal report finalization.
Fixture-mode manual validation for provider-scan and run_provider_scan using a temporary /tmp end-user project.
Live Codex and Claude CLI provider-scan validation on a real MLflow MoreFixes SSTI vulnerable/patched benchmark pair.

Not yet implemented:

Additional provider-specific primary CLI adapters beyond the implemented generic, Claude, and Codex runners.
Live parallel provider scan validation through the assistant command UX.
API/local primary scanner transports for Gemini, local models, or future assistants.
API/local challenger transports in /screw:scan.
Phase 6 Move 2: next agent onboarding cycle (candidates: xpath, ssrf, deserialization, weak_crypto — see AGENT_CATALOG.md).
Phase 7 screw.nvim editor integration.
Autonomous self-improvement loop: today autoresearch is a human-driven evidence pipeline (Phase 4 deliverable). The Karpathy-inspired autonomous mutation loop described in DECISIONS.md #5 is the designed direction, not the current capability — see AGENT_LIFECYCLE.md Stage 7 for the honest characterization.

See PROJECT_STATUS.md for the current roadmap.

Repository Layout

Path	Purpose
`src/screw_agents/`	Python MCP server, scan engine, formatter, trust, learning, adaptive execution, autoresearch support
`domains/`	CWE-1400 domain folders and YAML agent definitions
`plugins/screw/`	Shared Claude Code and Codex implementation of portable assistant commands, agents, skills, plugin manifests, and local MCP config
`benchmarks/`	CWE-1400-native benchmark runner, ingest scripts, autoresearch planning/execution scripts
`docs/`	Architecture, product plan, agent authoring, catalog, decisions, benchmark and phase records
`tests/`	Core unit/integration tests
`benchmarks/tests/`	Benchmark infrastructure tests
`.mcp.json`	Project-local MCP server configuration used by Claude Code today and adaptable to other MCP-capable hosts

Quick Start

Prerequisites:

Python 3.11+
uv
Claude Code for the plugin workflow

Clone and install dependencies:

git clone https://github.com/h0pes/screw-agents.git
cd screw-agents
uv sync

Run tests:

uv run pytest

Run the MCP server over stdio:

uv run screw-agents serve --transport stdio

Run the MCP server over HTTP:

uv run screw-agents serve --transport http --port 8080

The HTTP MCP endpoint is exposed at /mcp and binds to 127.0.0.1 by default. Use --host 0.0.0.0 only when intentionally exposing the MCP server outside localhost.

Assistant Plugin Usage

During development, Claude Code can load the local plugin directory directly:

claude --plugin-dir ./plugins/screw

The repo root .mcp.json starts the MCP server with:

{
  "mcpServers": {
    "screw-agents": {
      "command": "uv",
      "args": ["run", "screw-agents", "serve", "--transport", "stdio"]
    }
  }
}

Codex can load the shared skills and MCP assets through the repo-local marketplace descriptor:

codex plugin marketplace add /path/to/screw-agents
codex mcp add screw-agents -- uv run --directory /path/to/screw-agents screw-agents serve --transport stdio

The explicit codex mcp add command remains useful during local development because it makes the MCP server registration visible with codex mcp list. Run it from a screw-agents checkout or worktree; current Codex CLI versions may fail to load configuration when registration is attempted from an arbitrary temporary project directory. After adding the marketplace, open /plugins inside Codex and enable the screw-agents plugin so Codex loads the packaged skills and MCP server config. Current Codex releases use skills, not custom prompts, for reusable workflow instructions. The plugin therefore includes Codex skills for scan, learning report, adaptive-cleanup, review, and research workflows, backed by the same MCP tools and command grammar as the slash-command files.

Run a scan from a supported assistant host:

/screw:scan sqli src/
/screw:scan injection-input-handling src/
/screw:scan agents:sqli,xss src/api/ --format markdown
/screw:scan full . --no-confirm
/screw:scan sqli src/api/ --adaptive
/screw:scan sqli src/api/ --challenger claude_primary_codex_challenger --challenger-execution dry_run

Useful plugin commands:

Command	Purpose
`/screw:scan`	Run one or more vulnerability agents against a target
`/screw:learn-report`	Summarize project false-positive learning
`/screw:adaptive-cleanup`	Inspect and clean adaptive analysis scripts

In Codex, invoke the corresponding skills with natural command text such as screw:scan sqli src/ or run a screw-agents full scan of . --no-confirm.

Claude and Codex expose different host UX primitives. Claude uses /screw:* slash commands plus Claude skills (screw-review, screw-research) and internal agents such as screw-scan. Codex uses screw:* skills from codex-skills/. The backend behavior is the same MCP/package surface; see the host surface map in the command reference for the exact naming split.

For all command forms and options, see COMMAND_REFERENCE.md.

CLI Usage

The package installs the screw-agents command:

uv run screw-agents --help

Main CLI commands:

Command	Purpose
`screw-agents serve`	Run the MCP server with stdio or HTTP transport
`screw-agents onboard-agent`	Validate a new YAML agent and run zero-touch onboarding (ingest, materialize sources, run smoke suite, print coverage report). Requires `--id <name>`.
`screw-agents challenger-dry-run`	Run a configured fixture-only Phase 5 challenger mode and print JSON
`screw-agents challenger-run`	Run a configured opt-in CLI-backed Phase 5 challenger mode and print JSON
`screw-agents provider-scan`	Run a provider-neutral primary scan through fixture or opt-in CLI execution and print JSON
`screw-agents init-trust`	Register a local reviewer key for project trust
`screw-agents migrate-exclusions`	Sign legacy false-positive exclusions
`screw-agents validate-exclusion`	Re-sign a quarantined exclusion after review
`screw-agents validate-script`	Re-sign a quarantined adaptive script after review

Example trust setup:

uv run screw-agents init-trust \
  --name "Reviewer Name" \
  --email reviewer@example.com \
  --project-root /path/to/project

How Scanning Works

At a high level:

The user selects agents and a target.
The MCP server resolves the target into code chunks.
The engine applies language relevance filtering.
Claude Code receives agent-specific prompts and source context.
Findings are accumulated into a scan session.
The server finalizes reports in .screw/findings/.
False-positive decisions can be recorded in .screw/learning/.

The MCP server does not hardcode a single UI. Claude Code is one client. The same backend is intended for the web application integration pilot, screw.nvim, CI, and future clients.

Programmatic Integration

The public integration boundary is MCP. Clients can connect through:

stdio, for Claude Code and local subprocess-style clients;
streamable HTTP, for web applications, editor integrations, workers, or CI.

The server currently exposes MCP tools rather than a bespoke REST API. The important stable surfaces are:

discovery: list_domains, list_agents;
scan assembly: scan_agents, scan_domain, get_agent_prompt;
output: accumulate_findings, finalize_scan_results, format_output;
challenger execution: challenger_dry_run, challenger_run;
learning: record_exclusion, check_exclusions, aggregate_learning;
adaptive analysis: staging, promotion, execution, cleanup, and trust tools.

For a web application, the expected integration model is a background worker or service that submits scan targets to the MCP server, stores JSON/SARIF/Markdown results, presents triage in the application, and maps approved false-positive decisions back into screw-agents learning artifacts. SynApSec (github.com/h0pes/synapsec) is the reference implementation of this pattern, shipped via Phase 5.5 — see SYNAPSEC_HANDOVER.md for the per-PR contract-preservation record.

Outputs And Project State

Scan and learning artifacts are stored under the scanned project:

Path	Purpose
`.screw/findings/`	JSON, Markdown, CSV, and SARIF scan reports; provider-primary, primary-plus-challenger, and parallel modes use mode-aware filenames, and JSON/Markdown/SARIF can include provider/challenger metadata when present
`.screw/learning/exclusions.yaml`	Signed false-positive exclusions
`.screw/config.yaml`	Project trust and adaptive-analysis configuration
`.screw/custom-scripts/`	Approved adaptive analysis scripts
`.screw/staging/`	Temporary staged findings/scripts before finalization
`.screw/local/`	Local-only adaptive prompt/decline state

Agent Knowledge

Agents live in domains/<domain>/<agent>.yaml. Twenty-one agents are implemented today, spread across seven CWE-1400 domains.

domains/injection-input-handling/ (CWE-1406):

Agent	Primary vulnerability class	Primary CWE
`sqli`	SQL injection	CWE-89
`cmdi`	OS command injection	CWE-78
`ssti`	Server-side template injection	CWE-1336
`xss`	Cross-site scripting	CWE-79
`xpath`	XPath injection	CWE-643
`ldap_injection`	LDAP injection	CWE-90
`nosql_injection`	NoSQL injection	CWE-943
`header_injection`	HTTP header injection / response splitting	CWE-113
`log_injection`	Log injection / log forging	CWE-117

domains/file-handling/:

Agent	Primary vulnerability class	Primary CWE	Benchmark status
`path_traversal`	Directory/file path traversal	CWE-22	v1.0.2 — go, java, python, javascript validated (gate-backed: `priority_thresholds`); 7 other supported languages research-only (Move 1 PR-B Wave-A + PR-C Wave-B + Wave-C precision re-validation)

domains/resource-control/:

Agent	Primary vulnerability class	Primary CWE
`deserialization`	Insecure deserialization of untrusted data	CWE-502
`unsafe_reflection`	Use of externally-controlled input to select classes or code (dynamic class/method/module loading; WHICH-not-WHAT; 11 langs incl. c/cpp; OWASP A05:2025)	CWE-470

domains/resource-lifecycle/:

Agent	Primary vulnerability class	Primary CWE
`file_upload`	Unrestricted upload of file with dangerous type (type-allowlist + content-verify + safe-storage soundness; execution-context decides severity; 9 langs no c/cpp; OWASP A06:2025)	CWE-434

domains/access-control/:

Agent	Primary vulnerability class	Primary CWE
`broken_access`	Broken access control / authorization (IDOR, missing/incorrect authz)	CWE-862
`ssrf`	Server-side request forgery	CWE-918
`auth_failures`	Broken/improper authentication (weak credential storage, missing lockout/MFA, session fixation)	CWE-287
`xxe`	XML external entity injection (parser-config safe-by-default; 11 langs incl. c/cpp; OWASP A02:2025)	CWE-611
`open_redirect`	URL redirection to untrusted site (browser-navigate cousin of ssrf; host/scheme-control + sound-allowlist; OAuth redirect_uri elevation; 8 langs; OWASP A01:2025)	CWE-601

domains/cryptography/:

Agent	Primary vulnerability class	Primary CWE
`weak_crypto`	Use of broken/risky cryptography	CWE-327
`jwt_validation`	Improper verification of a cryptographic signature (JWT/JWS: no-verify, alg:none, HS/RS confusion, kid/jku trust, missing claims)	CWE-347

domains/data-authenticity-verification/:

Agent	Primary vulnerability class	Primary CWE
`csrf`	Cross-site request forgery (missing/disabled CSRF defense on a cookie-authed state change)	CWE-352

The full planned catalog contains 18 CWE-1400 domains and 41 agents; 21 are implemented today and 20 remain planned. Future agents are added as YAML definitions plus a one-line ACTIVE_CWES registration, and run through the existing registry, scan, output, learning, benchmark, and plugin infrastructure. No new per-agent Claude subagent file is required — Move 1.5 PREP shipped the zero-touch onboarding guarantee.

See:

AGENT_LIFECYCLE.md — 8-stage end-user overview of how an agent grows from research to production
AGENT_AUTHORING.md — developer procedure, stage by stage
AGENT_ONBOARDING_RUNBOOK.md — tactical runbook for screw-agents onboard-agent
AGENT_CATALOG.md — planned CWE-1400 agent inventory
KNOWLEDGE_SOURCES.md — Phase-0.5 research sources

How Agents Are Built (8-Stage Lifecycle)

Adding a new vulnerability agent to screw-agents walks through eight stages, from initial research to multi-language validated production coverage. The first four stages are fast (hours to days); stages 5–8 are where the deep work lives.

Stage	What happens	Typical duration
1. Knowledge acquisition	Tiered research (foundations, detection prior art, bypass techniques, modern CVEs)	1–3 days
2. YAML v1.0.0 authoring	Author the agent definition at `domains/<domain>/<agent>.yaml`	0.5–1 day
3. Register the CWE	One-line append to `benchmarks/scripts/_active_cwes.py`	30 seconds
4. Onboard + smoke test	Run `screw-agents onboard-agent --id <name>` — validates, ingests upstream CVE corpora, runs the 18-assertion smoke suite, prints coverage report	1–5 minutes
5. Wave-A calibration	Three-step benchmark pipeline against real CVE cases; produces a calibration ledger	0.5–2 days
6. Refinement PR (v1.0.1)	YAML revision in a separate PR using Wave-A evidence; declares the agent's TPR-floor + FPR-ceiling gate and flips per-language `benchmark_status` from research-only to validated when the gate passes (see VALIDATION_STANDARD.md)	1–3 days per iteration
7. Ongoing benchmark cycles	Repeated human-driven evidence + reviewed refinement over months (autoresearch is evidence pipeline today; autonomous loop is the designed future state)	Months
8. Status promotion	Per-language `meta.benchmark_status` declarations: `research-only` → `synthetic` → `validated` → (transient) `regression-flagged`	Cumulative

After Stage 4 a new agent is discovered everywhere — list_agents, list_domains, the Claude and Codex plugin layers, SynApSec's web UI — without any client-specific plumbing. This is the guarantee Move 1.5 PREP exists to provide.

The thirteen accepted agents have all passed Stages 1–4. path_traversal is the first agent to complete Stage 6 — path_traversal v1.0.1 (Move 1 PR-C, 2026-05-29) flipped go/java/python/javascript to validated using Wave-A/B evidence, and v1.0.2 (2026-05-31) then closed them out under the validation standard: the Wave-C precision re-validation replaced the grandfather exemption with the project's first real gate (priority_thresholds: {tpr: 0.75, fpr: 0.20}). The pattern it established is the template for the 24 remaining agents.

For the full conceptual walkthrough see AGENT_LIFECYCLE.md; for the developer procedure see AGENT_AUTHORING.md; for the tactical Stages 3–4 runbook see AGENT_ONBOARDING_RUNBOOK.md.

Adaptive Analysis And Trust

Adaptive analysis is for cases where normal agent knowledge sees a suspicious project-specific pattern but needs a reusable local probe, such as a custom ORM, query builder, template wrapper, or command execution helper.

The adaptive path is deliberately gated:

scripts are staged first;
a reviewer inspects the exact staged bytes;
promotion signs the staged bytes, not regenerated source;
execution verifies signature, hash, trust, staleness, lint rules, and sandbox constraints;
stale staging and rejected scripts are auditable and cleanable.

This is designed to preserve the invariant:

bytes reviewed == bytes signed == bytes executed

Benchmark And Autoresearch Infrastructure

The repository includes a CWE-1400-native benchmark system under benchmarks/.

It supports:

benchmark manifest inventory;
dataset readiness checks;
controlled run planning;
no-Claude prompt-budget preflight;
controlled Claude execution with explicit budget guards;
failure payload generation for reviewed agent improvement;
Phase 4 calibration evidence for the accepted agents.

Phase 4 is complete. The key closure documents are:

Broad benchmark runs are no longer the default next step. Future benchmark execution should start from a concrete hypothesis, reviewed slices, and an explicit prompt budget.

Roadmap

Completed:

Phase 0: initial knowledge research for the first four agents.
Phase 0.5: benchmark infrastructure.
Phase 1: MCP backend.
Phase 1.7: initial benchmark pipeline validation.
Phase 2: Claude Code integration.
Phase 3a: trust, prompt infrastructure, learning aggregation.
Phase 3b: adaptive analysis and staged approval flow.
Phase 4: Rust corpus, D-02 calibration, benchmark methodology closure.
Phase 5: multi-LLM challenger system — provider-neutral primary scan contracts, composed primary+challenger workflows in both directions (Claude/Codex), parallel-provider reconciliation, fixture + subscription-backed CLI runners with API-key isolation, MCP tools challenger_dry_run / challenger_run / run_provider_scan, and the /screw:scan provider-primary flag surface. Live validations recorded for composed (both directions) and parallel modes against MLflow SSTI vulnerable/patched pair.
Phase 5.5: web application integration pilot. SynApSec (github.com/h0pes/synapsec) consumes screw-agents as an external MCP engine; all five provider modes execute through screw-agents MCP from SynApSec's backend.
Phase 6 Move 0: capability catalog contract + path_traversal pilot agent.
Phase 6 Move 1 PR-A: MoreFixes benchmark recovery procedure (BENCHMARK_MOREFIXES_RUNBOOK.md).
Phase 6 Move 1 PR-B: path_traversal Wave-A benchmark calibration (Go validated; ten other supported languages research-only).
Phase 6 Move 1.5 PREP: zero-touch agent onboarding infrastructure (PR-D1 → PR-D6, 2026-05-27 → 2026-05-28). 7 LOAD-BEARING-FIX structural blockers closed; 18/18 smoke acceptance gate fires; screw-agents onboard-agent CLI subcommand shipped.

Upcoming:

Phase 6 Move 1 PR-C: path_traversal YAML v1.0.1 refinement using Wave-A evidence (template for every future agent's Stage 6).
Phase 6 Move 2: next agent onboarding cycle (candidates: xpath, ssrf, deserialization, weak_crypto — see AGENT_CATALOG.md).
Provider-neutral adapters so Gemini, local LLMs, or future assistants can join the provider modes without changing agent YAML.
API/local primary scanner and challenger transports (transport choice per provider; API billing explicitly opt-in).
Phase 7: screw.nvim editor integration.
Cross-cutting: Phase 3c sandbox hardening, deferred backlog closure, autonomous-loop direction work (see Stage 7 in AGENT_LIFECYCLE.md for the honest characterization of current autoresearch capability).

Development

Run the full suite:

uv run pytest

Run a focused test module:

uv run pytest tests/test_registry_invariants.py -v

Run production-source linting:

uv run ruff check src/screw_agents

Repo-wide lint also traverses tests and benchmark material, including assert-heavy pytest files and intentionally vulnerable benchmark fixtures, so src/screw_agents is the production-source baseline.

uv run ruff check .

The current full-suite baseline (after Move 1.5 PREP PR-D6, squash c51d77e, 2026-05-28) is:

1408 passed, 9 skipped

Documentation Map

Conceptual & product

Document	Use
PRD.md	Product requirements, architecture rationale, phase plan
PROJECT_STATUS.md	Current project status and roadmap
ARCHITECTURE.md	System architecture and component overview
DECISIONS.md	Architecture decision records (ADRs)
AGENT_LIFECYCLE.md	End-user 8-stage overview of how an agent grows from research to production

Agent authoring & integration

Document	Use
AGENT_CATALOG.md	Planned CWE-1400 agent inventory (18 domains / 41 agents)
AGENT_AUTHORING.md	Developer procedure for authoring agents, stage by stage
AGENT_ONBOARDING_RUNBOOK.md	Tactical runbook for the `screw-agents onboard-agent` CLI
SYNAPSEC_HANDOVER.md	SynApSec consumer contract — handover entries for every contract-affecting screw-agents change
COMMAND_REFERENCE.md	CLI, assistant/plugin commands, MCP tools, benchmark commands
KNOWLEDGE_SOURCES.md	Phase-0.5 research sources for the original four agents

Phase 5 (multi-LLM challenger)

Document	Use
PHASE_5_PLAN.md	Multi-LLM challenger plan, provider/transport architecture, required modes
PHASE_5_PRIMARY_SCANNER_PLAN.md	Phase 5 plan for provider-neutral primary scanning beyond Claude Code
PHASE_5_MANUAL_VALIDATION.md	Manual round-trip validation evidence for Phase 5 provider surfaces
PHASE_5_CLOSURE_READINESS.md	Phase 5 closure decision checklist

Phase 6 (agent expansion — Move 0 / Move 1 / Move 1.5 PREP)

Document	Use
PHASE_6_MOVE_0_CATALOG_CONTRACT_PLAN.md	Move 0 plan — capability catalog contract
PHASE_6_MOVE_1_PATH_TRAVERSAL_CALIBRATION_PLAN.md	Move 1 PR-B plan — path_traversal calibration
PHASE_6_MOVE_1_CALIBRATION_LEDGER.md	Wave-A calibration ledger for path_traversal (worked example)
PHASE_6_MOVE_1_5_PREP_PLAN.md	Move 1.5 PREP plan — zero-touch onboarding (PR-D1 → PR-D6)
PHASE_6_MOVE_1_5_PREP_CLOSURE_LEDGER.md	Move 1.5 PREP closure record — pre-sweep state, sweep classification, 8/8 acceptance gates, Move 2 unblocked

Benchmark infrastructure

Document	Use
BENCHMARK_MOREFIXES_RUNBOOK.md	MoreFixes deploy / teardown / recovery procedure
BENCHMARK_REVIEWER_RUBRIC.md	Closed-enum reviewer-flag vocabulary used in Wave-A calibration

Project hygiene

Document	Use
DEFERRED_BACKLOG.md	Deferred hardening, polish, and future-phase work
CONTRIBUTING.md	Development workflow notes

Security And Privacy Notes

Scans may include source code in prompts sent to an LLM client.
The Phase 5 challenger system is explicitly opt-in and must preserve provider, cost, billing-transport, and privacy controls.
Adaptive scripts are powerful and therefore gated through review, signing, linting, sandboxing, and trust verification.
The Linux sandbox has strong namespace/capability isolation today; seccomp hardening remains tracked in DEFERRED_BACKLOG.md.

License

MIT.

Name		Name	Last commit message	Last commit date
Latest commit History 401 Commits
.agents/plugins		.agents/plugins
benchmarks		benchmarks
docs		docs
domains		domains
plugins/screw		plugins/screw
src/screw_agents		src/screw_agents
tests		tests
.gitignore		.gitignore
.mcp.json		.mcp.json
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

screw-agents

Why This Exists

Current Capabilities

Repository Layout

Quick Start

Assistant Plugin Usage

CLI Usage

How Scanning Works

Programmatic Integration

Outputs And Project State

Agent Knowledge

How Agents Are Built (8-Stage Lifecycle)

Adaptive Analysis And Trust

Benchmark And Autoresearch Infrastructure

Roadmap

Development

Documentation Map

Conceptual & product

Agent authoring & integration

Phase 5 (multi-LLM challenger)

Phase 6 (agent expansion — Move 0 / Move 1 / Move 1.5 PREP)

Benchmark infrastructure

Project hygiene

Security And Privacy Notes

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

screw-agents

Why This Exists

Current Capabilities

Repository Layout

Quick Start

Assistant Plugin Usage

CLI Usage

How Scanning Works

Programmatic Integration

Outputs And Project State

Agent Knowledge

How Agents Are Built (8-Stage Lifecycle)

Adaptive Analysis And Trust

Benchmark And Autoresearch Infrastructure

Roadmap

Development

Documentation Map

Conceptual & product

Agent authoring & integration

Phase 5 (multi-LLM challenger)

Phase 6 (agent expansion — Move 0 / Move 1 / Move 1.5 PREP)

Benchmark infrastructure

Project hygiene

Security And Privacy Notes

License

About

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages