@x0rium/devkit-cli 0.6.0 → 0.8.0

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

package/skills/spec-kit/commands/speckit.analyze.md

@@ -0,0 +1,201 @@
+---
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.md`.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements
+- Non-Functional Requirements
+- User Stories
+- Edge Cases (if present)
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Phases
+- Technical constraints
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `.specify/memory/constitution.md` for principle validation
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Non-functional requirements not reflected in tasks (e.g., performance, security)
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+<!-- DEVKIT:START:coverage-pass -->
+#### G. DevKit Invariant Coverage
+
+- Run `devkit coverage` and capture the output
+- For each invariant (technical I1-I8, UX U1-U6):
+  - Check if the invariant has at least one test covering it
+  - Flag uncovered invariants as findings with severity based on invariant type:
+    - Technical invariant uncovered → HIGH
+    - UX invariant uncovered → MEDIUM
+- Add to Coverage Summary Table:
+  - Row per invariant: ID, Name, Covered (yes/no), Test IDs
+- Add "DevKit Invariant Coverage" section to the analysis report with:
+  - Coverage percentage
+  - Uncovered invariants list
+  - Recommendation: `devkit coverage` for detailed map
+<!-- DEVKIT:END:coverage-pass -->
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+## Specification Analysis Report
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+**Coverage Summary Table:**
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|-----------------|-----------|----------|-------|
+
+**Constitution Alignment Issues:** (if any)
+
+**Unmapped Tasks:** (if any)
+
+**Metrics:**
+
+- Total Requirements
+- Total Tasks
+- Coverage % (requirements with >=1 task)
+- Ambiguity Count
+- Duplication Count
+- Critical Issues Count
+
+### 7. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `/speckit.implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
+
+### 8. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+## Context
+
+$ARGUMENTS