@x0rium/devkit-cli 0.7.0 → 0.8.0

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

@@ -0,0 +1,153 @@
+---
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+handoffs:
+  - label: Analyze For Consistency
+    agent: speckit.analyze
+    prompt: Run a project analysis for consistency
+    send: true
+  - label: Implement Project
+    agent: speckit.implement
+    prompt: Start the implementation in phases
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. 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 design documents**: Read from FEATURE_DIR:
+   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
+   - **Optional**: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios)
+   - Note: Not all projects have all documents. Generate tasks based on what's available.
+
+3. **Execute task generation workflow**:
+   - Load plan.md and extract tech stack, libraries, project structure
+   - Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
+   - If data-model.md exists: Extract entities and map to user stories
+   - If contracts/ exists: Map endpoints to user stories
+   - If research.md exists: Extract decisions for setup tasks
+   - Generate tasks organized by user story (see Task Generation Rules below)
+   - Generate dependency graph showing user story completion order
+   - Create parallel execution examples per user story
+   - Validate task completeness (each user story has all needed tasks, independently testable)
+
+4. **Generate tasks.md**: Use `.specify/templates/tasks-template.md` as structure, fill with:
+   - Correct feature name from plan.md
+   - Phase 1: Setup tasks (project initialization)
+   - Phase 2: Foundational tasks (blocking prerequisites for all user stories)
+   - Phase 3+: One phase per user story (in priority order from spec.md)
+   - Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
+   - Final Phase: Polish & cross-cutting concerns
+   - All tasks must follow the strict checklist format (see Task Generation Rules below)
+   - Clear file paths for each task
+   - Dependencies section showing story completion order
+   - Parallel execution examples per story
+   - Implementation strategy section (MVP first, incremental delivery)
+
+5. **Report**: Output path to generated tasks.md and summary:
+   - Total task count
+   - Task count per user story
+   - Parallel opportunities identified
+   - Independent test criteria for each story
+   - Suggested MVP scope (typically just User Story 1)
+   - Format validation: Confirm ALL tasks follow the checklist format (checkbox, ID, labels, file paths)
+
+<!-- DEVKIT:START:validate-checkpoints -->
+6. **DevKit Validation Checkpoints** — add validation tasks between phases:
+
+   After generating the task list, insert `devkit validate` checkpoint tasks at phase boundaries:
+
+   - After Setup phase: `- [ ] [T0XX] Run devkit validate to verify project state`
+   - After Foundational phase: `- [ ] [T0XX] Run devkit validate to verify foundational integrity`
+   - Before Final Phase: `- [ ] [T0XX] Run devkit coverage to check invariant test coverage`
+
+   These checkpoints ensure that DevKit invariants remain satisfied throughout implementation. Assign sequential task IDs that fit within the existing numbering scheme.
+
+   Also include in the report:
+   - Number of DevKit validation checkpoints added
+   - Reminder: `devkit coverage` shows invariant ↔ test coverage map
+<!-- DEVKIT:END:validate-checkpoints -->
+
+Context for task generation: $ARGUMENTS
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
+
+## Task Generation Rules
+
+**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
+
+**Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.
+
+### Checklist Format (REQUIRED)
+
+Every task MUST strictly follow this format:
+
+```text
+- [ ] [TaskID] [P?] [Story?] Description with file path
+```
+
+**Format Components**:
+
+1. **Checkbox**: ALWAYS start with `- [ ]` (markdown checkbox)
+2. **Task ID**: Sequential number (T001, T002, T003...) in execution order
+3. **[P] marker**: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
+4. **[Story] label**: REQUIRED for user story phase tasks only
+   - Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
+   - Setup phase: NO story label
+   - Foundational phase: NO story label
+   - User Story phases: MUST have story label
+   - Polish phase: NO story label
+5. **Description**: Clear action with exact file path
+
+**Examples**:
+
+- CORRECT: `- [ ] T001 Create project structure per implementation plan`
+- CORRECT: `- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py`
+- CORRECT: `- [ ] T012 [P] [US1] Create User model in src/models/user.py`
+- CORRECT: `- [ ] T014 [US1] Implement UserService in src/services/user_service.py`
+- WRONG: `- [ ] Create User model` (missing ID and Story label)
+- WRONG: `T001 [US1] Create model` (missing checkbox)
+- WRONG: `- [ ] [US1] Create User model` (missing Task ID)
+- WRONG: `- [ ] T001 [US1] Create model` (missing file path)
+
+### Task Organization
+
+1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION:
+   - Each user story (P1, P2, P3...) gets its own phase
+   - Map all related components to their story:
+     - Models needed for that story
+     - Services needed for that story
+     - Endpoints/UI needed for that story
+     - If tests requested: Tests specific to that story
+   - Mark story dependencies (most stories should be independent)
+
+2. **From Contracts**:
+   - Map each contract/endpoint → to the user story it serves
+   - If tests requested: Each contract → contract test task [P] before implementation in that story's phase
+
+3. **From Data Model**:
+   - Map each entity to the user story(ies) that need it
+   - If entity serves multiple stories: Put in earliest story or Setup phase
+   - Relationships → service layer tasks in appropriate story phase
+
+4. **From Setup/Infrastructure**:
+   - Shared infrastructure → Setup phase (Phase 1)
+   - Foundational/blocking tasks → Foundational phase (Phase 2)
+   - Story-specific setup → within that story's phase
+
+### Phase Structure
+
+- **Phase 1**: Setup (project initialization)
+- **Phase 2**: Foundational (blocking prerequisites - MUST complete before user stories)
+- **Phase 3+**: User Stories in priority order (P1, P2, P3...)
+  - Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
+  - Each phase should be a complete, independently testable increment
+- **Final Phase**: Polish & Cross-Cutting Concerns

package/skills/spec-kit/hooks/analyze.coverage-pass.md

@@ -0,0 +1,14 @@
+#### 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

package/skills/spec-kit/hooks/checklist.invariant-category.md

@@ -0,0 +1,7 @@
+   **DevKit Invariant Coverage** (mandatory category):
+   - "Are all technical invariants (from `.devkit/arch/invariants.md`) referenced in the spec? [Traceability]"
+   - "Are all UX invariants (from `.devkit/product/ux_invariants.md`) addressed in requirements? [Coverage]"
+   - "Is the Invariant Coverage section present and up-to-date? [Completeness]"
+   - "Are invariant relations (TOUCHES/DEPENDS) justified with notes? [Clarity]"
+   - "Has `devkit impact` been run for this feature? [Process]"
+   - "Are there any HIGH/CRITICAL risk invariants that need RFC? [Risk]"

package/skills/spec-kit/hooks/clarify.invariant-check.md

@@ -0,0 +1,15 @@
+9. **DevKit Invariant Check** — after all clarifications are integrated:
+
+   a. **Check if clarifications touch invariants**: If any clarification answer modifies or constrains behavior related to project invariants (from `.devkit/arch/invariants.md` or `.devkit/product/ux_invariants.md`), flag it:
+
+      ```
+      ⚠️ Clarification Q[N] touches invariant [ID]: [invariant name]
+      Consider: devkit rfc "<description of the change>"
+      ```
+
+   b. **Run validation** to ensure spec still aligns with DevKit artifacts:
+      ```bash
+      devkit validate
+      ```
+
+   c. Include invariant impact in the completion report if any invariants were touched.

package/skills/spec-kit/hooks/implement.phase-guards.md

@@ -0,0 +1,25 @@
+10. **DevKit Phase Guards** — integrate DevKit checks into implementation:
+
+   a. **Before architecture-impacting tasks**: Run impact analysis:
+      ```bash
+      devkit impact "<task description>"
+      ```
+      If risk is HIGH, pause and suggest `devkit rfc` before proceeding.
+
+   b. **After completing each phase**: Run validation:
+      ```bash
+      devkit validate
+      ```
+      If validation fails, halt phase progression and report the issues.
+
+   c. **On implementation failure**: If a task fails in a way that suggests a broken assumption:
+      ```bash
+      devkit investigate "<description of the failure and broken assumption>"
+      ```
+      This creates an Investigation record linking back to relevant ADRs.
+
+   d. **After final phase**: Run full coverage check:
+      ```bash
+      devkit coverage
+      ```
+      Include coverage summary in the implementation completion report.

package/skills/spec-kit/hooks/plan.constitution-precheck.md

@@ -0,0 +1,7 @@
+**DevKit Pre-Planning Validation**:
+
+Before starting the planning workflow, run:
+```bash
+devkit validate
+```
+If validation fails with errors, resolve them before proceeding. Cross-reference the plan against invariants I1-I8 (technical) and U1-U6 (UX) from `.devkit/arch/invariants.md` and `.devkit/product/ux_invariants.md`. Any architectural decision in the plan that conflicts with an invariant must be justified or trigger `devkit rfc`.

package/skills/spec-kit/hooks/plan.plan-postcheck.md

@@ -0,0 +1,17 @@
+**DevKit Post-Planning Validation**:
+
+After plan generation is complete:
+
+1. **Run validation**:
+   ```bash
+   devkit validate
+   ```
+
+2. **Run impact analysis** on the plan:
+   ```bash
+   devkit impact "<feature name>: plan generated with tech stack <key technologies>"
+   ```
+
+3. If risk is HIGH, recommend running `devkit rfc` before proceeding to task generation.
+
+4. Include DevKit validation status and impact risk level in the plan completion report.

package/skills/spec-kit/hooks/specify.invariant-guard.md

@@ -0,0 +1,37 @@
+7. **DevKit Invariant Guard** — after the spec is written and validated:
+
+   a. **Load invariants**: Read `.devkit/arch/invariants.md` and `.devkit/product/ux_invariants.md` (if they exist).
+
+   b. **Map feature to invariants**: For each invariant (I1-I8, U1-U6 or whatever IDs exist), determine whether this feature TOUCHES, DEPENDS ON, or is UNRELATED to that invariant.
+
+   c. **Append `## Invariant Coverage` section** to the spec file (before any closing notes):
+
+      ```markdown
+      ## Invariant Coverage
+
+      > Auto-generated by DevKit. Maps this spec to project invariants.
+
+      **Technical invariants** (from `.devkit/arch/invariants.md`):
+      | ID | Name | Relation | Notes |
+      |----|------|----------|-------|
+      | I1 | ... | TOUCHES / DEPENDS / — | ... |
+
+      **UX invariants** (from `.devkit/product/ux_invariants.md`):
+      | ID | Name | Relation | Notes |
+      |----|------|----------|-------|
+      | U1 | ... | TOUCHES / DEPENDS / — | ... |
+      ```
+
+      Only include rows where Relation is TOUCHES or DEPENDS (skip unrelated).
+
+   d. **Run impact analysis**:
+      ```bash
+      devkit impact "<feature short name>: touches <list of touched invariant IDs>"
+      ```
+      - If risk is HIGH or CRITICAL: **WARN** the user before proceeding. Suggest running `devkit rfc` if the feature may need to deviate from an invariant.
+      - If risk is LOW or MEDIUM: note it in the report and proceed.
+
+   e. **Run validation**:
+      ```bash
+      devkit validate
+      ```

package/skills/spec-kit/hooks/tasks.validate-checkpoints.md

@@ -0,0 +1,13 @@
+6. **DevKit Validation Checkpoints** — add validation tasks between phases:
+
+   After generating the task list, insert `devkit validate` checkpoint tasks at phase boundaries:
+
+   - After Setup phase: `- [ ] [T0XX] Run devkit validate to verify project state`
+   - After Foundational phase: `- [ ] [T0XX] Run devkit validate to verify foundational integrity`
+   - Before Final Phase: `- [ ] [T0XX] Run devkit coverage to check invariant test coverage`
+
+   These checkpoints ensure that DevKit invariants remain satisfied throughout implementation. Assign sequential task IDs that fit within the existing numbering scheme.
+
+   Also include in the report:
+   - Number of DevKit validation checkpoints added
+   - Reminder: `devkit coverage` shows invariant ↔ test coverage map