Do Work

Complete implementation workflow from exploration to commit.

Workflow

Phase 1: Explore & Plan

Phase 2: Implement

If you're touching code that interacts with the database, follow the DB TDD workflow.

If you're touching frontend code with complex state (creating/modifying reducers, complex state transitions, non-trivial state management), follow the Frontend TDD workflow.

Phase 3: Feedback Loops & Verification

Run each check, fix issues, and re-run until clean. Do these sequentially:

1. Type checking: npm run typecheck
2. Tests: npm test

If a check fails, fix the issue and re-run that check before moving to the next one. Do not move on with failing checks.

3. Verify Acceptance Criteria: Review the original sub-issue body. Ensure all acceptance criteria are met.
   • If the implementation is complex, consider invoking a subagent (e.g., research or self) or manually running the app to verify the end-to-end behavior matches what was promised.
   • Update the sub-issue on GitHub to check off the completed acceptance criteria boxes (e.g., replace [ ] with [x]).

Phase 4: Commit & Close

1. One Commit per Sub-Issue: Once all tests pass and criteria are verified, commit your work to the active branch following the rules in docs/committing.md.
2. Close Sub-Issue: If you were working on a GitHub sub-issue, close it using the GitHub CLI (gh issue close <issue-number>) at the end of your implementation run.
3. Push Commits: Push your branch to remote. If you are working on master, simply push. If you are on an agent branch, you may merge it to master and push if the milestone is complete.
4. Draft PR (Optional): Only open a Pull Request if the user explicitly requested a code review or a PR. If just commits are enough, do not create a PR. If the final sub-issue of a PRD is completed, manually close the parent PRD.

This skill runs unattended in CI. It picks one architectural improvement, publishes it as a PRD, and emits a structured <output> block for the driver script. No grilling, no HTML, no human in the loop.

Methodology

You are looking for deepening opportunities — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.

Glossary — use these terms exactly in the PRD

• Module — anything with an interface and an implementation (function, class, package, slice).
• Interface — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.
• Implementation — the code inside.
• Depth — leverage at the interface: a lot of behaviour behind a small interface. Deep = high leverage. Shallow = interface nearly as complex as the implementation.
• Seam — where an interface lives; a place behaviour can be altered without editing in place.
• Adapter — a concrete thing satisfying an interface at a seam.
• Leverage — what callers get from depth.
• Locality — what maintainers get from depth: change, bugs, knowledge concentrated in one place.

Key principles

• Deletion test — imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
• The interface is the test surface.
• One adapter = hypothetical seam. Two adapters = real seam.

Use CONTEXT.md vocabulary for domain language. Do not re-litigate decisions recorded under docs/adr/.

Process

1. Read prior proposals

gh issue list --label "source:architecture-review" --state all --limit 200 \
  --json number,title,body,state,labels

Read every result. Build a mental list of: which modules each prior PRD touches, what friction it addresses, and whether it was merged, closed-without-merge, or still open. All of these count as "already proposed" — the goal is novelty, not re-litigation.

If a prior proposal was closed-without-merge with a comment giving a load-bearing reason, treat that reason as binding: do not re-propose anything matching that reasoning.

2. Explore the codebase

Read CONTEXT.md and any relevant ADRs under docs/adr/ first.

Then use the Agent tool with subagent_type=Explore to walk the repo. Note friction organically:

• Where does understanding one concept require bouncing between many small modules?
• Where are modules shallow — interface nearly as complex as the implementation?
• Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no locality)?
• Where do tightly-coupled modules leak across their seams?
• Which parts of the codebase are untested, or hard to test through their current interface?

Apply the deletion test to anything you suspect is shallow.

3. Filter against prior proposals — loose-duplicate rule

A candidate is a duplicate if either:

• it touches substantially the same modules as a prior proposal, or
• it addresses the same underlying friction, even with a different angle.

When in doubt, treat it as a duplicate. The goal is one fresh proposal per run — duplicates spam the backlog.

4. Pick the single top candidate

Internally generate 3-5 candidates, rank them, pick one. Rank on:

• Leverage — how much downstream code benefits
• Locality gain — how much complexity gets concentrated
• Test surface improvement — does the deepened interface make tests cleaner?
• Cost-to-value — small refactors that unlock a lot beat sprawling rewrites

If every reasonable candidate is a duplicate, skip (see step 6).

5. Format the PRD using /to-prd-project — but do NOT publish

Follow the /to-prd-project skill to produce the PRD content: same template (Problem Statement, Solution, User Stories, Implementation Decisions, Testing Decisions, Out of Scope, Further Notes) and same writing discipline.

Critical override: do not run gh issue create. The workflow publishes the issue itself so that creation and labelling are atomic. Your job is to write the title and body; the workflow handles the GitHub mutation.

In addition to the standard PRD-template sections, the body must include an Architecture review section at the top with:

• Files — which modules are involved
• Problem — the friction in current architecture, in CONTEXT.md + glossary vocabulary above
• Solution — what changes, in plain English
• Benefits — framed in terms of locality and leverage; how tests improve
• Before / After diagram — a fenced mermaid block showing the shallow → deep transition. GitHub renders Mermaid natively in issue bodies.
• Recommendation strength — Strong, Worth exploring, or Speculative

6. Emit structured output

The driver script parses a single <output> block at the end of your response.

On success (a fresh proposal was found):

<output>
{
  "status": "proposed",
  "title": "<the PRD title — short, imperative, < 80 chars>",
  "body": "<the full PRD markdown body, including the Architecture review section and all standard PRD-template sections>",
  "oneLineSummary": "<one sentence describing the proposal, for the workflow run summary>",
  "candidatesConsidered": [
    "<one-line description of candidate 1>",
    "<one-line description of candidate 2>",
    "<one-line description of candidate 3>"
  ]
}
</output>

The workflow takes title + body and runs gh issue create --label "source:architecture-review". Do not call gh issue create yourself.

If every reasonable candidate was already proposed:

<output>
{
  "status": "skipped",
  "reason": "<one or two sentences naming the candidates considered and which prior issues blocked them>"
}
</output>

Rules

• Read-only everywhere. No commits, no edits to CONTEXT.md / ADRs / source files, no gh issue create, no gh issue edit. The workflow does the publish. If you spot a stale doc, mention it inside the PRD body — don't edit it.
• One proposal per run. Never publish more than one PRD in a single invocation.
• No grilling, no questions. There is no user. Make the call and emit the <output> block.

Optimize Loader

Anti-patterns to catch

1. Re-fetching data the caller already has

If a loader fetches a record (e.g. getVideoWithClipsById) and then passes just the ID to a downstream function that re-fetches the same record internally — change the downstream function's signature to accept the already-fetched object.

// BAD — getNextVideoId internally calls getVideoWithClipsById again
const video = yield * db.getVideoWithClipsById(videoId)
const nextId = yield * db.getNextVideoId(videoId)

// GOOD — pass the already-fetched video
const video = yield * db.getVideoWithClipsById(videoId)
const nextId = yield * db.getNextVideoId(video)

When refactoring signatures, type the parameter as the minimal shape needed, not the full return type:

// Accept only what the function actually reads
function* (currentVideo: {
  id: string;
  lesson: {
    id: string;
    videos: Array<{ id: string; path: string }>;
    section: { repoVersion: { repo: { id: string } } };
  } | null;
})

2. Over-fetching nested relations

If a function only needs IDs and paths for navigation but loads full nested trees including clips, transcripts, etc. — create a slim query variant.

// BAD — loads clips, chapters, thumbnails etc. just to get video IDs
const course = yield * getCourseWithSectionsById(repoId)

// GOOD — dedicated lightweight query
const course = yield * getCourseNavigationData(repoId)

Slim query checklist:

• columns: { id: true, path: true } — only select needed columns on leaf relations
• limit: 1 on relations like versions where you only need the latest
• Omit with: for relations you don't traverse (clips, chapters, thumbnails)
• Keep where: filters (e.g. archived = false) and orderBy intact

3. Sequential independent queries

If a loader runs multiple independent DB calls sequentially, parallelize with Effect.all:

// BAD — sequential, total time = sum of both
const nextVideoId = yield * db.getNextVideoId(video)
const previousVideoId = yield * db.getPreviousVideoId(video)

// GOOD — parallel, total time = max of both
const [nextVideoId, previousVideoId] =
  yield * Effect.all([db.getNextVideoId(video), db.getPreviousVideoId(video)])

Dependency injection pattern

When adding a new query (like getCourseNavigationData) that lives in course operations but is used by video operations:

1. Add the query to db-course-operations.server.ts and export it
2. Declare the cross-domain dependency in VideoOperationsService's effect block via yield* CourseOperationsService
3. The Effect Layer system resolves cross-domain dependencies automatically

Project Rules & Best Practices

First Step: Orient Yourself

Before doing anything else, read docs/plans.md. It contains the current project status and the ordered list of next tasks. Start from the top incomplete item unless the user directs otherwise.

CRITICAL RULE: Do NOT implement anything or produce any results. Your sole responsibility during this initialization phase is to just outline what's next in the plan for the user to review.

Writing Style

• Do not use emojis anywhere in code, comments, or documentation.
• Do not use em dashes. Use commas, periods, or parentheses instead.
• Do not use semicolons in prose or documentation. In code, follow the project linter (no semicolons in TypeScript/JSX).
• Write clear, direct sentences. Prefer short statements over compound ones.

Code Quality & Architecture

• All code must be written in TypeScript with strict types. No any types unless absolutely unavoidable and documented with a comment explaining why.
• Feature-Driven Architecture: Organize code into app/features/ (e.g., features/uploader, features/converter, features/animator) rather than large monolithic folders.
• Zod for Validation: Use zod strictly for all data boundary validations, including API requests, form submissions, and environment variables.
• Define explicit interfaces and types for all props, state, data structures, and API responses.
• Export types from dedicated type files when shared across components.
• Use a headless UI approach (like Radix Primitives) coupled with Tailwind CSS for accessible, customizable components.

Documentation System: Docs vs. References

This project maintains strict documentation to govern AI behavior and architectural decisions. You must distinguish between Global Project Docs and Skill References.

1. Global Project Docs (docs/)

The root docs/ folder contains universal project rules (e.g., folder structure, color schemes, deployment). CRITICAL RULE: You MUST thoroughly read, internalize, and strictly adhere to ALL of the files in docs/ before making structural changes. As the architecture evolves, you MUST update these files. Do not hallucinate details—fill them out iteratively.

DYNAMIC DOCUMENTATION: The docs/ folder contains template files. As you build new components, establish design patterns, or configure deployment, you MUST gradually fill in these templates with accurate, updated information for the project. Do not leave them blank if you make architectural decisions, but do not hallucinate details—fill them out iteratively or when explicitly asked by the user.

COMMIT RULE: Any time you edit a file in docs/, a skill in .agents/skills/, or any README, you MUST commit that change before moving on. Follow the rules in docs/committing.md. Do not batch doc-only changes with code changes.

• Project Structure: Rules for directory organization, co-location, and forbidding barrel files / default boilerplates.
• Naming & Component Conventions: Rules for file naming (PascalCase vs camelCase) and React component purity.
• Committing Rules: Rules for writing git commit messages.
• Styling & Design Strategy: Rules for Tailwind CSS usage and the strict color token system.
• Color Scheme: The exact hex codes, visual swatches, and hierarchy of the project's color palette.
• Future Plans: The roadmap of feature ideas and enhancements to be implemented.
• Future Improvements: Planned enhancements beyond the current milestones (color SVG, vtracer, etc.). Not needed for current work, read only if explicitly relevant to the task.
• Running Locally: Instructions for starting the development server across OS environments.
• Deployment: Vercel deployment configurations and build commands.

2. Skill References (.agents/skills/<skill-name>/references/)

For deep-dive technical guidelines specific to an individual skill (e.g., exact instructions on how to use Potrace or Anime.js), store them in a references/ subdirectory inside the relevant skill folder. CRITICAL RULE: Do NOT bloat this SKILL.md file or the global docs/ folder with highly specific technical tutorials. Instead, place them in references/ and instruct agents to read them when the skill is invoked.

Styling & Tailwind Tokens

• Centralized Tokens: We use Tailwind CSS v4 tokens defined centrally in app/app.css. Use existing color, spacing, radius, and typography tokens before adding new values.
• Reference docs/styling.md: For implementation details, token hierarchy, component styling rules, and the current visual direction, consult and follow docs/styling.md.

Tailwind Design System (v4)

Build production-ready design systems with Tailwind CSS v4, including CSS-first configuration, design tokens, component variants, responsive patterns, and accessibility.

Note: This skill targets Tailwind CSS v4 (2024+). For v3 projects, refer to the upgrade guide.

When to Use This Skill

• Creating a component library with Tailwind v4
• Implementing design tokens and theming with CSS-first configuration
• Building responsive and accessible components
• Standardizing UI patterns across a codebase
• Migrating from Tailwind v3 to v4
• Setting up dark mode with native CSS features

Key v4 Changes

Quick Start

/* app.css - Tailwind v4 CSS-first configuration */
@import "tailwindcss";

/* Define your theme with @theme */
@theme {
  /* Semantic color tokens using OKLCH for better color perception */
  --color-background: oklch(100% 0 0);
  --color-foreground: oklch(14.5% 0.025 264);

  --color-primary: oklch(14.5% 0.025 264);
  --color-primary-foreground: oklch(98% 0.01 264);

  --color-secondary: oklch(96% 0.01 264);
  --color-secondary-foreground: oklch(14.5% 0.025 264);

  --color-muted: oklch(96% 0.01 264);
  --color-muted-foreground: oklch(46% 0.02 264);

  --color-accent: oklch(96% 0.01 264);
  --color-accent-foreground: oklch(14.5% 0.025 264);

  --color-destructive: oklch(53% 0.22 27);
  --color-destructive-foreground: oklch(98% 0.01 264);

  --color-border: oklch(91% 0.01 264);
  --color-ring: oklch(14.5% 0.025 264);

  --color-card: oklch(100% 0 0);
  --color-card-foreground: oklch(14.5% 0.025 264);

  /* Ring offset for focus states */
  --color-ring-offset: oklch(100% 0 0);

  /* Radius tokens */
  --radius-sm: 0.25rem;
  --radius-md: 0.375rem;
  --radius-lg: 0.5rem;
  --radius-xl: 0.75rem;

  /* Animation tokens - keyframes inside @theme are output when referenced by --animate-* variables */
  --animate-fade-in: fade-in 0.2s ease-out;
  --animate-fade-out: fade-out 0.2s ease-in;
  --animate-slide-in: slide-in 0.3s ease-out;
  --animate-slide-out: slide-out 0.3s ease-in;

  @keyframes fade-in {
    from {
      opacity: 0;
    }
    to {
      opacity: 1;
    }
  }

  @keyframes fade-out {
    from {
      opacity: 1;
    }
    to {
      opacity: 0;
    }
  }

  @keyframes slide-in {
    from {
      transform: translateY(-0.5rem);
      opacity: 0;
    }
    to {
      transform: translateY(0);
      opacity: 1;
    }
  }

  @keyframes slide-out {
    from {
      transform: translateY(0);
      opacity: 1;
    }
    to {
      transform: translateY(-0.5rem);
      opacity: 0;
    }
  }
}

/* Dark mode variant - use @custom-variant for class-based dark mode */
@custom-variant dark (&:where(.dark, .dark *));

/* Dark mode theme overrides */
.dark {
  --color-background: oklch(14.5% 0.025 264);
  --color-foreground: oklch(98% 0.01 264);

  --color-primary: oklch(98% 0.01 264);
  --color-primary-foreground: oklch(14.5% 0.025 264);

  --color-secondary: oklch(22% 0.02 264);
  --color-secondary-foreground: oklch(98% 0.01 264);

  --color-muted: oklch(22% 0.02 264);
  --color-muted-foreground: oklch(65% 0.02 264);

  --color-accent: oklch(22% 0.02 264);
  --color-accent-foreground: oklch(98% 0.01 264);

  --color-destructive: oklch(42% 0.15 27);
  --color-destructive-foreground: oklch(98% 0.01 264);

  --color-border: oklch(22% 0.02 264);
  --color-ring: oklch(83% 0.02 264);

  --color-card: oklch(14.5% 0.025 264);
  --color-card-foreground: oklch(98% 0.01 264);

  --color-ring-offset: oklch(14.5% 0.025 264);
}

/* Base styles */
@layer base {
  * {
    @apply border-border;
  }

  body {
    @apply bg-background text-foreground antialiased;
  }
}

Core Concepts

1. Design Token Hierarchy

Brand Tokens (abstract)
    └── Semantic Tokens (purpose)
        └── Component Tokens (specific)

Example:
    oklch(45% 0.2 260) → --color-primary → bg-primary

2. Component Architecture

Base styles → Variants → Sizes → States → Overrides

Detailed patterns and worked examples

Detailed pattern documentation lives in references/details.md. Read that file when the navigation tier above is insufficient.

To Issues (project)

Break a parent PRD into a flat list of native GitHub sub-issues, in execution order. Each sub-issue is a tracer-bullet vertical slice that the PRD-mode agent:implement workflow will pick up one at a time.

Inputs

• Argument: the parent PRD's issue number. If the user invoked the skill without one, ask for it (or for a URL).
• Conversation context (optional): any planning that's already happened. Use it.

Process

1. Fetch the PRD

gh issue view <PRD_NUMBER> --comments

Read the body carefully. The PRD is the spec. Don't add scope; don't redesign. If the PRD is ambiguous, ask the user to clarify before drafting slices — the slices should reflect the PRD as-is, not your interpretation.

2. Confirm there are no existing sub-issues

gh api repos/$GH_REPO/issues/<PRD_NUMBER>/sub_issues --jq 'length'

If non-zero, stop and ask the user whether to (a) abort, (b) add more on top of what's there, or (c) close/delete the existing ones first. Don't silently double up.

3. Explore the codebase (optional)

If you haven't already, explore the repo to understand the area you're touching. Use the project's domain glossary (CONTEXT.md) and respect ADRs under docs/adr/. Sub-issue titles and bodies should use the project's vocabulary.

Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change."

4. Draft vertical slices

Break the PRD into tracer-bullet sub-issues. Each slice is a thin vertical cut through every layer (schema → API → UI → tests), NOT a horizontal slice of one layer.

The PRD-mode workflow implements sub-issues one at a time, each in its own agent session, committing to a shared branch. Keep that in mind:

• Each slice must stand on its own in a single session — no slice should require state from a previous session beyond what's on the branch.
• A reasonable session can build a couple of files, write tests, and run typecheck/test. Don't draft slices that are unrealistic for one session.

5. Quiz the user

Present the proposed breakdown as a numbered list. For each slice, show:

• Title — short, imperative
• What it builds — one or two sentences
• Depends on — which earlier slice(s) it builds on (by position in the list), or "none"

Ask:

• Is the granularity right? (too coarse / too fine)
• Is the order right?
• Should any slices be merged, split, or dropped?

Iterate until the user approves.

6. Publish sub-issues to GitHub

Publish in order. For each slice:

1. Create the issue:

   gh issue create --title "<title>" --body "$(cat <<'EOF'
   <body — see template>
   EOF
   )"
   

   This prints the new issue URL. Capture the issue number.

2. Get its node ID (needed by the sub-issues API):

   gh api repos/$GH_REPO/issues/<sub_issue_number> --jq '.id'
   

   The .id field is the REST integer ID. Save it.

3. Attach as sub-issue of the PRD:

   gh api -X POST "repos/$GH_REPO/issues/<PRD_NUMBER>/sub_issues" \
     -f sub_issue_id=<sub_issue_id>
   

   This is the native sub-issues link — it shows up in the PRD's progress bar and is what the agent-implement-prd.yml workflow reads.

Do not apply agent:implement to the sub-issues — they're never labeled directly. The user (or you, if asked) adds agent:implement to the PRD when ready to start work.

7. Sub-issue body template

This skill writes a PRD and publishes it as a GitHub issue in a1stok/img2svg-animation. It does not apply agent:implement — labeling happens after sub-issues have been created.

Do NOT interview the user — just synthesize what you already know from the conversation. If context is thin, ask the user to talk through the problem first; don't run the skill on an empty plate.

Process

1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary (CONTEXT.md) and respect ADRs under docs/adr/ for areas you're touching.

2. Sketch the major modules you'd build or modify. Actively look for opportunities to extract deep modules that can be tested in isolation. A deep module encapsulates a lot of functionality behind a simple, testable interface that rarely changes.

   Check with the user that these modules match their expectations and which they want tests written for.

3. Write the PRD using the template below and publish it via gh issue create. Use a heredoc for the body. Do not apply agent:implement — that's reserved for after sub-issues exist. Add no labels unless the user asks.

4. Output the issue URL so the user can pass it to /to-issues-project next.

PRD template

The PRD will be read by:

• Humans deciding whether the plan is sound.
• /to-issues-project when breaking it into sub-issues.
• The PRD-mode implement workflow at the start of each sub-issue run (the prompt pulls in the PRD body for context).
• The review workflow when checking "does the PR match the spec?"

So the PRD must be a spec, not a sketch — concrete enough that a sub-issue agent can implement against it without re-deriving decisions.

After publishing

• Tell the user: "PRD published at <URL>. Run /to-issues-project <issue-number> to break it into sub-issues, then add agent:implement to start work."
• Do not add agent:implement yourself. The PRD has no sub-issues yet, so labeling it now would either silently bounce (regular single-issue workflow would try to run it as a leaf and might do unexpected work) or land in the wrong place. The user labels once sub-issues are in place.