@x0rium/devkit-cli 0.5.0 → 0.6.0

package/skills/arch-kit/references/rfc.md

@@ -0,0 +1,36 @@
+# RFC Template — Request for Change
+
+## RFC-XXX: [title]
+DATE:
+STATUS: open / accepted / rejected / deferred
+TRIGGERED_BY: [what new requirement or information caused this]
+
+## Affected Invariants
+[List invariants from invariants.md that this touches]
+
+## Affected Specs
+[List specs from .specify/ that need revision]
+
+## Change Cost
+SPECS_TO_REVISE: N
+INVARIANTS_TO_CHANGE: M
+ESTIMATED_EFFORT: [rough estimate]
+
+## Options
+### Option A: [name]
+Description, pros, cons
+
+### Option B: [name]
+Description, pros, cons
+
+## Decision
+CHOSEN: [option]
+RATIONALE: [why]
+DECIDED_BY: developer
+DATE_DECIDED:
+
+## Post-Decision Actions
+- [ ] Update invariants.md
+- [ ] Regenerate constitution.md
+- [ ] Mark affected specs as NEEDS_REVISION
+- [ ] Resume SpecKit

package/skills/devkit-init/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: devkit-init
+description: Initialize DevKit in any project. Use when developer wants to start using DevKit methodology — whether starting fresh, adding to an existing project with code, or upgrading from spec-kit alone. Triggers on phrases like "init devkit", "setup devkit", "start devkit", "add devkit to project", "initialize devkit".
+license: MIT
+metadata:
+  author: devkit
+  version: "1.0"
+---
+
+# DevKit Init
+
+Initialize DevKit for any project state. Detect what exists, choose the right mode, set up what's needed.
+
+## Step 1: Detect Project State
+
+Check what exists in the current directory:
+
+```
+Check for:
+  .devkit/          → already initialized
+  .specify/         → spec-kit exists, no DevKit
+  source code files → brownfield (code without DevKit)
+  empty directory   → greenfield
+```
+
+Based on findings, choose mode:
+
+| State | Mode |
+|-------|------|
+| .devkit/ exists | Already initialized → show status |
+| .specify/ only | Upgrade mode → wrap spec-kit with DevKit |
+| Code, no .devkit/ | Brownfield mode → reconstruct from code |
+| Empty / no code | Greenfield mode → start fresh |
+
+Read the mode guide:
+- Greenfield: [greenfield.md](references/greenfield.md)
+- Brownfield: [brownfield.md](references/brownfield.md)
+- Upgrade from spec-kit: [upgrade.md](references/upgrade.md)
+
+## Step 2: Create .devkit/ Structure
+
+After determining mode, create the directory structure:
+
+```
+.devkit/
+  research/         ← ResearchKit artifacts
+  product/          ← ProductKit artifacts
+  arch/
+    decisions/      ← ADR, RFC, Investigation files
+  qa/
+    escalations/    ← QA escalation history
+```
+
+## Step 3: Install spec-kit if not present
+
+Check if `specify` CLI is available:
+
+```bash
+specify --version
+```
+
+If not found, output instructions:
+```
+spec-kit not found. Install with:
+  uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
+
+Then run: specify init . --ai claude
+```
+
+If found but `.specify/` doesn't exist:
+```bash
+specify init . --ai claude
+```
+
+## Step 4: Confirm and Show Next Step
+
+After init, tell developer what to do next based on mode:
+
+Greenfield:
+```
+DevKit initialized. 
+Start with: /research-kit
+Describe your idea and we'll explore feasibility together.
+```
+
+Brownfield:
+```
+DevKit initialized in brownfield mode.
+Reconstructed N invariants (review required).
+Next: review .devkit/arch/invariants.md and confirm or correct.
+Then: /arch-kit to fill gaps.
+```
+
+Upgrade:
+```
+DevKit initialized over existing spec-kit project.
+Reconstructed constitution into ArchKit artifacts.
+Next: review .devkit/arch/invariants.md
+```

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,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