@x0rium/devkit-cli 0.6.0 → 0.7.0

package/skills/devkit-init/SKILL.md

@@ -4,54 +4,38 @@ description: Initialize DevKit in any project. Use when developer wants to start
 license: MIT
 metadata:
   author: devkit
-  version: "1.0"
+  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: Detect Project State
+## Step 1: Run CLI Init
 
-Check what exists in the current directory:
+Run the CLI command — it auto-detects project state and creates the structure:
 
+```bash
+devkit init
 ```
-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 |
+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
 
-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)
+If `.devkit/` already exists, it safely skips (idempotent).
 
-## Step 2: Create .devkit/ Structure
+## Step 2: Verify State
 
-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
+```bash
+devkit status
 ```
 
-## Step 3: Install spec-kit if not present
+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:
 
@@ -59,41 +43,32 @@ Check if `specify` CLI is available:
 specify --version
 ```
 
-If not found, output instructions:
+If not found, inform the developer (do not block init):
 ```
-spec-kit not found. Install with:
+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
 ```
 
-If found but `.specify/` doesn't exist:
-```bash
-specify init . --ai claude
-```
+Important: spec-kit installation is optional. DevKit init must succeed regardless of spec-kit availability.
 
-## Step 4: Confirm and Show Next Step
+## Step 4: Mode-Specific Setup
 
-After init, tell developer what to do next based on mode:
+For **brownfield** mode, also follow [brownfield.md](references/brownfield.md) to reconstruct invariants from existing code.
 
-Greenfield:
-```
-DevKit initialized. 
-Start with: /research-kit
-Describe your idea and we'll explore feasibility together.
-```
+For **upgrade** mode, follow [upgrade.md](references/upgrade.md) to extract artifacts from existing constitution.
 
-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.
-```
+For **greenfield**, no extra setup needed.
 
-Upgrade:
-```
-DevKit initialized over existing spec-kit project.
-Reconstructed constitution into ArchKit artifacts.
-Next: review .devkit/arch/invariants.md
+## 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"

package/skills/product-kit/SKILL.md

@@ -4,7 +4,7 @@ description: DevKit Level 2. Use after ResearchKit when developer needs to defin
 license: MIT
 metadata:
   author: devkit
-  version: "1.0"
+  version: "1.1"
   layer: "2-of-5"
   prev: research-kit
   next: arch-kit
@@ -14,6 +14,14 @@ metadata:
 
 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
@@ -62,8 +70,18 @@ Read templates from:
 
 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
@@ -85,11 +103,18 @@ Response:
 > [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.
+Review ux_invariants.md, explore options, update invariants if needed, propagate changes to ArchKit via `devkit rfc`.
 
 ## Handoff
 
-When gate conditions are met:
+When `devkit gate` shows ALLOWED:
+
+```bash
+devkit advance
+devkit status
+```
+
+Then generate summary:
 ```
 PRODUCT COMPLETE
 USER: [one-line description]

package/skills/qa-kit/SKILL.md

@@ -4,7 +4,7 @@ description: DevKit Level 5. Use after implementation to verify the system again
 license: MIT
 metadata:
   author: devkit
-  version: "1.0"
+  version: "1.1"
   layer: "5-of-5"
   prev: spec-kit
 ---
@@ -13,6 +13,14 @@ metadata:
 
 You are operating in QAKit phase. Your job is not just to find bugs — it is to verify the system against every level of decisions made in DevKit.
 
+## Start
+
+```bash
+devkit status
+```
+
+Confirm you are in the qa phase. If not, check gate status of the previous phase.
+
 ## Your Role
 
 - Generate test contracts from invariants (not from code)
@@ -44,9 +52,19 @@ For each invariant, generate a test contract:
 
 Save to `.devkit/qa/test_contracts.md`.
 
+**After creating contracts, validate:**
+```bash
+devkit validate
+```
+
 ### Phase 2: Coverage Analysis
 Map every invariant to its test contract.
 Identify uncovered invariants — these are explicit technical debt.
+
+```bash
+devkit coverage
+```
+
 Save to `.devkit/qa/coverage_map.md`.
 
 ### Phase 3: Assumption Validation
@@ -55,6 +73,10 @@ For each assumption, check whether reality confirmed or rejected it.
 Rejected assumptions → escalate to ResearchKit.
 Save findings to `.devkit/qa/assumption_checks.md`.
 
+```bash
+devkit validate
+```
+
 ## Artifacts to Produce
 
 Read templates from:
@@ -64,6 +86,12 @@ Read templates from:
 
 Save to `.devkit/qa/`.
 
+**After creating or updating artifacts, always run:**
+```bash
+devkit validate
+```
+Fix any errors before proceeding.
+
 ## Escalation Logic
 
 When a test fails or a problem is found:
@@ -87,7 +115,12 @@ Did a research assumption prove false in production?
 ```
 
 ### Step 3: Document the escalation
-Create `.devkit/qa/escalations/ESC-XXX.md`:
+
+```bash
+devkit escalate "description of failure"
+```
+
+This creates `.devkit/qa/escalations/ESC-XXX.md`. Fill in:
 - What was found
 - Which level it escalated to
 - What decision was triggered
@@ -95,6 +128,10 @@ Create `.devkit/qa/escalations/ESC-XXX.md`:
 
 ## Gate: Ready for Production?
 
+```bash
+devkit gate
+```
+
 ALLOWED when:
 - All BLOCKER test contracts pass
 - No open escalations of blocker severity
@@ -104,6 +141,11 @@ BLOCKED when:
 - Any BLOCKER contract fails
 - Open blocker-level escalation exists
 
+Check coverage threshold:
+```bash
+devkit coverage
+```
+
 ## Continuous QA
 
 QAKit is not a one-time gate. It runs:

package/skills/research-kit/SKILL.md

@@ -4,7 +4,7 @@ description: DevKit Level 1. Use when developer has a new idea and needs to expl
 license: MIT
 metadata:
   author: devkit
-  version: "1.0"
+  version: "1.1"
   layer: "1-of-5"
   next: product-kit
 ---
@@ -13,6 +13,10 @@ metadata:
 
 You are operating in ResearchKit phase. Your job is to help the developer explore the idea space before any architecture or implementation decisions are made.
 
+## Start
+
+Run `devkit status` to confirm you are in the research phase. If the project is not initialized, run `devkit init` first.
+
 ## Your Role
 
 - Ask questions, explore unknowns, map risks
@@ -54,8 +58,19 @@ Read templates from:
 
 Save artifacts to `.devkit/research/`.
 
+**After creating or updating artifacts, always run:**
+```bash
+devkit validate
+```
+Fix any errors before proceeding.
+
 ## Gate: When Can We Move to ProductKit?
 
+Check readiness with CLI:
+```bash
+devkit gate
+```
+
 ALLOWED to proceed when:
 - All HIGH RISK unknowns have a validation path
 - Feasibility is `yes` or `conditional` with known conditions
@@ -65,16 +80,16 @@ BLOCKED when:
 - Any BLOCKER unknown has no validation path
 - Feasibility is `no`
 
-## Event Detection
+## Handoff
 
-If developer mentions during ResearchKit:
-- New technical constraint → update feasibility.md
-- New analogue found → update market.md
-- Resolved unknown → update status in unknowns.md
+When `devkit gate` shows ALLOWED:
 
-## Handoff
+```bash
+devkit advance
+devkit status
+```
 
-When gate conditions are met, generate summary:
+Then generate summary:
 ```
 RESEARCH COMPLETE
 FEASIBILITY: yes/conditional/no
@@ -82,3 +97,10 @@ KEY UNKNOWNS RESOLVED: N
 REMAINING RISKS: [list with mitigations]
 READY FOR: ProductKit
 ```
+
+## Event Detection
+
+If developer mentions during ResearchKit:
+- New technical constraint → update feasibility.md → `devkit validate`
+- New analogue found → update market.md → `devkit validate`
+- Resolved unknown → update status in unknowns.md → `devkit validate`

package/skills/spec-kit/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: spec-kit
-description: DevKit Level 4. Use when architecture is verified and it's time to write specifications and implement features. Integrates with github/spec-kit workflow. Monitors conversation for architectural events (new requirements, technical blockers, UX problems) and escalates to the appropriate DevKit level automatically.
+description: DevKit Level 4. Activated when architecture is verified and constitution is synced. Delegates implementation to github/spec-kit (specify-cli) as the execution engine. DevKit provides event detection (RFC, Investigation, Product Blocker) that interrupts spec-kit workflow when invariants are touched. Triggers on phrases like "let's build", "implement", "start coding", "write the feature".
 license: MIT
 metadata:
   author: devkit
-  version: "1.0"
+  version: "2.0"
   layer: "4-of-5"
   prev: arch-kit
   next: qa-kit
@@ -12,32 +12,99 @@ metadata:
 
 # SpecKit — Level 4: "Build it."
 
-You are operating in SpecKit phase. Architecture is verified. You have a constitution.md. Now you build — using the github/spec-kit workflow as the implementation engine.
+You are operating in SpecKit phase. Architecture is verified. Constitution is synced to `.specify/memory/constitution.md`. Now you build — using **github/spec-kit** as the implementation engine.
+
+## Start
+
+```bash
+devkit status
+```
+
+Confirm you are in the spec phase. If not, check gate status of the previous phase.
+
+## Prerequisites
+
+Before any spec work, verify:
+
+1. Constitution exists and is synced:
+```bash
+ls .specify/memory/constitution.md
+```
+If missing:
+```bash
+devkit generate-constitution
+devkit sync
+```
+
+2. spec-kit is initialized:
+```bash
+ls .specify/scripts/
+```
+If missing:
+```bash
+specify init . --ai claude
+```
 
 ## Your Role
 
-- Follow github/spec-kit methodology for specification and implementation
+- Delegate specification and implementation to spec-kit `/speckit.*` commands
 - Monitor every developer message for escalation triggers
 - STOP and escalate before proceeding when triggers are detected
 - Never silently modify architecture within a spec
 
-## Constitution
+## spec-kit Workflow
 
-Before any spec work, confirm constitution.md exists at `.specify/constitution.md`.
-If it doesn't exist, stop and run: `/arch-kit generate-constitution`
+Execute these commands in order. Each is a slash command provided by spec-kit:
 
-The constitution comes from ArchKit — do not edit it manually. It contains the verified invariants that all specs must respect.
+### Step 1: Create Feature Specification
+```
+/speckit.specify <feature description>
+```
+Creates `.specify/specs/NNN-feature-name/spec.md` + git branch.
+Focuses on WHAT and WHY, not HOW. Max 3 `[NEEDS CLARIFICATION]` markers.
 
-## Standard Workflow (github/spec-kit)
+### Step 2: Resolve Ambiguities
+```
+/speckit.clarify
+```
+Structured ambiguity scan across 11 categories. Asks up to 5 questions per session.
+Updates spec.md with `## Clarifications` section.
 
+### Step 3: Technical Implementation Plan
 ```
-/constitution   — already generated by ArchKit, review only
-/specify        — describe the feature
-/clarify        — resolve ambiguities before planning
-/plan           — technical plan respecting invariants
-/tasks          — break into reviewable units
-/analyze        — check cross-spec consistency
-/implement      — generate code
+/speckit.plan <tech stack preferences>
+```
+Generates: `plan.md`, `research.md`, `data-model.md`, `contracts/`, `quickstart.md`.
+Performs constitution compliance check automatically.
+
+### Step 4: Task Breakdown
+```
+/speckit.tasks
+```
+Generates `tasks.md` with dependency ordering.
+Tasks tagged `[P]` for parallelizable, `[USn]` mapped to user stories.
+
+### Step 5: Cross-Artifact Consistency Analysis
+```
+/speckit.analyze
+```
+Read-only analysis: duplication, ambiguity, underspecification, constitution alignment, coverage gaps, inconsistency. Outputs severity-rated findings.
+
+### Step 6: Quality Checklists
+```
+/speckit.checklist <domain>
+```
+"Unit tests for English" — validates that requirements themselves are complete, clear, consistent, and measurable. Domains: security, ux, api, etc.
+
+### Step 7: Implement
+```
+/speckit.implement
+```
+Executes tasks phase-by-phase, marks completed in tasks.md, validates against spec.
+
+### Bonus: Export to GitHub Issues
+```
+/speckit.taskstoissues
 ```
 
 ## Invariant Guard
@@ -50,7 +117,12 @@ TECHNICAL: [I1, I3] from .devkit/arch/invariants.md
 UX: [U2] from .devkit/product/ux_invariants.md
 ```
 
-If implementation requires deviating from an invariant → STOP. Do not implement. Open RFC.
+If implementation requires deviating from an invariant — STOP. Do not implement. Open RFC:
+
+```bash
+devkit impact "description of deviation"
+devkit rfc "description"
+```
 
 ## Event Detection — CRITICAL
 
@@ -60,49 +132,71 @@ Monitor every developer message. Before continuing spec work, check for triggers
 Patterns: "we also need", "add support for", "client wants", "what about", "can we also"
 
 Action:
-> "This sounds like a new requirement. Let me check if it touches our invariants.
-> [read .devkit/arch/invariants.md]
-> This affects invariant [I_N]. I need to open an RFC before continuing.
-> Estimated impact: [N specs affected]. Proceed with RFC? /arch-kit rfc"
+> "This sounds like a new requirement. Let me check if it touches our invariants."
+
+```bash
+devkit impact "new requirement description"
+devkit rfc "description"
+```
 
 Do NOT continue spec work until RFC is resolved.
 
 ### Investigation Trigger — Technical Blocker
-Patterns: "bug in library", "this doesn't support", "benchmark shows", "unexpected behavior", "doesn't work as expected", "performance issue"
+Patterns: "bug in library", "this doesn't support", "benchmark shows", "unexpected behavior", "performance issue"
 
 Action:
-> "This breaks an architectural assumption. Let me identify which one.
-> [read .devkit/arch/decisions/ADR-*.md]
-> This breaks the assumption in [ADR-N]. Opening Investigation.
-> /arch-kit investigate"
+> "This breaks an architectural assumption. Opening Investigation."
+
+```bash
+devkit investigate "description of blocker"
+```
 
 Do NOT work around the blocker silently.
 
 ### Product Blocker Trigger — UX Problem
-Patterns: "this is hard to use", "too many parameters", "confusing", "users won't get this", "awkward interface"
+Patterns: "this is hard to use", "too many parameters", "confusing", "users won't get this"
 
 Action:
-> "This looks like a UX invariant issue. Let me check.
-> [read .devkit/product/ux_invariants.md]
-> This conflicts with [U_N]. Escalating to ProductKit investigation."
+> "This looks like a UX invariant issue."
 
-Do NOT continue with the current design.
+Check `.devkit/product/ux_invariants.md`. If violated — escalate to ProductKit.
 
 ### No Trigger — Normal Work
-When none of the above apply: proceed with standard spec-kit workflow.
+When none of the above apply: proceed with spec-kit workflow.
 
-## Spec Numbering
+**After creating or updating DevKit artifacts, always run:**
+```bash
+devkit validate
+```
+
+## Gate: When Can We Move to QAKit?
 
-Specs are numbered sequentially: spec_001, spec_002, etc.
-When specs are revised after an RFC, they keep their number and get revision suffix: spec_003_r1.
+```bash
+devkit gate
+```
 
-## Handoff to QAKit
+ALLOWED when:
+- At least one spec-kit feature implemented (`.specify/specs/NNN-*/`)
+- No open RFCs or Investigations
+
+BLOCKED when:
+- Open RFC or Investigation exists
+- No features in `.specify/specs/`
+
+## Handoff
+
+When `devkit gate` shows ALLOWED:
+
+```bash
+devkit advance
+devkit status
+```
 
-After implementation of a feature or milestone:
+Then generate summary:
 ```
 IMPLEMENTATION COMPLETE
-SPECS: [list]
-INVARIANTS COVERED: [list]
+SPECS: [list of .specify/specs/NNN-*/ directories]
+INVARIANTS COVERED: [list from spec invariant coverage sections]
 OPEN ITEMS: none / [list with owners]
 READY FOR: QAKit
 ```