cokit-cli 1.0.9 → 1.2.0

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

@@ -0,0 +1,270 @@
+---
+agent: 'agent'
+description: 'Create or update the feature specification from a natural language description'
+handoffs:
+  - label: Build Technical Plan
+    agent: ck.spec.plan
+    prompt: Create a plan for the spec. I am building with...
+  - label: Clarify Spec Requirements
+    agent: ck.spec.clarify
+    prompt: Clarify specification requirements
+    send: true
+scripts:
+  sh: 'spec-kit/scripts/bash/create-new-feature.sh --json "{ARGS}"'
+  ps: 'spec-kit/scripts/powershell/create-new-feature.ps1 -Json "{ARGS}"'
+---
+
+## User Input
+
+```text
+${input}
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+The text the user typed after `/ck.spec.specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `{ARGS}` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
+
+Given that feature description, do this:
+
+1. **Generate a concise short name** (2-4 words) for the branch:
+   - Analyze the feature description and extract the most meaningful keywords
+   - Create a 2-4 word short name that captures the essence of the feature
+   - Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
+   - Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
+   - Keep it concise but descriptive enough to understand the feature at a glance
+   - Examples:
+     - "I want to add user authentication" → "user-auth"
+     - "Implement OAuth2 integration for the API" → "oauth2-api-integration"
+     - "Create a dashboard for analytics" → "analytics-dashboard"
+     - "Fix payment processing timeout bug" → "fix-payment-timeout"
+
+2. **Check for existing specs and determine feature number**:
+
+   a. First, check if this is a git repository (optional - skip git steps if not):
+      ```bash
+      git rev-parse --git-dir 2>/dev/null
+      ```
+
+   b. Find the highest feature number from available sources:
+      - **Always check**: Specs directories matching `specs/[0-9]+-<short-name>`
+      - **If git repo**: Local branches matching `^[* ]*[0-9]+-<short-name>$`
+      - **If git repo with remote**: Remote branches (run `git fetch --all --prune` first, then check `git ls-remote --heads origin`)
+
+   c. Determine the next available number:
+      - Extract all numbers from available sources
+      - Find the highest number N
+      - Use N+1 for the new feature number (start with 1 if none found)
+
+   d. Run the script `{SCRIPT}` with the calculated number and short-name:
+      - Pass `--number N+1` and `--short-name "your-short-name"` along with the feature description
+      - Bash example: `{SCRIPT} --json --number 5 --short-name "user-auth" "Add user authentication"`
+      - PowerShell example: `{SCRIPT} -Json -Number 5 -ShortName "user-auth" "Add user authentication"`
+
+   **IMPORTANT**:
+   - Specs directories are the PRIMARY source - always check these
+   - Git operations are OPTIONAL - only run if the project is a git repository
+   - If no existing specs found with this short-name, start with number 1
+   - You must only ever run this script once per feature
+   - The JSON output will contain FEATURE_DIR and SPEC_FILE paths
+   - 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")
+
+3. Load `spec-kit/templates/spec-template.md` to understand required sections.
+
+4. Follow this execution flow:
+
+    1. Parse user description from Input
+       If empty: ERROR "No feature description provided"
+    2. Extract key concepts from description
+       Identify: actors, actions, data, constraints
+    3. For unclear aspects:
+       - Make informed guesses based on context and industry standards
+       - Only mark with [NEEDS CLARIFICATION: specific question] if:
+         - The choice significantly impacts feature scope or user experience
+         - Multiple reasonable interpretations exist with different implications
+         - No reasonable default exists
+       - **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total**
+       - Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
+    4. Fill User Scenarios & Testing section
+       If no clear user flow: ERROR "Cannot determine user scenarios"
+    5. Generate Functional Requirements
+       Each requirement must be testable
+       Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
+    6. Define Success Criteria
+       Create measurable, technology-agnostic outcomes
+       Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion)
+       Each criterion must be verifiable without implementation details
+    7. Identify Key Entities (if data involved)
+    8. Return: SUCCESS (spec ready for planning)
+
+5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+
+6. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
+
+   a. **Create Spec Quality Checklist**: Generate a checklist file at `FEATURE_DIR/checklists/requirements.md` using the checklist template structure with these validation items:
+
+      ```markdown
+      # Specification Quality Checklist: [FEATURE NAME]
+      
+      **Purpose**: Validate specification completeness and quality before proceeding to planning
+      **Created**: [DATE]
+      **Feature**: [Link to spec.md]
+      
+      ## Content Quality
+      
+      - [ ] No implementation details (languages, frameworks, APIs)
+      - [ ] Focused on user value and business needs
+      - [ ] Written for non-technical stakeholders
+      - [ ] All mandatory sections completed
+      
+      ## Requirement Completeness
+      
+      - [ ] No [NEEDS CLARIFICATION] markers remain
+      - [ ] Requirements are testable and unambiguous
+      - [ ] Success criteria are measurable
+      - [ ] Success criteria are technology-agnostic (no implementation details)
+      - [ ] All acceptance scenarios are defined
+      - [ ] Edge cases are identified
+      - [ ] Scope is clearly bounded
+      - [ ] Dependencies and assumptions identified
+      
+      ## Feature Readiness
+      
+      - [ ] All functional requirements have clear acceptance criteria
+      - [ ] User scenarios cover primary flows
+      - [ ] Feature meets measurable outcomes defined in Success Criteria
+      - [ ] No implementation details leak into specification
+      
+      ## Notes
+      
+      - Items marked incomplete require spec updates before `/ck.spec.clarify` or `/ck.spec.plan`
+      ```
+
+   b. **Run Validation Check**: Review the spec against each checklist item:
+      - For each item, determine if it passes or fails
+      - Document specific issues found (quote relevant spec sections)
+
+   c. **Handle Validation Results**:
+
+      - **If all items pass**: Mark checklist complete and proceed to step 6
+
+      - **If items fail (excluding [NEEDS CLARIFICATION])**:
+        1. List the failing items and specific issues
+        2. Update the spec to address each issue
+        3. Re-run validation until all items pass (max 3 iterations)
+        4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user
+
+      - **If [NEEDS CLARIFICATION] markers remain**:
+        1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec
+        2. **LIMIT CHECK**: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest
+        3. For each clarification needed (max 3), present options to user in this format:
+
+           ```markdown
+           ## Question [N]: [Topic]
+           
+           **Context**: [Quote relevant spec section]
+           
+           **What we need to know**: [Specific question from NEEDS CLARIFICATION marker]
+           
+           **Suggested Answers**:
+           
+           | Option | Answer | Implications |
+           |--------|--------|--------------|
+           | A      | [First suggested answer] | [What this means for the feature] |
+           | B      | [Second suggested answer] | [What this means for the feature] |
+           | C      | [Third suggested answer] | [What this means for the feature] |
+           | Custom | Provide your own answer | [Explain how to provide custom input] |
+           
+           **Your choice**: _[Wait for user response]_
+           ```
+
+        4. **CRITICAL - Table Formatting**: Ensure markdown tables are properly formatted:
+           - Use consistent spacing with pipes aligned
+           - Each cell should have spaces around content: `| Content |` not `|Content|`
+           - Header separator must have at least 3 dashes: `|--------|`
+           - Test that the table renders correctly in markdown preview
+        5. Number questions sequentially (Q1, Q2, Q3 - max 3 total)
+        6. Present all questions together before waiting for responses
+        7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
+        8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
+        9. Re-run validation after all clarifications are resolved
+
+   d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
+
+7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/ck.spec.clarify` or `/ck.spec.plan`).
+
+**NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.
+
+## General Guidelines
+
+## Quick Guidelines
+
+- Focus on **WHAT** users need and **WHY**.
+- Avoid HOW to implement (no tech stack, APIs, code structure).
+- Written for business stakeholders, not developers.
+- DO NOT create any checklists that are embedded in the spec. That will be a separate command.
+
+### Section Requirements
+
+- **Mandatory sections**: Must be completed for every feature
+- **Optional sections**: Include only when relevant to the feature
+- When a section doesn't apply, remove it entirely (don't leave as "N/A")
+
+### For AI Generation
+
+When creating this spec from a user prompt:
+
+1. **Make informed guesses**: Use context, industry standards, and common patterns to fill gaps
+2. **Document assumptions**: Record reasonable defaults in the Assumptions section
+3. **Limit clarifications**: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
+   - Significantly impact feature scope or user experience
+   - Have multiple reasonable interpretations with different implications
+   - Lack any reasonable default
+4. **Prioritize clarifications**: scope > security/privacy > user experience > technical details
+5. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
+6. **Common areas needing clarification** (only if no reasonable default exists):
+   - Feature scope and boundaries (include/exclude specific use cases)
+   - User types and permissions (if multiple conflicting interpretations possible)
+   - Security/compliance requirements (when legally/financially significant)
+
+**Examples of reasonable defaults** (don't ask about these):
+
+- Data retention: Industry-standard practices for the domain
+- Performance targets: Standard web/mobile app expectations unless specified
+- Error handling: User-friendly messages with appropriate fallbacks
+- Authentication method: Standard session-based or OAuth2 for web apps
+- Integration patterns: RESTful APIs unless specified otherwise
+
+### Success Criteria Guidelines
+
+Success criteria must be:
+
+1. **Measurable**: Include specific metrics (time, percentage, count, rate)
+2. **Technology-agnostic**: No mention of frameworks, languages, databases, or tools
+3. **User-focused**: Describe outcomes from user/business perspective, not system internals
+4. **Verifiable**: Can be tested/validated without knowing implementation details
+
+**Good examples**:
+
+- "Users can complete checkout in under 3 minutes"
+- "System supports 10,000 concurrent users"
+- "95% of searches return results in under 1 second"
+- "Task completion rate improves by 40%"
+
+**Bad examples** (implementation-focused):
+
+- "API response time is under 200ms" (too technical, use "Users see results instantly")
+- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
+- "React components render efficiently" (framework-specific)
+- "Redis cache hit rate above 80%" (technology-specific)
+
+---
+
+## Suggested Next Steps
+
+| Command | Description | When to Use |
+|---------|-------------|-------------|
+| `/ck.spec.clarify` | Ask clarification questions | Spec has [NEEDS CLARIFICATION] markers or vague requirements |
+| `/ck.spec.plan` | Generate implementation plan | Spec is complete and ready for technical planning |
+| `/ck.spec.constitution` | Create project principles | Need to establish non-negotiable rules before planning |

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

@@ -0,0 +1,193 @@
+---
+agent: 'agent'
+description: 'Generate actionable, dependency-ordered tasks.md from design artifacts'
+handoffs:
+  - label: Analyze For Consistency
+    agent: ck.spec.analyze
+    prompt: Run a project analysis for consistency
+    send: true
+  - label: Implement Project
+    agent: ck.spec.implement
+    prompt: Start the implementation in phases
+    send: true
+scripts:
+  sh: spec-kit/scripts/bash/check-prerequisites.sh --json
+  ps: spec-kit/scripts/powershell/check-prerequisites.ps1 -Json
+---
+
+## User Input
+
+```text
+${input}
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. **Setup**: Run `{SCRIPT}` 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 hybrid task structure**: Create master file + individual phase files:
+
+   **4a. Create phase files** in `FEATURE_DIR/tasks/`:
+   - `phase-01-setup.md` - Project initialization
+   - `phase-02-foundation.md` - Blocking prerequisites for all user stories
+   - `phase-03-us1-[slug].md` - User Story 1 (P1 priority)
+   - `phase-04-us2-[slug].md` - User Story 2 (P2 priority)
+   - ... (one file per user story, in priority order)
+   - `phase-NN-polish.md` - Final phase: Cross-cutting concerns
+
+   **Phase file structure**:
+   ```markdown
+   # Phase N: [Phase Title]
+
+   **Status**: pending | in-progress | completed
+   **Dependencies**: [List phase dependencies, e.g., "Phase 2 must complete first"]
+
+   ## Goal
+   [Brief description of what this phase delivers]
+
+   ## Test Criteria
+   [How to verify this phase is complete - independently testable]
+
+   ## Tasks
+   - [ ] TXXX [P?] [Story?] Description with file path
+   - [ ] TXXX ...
+
+   ## Checkpoint
+   [What should be true when this phase completes]
+   ```
+
+   **4b. Create master tasks.md** in `FEATURE_DIR/`:
+   Use `spec-kit/templates/tasks-template.md` as reference, generate:
+   - Feature name and overview
+   - Phase summary table with status and links:
+     ```markdown
+     | Phase | Title | Status | Tasks | Dependencies |
+     |-------|-------|--------|-------|--------------|
+     | 1 | [Setup](tasks/phase-01-setup.md) | pending | 3 | - |
+     | 2 | [Foundation](tasks/phase-02-foundation.md) | pending | 6 | Phase 1 |
+     | 3 | [US1: Title](tasks/phase-03-us1-slug.md) | pending | 7 | Phase 2 |
+     ```
+   - Dependency graph (text diagram showing phase order)
+   - Parallel execution notes
+   - Implementation strategy (MVP first, incremental delivery)
+   - Quick reference: Total tasks, parallel opportunities, MVP scope
+
+5. **Report**: Output paths to generated files and summary:
+   - Files created: `tasks.md` + list of `tasks/phase-*.md` files
+   - Total task count and count per phase
+   - Parallel opportunities identified
+   - Independent test criteria for each story
+   - Suggested MVP scope (typically Phase 1-3: Setup + Foundation + US1)
+   - Format validation: Confirm ALL tasks follow the checklist format
+
+Context for task generation: {ARGS}
+
+**Hybrid Structure Benefits**:
+- Master `tasks.md` provides overview and navigation
+- Individual phase files enable parallel work by multiple agents/developers
+- Each phase file is self-contained with clear dependencies
+- Easy to track progress per phase independently
+
+The task files 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
+
+---
+
+## Suggested Next Steps
+
+| Command | Description | When to Use |
+|---------|-------------|-------------|
+| `/ck.spec.analyze` | Cross-artifact consistency check | Before implementation, validate spec/plan/tasks alignment |
+| `/ck.spec.implement` | Execute implementation | All tasks validated, ready to code |
+| `/ck.spec.taskstoissues` | Create GitHub issues | Track tasks in GitHub project board |
+
+**Workflow:** `/ck.spec.specify` → `/ck.spec.clarify` → `/ck.spec.plan` → `/ck.spec.tasks` → `/ck.spec.implement`

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

@@ -0,0 +1,48 @@
+---
+agent: 'agent'
+description: 'Convert tasks into GitHub issues for project tracking'
+tools:
+  - github/github-mcp-server/issue_write
+scripts:
+  sh: spec-kit/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks
+  ps: spec-kit/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks
+---
+
+## User Input
+
+```text
+${input}
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. Run `{SCRIPT}` 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. From the executed script, extract the path to **tasks**.
+
+3. **Verify Git repository and GitHub remote**:
+   - Check if this is a git repository: `git rev-parse --git-dir 2>/dev/null`
+   - If NOT a git repo: **STOP** and inform user "This command requires a git repository with a GitHub remote. Initialize git first or use `/ck.spec.implement` instead."
+   - Get the Git remote: `git config --get remote.origin.url`
+
+> [!CAUTION]
+> ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL (contains github.com)
+
+4. For each task in the list, use the GitHub MCP server to create a new issue in the repository that is representative of the Git remote.
+
+> [!CAUTION]
+> UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL
+
+---
+
+## Suggested Next Steps
+
+| Command | Description | When to Use |
+|---------|-------------|-------------|
+| `/ck.spec.implement` | Start implementation | Issues created, ready to code |
+| `/ck.spec.tasks` | Regenerate tasks | Need to update task list |
+| `/ck.kanban` | View project board | Track progress on created issues |
+
+**Usage:** Run after `/ck.spec.tasks` to sync tasks with GitHub Issues for team tracking

package/prompts/ck-test.prompt.md

@@ -1,10 +1,19 @@
----
-agent: 'agent'
-description: 'Run tests locally and analyze the summary report.'
-tools: ['search/codebase', 'search/changes', 'read/problems', 'read/terminalLastCommand']
----
-
-run tests locally and analyze the summary report.
-
-**IMPORTANT**: **Do not** start implementing.
-**IMPORTANT:** 
+---
+agent: 'agent'
+description: 'Run tests locally and analyze the summary report'
+tools: ['execute/runInTerminal', 'execute/getTerminalOutput', 'execute/runTests', 'execute/testFailure', 'read/problems']
+---
+
+Use the `tester` subagent to run tests locally and analyze the summary report.
+
+**IMPORTANT**: **Do not** start implementing.
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+
+---
+
+## Suggested Next Steps
+
+| Command | Description |
+|---------|-------------|
+| `/ck.fix` | Analyze and fix issues |
+| `/ck.review` | Scan and analyze codebase |

package/prompts/ck-watzup.prompt.md

@@ -0,0 +1,19 @@
+---
+agent: 'agent'
+description: 'Review recent changes and wrap up the work'
+tools: ['search/changes', 'execute/runInTerminal', 'execute/getTerminalOutput', 'search/codebase', 'read/readFile']
+---
+Review my current branch and the most recent commits. 
+Provide a detailed summary of all changes, including what was modified, added, or removed. 
+Analyze the overall impact and quality of the changes.
+
+**IMPORTANT**: **Do not** start implementing.
+
+---
+
+## Suggested Next Steps
+
+| Command | Description |
+|---------|-------------|
+| `/ck.brainstorm` | Explore ideas |
+| `/ck.plan` | Create plan |