From 13942526a15915ba7ee5bd4630deee582930d9ed Mon Sep 17 00:00:00 2001 From: Sergey <93754860+slaid098@users.noreply.github.com> Date: Tue, 4 Aug 2026 13:37:03 +0300 Subject: [PATCH] feat(skills): audit skill + /audit command for one-command project audit (#257) * feat(skills): add audit skill for one-command project audit * feat(commands): add /audit command as thin wrapper for audit skill --------- Co-authored-by: opencode-agent --- .opencode/commands/audit.md | 5 ++ .opencode/skills/audit/SKILL.md | 148 ++++++++++++++++++++++++++++++++ 2 files changed, 153 insertions(+) create mode 100644 .opencode/commands/audit.md create mode 100644 .opencode/skills/audit/SKILL.md diff --git a/.opencode/commands/audit.md b/.opencode/commands/audit.md new file mode 100644 index 0000000..45a460b --- /dev/null +++ b/.opencode/commands/audit.md @@ -0,0 +1,5 @@ +--- +description: Audit existing project — verdict + auto-create issues for refactor +agent: build +--- +Load the `audit` skill via `skill({name: "audit"})` and follow its ПРОТОКОЛ strictly. Главный агент — оркестратор: `project-status` tool (read-only) + `explore` subagent (code-standards) + вопрос юзеру + `task(general)` для create-issue. Не делает edit/read/`gh issue create` сам. \ No newline at end of file diff --git a/.opencode/skills/audit/SKILL.md b/.opencode/skills/audit/SKILL.md new file mode 100644 index 0000000..7d3e32e --- /dev/null +++ b/.opencode/skills/audit/SKILL.md @@ -0,0 +1,148 @@ +--- +name: audit +description: One-command project audit. project-status tool + explore subagent (code-standards) → binary verdict → ask user → create-issue for each problem. Read-only (creates issues, NOT fixes). Also when user says "аудит проекта", "проверь проект", "audit", "проверь архитектуру". +--- + +# Audit + +Линейный flow для аудита существующего проекта. В отличие от +`project-template` check flow (который чинит через FIX subagents напрямую), +audit создаёт **GitHub issues** для рефакторинга — дальше юзер запускает +`/run-pipeline` на каждом issue (pipeline-подход: ISSUE → IMPLEMENT → CI → +REVIEW → MERGE). + +Источники находок: +- **`project-status` tool** — детерминированные проблемы (нет `conftest.py`, + нет `ci.yml`, thin routes, centralized models). Agent парсит текстовый + отчёт (НЕ JSON — `project-status.py` не трогаем). +- **`explore` subagent + `code-standards` skill** — качественные проблемы + (`project-status` НЕ ловит): schemas смешаны с models, бизнес-логика в + роутах, нарушение layering, service-слой пропущен. + +## ПРОТОКОЛ (ЖЁСТКО) + +1. **`project-status({})`** — оркестратор вызывает tool напрямую (read-only + oracle, ALLOWED — как `pipeline-status` / `spec-status`). Если вернул + `⚠️ ...failed` → WARN, продолжай без детерминированных находок (explore + всё равно работает). +2. **Парсит отчёт** (текст): `Итог:` (OK/WARN/FAIL counts) + `Рекомендации:` + (список FAIL с путями). +3. **`skill({ name: "code-standards" })`** — load skill (НЕ хардкод правил в + audit skill — `code-standards` источник правды). +4. **Delegate `explore` subagent** (Template EXPLORE) — проверяет структуру + и код против `code-standards`, возвращает + `[{category, problem, path, severity}, ...]`. +5. **Комбинирует** находки: FAIL/WARN из `project-status` + качественные из + explore. **Дедупликация**: если `project-status` FAIL и explore нашли + одну и ту же проблему → 1 issue (не 2). +6. **Бинарный вердикт**: + - `≥1 FAIL` ИЛИ `≥1 qualitative finding` → `❌ Найдено N проблем` + - `0 FAIL` + `0 qualitative` + `0 WARN` → `✅ Проект здоров` → STOP + - `0 FAIL` + `0 qualitative` + `≥1 WARN` → `⚠️ N замечаний` → вопрос +7. **Список проблем** (сгруппированный: Структура / Качество / Тесты / Infra + / Code-standards) — покажи юзеру. +8. **Вопрос юзеру**: + ``` + Найдено N проблем. Создать issues для рефакторинга? + [1] да — для каждой проблемы create-issue (subagent) + [2] нет — STOP, отчёт у юзера + ``` +9. Если `да` → для **каждой** проблемы (последовательно, НЕ параллельно — + Linear Execution из AGENTS.md) — delegate `task(general)` с Template + ISSUE_CREATE. Если `create-issue` валидация упала → subagent сообщает + ошибку, continue к следующей. Если gh недоступен → STOP + report. +10. **Финальный репорт**: + ``` + Audit complete. Создано N issues: + - #M1: — <url> + Запусти /run-pipeline на каждом issue для рефакторинга. + ``` + +### ЗАПРЕЩЕНО + +- Чинить код напрямую (audit = read-only, только issues). FIX flow остаётся + в `project-template` check flow. +- Параллелить create-issue subagents (Linear Execution). +- Хардкодить правила из `code-standards` — загружай через `skill()`. +- Трогать `project-status.py` (агент парсит текст — JSON не нужен). +- Создавать `audit-status` tool (audit — линейный, не фазный loop). +- Группировать проблемы в один issue (1 проблема = 1 issue для `/run-pipeline`). + +## Граничные случаи + +- **Репо UNKNOWN типа** → explore всё равно проверяет против + `code-standards`, вердикт по качественным находкам. +- **Репо без `src/<pkg>/`** (flat layout) → `project-status` WARNs, explore + проверяет по `code-standards` (если применимо). +- **Только WARN** (0 FAIL, 0 qualitative) → `⚠️ N замечаний`, вопрос (да/нет + — на усмотрение юзера). +- **Юзер "нет"** → STOP, отчёт у юзера. +- **create-issue валидация упала** → subagent сообщает, continue к следующей. +- **Дублирующие проблемы** → дедупликация оркестратором (1 issue, не 2). + +## Prompt templates + +### Template EXPLORE (code-standards qualitative audit) + +``` +Прочитай .opencode/skills/code-standards/SKILL.md. +Проверь структуру и код проекта в <cwd> против правил из skill. +Найди качественные проблемы, которые project-status НЕ ловит: +- schemas смешаны с models (Pydantic DTO в db/models/) +- бизнес-логика в роутах (Tortoise queries в api/) +- нарушение layering (routes импортируют db/models напрямую, минуя services) +- service-слой пропущен (routes → db/models без services/) +- файлы длиннее 200-300 строк (декомпозиция) +- mixing concerns (бизнес-логика ≠ транспорт ≠ представление) + +Для каждой находки верни: +{category: "Code-standards", problem: "<name>: <detail>", path: "<file:line>", severity: "warn"|"fail"} + +Верни массив находок. Если находок нет — пустой массив []. +НЕ редактируй код — audit read-only. Только отчёт. +``` + +### Template ISSUE_CREATE (create-issue для одной проблемы) + +``` +Создай GitHub issue для проблемы из audit. +Категория: <category> +Проблема: <name>: <detail> +Путь: <path> +Источник: <project-status | code-standards explore> +Severity: <warn|fail> + +1. Load `issue` skill via `skill({ name: "issue" })`. +2. Сформируй issue body (8 headings: ## Контекст, ## Задача, ## Контракты, + ## Инварианты, ## Граничные случаи, ## Вне scope, ## Критерии приемки). + - Контекст: проблема из audit (<repo>) — <name>: <detail>. Путь: <path>. + Источник: <source>. Severity: <severity>. + - Задача: что починить (конкретно, с путями к файлам). + - Контракты: конкретные изменения (что должно стать после фикса). + - Инварианты: что НЕ ломать при фиксе. + - Граничные случаи: edge cases при фиксе. + - Вне scope: что НЕ делаем в этом issue. + - Критерии приемки: чек-лист (включая `project-status` проходит эту + категорию после фикса). +3. `create-issue({ title: "fix(<scope>): <description>", body, labels: ["tech-debt", "from-audit"] })` + tool (НЕ raw `gh issue create` — заблокирован deny). tool валидирует + conventional title + 7 headings + Cyrillic. +4. Верни: issue URL (или ошибку валидации для оркестратора). + +Если gh недоступен → верни: "gh unavailable: <reason>". НЕ retry, НЕ fallback. +``` + +## Rules + +- Main agent = оркестратор: `project-status` tool + `explore` subagent + + вопрос юзеру + `task(general)` для create-issue. Не делает + edit/read/`gh issue create` сам. +- `project-status` — read-only oracle, ALLOWED для оркестратора. +- Audit — read-only (НЕ редактирует код, только создаёт issues). +- FAIL/WARN из `project-status` → issues, НЕ FIX напрямую. +- 1 проблема = 1 issue (для отдельного `/run-pipeline`). +- Issue body self-contained (8 headings, `create-issue` валидация). +- `code-standards` — через `skill()` tool, НЕ хардкод. +- Audit — линейный flow (не `audit-status` tool). +- create-issue subagents — последовательно (Linear Execution). +- Subagent error → 1 retry, потом STOP + report. \ No newline at end of file