" --priority <N> --label scorpio-import --desc "<body incl. Source: marker>" ``` - Create in priority order (1 → 4). Capture each printed issue id/url. - **Linear label caveat (tracker-dependent):** the `scorpio-import` label is requested via `--label`. The **GitHub** adapter auto-creates an unknown label; the **Linear** adapter only attaches a label that **already exists** in the workspace and silently drops an unknown one. So on Linear, pre-create a `scorpio-import` label if you want it for recognition / Step-3 narrowing — but dedup never *depends* on the label (the `Source:` marker, read via `view`, does), so a dropped label can't cause a double-create. - If the source carried in-progress/blocked states, set them with a follow-up `node scripts/tracker.mjs update <id> --state "<state>"` after creation. - If a `create` call fails, stop and report which succeeded — don't blindly retry the whole batch (you'd risk partial duplicates; the `Source:` dedup in Step 3 makes a *clean* re-run safe). ### Step 6 — Bootstrap the context layer (optional, offer it) Separate from task import — set up Scorpio's project grounding so downstream skills have context: - **Reference existing docs** — if the repo has a README / PRD / architecture / spec, point the `{docs.*}` locations at them (copy or reference into `{docs.planning}` as appropriate). - **Generate `PROJECT-CONTEXT.md`** — offer to run **`scorpio-project-map`** to map the codebase's structure/stack/patterns into the canonical context doc. - For advisor use later, note that `{docs.advisorReports}/ADVISOR-SKILLS-BUSINESS-GUIDANCE.md` and `app.url` are needed — flag if absent, don't fabricate them. ### Step 7 — Report + hand off Summarize: tracker + project, issues created (ids + priorities), what was skipped (completed / duplicate) and why, context artifacts set up, and the next step — **"Run `scorpio-loop` to prioritize and ship the imported backlog,"** since it now reads these issues from the tracker with no further setup. **Flag the source-of-truth split explicitly.** If the project keeps its own live backlog (a `GAPS.json`, a `TASKS.md`, an in-repo CLI/DB) that you imported *from*, say so plainly in the hand-off: this was a **one-time import, not a live sync** — from here Scorpio reads the **tracker**, while the original source keeps whatever its own tooling writes, and the two will **diverge** unless the user picks one as canonical. Recommend treating the tracker as the Scorpio-driven view and either freezing the old source or updating it manually. Don't leave the divergence implicit. ## Guardrails - **Never create issues without explicit user confirmation.** Always propose first (Step 4); honor `--dry-run`. Creating tracker issues is an outward-facing, hard-to-reverse bulk write. - **Idempotent by the `Source:` marker + `scorpio-import` label** — a second run on the same source must not duplicate. - **Read-only on the source.** Never mutate or delete the project's existing task file/DB; you're migrating *out of* it, not editing it. - **Never guess the tracker or commit a secret.** If the tracker can't be resolved or the credential env isn't set, stop and ask. Read the credential from the environment only. - **Skip completed tasks** unless `--include-done`. - **Don't plan or implement** — map existing tasks to issues only; the shipping is downstream. ## Skill Chain ``` [existing project: TASKS.md / tasks.json / DB / scattered TODOs] → onboard (resolve tracker · read+normalize · propose · [user approves] · tracker.create) → scorpio-project-map (optional: PROJECT-CONTEXT.md) → scorpio-loop (prioritizes from tracker) → scorpio-ship ```

--- name: scorpio-onboard description: Drop Scorpio into an existing project — pick a supported tracker, import the project's current tasks/issues into it, and bootstrap the context layer. Reads whatever the project uses today (a TASKS.md/checklist, a tasks.json/YAML, a local DB, or TODOs scattered across the repo), normalizes them to the tracker's issue shape, proposes the mapping for approval, then bulk-creates them via the tracker seam — idempotently. Use when adopting Scorpio on a project for the first time, "onboard this repo", "import my tasks into Linear", or "set this project up for scorpio-loop". argument-hint: "[source path(s)] [--tracker linear|github] [--include-done] [--dry-run]" --- # onboard Take an existing project from **"Scorpio installed" → "ready to `scorpio-loop`."** You (the agent) read the project's current backlog in whatever form it takes, normalize it, and — **only after the user approves** — create the issues in the chosen tracker through the Scorpio seam. You also bootstrap the context layer so the pipeline has project grounding. This is **drop-in adoption**, and it leans on a deliberate reframe: **Scorpio owns no task store.** "Importing tasks into Scorpio" means **migrating them into the project's chosen tracker** (the spine `scorpio-loop`/`scorpio-ship` read from). The *write* side already exists — the tracker `create` verb. Your job is the **read + normalize + map**, then a gated create. ## What this skill is / isn't - **Is:** a one-time **importer** — read the project's existing tasks once, write them into the tracker. Read-only on the source; an approval-gated, idempotent bulk-write to the tracker. - **Isn't:** a live tracker **adapter** (the ongoing five-verb connection). If a project wants to *keep* its backlog in a flat file / Planner / Jira as the live spine, that's a tracker adapter, not this skill. (See [ROADMAP §6](../../ROADMAP.md).) - **Isn't:** a planner or implementer. You map existing tasks to issues; shipping happens downstream via `scorpio-loop` → `scorpio-ship`. ## Prerequisites 1. **The framework is installed** in the target repo (skills + `scripts/` seam + a manifest). If `scripts/tracker.mjs` isn't present, tell the user to run `install.sh --target ` first. 2. **A tracker is (or will be) resolved.** Resolve `tracker.adapter` / `tracker.issueIdPattern` / `tracker.credentialEnv` per the resolution rule (**explicit config → repo detection → ask**; see [docs/CONFIG.md](../../docs/CONFIG.md)). If there's no `scorpio.config.json` yet, **Step 0** scaffolds one. The first-priority target is **Linear** (its adapter + `create` exist), but this skill is tracker-neutral — any adapter with a `create` verb works. ## Procedure ### Step 0 — Config + tracker (resolve, scaffold, echo) - If `scorpio.config.json` is absent, scaffold it: `install.sh` copies `config/` to the repo root (never overwriting), or copy a `config/*.example.json` template and **walk the user through editing `tracker`, `git.baseBranch`, and `gates.commands`** for this project. Validate it parses. - Resolve the tracker adapter and confirm the credential env var named by `tracker.credentialEnv` is **set in the environment** (the dispatcher errors clearly if not — ask the user to export it; never source a key from `~/.bashrc` or hardcode one). - **Echo what you resolved** before doing anything that writes: which tracker/adapter/project, which credential env var, and that the next steps will read the source backlog and *propose* (not yet create) issues. Creating issues is an outward-facing write — surface it up front. ### Step 1 — Locate the source backlog (source-agnostic) The project's tasks can live anywhere. **Inspect the repo and present what you find**, then let the user confirm or point you at the right source(s). If `$ARGUMENTS` names a path, start there. Look across the common shapes: - **Markdown** — `TASKS.md`, `TODO.md`, `ROADMAP.md`, checklists (`- [ ]` / `- [x]`), headings, or tables. - **Structured file** — `tasks.json` / `*.yaml` / `*.yml` / a CSV with task fields. - **Local DB** — a SQLite file or a tasks table (read-only query; ask for the table/columns if non-obvious). - **Scattered** — `TODO:` / `FIXME:` comments in code, or tasks embedded in a README/notes. Report each candidate source with a rough item count. **Don't guess silently** — if the source is ambiguous, ask which to import (and whether to merge several). ### Step 2 — Read + normalize to the canonical issue shape Read the confirmed source(s) and turn each task into a normalized issue. The LLM does the parsing — handle loose/heterogeneous structure gracefully. Canonical shape: | Field | How to derive | Notes | |-------|---------------|-------| | **title** | the task's summary line | keep concise; strip checkbox/markup | | **description** | body, sub-bullets, acceptance criteria, links — everything an implementer needs | preserve the plan if the source has one | | **status** | source state → Scorpio lifecycle: unstarted → `Todo`/`Backlog`; in-progress markers → `In Progress`; done (`- [x]`, "Done", closed) → **completed** | most imports land as `Todo`/`Backlog` | | **priority** | source priority → **1 urgent · 2 high · 3 medium · 4 low** (Linear convention; the adapter normalizes for other trackers) | map anything unrecognized to **3** and note it | | **labels** | source tags/categories, plus the marker label below | | | **dependencies** | "blocked by" / "depends on" references, if the source has them | record in the body if the tracker can't model edges | - **Completed tasks:** by default **skip** them (they're history, not actionable backlog) and report the count skipped. Import them as closed only if the user passes `--include-done`. - **Idempotency marker:** add a body line `Source: scorpio-onboard #` (a stable identifier from the source — a slug, line ref, or DB id) and tag every imported issue with the label **`scorpio-import`**, so re-runs can dedup and the seeded issues stay recognizable. ### Step 3 — Dedup against the tracker (read the body, not just the title) Re-running `scorpio-onboard` on the same source must never double-create — and the `Source:` marker that guarantees that lives in the issue **body**, which `list` does **not** print (it emits `id · state · priority · assignee · title` only; the body comes back only from `view`). So: 1. Narrow the candidate set: `node scripts/tracker.mjs list --label scorpio-import` (the `--label` filter is supported). If the label isn't reliably present (see the **Linear label caveat** in Step 5), fall back to `node scripts/tracker.mjs list` over open issues. 2. **`view` each candidate** (`node scripts/tracker.mjs view `) and **skip any task whose `Source: scorpio-onboard #` marker already appears** in the viewed description. Dedup correctness rests on the **marker read via `view`**, not on the label. Report what you skipped and why. ### Step 4 — Propose the mapping (do NOT create yet) Present the full set as a table — **title · mapped status · mapped priority · source key · one-line description** — plus the totals and everything skipped (completed / duplicate / unparseable). This is the dry-run. If the user passed `--dry-run` or only wants the preview, **stop here**. Otherwise ask for explicit confirmation before any write. ### Step 5 — Create on confirmation (idempotent, in priority order) Only after explicit approval, create each proposed issue through the seam: ``` node scripts/tracker.mjs create --title "" --priority <N> --label scorpio-import --desc "<body incl. Source: marker>" ``` - Create in priority order (1 → 4). Capture each printed issue id/url. - **Linear label caveat (tracker-dependent):** the `scorpio-import` label is requested via `--label`. The **GitHub** adapter auto-creates an unknown label; the **Linear** adapter only attaches a label that **already exists** in the workspace and silently drops an unknown one. So on Linear, pre-create a `scorpio-import` label if you want it for recognition / Step-3 narrowing — but dedup never *depends* on the label (the `Source:` marker, read via `view`, does), so a dropped label can't cause a double-create. - If the source carried in-progress/blocked states, set them with a follow-up `node scripts/tracker.mjs update <id> --state "<state>"` after creation. - If a `create` call fails, stop and report which succeeded — don't blindly retry the whole batch (you'd risk partial duplicates; the `Source:` dedup in Step 3 makes a *clean* re-run safe). ### Step 6 — Bootstrap the context layer (optional, offer it) Separate from task import — set up Scorpio's project grounding so downstream skills have context: - **Reference existing docs** — if the repo has a README / PRD / architecture / spec, point the `{docs.*}` locations at them (copy or reference into `{docs.planning}` as appropriate). - **Generate `PROJECT-CONTEXT.md`** — offer to run **`scorpio-project-map`** to map the codebase's structure/stack/patterns into the canonical context doc. - For advisor use later, note that `{docs.advisorReports}/ADVISOR-SKILLS-BUSINESS-GUIDANCE.md` and `app.url` are needed — flag if absent, don't fabricate them. ### Step 7 — Report + hand off Summarize: tracker + project, issues created (ids + priorities), what was skipped (completed / duplicate) and why, context artifacts set up, and the next step — **"Run `scorpio-loop` to prioritize and ship the imported backlog,"** since it now reads these issues from the tracker with no further setup. **Flag the source-of-truth split explicitly.** If the project keeps its own live backlog (a `GAPS.json`, a `TASKS.md`, an in-repo CLI/DB) that you imported *from*, say so plainly in the hand-off: this was a **one-time import, not a live sync** — from here Scorpio reads the **tracker**, while the original source keeps whatever its own tooling writes, and the two will **diverge** unless the user picks one as canonical. Recommend treating the tracker as the Scorpio-driven view and either freezing the old source or updating it manually. Don't leave the divergence implicit. ## Guardrails - **Never create issues without explicit user confirmation.** Always propose first (Step 4); honor `--dry-run`. Creating tracker issues is an outward-facing, hard-to-reverse bulk write. - **Idempotent by the `Source:` marker + `scorpio-import` label** — a second run on the same source must not duplicate. - **Read-only on the source.** Never mutate or delete the project's existing task file/DB; you're migrating *out of* it, not editing it. - **Never guess the tracker or commit a secret.** If the tracker can't be resolved or the credential env isn't set, stop and ask. Read the credential from the environment only. - **Skip completed tasks** unless `--include-done`. - **Don't plan or implement** — map existing tasks to issues only; the shipping is downstream. ## Skill Chain ``` [existing project: TASKS.md / tasks.json / DB / scattered TODOs] → onboard (resolve tracker · read+normalize · propose · [user approves] · tracker.create) → scorpio-project-map (optional: PROJECT-CONTEXT.md) → scorpio-loop (prioritizes from tracker) → scorpio-ship ```