@x0rium/devkit-cli 0.5.0 → 0.7.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,190 @@
+---
+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.1"
+  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.
+
+## Start
+
+```bash
+devkit status
+```
+
+Confirm you are in the arch phase. If not, check gate status of the previous phase.
+
+## 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
+
+Before creating an RFC for a change, check what it affects:
+```bash
+devkit impact "description of change"
+```
+
+To create an RFC:
+```bash
+devkit rfc "description"
+```
+
+To open an investigation:
+```bash
+devkit investigate "description"
+```
+
+### 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 constitution and sync:
+```bash
+devkit generate-constitution
+devkit sync
+```
+
+**After creating or updating artifacts, always run:**
+```bash
+devkit validate
+```
+Fix any errors before proceeding.
+
+## 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."
+
+```bash
+devkit impact "description of change"
+devkit rfc "description"
+```
+
+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."
+
+```bash
+devkit investigate "description"
+```
+
+Present options with costs. Developer decides. Update affected specs.
+
+After resolving, regenerate constitution if invariants changed:
+```bash
+devkit generate-constitution
+devkit sync
+devkit validate
+```
+
+## Gate: When Can We Move to SpecKit?
+
+```bash
+devkit gate
+```
+
+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
+
+When `devkit gate` shows ALLOWED:
+
+```bash
+devkit advance
+devkit status
+```
+
+Then generate summary:
+```
+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,74 @@
+---
+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.1"
+---
+
+# DevKit Init
+
+Initialize DevKit for any project state. Detect what exists, choose the right mode, set up what's needed.
+
+## Step 1: Run CLI Init
+
+Run the CLI command — it auto-detects project state and creates the structure:
+
+```bash
+devkit init
+```
+
+This will:
+- Detect project state (greenfield / brownfield / upgrade / already initialized)
+- Create `.devkit/` directory structure
+- Generate `STATUS.md` with correct mode and phase
+- Report what was created vs skipped
+
+If `.devkit/` already exists, it safely skips (idempotent).
+
+## Step 2: Verify State
+
+```bash
+devkit status
+```
+
+Review the output: mode, current phase, progress. This confirms init worked correctly.
+
+## Step 3: Install spec-kit if not present (optional)
+
+Check if `specify` CLI is available:
+
+```bash
+specify --version
+```
+
+If not found, inform the developer (do not block init):
+```
+Note: spec-kit not found. DevKit works independently.
+If you want SpecKit integration, install with:
+  uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
+Then run: specify init . --ai claude
+```
+
+Important: spec-kit installation is optional. DevKit init must succeed regardless of spec-kit availability.
+
+## Step 4: Mode-Specific Setup
+
+For **brownfield** mode, also follow [brownfield.md](references/brownfield.md) to reconstruct invariants from existing code.
+
+For **upgrade** mode, follow [upgrade.md](references/upgrade.md) to extract artifacts from existing constitution.
+
+For **greenfield**, no extra setup needed.
+
+## Step 5: Confirm and Show Next Step
+
+```bash
+devkit status
+```
+
+Tell developer what to do next based on detected mode:
+
+- Greenfield: "Start with: /research-kit — describe your idea"
+- Brownfield: "Review .devkit/arch/invariants.md, then /arch-kit to fill gaps"
+- Upgrade: "Review .devkit/arch/invariants.md extracted from constitution"