@x0rium/devkit-cli 0.4.0 → 0.6.0

package/skills/arch-kit/README.md

@@ -0,0 +1,195 @@
+# ArchKit
+
+> Уровень 3. "Как это устроено технически?"
+
+---
+
+## Когда использовать
+
+- ProductKit завершён, UX инварианты зафиксированы
+- нужно выбрать архитектуру из нескольких вариантов
+- нужно формализовать технические инварианты
+- нужно верифицировать архитектуру до написания кода
+- нужно сгенерировать constitution.md для SpecKit
+
+---
+
+## Ключевая идея
+
+Архитектура описывается декларативно — не "как реализовать" а "что гарантировать". Верификация происходит до написания кода. SpecKit получает на вход не догадки а доказанное основание.
+
+---
+
+## Фазы
+
+### Phase 1: Discovery
+```
+QUESTIONS:
+  - Какие quality attributes критичны? (reliability, performance, security)
+  - Что хуже: потерять данные или показать устаревшие?
+  - Какая нагрузка? Какие пики?
+  - Один разработчик или команда?
+  - Где хостим?
+
+FORBIDDEN:
+  - предлагать конкретные технологии
+  - выбирать стек
+```
+
+### Phase 2: Architecture Variants
+```
+AI предлагает 2-3 варианта с явными трейдоффами.
+Каждый вариант — ADR с:
+  - что выбираем
+  - почему именно это
+  - от чего отказываемся и почему
+  - риски выбора
+
+FORBIDDEN:
+  - предлагать один вариант как единственный
+  - скрывать трейдоффы
+  - выбирать за разработчика
+```
+
+### Phase 3: Specification
+```
+Выбранная архитектура формализуется:
+  - компоненты и их контракты
+  - технические инварианты
+  - failure modes и как обрабатываются
+  - явные UNKNOWN которые блокируют разработку
+```
+
+### Phase 4: Verification
+```
+Adversarial scenarios — AI играет роль враждебной среды:
+  - что если этот сервис упал в момент транзакции?
+  - что если два запроса пришли одновременно?
+  - что если внешний сервис недоступен?
+
+Для каждого сценария архитектура даёт ответ.
+Если ответа нет — OPEN_QUESTION, блокирует переход.
+
+Уровни верификации:
+  L1: структурная (зависимости, интерфейсы, нет циклов)
+  L2: сценарная (adversarial scenarios, AI симуляция)
+  L3: формальная (TLA+/Alloy для критических инвариантов, опционально)
+```
+
+---
+
+## События которые обрабатывает ArchKit
+
+### RFC (Request for Change)
+Triggered: когда новые требования затрагивают инварианты
+```markdown
+# RFC-XXX: [название]
+
+TRIGGER: что изменилось
+AFFECTED_INVARIANTS: [список]
+AFFECTED_SPECS: [список]
+COST: оценка стоимости изменения
+
+OPTIONS:
+  A: ...
+  B: ...
+
+DECISION: [выбранный вариант]
+RATIONALE: почему
+STATUS: open / accepted / rejected
+```
+
+### Investigation (технический блокер)
+Triggered: баг в либе / провал бенчмарка / неожиданное ограничение
+```markdown
+# Investigation-XXX: [название]
+
+TRIGGER: что произошло
+AFFECTED_ASSUMPTION: [ADR который сломался]
+FINDING: что обнаружили
+
+OPTIONS:
+  A: ...
+  B: ...
+  C: ...
+
+DECISION: [выбранный вариант]
+INVARIANTS_AFFECTED: none / [список]
+SPECS_AFFECTED: [список]
+TECHNICAL_DEBT: none / [описание]
+STATUS: open / resolved
+```
+
+---
+
+## Артефакты
+
+### invariants.md
+```markdown
+# Technical Invariants
+
+## I1: [название]
+STATEMENT: что система гарантирует
+RATIONALE: почему это важно
+VERIFICATION: как доказать / проверить
+FAILURE_MODE: что происходит при нарушении
+STATUS: verified / assumed / unverified
+```
+
+### impact.md
+```markdown
+# Impact Map
+
+Карта зависимостей между архитектурными решениями.
+Используется для impact analysis при RFC и Investigation.
+
+## [Компонент / Решение]
+DEPENDS_ON: [список]
+DEPENDED_BY: [список]
+INVARIANTS: [список инвариантов которые затрагивает]
+```
+
+### decisions/
+```
+ADR-XXX.md      ← Architecture Decision Records
+RFC-XXX.md      ← Request for Change
+INV-XXX.md      ← Investigation
+```
+
+### constitution.md
+```
+Генерируется автоматически из invariants.md и decisions/.
+Это входной артефакт для SpecKit.
+НЕ редактировать вручную.
+```
+
+---
+
+## Переход к SpecKit
+
+**ALLOWED** когда:
+- все adversarial scenarios имеют ответ
+- нет OPEN_QUESTIONS без resolution
+- все инварианты имеют статус verified или assumed с явным риском
+- constitution.md сгенерирован
+
+**BLOCKED** когда:
+- есть OPEN_QUESTIONS блокирующего типа
+- инварианты противоречат UX инвариантам из ProductKit
+- не все failure modes описаны для критических путей
+
+---
+
+## Команды
+
+```
+/arch init
+/arch discovery
+/arch variants
+/arch specify
+/arch verify
+/arch rfc "описание изменения"
+/arch investigate "описание блокера"
+/arch generate-constitution
+/arch status
+```

package/skills/arch-kit/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: arch-kit
+description: DevKit Level 3. Use after ProductKit to explore architecture variants, establish technical invariants, verify system design, and generate constitution.md for SpecKit. Also triggers on architectural events during development: new requirements touching invariants (RFC), technical blockers like library bugs or benchmark failures (Investigation), or any change that affects system guarantees.
+license: MIT
+metadata:
+  author: devkit
+  version: "1.0"
+  layer: "3-of-5"
+  prev: product-kit
+  next: spec-kit
+---
+
+# ArchKit — Level 3: "How is this technically structured?"
+
+You are operating in ArchKit phase. Your job is to explore architecture options, establish technical invariants, verify the design, and produce a verified foundation for SpecKit.
+
+## Your Role
+
+- Explore multiple architecture variants with explicit tradeoffs
+- Establish technical invariants the system must guarantee
+- Run adversarial verification before any code is written
+- Generate constitution.md for SpecKit
+- Handle RFC and Investigation events during development
+
+## FORBIDDEN at This Phase
+
+- Writing implementation code
+- Choosing FOR the developer between variants
+- Hiding tradeoffs
+- Moving to SpecKit while OPEN_QUESTIONS exist
+
+## Phases
+
+### Phase 1: Discovery
+Before proposing any architecture, understand constraints. Ask:
+- What quality attributes matter most? (reliability, performance, simplicity, security)
+- What is worse: losing data or showing stale data?
+- Expected load and growth?
+- Team size?
+- Hosting constraints?
+
+Do NOT suggest technologies yet.
+
+### Phase 2: Architecture Variants
+Propose 2–3 variants. Each must include:
+- What we choose
+- Why this fits the constraints
+- What we give up (explicit tradeoffs)
+- Risks of this choice
+
+Never present one option as the only option.
+
+### Phase 3: Specification
+Formalize the chosen architecture:
+- Components and their contracts
+- Technical invariants (what the system guarantees)
+- Failure modes and how each is handled
+- Explicit OPEN_QUESTIONS that block progress
+
+### Phase 4: Adversarial Verification
+Play the role of a hostile environment. For every critical path, ask:
+- What if this service crashes mid-transaction?
+- What if two requests arrive simultaneously?
+- What if the external service is down for 2 hours?
+- What if the queue fills up?
+
+Each scenario must have an answer. No answer = OPEN_QUESTION = blocks SpecKit.
+
+Verification levels:
+- L1: Structural (no circular deps, all interfaces defined, no unknowns)
+- L2: Scenario (adversarial simulation, all failure modes handled)
+- L3: Formal (TLA+/Alloy for critical invariants — optional, for high-stakes systems)
+
+## Artifacts to Produce
+
+Read templates from:
+- [Invariants template](references/invariants.md)
+- [ADR template](references/adr.md)
+- [RFC template](references/rfc.md)
+- [Investigation template](references/investigation.md)
+- [Impact map template](references/impact.md)
+
+Save to `.devkit/arch/`.
+Generate `.devkit/arch/constitution.md` → copy to `.specify/constitution.md`.
+
+## Event Detection During SpecKit
+
+### RFC Trigger
+Developer says: "we also need X", "the client wants Y", "what if we add Z"
+
+Check invariants.md. If any invariant is touched:
+> "This touches invariant [I_N]. I'm stopping SpecKit and opening an RFC.
+> Here's what's affected and the cost of the change."
+
+Create `arch/decisions/RFC-XXX.md`. Run delta ArchKit cycle. Resume SpecKit only after RFC is resolved.
+
+### Investigation Trigger
+Developer says: "found a bug in lib X", "benchmark failed", "this doesn't work as expected", "library doesn't support Y"
+
+Check which ADR this breaks:
+> "This breaks assumption in [ADR-N]. Opening Investigation."
+
+Create `arch/decisions/INV-XXX.md`. Present options with costs. Developer decides. Update affected specs.
+
+## Gate: When Can We Move to SpecKit?
+
+ALLOWED when:
+- All adversarial scenarios have answers
+- No OPEN_QUESTIONS of blocking type remain
+- All invariants are `verified` or `assumed` with explicit risk noted
+- UX invariants from ProductKit are not violated
+- constitution.md generated
+
+BLOCKED when:
+- Any blocking OPEN_QUESTION is unresolved
+- Invariants conflict with UX invariants
+- Critical failure modes are unaddressed
+
+## Handoff
+
+```
+ARCHITECTURE VERIFIED
+VARIANT CHOSEN: [name and one-line rationale]
+INVARIANTS: N verified, M assumed (risks noted)
+OPEN_QUESTIONS: none / [list with owners]
+CONSTITUTION: generated at .specify/constitution.md
+READY FOR: SpecKit
+```

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

@@ -0,0 +1,25 @@
+# Architecture Decision Record Template
+
+## ADR-XXX: [title]
+DATE: 
+STATUS: proposed / accepted / superseded / rejected
+
+## Context
+What situation requires a decision?
+
+## Decision
+What we chose.
+
+## Rationale
+Why this over alternatives.
+
+## Alternatives Considered
+| Option | Why rejected |
+|--------|-------------|
+
+## Consequences
+What becomes easier. What becomes harder. What risks we accept.
+
+## Assumptions
+What must be true for this decision to hold.
+[These become targets for Investigation if they break]

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

@@ -0,0 +1,13 @@
+# Impact Map Template
+
+## [Component or Decision Name]
+DEPENDS_ON: [list of components/decisions it depends on]
+DEPENDED_BY: [list of components/decisions that depend on it]
+INVARIANTS: [invariants from invariants.md this touches]
+SPECS: [spec files that implement this]
+
+## How to Use
+When RFC or Investigation opens, query this map:
+"What depends on [changed thing]?" → everything in DEPENDED_BY
+"What does [changed thing] depend on?" → everything in DEPENDS_ON
+This gives the full blast radius before any decision is made.

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

@@ -0,0 +1,9 @@
+# Technical Invariants Template
+
+## I1: [name]
+STATEMENT: what the system guarantees
+RATIONALE: why this matters
+VERIFICATION: how to prove or test this
+FAILURE_MODE: what happens if violated
+STATUS: verified / assumed / unverified
+RISK_IF_ASSUMED: [fill if status is assumed]

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

@@ -0,0 +1,37 @@
+# Investigation Template — Technical Blocker
+
+## INV-XXX: [title]
+DATE:
+STATUS: open / resolved
+TRIGGERED_BY: [what broke — bug, benchmark, unexpected limitation]
+
+## Broken Assumption
+ASSUMPTION_IN: [ADR-N]
+ASSUMPTION_WAS: [what we believed]
+REALITY: [what we discovered]
+
+## Impact
+INVARIANTS_AT_RISK: [list]
+SPECS_AFFECTED: [list]
+
+## Options
+### Option A: [name]
+Description. Cost. Technical debt introduced (if any).
+
+### Option B: [name]
+Description. Cost. Technical debt introduced (if any).
+
+### Option C: [name]
+Description. Cost. Technical debt introduced (if any).
+
+## Decision
+CHOSEN: [option]
+RATIONALE: [why]
+DECIDED_BY: developer
+DATE_DECIDED:
+
+## Post-Decision Actions
+- [ ] Update affected ADR or create new one
+- [ ] Update invariants.md if changed
+- [ ] Update affected specs
+- [ ] Document any technical debt in debt.md

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