evandro/dev-workflows
1
0 Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(readme): redesenha o README com hero em SVG [skip ci]

Browse Source
This commit is contained in:
evandro committed 2026-10-24 04:58:02 -03:00
1 parent 3891915df3
commit c1e887b35c
3 files changed
+280 -342
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+104 -147
View File
@@ -1,56 +1,106 @@
<div align="center">
# Dev Workflows
<img src="assets/readme/hero.svg" width="100%" alt="dev-workflows: agent workflows where every phase ends in a verification step, shown as the wf-security-review SKILL.md checklist from SCOPE to REPORT + GATE">
**Agent workflows as `SKILL.md` files for frontend, backend, architecture, security review and READMEs.
Every phase ends in a verification step, not a claim.**
![Format SKILL.md](https://img.shields.io/badge/format-SKILL.md-informational?style=flat-square)
![Workflows 5, v1.0.0](https://img.shields.io/badge/workflows-5%20%C2%B7%20v1.0.0-informational?style=flat-square)
![QA harness Python 3](https://img.shields.io/badge/QA%20harness-Python%203-3776AB?style=flat-square&logo=python&logoColor=white)
![License MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)
![License](https://img.shields.io/badge/license-MIT-blue)
![Workflows](https://img.shields.io/badge/workflows-5-informational)
![Vendored skills](https://img.shields.io/badge/vendored%20skills-10-informational)
[Issues](https://git.evandro.dev.br/evandro/dev-workflows/issues) · [Skills inventory](docs/SKILLS.md) · [Vendored skills notice](skills/NOTICE.md) · [Contributing](CONTRIBUTING.md)
[Workflows](#workflows) · [Install](#install) · [How it works](#how-it-works) · [QA harness](#the-qa-harness) · [Known limits](#known-limits)
**[Ler em português](README.pt-BR.md)**
**English** · [Português (BR)](README.pt-BR.md)
</div>
> [!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](README.pt-BR.md) is the Portuguese copy.
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):
> [!IMPORTANT]
> **Only `wf-security-review` works out of the box.** Its skills are vendored in
> [`skills/`](skills/NOTICE.md). The frontend, backend, architecture and README
> workflows load third-party skills that are **not** in this repository and must be
> installed separately ([list below](#skills-the-workflows-load)). 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.
```console
$ 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=[]
## Workflows
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`](workflows/wf-frontend.md) | DESIGN, BUILD, REVIEW | Design direction before code, anti-AI-slop, React performance, visual QA for PDFs |
| **Backend / API** | [`wf-backend.md`](workflows/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`](workflows/wf-architecture.md) | REQUIREMENTS, DESIGN, DOCS, REVIEW | Measurable requirements, C4 diagrams, ADRs, threat modeling |
| **Security review** | [`wf-security-review.md`](workflows/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`](workflows/wf-readme.md) | SCAN, CLASSIFY, AUDIT or DRAFT, GENERATE, VERIFY + VALIDATE | Create, audit or rewrite READMEs grounded in real repo facts |
| Frontend / UI | [`wf-frontend.md`](workflows/wf-frontend.md) | DESIGN, BUILD, REVIEW | Design direction before code, anti-AI-slop, React performance, visual QA for PDFs |
| Backend / API | [`wf-backend.md`](workflows/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`](workflows/wf-architecture.md) | REQUIREMENTS, DESIGN, DOCS, REVIEW | Measurable requirements, C4 diagrams, ADRs, threat modeling |
| Security review | [`wf-security-review.md`](workflows/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`](workflows/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.
The repository also vendors ten security skills under [`skills/`](skills/NOTICE.md) and ships a QA harness under [`qa/`](qa).
Why they exist: agents generate code well and admit ignorance badly. Each workflow
forces the agent to prove the work at every phase:
## 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".
- **A QA harness:** a scorecard for workflow quality, plus meta-tests that corrupt the harness to prove it catches regressions.
## Install
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.
<details>
<summary>Skills the workflows load</summary>
Vendored in `skills/` (security review). Origin, commit and license of each copy are in [`skills/NOTICE.md`](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](https://github.com/Jeneidi/safedeps) | MIT |
| `sca-audit` | Dependency supply-chain audit with reachability analysis and CWE mapping | [OWASP/secure-agent-playbook](https://github.com/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](https://github.com/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](https://github.com/Sahil-SS9/hermaguard) | MIT |
Not vendored (install separately; full inventory in [`docs/SKILLS.md`](docs/SKILLS.md)):
| Workflow | Skill | Origin |
|---|---|---|
| Frontend | `frontend-design` | [anthropics/skills](https://github.com/anthropics/skills) |
| Frontend | `web-design` | [KAOPU-XiaoPu/web-design](https://github.com/KAOPU-XiaoPu/web-design) |
| Frontend | `vercel-react-best-practices`, `vercel-composition-patterns` | [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) |
| Frontend | `animate` | [emilkowalski/skill](https://github.com/emilkowalski/skill) |
| Frontend | `impeccable` | [pbakaus/impeccable](https://github.com/pbakaus/impeccable) |
| Frontend | `avoid-ai-writing` | [conorbronsdon/avoid-ai-writing](https://github.com/conorbronsdon/avoid-ai-writing) |
| Frontend | `anti-ai-slop` | local skill, not published here |
| Backend | `secure-coding` | [securityreviewai/secure-coding-skill](https://github.com/securityreviewai/secure-coding-skill) |
| Backend | `bola-detector`, `auth-rbac-scaffold`, `injection-checker`, `openapi-hardener`, `api-security-review`, `security-test-generator` | [apisec-inc/apisec-skills](https://github.com/apisec-inc/apisec-skills) |
| Architecture | `system-design`, `c4-architecture`, `isaqb-architecture-governance`, `secure-architecture-governance` | [Kotivskyi/architecture-governance-skills](https://github.com/Kotivskyi/architecture-governance-skills) |
| README | `readme-crafter` | [linhai0872/readme-crafter-skill](https://github.com/linhai0872/readme-crafter-skill) |
| README | `good-readme` | [adewale/good-readme](https://github.com/adewale/good-readme) |
| README | `curating-readme` | [liang-senbei/curating-readme](https://github.com/liang-senbei/curating-readme) |
| Security review | `dependency-cve-audit`, `security-threat-model` | local skills, not published here |
</details>
## Quickstart
```bash
# 1. Copy the workflows into your agent's skills directory
@@ -87,76 +137,9 @@ 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](#the-qa-harness)).
> 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.
## 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.
```mermaid
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
<details>
<summary>Vendored in <code>skills/</code> (security review)</summary>
Exact origin, commit and license of each copy are in [`skills/NOTICE.md`](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](https://github.com/Jeneidi/safedeps) | MIT |
| `sca-audit` | Dependency supply-chain audit with reachability analysis and CWE mapping | [OWASP/secure-agent-playbook](https://github.com/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](https://github.com/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](https://github.com/Sahil-SS9/hermaguard) | MIT |
</details>
<details>
<summary>Not vendored (install separately)</summary>
Full inventory and install steps: [`docs/SKILLS.md`](docs/SKILLS.md).
| Workflow | Skill | Origin |
|---|---|---|
| Frontend | `frontend-design` | [anthropics/skills](https://github.com/anthropics/skills) |
| Frontend | `web-design` | [KAOPU-XiaoPu/web-design](https://github.com/KAOPU-XiaoPu/web-design) |
| Frontend | `vercel-react-best-practices`, `vercel-composition-patterns` | [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) |
| Frontend | `animate` | [emilkowalski/skill](https://github.com/emilkowalski/skill) |
| Frontend | `impeccable` | [pbakaus/impeccable](https://github.com/pbakaus/impeccable) |
| Frontend | `avoid-ai-writing` | [conorbronsdon/avoid-ai-writing](https://github.com/conorbronsdon/avoid-ai-writing) |
| Frontend | `anti-ai-slop` | local skill, not published here |
| Backend | `secure-coding` | [securityreviewai/secure-coding-skill](https://github.com/securityreviewai/secure-coding-skill) |
| Backend | `bola-detector`, `auth-rbac-scaffold`, `injection-checker`, `openapi-hardener`, `api-security-review`, `security-test-generator` | [apisec-inc/apisec-skills](https://github.com/apisec-inc/apisec-skills) |
| Architecture | `system-design`, `c4-architecture`, `isaqb-architecture-governance`, `secure-architecture-governance` | [Kotivskyi/architecture-governance-skills](https://github.com/Kotivskyi/architecture-governance-skills) |
| README | `readme-crafter` | [linhai0872/readme-crafter-skill](https://github.com/linhai0872/readme-crafter-skill) |
| README | `good-readme` | [adewale/good-readme](https://github.com/adewale/good-readme) |
| README | `curating-readme` | [liang-senbei/curating-readme](https://github.com/liang-senbei/curating-readme) |
</details>
## The QA harness
The [`qa/`](qa) directory keeps the workflows honest:
## Usage
```bash
cd qa
@@ -165,55 +148,29 @@ python3 test_quality.py # gates: no regression, referenced skills exist,
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.
Final scores per workflow are versioned in [`qa/snapshots/baseline-final.json`](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.
<details>
<summary>Measured scores</summary>
## Project status
Final scores per workflow come from [`qa/snapshots/baseline-final.json`](qa/snapshots/baseline-final.json).
The "before" values come from earlier harness runs; only the final snapshot is
versioned.
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.
| 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 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.
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.
</details>
## 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`](CONTRIBUTING.md).
Contribution rules are in [`CONTRIBUTING.md`](CONTRIBUTING.md): claims trace back to repo facts, every phase has a verification step, and docs avoid AI-isms.
## License
[MIT](LICENSE), (c) 2026 Evandro Fonseca Junior. Vendored skills keep their own
licenses ([`skills/NOTICE.md`](skills/NOTICE.md)).
[MIT](LICENSE), (c) 2026 Evandro Fonseca Junior. Vendored skills keep their own licenses ([`skills/NOTICE.md`](skills/NOTICE.md)).
---
<div align="center">
<sub>Made by <a href="https://evandro.dev.br">Evandro Fonseca Junior</a> · <a href="https://git.evandro.dev.br/evandro">git.evandro.dev.br</a></sub>
</div>