cokit-cli 1.0.9 → 1.2.0

package/skills/{ck-planning → planning}/references/output-standards.md

@@ -1,127 +1,141 @@
-# 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.
+# Output Standards & Quality
+
+## Plan File Format
+
+**Important:**
+- DO NOT create plans or reports in USER directory.
+- ALWAYS create plans or reports in CURRENT WORKING PROJECT DIRECTORY.
+
+### 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
+
+**Important:**
+- DO NOT create plans or reports in USER directory.
+- ALWAYS create plans or reports in CURRENT WORKING PROJECT DIRECTORY.
+
+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
+
+**Important:**
+- DO NOT create plans or reports in USER directory.
+- ALWAYS create plans or reports in CURRENT WORKING PROJECT DIRECTORY.
+
+### 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 `AskUserQuestion` 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 → skills/planning}/references/plan-organization.md

@@ -1,150 +1,160 @@
-# 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
-
-```
-{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:
-# Update plan context via session state management
-```
-
-**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 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]
-created: 2025-12-16
----
-
-# Feature Implementation Plan
-
-## Overview
-
-Brief description of what this plan accomplishes.
-
-## Phases
-
-| # | 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) |
-
-## 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
+# Plan Creation & Organization
+
+## Directory Structure
+
+### Plan Location
+
+**Important:**
+- DO NOT create plans or reports in USER directory.
+- ALWAYS create plans or reports in CURRENT WORKING PROJECT DIRECTORY.
+
+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
+```
+
+### 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 $HOME/.copilot/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
+
+**Important:**
+- DO NOT create plans or reports in USER directory.
+- ALWAYS create plans or reports in CURRENT WORKING PROJECT DIRECTORY.
+
+### 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]
+created: 2025-12-16
+---
+
+# Feature Implementation Plan
+
+## Overview
+
+Brief description of what this plan accomplishes.
+
+## Phases
+
+| # | 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) |
+
+## 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