dev-workflows/README.md

Dev Workflows

Agent workflows as SKILL.md files for frontend, backend, architecture, security review and READMEs. Every phase ends in a verification step, not a claim.

Workflows · Install · How it works · QA harness · Known limits

Ler em português

Note

Project state: five commits between 2026-08-19 (workflows, bilingual README, wf-readme) and 2026-08-24 (ten security skills vendored under skills/). Every workflow declares version: 1.0.0. The workflow bodies are written in Portuguese; this README is in English and README.pt-BR.md is the Portuguese copy.

Important

Only wf-security-review works out of the box. Its skills are vendored in skills/. The frontend, backend, architecture and README workflows load third-party skills that are not in this repository and must be installed separately (list below). The security workflow also needs network access: it must query OSV.dev, the GitHub Advisory DB and NVD, and stamp the date on the report.

Workflows

Workflow	File	Phases	Covers
Frontend / UI	wf-frontend.md	DESIGN, BUILD, REVIEW	Design direction before code, anti-AI-slop, React performance, visual QA for PDFs
Backend / API	wf-backend.md	PLAN, BUILD, SECURITY, TEST + BUG HUNT	Contract before handler, safe defaults, OWASP audit, tests and adversarial bug hunt
Architecture	wf-architecture.md	REQUIREMENTS, DESIGN, DOCS, REVIEW	Measurable requirements, C4 diagrams, ADRs, threat modeling
Security review	wf-security-review.md	SCOPE, HUNT, CONSULT, CODE REVIEW, REPORT + GATE	Front and back code review, known CVEs and a live lookup of new ones
README	wf-readme.md	SCAN, CLASSIFY, AUDIT or DRAFT, GENERATE, VERIFY + VALIDATE	Create, audit or rewrite READMEs grounded in real repo facts

Each file is a standard SKILL.md: the description in the frontmatter is the trigger, so the workflow loads when the agent's context matches it.

Why they exist: agents generate code well and admit ignorance badly. Each workflow forces the agent to prove the work at every phase:

• Verification steps: run the build, run the tests, hit the API, consult the registry.
• Acceptance criteria: checkbox gates that must be marked before a phase closes.
• Hard rules: "never merge with a red build", "never claim 'no CVE' without querying OSV.dev".
• A QA harness: a scorecard for workflow quality, plus meta-tests that corrupt the harness to prove it catches regressions.

Install

# 1. Copy the workflows into your agent's skills directory

# Hermes Agent
cp workflows/*.md ~/.hermes/skills/software-development/

# Claude Code: each skill needs its own directory (a loose .md is not loaded)
mkdir -p ~/.claude/skills
for f in workflows/*.md; do
  name=$(basename "$f" .md)
  mkdir -p "$HOME/.claude/skills/$name"
  cp "$f" "$HOME/.claude/skills/$name/SKILL.md"
done

# 2. Security review: the supporting skills are already vendored in skills/.
# Hermes:
cp -r skills/* ~/.hermes/skills/
# Claude Code: copy each skills/<name>/ directory to ~/.claude/skills/<name>/
# (the SKILL.md must sit inside its own directory, as in step 1).

# 3. Use it
# "review this PR for security"  -> wf-security-review loads
# "build a new page"             -> wf-frontend loads

The remaining skills install through npx skills (agentskills.io format), for example:

npx skills add anthropics/skills --skill frontend-design
npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices
npx skills add conorbronsdon/avoid-ai-writing
npx skills add https://github.com/pbakaus/impeccable --skill impeccable

Warning

Install layout matters. Claude Code ignores a loose .md; it needs <skill>/SKILL.md. The QA harness has the same requirement: it reads ~/.hermes/skills/software-development/<workflow>/SKILL.md, so the flat cp used for Hermes above is not enough to run it (see the harness).

How it works

The security workflow is built on one fact: a model's knowledge of CVEs stops at its training date, so "no vulnerabilities" from memory is a guess.

flowchart LR
    A["Code / diff"] --> B["1 SCOPE"]
    B --> C["2 HUNT<br/>known CVEs"]
    C --> D["3 CONSULT<br/>OSV.dev, GitHub Advisory, NVD"]
    D --> E["4 CODE REVIEW<br/>OWASP Top 10 + ASVS"]
    E --> F["5 REPORT + GATE<br/>sources and date stamped"]

A review with no source and no date is expired on arrival.

Skills the workflows load

Vendored in skills/ (security review)

Exact origin, commit and license of each copy are in skills/NOTICE.md. The copies are 1:1 with the origin; CC-BY-4.0 requires attribution, kept in that file.

Skill	What it does	Origin	License
safedeps	Queries OSV.dev live: CVE, severity and fixed version for a package@version (script check_deps.py)	Jeneidi/safedeps	MIT
sca-audit	Dependency supply-chain audit with reachability analysis and CWE mapping	OWASP/secure-agent-playbook	CC-BY-4.0
code-review-security	Systematic security code review mapped to OWASP Top 10 + ASVS	OWASP/secure-agent-playbook	CC-BY-4.0
secrets-scan	Hardcoded credentials and API keys in code and git history	OWASP/secure-agent-playbook	CC-BY-4.0
api-security-review	API review against OWASP API Security Top 10	OWASP/secure-agent-playbook	CC-BY-4.0
web-security-review	Web app review against OWASP Top 10	OWASP/secure-agent-playbook	CC-BY-4.0
cve-triage	Prioritizes CVEs with CVSS 4.0, EPSS and CISA KEV	UnitOneAI/SecuritySkills	MIT
patch-prioritization	Decides remediation order	UnitOneAI/SecuritySkills	MIT
dependency-scanning	Dependency tree scanning	UnitOneAI/SecuritySkills	MIT
hermaguard	Adversarial review: static pre-scan plus 3 specialist agents (edge cases, attack, blast radius)	Sahil-SS9/hermaguard	MIT

Not vendored (install separately)

Full inventory and install steps: docs/SKILLS.md.

Workflow	Skill	Origin
Frontend	frontend-design	anthropics/skills
Frontend	web-design	KAOPU-XiaoPu/web-design
Frontend	vercel-react-best-practices, vercel-composition-patterns	vercel-labs/agent-skills
Frontend	animate	emilkowalski/skill
Frontend	impeccable	pbakaus/impeccable
Frontend	avoid-ai-writing	conorbronsdon/avoid-ai-writing
Frontend	anti-ai-slop	local skill, not published here
Backend	secure-coding	securityreviewai/secure-coding-skill
Backend	bola-detector, auth-rbac-scaffold, injection-checker, openapi-hardener, api-security-review, security-test-generator	apisec-inc/apisec-skills
Architecture	system-design, c4-architecture, isaqb-architecture-governance, secure-architecture-governance	Kotivskyi/architecture-governance-skills
README	readme-crafter	linhai0872/readme-crafter-skill
README	good-readme	adewale/good-readme
README	curating-readme	liang-senbei/curating-readme

The QA harness

The qa/ directory keeps the workflows honest:

cd qa
python3 wf_quality_harness.py   # score each workflow on 30+ criteria
python3 test_quality.py         # gates: no regression, referenced skills exist, every phase verified
python3 test_tests.py           # meta-tests: corrupt harness/workflows, confirm the score drops

The harness scores wf-frontend, wf-backend, wf-architecture and wf-security-review (not wf-readme) by static criteria extracted from each SKILL.md: structure, numbered steps per phase, verification verbs, referenced skills that exist, and AI-isms density. The meta-tests are the useful part: they deliberately break the harness and a workflow, then confirm the score changes. If it did not, the detector would be useless.

Measured scores

Final scores per workflow come from qa/snapshots/baseline-final.json. The "before" values come from earlier harness runs; only the final snapshot is versioned.

Workflow	Before	Final	Gain
wf-frontend	201.0	385.5	+92%
wf-backend	215.0	424.0	+97%
wf-architecture	199.9	413.7	+107%
wf-security-review	332.0	390.0	+17%
Sum of the first three	615.9	1223.2	+98.6%
Sum of the four	947.9	1613.2	+70.2%

The ruler also got stricter over time (13 criteria at first, 30+ later), so the before/after comparison uses the final ruler on both sides. The numeric "2x" target was not forced: inflating the score to hit it would be gaming the metric.

Known limits

• The harness reads installed copies from ~/.hermes/skills/software-development/<name>/SKILL.md (hardcoded SKILLS_DIR), not the files in workflows/. Install in the directory layout first, or it reports SKILL.md não encontrado.
• Two different skills share the name api-security-review: the vendored OWASP one (skills/) and the apisec-inc one used by the backend workflow. Installing both into the same directory makes one overwrite the other.
• There is no root CI workflow. skills/hermaguard/.github/workflows/ci.yml belongs to the vendored hermaguard and does not run from this repository.
• The wf-readme workflow is not covered by the harness.

Contributing

Open an issue first, then a PR. The rules are the ones the workflows enforce: claims trace back to repo facts, every phase has a verification step, and docs avoid AI-isms. Run the three qa/ commands above before a PR; if you change scoring, update qa/snapshots/baseline-final.json. Details in CONTRIBUTING.md.

License

MIT, (c) 2026 Evandro Fonseca Junior. Vendored skills keep their own licenses (skills/NOTICE.md).