@x0rium/devkit-cli 0.5.0 → 0.7.0

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

@@ -0,0 +1,147 @@
+# Brownfield Mode
+
+Code exists. No .devkit/. May or may not have .specify/.
+
+## Phase 1: Project Scan
+
+Read the codebase to understand what exists:
+
+```
+Scan for:
+  - Main language and framework
+  - Entry points (main files, index, app)
+  - Database / storage patterns
+  - External services and integrations
+  - Test files (understand what's already tested)
+  - README or docs (understand stated intent)
+  - Package files (dependencies reveal architecture)
+```
+
+Summarize findings before proceeding:
+```
+Found: [framework], [database], [key integrations]
+Size: ~N files, ~M lines
+Tests: yes/no, coverage unknown
+Docs: yes/no
+```
+
+## Phase 2: Invariant Extraction
+
+Read source code deeply. Look for patterns that reveal implicit invariants:
+
+**Signals of technical invariants:**
+- Transactions wrapping multiple operations → atomicity invariant
+- Locks, mutexes, SELECT FOR UPDATE → concurrency invariant
+- Retry logic → reliability invariant
+- Auth checks on every endpoint → security invariant
+- Validation before DB writes → data integrity invariant
+
+**Signals of broken invariants:**
+- TODO/FIXME/HACK comments
+- Exception swallowed silently
+- Missing error handling on critical paths
+- Race conditions (no locking where needed)
+
+For each extracted invariant, create entry with status `inferred`:
+
+```markdown
+## I1: [name]
+STATEMENT: what the system appears to guarantee
+STATUS: inferred
+CONFIDENCE: high / medium / low
+SOURCE: code-analysis
+EVIDENCE: [file:line that shows this]
+NEEDS_REVIEW: true
+```
+
+## Phase 3: Decision Archaeology
+
+Look for evidence of past architectural decisions:
+
+**Where to look:**
+- Git history and commit messages
+- PR descriptions (if accessible)
+- Comments explaining "why" not "what"
+- Unusual patterns that suggest a workaround
+- Dependencies that seem overengineered for the task
+
+For each discovered decision:
+
+```markdown
+## ADR-XXX: [inferred decision name]
+STATUS: inferred
+CONFIDENCE: high / medium / low
+EVIDENCE: [what in code suggests this]
+UNKNOWN: [what context is lost]
+NEEDS_REVIEW: true
+```
+
+## Phase 4: Gap Analysis
+
+What can't be reconstructed from code alone?
+
+```markdown
+# Gaps
+
+## UNKNOWN: [topic]
+QUESTION: what we can't determine from code
+WHY_MATTERS: impact on future development
+HOW_TO_RESOLVE: ask developer / check git history / accept unknown
+```
+
+Present gaps to developer and ask them to fill what they remember.
+
+## Phase 5: Produce Artifacts
+
+Save to `.devkit/arch/`:
+- `invariants.md` — all inferred invariants (status: inferred, needs_review: true)
+- `decisions/ADR-*.md` — all inferred decisions
+- `impact.md` — dependency map extracted from imports/calls
+
+## Status File
+
+Create `.devkit/STATUS.md`:
+
+```markdown
+# DevKit Status
+
+MODE: brownfield
+INITIALIZED: [date]
+CURRENT_PHASE: arch-review
+
+## Reconstruction Summary
+INVARIANTS_INFERRED: N
+DECISIONS_INFERRED: M  
+GAPS: K (see arch/gaps.md)
+
+## Required Actions Before Development
+- [ ] Review and confirm invariants.md
+- [ ] Fill gaps in arch/gaps.md
+- [ ] Run /arch-kit to verify and fill missing decisions
+
+## Phase Status
+- [~] ResearchKit (skipped — existing project)
+- [~] ProductKit (partially reconstructed)
+- [ ] ArchKit (review required)
+- [ ] SpecKit
+- [ ] QAKit
+```
+
+## Message to Developer
+
+```
+DevKit initialized in brownfield mode.
+
+Reconstructed from your codebase:
+  Invariants: N (all marked as 'inferred', need your review)
+  Decisions:  M (inferred from code patterns)
+  Gaps:       K unknowns that couldn't be reconstructed
+
+Next steps:
+1. Review .devkit/arch/invariants.md — confirm or correct each one
+2. Check .devkit/arch/gaps.md — fill what you remember
+3. Run /arch-kit to verify architecture and fill remaining gaps
+
+Important: 'inferred' invariants are AI's best guess from code.
+They may be wrong. Please review before trusting them.
+```

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,126 @@
+---
+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.1"
+  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.
+
+## Start
+
+```bash
+devkit status
+```
+
+Confirm you are in the product phase. If not, check gate status of the previous phase.
+
+## 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/`.
+
+**After creating or updating artifacts, always run:**
+```bash
+devkit validate
+```
+Fix any errors before proceeding.
+
+## Gate: When Can We Move to ArchKit?
+
+```bash
+devkit gate
+```
+
+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."
+
+Review ux_invariants.md, explore options, update invariants if needed, propagate changes to ArchKit via `devkit rfc`.
+
+## Handoff
+
+When `devkit gate` shows ALLOWED:
+
+```bash
+devkit advance
+devkit status
+```
+
+Then generate summary:
+```
+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