cokit-cli 1.0.1 → 1.0.3

package/skills/ck-planning/SKILL.md

@@ -1,82 +1,112 @@
 ---
-name: planning
-description: Create technical implementation plans through research, analysis, and design. Use when planning features, architecting systems, or breaking down complex requirements.
+name: 'ck-planning'
+description: 'Use when you need to plan technical solutions that are scalable, secure, and maintainable.'
 ---
 
 # Planning
 
-Create detailed implementation plans before writing code.
-
-## Core Principles
-
-- **YAGNI**, **KISS**, **DRY**
-- Plan quality determines implementation success
-- Research before designing
+Create detailed technical implementation plans through research, codebase analysis, solution design, and comprehensive documentation.
 
 ## When to Use
 
+Use this skill when:
 - Planning new feature implementations
 - Architecting system designs
 - Evaluating technical approaches
+- Creating implementation roadmaps
 - Breaking down complex requirements
 - Assessing technical trade-offs
 
-## Planning Workflow
+## Core Responsibilities & Rules
+
+Always honoring **YAGNI**, **KISS**, and **DRY** principles.
+**Be honest, be brutal, straight to the point, and be concise.**
 
 ### 1. Research & Analysis
-- Understand requirements fully
-- Research existing solutions
-- Identify constraints and risks
+Load: `references/research-phase.md`
+**Skip if:** Provided with researcher reports
 
 ### 2. Codebase Understanding
-- Read existing code patterns
-- Identify integration points
-- Note dependencies
+Load: `references/codebase-understanding.md`
+**Skip if:** Provided with scout reports
 
 ### 3. Solution Design
-- Design architecture
-- Consider alternatives
-- Evaluate trade-offs
+Load: `references/solution-design.md`
 
-### 4. Plan Documentation
-- Write clear plan document
-- Break into phases
-- Define success criteria
+### 4. Plan Creation & Organization
+Load: `references/plan-organization.md`
 
-### 5. Review & Refine
-- Verify completeness
-- Check actionability
-- Get stakeholder input
+### 5. Task Breakdown & Output Standards
+Load: `references/output-standards.md`
 
-## Output Requirements
+## Workflow Process
 
-- **DO NOT** implement code - only create plans
-- Plans must be self-contained
-- Include code snippets for clarity
-- Provide multiple options when applicable
+1. **Initial Analysis** → Read codebase docs, understand context
+2. **Research Phase** → Spawn researchers, investigate approaches
+3. **Synthesis** → Analyze reports, identify optimal solution
+4. **Design Phase** → Create architecture, implementation design
+5. **Plan Documentation** → Write comprehensive plan
+6. **Review & Refine** → Ensure completeness, clarity, actionability
 
-## Plan Structure
+## Output Requirements
+
+- 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
+- Provide multiple options with trade-offs when appropriate
+- Fully respect the `./docs/development-rules.md` file.
 
+**Plan Directory Structure**
 ```
 plans/
-└── YYMMDD-plan-name/
-    ├── plan.md           # Main plan
-    ├── phase-01-xxx.md   # Phase details
-    ├── phase-02-xxx.md
-    └── research/         # Research notes
+└── {date}-plan-name/
+    ├── research/
+    │   ├── researcher-XX-report.md
+    │   └── ...
+    ├── reports/
+    │   ├── XX-report.md
+    │   └── ...
+    ├── scout/
+    │   ├── scout-XX-report.md
+    │   └── ...
+    ├── plan.md
+    ├── phase-XX-phase-name-here.md
+    └── ...
 ```
 
-## Quality Standards
+## Active Plan State
+
+Prevents version proliferation by tracking current working plan via session state.
 
-- Thorough and specific
-- Consider maintainability
-- Address security concerns
-- Detailed enough for any developer
-- Validate against existing patterns
+### Active vs Suggested Plans
+
+Check the `## Plan Context` section cjs` - use for reports
+- **"Suggested: {path}"** = Branch-matched, hint only - do NOT auto-use
+- **"Plan: none"** = No active plan
+
+### Rules
+
+1. **If "Plan:" shows a path**: Ask "Continue with existing plan? [Y/n]"
+2. **If "Suggested:" shows a path**: Inform user, ask if they want to activate or create new
+3. **If "Plan: none"**: Create new plan using naming from `## Naming` section
+4. **Update on create**: Run `node  {plan-dir}`
+
+### Report Output Location
+
+All agents writing reports MUST:
+1. Check `## Naming` section  Active plans use plan-specific reports path
+3. Suggested plans use default reports path (not plan folder)
+
+**Important:** Suggested plans do NOT get plan-specific reports - this prevents pollution of old plan folders.
+
+## Quality Standards
 
-## References
+- Be thorough and specific
+- Consider long-term maintainability
+- Research thoroughly when uncertain
+- Address security and performance concerns
+- Make plans detailed enough for junior developers
+- Validate against existing codebase patterns
 
-See `./references/` for detailed guides:
-- `research-phase.md` - Research methodology
-- `solution-design.md` - Design patterns
-- `plan-organization.md` - Plan structure
+**Remember:** Plan quality determines implementation success. Be comprehensive and consider all solution aspects.

package/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 `/scout:ext` (preferred) or `/scout` (fallback) slash command 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/skills/ck-planning/references/output-standards.md

@@ -0,0 +1,127 @@
+# 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
+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)
+- **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 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:** List unresolved questions at end
+- Questions needing clarification
+- Technical decisions requiring input
+- Unknowns impacting implementation
+- Trade-offs requiring business decisions
+
+## 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/skills/ck-planning/references/plan-organization.md

@@ -1,88 +1,150 @@
-# Plan Organization
+# Plan Creation & Organization
 
-How to structure implementation plans.
+## Directory Structure
 
-## Plan Document 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
+
+```
+{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
+```
+
+### Active Plan State Tracking
+
+Check the `## Plan Context` section injected by hooks:
+- **"Plan: {path}"** = Active plan - use for reports
+- **"Suggested: {path}"** = Branch-matched, hint only - do NOT auto-use
+- **"Plan: none"** = No active plan
+
+**Pre-Creation Check:**
+1. If "Plan:" shows a path → ask "Continue with existing plan? [Y/n]"
+2. If "Suggested:" shows a path → inform user (hint only, do NOT auto-use)
+3. If "Plan: none" → create new plan using naming from `## Naming` section
+
+**After Creating Plan:**
+```bash
+# Update session state so subagents get the new plan context:
+node %USERPROFILE%/.claude/scripts/set-active-plan.cjs {plan-dir}
+```
+
+**Report Output Rules:**
+1. Use `Report:` and `Plan dir:` from `## Naming` section
+2. Active plans use plan-specific reports path
+3. Suggested plans use default reports path to prevent old plan pollution
+
+## 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 Name"
+title: "Feature Implementation Plan"
+description: "Add user authentication with OAuth2 support"
 status: pending
-effort: Xh
-created: YYYY-MM-DD
+priority: P1
+effort: 8h
+issue: 123
+branch: kai/feat/oauth-auth
+tags: [auth, backend, security]
+created: 2025-12-16
 ---
 
-# Plan Title
+# Feature Implementation Plan
 
 ## Overview
-[2-3 sentences describing what and why]
-
-## Goals
-- [ ] Goal 1
-- [ ] Goal 2
 
-## Non-Goals
-- Thing we're not doing
-- Thing deferred to later
-
-## Design
-[Architecture overview]
+Brief description of what this plan accomplishes.
 
 ## Phases
 
-| Phase | Description | Effort |
-|-------|-------------|--------|
-| 1 | Setup | 1h |
-| 2 | Core feature | 2h |
-| 3 | Testing | 1h |
+| # | Phase | Status | Effort | Link |
+|---|-------|--------|--------|------|
+| 1 | Setup | Pending | 2h | [phase-01](./phase-01-setup.md) |
+| 2 | Implementation | Pending | 4h | [phase-02](./phase-02-impl.md) |
+| 3 | Testing | Pending | 2h | [phase-03](./phase-03-test.md) |
 
-## Risks
-- Risk 1: [mitigation]
-- Risk 2: [mitigation]
+## Dependencies
 
-## Success Criteria
-- [ ] Criterion 1
-- [ ] Criterion 2
+- List key dependencies here
 ```
 
-## Phase Documents
+**Guidelines:**
+- Keep generic and under 80 lines
+- List each phase with status/progress
+- Link to detailed phase files
+- Key dependencies
 
-Each phase gets its own file:
+### Phase Files (phase-XX-name.md)
+Fully respect the `./docs/development-rules.md` file.
+Each phase file should contain:
 
-```markdown
-# Phase N: Name
+**Context Links**
+- Links to related reports, files, documentation
 
-**Effort:** Xh | **Status:** Pending
+**Overview**
+- Priority
+- Current status
+- Brief description
 
-## Objective
-[What this phase accomplishes]
+**Key Insights**
+- Important findings from research
+- Critical considerations
 
-## Tasks
-- [ ] Task 1
-- [ ] Task 2
-- [ ] Task 3
+**Requirements**
+- Functional requirements
+- Non-functional requirements
 
-## Acceptance Criteria
-- [ ] Criterion 1
-- [ ] Criterion 2
-```
+**Architecture**
+- System design
+- Component interactions
+- Data flow
 
-## File Organization
+**Related Code Files**
+- List of files to modify
+- List of files to create
+- List of files to delete
 
-```
-plans/
-└── YYMMDD-feature-name/
-    ├── plan.md
-    ├── phase-01-setup.md
-    ├── phase-02-implementation.md
-    ├── phase-03-testing.md
-    └── research/
-        └── notes.md
-```
+**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
 
-## Quality Checks
+**Security Considerations**
+- Auth/authorization
+- Data protection
 
-- [ ] Clear structure?
-- [ ] Tasks actionable?
-- [ ] Effort estimated?
-- [ ] Success criteria defined?
+**Next Steps**
+- Dependencies
+- Follow-up tasks

package/skills/ck-planning/references/research-phase.md

@@ -1,56 +1,49 @@
-# Research Phase
-
-How to properly research before planning.
-
-## Goals
-
-- Understand problem space
-- Find existing solutions
-- Identify constraints
-- Avoid reinventing wheels
-
-## Research Steps
-
-### 1. Understand Requirements
-
-- What exactly needs to be built?
-- What's the success criteria?
-- What are the constraints?
-- Who are the stakeholders?
-
-### 2. Research Existing Solutions
-
-- How do others solve this?
-- What libraries/tools exist?
-- What patterns are common?
-- What pitfalls to avoid?
-
-### 3. Analyze Codebase
-
-- What exists already?
-- What patterns are used?
-- What can be reused?
-- What needs to change?
-
-### 4. Identify Risks
-
-- What could go wrong?
-- What's uncertain?
-- What needs clarification?
-- What are blockers?
-
-## Research Output
-
-Document findings:
-- Problem summary
-- Existing solutions
-- Recommended approach
-- Risks and mitigations
-- Open questions
-
-## Quality Checks
-
-- [ ] Requirements clear?
-- [ ] Alternatives considered?
-- [ ] Risks identified?
-- [ ] Questions listed?
+# Research & Analysis Phase
+
+**When to skip:** If provided with researcher reports, skip this phase.
+
+## Core Activities
+
+### Parallel Researcher Agents
+- Spawn multiple `researcher` agents in parallel to investigate different approaches
+- Wait for all researcher agents to report back before proceeding
+- Each researcher investigates a specific aspect or approach
+
+### Sequential Thinking
+- Use `sequential-thinking` skill for dynamic and reflective problem-solving
+- Structured thinking process for complex analysis
+- Enables multi-step reasoning with revision capability
+
+### Documentation Research
+- Use `docs-seeker` skill to read and understand documentation
+- Research plugins, packages, and frameworks
+- Find latest technical documentation using llms.txt standard
+
+### GitHub Analysis
+- Use `gh` command to read and analyze:
+  - GitHub Actions logs
+  - Pull requests
+  - Issues and discussions
+- Extract relevant technical context from GitHub resources
+
+### Remote Repository Analysis
+When given GitHub repository URL, generate fresh codebase summary:
+```bash
+# usage: 
+repomix --remote <github-repo-url>
+# example: 
+repomix --remote https://github.com/mrgoonie/human-mcp
+```
+
+### Debugger Delegation
+- Delegate to `debugger` agent for root cause analysis
+- Use when investigating complex issues or bugs
+- Debugger agent specializes in diagnostic tasks
+
+## Best Practices
+
+- Research breadth before depth
+- Document findings for synthesis phase
+- Identify multiple approaches for comparison
+- Consider edge cases during research
+- Note security implications early