---
name: manual-kimaki-upstream-adapt
description: >
  Manual, file-by-file port of changes from remorses/kimaki into this repo.
  Use when the user asks to "pull from kimaki", "port kimaki changes", or
  "sync kimaki manually" without any automatic GitHub Actions syncing.
---

# Manual kimaki upstream adaptation (file-by-file)

This workflow replaces any automatic upstream sync. You MUST do a manual, explicit, reviewable port from `remorses/kimaki` into this repository.

## Hard rules

- Never enable scheduled/automatic syncing in GitHub Actions.
- Never auto-push or auto-merge upstream changes. Prefer a local branch + PR.
- Always adapt for this repo (branding, paths, CI policy). Do not copy blindly.
- After making changes, always run TypeScript compile in `cli/`:

```bash
cd cli && pnpm tsc
```

## Choose the upstream change-set

Pick one:

1. **Commit range**: kimaki `base..head` (preferred if you know the commits)
2. **GitHub compare**: kimaki compare view between two refs/tags
3. **File target list**: you already know which files/features to port

Always record which kimaki ref(s) you used (branch/tag/commit SHA) in your PR description or notes.

## Get the list of changed files (file-by-file checklist)

Preferred (GitHub compare via `gh`):

```bash
gh repo view remorses/kimaki
gh api "repos/remorses/kimaki/compare/<base>...<head>" --jq ".files[].filename"
```

Alternative (local clone in a separate directory):

```bash
git clone --depth 1 https://github.com/remorses/kimaki.git ../kimaki
cd ../kimaki && git fetch --depth 1 origin <head>
git diff --name-only <base>..<head>
```

## Port each file

For each file in the checklist:

1. Fetch the kimaki version (raw file at a specific ref).
2. Copy it into the matching location in this repo.
3. Apply the adaptation rules below.
4. If the file does not exist here, stop and decide: is it a real dependency for the feature, or kimaki-only baggage?
5. If the file exists but differs, merge carefully (do not revert unrelated local changes).

Raw fetch patterns (pick one):

```bash
curl -fsSL "https://raw.githubusercontent.com/remorses/kimaki/<ref>/<path>" -o "./tmp/upstream-kimaki-$(basename \"<path>\")"
```

```bash
gh api "repos/remorses/kimaki/contents/<path>?ref=<ref>" --jq ".content" | base64 -d > "./tmp/upstream-kimaki-file"
```

## Adaptation rules (always apply)

### Monorepo paths

- Skills live in `skills/<name>/SKILL.md` at repo root (canonical).
- Packaged `cli/skills/` is a copy generated by build/publish; do not treat it as the source of truth.
- Prefer changes inside `cli/` when the change is bot/runtime behavior.
- Do not add new tsconfig path aliases; use workspace deps instead.

### Naming / branding

When porting text, config, or package metadata:

- Prefer `otto` / `@otto-assistant/bridge` / `otto-assistant/bridge` over `kimaki` branding unless the code is explicitly legacy-compat.
- URLs/domains must match this project’s expectations (do not introduce kimaki domains unless explicitly required).
- When generating paths, prefer `OTTO_DATA_DIR` conventions; `KIMAKI_*` should remain only as explicitly deprecated/compat paths.

### CI policy (no automation)

- Do not introduce new scheduled workflows for upstream syncing.
- Any upstream-related workflow must be `workflow_dispatch` only.
- No bot accounts committing to `main` as part of an upstream sync flow.

## Validation checklist (must pass)

At minimum:

```bash
cd cli && pnpm tsc
```

If you touched message handling / queueing / runtime flow, also run:

```bash
cd cli && pnpm test -u --run
```

## Conflict resolution checklist

If the kimaki change conflicts with this repo:

- Prefer keeping this repo’s packaging identity (`@otto-assistant/bridge`) and workspace layout.
- Prefer keeping CI “manual only” policy.
- Prefer keeping local bugfixes even if upstream differs; re-apply the upstream intent in a way that compiles and passes tests here.
