docs: rewrite README with bilingual polished version
Two versions (EN primary, PT-BR). Hero with badges, TOC, per-skill explanations with links to each skill's owner, security rationale, quick start, QA harness section and repo layout. Removed AI-isms and em-dashes flagged by avoid-ai-writing checks.
This commit is contained in:
Evandro Fonseca Junior committed
1 parent
722c544b72
commit
66d6f61e0c
2 files changed
+360
-59
No files matched your search
@@ -1,79 +1,190 @@
|
||||
# dev-workflows
|
||||
<div align="center">
|
||||
|
||||
Workflows de desenvolvimento que uso no dia a dia, codificados como skills
|
||||
de agente (formato SKILL.md). Cada um define um processo com fases, passos
|
||||
de verificação, comandos reais e regras duras - daí sai trabalho consistente
|
||||
em vez de "confia em mim".
|
||||
# Dev Workflows
|
||||
|
||||
Em geral mexo com Node/TypeScript, NestJS, PostgreSQL, Docker e front em
|
||||
React. Os workflows refletem isso, mas as fases são neutras o suficiente
|
||||
pra servir em outros stacks.
|
||||
**Agent workflows as SKILL.md files**: frontend, backend, architecture and security code review that never skip verification.
|
||||
|
||||
## O que tem aqui
|
||||
[](LICENSE)
|
||||
[](qa/wf_quality_harness.py)
|
||||
[](https://agentskills.io)
|
||||
[](https://github.com/evandrodevbr/dev-workflows/pulls)
|
||||
|
||||
| Workflow | Para quê |
|
||||
|---|---|
|
||||
| [wf-frontend](workflows/wf-frontend.md) | UI/design/PDF: direção visual antes de codar, anti-AI-slop, perf React, QA visual |
|
||||
| [wf-backend](workflows/wf-backend.md) | API/backend: contrato antes do handler, defaults seguros, auditoria OWASP, testes |
|
||||
| [wf-architecture](workflows/wf-architecture.md) | Arquitetura: requisitos mensuráveis, C4, ADR, threat model, revisão |
|
||||
| [wf-security-review](workflows/wf-security-review.md) | Code review de segurança front+back: CVE conhecidas + consulta de novas (OSV/NVD/GH Advisory) |
|
||||
Turn your coding agent into a repeatable, verifiable process. Each workflow defines phases, concrete verification steps, real commands, and hard rules. The agent delivers work that can be *checked*, not just *claimed*.
|
||||
|
||||
Cada SKILL.md funciona no Hermes Agent (e em qualquer agente que leia o
|
||||
formato): a descrição no frontmatter é o gatilho - quando o contexto bate,
|
||||
o fluxo carrega sozinho.
|
||||
**🇧🇷 [Ler em português](README.pt-BR.md)**
|
||||
|
||||
## Por que fases com verificação
|
||||
</div>
|
||||
|
||||
O problema que isso resolve: agente "acha que fez" mas não tem como provar.
|
||||
Cada fase termina com passos de verificação (rodar build, rodar teste,
|
||||
consultar OSV.dev) e os workflows têm critérios de aceite. Sem evidência,
|
||||
não entrega.
|
||||
---
|
||||
|
||||
Tem um harness de qualidade no `qa/` que mede isso de forma objetiva:
|
||||
## Why
|
||||
|
||||
Agents are great at generating code and terrible at admitting they don't know. This project fixes the second part.
|
||||
|
||||
Every workflow here forces the agent to **prove** the work at each phase:
|
||||
|
||||
- **Verification steps**: run the build, run the tests, hit the API, consult the registry. Not "I think it works".
|
||||
- **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 that measures workflow quality objectively, plus meta-tests that corrupt the harness to prove it detects regressions.
|
||||
|
||||
## Table of contents
|
||||
|
||||
- [Workflows](#workflows)
|
||||
- [Security: do not trust the training cutoff](#security-do-not-trust-the-training-cutoff)
|
||||
- [Skills used, and their owners](#skills-used-and-their-owners)
|
||||
- [Quick start](#quick-start)
|
||||
- [The QA harness](#the-qa-harness)
|
||||
- [Repository layout](#repository-layout)
|
||||
- [License](#license)
|
||||
|
||||
## Workflows
|
||||
|
||||
| Workflow | File | Covers |
|
||||
|---|---|---|
|
||||
| 🎨 **Frontend / UI** | [workflows/wf-frontend.md](workflows/wf-frontend.md) | Design direction before code, anti-AI-slop, React performance, visual QA for PDFs |
|
||||
| ⚙️ **Backend / API** | [workflows/wf-backend.md](workflows/wf-backend.md) | Contract before handler, safe defaults, OWASP audit, tests + adversarial bug hunt |
|
||||
| 🏗️ **Architecture** | [workflows/wf-architecture.md](workflows/wf-architecture.md) | Measurable requirements, C4 diagrams, ADRs, threat modeling, review |
|
||||
| 🛡️ **Security review** | [workflows/wf-security-review.md](workflows/wf-security-review.md) | Code review (front + back), known CVEs **and** live lookup of new ones |
|
||||
|
||||
Each file is a standard `SKILL.md`. The `description` in the frontmatter is the trigger: when the agent's context matches it, the workflow loads automatically. Works in [Hermes Agent](https://hermes-agent.nousresearch.com), Claude Code, and anything that reads the Agent Skills format.
|
||||
|
||||
## Security: do not trust the training cutoff
|
||||
|
||||
A model's knowledge of CVEs stops at its training date. Anything disclosed after that, it has never seen, so "no vulnerabilities" from memory is a guess, not an answer.
|
||||
|
||||
The security workflow is built around that fact:
|
||||
|
||||
```
|
||||
Code/diff → SCOPE → HUNT (known CVEs) → CONSULT (live sources) → CODE REVIEW → REPORT + GATE
|
||||
│ │
|
||||
│ └─ OSV.dev · GitHub Advisory DB · NVD
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
Every security review **must** consult live sources and stamp the date. A review with no source and no date is expired on arrival.
|
||||
|
||||
## Skills used, and their owners
|
||||
|
||||
Workflows load these skills by context. The three pillars of the security review come from primary security sources (OWASP, OSV.dev, UnitOne SecuritySkills), not from a model's memory.
|
||||
|
||||
### 🛡️ Security review: the three pillars
|
||||
|
||||
| Skill | What it does | Owner |
|
||||
|---|---|---|
|
||||
| [`safedeps`](https://github.com/Jeneidi/safedeps) | Queries OSV.dev in real time; returns CVE + severity + fixed version for a `package@version`. Covers the gap a frozen model can't. | [Jeneidi](https://github.com/Jeneidi) |
|
||||
| [`sca-audit`](https://github.com/OWASP/secure-agent-playbook) | Supply-chain audit of dependencies with reachability analysis and CWE mapping. | [OWASP](https://github.com/OWASP) |
|
||||
| [`code-review-security`](https://github.com/OWASP/secure-agent-playbook) | Systematic security code review mapped to OWASP Top 10 + ASVS. | [OWASP](https://github.com/OWASP) |
|
||||
|
||||
### 🛡️ Security review: supporting skills
|
||||
|
||||
| Skill | What it does | Owner |
|
||||
|---|---|---|
|
||||
| [`secrets-scan`](https://github.com/OWASP/secure-agent-playbook) | Finds hardcoded credentials / API keys in code and git history. | [OWASP](https://github.com/OWASP) |
|
||||
| [`api-security-review`](https://github.com/OWASP/secure-agent-playbook) | API review against OWASP API Security Top 10. | [OWASP](https://github.com/OWASP) |
|
||||
| [`web-security-review`](https://github.com/OWASP/secure-agent-playbook) | Web app review against OWASP Top 10. | [OWASP](https://github.com/OWASP) |
|
||||
| [`cve-triage`](https://github.com/UnitOneAI/SecuritySkills) | Prioritizes CVEs using CVSS 4.0 / EPSS / CISA KEV. | [UnitOneAI](https://github.com/UnitOneAI) |
|
||||
| [`patch-prioritization`](https://github.com/UnitOneAI/SecuritySkills) | Decides remediation order. | [UnitOneAI](https://github.com/UnitOneAI) |
|
||||
| [`dependency-scanning`](https://github.com/UnitOneAI/SecuritySkills) | Dependency tree scanning. | [UnitOneAI](https://github.com/UnitOneAI) |
|
||||
| [`hermaguard`](https://github.com/Sahil-SS9/hermaguard) | Adversarial review: static pre-scan + 3 specialist agents (edge cases, attack, blast radius). | [Sahil-SS9](https://github.com/Sahil-SS9) |
|
||||
|
||||
### 🎨 Frontend / UI
|
||||
|
||||
| Skill | What it does | Owner |
|
||||
|---|---|---|
|
||||
| [`frontend-design`](https://github.com/anthropics/skills) | Intentional visual direction, typography, avoiding "generic AI" output. | [Anthropic](https://github.com/anthropics) |
|
||||
| [`web-design`](https://github.com/KAOPU-XiaoPu/web-design) | Cohesive web aesthetics. | [KAOPU-XiaoPu](https://github.com/KAOPU-XiaoPu) |
|
||||
| [`vercel-react-best-practices`](https://github.com/vercel-labs/agent-skills) | 40+ React/Next performance rules from Vercel engineering. | [Vercel Labs](https://github.com/vercel-labs) |
|
||||
| [`vercel-composition-patterns`](https://github.com/vercel-labs/agent-skills) | Compound components, clean composition. | [Vercel Labs](https://github.com/vercel-labs) |
|
||||
| [`animate`](https://github.com/emilkowalski/skill) | Purpose-driven motion. | [emilkowalski](https://github.com/emilkowalski) |
|
||||
| [`anti-ai-slop`](https://github.com/evandrodevbr/dev-workflows) | Detects "generated-by-AI" visual patterns (auto-loaded, local). | community skill |
|
||||
| [`avoid-ai-writing`](https://github.com/conorbronsdon/avoid-ai-writing) | Removes AI-isms from microcopy, labels and docs. | [conorbronsdon](https://github.com/conorbronsdon) |
|
||||
|
||||
### ⚙️ Backend / API
|
||||
|
||||
| Skill | What it does | Owner |
|
||||
|---|---|---|
|
||||
| [`secure-coding`](https://github.com/securityreviewai/secure-coding-skill) | Secure coding patterns covering 15 stacks. | [securityreviewai](https://github.com/securityreviewai) |
|
||||
| [`bola-detector`](https://github.com/apisec-inc/apisec-skills) | Broken object-level authorization (OWASP API1). | [apisec-inc](https://github.com/apisec-inc) |
|
||||
| [`auth-rbac-scaffold`](https://github.com/apisec-inc/apisec-skills) | Authentication + RBAC (OWASP API2 / API5). | [apisec-inc](https://github.com/apisec-inc) |
|
||||
| [`injection-checker`](https://github.com/apisec-inc/apisec-skills) | SQL / ORM / shell / template injection (OWASP API8). | [apisec-inc](https://github.com/apisec-inc) |
|
||||
| [`openapi-hardener`](https://github.com/apisec-inc/apisec-skills) | Sanitizes OpenAPI / Zod / Pydantic schemas (OWASP API3). | [apisec-inc](https://github.com/apisec-inc) |
|
||||
| [`api-security-review`](https://github.com/apisec-inc/apisec-skills) | Full OWASP API Top 10 review. | [apisec-inc](https://github.com/apisec-inc) |
|
||||
| [`security-test-generator`](https://github.com/apisec-inc/apisec-skills) | Generates security test suites. | [apisec-inc](https://github.com/apisec-inc) |
|
||||
|
||||
### 🏗️ Architecture
|
||||
|
||||
| Skill | What it does | Owner |
|
||||
|---|---|---|
|
||||
| [`system-design`](https://github.com/Kotivskyi/architecture-governance-skills) | HelloInterview system-design framework. | [Kotivskyi](https://github.com/Kotivskyi) |
|
||||
| [`c4-architecture`](https://github.com/Kotivskyi/architecture-governance-skills) | C4 diagrams (Mermaid / Structurizr). | [Kotivskyi](https://github.com/Kotivskyi) |
|
||||
| [`isaqb-architecture-governance`](https://github.com/Kotivskyi/architecture-governance-skills) | arc42 + ADRs. | [Kotivskyi](https://github.com/Kotivskyi) |
|
||||
| [`secure-architecture-governance`](https://github.com/Kotivskyi/architecture-governance-skills) | STRIDE+CIA threat models, security ADRs. | [Kotivskyi](https://github.com/Kotivskyi) |
|
||||
|
||||
> 📖 Full install instructions for every skill live in [docs/SKILLS.md](docs/SKILLS.md).
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
# 1. Copy workflows into your agent's skills directory
|
||||
# Hermes Agent:
|
||||
cp workflows/*.md ~/.hermes/skills/software-development/
|
||||
|
||||
# Claude Code / any skills-dir agent:
|
||||
mkdir -p ~/.claude/skills && cp workflows/*.md ~/.claude/skills/
|
||||
|
||||
# 2. (Optional, for security review) install safedeps + the OSV checker
|
||||
git clone --depth 1 https://github.com/Jeneidi/safedeps.git
|
||||
cp -r safedeps/skills/safedeps ~/.hermes/skills/safedeps
|
||||
cp safedeps/check_deps.py ~/.hermes/skills/safedeps/
|
||||
|
||||
# 3. Use it
|
||||
# "review this PR for security" -> wf-security-review loads
|
||||
# "build a new page" -> wf-frontend loads
|
||||
```
|
||||
|
||||
## The QA harness
|
||||
|
||||
The `qa/` directory keeps the workflows themselves honest:
|
||||
|
||||
```bash
|
||||
cd qa
|
||||
python3 wf_quality_harness.py # score por workflow (30+ critérios)
|
||||
python3 test_quality.py # gates: não-regressão, skills válidas, verificação por fase
|
||||
python3 test_tests.py # teste dos testes: muta e confirma que o harness detecta
|
||||
|
||||
python3 wf_quality_harness.py # score each workflow on 30+ criteria
|
||||
python3 test_quality.py # gates: no regression, valid skills, phases verified
|
||||
python3 test_tests.py # meta-tests: corrupt the harness, prove it detects the corruption
|
||||
```
|
||||
|
||||
O `test_tests.py` é o diferencial: ele corrompe o harness e os workflows de
|
||||
propósito e confirma que o score cai. Se o score não muda com a corrupção,
|
||||
o detetor é inútil. Isso está sempre verde.
|
||||
The meta-tests are the interesting part. They deliberately break the harness and the workflows, then confirm the score *drops*. If the score didn't move, the detector would be useless. These tests stay green as a contract.
|
||||
|
||||
## Segurança: não confiar no cutoff
|
||||
## Repository layout
|
||||
|
||||
A skill de segurança tem uma regra dura: o modelo conhece CVE só até o
|
||||
cutoff de treino. Então "não tem vulnerabilidade" nunca é resposta de
|
||||
memória - o workflow consulta fontes vivas:
|
||||
|
||||
- OSV.dev via safedeps (CVE em tempo real por `package@version`)
|
||||
- GitHub Advisory Database (via gh api)
|
||||
- NVD
|
||||
|
||||
Leva 3 skills de segurança de fontes primárias (OWASP, OSV.dev, UnitOne
|
||||
SecuritySkills) e as usa como pilares do review.
|
||||
|
||||
## Instalação
|
||||
|
||||
Copie os arquivos de `workflows/` para o diretório de skills do seu agente:
|
||||
|
||||
```bash
|
||||
# Hermes Agent
|
||||
cp workflows/*.md ~/.hermes/skills/software-development/
|
||||
|
||||
# Claude Code / agentes com skills dir
|
||||
mkdir -p ~/.claude/skills && cp workflows/*.md ~/.claude/skills/
|
||||
```
|
||||
dev-workflows/
|
||||
├── README.md # this file
|
||||
├── README.pt-BR.md # Portuguese version
|
||||
├── workflows/ # the four SKILL.md workflows
|
||||
│ ├── wf-frontend.md
|
||||
│ ├── wf-backend.md
|
||||
│ ├── wf-architecture.md
|
||||
│ └── wf-security-review.md
|
||||
├── docs/
|
||||
│ └── SKILLS.md # full skill inventory + install steps
|
||||
└── qa/ # quality harness, gates, meta-tests
|
||||
├── wf_quality_harness.py
|
||||
├── test_quality.py
|
||||
├── test_tests.py
|
||||
└── snapshots/
|
||||
```
|
||||
|
||||
Para o `wf-security-review`, instale também a skill safedeps e o script
|
||||
`check_deps.py` (veja `docs/SKILLS.md`) - é o que consulta o OSV.dev.
|
||||
## License
|
||||
|
||||
## Docs
|
||||
[MIT](LICENSE) © 2026 [Evandro Fonseca Junior](https://github.com/evandrodevbr)
|
||||
|
||||
- [docs/SKILLS.md](docs/SKILLS.md) - lista completa das skills usadas,
|
||||
origem de cada uma e como instalá-las
|
||||
- [qa/](qa/) - harness de qualidade + gates + teste dos testes
|
||||
---
|
||||
|
||||
Licença: MIT.
|
||||
<div align="center">
|
||||
|
||||
⭐ If this saves you from one "works on my machine" merge, star it.
|
||||
|
||||
</div>
|
||||
Reference in new issue
Block a user