evandro/dev-workflows
1
0 Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
dev-workflows/README.md
T

12 KiB
Raw Permalink Blame History

Harness output after installing the workflows and the vendored skills in the Hermes layout (real run; impeccable is a third-party skill that was not installed, so the harness exits 1):

$ cd qa && python wf_quality_harness.py
wf-frontend        score= 385.5  refs=18 sem_match=['impeccable'] fases_sem_verif=[]
wf-backend         score= 424.0  refs=15 sem_match=[] fases_sem_verif=[]
wf-architecture    score= 413.7  refs=11 sem_match=[] fases_sem_verif=[]
wf-security-review score= 390.0  refs=14 sem_match=[] fases_sem_verif=[]

TOTAL: 1613.2 / 400.0  (403.3%)

What it is

Five agent workflows written as standard SKILL.md files. The description in each frontmatter is the trigger, so the workflow loads when the agent's context matches it. The workflow bodies are in Portuguese.

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

The repository also vendors ten security skills under skills/ and ships a QA harness under qa/.

Why use it

Agents generate code well and admit ignorance badly. Each workflow makes the agent 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".

Do not use it if you want self-contained skills. The frontend, backend, architecture and README workflows load third-party skills that are not in this repository, the security workflow also expects two local skills that are not vendored, and the QA harness only reads the Hermes Agent layout.

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.

  1. SCOPE defines the target before auditing.
  2. HUNT checks known CVEs in the dependencies (safedeps queries OSV.dev for a package@version).
  3. CONSULT looks up new vulnerabilities in live sources: OSV.dev, GitHub Advisory DB and NVD.
  4. CODE REVIEW reviews front and back code against OWASP Top 10 and ASVS.
  5. REPORT + GATE delivers the report with sources and date stamped, then decides.

The QA harness scores wf-frontend, wf-backend, wf-architecture and wf-security-review (not wf-readme) on 30+ static criteria extracted from each SKILL.md: structure, numbered steps per phase, verification verbs, referenced skills and AI-isms density. test_tests.py holds meta-tests that break the harness on purpose and check that the score changes.

Skills the workflows load

Vendored in skills/ (security review). Origin, commit and license of each copy are in skills/NOTICE.md; 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 in 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
Security review dependency-cve-audit, security-threat-model local skills, not published here

Quickstart

# 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.

Usage

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

Final scores per workflow are versioned in qa/snapshots/baseline-final.json: wf-frontend 385.5, wf-backend 424.0, wf-architecture 413.7, wf-security-review 390.0, total 1613.2. The run above reproduces them.

Project status

Six commits between 2026-08-19 and 2026-10-13; every workflow declares version: 1.0.0. No root CI: skills/hermaguard/.github/workflows/ci.yml belongs to the vendored hermaguard and does not run from this repository.

  • The harness reads installed copies from ~/.hermes/skills/software-development/<name>/SKILL.md (hardcoded SKILLS_DIR), not the files in workflows/. Without them it reports SKILL.md não encontrado.
  • The harness exits 1 when a referenced skill is missing, and test_quality.py then stops with HARNESS FALHOU. Even with every skill installed, gate G3 asks each workflow to reach twice its own final baseline, so test_quality.py cannot pass against the current snapshot.
  • test_tests.py mutates wf-frontend/SKILL.md at the repository root, which does not exist, so that meta-test does nothing; the anti-slop mutation still runs.
  • The "referenced skills exist" check also accepts names from a hardcoded list without checking the disk.
  • wf-security-review mentions dependency-cve-audit and security-threat-model as local skills that are not vendored, and calls ~/.hermes/skills/safedeps/check_deps.py, so it assumes the Hermes layout.
  • Two different skills share the name api-security-review: the vendored OWASP one and the apisec-inc one used by the backend workflow. Installing both into the same directory makes one overwrite the other.
  • In docs/SKILLS.md, the Claude Code snippet quotes the tilde ("~/.claude/skills/$nome"), which creates a literal ~ directory; use $HOME as in the Quickstart above.
  • wf-readme is not covered by the harness.

Contribution rules are in CONTRIBUTING.md: claims trace back to repo facts, every phase has a verification step, and docs avoid AI-isms.

License

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

Reference in new issue View Git Blame Copy Permalink