@manhnv319/codexkit 0.1.0

package/.agents/skills/plan/references/task-management.md

@@ -0,0 +1,132 @@
+# Task Management Integration
+
+## Session-Scoped Reality
+
+Claude Tasks are **ephemeral** — they die when the session ends. `~/.codex/tasks/` holds lock files only, NOT task data. Plan files (plan.md, phase-XX.md with checkboxes) are the **persistent** layer.
+
+The **hydration pattern** bridges sessions:
+
+```
+┌──────────────────┐  Hydrate   ┌───────────────────┐
+│ Plan Files       │ ─────────► │ Claude 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. `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/.agents/skills/plan/references/validate-question-framework.md

@@ -0,0 +1,80 @@
+# Validation Question Framework
+
+## Question Categories
+
+| Category | Keywords to detect |
+|----------|-------------------|
+| **Architecture** | "approach", "pattern", "design", "structure", "database", "API" |
+| **Assumptions** | "assume", "expect", "should", "will", "must", "default" |
+| **Tradeoffs** | "tradeoff", "vs", "alternative", "option", "choice", "either/or" |
+| **Risks** | "risk", "might", "could fail", "dependency", "blocker", "concern" |
+| **Scope** | "phase", "MVP", "future", "out of scope", "nice to have" |
+
+## Question Format Rules
+
+- Each question must have 2-4 concrete options
+- Mark recommended option with "(Recommended)" suffix
+- "Other" option is automatic
+- Questions should surface implicit decisions
+
+## Example Questions
+
+Category: Architecture
+Question: "How should the validation results be persisted?"
+Options:
+1. Save to plan.md frontmatter (Recommended)
+2. Create validation-answers.md
+3. Don't persist
+
+Category: Assumptions
+Question: "The plan assumes API rate limiting is not needed. Is this correct?"
+Options:
+1. Yes, not needed for MVP
+2. No, add basic rate limiting now (Recommended)
+3. Defer to Phase 2
+
+## Validation Log Format
+
+```markdown
+## Validation Log
+
+### Session {N} — {YYYY-MM-DD}
+**Trigger:** {what prompted this validation}
+**Questions asked:** {count}
+
+#### Questions & Answers
+
+1. **[{Category}]** {full question text}
+   - Options: {A} | {B} | {C}
+   - **Answer:** {user's choice}
+   - **Custom input:** {verbatim "Other" text if applicable}
+   - **Rationale:** {why this decision matters}
+
+#### Confirmed Decisions
+- {decision}: {choice} — {brief why}
+
+#### Action Items
+- [ ] {specific change needed}
+
+#### Impact on Phases
+- Phase {N}: {what needs updating and why}
+```
+
+## Recording Rules
+
+- **Full question text**: exact question, not summary
+- **All options**: every option presented
+- **Verbatim custom input**: record "Other" text exactly
+- **Rationale**: explain why decision affects implementation
+- **Session numbering**: increment from last session
+- **Trigger**: state what prompted validation
+
+## Section Mapping for Phase Propagation
+
+| Change Type | Target Section |
+|-------------|----------------|
+| Requirements | Requirements |
+| Architecture | Architecture |
+| Scope | Overview / Implementation Steps |
+| Risk | Risk Assessment |
+| Unknown | Key Insights (new subsection) |

package/.agents/skills/plan/references/validate-workflow.md

@@ -0,0 +1,65 @@
+# Validate Workflow
+
+Interview the user with critical questions to validate assumptions, confirm decisions, and surface potential issues in an implementation plan before coding begins.
+
+## Plan Resolution
+
+1. If `$ARGUMENTS` provided → Use that path
+2. Else check `## Plan Context` section → Use active plan path
+3. If no plan found → Ask user to specify path or run `/ck:plan --hard` first
+
+## Configuration
+
+Check `## Plan Context` section for validation settings:
+- `mode` - Controls auto/prompt/off behavior
+- `questions` - Range like `3-8` (min-max)
+
+## Workflow
+
+### Step 1: Read Plan Files
+- `plan.md` - Overview and phases list
+- `phase-*.md` - All phase files
+- Look for decision points, assumptions, risks, tradeoffs
+
+### Step 2: Extract Question Topics
+Load: `references/validate-question-framework.md`
+
+### Step 3: Generate Questions
+For each detected topic, formulate a concrete question with 2-4 options.
+Mark recommended option with "(Recommended)" suffix.
+
+### Step 4: Interview User
+Use `AskUserQuestion` tool.
+- Use question count from `## Plan Context` validation settings
+- Group related questions (max 4 per tool call)
+- Focus on: assumptions, risks, tradeoffs, architecture
+
+### Step 5: Document Answers
+Add or append `## Validation Log` section in `plan.md`.
+Load: `references/validate-question-framework.md` for recording format.
+
+### Step 6: Propagate Changes to Phases
+Auto-propagate validation decisions to affected phase files.
+Add marker: `<!-- Updated: Validation Session N - {change} -->`
+
+## Output
+- Number of questions asked
+- Key decisions confirmed
+- Phase propagation results
+- Recommendation: proceed or revise
+
+## Next Steps (MANDATORY)
+Remind user with absolute path:
+> **Best Practice:** Run `/clear` before implementing to start with fresh context.
+> Then run:
+> ```
+> /ck:cook --auto {ABSOLUTE_PATH_TO_PLAN_DIR}/plan.md
+> ```
+> **Why `--auto`?** Plan was already validated — safe to skip review gates.
+> **Why absolute path?** After `/clear`, the new session loses context.
+> Fresh context helps Claude focus solely on implementation without planning context pollution.
+
+## Important Notes
+- Only ask about genuine decision points
+- If plan is simple, fewer than min questions is okay
+- Prioritize questions that could change implementation significantly

package/.agents/skills/plan/references/workflow-modes.md

@@ -0,0 +1,145 @@
+# 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 `AskUserQuestion` if detection is uncertain.
+
+## Fast Mode (`--fast`)
+
+No research. Analyze → Plan → Hydrate Tasks.
+
+1. Read codebase docs (`codebase-summary.md`, `code-standards.md`, `system-architecture.md`)
+2. Use `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 `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 `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:** Use the `Skill` tool to invoke `plan:red-team` with the plan directory path as argument:
+```
+Skill(skill: "ck:plan:red-team", args: "{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` | Use the `Skill` tool: `Skill(skill: "ck:plan:validate", args: "{plan-directory-path}")` |
+| `off` | Skip validation |
+
+**Invocation (when prompt mode, user says yes):** Use the `Skill` tool to invoke `plan:validate`:
+```
+Skill(skill: "ck:plan:validate", args: "{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 start fresh context.
+> Then run the cook command above.
+
+**Why absolute path?** After `/clear`, new session loses 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`
+
+After creating: `node .codex/scripts/set-active-plan.cjs {plan-dir}`
+Pass plan directory path to every subagent during the process.

package/.agents/skills/plans-kanban/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: ck:plans-kanban
+description: View plans dashboard with progress tracking and timeline visualization. Use for kanban boards, plan status overview, phase progress, milestone tracking, project visibility.
+argument-hint: "[plans-dir]"
+---
+
+# plans-kanban
+
+Plans dashboard server with progress tracking and timeline visualization.
+
+## ⚠️ Installation Required
+
+**This skill requires npm dependencies.** Run one of the following:
+
+```bash
+# Option 1: Install via Codex Kit CLI (recommended)
+ck init  # Runs install.sh which handles all skills
+
+# Option 2: Manual installation
+cd .agents/skills/plans-kanban
+npm install
+```
+
+**Dependencies:** `gray-matter`
+
+Without installation, you'll get **Error 500** when viewing plan details.
+
+## Purpose
+
+Visual dashboard for viewing plan directories with:
+- Progress tracking per plan
+- Timeline/Gantt visualization
+- Phase status indicators
+- Activity heatmap
+
+## Quick Start
+
+```bash
+# View plans dashboard
+node .agents/skills/plans-kanban/scripts/server.cjs \
+  --dir ./plans \
+  --open
+
+# Remote access (all interfaces)
+node .agents/skills/plans-kanban/scripts/server.cjs \
+  --dir ./plans \
+  --host 0.0.0.0 \
+  --open
+
+# Background mode
+node .agents/skills/plans-kanban/scripts/server.cjs \
+  --dir ./plans \
+  --background
+
+# Stop all running servers
+node .agents/skills/plans-kanban/scripts/server.cjs --stop
+```
+
+## Slash Command
+
+Use `$kanban` for quick access:
+
+```bash
+/kanban plans/           # View plans dashboard
+/kanban --stop           # Stop kanban server
+```
+
+## Features
+
+### Dashboard View
+- Plan cards with progress bars
+- Phase status breakdown (completed, in-progress, pending)
+- Last modified timestamps
+- Issue and branch links
+- Priority indicators
+
+### Timeline Visualization
+- Gantt-style timeline of plans
+- Duration tracking
+- Activity heatmap
+
+### Design
+- Glassmorphism UI with dark mode
+- Responsive grid layout
+- Warm accent colors
+
+## CLI Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--dir <path>` | Plans directory | - |
+| `--port <number>` | Server port | 3500 |
+| `--host <addr>` | Host to bind (`0.0.0.0` for remote) | localhost |
+| `--open` | Auto-open browser | false |
+| `--background` | Run in background | false |
+| `--stop` | Stop all servers | - |
+
+## Architecture
+
+```
+scripts/
+├── server.cjs               # Main entry point
+└── lib/
+    ├── port-finder.cjs      # Port allocation (3500-3550)
+    ├── process-mgr.cjs      # PID management
+    ├── http-server.cjs      # HTTP routing
+    ├── plan-parser.cjs      # Plan.md parsing
+    ├── plan-scanner.cjs     # Directory scanning
+    ├── plan-metadata-extractor.cjs  # Rich metadata
+    └── dashboard-renderer.cjs       # HTML generation
+
+assets/
+├── dashboard-template.html  # Dashboard HTML template
+├── dashboard.css           # Styles
+└── dashboard.js            # Client interactivity
+```
+
+## HTTP Routes
+
+| Route | Description |
+|-------|-------------|
+| `/` route or `$kanban` skill | Dashboard view |
+| `$kanban?dir=<path>` | Dashboard for specific directory |
+| `/api/plans` | JSON API for plans data |
+| `/api/plans?dir=<path>` | JSON API for specific directory |
+| `/assets/*` | Static assets |
+| `/file/*` | Local file serving |
+
+## Remote Access
+
+When using `--host 0.0.0.0`, the server auto-detects your local network IP:
+
+```json
+{
+  "success": true,
+  "url": "http://localhost:3500/kanban?dir=...",
+  "networkUrl": "http://192.168.2.75:3500/kanban?dir=...",
+  "port": 3500
+}
+```
+
+Use `networkUrl` to access from other devices on the same network.
+
+## Plan Structure
+
+The dashboard scans for directories containing `plan.md` files:
+
+```
+plans/
+├── 251215-feature-a/
+│   ├── plan.md              # Required - parsed for phases
+│   ├── phase-01-setup.md
+│   └── phase-02-impl.md
+├── 251214-feature-b/
+│   └── plan.md
+└── templates/               # Excluded by default
+```
+
+## Troubleshooting
+
+**Port in use**: Server auto-increments from 3500-3550
+
+**No plans found**: Ensure directories contain `plan.md` files
+
+**Remote access denied**: Use `--host 0.0.0.0` to bind all interfaces
+
+**PID files**: Located at `/tmp/plans-kanban-*.pid`