From 3891915df356a7e2cdbe7e801b15604dd1b97326 Mon Sep 17 00:00:00 2001 From: Evandro Fonseca Junior Date: Tue, 13 Oct 2026 21:47:18 -0300 Subject: [PATCH] =?UTF-8?q?docs:=20redesign=20do=20README=20(padr=C3=A3o?= =?UTF-8?q?=20TwitterBR-MOD)=20=E2=80=94=20dados=20atualizados?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 353 +++++++++++++++++++++++++----------------------------- 1 file changed, 163 insertions(+), 190 deletions(-) diff --git a/README.md b/README.md index f8e162e..69a3157 100644 --- a/README.md +++ b/README.md @@ -2,142 +2,63 @@ # Dev Workflows -**Agent workflows as SKILL.md files**: frontend, backend, architecture and security code review that never skip verification. +**Agent workflows as `SKILL.md` files for frontend, backend, architecture, security review and READMEs. +Every phase ends in a verification step, not a claim.** -[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) -[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white)](qa/wf_quality_harness.py) -[![Agent Skills](https://img.shields.io/badge/Agent%20Skills-1.0-8A2BE2)](https://agentskills.io) -[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/evandrodevbr/dev-workflows/pulls) +![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) -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*. +[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)** +**[Ler em portuguΓͺs](README.pt-BR.md)** ---- +> [!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. -## 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) -- [Quality tests and measured gains](#quality-tests-and-measured-gains) -- [Repository layout](#repository-layout) -- [License](#license) +> [!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. ## 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 | -| πŸ“„ **README** | [workflows/wf-readme.md](workflows/wf-readme.md) | Create/audit/rewrite READMEs grounded in real repo facts | +| 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 | -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. +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. -## Security: do not trust the training cutoff +Why they exist: agents generate code well and admit ignorance badly. Each workflow +forces the agent to prove the work at every phase: -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. +- **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. -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 - -_Vendored under `skills/` β€” see [`skills/NOTICE.md`](skills/NOTICE.md) for exact origin and license._ - -| 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 - -_Also vendored under `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) | -| [`impeccable`](https://github.com/pbakaus/impeccable) | The missing design vocabulary for agents: 23 commands (craft, shape, audit, polish, animate, live) and 59 deterministic anti-slop rules. The most-used frontend design skill (230k+ installs). | [pbakaus](https://github.com/pbakaus) | -| [`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 +## Install ```bash -# 1. Copy workflows into your agent's skills directory -# Hermes Agent: +# 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 (won't load a loose .md) +# 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) @@ -145,102 +66,154 @@ for f in workflows/*.md; do cp "$f" "$HOME/.claude/skills/$name/SKILL.md" done -# 2. (Optional, for security review) the supporting skills are already -# vendored in skills/ -- no external clone needed, just copy (Hermes; for -# Claude Code use the same loop as step 1, swapping "workflows" for "skills"): +# 2. Security review: the supporting skills are already vendored in skills/. +# Hermes: cp -r skills/* ~/.hermes/skills/ +# Claude Code: copy each skills// directory to ~/.claude/skills// +# (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 +# "build a new page" -> wf-frontend loads ``` +The remaining skills install through `npx skills` (agentskills.io format), for example: + +```bash +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.md`. The QA harness has the same requirement: it reads +> `~/.hermes/skills/software-development//SKILL.md`, so the flat `cp` +> used for Hermes above is not enough to run it (see [the harness](#the-qa-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. + +```mermaid +flowchart LR + A["Code / diff"] --> B["1 SCOPE"] + B --> C["2 HUNT
known CVEs"] + C --> D["3 CONSULT
OSV.dev, GitHub Advisory, NVD"] + D --> E["4 CODE REVIEW
OWASP Top 10 + ASVS"] + E --> F["5 REPORT + GATE
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`](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 | + +
+ +
+Not vendored (install separately) + +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) | + +
+ ## The QA harness -The `qa/` directory keeps the workflows themselves honest: +The [`qa/`](qa) directory keeps the workflows honest: ```bash cd qa - 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 +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 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. +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. -## Quality tests and measured gains +
+Measured scores -These are real numbers from the harness runs, stored in `qa/snapshots/`. The baseline column is the state before the refinement work; the final column is the result after it. +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. -### Workflow quality score (same harness, before β†’ after) - -| Workflow | Baseline | Final | Gain | +| 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% | -| **Total** | **615.9** | **1223.2** | **+98.6%** | +| `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% | -That is almost exactly double the quality of the workflows, measured with the same ruler. +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. -The ruler itself also grew stricter over the project (13 β†’ 30+ criteria: verification per phase, real commands, anti-patterns, acceptance criteria, artifacts, flow). That is why the early snapshots show lower totals: `base-364` (13 criteria) β†’ `baseline-v2` (536.7) β†’ `baseline-v3` (675.0) β†’ `baseline-v4` (884.6) β†’ `baseline-final` (1613.2 with four workflows). The fair before/after comparison above uses the final ruler for both sides. +
-### Gates (regression checks): all green +## Known limits -| Gate | What it checks | Status | -|---|---|---| -| G1 | Score did not drop below baseline | βœ… | -| G4 | Every referenced skill exists | βœ… 4/4 workflows | -| G5 | Every phase has β‰₯3 verification verbs | βœ… 4/4 workflows | -| Meta-tests | Corrupt harness/workflows β†’ score drops (proves detector works) | βœ… | +- The harness reads installed copies from `~/.hermes/skills/software-development//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. -### What the refinement added +## Contributing -Every workflow gained the same batch of real improvements: -- **Verification steps** with actual commands (`curl`, `grep`, `python3`, `git`, `npm`, `pytest`) instead of prose. -- **Per-phase acceptance checklists** (markable `[ ]` gates). -- **Anti-pattern blocks** per phase (what not to do, and why). -- **Executable-command sections** and **worked examples per phase**. -- **Checkpoints** that pause for user approval between phases. - -The security workflow gained a hard rule: *never claim "no CVE" without querying OSV.dev / GitHub Advisory*. A model's knowledge stops at its training cutoff; the live sources don't. - -### Context on the "double" target - -The harness has a physical ceiling (sum of all criterion caps). The numeric "2Γ— of baseline" target would need a ruler with more resolution to be expressible, so inflating the score to hit it would be gaming the metric. What shipped is the honest version: real quality ~doubled on the same ruler (+98.6%), with meta-tests proving the ruler detects regressions. - - -## Repository layout - -``` -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 -β”œβ”€β”€ CONTRIBUTING.md # what to improve, local checks, PR process -└── qa/ # quality harness, gates, meta-tests - β”œβ”€β”€ wf_quality_harness.py - β”œβ”€β”€ test_quality.py - β”œβ”€β”€ test_tests.py - └── snapshots/ -``` +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). ## License -[MIT](LICENSE) Β© 2026 [Evandro Fonseca Junior](https://github.com/evandrodevbr) - ---- - -
- -⭐ If this saves you from one "works on my machine" merge, star it. - -
+[MIT](LICENSE), (c) 2026 Evandro Fonseca Junior. Vendored skills keep their own +licenses ([`skills/NOTICE.md`](skills/NOTICE.md)).