cokit-cli 1.2.7 → 1.4.0

package/docs/guide-next-steps-speckit-cokit-implementation.md

@@ -1,187 +0,0 @@
-# Next Steps Guide: Spec-Kit + Cokit Implementation
-
-**Created:** Feb 3, 2026
-**Status:** COMPLETE (v1.2.6 released with SpecKit integration)
-
----
-
-## Phase 1: Setup Spec-Kit (Week 1)
-
-### Step 1.1: Install GitHub Spec-Kit (Reference)
-```bash
-# Install spec-kit CLI for reference
-uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
-
-# Test it works
-specify --help
-```
-
-### Step 1.2: Study Spec-Kit Structure
-```bash
-# Clone for reference (don't modify)
-git clone https://github.com/github/spec-kit.git ~/reference/spec-kit
-
-# Key files to study:
-# - templates/claude/commands/*.md
-# - src/specify_cli/
-# - docs/
-```
-
-### Step 1.3: Create my-spec-kit Scaffold
-```bash
-cd /Users/admin/workspace/_me/cokit
-mkdir -p src/spec-kit/{cli,templates,validators}
-
-# Create initial files
-touch src/spec-kit/cli/init.js
-touch src/spec-kit/cli/constitution.js
-touch src/spec-kit/cli/specify.js
-touch src/spec-kit/templates/constitution.md
-touch src/spec-kit/templates/spec-feature.md
-touch src/spec-kit/templates/spec-api.md
-```
-
-### Step 1.4: Define Custom Templates
-
-**constitution.md** - Project governance:
-- Tech stack decisions
-- Code standards
-- Security requirements
-- Team conventions
-
-**spec-feature.md** - Feature specs:
-- User stories
-- Acceptance criteria
-- Technical constraints
-- Dependencies
-
----
-
-## Phase 2: Port ClaudeKit → Cokit (Week 2-3)
-
-### Step 2.1: Research Copilot CLI
-```bash
-# Check Copilot CLI docs
-# https://docs.github.com/en/copilot/using-github-copilot/using-github-copilot-in-the-command-line
-
-# Install GitHub CLI with Copilot extension
-gh extension install github/gh-copilot
-```
-
-### Step 2.2: Map Commands
-| ClaudeKit | Cokit (Copilot) | Notes |
-|-----------|-----------------|-------|
-| `/brainstorm` | `cokit brainstorm` | Adapt prompts |
-| `/plan` | `cokit plan` | Different context model |
-| `/cook` | `cokit cook` | Simplify for Copilot |
-| `/fix` | `cokit fix` | Direct port |
-| `/worktree` | `cokit worktree` | Git-only, no AI needed |
-
-### Step 2.3: Create Cokit CLI
-```bash
-# Scaffold already exists in /src
-# Enhance with new commands:
-
-# src/commands/
-#   brainstorm.js
-#   plan.js
-#   cook.js
-#   fix.js
-#   worktree.js
-```
-
----
-
-## Phase 3: Integrate Spec-Kit + Cokit (Week 3-4)
-
-### Step 3.1: Create Combo Workflows
-```
-cokit workflow enterprise  → speckit.constitution → speckit.specify → brainstorm → plan → cook
-cokit workflow quick       → brainstorm → plan:fast → cook
-cokit workflow fix         → fix --auto
-```
-
-### Step 3.2: Add to Instructions
-```bash
-# Update /instructions/ with combo workflows
-touch instructions/workflow-enterprise.md
-touch instructions/workflow-quick-md
-touch instructions/workflow-fix.md
-```
-
----
-
-## Phase 4: Team Training (Week 4)
-
-### Step 4.1: Create Training Materials
-- [ ] Quick start guide (5 min read)
-- [ ] Video demo (10 min)
-- [ ] Cheat sheet (1 page)
-- [ ] FAQ document
-
-### Step 4.2: Pilot Program
-- [ ] Select 2-3 volunteer devs
-- [ ] Run 1-week pilot
-- [ ] Collect feedback
-- [ ] Iterate
-
-### Step 4.3: Full Rollout
-- [ ] Team presentation
-- [ ] Pair programming sessions
-- [ ] Office hours for questions
-
----
-
-## Quick Reference: Commands After Setup
-
-```bash
-# Enterprise feature (with specs)
-cokit workflow enterprise "new payment system"
-
-# Quick feature (no specs)
-cokit workflow quick "add dark mode"
-
-# Bug fix
-cokit fix "error: undefined is not a function"
-
-# Parallel development
-cokit worktree "feature-x"
-```
-
----
-
-## Checklist
-
-### Week 1
-- [ ] Install spec-kit CLI (reference)
-- [ ] Clone spec-kit repo (study)
-- [ ] Create my-spec-kit scaffold
-- [ ] Write constitution template
-- [ ] Write spec-feature template
-
-### Week 2
-- [ ] Research Copilot CLI API
-- [ ] Map ClaudeKit → Cokit commands
-- [ ] Port `/brainstorm` command
-- [ ] Port `/plan` command
-
-### Week 3
-- [ ] Port `/cook` command
-- [ ] Port `/fix` command
-- [ ] Port `/worktree` command
-- [ ] Create combo workflows
-
-### Week 4
-- [ ] Write training materials
-- [ ] Run pilot program
-- [ ] Collect feedback
-- [ ] Full team rollout
-
----
-
-## Resources
-
-- [GitHub Spec-Kit](https://github.com/github/spec-kit)
-- [ClaudeKit Reference](https://github.com/duthaho/claudekit)
-- [Copilot CLI Docs](https://docs.github.com/en/copilot)
-- Research reports: `pocketquant/plans/reports/brainstorm-260203-*`

package/prompts/ck-spec-analyze.prompt.md

@@ -1,201 +0,0 @@
----
-agent: 'agent'
-description: 'Cross-artifact consistency and quality analysis across spec, plan, and tasks'
----
-
-## User Input
-
-```text
-${input}
-```
-
-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 `/ck-spec-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 (`constitution.md` at project root) 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 `/ck-spec-analyze`.
-
-## Execution Steps
-
-### 1. Initialize Analysis Context
-
-Run `{SCRIPT}` 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 (master file)
-- TASKS_DIR = FEATURE_DIR/tasks/ (phase files, if hybrid structure)
-
-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 (and tasks/ if hybrid structure):**
-
-- Task IDs
-- Descriptions
-- Phase grouping (from master file or individual phase files)
-- Parallel markers [P]
-- Story labels [USx]
-- Referenced file paths
-- Phase dependencies and status
-
-**From constitution:**
-
-- Load `constitution.md` (project root) 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)
-
-### 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 `/ck-spec-implement`
-- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
-- Provide explicit command suggestions: e.g., "Run /ck-spec-specify with refinement", "Run /ck-spec-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
-
-{ARGS}
-
----
-
-## Suggested Next Steps
-
-| Command | Description | When to Use |
-|---------|-------------|-------------|
-| `/ck-spec-implement` | Start implementation | Analysis passed, no critical issues |
-| `/ck-spec-clarify` | Clarify requirements | Analysis found ambiguities in spec |
-| `/ck-spec-tasks` | Regenerate tasks | Task coverage gaps identified |
-| `/ck-fix` | Fix issues found in analysis | Code-level bugs identified |
-
-**Workflow:** `/ck-spec-analyze` → fix issues → `/ck-spec-implement`