cokit-cli 1.2.7 → 1.4.0

package/templates/repo/.github/skills/ck-planning/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: ck-plan
+description: "Plan implementations, design architectures, create technical roadmaps with detailed phases. Use for feature planning, system design, solution architecture, implementation strategy, phase documentation."
+argument-hint: "[task] OR [archive|red-team|validate]"
+license: MIT
+---
+
+# Planning
+
+Create detailed technical implementation plans through research, codebase analysis, solution design, and comprehensive documentation.
+
+**IMPORTANT:** Before you start, scan unfinished plans in the current project at `./plans/` directory, read the `plan.md`, if there are relevant plans with your upcoming plan, update them as well. If you're unsure or need more clarifications, use ask the user.
+
+### Cross-Plan Dependency Detection
+
+During the pre-creation scan, detect and mark blocking relationships between plans:
+
+1. **Scan** — Read `plan.md` frontmatter of each unfinished plan (status != `completed`/`cancelled`)
+2. **Compare scope** — Check overlapping files, shared dependencies, same feature area
+3. **Classify relationship:**
+   - New plan needs output of existing plan → new plan `blockedBy: [existing-plan-dir]`
+   - New plan changes something existing plan depends on → existing plan `blockedBy: [new-plan-dir]`, new plan `blocks: [existing-plan-dir]`
+   - Mutual dependency → both plans reference each other in `blockedBy`/`blocks`
+4. **Bidirectional update** — When relationship detected, update BOTH `plan.md` files' frontmatter
+5. **Ambiguous?** → Use asking the user with header "Plan Dependency", present detected overlap, ask user to confirm relationship type (blocks/blockedBy/none)
+
+**Frontmatter fields** (relative plan dir paths):
+```yaml
+blockedBy: [260301-1200-auth-system]     # This plan waits on these plans
+blocks: [260228-0900-user-dashboard]     # This plan blocks these plans
+```
+
+**Status interaction:** A plan with `blockedBy` entries where ANY blocker is not `completed` → plan status should note `blocked` in its overview. When all blockers complete, the blocked plan becomes unblocked automatically on next scan.
+
+## Default (No Arguments)
+
+If invoked with a task description, proceed with planning workflow. If invoked WITHOUT arguments or with unclear intent, use asking the user to present available operations:
+
+| Operation | Description |
+|-----------|-------------|
+| `(default)` | Create implementation plan for a task |
+| `archive` | Write journal entry & archive plans |
+| `red-team` | Adversarial plan review |
+| `validate` | Critical questions interview |
+
+Present as options by asking the user with header "Planning Operation", question "What would you like to do?".
+
+## Workflow Modes
+
+Default: `--auto` (analyze task complexity and auto-pick mode).
+
+| Flag | Mode | Research | Red Team | Validation | Cook Flag |
+|------|------|----------|----------|------------|-----------|
+| `--auto` | Auto-detect | Follows mode | Follows mode | Follows mode | Follows mode |
+| `--fast` | Fast | Skip | Skip | Skip | `--auto` |
+| `--hard` | Hard | 2 researchers | Yes | Optional | (none) |
+| `--parallel` | Parallel | 2 researchers | Yes | Optional | `--parallel` |
+| `--two` | Two approaches | 2+ researchers | After selection | After selection | (none) |
+
+Add `--no-tasks` to skip task hydration in any mode.
+
+Load: `references/workflow-modes.md` for auto-detection logic, per-mode workflows, context reminders.
+
+## When to Use
+
+- Planning new feature implementations
+- Architecting system designs
+- Evaluating technical approaches
+- Creating implementation roadmaps
+- Breaking down complex requirements
+
+## Core Responsibilities & Rules
+
+Always honoring **YAGNI**, **KISS**, and **DRY** principles.
+**Be honest, be brutal, straight to the point, and be concise.**
+
+### 0. Scope Challenge
+Load: `references/scope-challenge.md`
+**Skip if:** `--fast` mode or trivial task (single file fix, <20 word description)
+
+### 1. Research & Analysis
+Load: `references/research-phase.md`
+**Skip if:** Fast mode or provided with researcher reports
+
+### 2. Codebase Understanding
+Load: `references/codebase-understanding.md`
+**Skip if:** Provided with scout reports
+
+### 3. Solution Design
+Load: `references/solution-design.md`
+
+### 4. Plan Creation & Organization
+Load: `references/plan-organization.md`
+
+### 5. Task Breakdown & Output Standards
+Load: `references/output-standards.md`
+
+## Process Flow (Authoritative)
+
+```mermaid
+flowchart TD
+    A[Pre-Creation Check] --> B[Cross-Plan Scan]
+    B --> C[Scope Challenge]
+    C --> D[Mode Detection]
+    D -->|fast| E[Skip Research]
+    D -->|hard/parallel/two| F[Spawn Researchers]
+    E --> G[Codebase Analysis]
+    F --> G
+    G --> H[Write Plan via Planner]
+    H --> I{Red Team?}
+    I -->|Yes| J[Red Team Review]
+    I -->|No| K{Validate?}
+    J --> K
+    K -->|Yes| L[Validation Interview]
+    K -->|No| M[Hydrate Tasks]
+    L --> M
+    M --> N[Output Cook Command]
+    N --> O[Journal]
+```
+
+**This diagram is the authoritative workflow.** Prose sections below provide detail for each node.
+
+## Workflow Process
+
+1. **Pre-Creation Check** → Check Plan Context for active/suggested/none
+1b. **Cross-Plan Scan** → Scan unfinished plans, detect `blockedBy`/`blocks` relationships, update both plans
+1c. **Scope Challenge** → Run Step 0 scope questions, select mode (see `references/scope-challenge.md`)
+    **Skip if:** `--fast` mode or trivial task
+2. **Mode Detection** → Auto-detect or use explicit flag (see `workflow-modes.md`)
+3. **Research Phase** → Spawn researchers (skip in fast mode)
+4. **Codebase Analysis** → Read docs, scout if needed
+5. **Plan Documentation** → Write comprehensive plan via planner subagent
+6. **Red Team Review** → Run `/ck-plan red-team {plan-path}` (hard/parallel/two modes)
+7. **Post-Plan Validation** → Run `/ck-plan validate {plan-path}` (hard/parallel/two modes)
+8. **Hydrate Tasks** → Create Tasks from phases (default on, `--no-tasks` to skip)
+9. **Context Reminder** → Output cook command with absolute path (MANDATORY)
+10. **Journal** → Run `/ck-journal` to write a concise technical journal entry upon completion
+
+## Output Requirements
+**IMPORTANT:** Invoke "/ck-project-organization" skill to organize the outputs.
+
+- DO NOT implement code - only create plans
+- Respond with plan file path and summary
+- Ensure self-contained plans with necessary context
+- Include code snippets/pseudocode when clarifying
+- Fully respect the `./docs/development-rules.md` file
+
+## Task Management
+
+Plan files = persistent. Tasks = session-scoped. Hydration bridges the gap.
+
+**Default:** Auto-hydrate tasks after plan files are written. Skip with `--no-tasks`.
+**3-Task Rule:** <3 phases → skip task creation.
+**Fallback:** Task tools (`TaskCreate`/`TaskUpdate`/`TaskGet`/`TaskList`) are CLI-only — unavailable in VSCode extension. If they error, use `TodoWrite` for tracking. Plan files remain the source of truth; hydration is an optimization, not a requirement.
+
+Load: `references/task-management.md` for hydration pattern, TaskCreate patterns, cook handoff protocol.
+
+### Hydration Workflow
+1. Write plan.md + phase files (persistent layer)
+2. TaskCreate per phase with `addBlockedBy` chain (skip if Task tools unavailable)
+3. TaskCreate for critical/high-risk steps within phases (skip if Task tools unavailable)
+4. Metadata: phase, priority, effort, planDir, phaseFile
+5. Cook picks up via TaskList (same session) or re-hydrates (new session)
+
+## Active Plan State
+
+Check `## Plan Context` injected by hooks:
+- **"Plan: {path}"** → Active plan. Ask "Continue? [Y/n]"
+- **"Suggested: {path}"** → Branch hint only. Ask if activate or create new.
+- **"Plan: none"** → Create new using `Plan dir:` from `## Naming`
+
+Reports: Active plans → plan-specific path. Suggested → default path.
+
+### Important
+**DO NOT** create plans or reports in USER directory.
+**MUST** create plans or reports in **THE CURRENT WORKING PROJECT DIRECTORY**.
+
+## Subcommands
+
+| Subcommand | Reference | Purpose |
+|------------|-----------|---------|
+| `/ck-plan archive` | `references/archive-workflow.md` | Archive plans + write journal entries |
+| `/ck-plan red-team` | `references/red-team-workflow.md` | Adversarial plan review with hostile reviewers |
+| `/ck-plan validate` | `references/validate-workflow.md` | Validate plan with critical questions interview |
+
+## Quality Standards
+
+- Thorough and specific, consider long-term maintainability
+- Research thoroughly when uncertain
+- Address security and performance concerns
+- Detailed enough for junior developers
+- Validate against existing codebase patterns
+
+**Remember:** Plan quality determines implementation success. Be comprehensive and consider all solution aspects.

package/templates/repo/.github/skills/ck-planning/references/archive-workflow.md

@@ -0,0 +1,53 @@
+# Archive Workflow
+
+## Your mission
+Read and analyze the plans, then write journal entries and archive specific plans or all plans in the `plans` directory.
+
+## Plan Resolution
+1. If `$ARGUMENTS` provided → Use that path
+2. Else read all plans in the `plans` directory
+
+## Workflow
+
+### Step 1: Read Plan Files
+
+Read the plan directory:
+- `plan.md` - Overview and phases list
+- `phase-*.md` - 20 first lines of each phase file to understand the progress and status
+
+### Step 2: Summarize the plans and document them with `/ck-journal` skill invocation
+ask if user wants to document journal entries or not.
+Skip this step if user selects "No".
+If user selects "Yes":
+- Analyze the information in previous steps.
+- Use Task tool with `subagent_type="journal-writer"` in parallel to document all plans.
+- Journal entries should be concise and focused on the most important events, key changes, impacts, and decisions.
+- Keep journal entries in the `./docs/journals/` directory.
+
+### Step 3: Ask user to confirm the action before archiving these plans
+ask if user wants to proceed with archiving these plans, select specific plans to archive or all completed plans only.
+ask if user wants to delete permanently or move to the `./plans/archive` directory.
+
+### Step 4: Archive the plans
+Start archiving the plans based on the user's choice:
+- Move the plans to the `./plans/archive` directory.
+- Delete the plans permanently: `rm -rf ./plans/<plan-1> ./plans/<plan-2> ...`
+
+### Step 5: Ask if user wants to commit the changes
+ask if user wants to commit the changes with these options:
+- Stage and commit the changes (Use `/ck-git` for commit flow)
+- Commit and push the changes (Use `/ck-git` for push flow)
+- Nah, I'll do it later
+
+## Output
+After archiving the plans, provide summary:
+- Number of plans archived
+- Number of plans deleted permanently
+- Table of plans that are archived or deleted (title, status, created date, LOC)
+- Table of journal entries that are created (title, status, created date, LOC)
+
+## Important Notes
+- Only ask questions about genuine decision points
+- Sacrifice grammar for concision
+- List any unresolved questions at the end
+- Ensure token efficiency while maintaining high quality

package/templates/repo/.github/skills/ck-planning/references/codebase-understanding.md

@@ -0,0 +1,62 @@
+# Codebase Understanding Phase
+
+**When to skip:** If provided with scout reports, skip this phase.
+
+## Core Activities
+
+### Parallel Scout Agents
+- Use `/ck-scout ext` (preferred) or `/ck-scout` (fallback) skill invocation to search the codebase for files needed to complete the task
+- Each scout locates files needed for specific task aspects
+- Wait for all scout agents to report back before analysis
+- Efficient for finding relevant code across large codebases
+
+### Essential Documentation Review
+ALWAYS read these files first:
+
+1. **`./docs/development-rules.md`** (IMPORTANT)
+   - File Name Conventions
+   - File Size Management
+   - Development rules and best practices
+   - Code quality standards
+   - Security guidelines
+
+2. **`./docs/codebase-summary.md`**
+   - Project structure and current status
+   - High-level architecture overview
+   - Component relationships
+
+3. **`./docs/code-standards.md`**
+   - Coding conventions and standards
+   - Language-specific patterns
+   - Naming conventions
+
+4. **`./docs/design-guidelines.md`** (if exists)
+   - Design system guidelines
+   - Branding and UI/UX conventions
+   - Component library usage
+
+### Environment Analysis
+- Review development environment setup
+- Analyze dotenv files and configuration
+- Identify required dependencies
+- Understand build and deployment processes
+
+### Pattern Recognition
+- Study existing patterns in codebase
+- Identify conventions and architectural decisions
+- Note consistency in implementation approaches
+- Understand error handling patterns
+
+### Integration Planning
+- Identify how new features integrate with existing architecture
+- Map dependencies between components
+- Understand data flow and state management
+- Consider backward compatibility
+
+## Best Practices
+
+- Start with documentation before diving into code
+- Use scouts for targeted file discovery
+- Document patterns found for consistency
+- Note any inconsistencies or technical debt
+- Consider impact on existing features

package/templates/repo/.github/skills/ck-planning/references/output-standards.md

@@ -0,0 +1,145 @@
+# Output Standards & Quality
+
+## Plan File Format
+
+### YAML Frontmatter (Required for plan.md)
+
+All `plan.md` files MUST include YAML frontmatter at the top:
+
+```yaml
+---
+title: "{Brief plan title}"
+description: "{One-sentence summary for card preview}"
+status: pending  # pending | in-progress | completed | cancelled
+priority: P2     # P1 (High) | P2 (Medium) | P3 (Low)
+effort: 4h       # Estimated total effort
+issue: 74        # GitHub issue number (if applicable)
+branch: kai/feat/feature-name
+tags: [frontend, api]  # Category tags
+blockedBy: []    # Plan dirs this plan waits on (e.g., [260301-1200-auth-system])
+blocks: []       # Plan dirs this plan blocks (e.g., [260228-0900-user-dashboard])
+created: 2025-12-16
+---
+```
+
+### Auto-Population Rules
+
+When creating plans, auto-populate these fields:
+- **title**: Extract from task description
+- **description**: First sentence of Overview section
+- **status**: Always `pending` for new plans
+- **priority**: From user request or default `P2`
+- **effort**: Sum of phase estimates
+- **issue**: Parse from branch name or context
+- **branch**: Current git branch (`git branch --show-current`)
+- **tags**: Infer from task keywords (e.g., frontend, backend, api, auth)
+- **blockedBy**: Detected during pre-creation scan (empty `[]` if none)
+- **blocks**: Detected during pre-creation scan (empty `[]` if none)
+- **created**: Today's date in YYYY-MM-DD format
+
+### Tag Vocabulary (Recommended)
+
+Use these predefined tags for consistency:
+- **Type**: `feature`, `bugfix`, `refactor`, `docs`, `infra`
+- **Domain**: `frontend`, `backend`, `database`, `api`, `auth`
+- **Scope**: `critical`, `tech-debt`, `experimental`
+
+### Task Naming Conventions
+
+**subject** (imperative): Action verb + deliverable, <60 chars
+  Examples: "Setup database migrations", "Implement OAuth2 flow"
+
+**activeForm** (continuous): Present participle of subject
+  Examples: "Setting up database", "Implementing OAuth2"
+
+**description**: 1-2 sentences, concrete deliverables, reference phase file
+
+See `task-management.md` for full TaskCreate patterns and metadata.
+
+## Task Breakdown
+
+- Transform complex requirements into manageable, actionable tasks
+- Each task independently executable with clear dependencies
+- Prioritize by dependencies, risk, business value
+- Eliminate ambiguity in instructions
+- Include specific file paths for all modifications
+- Provide clear acceptance criteria per task
+
+### File Management
+
+List affected files with:
+- Full paths (not relative)
+- Action type (modify/create/delete)
+- Brief change description
+- Dependencies on other changes
+- Fully respect the `./docs/development-rules.md` file.
+
+## Workflow Process
+
+1. **Initial Analysis** → Read docs, understand context
+2. **Research Phase** → Spawn researchers in parallel, investigate approaches
+3. **Synthesis** → Analyze reports, identify optimal solution
+4. **Design Phase** → Create architecture, implementation design
+5. **Plan Documentation** → Write comprehensive plan in Markdown
+6. **Review & Refine** → Ensure completeness, clarity, actionability
+
+## Output Requirements
+
+### What Planners Do
+- Create plans ONLY (no implementation)
+- Provide plan file path and summary
+- Self-contained plans with necessary context
+- Code snippets/pseudocode when clarifying
+- Multiple options with trade-offs when appropriate
+- Fully respect the `./docs/development-rules.md` file.
+
+### Writing Style
+**IMPORTANT:** Sacrifice grammar for concision
+- Focus clarity over eloquence
+- Use bullets and lists
+- Short sentences
+- Remove unnecessary words
+- Prioritize actionable info
+
+### Unresolved Questions
+**IMPORTANT:** Use asking the user to ask users for unresolved questions at the end
+- Questions needing clarification
+- Technical decisions requiring input
+- Unknowns impacting implementation
+- Trade-offs requiring business decisions
+Revise the plan and phases based on the answers.
+
+## Quality Standards
+
+### Thoroughness
+- Thorough and specific in research/planning
+- Consider edge cases, failure modes
+- Think through entire user journey
+- Document all assumptions
+
+### Maintainability
+- Consider long-term maintainability
+- Design for future modifications
+- Document decision rationale
+- Avoid over-engineering
+- Fully respect the `./docs/development-rules.md` file.
+
+### Research Depth
+- When uncertain, research more
+- Multiple options with clear trade-offs
+- Validate against best practices
+- Consider industry standards
+
+### Security & Performance
+- Address all security concerns
+- Identify performance implications
+- Plan for scalability
+- Consider resource constraints
+
+### Implementability
+- Detailed enough for junior developers
+- Validate against existing patterns
+- Ensure codebase standards consistency
+- Provide clear examples
+
+**Remember:** Plan quality determines implementation success. Be comprehensive, consider all solution aspects.

package/templates/repo/.github/skills/ck-planning/references/plan-organization.md

@@ -0,0 +1,182 @@
+# Plan Creation & Organization
+
+## Directory Structure
+
+### Plan Location
+
+Use `Plan dir:` from `## Naming` section injected by hooks. This is the full computed path.
+
+**Example:** `plans/251101-1505-authentication/` or `ai_docs/feature/MRR-1453/`
+
+### File Organization
+
+IN CURRENT WORKING PROJECT DIRECTORY:
+```
+{plan-dir}/                                    # From `Plan dir:` in ## Naming
+├── research/
+│   ├── researcher-XX-report.md
+│   └── ...
+├── reports/
+│   ├── scout-report.md
+│   ├── researcher-report.md
+│   └── ...
+├── plan.md                                    # Overview access point
+├── phase-01-setup-environment.md              # Setup environment
+├── phase-02-implement-database.md             # Database models
+├── phase-03-implement-api-endpoints.md        # API endpoints
+├── phase-04-implement-ui-components.md        # UI components
+├── phase-05-implement-authentication.md       # Auth & authorization
+├── phase-06-implement-profile.md              # Profile page
+└── phase-07-write-tests.md                    # Tests
+```
+
+### Task Hydration
+
+After creating plan.md and phase files, hydrate tasks (unless `--no-tasks`):
+1. TaskCreate per phase with `addBlockedBy` dependency chain
+2. Add critical step tasks for high-risk items
+3. See `task-management.md` for patterns and cook handoff protocol
+
+### Active Plan State Tracking
+
+See SKILL.md "Active Plan State" section for full rules. Key points:
+- Check `## Plan Context` injected by hooks for active/suggested/none state
+- Active plans use plan-specific reports path; suggested plans use default path
+
+## Plan Creation via CLI
+
+After determining phases from research/design:
+
+1. **Scaffold via CLI:**
+   ```bash
+   ck plan create \
+     --title "{plan title}" \
+     --phases "{Phase1},{Phase2},{Phase3}" \
+     --dir {plan-dir} \
+     --priority {P1|P2|P3} \
+     [--issue {N}]
+   ```
+
+2. **Fill content sections** in plan.md via Edit tool:
+   - `## Overview` — brief description
+   - `## Dependencies` — cross-plan dependencies
+
+3. **Fill each phase-XX.md** with:
+   - Architecture, implementation steps, success criteria
+   - Requirements, risk assessment, security considerations
+
+4. **NEVER edit the Phases table directly** — it's CLI-owned.
+   Use `ck plan check/uncheck/add-phase` for structural changes.
+
+**Fallback:** If `ck` CLI is not available (e.g., user hasn't installed),
+write plan.md directly using the canonical 3-column format.
+
+## File Structure
+
+### Overview Plan (plan.md)
+
+**IMPORTANT:** All plan.md files MUST include YAML frontmatter. See `output-standards.md` for schema.
+
+**Example plan.md structure:**
+```markdown
+---
+title: "Feature Implementation Plan"
+description: "Add user authentication with OAuth2 support"
+status: pending
+priority: P1
+effort: 8h
+issue: 123
+branch: kai/feat/oauth-auth
+tags: [auth, backend, security]
+blockedBy: []
+blocks: [260115-0900-user-dashboard]
+created: 2025-12-16
+---
+
+# Feature Implementation Plan
+
+## Overview
+
+Brief description of what this plan accomplishes.
+
+## Cross-Plan Dependencies
+
+| Relationship | Plan | Status |
+|-------------|------|--------|
+| Blocks | [260115-0900-user-dashboard](../260115-0900-user-dashboard/plan.md) | pending |
+
+## Phases
+
+| Phase | Name | Status |
+|-------|------|--------|
+| 1 | [Setup Environment](./phase-01-setup.md) | Pending |
+| 2 | [Core Implementation](./phase-02-impl.md) | Pending |
+| 3 | [Testing & Validation](./phase-03-test.md) | Pending |
+
+<!-- IMPORTANT: Link text MUST be human-readable names (not filenames).
+     Bad:  [phase-01-setup.md](./phase-01-setup.md)
+     Good: [Setup Environment](./phase-01-setup.md) -->
+
+## Dependencies
+
+- List key dependencies here
+```
+
+**Guidelines:**
+- Keep generic and under 80 lines
+- List each phase with status/progress
+- Link to detailed phase files
+- Key dependencies
+
+### Phase Files (phase-XX-name.md)
+Fully respect the `./docs/development-rules.md` file.
+Each phase file should contain:
+
+**Context Links**
+- Links to related reports, files, documentation
+
+**Overview**
+- Priority
+- Current status
+- Brief description
+
+**Key Insights**
+- Important findings from research
+- Critical considerations
+
+**Requirements**
+- Functional requirements
+- Non-functional requirements
+
+**Architecture**
+- System design
+- Component interactions
+- Data flow
+
+**Related Code Files**
+- List of files to modify
+- List of files to create
+- List of files to delete
+
+**Implementation Steps**
+- Detailed, numbered steps
+- Specific instructions
+
+**Todo List**
+- Checkbox list for tracking
+
+**Success Criteria**
+- Definition of done
+- Validation methods
+
+**Risk Assessment**
+- Potential issues
+- Mitigation strategies
+
+**Security Considerations**
+- Auth/authorization
+- Data protection
+
+**Next Steps**
+- Dependencies
+- Follow-up tasks