Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
e5e400e
chore: gitignore .superpowers/ SDD scratch directory
vitor-rangel-vinta Sep 10, 2026
0fea2c6
feat(schema): add qa-frontend / qa-review config contract
vitor-rangel-vinta Sep 10, 2026
9c70a25
feat(skills): add qa-frontend foundation skill template
vitor-rangel-vinta Sep 10, 2026
ee8d3b2
fix(skills): restore phi ledger clause and tighten qa-frontend guard …
vitor-rangel-vinta Sep 10, 2026
e21fc99
feat(skills): add portable qa-review foundation skill template
vitor-rangel-vinta Sep 10, 2026
9220788
fix(skills): add browser-availability stop, load retry, report-locati…
vitor-rangel-vinta Sep 10, 2026
f0ec77a
feat(derive-skills): wire qa-frontend / qa-review buckets and placeho…
vitor-rangel-vinta Sep 10, 2026
94224e7
fix(derive-skills): align placeholder table with template contracts
vitor-rangel-vinta Sep 10, 2026
f0acec3
feat(bootstrap): add qa-frontend / qa-review interview and config emi…
vitor-rangel-vinta Sep 10, 2026
6e0e8aa
docs: wire qa-frontend / qa-review into classifier, refresh path and …
vitor-rangel-vinta Sep 10, 2026
0c2d7a9
docs(changelog): add 0.7.0 section for qa-frontend / qa-review
vitor-rangel-vinta Sep 10, 2026
101331a
refactor(skills): rename qa-frontend foundation skill to dev-desk-check
vitor-rangel-vinta Sep 10, 2026
6df3740
fix(skills): drop conditional-skill links, add viewport field, remove…
vitor-rangel-vinta Sep 10, 2026
4d11d2f
fix(skills): stop dev-desk-check promising stripped regions, resolve …
vitor-rangel-vinta Sep 14, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -71,3 +71,6 @@ coverage/
!.cursor/skills
.agents/*
!.agents/skills

# Superpowers SDD scratch
.superpowers/
84 changes: 84 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,90 @@ All notable changes to `vinta-ai-workflows` are documented in this file.
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.7.0] — YYYY-MM-DD

### Added

- **Two new opt-in foundation skills for browser QA: `dev-desk-check` and
`qa-review`.** Every QA path in this package was Playwright-shaped:
`create-qa-use-cases` generates a human checklist that nothing executes, and
`run_options.run_e2e` defaults off because the suite is slow. These two drive
a real browser through the app as a user, judge what renders, and produce
evidence someone who wasn't there can trust.

`dev-desk-check` is the engineer path: it takes a plan from the branch diff (vs
the PR's real base, resolved per `project.code_host` — "no PR" and "the CLI
failed" are different answers, and only the first falls back to the default
branch), from ids in the project's QA use-cases doc, or from a ticket. It
preflights services → frontend → backend, enforces the project's
per-environment write policy before the browser opens, keeps an incremental
write ledger with a reversal recorded per entry, and writes a report plus a
PR `Q.A.` section. Template-rendered from
`vinta-derive-skills/resources/dev-desk-check-template.md`. It is **not** wired
into `implement-plan`'s phase gate — a browser pass per phase is too slow,
the same reasoning that keeps `run_e2e` off — and it hand-rolls no browser
tooling: with no browser skill or MCP in the harness it says so and stops.

`qa-review` is the portable path for product managers and designers: the same
walk and the same report shape with git, diffs, dev servers, service probes,
PR edits and database access stripped out. It renders **self-contained** — no
relative links, no repo-dependent commands — so an engineer hands over the
single `SKILL.md` and it works with no checkout. Stable facts are inlined
(environment addresses, account role, design source, who to ask when
blocked); the QA use-cases doc deliberately is not, because a snapshot of a
checklist the repo keeps updating is worse than no snapshot. From
`vinta-derive-skills/resources/qa-review-template.md`.

- **New `foundation_skills` enum entries `dev-desk-check` and `qa-review`** in
`schemas/vinta-ai-workflows-config.v1.schema.json`. They are **independent**
opt-ins — a project can take the engineer path alone, the review path alone,
or both — and both render from one shared config block.

- **New `skills.dev-desk-check` config block**, read by both skills. Guard rails
are data, not prose: `environments.<name>` carries `base_url`, optional
`api_url` / `api_health_path`, an opt-in-by-absence `frontend_start` (no key
means probe and stop — a second dev server on an occupied port silently
invalidates a run), a required `writes` policy (`free` / `confirm` /
`forbidden`), a `data_sensitivity` level (`none` / `client` / `phi`), and an
optional `edge_proxy` that suppresses the `curl` preflight for environments
behind a WAF that answers non-browser traffic with a 403. Alongside it:
optional `services[]` (read-only time-bounded probes, `required` verdict,
local-only `start`), `auth` (manual login only — the agent can never type a
password — with account roles and **pointers to** where credentials live,
never credentials), `feature_flags`, `design_source`, `use_cases_path`,
`report_dir` and `escalation_contact`. Absent optional blocks strip their
region from the rendered body rather than shipping it empty.

`data_sensitivity` drives evidence handling, not just writes: `client` keeps
screenshots in the gitignored `report_dir` and off PRs and design tools;
`phi` additionally restricts the report and the write ledger to opaque ids
and removes the shareable-Artifact deliverable entirely, because publishing
to hosted storage would move records outside the managed platform's access
controls and audit logging.

- **New `run_options.dev-desk-check` block** — `screenshots`, `scope`
(`diff` / `use-cases` / `description`), `browser`, `dry_run`. Read by both
skills; `qa-review` ignores what has no meaning without a checkout.

- **Two new `vinta-bootstrap-ai-tools` interview questions** in the **Optional
foundation skills** group (now nine, up from seven), plus one shared block of
config follow-ups asked once when either skill is enabled: environments,
per-environment write policy and data sensitivity, edge proxies, backing
services, auth account pointers, feature-flag system, design source,
escalation contact, and per-run defaults.

- **Sixteen new `vinta-derive-skills` placeholders** (`{{QA_*}}`) documented in
its placeholder table, plus a `qa-review`-specific **portability check** run
before the render is saved: it greps the output for relative links and
repo-dependent commands, because a config value spliced into a block can
break portability even when the template is clean.

- **`vinta-update-project-skills` now flags `qa-review` for re-render on a
config change**, not only on a template change. Its body inlines facts its
holder cannot look up, so a changed `skills.dev-desk-check` makes the shipped
copy stale; the render carries a generation date and source commit to compare
against.

## [0.6.1] — 2026-08-17

### Fixed
Expand Down
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,7 @@ Standalone re-invocation works at every step — kick `create-spec` again when t

Quick inventory of what `vinta-bootstrap-ai-tools` writes into your repo's `ai-tools/` layout — plus `AGENTS.md` at the repo root, the one artifact that lives outside it — and exposes via per-vendor wiring at `.claude/skills/`, `.agents/skills/`, etc. Two disclaimers up front:

> **Optional foundation skills are gated by the bootstrap interview.** `systematic-debugging`, `add-e2e-test`, `add-env-var`, `add-one-off-script`, `prepare-worktree`, `thermo-nuclear-code-quality-review`, and `handoff-to-client` ship **only** if the user says yes during `vinta-bootstrap-ai-tools` Step 0 (or later opts in via `vinta-sync-ai-tools`). They are not in every bootstrapped project. The opt-in is recorded in `.vinta-ai-workflows.yaml` under `foundation_skills.*.enabled` and is sticky across syncs.
> **Optional foundation skills are gated by the bootstrap interview.** `systematic-debugging`, `add-e2e-test`, `add-env-var`, `add-one-off-script`, `prepare-worktree`, `thermo-nuclear-code-quality-review`, `dev-desk-check`, `qa-review`, and `handoff-to-client` ship **only** if the user says yes during `vinta-bootstrap-ai-tools` Step 0 (or later opts in via `vinta-sync-ai-tools`). They are not in every bootstrapped project. The opt-in is recorded in `.vinta-ai-workflows.yaml` under `foundation_skills.*.enabled` and is sticky across syncs.
>
> **Stack-specific skills and sub-agents are user-supplied.** This package ships **detection signals + category lists** per stack ([resources/stacks/](skills/vinta-bootstrap-ai-tools/resources/stacks/) — Django, Medplum, Next.js App Router, Python package, TypeScript monorepo), not the bodies. When a stack is detected, the orchestrator asks the user for a path / URL to their team's existing template. If no template exists, the category is recorded as a gap in the final summary, not auto-drafted. Bodies are project- and team-specific; one shared template doesn't fit every team's conventions.

Expand Down Expand Up @@ -249,6 +249,8 @@ Land at `ai-tools/skills/<name>/SKILL.md`. Always-on unless flagged optional.
| [`prepare-worktree`](skills/vinta-derive-skills/resources/foundation-skills/prepare-worktree/SKILL.md) | **opt-in** | Provision a fully-runnable git worktree for parallel plan work — reads the plan + `.gitignore` + manifests + env / docker config and decides per ignored path whether to **symlink / copy / fork** (dev DB, env files, compose project name). Ships an OS-level write-guard (`sandbox-run.sh` + a Claude Code `PreToolUse` hook) so stray writes to the main checkout fail at the kernel layer. `implement-plan` Step 0 question (c) opts a run into it. |
| [`thermo-nuclear-code-quality-review`](skills/vinta-derive-skills/resources/foundation-skills/thermo-nuclear-code-quality-review/SKILL.md) | **opt-in** | Deliberately harsh structural-maintainability audit of a diff — abstraction quality, giant files, spaghetti-condition growth — hunting "code-judo" reframes that collapse whole branches / helpers / modes / layers. Read-only; hands each fix to `fixer`. `review-phase` Layer 3 runs a condensed lens every phase and escalates to this full audit on core-architecture / ~1000-line / structurally-smelly phases. |
| `handoff-to-client` | **opt-in** | (API-only repos) Generate a self-contained API-change handoff doc for the client teams consuming the repo's API — every endpoint / operation added / changed / deprecated / removed vs the default branch, with request/response shapes, auth + error changes, breaking-change flags, one example per operation, and per-platform migration notes. Template-rendered from `skills.handoff-to-client.*` config (client platforms, API style, spec path). |
| `dev-desk-check` | **opt-in** | Drive a real browser through the app as a user and report what actually renders — the manual pass that complements automated e2e. Plan source is the branch diff, ids from `QA_USE_CASES.md`, or a ticket. Preflights services / frontend / backend per environment, enforces the project's per-environment write policy and data-sensitivity rules before opening the browser, keeps an incremental write ledger with a reversal per entry, and writes an evidence-backed report plus a PR `Q.A.` section. Template-rendered from `skills.dev-desk-check.*` config. |
| `qa-review` | **opt-in** | The same browser walk and report shape for product managers and designers, with git, diffs, dev servers, service probes, PR edits and database access stripped out. Rendered **self-contained** — no relative links, no repo-dependent commands — so an engineer can hand over the single `SKILL.md` and it works with no checkout. Reads the same `skills.dev-desk-check.*` config block; opt-in independently of `dev-desk-check`. |

#### `write-unit-test` in depth

Expand Down
Loading