OpenParable
Skip to content
← Back to skills

Sync Upstream Feature

Development
sync-upstream-feature

Sync Upstream Feature is an Agent Skill for development published in the Innei/Shiro repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when porting a feature from the closed-source Shiroi repo to the open-source Shiro repo. Triggers on "sync from upstream", "port feature from Shiroi", "bring X from Shiroi to Shiro", or any task requiring code migration between the two repos.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/Innei/Shiro/blob/HEAD/.claude/skills/sync-upstream-feature/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/sync-upstream-feature, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Sync Upstream Feature

Overview

Port features stripped during Shiroi-to-Shiro sync back into the open-source repo. The closed-source Shiroi repo lives at /Users/innei/git/innei-repo/Shiroi, the open-source Shiro at /Users/innei/git/innei-repo/Shiro.

Repo Layout

RepoPathRole
Shiro/Users/innei/git/innei-repo/ShiroOpen-source, primary working dir
Shiroi/Users/innei/git/innei-repo/ShiroiClosed-source upstream, read-only reference

Both share the same monorepo structure (apps/web/src/...). Shiroi is the superset.

Workflow

digraph sync {
  rankdir=TB;
  node [shape=box];

  explore [label="1. Explore: find target code in both repos"];
  diff [label="2. Diff: identify what Shiroi has that Shiro lacks"];
  layers [label="3. Map all touchpoints across layers"];
  deps [label="4. Add dependencies (package.json)"];
  core [label="5. Port core components"];
  integrate [label="6. Wire into routing (Content, Markdown, page)"];
  api [label="7. Sync API query params"];
  style [label="8. Sync conditional styling"];
  lint [label="9. Lint/typecheck modified files only"];
  review [label="10. Code review via Codex"];

  explore -> diff -> layers -> deps -> core -> integrate -> api -> style -> lint -> review;
}

1. Explore Both Repos

Use parallel Explore agents to search the target feature keyword in both repos. Identify:

  • Which files exist in Shiroi but not Shiro
  • Which files exist in both but differ
  • Which dependencies Shiroi has that Shiro lacks

2. Diff: Identify the Gap

Compare key files side-by-side. Focus on:

  • Component files: Shiroi may have extra renderers, wrappers, or providers
  • Routing files (*Content.tsx): Shiroi branches on a discriminator (e.g. contentFormat), Shiro always takes one path
  • Lazy-load entries (*Markdown.tsx): Used in preview/peek contexts, often overlooked
  • API query definitions (queries/definition/*.ts): Shiroi may pass extra params (e.g. prefer: 'lexical')
  • Server-side API files (api.ts): Direct apiClient calls may also need params

3. Map All Touchpoints

A feature typically spans these layers (check ALL):

LayerFilesWhat to sync
Dependenciespackage.json, pnpm-lock.yamlNew npm packages
Core componentscomponents/ui/...Rendering logic
Route renderers*LexicalRenderer.tsx, etc.Per-route wrappers
Content branching*Content.tsxcontentFormat discriminator
Lazy-load entries*Markdown.tsxDynamic import + branching for preview/peek
API queriesqueries/definition/*.tsQuery params like prefer
Server APIapp/[locale]/.../api.tsDirect apiClient calls
Conditional stylespage.tsx, layout.tsxprose class gating
TOC / headingsTocHeadingStrategy.tsxAlready wired, verify

4. Add Dependencies

Read Shiroi's package.json, extract only the packages needed for rendering (not editing/dashboard). Add to Shiro's package.json alphabetically, then pnpm install.

5. Port Core Components

Copy from Shiroi, adapting for Shiro:

  • Remove Shiroi-exclusive wrappers (e.g. LexicalCommentWrapper is sponsorship-only)
  • Check that all ~/ imports resolve in Shiro (modal types, hooks, constants)
  • Fix any API mismatches (e.g. contentClassName prop may not exist in Shiro's modal types)

6. Wire Into Routing

Three integration points per content type (note/post/page):

*Content.tsx (server component entry):

if (contentFormat === 'lexical') return <XxxLexicalRenderer />
return <XxxMarkdownRenderer />

*Markdown.tsx (lazy-load entry for preview/peek):

const XxxLexicalRenderer = dynamic(() => import('./XxxLexicalRenderer').then(m => m.XxxLexicalRenderer))
// ... branch on contentFormat from data selector

page.tsx / layout.tsx (conditional prose):

className={clsx(data.contentFormat !== 'lexical' && 'prose')}

7. Sync API Query Params

Compare queries/definition/*.ts and app/.../api.ts between repos. Add missing params (e.g. prefer: 'lexical').

8. Lint and Verify

  • Lint only modified files: pnpm exec eslint --fix <files>
  • Typecheck: pnpm exec tsc --noEmit — ignore pre-existing errors, verify new files don't appear in output

Common Mistakes

MistakeFix
Only update *Content.tsx, forget *Markdown.tsxMarkdown.tsx is the lazy entry for preview/peek — always update both
Forget API prefer paramBackend won't return rich content without it
Copy Shiroi-only wrappers verbatimStrip sponsorship features (comment anchoring, AI, etc.)
Leave prose class unconditionalRich content has its own typography — gate with contentFormat
Add editing dependencies when only rendering neededOnly port what's required for the read path