@macpaw/cctk 1.0.0-beta.1

package/templates/claude/commands/plan/parallel.md

@@ -0,0 +1,129 @@
+---
+description: ⚡⚡⚡ Create detailed plan with parallel-executable phases
+argument-hint: [task]
+---
+
+Think strategically about parallelization.
+Activate `planning` skill.
+
+## Your mission
+<task>
+$ARGUMENTS
+</task>
+
+## Workflow
+1. Create a directory using naming pattern from `## Naming` section in injected context.
+   Make sure you pass the directory path to every subagent during the process.
+2. Follow strictly to the "Plan Creation & Organization" rules of `planning` skill.
+3. Use multiple `researcher` agents (max 2 agents) in parallel to research for this task:
+   Each agent research for a different aspect of the task and are allowed to perform max 5 tool calls.
+4. Analyze the codebase by reading `codebase-summary.md`, `code-standards.md`, `system-architecture.md` and `project-overview-pdr.md` file.
+   **ONLY PERFORM THIS FOLLOWING STEP IF `codebase-summary.md` is not available or older than 3 days**: Use `/scout <instructions>` slash command to search the codebase for files needed to complete the task.
+5. Main agent gathers all research and scout report filepaths, and pass them to `planner` subagent with the prompt to create a parallel-optimized implementation plan.
+6. Main agent receives the implementation plan from `planner` subagent, and ask user to review the plan
+
+## Post-Plan Validation (Optional)
+
+After plan creation, offer validation interview to confirm decisions before implementation.
+
+**Check `## Plan Context` → `Validation: mode=X, questions=MIN-MAX`:**
+
+| Mode | Behavior |
+|------|----------|
+| `prompt` | Ask user: "Validate this plan with a brief interview?" → Yes (Recommended) / No |
+| `auto` | Automatically execute `/plan:validate {plan-path}` |
+| `off` | Skip validation step entirely |
+
+**If mode is `prompt`:** Use `AskUserQuestion` tool with options above.
+**If user chooses validation or mode is `auto`:** Execute `/plan:validate {plan-path}` SlashCommand.
+
+## Special Requirements for Parallel Execution
+
+**CRITICAL:** The planner subagent must create phases that:
+1. **Can be executed independently** - Each phase should be self-contained with no runtime dependencies on other phases
+2. **Have clear boundaries** - No file overlap between phases (each file should only be modified in ONE phase)
+3. **Separate concerns logically** - Group by architectural layer, feature domain, or technology stack
+4. **Minimize coupling** - Phases should communicate through well-defined interfaces only
+5. **Include dependency matrix** - Clearly document which phases must run sequentially vs in parallel
+
+**Parallelization Strategy:**
+- Group frontend/backend/database work into separate phases when possible
+- Separate infrastructure setup from application logic
+- Isolate different feature domains (e.g., auth vs profile vs payments)
+- Split by file type/directory (e.g., components vs services vs models)
+- Create independent test phases per module
+
+**Phase Organization Example:**
+```
+Phase 01: Database Schema (can run independently)
+Phase 02: Backend API Layer (can run independently)
+Phase 03: Frontend Components (can run independently)
+Phase 04: Integration Tests (depends on 01, 02, 03)
+```
+
+## Output Requirements
+
+**Plan Directory Structure** (use `Plan dir:` from `## Naming` section)
+```
+{plan-dir}/
+├── research/
+│   ├── researcher-XX-report.md
+│   └── ...
+├── reports/
+│   ├── XX-report.md
+│   └── ...
+├── scout/
+│   ├── scout-XX-report.md
+│   └── ...
+├── plan.md
+├── phase-XX-phase-name-here.md
+└── ...
+```
+
+**Research Output Requirements**
+- Ensure every research markdown report remains concise (≤150 lines) while covering all requested topics and citations.
+
+**Plan File Specification**
+- Every `plan.md` MUST start with YAML frontmatter:
+  ```yaml
+  ---
+  title: "{Brief title}"
+  description: "{One sentence for card preview}"
+  status: pending
+  priority: P2
+  effort: {sum of phases, e.g., 4h}
+  branch: {current git branch}
+  tags: [relevant, tags]
+  created: {YYYY-MM-DD}
+  ---
+  ```
+- Save the overview access point at `{plan-dir}/plan.md`. Keep it generic, under 80 lines, and list each implementation phase with status, progress, parallelization group, and links to phase files.
+- For each phase, create `{plan-dir}/phase-XX-phase-name-here.md` containing the following sections in order:
+  - Context links (reference parent plan, dependencies, docs)
+  - **Parallelization Info** (which phases can run concurrently, which must wait)
+  - Overview (date, description, priority, implementation status, review status)
+  - Key Insights
+  - Requirements
+  - Architecture
+  - **Related code files** (MUST be exclusive to this phase - no overlap with other phases)
+  - **File Ownership** (explicit list of files this phase owns/modifies)
+  - Implementation Steps
+  - Todo list
+  - Success Criteria
+  - **Conflict Prevention** (how this phase avoids conflicts with parallel phases)
+  - Risk Assessment
+  - Security Considerations
+  - Next steps
+
+**Main plan.md must include:**
+- Dependency graph showing which phases can run in parallel
+- Execution strategy (e.g., "Phases 1-3 parallel, then Phase 4")
+- File ownership matrix (which phase owns which files)
+
+## Important Notes
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+**IMPORTANT:** Ensure token efficiency while maintaining high quality.
+**IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
+**IMPORTANT:** In reports, list any unresolved questions at the end, if any.
+**IMPORTANT:** Do not start implementing.
+**IMPORTANT:** Each phase MUST have exclusive file ownership - no file can be modified by multiple phases.

package/templates/claude/commands/plan/two.md

@@ -0,0 +1,45 @@
+---
+description: ⚡⚡⚡⚡ Research & create an implementation plan with 2 approaches
+argument-hint: [task]
+---
+
+Think harder.
+Activate `planning` skill.
+
+## Your mission
+Use the `planner` subagent to create 2 detailed implementation plans for this following task:
+<task>
+ $ARGUMENTS
+</task>
+
+## Workflow
+1. First: Create a directory using naming pattern from `## Naming` section in injected context.
+   Make sure you pass the directory path to every subagent during the process.
+2. Follow strictly to the "Plan Creation & Organization" rules of `planning` skill.
+3. Use multiple `researcher` agents in parallel to research for this task, each agent research for a different aspect of the task and perform max 5 researches (max 5 tool calls).
+4. Use `scout` agent to search the codebase for files needed to complete the task.
+5. Main agent gathers all research and scout report filepaths, and pass them to `planner` subagent with the detailed instructions prompt to create an implementation plan of this task.
+  **Output:** Provide at least 2 implementation approaches with clear trade-offs, and explain the pros and cons of each approach, and provide a recommended approach.
+1. Main agent receives the implementation plan from `planner` subagent, and ask user to review the plan
+
+## Plan File Specification
+- Every `plan.md` MUST start with YAML frontmatter:
+  ```yaml
+  ---
+  title: "{Brief title}"
+  description: "{One sentence for card preview}"
+  status: pending
+  priority: P2
+  effort: {sum of phases, e.g., 4h}
+  branch: {current git branch}
+  tags: [relevant, tags]
+  created: {YYYY-MM-DD}
+  ---
+  ```
+
+## Important Notes
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+**IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
+**IMPORTANT:** Ensure token efficiency while maintaining high quality.
+**IMPORTANT:** In reports, list any unresolved questions at the end, if any.
+**IMPORTANT**: **Do not** start implementing.

package/templates/claude/commands/plan/validate.md

@@ -0,0 +1,117 @@
+---
+description: Validate plan with critical questions interview
+argument-hint: [plan-path]
+---
+
+## Your mission
+
+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 `/plan:hard` first
+
+## Configuration (from injected context)
+
+Check `## Plan Context` section for validation settings:
+- `mode` - Controls auto/prompt/off behavior
+- `questions` - Range like `3-8` (min-max)
+
+These values are automatically injected from user config. Use them as constraints.
+
+## Workflow
+
+### Step 1: Read Plan Files
+
+Read the plan directory:
+- `plan.md` - Overview and phases list
+- `phase-*.md` - All phase files
+- Look for decision points, assumptions, risks, tradeoffs
+
+### Step 2: Extract Question Topics
+
+Scan plan content for:
+
+| 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" |
+
+### Step 3: Generate Questions
+
+For each detected topic, formulate a concrete question:
+
+**Question format rules:**
+- Each question must have 2-4 concrete options
+- Mark recommended option with "(Recommended)" suffix
+- Include "Other" option is automatic - don't add it
+- 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) - Updates existing plan
+2. Create validation-answers.md - Separate file for answers
+3. Don't persist - Ephemeral validation only
+```
+
+```
+Category: Assumptions
+Question: "The plan assumes API rate limiting is not needed. Is this correct?"
+Options:
+1. Yes, rate limiting not needed for MVP
+2. No, add basic rate limiting now (Recommended)
+3. Defer to Phase 2
+```
+
+### Step 4: Interview User
+
+Use `AskUserQuestion` tool to present questions.
+
+**Rules:**
+- Use question count from `## Plan Context` → `Validation: mode=X, questions=MIN-MAX`
+- Group related questions when possible (max 4 questions per tool call)
+- Focus on: assumptions, risks, tradeoffs, architecture
+
+### Step 5: Document Answers
+
+After collecting answers, update the plan:
+
+1. Add `## Validation Summary` section to `plan.md`:
+```markdown
+## Validation Summary
+
+**Validated:** {date}
+**Questions asked:** {count}
+
+### Confirmed Decisions
+- {decision 1}: {user choice}
+- {decision 2}: {user choice}
+
+### Action Items
+- [ ] {any changes needed based on answers}
+```
+
+2. If answers require plan changes, note them but **do not modify phase files** - just document what needs updating.
+
+## Output
+
+After validation completes, provide summary:
+- Number of questions asked
+- Key decisions confirmed
+- Any items flagged for plan revision
+- Recommendation: proceed to implementation or revise plan first
+
+## Important Notes
+
+**IMPORTANT:** Only ask questions about genuine decision points - don't manufacture artificial choices.
+**IMPORTANT:** If plan is simple with few decisions, it's okay to ask fewer than min questions.
+**IMPORTANT:** Prioritize questions that could change implementation significantly.

package/templates/claude/commands/plan.md

@@ -0,0 +1,30 @@
+---
+description: ⚡⚡⚡ Intelligent plan creation with prompt enhancement
+argument-hint: [task]
+---
+
+## Your mission
+<task>
+$ARGUMENTS
+</task>
+
+## Pre-Creation Check (Active vs Suggested Plan Detection)
+
+Check the `## Plan Context` section in the injected context:
+- If "Plan:" shows a path → Active plan exists. Ask user: "Active plan found: {path}. Continue with this? [Y/n]"
+- If "Suggested:" shows a path → Branch-matched plan hint only. Ask user if they want to activate it or create new.
+- If "Plan: none" → Proceed to create new plan using naming pattern from `## Naming` section.
+
+## Workflow
+- Analyze the given task and use `AskUserQuestion` tool to ask for more details if needed.
+- Decide to use `/plan:fast` or `/plan:hard` SlashCommands based on the complexity.
+- Execute SlashCommand: `/plan:fast <detailed-instructions-prompt>` or `/plan:hard <detailed-instructions-prompt>`
+- Activate `planning` skill.
+- Note: `detailed-instructions-prompt` is **an enhanced prompt** that describes the task in detail based on the provided task description.
+
+## Important Notes
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+**IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
+**IMPORTANT:** Ensure token efficiency while maintaining high quality.
+**IMPORTANT:** In reports, list any unresolved questions at the end, if any.
+**IMPORTANT**: **Do not** start implementing.

package/templates/claude/commands/preview.md

@@ -0,0 +1,87 @@
+---
+description: Path to markdown file, plan directory, or plans collection
+arguments:
+  - name: path
+    description: Path to file or directory to preview
+    required: false
+---
+
+Universal viewer using `markdown-novel-viewer` skill - pass ANY path and see it rendered nicely.
+
+## Usage
+
+- `/preview <file.md>` - View markdown file in novel-reader UI
+- `/preview <directory/>` - Browse directory contents
+- `/preview --stop` - Stop running server
+
+## Examples
+
+```bash
+/preview plans/my-plan/plan.md     # View markdown file
+/preview plans/                    # Browse plans directory
+/preview docs/                     # Browse docs directory
+/preview any/path/to/file.md      # View any markdown file
+/preview any/path/                 # Browse any directory
+```
+
+## Execution
+
+**IMPORTANT:** Run server as Claude Code background task using `run_in_background: true` with the Bash tool. This makes the server visible in `/tasks` and manageable via `KillShell`.
+
+Check if this script is located in the current workspace or in `$HOME/.claude/skills/markdown-novel-viewer` directory:
+- If in current workspace: `$SKILL_DIR_PATH` = `./.claude/skills/markdown-novel-viewer/`
+- If in home directory: `$SKILL_DIR_PATH` = `$HOME/.claude/skills/markdown-novel-viewer/`
+
+### Stop Server
+
+If `--stop` flag is provided:
+
+```bash
+node $SKILL_DIR_PATH/scripts/server.cjs --stop
+```
+
+### Start Server
+
+Otherwise, run the `markdown-novel-viewer` server as CC background task with `--foreground` flag (keeps process alive for CC task management):
+
+```bash
+# Determine if path is file or directory
+INPUT_PATH="{{path}}"
+if [[ -d "$INPUT_PATH" ]]; then
+  # Directory mode - browse
+  node $SKILL_DIR_PATH/scripts/server.cjs \
+    --dir "$INPUT_PATH" \
+    --host 0.0.0.0 \
+    --open \
+    --foreground
+else
+  # File mode - view markdown
+  node $SKILL_DIR_PATH/scripts/server.cjs \
+    --file "$INPUT_PATH" \
+    --host 0.0.0.0 \
+    --open \
+    --foreground
+fi
+```
+
+**Critical:** When calling the Bash tool:
+- Set `run_in_background: true` to run as CC background task
+- Set `timeout: 300000` (5 minutes) to prevent premature termination
+- Parse JSON output and report URL to user
+
+Example Bash tool call:
+```json
+{
+  "command": "node .claude/skills/markdown-novel-viewer/scripts/server.cjs --dir \"path\" --host 0.0.0.0 --open --foreground",
+  "run_in_background": true,
+  "timeout": 300000,
+  "description": "Start preview server in background"
+}
+```
+
+After starting, parse the JSON output (e.g., `{"success":true,"url":"http://localhost:3456/view?file=...","networkUrl":"http://192.168.1.x:3456/view?file=..."}`) and report:
+- Local URL for browser access
+- Network URL for remote device access (if available)
+- Inform user that server is now running as CC background task (visible in `/tasks`)
+
+**CRITICAL:** MUST display the FULL URL including path and query string (e.g., `http://localhost:3456/view?file=/path/to/file.md`). NEVER truncate to just `host:port` (e.g., `http://localhost:3456`). The full URL is required for direct file access.