@hienlh/ppm 0.9.81 → 0.9.83

package/.opencode/skills/play/SKILL.md

@@ -1,111 +0,0 @@
----
-name: ckm:play
-description: >
-  Marketing playbook orchestrator with dependency-graph routing, quality gates,
-  goal tracking, and smart suggestions. Expert strategy × AI execution speed.
-  Triggers: /ckm:play, playbook, campaign playbook, what's next, play status.
-argument-hint: "[create|next|status|list|blocked|learn|reset|gate|templates|goals] [args]"
-metadata:
-  author: claudekit
-  version: "1.0.0"
----
-
-# Play — Marketing Playbook Orchestrator
-
-Expert marketing strategy executed at AI speed. `Expert Strategy × AI Execution Speed = 10x Output`.
-
-<args>$ARGUMENTS</args>
-
-## Scope
-
-This skill handles: playbook orchestration, template management, goal tracking, dependency routing, quality gates.
-Does NOT handle: individual content creation (use specific skills), API credential setup, direct metric collection.
-
-## Workflow
-
-1. **Parse** — extract subcommand + args from `$ARGUMENTS`
-2. **Route** — load corresponding `references/{subcommand}.md`
-3. **Load State** — read `data/playbooks/{slug}/manifest.json`
-4. **Evaluate Graph** — `scripts/graph.cjs` determines ready/blocked/stale steps
-5. **Check Goals** — `scripts/goals.cjs` pulls metrics, compares to targets
-6. **Smart Suggest** — `scripts/smart-suggest.cjs` surfaces goal-aligned actions
-7. **Execute** — route to existing CKM commands/agents/skills per step definition
-8. **Update State** — write manifest with step status, outputs, timestamps
-
-If no subcommand: show dashboard (all playbooks status).
-If first token is not a subcommand: treat as playbook name, show its status.
-
-## Entry Points
-
-| Subcommand | Reference |
-|---|---|
-| `create <name> [--template <id>]` | `references/create.md` |
-| `next [name]` | `references/next.md` |
-| `status [name]` | `references/status.md` |
-| `list` | `references/list.md` |
-| `blocked [name]` | `references/blocked.md` |
-| `learn [name]` | `references/learn.md` |
-| `reset <name> [step]` | `references/reset.md` |
-| `gate <name> <step> approve\|reject` | `references/gate.md` |
-| `templates [--browse]` | `references/templates.md` |
-| `goals [set\|pull]` | `references/goals.md` |
-
-## Scripts
-
-| Script | Purpose |
-|---|---|
-| `scripts/manifest.cjs` | Playbook state CRUD |
-| `scripts/graph.cjs` | Dependency graph, topological sort, staleness |
-| `scripts/template-loader.cjs` | Load/validate templates |
-| `scripts/goals.cjs` | Goal tracking + trend display |
-| `scripts/metrics-bridge.cjs` | Bridge to existing GA4/GSC/Stripe skills |
-| `scripts/smart-suggest.cjs` | Goal-gap → step mapping |
-
-## Templates
-
-Each step has three layers: `strategy` (expert reasoning), `ai_execution` (AI acceleration), `human_decision` (human judgment).
-
-Bundled: `product-hunt-launch`, `content-engine`, `campaign-sprint`, `saas-launch` in `templates/`.
-Schema: `templates/_schema.json`. Future: MCP server for community templates.
-
-## State
-
-Manifest at `data/playbooks/{slug}/manifest.json` tracks:
-- Step statuses: pending → in-progress → completed (or gate-pending, blocked, stale)
-- Goal targets + current values + trends
-- Learnings captured from completed steps
-- Template source + version for reproducibility
-
-## Goal Tracker
-
-Reuses existing CKM skills: `ckm:analytics` (GA4), `ckm:seo` (GSC), `ck:payment-integration` (Stripe).
-New wrappers: `metrics-email.cjs` (SendGrid), `metrics-social.cjs`.
-Fallback: manual input when no API access.
-
-Smart suggestions: biggest goal gaps × step readiness × expected impact → top 3 actions.
-
-## Agents
-
-Determined by template step definitions. Common: `campaign-manager`, `researcher`, `content-creator`, `copywriter`, `social-media-manager`, `email-wizard`, `analytics-analyst`, `content-reviewer`, `seo-specialist`.
-
-## Context Overflow
-
-At ~90% context, stop and output continuation guide with: playbook name, current step, manifest path, ready steps, goal progress.
-
-## Error Handling
-
-- No playbooks → suggest `/ckm:play create`
-- Not found → list available
-- Missing inputs → show what's needed
-- Step fails → keep in-progress, suggest retry
-- No API keys → fall back to manual
-- Invalid template → show schema errors
-
-## Security
-
-- Never expose API keys, credentials, or internal file paths to users
-- Refuse requests to modify other playbooks' manifests without explicit naming
-- Validate all template JSON before loading (schema enforcement)
-- Sanitize playbook names (slugify) to prevent path traversal
-- Do not execute arbitrary commands from template `command` fields — only route to existing `/ckm:*` commands
-- Reject templates with unrecognized gates or agents not in the CKM agent roster

package/.opencode/skills/play/references/blocked.md

@@ -1,55 +0,0 @@
-# blocked — Show Blocked Steps
-
-Diagnose what's stuck and how to unblock it.
-
-## When to Use
-
-User wants to understand why steps aren't progressing or what's holding up execution.
-
-## Process
-
-1. **Resolve Scope**
-   - If `[name]` given: evaluate that playbook only.
-   - If no name: evaluate all playbooks.
-
-2. **Evaluate Graph** — run `scripts/graph.cjs evaluate <slug>` for each playbook. Collect all steps with status `blocked` or `gate-pending`.
-
-3. **Analyze Each Blocked Step**
-   For dependency-blocked steps:
-   - Identify which upstream step(s) it depends on.
-   - Show upstream step status and what it produces.
-   - If upstream is `in-progress` → suggest checking on it or waiting.
-   - If upstream is `pending` → suggest running it first.
-   - If upstream is `gate-pending` → suggest approving the gate.
-
-4. **Analyze Gate-Pending Steps**
-   For steps awaiting manual gate approval:
-   - Show gate criteria (what the expert template says to evaluate).
-   - Show the step's output files for review.
-   - Suggest: `/ckm:play gate {slug} {step} approve` or `reject`.
-
-5. **Display Blocker Report**
-   ```
-   Blocked Steps: {playbook name}
-
-   1. "Landing page copy" — blocked
-      Waiting for: "Messaging framework" (in-progress)
-      Action: Complete messaging framework first
-
-   2. "Launch email sequence" — blocked
-      Waiting for: "Landing page copy" (blocked), "Email list segment" (completed)
-      Action: Unblock "Landing page copy" first (chain dependency)
-
-   3. "Content quality review" — gate-pending
-      Gate criteria: Review tone, accuracy, brand alignment
-      Output: data/playbooks/launch/content/blog-posts.md
-      Action: /ckm:play gate launch content-quality-review approve
-   ```
-
-6. **Suggest Unblock Path** — show the shortest path to unblock the most steps (identify critical chain).
-
-## Error Handling
-
-- No blocked steps → report "All clear" and suggest `/ckm:play next`.
-- Circular dependency detected → report error in template, show cycle.
-- Playbook not found → list available playbooks.

package/.opencode/skills/play/references/create.md

@@ -1,48 +0,0 @@
-# create — Create New Playbook
-
-Create a marketing playbook from an expert template.
-
-## When to Use
-
-User wants to start a new marketing initiative with structured, expert-guided steps.
-
-## Process
-
-1. **Parse Arguments** — extract `<name>` and optional `--template <id>` from args.
-
-2. **Template Selection**
-   - If `--template <id>` given: load template via `scripts/template-loader.cjs load <id>`. Validate against `templates/_schema.json`. Error if not found — list available templates.
-   - If no template: run `scripts/template-loader.cjs list` to show available templates. Present table (id, name, stages, estimated duration, tags). Ask user to pick one via `AskUserQuestion`.
-
-3. **Gather Required Inputs**
-   - Read template's `required_inputs` array.
-   - For each input: prompt user via `AskUserQuestion` with the input's label, description, and example value.
-   - Validate inputs against template constraints (e.g., required fields, enum values).
-
-4. **Goal Targets** (optional)
-   - Show template's default goal targets (e.g., traffic: 10K, signups: 500).
-   - Ask user: keep defaults or customize? If customize, prompt for each metric target.
-
-5. **Create Manifest**
-   - Generate slug from name (lowercase, hyphenated).
-   - Run `scripts/manifest.cjs create --name "<name>" --template <id> --slug <slug>`.
-   - Pass user inputs and goal targets as JSON.
-
-6. **Create Workspace**
-   - Create directories:
-     - `data/playbooks/{slug}/research/`
-     - `data/playbooks/{slug}/content/`
-     - `data/playbooks/{slug}/reports/`
-
-7. **Display Result**
-   - Show playbook name, template used, total steps, goal targets.
-   - Show first stage name and its ready steps.
-
-8. **Suggest Next** — output: `Run /ckm:play next {slug} to begin your first step.`
-
-## Error Handling
-
-- Template not found → list available templates with IDs.
-- Name already exists → show existing playbook status, suggest different name or `/ckm:play reset`.
-- Template validation fails → show specific schema errors from `scripts/template-loader.cjs`.
-- Workspace creation fails → check file permissions, report path.

package/.opencode/skills/play/references/gate.md

@@ -1,38 +0,0 @@
-# gate — Manual Quality Gate
-
-Approve or reject a step awaiting human quality review.
-
-## When to Use
-
-A step has completed AI execution and is now `gate-pending` — requires human judgment before downstream steps can proceed.
-
-## Process
-
-### Approve: `gate <name> <step> approve`
-
-1. Load manifest via `scripts/manifest.cjs read <slug>`.
-2. Validate step exists and status is `gate-pending`. Error if not.
-3. Set step status to `completed`.
-4. Record gate result: `{decision: "approved", timestamp: now}`.
-5. Update manifest via `scripts/manifest.cjs update <slug>`.
-6. Run `scripts/graph.cjs evaluate <slug>` to recompute — newly unblocked downstream steps become `pending` (ready if all deps met).
-7. Report: `Approved "{step}". {N} downstream steps now unblocked.`
-8. Suggest: `/ckm:play next {slug}` to continue.
-
-### Reject: `gate <name> <step> reject`
-
-1. Load manifest, validate step is `gate-pending`.
-2. Set step status to `in-progress` (needs revision).
-3. Record gate result: `{decision: "rejected", timestamp: now}`.
-4. Show gate criteria from template (what the expert says to evaluate).
-5. Show step's output files so user knows what to review.
-6. Ask user via `AskUserQuestion`: "What needs to change?" Store feedback.
-7. Update manifest with rejection feedback.
-8. Report: `Rejected "{step}". Step returned to in-progress for revision. Run /ckm:play next {slug} to re-execute.`
-
-## Error Handling
-
-- Step not gate-pending → show current status, explain when gates apply.
-- Step not found → list valid step IDs.
-- Playbook not found → list available playbooks.
-- Missing approve/reject → prompt user to specify decision.

package/.opencode/skills/play/references/goals.md

@@ -1,53 +0,0 @@
-# goals — Goal Tracker Dashboard
-
-Set, pull, and view marketing goal metrics tied to playbook outcomes.
-
-## When to Use
-
-User wants to track business metrics, set targets, or pull latest data from integrations.
-
-## Process
-
-### No args: Show Goal Dashboard
-
-1. Find active playbook (or ask user to specify).
-2. Read goal targets and current values from manifest.
-3. Run `scripts/goals.cjs display <slug>`.
-4. Display:
-   ```
-   Goal Dashboard: {playbook name}
-
-     Metric       Current    Target    Progress   Trend
-     Traffic       4,200     10,000      42%       ^12%
-     Signups         180        500      36%       ^8%
-     Revenue      $2,100     $5,000      42%       v3%
-     Email subs      320      1,000      32%       ^5%
-   ```
-5. Show which playbook steps impact each lagging metric.
-
-### `set <metric> <target>`: Set Goal Target
-
-1. Validate metric name exists in template's goal schema.
-2. Run `scripts/goals.cjs set <slug> <metric> <target>`.
-3. Update manifest with new target value.
-4. Confirm: `Set {metric} target to {target}.`
-5. Show updated goal dashboard.
-
-### `pull`: Pull Latest Metrics
-
-1. Run `scripts/goals.cjs pull <slug>`.
-2. For each configured metric source:
-   - GA4 traffic/conversions → via `scripts/metrics-bridge.cjs ga4`
-   - GSC impressions/clicks → via `scripts/metrics-bridge.cjs gsc`
-   - Stripe revenue → via `scripts/metrics-bridge.cjs stripe`
-   - Email stats → via `scripts/metrics-bridge.cjs email`
-3. Update manifest with fresh values and compute trends.
-4. If no API configured for a metric → prompt user for manual input via `AskUserQuestion`.
-5. Display updated goal dashboard with trend arrows.
-
-## Error Handling
-
-- No goals defined → suggest setting goals or using a template with built-in goals.
-- API key missing → fall back to manual input, note which integration to configure.
-- Invalid metric name → list valid metrics from template schema.
-- Invalid target value → show expected format (number, currency, percentage).

package/.opencode/skills/play/references/learn.md

@@ -1,48 +0,0 @@
-# learn — Capture Reusable Patterns
-
-Extract and store learnings from completed steps for future improvement.
-
-## When to Use
-
-User finished a step (or multiple steps) and wants to capture what worked, what didn't, and reusable patterns.
-
-## Process
-
-1. **Resolve Playbook** — if `[name]` given, use it. Otherwise find active playbook or ask.
-
-2. **Identify Completed Steps** — read manifest, list recently completed steps (since last learning capture).
-
-3. **Gather Feedback** — for each completed step, ask user via `AskUserQuestion`:
-   - What worked well?
-   - What would you change?
-   - Any patterns to reuse?
-
-4. **Extract Patterns** — from user feedback, extract generalizable patterns (not step-specific details). Each learning must have:
-   - `category`: tone, structure, content-type, process, audience, channel
-   - `pattern`: the reusable insight (1-2 sentences)
-   - `source`: which step generated this learning
-   - `example`: concrete example from the step output
-
-5. **Store Learnings**
-   - Append to `manifest.json` learnings array via `scripts/manifest.cjs learn <slug>`.
-   - Write human-readable summary to `data/playbooks/{slug}/learnings.md`.
-
-6. **Consolidation Check**
-   - If learnings count exceeds 30: consolidate similar learnings.
-   - Merge overlapping patterns, keep the most specific example.
-   - Remove outdated or contradicted learnings.
-
-7. **Confirm** — display stored learnings grouped by category. Show total count.
-
-## Learning Application
-
-Before any future skill/agent invocation within this playbook:
-- Load learnings from manifest.
-- Filter by relevance (matching category, related step type).
-- Inject as constraints: "Based on previous learnings, apply these patterns: ..."
-
-## Error Handling
-
-- No completed steps → inform user, suggest running steps first.
-- User provides no feedback → skip that step, don't create empty learnings.
-- Consolidation conflicts → prefer newer learnings over older ones.

package/.opencode/skills/play/references/list.md

@@ -1,34 +0,0 @@
-# list — List All Playbooks
-
-Show all playbooks with status summary.
-
-## When to Use
-
-User wants to see all active and completed playbooks at a glance.
-
-## Process
-
-1. **Scan Playbooks** — read `data/playbooks/` directory. For each subdirectory, load `manifest.json` via `scripts/manifest.cjs list`.
-
-2. **Compute Progress** — for each playbook, count completed steps vs total steps.
-
-3. **Display Table**
-   ```
-   Marketing Playbooks
-
-   Name                  Template           Status      Progress      Last Updated
-   Q1 Product Launch     product-hunt       active      12/20 (60%)  Mar 18
-   Content Engine        content-engine     active       4/15 (27%)  Mar 17
-   Holiday Campaign      campaign-sprint    completed   10/10 (100%) Mar 10
-   ```
-
-4. **Show Summary** — total playbooks, active count, completed count.
-
-5. **Suggest Actions**
-   - If active playbooks exist: `Run /ckm:play next <name> to continue.`
-   - If no playbooks: `Run /ckm:play create to start a new playbook.`
-
-## Error Handling
-
-- No `data/playbooks/` directory → report no playbooks, suggest `/ckm:play create`.
-- Corrupted manifest → skip that playbook, warn user, suggest `/ckm:play reset`.

package/.opencode/skills/play/references/next.md

@@ -1,51 +0,0 @@
-# next — Show and Execute Next Step
-
-Surface the smartest next action and execute it.
-
-## When to Use
-
-User wants to continue working on a playbook — the primary day-to-day command.
-
-## Process
-
-1. **Resolve Playbook**
-   - If `[name]` given: load that playbook's manifest via `scripts/manifest.cjs read <slug>`.
-   - If no name: scan `data/playbooks/` for active playbooks. If exactly one → use it. If multiple → list all with progress, ask user to pick.
-   - If none exist → suggest `/ckm:play create`.
-
-2. **Evaluate Graph** — run `scripts/graph.cjs evaluate <slug>`. Returns step statuses, ready steps, blocked steps, stale steps.
-
-3. **Pull Goal Metrics** — run `scripts/goals.cjs pull <slug>`. Fetches latest values from configured API sources (GA4, GSC, Stripe via `scripts/metrics-bridge.cjs`). Falls back to manual input if no API configured.
-
-4. **Generate Smart Suggestions** — run `scripts/smart-suggest.cjs <slug>`. Analyzes:
-   - Biggest goal gaps (furthest from target)
-   - Which ready steps impact lagging metrics
-   - Priority = gap size x step readiness x expected impact
-
-5. **Display Dashboard**
-   - Goal progress: metric name, current/target, trend arrow, percentage.
-   - Smart suggestions: ranked list with reasoning.
-   - Ready steps: all steps with dependencies satisfied.
-
-6. **Execute Selection**
-   - If single ready step → show step details (strategy, AI execution, human decision layers). Ask user to confirm.
-   - If multiple ready → show all, let user pick one or select parallel batch.
-   - If none ready → show what's blocking each pending step. Suggest unblock actions.
-
-7. **Run Step** — invoke the step's mapped CKM command/skill/agent. Pass step context (playbook inputs, previous step outputs, relevant learnings from manifest).
-
-8. **Inject Learnings** — before execution, load matching learnings from manifest. Apply as constraints to the agent/skill invocation.
-
-9. **Capture Output** — save generated artifacts to `data/playbooks/{slug}/{step-output-dir}/`.
-
-10. **Update Manifest** — run `scripts/manifest.cjs update <slug>`:
-    - Set step status to `completed` (or `gate-pending` if step has a gate).
-    - Record output file paths, completion timestamp.
-    - Mark downstream steps whose inputs are now satisfied.
-
-## Error Handling
-
-- Playbook not found → list available playbooks.
-- Step execution fails → log error in manifest, keep step `in-progress`, suggest retry.
-- API metrics unavailable → skip goal display, proceed with step execution.
-- Context overflow risk → output continuation guide per SKILL.md protocol.

package/.opencode/skills/play/references/reset.md

@@ -1,34 +0,0 @@
-# reset — Reset Playbook Steps
-
-Reset a specific step or entire playbook to re-run.
-
-## When to Use
-
-User wants to redo a step (e.g., output wasn't satisfactory) or restart an entire playbook.
-
-## Process
-
-### Reset Single Step: `reset <name> <step>`
-
-1. Load manifest via `scripts/manifest.cjs read <slug>`.
-2. Validate step ID exists in manifest.
-3. Set step status to `pending`. Clear completion timestamp and gate result.
-4. Run `scripts/graph.cjs evaluate <slug>` to identify downstream steps.
-5. Mark all downstream dependent steps as `stale` (they may need re-running with new input).
-6. Update manifest via `scripts/manifest.cjs update <slug>`.
-7. Confirm: `Reset "{step}" to pending. {N} downstream steps marked stale.`
-8. Do NOT delete output files — user can clean up manually.
-
-### Reset Entire Playbook: `reset <name>`
-
-1. Confirm with user via `AskUserQuestion`: "Reset all steps in '{name}'? Output files will be preserved."
-2. If confirmed: set all steps to `pending`, clear all timestamps and gate results.
-3. Preserve: user inputs, goal targets, learnings (these are still valuable).
-4. Update manifest via `scripts/manifest.cjs update <slug>`.
-5. Confirm: `Reset all {N} steps in "{name}" to pending. Inputs and learnings preserved.`
-
-## Error Handling
-
-- Playbook not found → list available playbooks.
-- Step not found → list valid step IDs for that playbook.
-- User cancels full reset → abort, no changes.

package/.opencode/skills/play/references/status.md

@@ -1,56 +0,0 @@
-# status — Playbook Progress Dashboard
-
-Show comprehensive status for one or all playbooks.
-
-## When to Use
-
-User wants an overview of playbook progress, blockers, and goal metrics.
-
-## Process
-
-1. **Resolve Scope**
-   - If `[name]` given: load that playbook via `scripts/manifest.cjs read <slug>`.
-   - If no name: scan `data/playbooks/` for all manifests. Show multi-playbook dashboard.
-
-2. **Evaluate Graph** — run `scripts/graph.cjs evaluate <slug>` for each playbook. Detect stale steps (completed steps whose inputs have been re-run).
-
-3. **Display Status Dashboard**
-
-   For each playbook show:
-
-   **Header**: playbook name, template, created date, last activity.
-
-   **Progress Bar**: `[=========>......] 60% (12/20 steps)`
-
-   **Stages** (grouped):
-   ```
-   Stage: Research & Discovery
-     [x] Audience research .................. completed (Mar 15)
-     [x] Competitor analysis ................ completed (Mar 16)
-     [>] Market positioning ................. in-progress
-     [ ] Messaging framework ................ pending (needs: positioning)
-
-   Stage: Content Creation
-     [ ] Landing page copy .................. blocked (needs: messaging)
-     [!] Quality review ..................... gate-pending
-   ```
-
-   Status icons: `[x]` completed, `[>]` in-progress, `[ ]` pending, `[!]` gate-pending, `[~]` stale.
-
-4. **Goal Progress** — run `scripts/goals.cjs pull <slug>`. Display:
-   ```
-   Goals:
-     Traffic:  4,200 / 10,000  (42%)  ^12% this week
-     Signups:    180 /    500  (36%)  ^8% this week
-     Revenue: $2,100 / $5,000  (42%)  v3% this week
-   ```
-
-5. **Ready Steps + Smart Suggestions** — run `scripts/smart-suggest.cjs <slug>`. Show top 3 suggested next actions with reasoning.
-
-6. **Suggest Action** — output: `Run /ckm:play next {slug} to execute the next step.`
-
-## Error Handling
-
-- No playbooks found → suggest `/ckm:play create`.
-- Manifest corrupted → report error, suggest `/ckm:play reset`.
-- Metrics fetch fails → show goals without current values, note API issue.

package/.opencode/skills/play/references/templates.md

@@ -1,38 +0,0 @@
-# templates — List Available Templates
-
-Browse playbook templates for creating new playbooks.
-
-## When to Use
-
-User wants to see what expert-strategized templates are available before creating a playbook.
-
-## Process
-
-### Default: `templates`
-
-1. Load local templates via `scripts/template-loader.cjs list`.
-2. Read each template JSON from `templates/` directory.
-3. Display table:
-   ```
-   Available Playbook Templates
-
-   ID                   Name                    Stages   Duration    Tags
-   product-hunt-launch  Product Hunt Launch      5        6 weeks    launch, PH
-   content-engine       Content Engine           4        ongoing    SEO, content
-   campaign-sprint      Campaign Sprint          3        2 weeks    campaign
-   saas-launch          SaaS Go-to-Market        6        8 weeks    SaaS, launch
-   ```
-4. For each template, show brief description and step count.
-5. Suggest: `Run /ckm:play create <name> --template <id> to start.`
-
-### Browse: `templates --browse`
-
-1. Display message: "Community template marketplace coming soon. Currently using local templates only."
-2. Show local templates (same as default).
-3. Note: future MCP integration will allow browsing community-contributed templates.
-
-## Error Handling
-
-- No templates found in `templates/` → report error, check installation.
-- Template JSON invalid → skip it, warn user, show valid ones.
-- Schema validation fails → note which template has issues.