@x0rium/devkit-cli 0.4.0 → 0.6.0

package/skills/devkit-init/references/greenfield.md

@@ -0,0 +1,44 @@
+# Greenfield Mode
+
+Fresh project. No code, no .devkit/, no .specify/.
+
+## What to Do
+
+1. Create .devkit/ structure (done by SKILL.md)
+2. Run `specify init . --ai claude` (done by SKILL.md)
+3. Tell developer to start with ResearchKit
+
+## Starting Message to Developer
+
+```
+DevKit initialized for a new project.
+
+Your development cycle:
+  /research-kit  → explore feasibility and unknowns
+  /product-kit   → define users and UX invariants  
+  /arch-kit      → verify architecture
+  /spec-kit      → implement (via spec-kit workflow)
+  /qa-kit        → verify against all decisions
+
+Start with /research-kit — describe your idea.
+```
+
+## Files to Create
+
+Create `.devkit/STATUS.md`:
+
+```markdown
+# DevKit Status
+
+MODE: greenfield
+INITIALIZED: [date]
+CURRENT_PHASE: research
+SPEC_KIT: initialized
+
+## Phase Status
+- [ ] ResearchKit
+- [ ] ProductKit  
+- [ ] ArchKit
+- [ ] SpecKit
+- [ ] QAKit
+```

package/skills/devkit-init/references/upgrade.md

@@ -0,0 +1,103 @@
+# Upgrade Mode
+
+spec-kit exists (.specify/ present). No .devkit/ yet.
+Developer is already using spec-kit and wants to add the full DevKit layer.
+
+## What This Means
+
+spec-kit is already running. There are specs, possibly a constitution.md.
+We need to reverse-engineer DevKit artifacts from what spec-kit has,
+then connect them so ArchKit owns constitution.md going forward.
+
+## Phase 1: Read Existing spec-kit Artifacts
+
+Read all files in `.specify/`:
+- `constitution.md` — project principles and constraints
+- `spec.md` — feature specifications
+- `plan.md` — technical plans
+- `tasks/` — implementation tasks
+
+Understand what's already been built and decided.
+
+## Phase 2: Extract ArchKit Artifacts from constitution.md
+
+constitution.md contains decisions that belong in ArchKit.
+
+Extract:
+- Tech stack decisions → ADR entries
+- Constraints and rules → invariant candidates
+- Patterns and standards → more invariants
+
+Create `.devkit/arch/invariants.md` from these.
+Create `.devkit/arch/decisions/` ADR files.
+
+Mark all as `inferred` with `SOURCE: constitution.md`.
+
+## Phase 3: Extract ProductKit Artifacts
+
+Look in constitution.md and spec.md for:
+- Who the user is
+- UX rules and constraints
+- What's in scope / out of scope
+
+Create `.devkit/product/users.md` and `ux_invariants.md`.
+Mark as `inferred`.
+
+## Phase 4: Link DevKit to spec-kit
+
+Going forward, constitution.md is OWNED by ArchKit.
+Add a note at the top of `.specify/constitution.md`:
+
+```markdown
+<!-- GENERATED BY DEVKIT — do not edit manually -->
+<!-- Source: .devkit/arch/invariants.md + decisions/ -->
+<!-- Regenerate with: /arch-kit generate-constitution -->
+```
+
+## Phase 5: Produce Status File
+
+Create `.devkit/STATUS.md`:
+
+```markdown
+# DevKit Status
+
+MODE: upgrade-from-speckit
+INITIALIZED: [date]
+CURRENT_PHASE: arch-review
+
+## Migration Summary
+SPEC_KIT_SPECS_FOUND: N
+INVARIANTS_EXTRACTED: M
+CONSTITUTION: linked (DevKit now owns it)
+
+## Required Actions
+- [ ] Review .devkit/arch/invariants.md
+- [ ] Confirm or correct extracted decisions
+- [ ] Run /arch-kit to fill gaps
+
+## Phase Status
+- [~] ResearchKit (not available — existing project)
+- [~] ProductKit (partially extracted)
+- [ ] ArchKit (review required)
+- [x] SpecKit (already in use)
+- [ ] QAKit
+```
+
+## Message to Developer
+
+```
+DevKit initialized over your existing spec-kit project.
+
+Extracted from your spec-kit artifacts:
+  Invariants: N (from constitution.md — review required)
+  Decisions:  M (inferred — review required)
+
+constitution.md is now managed by ArchKit.
+Changes to architecture go through /arch-kit, 
+which regenerates constitution.md automatically.
+
+Next steps:
+1. Review .devkit/arch/invariants.md
+2. Run /arch-kit to verify and complete the picture
+3. Continue using spec-kit as normal — it now has a verified foundation
+```

package/skills/product-kit/README.md

@@ -0,0 +1,135 @@
+# ProductKit
+
+> Уровень 2. "Что именно строим и для кого?"
+
+---
+
+## Когда использовать
+
+- feasibility подтверждена в ResearchKit
+- нужно определить что именно строить
+- нужно понять как пользователь будет это использовать
+- нужно зафиксировать UX инварианты до архитектуры
+- нужно определить роадмап и приоритеты
+
+---
+
+## Ключевая идея
+
+UX инварианты определяются **до** архитектуры. Они ограничивают архитектурные решения так же жёстко как технические требования.
+
+Пример: если U1 = "CLI запускается с максимум 3 обязательными параметрами" зафиксирован здесь — архитектура с 60 параметрами станет блокером в ArchKit, а не открытием после реализации.
+
+---
+
+## Фазы
+
+### Phase 1: User Definition
+```
+QUESTIONS:
+  - Кто конкретно будет это использовать?
+  - Какую проблему они решают сейчас без этого инструмента?
+  - Что они знают / умеют заранее?
+  - В каком контексте используют: вручную, в скрипте, в CI?
+
+FORBIDDEN:
+  - думать о технической реализации
+  - выбирать стек
+```
+
+### Phase 2: UX Invariants
+```
+Формализуем что система гарантирует пользователю.
+Не "как выглядит" а "что обещает".
+
+EXAMPLES:
+  U1: новый пользователь достигает результата за N шагов
+  U2: без конфига работает разумный default
+  U3: ошибка всегда содержит что делать дальше
+  U4: операция X занимает не более Y секунд субъективно
+```
+
+### Phase 3: Roadmap
+```
+Фазы разработки с точки зрения продукта.
+Что входит в MVP, что в v1, что позже.
+
+BASIS: UX инварианты + assumptions из ResearchKit
+CONSTRAINTS: будут дополнены техническими из ArchKit
+```
+
+---
+
+## Артефакты
+
+### users.md
+```markdown
+# Users
+
+## Primary User
+PROFILE: кто это
+CONTEXT: как и где использует
+KNOWLEDGE: что знает заранее
+GOAL: чего хочет достичь
+HAPPY_PATH: типичный сценарий (80% случаев)
+
+## Edge Cases
+...
+```
+
+### ux_invariants.md
+```markdown
+# UX Invariants
+
+## U1: [название]
+STATEMENT: что система гарантирует пользователю
+RATIONALE: почему это важно
+VALIDATION: как проверить что инвариант соблюдён
+PRIORITY: must / should / could
+STATUS: active / suspended / rejected
+```
+
+### roadmap.md
+```markdown
+# Roadmap
+
+## MVP
+GOAL: минимум для первого реального использования
+UX_INVARIANTS: [какие инварианты покрывает]
+EXCLUDES: [что явно не входит]
+
+## V1
+...
+
+## Later
+...
+
+## Never (явный anti-scope)
+...
+```
+
+---
+
+## Переход к ArchKit
+
+**ALLOWED** когда:
+- все пользовательские сценарии описаны
+- UX инварианты зафиксированы для MVP
+- роадмап имеет явный anti-scope
+- нет open questions о том кто пользователь
+
+**BLOCKED** когда:
+- UX инварианты противоречат друг другу
+- happy path не определён
+
+---
+
+## Команды
+
+```
+/product init
+/product users
+/product ux-invariants
+/product roadmap
+/product status
+```

package/skills/product-kit/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: product-kit
+description: DevKit Level 2. Use after ResearchKit when developer needs to define who the user is, establish UX invariants, and set the roadmap before architecture. Triggers on phrases like "who is this for", "how will people use this", "what's the MVP", "user experience", or when ResearchKit handoff is complete.
+license: MIT
+metadata:
+  author: devkit
+  version: "1.0"
+  layer: "2-of-5"
+  prev: research-kit
+  next: arch-kit
+---
+
+# ProductKit — Level 2: "What exactly are we building and for whom?"
+
+You are operating in ProductKit phase. Your job is to define the user, establish UX invariants, and set roadmap priorities before any architecture decisions are made.
+
+## Your Role
+
+- Define who the user is and how they interact with the product
+- Establish UX invariants that constrain architecture
+- Prioritize ruthlessly: MVP vs later vs never
+- Do NOT recommend technical solutions
+- Do NOT write code or architecture
+
+## Critical Principle
+
+UX invariants are defined HERE, before ArchKit. They constrain architecture just as hard as technical requirements. If defined after, you get 60-parameter CLIs that formally work but are unusable.
+
+## Phases
+
+### Phase 1: User Definition
+Identify the real user. Ask:
+- Who specifically will use this? (developer, devops, manager, end user?)
+- What do they already know?
+- What context are they in when they use this? (manually, in CI, in a script?)
+- What is their happy path — the 80% case?
+
+### Phase 2: UX Invariants
+Formalize what the system PROMISES the user. Not how it looks — what it guarantees.
+
+Examples:
+- "New user reaches result in under N steps"
+- "No required config to get started — sensible defaults"
+- "Every error message tells you what to do next"
+- "Core operation completes in under N seconds"
+
+Each invariant gets: PRIORITY (must/should/could) and VALIDATION method.
+
+### Phase 3: Roadmap
+Define phases from user perspective:
+- MVP: minimum to be genuinely useful
+- V1: full intended experience
+- Later: good ideas for the future
+- Never (anti-scope): explicitly out of scope — prevents scope creep
+
+## Artifacts to Produce
+
+Read templates from:
+- [Users template](references/users.md)
+- [UX Invariants template](references/ux_invariants.md)
+- [Roadmap template](references/roadmap.md)
+
+Save artifacts to `.devkit/product/`.
+
+## Gate: When Can We Move to ArchKit?
+
+ALLOWED to proceed when:
+- Primary user and happy path defined
+- UX invariants established for MVP scope
+- Roadmap has explicit anti-scope
+- No contradictions between UX invariants
+
+BLOCKED when:
+- UX invariants contradict each other
+- Happy path unclear
+- "Who is the user" still open
+
+## Event Detection
+
+### Product Blocker (triggered during SpecKit or later)
+If developer says: "this is awkward to use", "too many parameters", "users won't understand this" — this is a UX invariant violation.
+
+Response:
+> "This looks like a UX invariant violation. Let me check product-kit artifacts.
+> [check ux_invariants.md]
+> This conflicts with [U_N]. Running ProductKit investigation before continuing."
+
+Open `product/investigations/PROD-XXX.md`, explore options, update ux_invariants.md, propagate changes to ArchKit.
+
+## Handoff
+
+When gate conditions are met:
+```
+PRODUCT COMPLETE
+USER: [one-line description]
+HAPPY PATH: [one sentence]
+UX INVARIANTS: N defined (M must, K should)
+MVP SCOPE: [summary]
+ANTI-SCOPE: [what we explicitly won't do]
+READY FOR: ArchKit
+```

package/skills/product-kit/references/roadmap.md

@@ -0,0 +1,16 @@
+# Roadmap Template
+
+## MVP
+GOAL: minimum to be genuinely useful to the primary user
+UX_INVARIANTS_COVERED: [U1, U2, ...]
+EXCLUDES: [what is explicitly out of MVP]
+
+## V1
+GOAL: full intended experience
+ADDS: [what MVP lacks]
+
+## Later
+[Good ideas that are not V1]
+
+## Never (Anti-Scope)
+[What we explicitly will NOT do — this prevents scope creep]

package/skills/product-kit/references/users.md

@@ -0,0 +1,14 @@
+# Users Template
+
+## Primary User
+PROFILE: who they are
+CONTEXT: when and where they use this
+KNOWLEDGE: what they know coming in
+GOAL: what they want to achieve
+HAPPY_PATH: the typical 80% scenario (one sentence)
+
+## Secondary Users
+[Other users and their scenarios if applicable]
+
+## Anti-Users
+[Who this is explicitly NOT for — prevents over-engineering]

package/skills/product-kit/references/ux_invariants.md

@@ -0,0 +1,8 @@
+# UX Invariants Template
+
+## U1: [name]
+STATEMENT: what the system promises the user
+RATIONALE: why this matters
+VALIDATION: how to verify the invariant holds
+PRIORITY: must / should / could
+STATUS: active / suspended / rejected

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
+```