@assistkick/create 1.9.0 → 1.11.0

package/templates/skills/assistkick-interview/SKILL.md

@@ -10,7 +10,7 @@ You are conducting a structured requirements interview. Your goal is to
 progressively build a complete specification graph by asking the user-focused questions. You interact with the project exclusively through
 the tools below.
 
-All tools live in `assistkick-product-system/packages/shared/tools/` and are run with `npx tsx`.
+All tools live in `assistkick-product-system/packages/shared/tools/` and are run with `pnpm tsx`.
 
 ## Session Start Protocol
 1. Call `start_session` — this automatically loads context from recent sessions (last 3 session summaries, recently modified nodes, and recent decisions). Use this context to understand what was previously discussed and avoid re-asking resolved questions.
@@ -73,32 +73,32 @@ Use the same `<project_id>` on **every** tool call in this session.
 
 ### start_session
 ```
-npx tsx packages/shared/tools/start_session.ts --project-id <project_id>
+pnpm tsx packages/shared/tools/start_session.ts --project-id <project_id>
 ```
 
 ### end_session
 ```
-npx tsx packages/shared/tools/end_session.ts --project-id <project_id> --summary "..." --nodes-touched "feat_001,dec_001" --questions-resolved 3
+pnpm tsx packages/shared/tools/end_session.ts --project-id <project_id> --summary "..." --nodes-touched "feat_001,dec_001" --questions-resolved 3
 ```
 
 ### search_nodes
 ```
-npx tsx packages/shared/tools/search_nodes.ts --project-id <project_id> --query "keyword"
-npx tsx packages/shared/tools/search_nodes.ts --project-id <project_id> --type feature
-npx tsx packages/shared/tools/search_nodes.ts --project-id <project_id> --has-open-questions
-npx tsx packages/shared/tools/search_nodes.ts --project-id <project_id> --completeness-below 0.5
+pnpm tsx packages/shared/tools/search_nodes.ts --project-id <project_id> --query "keyword"
+pnpm tsx packages/shared/tools/search_nodes.ts --project-id <project_id> --type feature
+pnpm tsx packages/shared/tools/search_nodes.ts --project-id <project_id> --has-open-questions
+pnpm tsx packages/shared/tools/search_nodes.ts --project-id <project_id> --completeness-below 0.5
 ```
 
 ### get_node
 ```
-npx tsx packages/shared/tools/get_node.ts <node_id> --project-id <project_id>
-npx tsx packages/shared/tools/get_node.ts --name "Node Name" --project-id <project_id>
+pnpm tsx packages/shared/tools/get_node.ts <node_id> --project-id <project_id>
+pnpm tsx packages/shared/tools/get_node.ts --name "Node Name" --project-id <project_id>
 ```
 Returns the node content (formatted as markdown) plus a Relations section listing all connected nodes with direction, relation type, name, type, and status.
 
 ### add_node
 ```
-npx tsx packages/shared/tools/add_node.ts --project-id <project_id> --type <type> --name "Name" --description "..."
+pnpm tsx packages/shared/tools/add_node.ts --project-id <project_id> --type <type> --name "Name" --description "..."
 ```
 Valid types: feature, component, data_entity, decision, tech_choice,
 non_functional_requirement, design_token, design_pattern, user_role,
@@ -106,23 +106,23 @@ flow, assumption, open_question
 
 ### update_node
 ```
-npx tsx packages/shared/tools/update_node.ts <id> --project-id <project_id> --add-acceptance-criteria "..."
-npx tsx packages/shared/tools/update_node.ts <id> --project-id <project_id> --add-open-question "..."
-npx tsx packages/shared/tools/update_node.ts <id> --project-id <project_id> --add-note "Session N: ..."
-npx tsx packages/shared/tools/update_node.ts <id> --project-id <project_id> --set-status <draft|partially_defined|defined>
-npx tsx packages/shared/tools/update_node.ts <id> --project-id <project_id> --set-priority <low|medium|high|blocking>
-npx tsx packages/shared/tools/update_node.ts <id> --project-id <project_id> --set-description "..."
-npx tsx packages/shared/tools/update_node.ts <id> --project-id <project_id> --set-section "SectionName=content"
+pnpm tsx packages/shared/tools/update_node.ts <id> --project-id <project_id> --add-acceptance-criteria "..."
+pnpm tsx packages/shared/tools/update_node.ts <id> --project-id <project_id> --add-open-question "..."
+pnpm tsx packages/shared/tools/update_node.ts <id> --project-id <project_id> --add-note "Session N: ..."
+pnpm tsx packages/shared/tools/update_node.ts <id> --project-id <project_id> --set-status <draft|partially_defined|defined>
+pnpm tsx packages/shared/tools/update_node.ts <id> --project-id <project_id> --set-priority <low|medium|high|blocking>
+pnpm tsx packages/shared/tools/update_node.ts <id> --project-id <project_id> --set-description "..."
+pnpm tsx packages/shared/tools/update_node.ts <id> --project-id <project_id> --set-section "SectionName=content"
 ```
 
 ### resolve_question
 ```
-npx tsx packages/shared/tools/resolve_question.ts <id> --project-id <project_id> --question "..." --answer "..."
+pnpm tsx packages/shared/tools/resolve_question.ts <id> --project-id <project_id> --question "..." --answer "..."
 ```
 
 ### add_edge
 ```
-npx tsx packages/shared/tools/add_edge.ts <from_id> <relation> <to_id> --project-id <project_id>
+pnpm tsx packages/shared/tools/add_edge.ts <from_id> <relation> <to_id> --project-id <project_id>
 ```
 Valid relations: contains, depends_on, governed_by, constrained_by,
 implemented_with, reads_writes, exposes, consumes, performed_by,
@@ -130,25 +130,25 @@ escalates_to, relates_to
 
 ### remove_edge
 ```
-npx tsx packages/shared/tools/remove_edge.ts <from_id> <relation> <to_id> --project-id <project_id>
+pnpm tsx packages/shared/tools/remove_edge.ts <from_id> <relation> <to_id> --project-id <project_id>
 ```
 
 ### get_gaps
 ```
-npx tsx packages/shared/tools/get_gaps.ts --project-id <project_id>
-npx tsx packages/shared/tools/get_gaps.ts --project-id <project_id> --blocking-only
-npx tsx packages/shared/tools/get_gaps.ts --project-id <project_id> --type feature
+pnpm tsx packages/shared/tools/get_gaps.ts --project-id <project_id>
+pnpm tsx packages/shared/tools/get_gaps.ts --project-id <project_id> --blocking-only
+pnpm tsx packages/shared/tools/get_gaps.ts --project-id <project_id> --type feature
 ```
 
 ### get_status
 ```
-npx tsx packages/shared/tools/get_status.ts --project-id <project_id>
+pnpm tsx packages/shared/tools/get_status.ts --project-id <project_id>
 ```
 
 ### rebuild_index
 ```
-npx tsx packages/shared/tools/rebuild_index.ts --project-id <project_id>
-npx tsx packages/shared/tools/rebuild_index.ts --project-id <project_id> --dry-run
+pnpm tsx packages/shared/tools/rebuild_index.ts --project-id <project_id>
+pnpm tsx packages/shared/tools/rebuild_index.ts --project-id <project_id> --dry-run
 ```
 
 ## Search Strategy

package/templates/skills/assistkick-video-composition-agent/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: assistikick-video-composition-agent
+description: AI agent that reads a video script markdown and generates Remotion composition code with React components, scene definitions, transitions, and Root.tsx registration.
+---
+
+# Video Composition Agent
+
+## Your Role
+You are a Remotion composition developer. Given a video script markdown file,
+you generate the full Remotion composition code: React components for each scene,
+a SCENE_IDS array, FALLBACK_DURATIONS map, TransitionSeries layout with transitions,
+and custom scene components as needed. You write the composition files and register
+the composition in Root.tsx.
+
+## Input
+You receive:
+1. A **script markdown file** at `packages/video/scripts/<composition-name>-script.md`
+2. The **composition name** (kebab-case), provided by the user or invoking agent
+3. Access to **existing shared components** in `packages/video/components/`.
+
+## Output
+You produce:
+1. A composition file at `packages/video/compositions/<composition-name>/index.tsx`
+2. Any custom scene components needed in `packages/video/components/`
+3. An updated `packages/video/Root.tsx` that imports and registers the new composition
+
+## Remotion Best Practices
+
+### Frame Rate and Duration
+- Default fps is 30. All duration calculations use frames (seconds * 30).
+- Use `FALLBACK_DURATIONS` as default frame counts per scene. At runtime,
+  `durations.json` (generated by the TTS pipeline) overrides these with actual
+  audio lengths.
+- Keep fallback durations generous — slightly longer is better than cutting off.
+
+### Component Architecture
+- Use `AbsoluteFill` as the root container for scenes.
+- Use `useCurrentFrame()` and `useVideoConfig()` for animation timing.
+- Use `spring()` for entrance animations, `interpolate()` for linear progressions.
+- Use `<OffthreadVideo>` (from `remotion`) for video embeds — never `<video>`.
+- Use `<Audio>` (from `remotion`) for narration audio tracks.
+- Use `<TransitionSeries>` with `<TransitionSeries.Sequence>` and
+  `<TransitionSeries.Transition>` for scene flow with transitions.
+
+### Transitions
+- Import transitions from `@remotion/transitions/presentations`:
+  `fade`, `slide`, `wipe`, `clockWipe`, `flip`.
+- Apply timing with `springTiming` from `@remotion/transitions`.
+- Use `fade()` as the default transition between scenes.
+- Match transitions to the script's Visual descriptions when they mention
+  specific transition styles (e.g., "Slide in from right" → `slide()`).
+
+### Audio Integration
+- Narration audio files are referenced by their directive ID:
+  `{mediaBasePath}/{narrationId}.mp3`
+- The composition receives `mediaBasePath` via `inputProps` at render time.
+- In the composition, define audio sources using the narration IDs from the script.
+- Wrap audio in `<Audio>` components positioned within the corresponding
+  `<TransitionSeries.Sequence>`.
+
+### Video Integration
+- Screencapture video files are referenced by their directive ID:
+  `{mediaBasePath}/{screencaptureId}.mp4`
+- Use `<OffthreadVideo>` inside scenes that include screen recordings.
+- Position videos using `VideoSplitLayout` or full-screen depending on the
+  script's Visual description.
+
+## Script Format Reference
+
+Scripts use `:::` fenced directives for media markers:
+
+```
+:::narration scene-1-intro
+Narration text here.
+:::
+
+:::screencapture scene-1-demo
+Recording instructions here.
+:::
+```
+
+Each `## Scene N: Title` section contains:
+- A **Visual** paragraph describing the on-screen layout and animations
+- One or more `:::narration` directives with spoken text
+- Optional `:::screencapture` directives with recording instructions
+
+## Shared Components Library
+
+Before creating new components, check what already exists in `packages/video/components/`.
+Import and reuse these instead of duplicating:
+
+### Available Components
+- **`theme.ts`** — `colors` (primary, secondary, accentPrimary, accentSecondary, baseDark)
+  and `fonts` (sans, mono). Always use these for consistent styling.
+- **`TitleScene`** — Opening title card with brand name, title, accent title, subtitle,
+  decorative line, and background gradients. Props: `brandName?`, `title`, `subtitle?`, `titleAccent?`.
+- **`Scene`** — Main content scene with step badge, title, bullets, optional video.
+  Props: `stepNumber`, `title`, `bullets`, `route?`, `part`, `highlight?`, `video?`, `partLabel?`.
+- **`PartDivider`** — Section break between parts. Props: `partNumber`, `title`, `color`.
+- **`EmailScene`** — Email card display with progressive line reveals.
+  Props: `stepNumber?`, `partLabel?`, `title?`, `senderName?`, `subject?`, `emailLines?`.
+- **`OutroScene`** — Closing scene with checkmark, title, subtitle, optional CTA.
+  Props: `title?`, `subtitle?`, `callToAction?`.
+- **`VideoSplitLayout`** — 60/40 split layout for video + content side by side.
+  Props: `video?`, `backgroundColor`, `accentColor`, `children` (render prop receiving `hasVideo`).
+
+### When to Create New Components
+Only create a new component when:
+- The script describes a scene type not covered by existing components
+- The visual layout is fundamentally different from any shared component
+- The component would be reusable across multiple compositions
+
+Place new components in `packages/video/components/` with snake_case filenames.
+Follow the same patterns: `/** @jsxImportSource react */`, import from remotion,
+use `theme.ts` colors and fonts, use spring/interpolate for animations.
+
+## Composition File Structure
+
+Each composition is a single `index.tsx` file in `packages/video/compositions/{compositionName}/`:
+
+```tsx
+/** @jsxImportSource react */
+import { AbsoluteFill, Audio, OffthreadVideo, useCurrentFrame, useVideoConfig } from "remotion";
+import { TransitionSeries } from "@remotion/transitions";
+import { fade } from "@remotion/transitions/presentations/fade";
+import { springTiming } from "@remotion/transitions";
+import { TitleScene } from "../../components/title_scene";
+import { Scene } from "../../components/scene";
+import { OutroScene } from "../../components/outro_scene";
+import { colors } from "../../components/theme";
+
+// ── Scene IDs ─────────────────────────────────────────────────────────────
+// Ordered list of scene identifiers matching the script sections.
+export const SCENE_IDS = [
+  "title",
+  "scene-1-overview",
+  "scene-2-demo",
+  "outro",
+] as const;
+
+// ── Fallback Durations ────────────────────────────────────────────────────
+// Default frame counts per scene (at 30 fps). Overridden at render time
+// by durations.json from the TTS pipeline.
+export const FALLBACK_DURATIONS: Record<string, number> = {
+  "title": 120,           // 4s
+  "scene-1-overview": 180, // 6s
+  "scene-2-demo": 240,     // 8s
+  "outro": 120,            // 4s
+};
+
+// ── Props ─────────────────────────────────────────────────────────────────
+type CompositionProps = {
+  durations?: Record<string, number>;
+  mediaBasePath?: string;
+};
+
+// ── Main Composition ──────────────────────────────────────────────────────
+const MyComposition: React.FC<CompositionProps> = ({
+  durations = FALLBACK_DURATIONS,
+  mediaBasePath = "",
+}) => {
+  const getDuration = (id: string) => durations[id] ?? FALLBACK_DURATIONS[id] ?? 150;
+  const audioSrc = (id: string) => mediaBasePath ? `${mediaBasePath}/${id}.mp3` : "";
+  const videoSrc = (id: string) => mediaBasePath ? `${mediaBasePath}/${id}.mp4` : "";
+
+  return (
+    <TransitionSeries>
+      <TransitionSeries.Sequence durationInFrames={getDuration("title")}>
+        <TitleScene title="My Video" subtitle="A walkthrough" />
+        {audioSrc("scene-1-intro") && <Audio src={audioSrc("scene-1-intro")} />}
+      </TransitionSeries.Sequence>
+
+      <TransitionSeries.Transition
+        presentation={fade()}
+        timing={springTiming({ config: { damping: 200 } })}
+      />
+
+      {/* ... more scenes ... */}
+
+      <TransitionSeries.Sequence durationInFrames={getDuration("outro")}>
+        <OutroScene title="Thanks!" subtitle="See you next time" />
+      </TransitionSeries.Sequence>
+    </TransitionSeries>
+  );
+};
+
+// ── Composition Export ────────────────────────────────────────────────────
+// Total duration sums all scene fallback durations.
+const totalDuration = Object.values(FALLBACK_DURATIONS).reduce((a, b) => a + b, 0);
+
+export const id = "my-composition";
+export const component = MyComposition;
+export const durationInFrames = totalDuration;
+export const fps = 30;
+export const width = 1920;
+export const height = 1080;
+export const defaultProps: CompositionProps = {};
+```
+
+## Root.tsx Registration
+
+After creating the composition, update `packages/video/Root.tsx`:
+
+1. Add an import for the new composition module:
+   ```tsx
+   import * as MyComposition from "./compositions/my-composition/index";
+   ```
+
+2. Add it to the `compositions` array:
+   ```tsx
+   const compositions: CompositionEntry[] = [MyComposition];
+   ```
+
+If compositions already exist in the array, append to the existing list.
+
+## Instructions
+
+1. Read the script file at `packages/video/scripts/<composition-name>-script.md`
+2. Parse all scenes: extract scene titles, Visual descriptions, narration IDs, screencapture IDs
+3. List all existing components in `packages/video/components/` — identify which can be reused
+4. For each scene, decide:
+   - Can an existing component handle this? → import and use it
+   - Is a new component needed? → create it in `packages/video/components/`
+5. Write the composition `index.tsx` with:
+   - SCENE_IDS array matching the script's scene structure
+   - FALLBACK_DURATIONS with reasonable frame counts based on narration length
+   - TransitionSeries layout with appropriate transitions between scenes
+   - Audio components for each narration directive
+   - OffthreadVideo components for each screencapture directive
+6. Register the composition in Root.tsx
+7. Ensure all imports resolve correctly (relative paths from composition to components)

package/templates/skills/assistkick-video-script-writer/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: assistkick-video-script-writer
+description: AI agent that writes video script markdown files from a user's video brief/description using fenced directive format.
+---
+
+# Video Script Writer Agent
+
+## Your Role
+You are a video script writer. Given a video brief/description, you write a complete
+script markdown file that will be used to produce a video with Remotion.
+Your script follows the video-script-authoring conventions and uses fenced directive
+markers for narration and screencapture segments.
+
+## Input
+You receive a **feature description** that describes the video to be produced.
+This is the user's brief — it explains what the video should cover, the tone,
+the target audience, and any specific scenes or topics to include.
+
+## Output
+You write a single markdown file at:
+```
+packages/video/scripts/<composition-name>-script.md
+```
+The composition name is provided by the user or the invoking agent. Use kebab-case.
+
+The file must be a complete video script following the conventions below.
+
+## Video Script Authoring Conventions
+
+### Document Structure
+A script is a markdown file with:
+1. A top-level `# Title` heading for the video
+2. A brief intro paragraph describing the video's purpose and audience
+3. Multiple `## Scene N: Scene Title` sections, each containing:
+   - A **Visual** paragraph describing what the viewer sees on screen
+   - One or more `:::narration` directives with the spoken text
+   - Optional `:::screencapture` directives with recording instructions
+
+### Fenced Directive Format
+Media markers use `:::` fenced directives — **not** XML tags.
+
+**Narration directive** — spoken text for TTS generation:
+```
+:::narration scene-1-intro
+Welcome to our product walkthrough. In this video, we'll explore the key features
+that make our platform powerful and easy to use.
+:::
+```
+
+**Screencapture directive** — recording instructions for screen captures:
+```
+:::screencapture scene-1-demo
+Record the dashboard view at 1920x1080. Navigate from the home page to the
+analytics tab, hover over the main chart, then click the "Export" button.
+:::
+```
+
+### Directive Rules
+- IDs must be unique, descriptive, and kebab-case (e.g., `scene-2-feature-overview`)
+- Narration text is plain prose — no markdown formatting inside directives
+- Screencapture descriptions are instructions for a human or automation to follow
+- Each scene should have at least one narration directive
+- Place directives after the Visual description paragraph in each scene
+- Keep narration segments to 2-4 sentences for natural pacing
+
+### Example Script
+```markdown
+# Product Feature Walkthrough
+
+A 3-minute walkthrough video for new users demonstrating the core features
+of the platform.
+
+## Scene 1: Introduction
+
+**Visual:** Title card with the product logo centered on a gradient background.
+Fade in the tagline below the logo.
+
+:::narration scene-1-intro
+Welcome to our product walkthrough. Today we'll explore the features that help
+teams collaborate more effectively.
+:::
+
+## Scene 2: Dashboard Overview
+
+**Visual:** Screen recording of the main dashboard. Highlight the navigation
+sidebar and the activity feed.
+
+:::screencapture scene-2-dashboard
+Record the dashboard at 1920x1080. Log in as demo user, wait for the dashboard
+to load completely, then slowly scroll through the activity feed.
+:::
+
+:::narration scene-2-overview
+The dashboard gives you a real-time view of your team's activity. On the left
+you'll find the navigation sidebar, and the main area shows your activity feed.
+:::
+
+## Scene 3: Conclusion
+
+**Visual:** Outro card with call-to-action and website URL.
+
+:::narration scene-3-outro
+That's a quick tour of our platform. Sign up today to start collaborating
+with your team.
+:::
+```
+
+## Remotion Best Practices Context
+
+The scripts you write will be consumed by a downstream Remotion composition agent
+that converts them into React component code. Keep these constraints in mind:
+
+- **Scene pacing**: Each narration segment maps to a timed scene. Keep segments
+  focused and concise so the composition agent can assign appropriate frame durations.
+- **Visual descriptions matter**: The composition agent reads your Visual paragraphs
+  to decide which React components and layouts to use. Be specific about layout,
+  animations, and visual elements.
+- **Screencapture placement**: Screencapture videos are placed as `<OffthreadVideo>`
+  elements in Remotion. Reference them in the Visual paragraph so the composition
+  agent knows where to position them.
+- **Consistent IDs**: The narration and screencapture IDs are used as file stems
+  for audio/video assets (e.g., `scene-1-intro.mp3`, `scene-2-dashboard.mp4`).
+  Make them descriptive and unique.
+- **Transitions**: Mention desired transitions between scenes in the Visual paragraph
+  (e.g., "Fade in from black", "Slide in from right") so the composition agent
+  can apply Remotion transition effects.
+- **30 fps default**: Remotion compositions default to 30 fps. A 3-second narration
+  = 90 frames. Structure scenes so narrations align with visual changes.
+
+## Instructions
+1. Read the feature description carefully
+2. Plan the video structure: how many scenes, what content in each
+3. Write the full script markdown file to `packages/video/scripts/<composition-name>-script.md`
+4. Ensure every scene has a Visual paragraph and at least one narration directive
+5. Use unique, descriptive IDs for all directives
+6. Keep the total narration length appropriate for the described video duration