cokit-cli 1.0.8 → 1.2.0

package/templates/repo/.github/prompts/ck-preview.prompt.md

@@ -1,41 +1,40 @@
 ---
 agent: 'agent'
-description: 'Path to file or directory to preview'
-tools: ['search/codebase', 'read/terminalLastCommand']
+description: 'Preview markdown files, plan directories, or plans collection'
+argument-hint: 'Path to markdown file or directory'
+tools: ['execute/runInTerminal', 'execute/getTerminalOutput']
 ---
 
 Universal viewer using `markdown-novel-viewer` skill - pass ANY path and see it rendered nicely.
 
 ## Usage
 
-- `/preview <file.md>` - View markdown file in novel-reader UI
-- `/preview <directory/>` - Browse directory contents
-- `/preview --stop` - Stop running server
+- `/ck.preview <file.md>` - View markdown file in novel-reader UI
+- `/ck.preview <directory/>` - Browse directory contents
+- `/ck.preview --stop` - Stop running server
 
 ## Examples
 
 ```bash
-/preview plans/my-plan.md     # View markdown file
-/preview plans/                    # Browse plans directory
-/preview docs/                     # Browse docs directory
-/preview any/path/to/file.md      # View any markdown file
-/preview any/path/                 # Browse any directory
+/ck.preview plans/my-plan/ck.plan.md     # View markdown file
+/ck.preview plans/                    # Browse plans directory
+/ck.preview docs/                     # Browse docs directory
+/ck.preview any/path/to/file.md      # View any markdown file
+/ck.preview any/path/                 # Browse any directory
 ```
 
 ## Execution
 
-**IMPORTANT:**  This makes the server visible in `/tasks` and manageable via `KillShell`.
+**IMPORTANT:** Run server as Claude Code background task using `run_in_background: true` with the Bash tool. This makes the server visible in `/tasks` and manageable via `KillShell`.
 
-Check if this script is located in the current workspace or in  directory:
-- If in current workspace: `$SKILL_DIR_PATH` = 
-- If in home directory: `$SKILL_DIR_PATH` = 
+The skill is located at `$HOME/.copilot/skills/markdown-novel-viewer/`.
 
 ### Stop Server
 
 If `--stop` flag is provided:
 
 ```bash
-node $SKILL_DIR_PATH/scripts/server.cjs --stop
+node $HOME/.copilot/skills/markdown-novel-viewer/scripts/server.cjs --stop
 ```
 
 ### Start Server
@@ -44,17 +43,17 @@ Otherwise, run the `markdown-novel-viewer` server as CC background task with `--
 
 ```bash
 # Determine if path is file or directory
-INPUT_PATH="${path}"
+INPUT_PATH="{{path}}"
 if [[ -d "$INPUT_PATH" ]]; then
   # Directory mode - browse
-  node $SKILL_DIR_PATH/scripts/server.cjs \
+  node $HOME/.copilot/skills/markdown-novel-viewer/scripts/server.cjs \
     --dir "$INPUT_PATH" \
     --host 0.0.0.0 \
     --open \
     --foreground
 else
   # File mode - view markdown
-  node $SKILL_DIR_PATH/scripts/server.cjs \
+  node $HOME/.copilot/skills/markdown-novel-viewer/scripts/server.cjs \
     --file "$INPUT_PATH" \
     --host 0.0.0.0 \
     --open \
@@ -62,4 +61,33 @@ else
 fi
 ```
 
-**Critical:** 
+**Critical:** When calling the Bash tool:
+- Set `run_in_background: true` to run as CC background task
+- Set `timeout: 300000` (5 minutes) to prevent premature termination
+- Parse JSON output and report URL to user
+
+Example Bash tool call:
+```json
+{
+  "command": "node $HOME/.copilot/skills/markdown-novel-viewer/scripts/server.cjs --dir \"path\" --host 0.0.0.0 --open --foreground",
+  "run_in_background": true,
+  "timeout": 300000,
+  "description": "Start preview server in background"
+}
+```
+
+After starting, parse the JSON output (e.g., `{"success":true,"url":"http://localhost:3456/view?file=...","networkUrl":"http://192.168.1.x:3456/view?file=..."}`) and report:
+- Local URL for browser access
+- Network URL for remote device access (if available)
+- Inform user that server is now running as CC background task (visible in `/tasks`)
+
+**CRITICAL:** MUST display the FULL URL including path and query string (e.g., `http://localhost:3456/view?file=/path/to/file.md`). NEVER truncate to just `host:port` (e.g., `http://localhost:3456`). The full URL is required for direct file access.
+
+---
+
+## Suggested Next Steps
+
+| Command | Description |
+|---------|-------------|
+| `/ck.brainstorm` | Explore ideas |
+| `/ck.plan` | Create plan |

package/templates/repo/.github/prompts/ck-review.prompt.md

@@ -0,0 +1,59 @@
+---
+agent: 'agent'
+description: 'Scan and analyze the codebase'
+argument-hint: 'Tasks or prompt to review'
+---
+
+Think harder to scan the codebase and analyze it follow the Orchestration Protocol, Core Responsibilities, Subagents Team and Development Rules: 
+<tasks>${input}</tasks>
+
+---
+
+## Role Responsibilities
+- You are an elite software engineering expert who specializes in system architecture design and technical decision-making. 
+- You operate by the holy trinity of software engineering: **YAGNI** (You Aren't Gonna Need It), **KISS** (Keep It Simple, Stupid), and **DRY** (Don't Repeat Yourself). Every solution you propose must honor these principles.
+- **IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
+- **IMPORTANT:** In reports, list any unresolved questions at the end, if any.
+
+---
+
+## Workflow:
+
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+
+### Research
+
+* Use 2 `researcher` subagents in parallel to search up to max 5 sources for the user's request, idea validation, best practices, challenges, and find the best possible solutions.
+* Keep every research markdown report concise (≤150 lines) while covering all requested topics and citations.
+* Use `/scout:ext` (preferred) or `/scout` (fallback) slash command to search the codebase for files needed to complete the task
+
+### Code Review
+
+* After finishing, use multiple `code-reviewer` subagents in parallel to review code. 
+* If there are any issues, duplicate code, or security vulnerabilities, ask main agent to improve the code and repeat the "Testing" process until all tests pass. 
+* When all tests pass, code is reviewed, the tasks are completed, report back to user with a summary of the changes and explain everything briefly, ask user to review the changes and approve them.
+* **IMPORTANT:** Sacrifice grammar for the sake of concision when writing outputs.
+
+### Plan
+* Use `planner` subagent to analyze reports from `researcher` and `scout` subagents to create an improvement plan following the progressive disclosure structure:
+  - Create a directory using naming pattern from `## Naming` section.
+  - Save the overview access point at `plan.md`, keep it generic, under 80 lines, and list each phase with status/progress and links.
+  - For each phase, add `phase-XX-phase-name.md` files containing sections (Context links, Overview with date/priority/statuses, Key Insights, Requirements, Architecture, Related code files, Implementation Steps, Todo list, Success Criteria, Risk Assessment, Security Considerations, Next steps).
+
+### Final Report
+* Report back to user with a summary of the changes and explain everything briefly, guide user to get started and suggest the next steps.
+* Ask the user if they want to commit and push to git repository, if yes, use `git-manager` subagent to commit and push to git repository.
+
+**REMEMBER**:
+- You can always generate images with `ai-multimodal` skill on the fly for visual assets.
+- You always read and analyze the generated assets with `ai-multimodal` skill to verify they meet requirements.
+- For image editing (removing background, adjusting, cropping), use ImageMagick or similar tools as needed.
+
+---
+
+## Suggested Next Steps
+
+| Command | Description |
+|---------|-------------|
+| `/ck.brainstorm` | Explore ideas |
+| `/ck.plan` | Create plan |

package/templates/repo/.github/prompts/ck-scout.prompt.md

@@ -1,25 +1,84 @@
----
-agent: 'agent'
-description: 'Scout given directories to respond to the user\'s requests'
-tools: ['search/codebase', 'search/changes']
----
-
-## Purpose
-
-Search the codebase for files needed to complete the task using a fast, token efficient agent.
-
-## Variables
-
-USER_PROMPT: $1
-SCALE: $2 (defaults to 3)
-REPORT_OUTPUT_DIR: Use `Report:` from `## Naming` section
-
-## Workflow:
-- IMPORTANT: Kick these agents off  using the , analyze and divide folders for each agent to scout intelligently and quickly.
-- IMPORTANT: Instruct the agents to quickly search the codebase for files needed to complete the task. This isn't about a full blown search, just a quick search to find the files needed to complete the task.
-- Instruct the  use a timeout of 3 minutes for each agent's bash call. Skip any agents that don't return within the timeout, don't restart them.
-
-**How to write reports:**
-
-- **IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
-- **IMPORTANT:** In reports, list any unresolved questions at the end, if any.
+---
+agent: 'agent'
+description: 'Fast codebase scouting using parallel agents'
+argument-hint: 'Search target or keyword'
+tools: ['search/codebase', 'read/readFile', 'search/listDirectory', 'search/textSearch', 'search/fileSearch']
+---
+
+## Context
+Search target:
+<target>${input}</target>
+
+## Your Role
+
+Fast, token-efficient codebase scouting to find files needed for tasks.
+
+## When to Use
+
+- Beginning work on feature spanning multiple directories
+- User mentions needing to "find", "locate", or "search for" files
+- Starting debugging session requiring file relationships understanding
+- User asks about project structure or where functionality lives
+- Before changes that might affect multiple codebase parts
+
+## Workflow
+
+### 1. Analyze Task
+- Parse user prompt for search targets
+- Identify key directories, patterns, file types
+- Determine optimal number of parallel searches
+
+### 2. Divide and Conquer
+- Split codebase into logical segments
+- Assign each search specific directories or patterns
+- Ensure no overlap, maximize coverage
+
+### 3. Execute Parallel Searches
+Use Glob and Grep with wide range of patterns:
+- File patterns: `**/*.ts`, `**/*.tsx`, `**/*.md`
+- Content patterns: function names, class names, keywords
+- Directory patterns: `src/`, `lib/`, `components/`
+
+### 4. Collect Results
+- Timeout: 3 minutes per search (skip non-responders)
+- Aggregate findings into single report
+- List unresolved questions at end
+
+## Report Format
+
+```markdown
+# Scout Report
+
+## Relevant Files
+- `path/to/file.ts` - Brief description
+- `path/to/another.ts` - Brief description
+
+## Directory Structure
+- `src/components/` - UI components
+- `src/services/` - Business logic
+
+## Key Findings
+- Pattern X found in Y locations
+- Feature Z implemented in files A, B, C
+
+## Unresolved Questions
+- Any gaps in findings
+```
+
+## Output Requirements
+
+**Be concise and actionable:**
+- List files with brief descriptions
+- Group by functionality or directory
+- Highlight key patterns and relationships
+- Note any gaps or areas needing further investigation
+
+---
+
+## Suggested Next Steps
+
+| Command | Description |
+|---------|-------------|
+| `/ck.plan` | Create implementation plan |
+| `/ck.cook` | Implement feature |
+| `/ck.ask` | Ask technical questions |

package/templates/repo/.github/prompts/ck-simplify.prompt.md

@@ -0,0 +1,46 @@
+---
+agent: 'code-simplifier'
+description: 'Simplify and refine code for clarity and maintainability'
+argument-hint: 'Scope: file path, git diff, or "recent changes"'
+---
+
+## Context
+Scope:
+<scope>${input}</scope>
+
+**Principles:** YAGNI, KISS, DRY | Preserve functionality | Token efficiency
+
+## Simplification Rules
+
+- Reduce unnecessary nesting — prefer early returns and guard clauses
+- Eliminate redundant code and abstractions
+- Improve variable and function names for clarity
+- Consolidate related logic
+- Remove comments that describe obvious code
+- Choose clarity over brevity — explicit > compact
+- Never combine too many concerns into single functions
+- Never remove helpful abstractions that improve organization
+
+## Process
+
+1. **Identify scope**: Use `${input}` or default to recent `git diff` changes
+2. **Analyze**: Find complexity reduction opportunities
+3. **Apply standards**: Follow `./docs/code-standards.md` conventions
+4. **Refine**: Simplify without changing behavior
+5. **Verify**: Run typecheck + linter to confirm no breakage
+
+## Scope Rules
+
+- **Default**: Only refine recently modified code (git diff)
+- **Explicit path**: Review specified files/directories
+- **Never**: Refactor unrelated code or change architecture
+
+---
+
+## Suggested Next Steps
+
+| Command | Description |
+|---------|-------------|
+| `/ck.test` | Run tests to verify nothing broke |
+| `/ck.review` | Code review the simplified code |
+| `/ck.git` | Commit changes |

package/templates/repo/.github/prompts/ck-spec-analyze.prompt.md

@@ -0,0 +1,203 @@
+---
+agent: 'agent'
+description: 'Cross-artifact consistency and quality analysis across spec, plan, and tasks'
+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).
+
+## 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 |
+
+**Workflow:** `/ck.spec.analyze` → fix issues → `/ck.spec.implement`