@x0rium/devkit-cli 0.5.0 → 0.6.0

package/skills/qa-kit/README.md

@@ -0,0 +1,188 @@
+# QAKit
+
+> Уровень 5. "Работает ли это как мы решили?"
+
+---
+
+## Ключевая идея
+
+Обычный QA проверяет код против спек. QAKit проверяет систему против **всех уровней принятых решений**. Тест который упал — это не просто баг. Это сигнал о том на каком уровне решение было неверным.
+
+```
+QAKit проверяет:
+
+  против SpecKit:      код делает что написано в спеке?
+  против ArchKit:      система соблюдает технические инварианты?
+  против ProductKit:   продукт решает проблему пользователя?
+  против ResearchKit:  assumptions оказались верны?
+```
+
+---
+
+## Входные артефакты
+
+```
+.devkit/arch/invariants.md       → test_contracts.md
+.devkit/product/ux_invariants.md → ux_test_contracts.md
+.devkit/research/assumptions.md  → assumption_checks.md
+.specify/specs/                  → spec coverage
+```
+
+---
+
+## Фазы
+
+### Phase 1: Contract Generation
+```
+Из каждого инварианта генерируется тест-контракт:
+  - что проверяем
+  - как проверяем
+  - что является нарушением
+  - критичность нарушения
+```
+
+### Phase 2: Coverage Analysis
+```
+Карта покрытия:
+  - какие инварианты покрыты тестами
+  - какие инварианты не покрыты (технический долг)
+  - какие assumptions проверены в реальности
+```
+
+### Phase 3: Assumption Validation
+```
+Проверка что assumptions из ResearchKit
+оказались верны в реальной системе.
+
+Если assumption отклонён реальностью →
+эскалация в ResearchKit для пересмотра.
+```
+
+---
+
+## Эскалация
+
+### Логика эскалации упавшего теста
+
+```
+Тест упал
+      ↓
+AI анализирует: что именно нарушено?
+      ↓
+┌─────────────────────────────────────────────┐
+│ Баг реализации?                             │
+│ Код не соответствует спеке                  │
+│ → фикс в SpecKit, не эскалируем             │
+└─────────────────────────────────────────────┘
+      ↓ нет
+┌─────────────────────────────────────────────┐
+│ Нарушен технический инвариант?              │
+│ Система не выполняет архитектурную гарантию │
+│ → Investigation в ArchKit                   │
+└─────────────────────────────────────────────┘
+      ↓ нет
+┌─────────────────────────────────────────────┐
+│ Нарушен UX инвариант?                       │
+│ Система работает но неудобна / непонятна    │
+│ → Product Blocker в ProductKit              │
+└─────────────────────────────────────────────┘
+      ↓ нет
+┌─────────────────────────────────────────────┐
+│ Отклонён assumption из ResearchKit?         │
+│ Реальность не совпала с предположением      │
+│ → ResearchKit revision                      │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## Артефакты
+
+### test_contracts.md
+```markdown
+# Test Contracts
+
+## TC-I1: [название инварианта]
+INVARIANT: I1 из invariants.md
+WHAT: что проверяем
+HOW: метод проверки (unit / integration / e2e / manual)
+VIOLATION: что считается нарушением
+CRITICALITY: blocker / major / minor
+COVERAGE: covered / not-covered
+```
+
+### ux_test_contracts.md
+```markdown
+# UX Test Contracts
+
+## TC-U1: [название UX инварианта]
+INVARIANT: U1 из ux_invariants.md
+SCENARIO: пользовательский сценарий для проверки
+WHAT: что наблюдаем
+VIOLATION: что считается нарушением
+METHOD: usability test / metric / manual review
+```
+
+### assumption_checks.md
+```markdown
+# Assumption Validation
+
+## AC-A1: [название assumption]
+ASSUMPTION: A1 из assumptions.md
+ORIGINAL_STATEMENT: что предполагали
+VALIDATION_METHOD: как проверили
+RESULT: confirmed / rejected / partially-confirmed
+FINDING: что обнаружили
+ESCALATION: none / ResearchKit revision needed
+```
+
+### coverage_map.md
+```markdown
+# Coverage Map
+
+## Technical Invariants Coverage
+| Инвариант | Контракт | Статус | Метод |
+|----------|---------|--------|-------|
+| I1       | TC-I1   | ✅     | unit  |
+| I2       | TC-I2   | ❌     | -     |
+
+## UX Invariants Coverage
+...
+
+## Assumptions Validation
+...
+
+## Uncovered (технический долг)
+...
+```
+
+### escalations/
+```
+ESC-XXX.md  ← история каждой эскалации
+            ← что нашли, на какой уровень эскалировали, решение
+```
+
+---
+
+## Переход к Production
+
+**ALLOWED** когда:
+- все BLOCKER test contracts покрыты
+- нет open эскалаций blocker уровня
+- coverage_map показывает покрытие критических инвариантов
+
+**BLOCKED** когда:
+- есть непокрытые BLOCKER контракты
+- есть open эскалации blocker уровня
+
+---
+
+## Команды
+
+```
+/qa init                    ← генерация контрактов из инвариантов
+/qa coverage                ← анализ текущего покрытия
+/qa check-assumptions       ← валидация assumptions против реальности
+/qa escalate "описание"     ← ручная эскалация
+/qa status                  ← можно ли в production
+```

package/skills/qa-kit/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: qa-kit
+description: DevKit Level 5. Use after implementation to verify the system against all levels of decisions: specs, technical invariants, UX invariants, and research assumptions. Generates test contracts from invariants. Escalates failures to the correct DevKit level — not just bug reports, but signals about where a decision was wrong.
+license: MIT
+metadata:
+  author: devkit
+  version: "1.0"
+  layer: "5-of-5"
+  prev: spec-kit
+---
+
+# QAKit — Level 5: "Does it work the way we decided?"
+
+You are operating in QAKit phase. Your job is not just to find bugs — it is to verify the system against every level of decisions made in DevKit.
+
+## Your Role
+
+- Generate test contracts from invariants (not from code)
+- Map coverage: which invariants are tested, which are not
+- Validate that research assumptions held in reality
+- Escalate failures to the correct DevKit level
+- Distinguish between a bug in code and a wrong decision upstream
+
+## CRITICAL PRINCIPLE
+
+A failing test is a signal, not just an error. The question is not only "what broke" but "at which level was the decision wrong":
+
+```
+Code doesn't match spec?        → fix in SpecKit (no escalation)
+System violates invariant?      → Investigation in ArchKit
+System works but feels wrong?   → ProductKit investigation
+Assumption proved false?        → ResearchKit revision
+```
+
+## Phases
+
+### Phase 1: Contract Generation
+Read `.devkit/arch/invariants.md` and `.devkit/product/ux_invariants.md`.
+For each invariant, generate a test contract:
+- What to check
+- How to check it (unit / integration / e2e / manual)
+- What constitutes a violation
+- Criticality: blocker / major / minor
+
+Save to `.devkit/qa/test_contracts.md`.
+
+### Phase 2: Coverage Analysis
+Map every invariant to its test contract.
+Identify uncovered invariants — these are explicit technical debt.
+Save to `.devkit/qa/coverage_map.md`.
+
+### Phase 3: Assumption Validation
+Read `.devkit/research/assumptions.md`.
+For each assumption, check whether reality confirmed or rejected it.
+Rejected assumptions → escalate to ResearchKit.
+Save findings to `.devkit/qa/assumption_checks.md`.
+
+## Artifacts to Produce
+
+Read templates from:
+- [Test contracts template](references/test_contracts.md)
+- [Coverage map template](references/coverage_map.md)
+- [Assumption checks template](references/assumption_checks.md)
+
+Save to `.devkit/qa/`.
+
+## Escalation Logic
+
+When a test fails or a problem is found:
+
+### Step 1: What exactly failed?
+Read the failing test contract. What invariant or spec does it cover?
+
+### Step 2: Why did it fail?
+```
+Is this a code bug (code ≠ spec)?
+  → Fix in SpecKit. No escalation needed.
+
+Does the code match the spec but the spec violates an invariant?
+  → Investigation in ArchKit. Open INV-XXX.
+
+Does everything work technically but the user experience is wrong?
+  → Product Blocker in ProductKit.
+
+Did a research assumption prove false in production?
+  → ResearchKit revision.
+```
+
+### Step 3: Document the escalation
+Create `.devkit/qa/escalations/ESC-XXX.md`:
+- What was found
+- Which level it escalated to
+- What decision was triggered
+- Resolution
+
+## Gate: Ready for Production?
+
+ALLOWED when:
+- All BLOCKER test contracts pass
+- No open escalations of blocker severity
+- Coverage map shows all `must` invariants covered
+
+BLOCKED when:
+- Any BLOCKER contract fails
+- Open blocker-level escalation exists
+
+## Continuous QA
+
+QAKit is not a one-time gate. It runs:
+- After each SpecKit implementation batch
+- After each RFC resolution (re-verify affected invariants)
+- After each Investigation resolution
+- Before any production deployment

package/skills/qa-kit/references/assumption_checks.md

@@ -0,0 +1,10 @@
+# Assumption Validation Template
+
+## AC-[A_N]: [assumption name]
+SOURCE: [A1 from .devkit/research/assumptions.md]
+ORIGINAL_STATEMENT: what we assumed
+VALIDATION_METHOD: how we checked this
+RESULT: confirmed / rejected / partially-confirmed
+FINDING: what we actually found
+ESCALATION: none / ResearchKit revision needed
+IMPACT_IF_REJECTED: what changes if this assumption was wrong

package/skills/qa-kit/references/coverage_map.md

@@ -0,0 +1,19 @@
+# Coverage Map Template
+
+## Technical Invariants
+| Invariant | Contract | Status | Method | Criticality |
+|----------|---------|--------|--------|-------------|
+| I1       | TC-I1   | ✅ covered | unit | blocker |
+| I2       | TC-I2   | ❌ not covered | — | major |
+
+## UX Invariants
+| Invariant | Contract | Status | Method | Criticality |
+|----------|---------|--------|--------|-------------|
+
+## Uncovered Invariants (Technical Debt)
+[List invariants with no test contract — explicit debt, not hidden]
+
+## Coverage Summary
+BLOCKER invariants covered: N/M
+MAJOR invariants covered: N/M
+OVERALL: [percentage or status]

package/skills/qa-kit/references/test_contracts.md

@@ -0,0 +1,10 @@
+# Test Contracts Template
+
+## TC-[I_N or U_N]: [invariant name]
+SOURCE_INVARIANT: [I1 from invariants.md / U1 from ux_invariants.md]
+WHAT: what we are checking
+HOW: unit / integration / e2e / manual
+VIOLATION: what counts as a failure
+CRITICALITY: blocker / major / minor
+COVERAGE: covered / not-covered
+ESCALATION_LEVEL: SpecKit / ArchKit / ProductKit / ResearchKit

package/skills/research-kit/README.md

@@ -0,0 +1,139 @@
+# ResearchKit
+
+> Уровень 1. "Возможно ли это вообще?"
+
+---
+
+## Когда использовать
+
+- у тебя есть идея которую никто ещё не делал
+- не знаешь существуют ли аналоги
+- не знаешь технически реализуемо ли это
+- не знаешь нужно ли это кому-то кроме тебя
+- хочешь понять риски до инвестиции времени
+
+---
+
+## Фазы
+
+### Phase 1: Market Research
+```
+QUESTIONS:
+  - Существуют ли аналоги?
+  - Чем они плохи / чего не делают?
+  - Есть ли незанятая ниша?
+  - Кто потенциальный пользователь?
+
+FORBIDDEN:
+  - предлагать решения
+  - думать об архитектуре
+  - оценивать сложность реализации
+```
+
+### Phase 2: Technical Feasibility
+```
+QUESTIONS:
+  - Это реализуемо с текущим state of the art?
+  - Какие известные подходы существуют?
+  - Где известные тупики и ограничения?
+  - Какие технологии близко решают задачу?
+
+FORBIDDEN:
+  - выбирать конкретный стек
+  - писать архитектуру
+```
+
+### Phase 3: Unknowns Map
+```
+Главный артефакт ResearchKit.
+Не ответы — карта того что мы не знаем.
+
+Каждый unknown классифицируется:
+  RISK: high / medium / low
+  VALIDATION: как проверить до начала разработки
+  BLOCKER: блокирует ли переход к ProductKit
+```
+
+---
+
+## Артефакты
+
+### market.md
+```markdown
+# Market Research
+
+## Аналоги
+| Инструмент | Что делает | Чего не делает | Ниша |
+|-----------|-----------|---------------|------|
+
+## Незанятое пространство
+...
+
+## Потенциальный пользователь
+...
+```
+
+### feasibility.md
+```markdown
+# Technical Feasibility
+
+## Известные подходы
+...
+
+## Известные ограничения
+...
+
+## Вывод
+FEASIBLE: yes / no / conditional
+CONDITIONS: [что должно быть верным чтобы это работало]
+```
+
+### unknowns.md
+```markdown
+# Unknowns Map
+
+## Unknown: [название]
+DESCRIPTION: что именно не знаем
+RISK: high / medium / low
+VALIDATION: как проверить
+BLOCKER: yes / no
+STATUS: open / validated / invalidated
+```
+
+### assumptions.md
+```markdown
+# Assumptions
+
+## Assumption: [название]
+STATEMENT: что предполагаем
+BASIS: почему предполагаем
+RISK: high / medium / low
+VALIDATION_METHOD: как проверить
+STATUS: assumed / confirmed / rejected
+```
+
+---
+
+## Переход к ProductKit
+
+**ALLOWED** когда:
+- все HIGH RISK unknowns имеют validation path
+- feasibility = yes или conditional с известными условиями
+- нет BLOCKER unknowns в статусе open
+
+**BLOCKED** когда:
+- есть BLOCKER unknown без validation path
+- feasibility = no
+
+---
+
+## Команды
+
+```
+/research init "описание идеи"
+/research market
+/research feasibility  
+/research unknowns
+/research validate "unknown name" "результат проверки"
+/research status      ← можно ли переходить к ProductKit
+```

package/skills/research-kit/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: research-kit
+description: DevKit Level 1. Use when developer has a new idea and needs to explore feasibility, find analogues, map unknowns, and validate assumptions before committing to build. Triggers on phrases like "I want to build X", "does this exist", "is this possible", "never been done before", "new idea".
+license: MIT
+metadata:
+  author: devkit
+  version: "1.0"
+  layer: "1-of-5"
+  next: product-kit
+---
+
+# ResearchKit — Level 1: "Is this even possible?"
+
+You are operating in ResearchKit phase. Your job is to help the developer explore the idea space before any architecture or implementation decisions are made.
+
+## Your Role
+
+- Ask questions, explore unknowns, map risks
+- Do NOT suggest technical solutions or architecture
+- Do NOT recommend a tech stack
+- Do NOT write any code
+
+## Phases
+
+### Phase 1: Market Research
+Explore whether analogues exist. Ask:
+- What problem does this solve?
+- Who has tried this before?
+- What do existing solutions lack?
+- Where is the unoccupied niche?
+
+### Phase 2: Technical Feasibility
+Explore whether this is buildable. Ask:
+- Is this achievable with current state of the art?
+- What known approaches exist?
+- What are known dead ends?
+- What are the hard constraints?
+
+### Phase 3: Unknowns Map
+This is the PRIMARY deliverable of ResearchKit.
+
+For every unknown, classify:
+- RISK: high / medium / low
+- VALIDATION: how to check before building
+- BLOCKER: does this block moving forward?
+
+## Artifacts to Produce
+
+Read templates from:
+- [Market Research template](references/market.md)
+- [Feasibility template](references/feasibility.md)
+- [Unknowns template](references/unknowns.md)
+- [Assumptions template](references/assumptions.md)
+
+Save artifacts to `.devkit/research/`.
+
+## Gate: When Can We Move to ProductKit?
+
+ALLOWED to proceed when:
+- All HIGH RISK unknowns have a validation path
+- Feasibility is `yes` or `conditional` with known conditions
+- No BLOCKER unknowns remain `open`
+
+BLOCKED when:
+- Any BLOCKER unknown has no validation path
+- Feasibility is `no`
+
+## Event Detection
+
+If developer mentions during ResearchKit:
+- New technical constraint → update feasibility.md
+- New analogue found → update market.md
+- Resolved unknown → update status in unknowns.md
+
+## Handoff
+
+When gate conditions are met, generate summary:
+```
+RESEARCH COMPLETE
+FEASIBILITY: yes/conditional/no
+KEY UNKNOWNS RESOLVED: N
+REMAINING RISKS: [list with mitigations]
+READY FOR: ProductKit
+```

package/skills/research-kit/references/assumptions.md

@@ -0,0 +1,9 @@
+# Assumptions Template
+
+## Assumption: [name]
+STATEMENT: what we assume to be true
+BASIS: why we believe this
+RISK: high / medium / low
+VALIDATION_METHOD: how to confirm or reject
+STATUS: assumed / confirmed / rejected
+FINDING: [fill when validated]

package/skills/research-kit/references/feasibility.md

@@ -0,0 +1,15 @@
+# Technical Feasibility Template
+
+## Known Approaches
+[What exists that could be used or adapted]
+
+## Known Limitations
+[Where known approaches break down]
+
+## Hard Constraints
+[Physical, regulatory, or technical ceilings]
+
+## Verdict
+FEASIBLE: yes / no / conditional
+CONDITIONS: [what must be true for this to work]
+CONFIDENCE: high / medium / low

package/skills/research-kit/references/market.md

@@ -0,0 +1,13 @@
+# Market Research Template
+
+## Analogues
+| Tool | What it does | What it lacks | Our niche |
+|------|-------------|---------------|-----------|
+
+## Unoccupied Space
+[What exists in the space no tool covers]
+
+## Potential User
+PROFILE: who they are
+PROBLEM: what they struggle with today
+CURRENT_SOLUTION: how they solve it without us

package/skills/research-kit/references/unknowns.md

@@ -0,0 +1,9 @@
+# Unknowns Map Template
+
+## Unknown: [name]
+DESCRIPTION: what exactly we don't know
+RISK: high / medium / low
+VALIDATION: how to check this before building
+BLOCKER: yes / no
+STATUS: open / validated / invalidated
+FINDING: [fill when validated]