Devana

Devana is an agent skill for static semantic bug hunts. Use devana-bug-hunt when you want an agent to inspect source code for reachable runtime defects, not when you want a normal code review.

Devana focuses on contracts, invariants, authority boundaries, state changes, dataflow, persistence, and failure paths. It rejects style feedback, lint output, architecture opinions, missing-test comments, and generic cleanup suggestions.

Install

Install the latest release ZIP:

Download devana.zip

Or install with Skills.sh:

npx skills add bnomei/devana --skill devana-bug-hunt

Quickstart

Use this when you want the current repository inspected now.

Prerequisites

• Devana is installed in your agent host.
• You are in the repository you want to inspect.
• The agent can read the repository source files.

Run a one-shot hunt

In Codex:

Use $devana-bug-hunt on this project.

In Claude Code:

Use /devana-bug-hunt on this project.

Expected result:

reports written: 0
stop reason: no actionable findings

If Devana finds a reportable bug, it writes one or more Markdown reports under .devana/ and prints the filenames before it stops.

Every finished hunt reports the number of reports written, any report filenames, and the stop reason.

What Devana reports

Devana writes a report only when it can show all of these:

• a specific affected location
• a realistic runtime path
• a violated invariant, contract, state transition, trust boundary, or failure path expectation
• a concrete counterexample
• source-backed proof and counterevidence checked
• the strongest false-positive reason checked
• user, data, security, availability, or correctness impact
• no obvious duplicate

Devana prefers zero reports over noisy reports. It does not run tests, builds, package installs, migrations, services, or network calls during a hunt.

Report files

Reports are durable Markdown records under .devana/:

.devana/YYYYMMDDTHHMMSSZ-PN-short-slug.md

Use UTC when possible. Keep the slug lowercase ASCII, hyphen-separated, and under eight words.

Each report includes:

• DEVANA-FINDING, DEVANA-STATE, and DEVANA-KEY header lines
• the affected location, priority, confidence, and security marker
• the violated invariant or contract
• the oracle Devana used as source evidence
• a counterexample and proof shape
• counterevidence checked
• a suggested next step
• deterministic trailing DEVANA-KEY and DEVANA-SUMMARY lines

See the report template for the exact format.

Work a report

After Devana writes a report, hand that single file to your normal coding agent:

Please work this Devana report: .devana/YYYYMMDDTHHMMSSZ-PN-short-slug.md
Validate it against the current code, fix it if it is still valid, and update the report status.

The agent should read the whole report, inspect the current code, and then either fix the bug or mark the report as fixed, invalid, stale, duplicate, or wontfix.

When updating a report:

• preserve line 1 and the original finding body
• update line 2, DEVANA-STATE: ...
• update the final DEVANA-SUMMARY: status, priority, and confidence prefix
• keep both DEVANA-KEY values stable unless the same finding moved
• add dated notes under ## Status Notes
• mark fixed only after the original counterexample is blocked

Priority reference

Priority means human review urgency.

Priority	Use it for
P0	Sensitive, private, or catastrophic bugs, including reachable security, privacy, data loss, auth, tenant isolation, injection, RCE, path traversal, or secret exposure issues.
P1	Likely serious bugs, such as important workflow breakage, persisted inconsistency, high-confidence crashes, or skipped billing, publishing, sync, permission, or cleanup behavior.
P2	Plausible actionable bugs with concrete proof but uncertain impact.
P3	Minor or uncertain runtime concerns that are still actionable. Devana should not emit P3 for vague suspicion.

Trail reference

Trails are hunt lenses. Valid command arguments are empty, --all, or one or more trail slugs. Empty invocation means all trails are available, but the hunt is not exhaustive. --all means Devana must actively cover all nine trails before it stops. Unknown tokens stop the run and list the valid trails.

/devana-bug-hunt
/devana-bug-hunt inside-out-paths
/devana-bug-hunt boundaries-oracles
/devana-bug-hunt inside-out-paths dataflow-boundaries
/devana-bug-hunt --all

Trail	Use it to inspect
inside-out-paths	Core functions, handlers, reducers, parsers, state machines, jobs, and state-changing methods.
outside-in-entrypoints	Routes, CLI commands, consumers, scheduled jobs, webhooks, UI actions, public APIs, SDK methods, and plugin hooks.
invariants-contracts	Docs, schemas, tests, callers, and callees for fields, units, optionality, ordering, ownership, errors, idempotency, and returns.
boundaries-oracles	Empty, zero, one, min/max, duplicate, reordered, missing, null, expired, cancelled, retried, and just-outside values.
dataflow-boundaries	Input and state as they move through transforms to sinks, including trust labels such as tenant, owner, actor, locale, version, and permission.
state-lifecycle	Initialization, transitions, cleanup, retries, cancellation, concurrency, subscriptions, timers, workers, sessions, locks, and disposal.
contracts-errors	Adapters, implementations, request and response shapes, return values, errors, nullability, timeouts, and partial failures.
cache-persistence	Cache keys, canonicalization, tenant/user/locale/version dimensions, invalidation, transactions, stale reads, and background jobs.
security-boundaries	Auth, ownership, tenant or project scoping, paths, injection, secrets, deserialization, and unsafe policy fallbacks.

When subagents are available, Devana may send one Arrow per trail. Arrows return candidates only and must not write reports; lead Devana validates, deduplicates, prioritizes, and writes reports.

Scheduled hunts

Use an automation or loop when you want recurring background checks.

Codex automation prompt:

Use $devana-bug-hunt on this project.

Claude Code loop:

/loop Use /devana-bug-hunt on this project.

GitHub Agentic Workflows

Devana includes two reusable GitHub Agentic Workflows:

• devana-hunt installs Devana with npx skills, runs a static bug hunt, and creates one [devana] issue per new report.
• devana-work-queue validates open issues carrying the devana label and creates focused draft pull requests for confirmed bugs.

Install them into another repository with the GitHub Agentic Workflows CLI:

gh aw add-wizard bnomei/devana/devana-hunt
gh aw add-wizard bnomei/devana/devana-work-queue

The installer places the Markdown sources under .github/workflows/. From the root of the consuming repository, compile them before committing or running the workflows:

gh aw compile

GitHub executes the generated .lock.yml files, not the Markdown sources directly. Run gh aw compile again after every workflow edit, Devana workflow upgrade, or gh-aw upgrade, then commit the Markdown sources and generated files together. The workflows use GitHub Copilot by default, so configure Copilot authentication as prompted by add-wizard.

Before the first run:

1. Open the generated Agentic Maintenance workflow, choose Run workflow, and select the create_labels operation. The hunt cannot create issues until the configured devana label exists.
2. To let the work queue open pull requests directly, go to Settings → Actions → General and enable Allow GitHub Actions to create and approve pull requests. Otherwise create-pull-request preserves the fix branch but falls back to an issue with a compare link.
3. Review the installed work queue's tools.bash setting. The reusable blueprint uses ":*" so it can validate projects with unknown toolchains; with the default Copilot engine this permits all tools. Narrow it to the consuming repository's formatter, test, build, and read-only Git commands when possible.

To validate the reusable workflow sources in this repository, install the gh-aw extension and run:

gh aw validate --dir workflows

Validation compiles without emitting lock files and runs actionlint, zizmor, and poutine. To compile and run only Actionlint explicitly, use gh aw compile --dir workflows --no-emit --actionlint.

Source files

• Skill definition
• Report template
• Trail playbook
• OpenAI agent metadata

License

MIT