cokit-cli 1.3.0 → 1.4.0

package/skills/ck-planning/references/task-management.md

@@ -0,0 +1,134 @@
+# Task Management Integration
+
+## Session-Scoped Reality
+
+Tasks are **ephemeral** — they die when the session ends. `tasks/` holds lock files only, NOT task data. Plan files (plan.md, phase-XX.md with checkboxes) are the **persistent** layer.
+
+**Tool Availability:** `TaskCreate`/`TaskUpdate`/`TaskGet`/`TaskList` are **CLI-only** — disabled in VSCode extension (`isTTY` check). If these tools error, use `TodoWrite` for progress tracking. Plan files remain the source of truth; hydration is an optimization, not a requirement.
+
+The **hydration pattern** bridges sessions:
+
+```
+┌──────────────────┐  Hydrate   ┌───────────────────┐
+│ Plan Files       │ ─────────► │ Tasks      │
+│ (persistent)     │            │ (session-scoped)  │
+│ [ ] Phase 1      │            │ ◼ pending         │
+│ [ ] Phase 2      │            │ ◼ pending         │
+└──────────────────┘            └───────────────────┘
+                                        │ Work
+                                        ▼
+┌──────────────────┐  Sync-back ┌───────────────────┐
+│ Plan Files       │ ◄───────── │ Task Updates      │
+│ (updated)        │            │ (completed)       │
+│ [x] Phase 1      │            │ ✓ completed       │
+│ [ ] Phase 2      │            │ ◼ in_progress     │
+└──────────────────┘            └───────────────────┘
+```
+
+- **Hydrate:** Read plan files → TaskCreate per unchecked `[ ]` item
+- **Work:** TaskUpdate tracks in_progress/completed in real-time
+- **Sync-back:** Update `[ ]` → `[x]` in phase files, update plan.md frontmatter status
+
+## When to Create Tasks
+
+**Default:** On — auto-hydrate after plan files are written
+**Skip with:** `--no-tasks` flag in planning request
+**3-Task Rule:** <3 phases → skip tasks (overhead exceeds benefit)
+
+| Scenario | Tasks? | Why |
+|----------|--------|-----|
+| Multi-phase feature (3+ phases) | Yes | Track progress, enable parallel |
+| Complex dependencies between phases | Yes | Automatic unblocking |
+| Plan will be executed by cook | Yes | Seamless handoff |
+| Single-phase quick fix | No | Just do it directly |
+| Trivial 1-2 step plan | No | Overhead not worth it |
+
+## Task Creation Patterns
+
+### Phase-Level TaskCreate
+
+```
+TaskCreate(
+  subject: "Setup environment and dependencies",
+  activeForm: "Setting up environment",
+  description: "Install packages, configure env, setup database. See phase-01-setup.md",
+  metadata: { phase: 1, priority: "P1", effort: "2h",
+              planDir: "plans/260205-auth/", phaseFile: "phase-01-setup.md" }
+)
+```
+
+### Critical Step TaskCreate
+
+For high-risk/complex steps within phases:
+
+```
+TaskCreate(
+  subject: "Implement OAuth2 token refresh",
+  activeForm: "Implementing token refresh",
+  description: "Handle token expiry, refresh flow, error recovery",
+  metadata: { phase: 3, step: "3.4", priority: "P1", effort: "1.5h",
+              planDir: "plans/260205-auth/", phaseFile: "phase-03-api.md",
+              critical: true, riskLevel: "high" },
+  addBlockedBy: ["{phase-2-task-id}"]
+)
+```
+
+## Metadata & Naming Conventions
+
+**Required metadata:** `phase`, `priority` (P1/P2/P3), `effort`, `planDir`, `phaseFile`
+**Optional metadata:** `step`, `critical`, `riskLevel`, `dependencies`
+
+**subject** (imperative): Action verb + deliverable, <60 chars
+- "Setup database migrations", "Implement OAuth2 flow", "Create user profile endpoints"
+
+**activeForm** (present continuous): Matches subject in -ing form
+- "Setting up database", "Implementing OAuth2", "Creating user profile endpoints"
+
+**description**: 1-2 sentences, concrete deliverables, reference phase file
+
+## Dependency Chains
+
+```
+Phase 1 (no blockers)              ← start here
+Phase 2 (addBlockedBy: [P1-id])    ← auto-unblocked when P1 completes
+Phase 3 (addBlockedBy: [P2-id])
+Step 3.4 (addBlockedBy: [P2-id])   ← critical steps share phase dependency
+```
+
+Use `addBlockedBy` for forward references ("I need X done first").
+Use `addBlocks` when creating parent first ("X blocks these children").
+
+## Cook Handoff Protocol
+
+### Same-Session (planning → cook immediately)
+
+1. Planning hydrates tasks → tasks exist in session
+2. Cook Step 3: `TaskList` → finds existing tasks → picks them up
+3. Cook skips re-creation, begins implementation directly
+
+### Cross-Session (new session, resume plan)
+
+1. User runs `/ck-cook path/to/plan.md` in new session
+2. Cook Step 3: `TaskList` → empty (tasks died with old session)
+3. Cook reads plan files → re-hydrates from unchecked `[ ]` items
+4. Already-checked `[x]` items = done, skip those
+
+### Sync-Back (cook Step 6)
+
+1. `TaskUpdate` marks all session tasks complete.
+2. `ck-project-manager` subagent runs full-plan sync-back:
+   - Sweep all `phase-XX-*.md` files.
+   - Reconcile completed tasks by metadata (`phase`, `phaseFile`).
+   - Backfill stale completed checkboxes `[ ]` → `[x]` across all phases (not only current phase).
+   - Update `plan.md` status/progress from actual checkbox state.
+3. If any completed task cannot be mapped to a phase file, report unresolved mappings before claiming completion.
+4. Git commit captures the state transition for next session.
+
+## Quality Checks
+
+After task hydration, verify:
+- Dependency chain has no cycles
+- All phases have corresponding tasks
+- Required metadata fields present (phase, priority, effort, planDir, phaseFile)
+- Task count matches unchecked `[ ]` items in plan files
+- Output: `✓ Hydrated [N] phase tasks + [M] critical step tasks with dependency chain`

package/skills/ck-planning/references/workflow-modes.md

@@ -0,0 +1,154 @@
+# Workflow Modes
+
+## Auto-Detection (Default: `--auto`)
+
+When no flag specified, analyze task and pick mode:
+
+| Signal | Mode | Rationale |
+|--------|------|-----------|
+| Simple task, clear scope, no unknowns | fast | Skip research overhead |
+| Complex task, unfamiliar domain, new tech | hard | Research needed |
+| 3+ independent features/layers/modules | parallel | Enable concurrent agents |
+| Ambiguous approach, multiple valid paths | two | Compare alternatives |
+
+Use asking the user if detection is uncertain.
+
+## Scope Challenge Integration
+
+Step 0 (Scope Challenge, see `scope-challenge.md`) runs before mode detection and can influence it:
+- If user selects **EXPANSION** → auto-suggest `--hard` or `--two`
+- If user selects **REDUCTION** → auto-suggest `--fast`
+- If user selects **HOLD** → proceed with auto-detected mode
+
+Mode can still be overridden by explicit flags (`--fast`, `--hard`, etc.).
+Scope challenge is skipped when `--fast` is explicitly set or task is trivial.
+
+## Fast Mode (`--fast`)
+
+No research. Analyze → Plan → Hydrate Tasks.
+
+1. Read codebase docs (`codebase-summary.md`, `code-standards.md`, `system-architecture.md`)
+2. Use `ck-planner` subagent to create plan
+3. Hydrate tasks (unless `--no-tasks`)
+4. **Context reminder:** `/ck-cook --auto {absolute-plan-path}/plan.md`
+
+**Why `--auto` cook flag?** Fast planning pairs with fast execution — skip review gates.
+
+## Hard Mode (`--hard`)
+
+Research → Scout → Plan → Red Team → Validate → Hydrate Tasks.
+
+1. Spawn max 2 `ck-researcher` agents in parallel (different aspects, max 5 calls each)
+2. Read codebase docs; if stale/missing: run `/ck-scout` to search codebase
+3. Gather research + scout report filepaths → pass to `ck-planner` subagent
+4. Post-plan red team review (see Red Team Review section below)
+5. Post-plan validation (see Validation section below)
+6. Hydrate tasks (unless `--no-tasks`)
+7. **Context reminder:** `/ck-cook {absolute-plan-path}/plan.md`
+
+**Why no cook flag?** Thorough planning needs interactive review gates.
+
+## Parallel Mode (`--parallel`)
+
+Research → Scout → Plan with file ownership → Red Team → Validate → Hydrate Tasks with dependency graph.
+
+1. Same as Hard mode steps 1-3
+2. Planner creates phases with:
+   - **Exclusive file ownership** per phase (no overlap)
+   - **Dependency matrix** (which phases run concurrently vs sequentially)
+   - **Conflict prevention** strategy
+3. plan.md includes: dependency graph, execution strategy, file ownership matrix
+4. Hydrate tasks: `addBlockedBy` for sequential deps, no blockers for parallel groups
+5. Post-plan red team review
+6. Post-plan validation
+7. **Context reminder:** `/ck-cook --parallel {absolute-plan-path}/plan.md`
+
+### Parallel Phase Requirements
+- Each phase self-contained, no runtime deps on other phases
+- Clear file boundaries — each file modified in ONE phase only
+- Group by: architectural layer, feature domain, or technology stack
+- Example: Phases 1-3 parallel (DB/API/UI), Phase 4 sequential (integration tests)
+
+## Two-Approach Mode (`--two`)
+
+Research → Scout → Plan 2 approaches → Compare → Hydrate Tasks.
+
+1. Same as Hard mode steps 1-3
+2. Planner creates 2 implementation approaches with:
+   - Clear trade-offs (pros/cons each)
+   - Recommended approach with rationale
+3. User selects approach
+4. Post-plan red team review on selected approach
+5. Post-plan validation
+6. Hydrate tasks for selected approach (unless `--no-tasks`)
+7. **Context reminder:** `/ck-cook {absolute-plan-path}/plan.md`
+
+## Task Hydration Per Mode
+
+| Mode | Task Granularity | Dependency Pattern |
+|------|------------------|--------------------|
+| fast | Phase-level only | Sequential chain |
+| hard | Phase + critical steps | Sequential + step deps |
+| parallel | Phase + steps + ownership | Parallel groups + sequential deps |
+| two | After user selects approach | Sequential chain |
+
+All modes: See `task-management.md` for TaskCreate patterns and metadata.
+
+## Post-Plan Red Team Review
+
+Adversarial review that spawns hostile reviewers to find flaws before validation.
+
+**Available in:** hard, parallel, two modes. **Skipped in:** fast mode.
+
+**Invocation:** Run `/ck-plan red-team {plan-directory-path}`.
+```
+/ck-plan red-team {plan-directory-path}
+```
+
+**Sequence:** Red team runs BEFORE validation because:
+1. Red team may change the plan (added risks, removed sections, new constraints)
+2. Validation should confirm the FINAL plan, not a pre-review draft
+3. Validating first then red-teaming would invalidate validation answers
+
+## Post-Plan Validation
+
+Check `## Plan Context` → `Validation: mode=X, questions=MIN-MAX`:
+
+| Mode | Behavior |
+|------|----------|
+| `prompt` | Ask: "Validate this plan with interview?" → Yes (Recommended) / No |
+| `auto` | Run `/ck-plan validate {plan-directory-path}` |
+| `off` | Skip validation |
+
+**Invocation (when prompt mode, user says yes):** Run:
+```
+/ck-plan validate {plan-directory-path}
+```
+
+**Available in:** hard, parallel, two modes. **Skipped in:** fast mode.
+
+## Context Reminder (MANDATORY)
+
+After plan creation, MUST output with **actual absolute path**:
+
+| Mode | Cook Command |
+|------|-----------------------------|
+| fast | `/ck-cook --auto {path}/plan.md` |
+| hard | `/ck-cook {path}/plan.md` |
+| parallel | `/ck-cook --parallel {path}/plan.md` |
+| two | `/ck-cook {path}/plan.md` |
+
+> **Best Practice:** Run `/clear` before implementing to reduce planning-context carryover.
+> Then run the cook command above.
+
+**Why absolute path?** After `/clear`, the new session loses previous context.
+This reminder is **NON-NEGOTIABLE** — always output after presenting the plan.
+
+## Pre-Creation Check
+
+Check `## Plan Context` in injected context:
+- **"Plan: {path}"** → Ask "Continue with existing plan? [Y/n]"
+- **"Suggested: {path}"** → Branch hint only, ask if activate or create new
+- **"Plan: none"** → Create new using `Plan dir:` from `## Naming`
+
+Pass plan directory path to every subagent during the process.

package/skills/ck-problem-solving/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: ck-problem-solving
+description: Apply systematic problem-solving techniques when stuck. Use for complexity spirals, innovation blocks, recurring patterns, assumption constraints, simplification cascades, scale uncertainty.
+argument-hint: "[problem description]"
+---
+
+# Problem-Solving Techniques
+
+Systematic approaches for different types of stuck-ness. Each technique targets specific problem patterns.
+
+## When to Use
+
+Apply when encountering:
+- **Complexity spiraling** - Multiple implementations, growing special cases, excessive branching
+- **Innovation blocks** - Conventional solutions inadequate, need breakthrough thinking
+- **Recurring patterns** - Same issue across domains, reinventing solutions
+- **Assumption constraints** - Forced into "only way", can't question premise
+- **Scale uncertainty** - Production readiness unclear, edge cases unknown
+- **General stuck-ness** - Unsure which technique applies
+
+## Quick Dispatch
+
+**Match symptom to technique:**
+
+| Stuck Symptom | Technique | Reference |
+|---------------|-----------|-----------|
+| Same thing implemented 5+ ways, growing special cases | **Simplification Cascades** | `references/simplification-cascades.md` |
+| Conventional solutions inadequate, need breakthrough | **Collision-Zone Thinking** | `references/collision-zone-thinking.md` |
+| Same issue in different places, reinventing wheels | **Meta-Pattern Recognition** | `references/meta-pattern-recognition.md` |
+| Solution feels forced, "must be done this way" | **Inversion Exercise** | `references/inversion-exercise.md` |
+| Will this work at production? Edge cases unclear? | **Scale Game** | `references/scale-game.md` |
+| Unsure which technique to use | **When Stuck** | `references/when-stuck.md` |
+
+## Core Techniques
+
+### 1. Simplification Cascades
+Find one insight eliminating multiple components. "If this is true, we don't need X, Y, Z."
+
+**Key insight:** Everything is a special case of one general pattern.
+
+**Red flag:** "Just need to add one more case..." (repeating forever)
+
+### 2. Collision-Zone Thinking
+Force unrelated concepts together to discover emergent properties. "What if we treated X like Y?"
+
+**Key insight:** Revolutionary ideas from deliberate metaphor-mixing.
+
+**Red flag:** "I've tried everything in this domain"
+
+### 3. Meta-Pattern Recognition
+Spot patterns appearing in 3+ domains to find universal principles.
+
+**Key insight:** Patterns in how patterns emerge reveal reusable abstractions.
+
+**Red flag:** "This problem is unique" (probably not)
+
+### 4. Inversion Exercise
+Flip core assumptions to reveal hidden constraints. "What if the opposite were true?"
+
+**Key insight:** Valid inversions reveal context-dependence of "rules."
+
+**Red flag:** "There's only one way to do this"
+
+### 5. Scale Game
+Test at extremes (1000x bigger/smaller, instant/year-long) to expose fundamental truths.
+
+**Key insight:** What works at one scale fails at another.
+
+**Red flag:** "Should scale fine" (without testing)
+
+## Application Process
+
+1. **Identify stuck-type** - Match symptom to technique above
+2. **Load detailed reference** - Read specific technique from `references/`
+3. **Apply systematically** - Follow technique's process
+4. **Document insights** - Record what worked/failed
+5. **Combine if needed** - Some problems need multiple techniques
+
+## Combining Techniques
+
+Powerful combinations:
+- **Simplification + Meta-pattern** - Find pattern, then simplify all instances
+- **Collision + Inversion** - Force metaphor, then invert its assumptions
+- **Scale + Simplification** - Extremes reveal what to eliminate
+- **Meta-pattern + Scale** - Universal patterns tested at extremes
+
+## References
+
+Load detailed guides as needed:
+- `references/when-stuck.md` - Dispatch flowchart and decision tree
+- `references/simplification-cascades.md` - Cascade detection and extraction
+- `references/collision-zone-thinking.md` - Metaphor collision process
+- `references/meta-pattern-recognition.md` - Pattern abstraction techniques
+- `references/inversion-exercise.md` - Assumption flipping methodology
+- `references/scale-game.md` - Extreme testing procedures
+- `references/attribution.md` - Source and adaptation notes

package/skills/ck-project-management/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: ck-project-management
+description: "Track progress, update plan statuses, manage Tasks, generate reports, coordinate docs updates. Use for project oversight, status checks, plan completion, task hydration, cross-session continuity."
+argument-hint: "[task: status, hydrate, sync, report]"
+---
+
+# Project Management
+
+Project oversight and coordination using native Tasks with persistent plan files.
+
+**Principles:** Token efficiency | Concise reports | Data-driven insights
+
+## When to Use
+
+- Checking project status or progress across plans
+- Updating plan statuses after feature completion
+- Hydrating/syncing Tasks with plan files
+- Generating status reports or summaries
+- Coordinating documentation updates after milestones
+- Verifying task completeness against acceptance criteria
+- Cross-session resume of multi-phase work
+
+## Tool Availability
+
+`TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList` are **CLI-only** — disabled in VSCode extension (`isTTY` check).
+
+| Environment | Task Tools | Fallback |
+|-------------|-----------|----------|
+| CLI terminal | Available | — |
+| VSCode extension | **Disabled** | `TodoWrite` |
+
+**Fallback behavior:** If Task tools error, use `TodoWrite` for progress tracking. Plan file sync-back (checkbox updates, YAML frontmatter) works identically without Task tools. Core PM workflow remains functional.
+
+## Core Capabilities
+
+### 1. Task Operations
+Load: `references/task-operations.md`
+
+Use `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList` to manage session-scoped tasks (CLI only; see Tool Availability above).
+- Create tasks with metadata (phase, priority, effort, planDir, phaseFile)
+- Track status: `pending` → `in_progress` → `completed`
+- Manage dependencies with `addBlockedBy` / `addBlocks`
+- Coordinate parallel agents with scoped ownership
+
+### 2. Session Bridging (Hydration Pattern)
+Load: `references/hydration-workflow.md`
+
+Tasks are ephemeral. Plan files are persistent. The hydration pattern bridges them:
+- **Hydrate:** Read plan `[ ]` items → `TaskCreate` per unchecked item
+- **Work:** `TaskUpdate` tracks progress in real-time
+- **Sync-back:** Reconcile all completed tasks against all phase files, update `[ ]` → `[x]`, update YAML frontmatter status
+- **Resume:** Next session re-hydrates from remaining `[ ]` items
+
+### 3. Progress Tracking
+Load: `references/progress-tracking.md`
+
+- Scan `./plans/*/plan.md` for active plans
+- Parse YAML frontmatter for status, priority, effort
+- Count `[x]` vs `[ ]` in phase files for completion %
+- Cross-reference completed work against planned tasks
+- Verify acceptance criteria met before marking complete
+
+### 4. Documentation Coordination
+Load: `references/documentation-triggers.md`
+
+Trigger `./docs` updates when:
+- Phase status changes, major features complete
+- API contracts change, architecture decisions made
+- Security patches applied, breaking changes occur
+
+Delegate to `ck-docs-manager` subagent for actual updates.
+
+### 5. Status Reporting
+Load: `references/reporting-patterns.md`
+
+Generate reports: session summaries, plan completion, multi-plan overviews.
+- Use naming: `{reports-path}/pm-{date}-{time}-{slug}.md`
+- Sacrifice grammar for brevity; use tables over prose
+- List unresolved questions at end
+
+## Workflow
+
+```
+[Scan Plans] → [Hydrate Tasks] → [Track Progress] → [Update Status] → [Generate Report] → [Trigger Doc Updates]
+```
+
+1. `TaskList()` — check existing tasks first
+2. If empty: hydrate from plan files (unchecked items)
+3. During work: `TaskUpdate` as tasks progress
+4. On completion: run full-plan sync-back (all phase files, including backfill for earlier phases), then update YAML frontmatter
+5. Generate status report to reports directory
+6. Delegate doc updates if changes warrant
+
+## Mandatory Sync-Back Guard
+
+When updating plan status, NEVER mark only the currently active phase.
+
+1. Sweep all `phase-XX-*.md` files under the target plan directory.
+2. Reconcile every `TaskUpdate(status: "completed")` item to phase metadata (`phase` / `phaseFile`).
+3. Backfill stale checkboxes in earlier phases before marking later phases done.
+4. Update `plan.md` status/progress from real checkbox counts.
+5. If any completed task cannot be mapped to a phase file, report unresolved mappings and do not claim full completion.
+
+## Plan YAML Frontmatter
+
+All `plan.md` files MUST have:
+
+```yaml
+---
+title: Feature name
+status: in-progress  # pending | in-progress | completed
+priority: P1
+effort: medium
+branch: feature-branch
+tags: [auth, api]
+created: 2026-02-05
+---
+```
+
+Update `status` when plan state changes.
+
+## Quality Standards
+
+- All analysis data-driven, referencing specific plans and reports
+- Focus on business value delivery and actionable insights
+- Highlight critical issues requiring immediate attention
+- Maintain traceability between requirements and implementation
+
+## Related Skills
+
+- `plan` — Creates implementation plans (planning phase)
+- `ck-cook` — Implements plans (execution phase, invokes project-manager at finalize)
+- `plans-kanban` — Visual dashboard for plan viewing

package/skills/ck-project-management/references/documentation-triggers.md

@@ -0,0 +1,60 @@
+# Documentation Triggers
+
+## When to Update Docs
+
+MUST update project documentation in `./docs` when:
+
+| Trigger | Which Docs | Action |
+|---------|-----------|--------|
+| Phase status changes | project-roadmap.md | Update progress %, milestone status |
+| Major feature complete | project-roadmap.md, codebase-summary.md | Add feature, update architecture |
+| Bug fix (significant) | project-roadmap.md | Document fix, severity, impact |
+| Security patch | project-roadmap.md, system-architecture.md | Record improvement |
+| API contract changes | system-architecture.md, code-standards.md | Update endpoints, schemas |
+| Architecture decision | system-architecture.md | Document decision + rationale |
+| Scope/timeline change | project-roadmap.md | Adjust phases, dates |
+| Dependencies updated | system-architecture.md | Record version changes |
+| Breaking changes | code-standards.md | Document migration path |
+
+## Documentation Files
+
+```
+./docs/
+├── project-overview-pdr.md     # Product requirements
+├── code-standards.md           # Coding conventions
+├── codebase-summary.md         # Architecture overview
+├── design-guidelines.md        # UI/UX standards
+├── deployment-guide.md         # Deploy procedures
+├── system-architecture.md      # System design
+└── project-roadmap.md          # Milestones & progress
+```
+
+## Update Protocol
+
+1. **Read current state:** Always read target doc before editing
+2. **Analyze reports:** Review agent reports in plan reports directory
+3. **Update content:** Modify progress %, statuses, dates, descriptions
+4. **Cross-reference:** Ensure consistency across docs
+5. **Validate:** Verify dates, versions, references accurate
+
+## Quality Standards
+
+- **Consistency:** Same formatting, versioning across all docs
+- **Accuracy:** Progress %, dates, statuses reflect reality
+- **Completeness:** Sufficient detail for stakeholder communication
+- **Timeliness:** Update within same session as significant changes
+- **Traceability:** Clear links between roadmap items and implementation
+
+## Delegation Pattern
+
+Use `ck-docs-manager` subagent for documentation updates:
+
+```
+Task(
+  subagent_type: "docs-manager",
+  prompt: "Update ./docs for [changes]. Work context: [path]",
+  description: "Update docs"
+)
+```
+
+Project manager coordinates WHEN to update; docs-manager handles HOW.