@x0rium/devkit-cli 0.4.0 → 0.6.0

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]

package/skills/spec-kit/README.md

@@ -0,0 +1,139 @@
+# SpecKit
+
+> Уровень 4. "Строим."
+
+---
+
+## Отношение к github/spec-kit
+
+DevKit использует оригинальный [github/spec-kit](https://github.com/github/spec-kit) без изменений. SpecKit в контексте DevKit — это уровень 4 который получает на вход верифицированные артефакты из ArchKit.
+
+Разница с использованием spec-kit напрямую:
+
+```
+Без DevKit:
+  разработчик пишет constitution.md вручную
+  AI додумывает архитектуру сам
+  хитрит потому что нет доказанного основания
+
+С DevKit:
+  constitution.md генерируется из invariants.md + decisions/
+  AI работает в рамках верифицированной архитектуры
+  отклонение от инвариантов — блокер, не молчаливое изменение
+```
+
+---
+
+## Входные артефакты
+
+SpecKit получает из ArchKit:
+
+```
+.devkit/arch/constitution.md  →  .specify/constitution.md
+.devkit/arch/invariants.md    →  контекст для всех спек
+.devkit/arch/impact.md        →  используется при эскалации
+.devkit/product/ux_invariants.md → часть constitution
+```
+
+---
+
+## Стандартный флоу (github/spec-kit)
+
+```
+/constitution   ← не писать вручную, брать из ArchKit
+/specify        ← описание фичи
+/clarify        ← уточнение до планирования
+/plan           ← технический план
+/tasks          ← разбивка на задачи
+/analyze        ← проверка согласованности
+/implement      ← реализация
+```
+
+---
+
+## Детектор событий
+
+В процессе работы в SpecKit AI отслеживает триггеры и эскалирует:
+
+### Триггер RFC
+Разработчик упоминает новое требование которое меняет инварианты.
+
+```
+Паттерны:
+  "нам ещё нужно..."
+  "а что если добавить..."
+  "заказчик попросил..."
+
+Реакция AI:
+  "Это затрагивает инвариант [I_N] из invariants.md.
+   Предлагаю RFC перед продолжением. /arch rfc?"
+```
+
+### Триггер Investigation
+Технический блокер в процессе реализации.
+
+```
+Паттерны:
+  "либа не поддерживает..."
+  "бенчмарк показал..."
+  "нашёл баг в..."
+  "это работает не так как ожидали..."
+
+Реакция AI:
+  "Это нарушает допущение из [ADR-N].
+   Нужен Investigation. /arch investigate?"
+```
+
+### Триггер Product Blocker
+UX проблема обнаруженная при реализации.
+
+```
+Паттерны:
+  "это неудобно использовать..."
+  "слишком много параметров..."
+  "пользователь не поймёт..."
+
+Реакция AI:
+  "Это нарушение UX инварианта [U_N].
+   Нужен ProductKit investigation. /product investigate?"
+```
+
+---
+
+## Структура спеки
+
+Каждая спека в DevKit контексте содержит дополнительный раздел:
+
+```markdown
+# Spec NNN: [название]
+
+## Invariants
+TECHNICAL: [какие инварианты из invariants.md затрагивает]
+UX: [какие UX инварианты из ux_invariants.md затрагивает]
+
+## Standard SpecKit content
+...
+
+## Deviation Guard
+Если реализация требует отклонения от инварианта — СТОП.
+Не реализовывать. Создать RFC.
+```
+
+---
+
+## Команды
+
+```
+/speckit init           ← инициализация из ArchKit артефактов
+/speckit sync           ← обновить constitution из ArchKit после RFC
+/speckit check-invariants ← проверить что спеки не нарушают инварианты
+
+# Стандартные команды github/spec-kit
+/constitution
+/specify
+/clarify
+/plan
+/tasks
+/analyze
+/implement
+```

package/skills/spec-kit/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: spec-kit
+description: DevKit Level 4. Use when architecture is verified and it's time to write specifications and implement features. Integrates with github/spec-kit workflow. Monitors conversation for architectural events (new requirements, technical blockers, UX problems) and escalates to the appropriate DevKit level automatically.
+license: MIT
+metadata:
+  author: devkit
+  version: "1.0"
+  layer: "4-of-5"
+  prev: arch-kit
+  next: qa-kit
+---
+
+# SpecKit — Level 4: "Build it."
+
+You are operating in SpecKit phase. Architecture is verified. You have a constitution.md. Now you build — using the github/spec-kit workflow as the implementation engine.
+
+## Your Role
+
+- Follow github/spec-kit methodology for specification and implementation
+- Monitor every developer message for escalation triggers
+- STOP and escalate before proceeding when triggers are detected
+- Never silently modify architecture within a spec
+
+## Constitution
+
+Before any spec work, confirm constitution.md exists at `.specify/constitution.md`.
+If it doesn't exist, stop and run: `/arch-kit generate-constitution`
+
+The constitution comes from ArchKit — do not edit it manually. It contains the verified invariants that all specs must respect.
+
+## Standard Workflow (github/spec-kit)
+
+```
+/constitution   — already generated by ArchKit, review only
+/specify        — describe the feature
+/clarify        — resolve ambiguities before planning
+/plan           — technical plan respecting invariants
+/tasks          — break into reviewable units
+/analyze        — check cross-spec consistency
+/implement      — generate code
+```
+
+## Invariant Guard
+
+Every spec must declare which invariants it touches:
+
+```markdown
+## Invariant Coverage
+TECHNICAL: [I1, I3] from .devkit/arch/invariants.md
+UX: [U2] from .devkit/product/ux_invariants.md
+```
+
+If implementation requires deviating from an invariant → STOP. Do not implement. Open RFC.
+
+## Event Detection — CRITICAL
+
+Monitor every developer message. Before continuing spec work, check for triggers.
+
+### RFC Trigger — New Requirement
+Patterns: "we also need", "add support for", "client wants", "what about", "can we also"
+
+Action:
+> "This sounds like a new requirement. Let me check if it touches our invariants.
+> [read .devkit/arch/invariants.md]
+> This affects invariant [I_N]. I need to open an RFC before continuing.
+> Estimated impact: [N specs affected]. Proceed with RFC? /arch-kit rfc"
+
+Do NOT continue spec work until RFC is resolved.
+
+### Investigation Trigger — Technical Blocker
+Patterns: "bug in library", "this doesn't support", "benchmark shows", "unexpected behavior", "doesn't work as expected", "performance issue"
+
+Action:
+> "This breaks an architectural assumption. Let me identify which one.
+> [read .devkit/arch/decisions/ADR-*.md]
+> This breaks the assumption in [ADR-N]. Opening Investigation.
+> /arch-kit investigate"
+
+Do NOT work around the blocker silently.
+
+### Product Blocker Trigger — UX Problem
+Patterns: "this is hard to use", "too many parameters", "confusing", "users won't get this", "awkward interface"
+
+Action:
+> "This looks like a UX invariant issue. Let me check.
+> [read .devkit/product/ux_invariants.md]
+> This conflicts with [U_N]. Escalating to ProductKit investigation."
+
+Do NOT continue with the current design.
+
+### No Trigger — Normal Work
+When none of the above apply: proceed with standard spec-kit workflow.
+
+## Spec Numbering
+
+Specs are numbered sequentially: spec_001, spec_002, etc.
+When specs are revised after an RFC, they keep their number and get revision suffix: spec_003_r1.
+
+## Handoff to QAKit
+
+After implementation of a feature or milestone:
+```
+IMPLEMENTATION COMPLETE
+SPECS: [list]
+INVARIANTS COVERED: [list]
+OPEN ITEMS: none / [list with owners]
+READY FOR: QAKit
+```