@damian87/omp 0.1.0

package/dist/src/team/task-store.js

@@ -0,0 +1,153 @@
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+export function taskFilePath(tasksDir, taskId) {
+    return join(tasksDir, `${taskId}.json`);
+}
+export function taskLockPath(tasksDir, taskId) {
+    return join(tasksDir, `${taskId}.lock`);
+}
+export function writeTask(taskPath, task) {
+    mkdirSync(dirname(taskPath), { recursive: true });
+    const tmp = `${taskPath}.tmp.${process.pid}.${Date.now()}`;
+    writeFileSync(tmp, JSON.stringify(task, null, 2), "utf8");
+    renameSync(tmp, taskPath);
+}
+export function readTask(taskPath) {
+    if (!existsSync(taskPath))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(taskPath, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function listTasks(tasksDir) {
+    if (!existsSync(tasksDir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(tasksDir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith(".json"))
+            continue;
+        const t = readTask(join(tasksDir, entry.name));
+        if (t)
+            out.push(t);
+    }
+    return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+function openLockExclusive(lockPath, worker) {
+    try {
+        const fd = openSync(lockPath, "wx");
+        try {
+            writeFileSync(lockPath, JSON.stringify({ owner: worker, pid: process.pid, claimedAt: new Date().toISOString() }));
+        }
+        finally {
+            closeSync(fd);
+        }
+        return fd;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function tryClaimTask(opts) {
+    const path = taskFilePath(opts.tasksDir, opts.taskId);
+    const task = readTask(path);
+    if (!task)
+        return { ok: false, reason: `task ${opts.taskId} not found` };
+    if (task.status !== "pending") {
+        return { ok: false, reason: `task ${opts.taskId} status=${task.status}` };
+    }
+    const lockPath = taskLockPath(opts.tasksDir, opts.taskId);
+    let fd = openLockExclusive(lockPath, opts.worker);
+    if (fd === undefined) {
+        // Lock exists. Re-read task status: if still pending, the lock is orphan
+        // (previous worker crashed between lock-acquire and task-write). Force-claim.
+        const recheck = readTask(path);
+        if (recheck?.status !== "pending") {
+            return { ok: false, reason: `task ${opts.taskId} status=${recheck?.status ?? "missing"}` };
+        }
+        try {
+            unlinkSync(lockPath);
+        }
+        catch {
+            // ignore: race with another claimer; the second openSync will arbitrate
+        }
+        fd = openLockExclusive(lockPath, opts.worker);
+        if (fd === undefined)
+            return { ok: false, reason: "concurrent claim race" };
+    }
+    const claimToken = `${opts.worker}-${Date.now()}-${Math.floor(Math.random() * 1_000_000)}`;
+    const updated = {
+        ...task,
+        status: "in_progress",
+        owner: opts.worker,
+        startedAt: new Date().toISOString(),
+        claimToken,
+    };
+    writeTask(path, updated);
+    // Optimistic CAS verification: re-read the task and confirm OUR claimToken
+    // landed. If a concurrent orphan-stealer raced us, their writeTask may have
+    // overwritten ours (writeTask is rename-atomic, so the last writer wins).
+    // Both workers' lock-acquire could succeed if B unlinks A's freshly-created
+    // lock between A's openSync and A's writeTask. The verify is the
+    // ground-truth tiebreaker — only the worker whose claimToken is currently
+    // persisted owns the task.
+    const verified = readTask(path);
+    if (verified?.claimToken !== claimToken) {
+        return { ok: false, reason: "concurrent claim overwrote ours; retry" };
+    }
+    return { ok: true, task: updated, claimToken };
+}
+export function clearAllLocks(tasksDir) {
+    return clearAllLocksDetailed(tasksDir).removed;
+}
+export function clearAllLocksDetailed(tasksDir) {
+    if (!existsSync(tasksDir))
+        return { removed: 0, failures: [] };
+    const failures = [];
+    let removed = 0;
+    for (const entry of readdirSync(tasksDir)) {
+        if (!entry.endsWith(".lock"))
+            continue;
+        const target = join(tasksDir, entry);
+        try {
+            unlinkSync(target);
+            removed++;
+        }
+        catch (err) {
+            failures.push({ path: target, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    return { removed, failures };
+}
+const TERMINAL = ["completed", "failed"];
+export function transitionTask(opts) {
+    const path = taskFilePath(opts.tasksDir, opts.taskId);
+    const task = readTask(path);
+    if (!task)
+        return { ok: false, reason: `task ${opts.taskId} not found` };
+    if (task.status !== opts.from) {
+        return { ok: false, reason: `task ${opts.taskId} status=${task.status}, expected ${opts.from}` };
+    }
+    if (task.claimToken && task.claimToken !== opts.claimToken) {
+        return { ok: false, reason: "claim token mismatch" };
+    }
+    const updated = {
+        ...task,
+        status: opts.to,
+        result: opts.result ?? task.result,
+        finishedAt: TERMINAL.includes(opts.to) ? new Date().toISOString() : task.finishedAt,
+    };
+    writeTask(path, updated);
+    if (TERMINAL.includes(opts.to)) {
+        try {
+            unlinkSync(taskLockPath(opts.tasksDir, opts.taskId));
+        }
+        catch {
+            // ignore: lock may already be gone
+        }
+    }
+    return { ok: true, task: updated };
+}
+//# sourceMappingURL=task-store.js.map

package/dist/src/team/task-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-store.js","sourceRoot":"","sources":["../../../src/team/task-store.ts"],"names":[],"mappings":"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"}

package/dist/src/team/tmux.d.ts

@@ -0,0 +1,26 @@
+export interface TmuxResult {
+    stdout: string;
+    stderr: string;
+    status: number;
+}
+export type TmuxRunner = (args: string[]) => TmuxResult;
+export declare function tmuxExec(args: string[]): TmuxResult;
+export declare function paneLooksReady(captured: string): boolean;
+export declare function paneHasActiveTask(captured: string): boolean;
+export interface TmuxApi {
+    newSession(session: string, cwd: string): TmuxResult;
+    splitWindow(target: string, cwd: string): TmuxResult;
+    sendKeys(target: string, ...keys: string[]): TmuxResult;
+    sendText(target: string, text: string): TmuxResult;
+    capturePane(target: string, lines?: number): TmuxResult;
+    killPane(target: string): TmuxResult;
+    killSession(session: string): TmuxResult;
+    paneDead(target: string): boolean;
+    sessionExists(session: string): boolean;
+}
+export declare function makeTmux(runner?: TmuxRunner): TmuxApi;
+export interface SendToWorkerOptions {
+    rounds?: number;
+    delayMs?: number;
+}
+export declare function sendToWorker(api: TmuxApi, target: string, text: string, options?: SendToWorkerOptions): Promise<boolean>;

package/dist/src/team/tmux.js

@@ -0,0 +1,87 @@
+import { spawnSync } from "node:child_process";
+export function tmuxExec(args) {
+    const r = spawnSync("tmux", args, { encoding: "utf8" });
+    return {
+        stdout: r.stdout ?? "",
+        stderr: r.stderr ?? "",
+        status: r.status ?? 1,
+    };
+}
+const PROMPT_RE = /(?:^|\s)(?:[│┃║▌▐▏▕╎┆┊]\s*)?[›>❯$#%]\s*$/;
+const ACTIVE_HINTS = [
+    /esc to interrupt/i,
+    /running\s*[…\.]/,
+    /background terminal/i,
+    /tool call in progress/i,
+];
+export function paneLooksReady(captured) {
+    if (!captured.trim())
+        return false;
+    const lines = captured.split("\n");
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (line.trim().length === 0)
+            continue;
+        return PROMPT_RE.test(line);
+    }
+    return false;
+}
+export function paneHasActiveTask(captured) {
+    return ACTIVE_HINTS.some((re) => re.test(captured));
+}
+export function makeTmux(runner = tmuxExec) {
+    return {
+        newSession(session, cwd) {
+            return runner(["new-session", "-d", "-P", "-F", "#S:0 #{pane_id}", "-s", session, "-c", cwd]);
+        },
+        splitWindow(target, cwd) {
+            return runner(["split-window", "-h", "-t", target, "-d", "-P", "-F", "#{pane_id}", "-c", cwd]);
+        },
+        sendKeys(target, ...keys) {
+            return runner(["send-keys", "-t", target, ...keys]);
+        },
+        sendText(target, text) {
+            return runner(["send-keys", "-t", target, "-l", "--", text]);
+        },
+        capturePane(target, lines = 80) {
+            return runner(["capture-pane", "-t", target, "-p", "-S", `-${lines}`]);
+        },
+        killPane(target) {
+            return runner(["kill-pane", "-t", target]);
+        },
+        killSession(session) {
+            return runner(["kill-session", "-t", session]);
+        },
+        paneDead(target) {
+            const r = runner(["display-message", "-t", target, "-p", "#{pane_dead}"]);
+            return r.stdout.trim() === "1";
+        },
+        sessionExists(session) {
+            const r = runner(["has-session", "-t", session]);
+            return r.status === 0;
+        },
+    };
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+export async function sendToWorker(api, target, text, options = {}) {
+    const rounds = options.rounds ?? 6;
+    const delayMs = options.delayMs ?? 150;
+    const payload = text.length > 200 ? text.slice(0, 200) : text;
+    api.sendText(target, payload);
+    for (let i = 0; i < rounds; i++) {
+        api.sendKeys(target, "C-m");
+        await sleep(delayMs);
+        const captured = api.capturePane(target, 5).stdout;
+        if (!captured.includes(payload))
+            return true;
+    }
+    // adaptive fallback: kill-line then retry once
+    api.sendKeys(target, "C-u");
+    await sleep(delayMs);
+    api.sendText(target, payload);
+    api.sendKeys(target, "C-m");
+    return true;
+}
+//# sourceMappingURL=tmux.js.map

package/dist/src/team/tmux.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tmux.js","sourceRoot":"","sources":["../../../src/team/tmux.ts"],"names":[],"mappings":"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"}

package/dist/src/team/types.d.ts

@@ -0,0 +1,45 @@
+export type WorkerRole = "claude" | "codex" | "gemini" | string;
+export type TaskStatus = "pending" | "in_progress" | "completed" | "failed";
+export interface Task {
+    id: string;
+    description: string;
+    status: TaskStatus;
+    owner?: string;
+    result?: string;
+    createdAt: string;
+    startedAt?: string;
+    finishedAt?: string;
+    claimToken?: string;
+}
+export interface Worker {
+    name: string;
+    role: WorkerRole;
+    paneId?: string;
+    taskId?: string;
+}
+export interface TeamConfig {
+    name: string;
+    task: string;
+    role: WorkerRole;
+    workerCount: number;
+    tmuxSession: string;
+    workers: Worker[];
+    cwd: string;
+    createdAt: string;
+}
+export interface Heartbeat {
+    pid: number;
+    workerName: string;
+    teamName: string;
+    lastPollAt: string;
+    turnCount: number;
+    alive: boolean;
+}
+export interface OutboxMessage {
+    type: "task_complete" | "task_failed" | "progress" | string;
+    taskId?: string;
+    status?: TaskStatus;
+    result?: string;
+    detail?: string;
+    timestamp: string;
+}

package/dist/src/team/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/team/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/team/types.ts"],"names":[],"mappings":""}

package/dist/src/team/worker-bootstrap.d.ts

@@ -0,0 +1,8 @@
+import type { Task } from "./types.js";
+export interface InboxOptions {
+    teamName: string;
+    workerName: string;
+    task: Task;
+    cwd: string;
+}
+export declare function buildInboxMarkdown(opts: InboxOptions): string;

package/dist/src/team/worker-bootstrap.js

@@ -0,0 +1,52 @@
+export function buildInboxMarkdown(opts) {
+    const claimInput = JSON.stringify({
+        team_name: opts.teamName,
+        task_id: opts.task.id,
+        worker: opts.workerName,
+        cwd: opts.cwd,
+    });
+    const completeInputTemplate = JSON.stringify({
+        team_name: opts.teamName,
+        task_id: opts.task.id,
+        worker: opts.workerName,
+        cwd: opts.cwd,
+        from: "in_progress",
+        to: "completed",
+        claim_token: "<claim_token>",
+        result: "Summary: ...",
+    });
+    const failInputTemplate = JSON.stringify({
+        team_name: opts.teamName,
+        task_id: opts.task.id,
+        worker: opts.workerName,
+        cwd: opts.cwd,
+        from: "in_progress",
+        to: "failed",
+        claim_token: "<claim_token>",
+    });
+    return [
+        "## REQUIRED: Task Lifecycle Commands",
+        "You MUST run these commands. Do NOT skip any step.",
+        "",
+        "1. Claim your task:",
+        `   omp team api claim-task --input '${claimInput}' --json`,
+        "   Save the claim_token from the response.",
+        "",
+        "2. Do the work described below.",
+        "",
+        "3. On completion (use claim_token from step 1):",
+        `   omp team api transition-task-status --input '${completeInputTemplate}' --json`,
+        "",
+        "4. On failure:",
+        `   omp team api transition-task-status --input '${failInputTemplate}' --json`,
+        "",
+        "## Task Assignment",
+        `Task ID: ${opts.task.id}`,
+        `Worker: ${opts.workerName}`,
+        "",
+        "## Description",
+        opts.task.description,
+        "",
+    ].join("\n");
+}
+//# sourceMappingURL=worker-bootstrap.js.map

package/dist/src/team/worker-bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-bootstrap.js","sourceRoot":"","sources":["../../../src/team/worker-bootstrap.ts"],"names":[],"mappings":"AASA,MAAM,UAAU,kBAAkB,CAAC,IAAkB;IACnD,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,SAAS,EAAE,IAAI,CAAC,QAAQ;QACxB,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE;QACrB,MAAM,EAAE,IAAI,CAAC,UAAU;QACvB,GAAG,EAAE,IAAI,CAAC,GAAG;KACd,CAAC,CAAC;IACH,MAAM,qBAAqB,GAAG,IAAI,CAAC,SAAS,CAAC;QAC3C,SAAS,EAAE,IAAI,CAAC,QAAQ;QACxB,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE;QACrB,MAAM,EAAE,IAAI,CAAC,UAAU;QACvB,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,IAAI,EAAE,aAAa;QACnB,EAAE,EAAE,WAAW;QACf,WAAW,EAAE,eAAe;QAC5B,MAAM,EAAE,cAAc;KACvB,CAAC,CAAC;IACH,MAAM,iBAAiB,GAAG,IAAI,CAAC,SAAS,CAAC;QACvC,SAAS,EAAE,IAAI,CAAC,QAAQ;QACxB,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE;QACrB,MAAM,EAAE,IAAI,CAAC,UAAU;QACvB,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,IAAI,EAAE,aAAa;QACnB,EAAE,EAAE,QAAQ;QACZ,WAAW,EAAE,eAAe;KAC7B,CAAC,CAAC;IACH,OAAO;QACL,sCAAsC;QACtC,oDAAoD;QACpD,EAAE;QACF,qBAAqB;QACrB,uCAAuC,UAAU,UAAU;QAC3D,4CAA4C;QAC5C,EAAE;QACF,iCAAiC;QACjC,EAAE;QACF,iDAAiD;QACjD,mDAAmD,qBAAqB,UAAU;QAClF,EAAE;QACF,gBAAgB;QAChB,mDAAmD,iBAAiB,UAAU;QAC9E,EAAE;QACF,oBAAoB;QACpB,YAAY,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE;QAC1B,WAAW,IAAI,CAAC,UAAU,EAAE;QAC5B,EAAE;QACF,gBAAgB;QAChB,IAAI,CAAC,IAAI,CAAC,WAAW;QACrB,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/docs/copilot-distribution.md

@@ -0,0 +1,100 @@
+# Copilot skill distribution
+
+## Bundle install (Copilot CLI plugin)
+
+The future-proof path: register the marketplace once, then install the bundled 17-skill plugin.
+
+```bash
+copilot plugin marketplace add damian87x/oh-my-copilot
+copilot plugin install oh-my-copilot@oh-my-copilot
+```
+
+Backed by root `plugin.json` with `"skills": ".github/skills/"` — no skills moved, no duplication. Backed by `.github/plugin/marketplace.json` listing the single self-hosted plugin. Requires Copilot CLI v1.0.48+.
+
+The shorter `owner/repo` form also works today but Copilot CLI prints a deprecation notice and will remove it in a future release:
+
+```bash
+copilot plugin install damian87x/oh-my-copilot   # works today, deprecated
+```
+
+The per-skill flows below remain valid for cases where you only want one skill or are on an older Copilot CLI.
+
+---
+
+## Per-skill install
+
+Use the agent-skill package shape as the default install surface:
+
+```text
+skills/<skill-name>/SKILL.md
+skills/<skill-name>/references/*
+skills/<skill-name>/scripts/*
+skills/<skill-name>/assets/*
+```
+
+For Copilot project install, copy the skill directory to:
+
+```text
+.github/skills/<skill-name>/SKILL.md
+```
+
+For Copilot personal install, copy the skill directory to:
+
+```text
+~/.copilot/skills/<skill-name>/SKILL.md
+```
+
+The catalog is optional metadata for this repository's built-in general skill list. Copilot discovers skills from the skill directories themselves.
+
+## Native oh-my-copilot installer
+
+Use `omcc skill install` when you want the same simple OMC-style copy flow, or as a fallback on machines without a new enough GitHub CLI. The bin is `omcc` (not `omc`) to avoid colliding with the `oh-my-claudecode` global command:
+
+```bash
+omcc skill install ./skills/my-skill --dry-run
+omcc skill install ./skills/my-skill --root /path/to/repo
+omcc skill install ./skills/my-skill --scope user
+```
+
+The installer validates `SKILL.md` frontmatter, previews copied files with `--dry-run`, preserves optional resource folders, and writes to `.github/skills/<name>` by default.
+
+## GitHub CLI path
+
+GitHub documents `gh skill` for searching, previewing, installing, updating, and publishing skills. It requires GitHub CLI `2.90.0` or newer.
+
+Useful commands:
+
+```bash
+gh skill preview OWNER/REPOSITORY SKILL
+gh skill install OWNER/REPOSITORY SKILL
+gh skill install OWNER/REPOSITORY SKILL --scope user
+gh skill publish --dry-run
+```
+
+Local note: this machine has `gh 2.92.0`, so `gh skill` is available. Do not make `gh skill` the only install path; keep `omcc skill install` as the fallback and repo-native dry-run surface.
+
+## OMC-like installer shape
+
+The `oh-my-copilot` installer should stay thin:
+
+1. Fetch a skill directory from a GitHub repository.
+2. Validate `SKILL.md` frontmatter: `name` and `description`.
+3. Preview the file tree before writing.
+4. Copy the directory unchanged to `.github/skills/<name>` for project scope or `~/.copilot/skills/<name>` for user scope.
+5. Preserve optional `references/`, `scripts/`, and `assets/`.
+6. Write provenance metadata only if needed for updates; do not require catalog entries.
+
+Dry-run output should show the target path and files that would be written.
+
+## Not a GitHub App Copilot Extension
+
+GitHub App-based Copilot Extensions are not the right path for this repo. GitHub sunset that extension type in favor of MCP servers: new creation was blocked in September 2025 and existing GitHub App-based Copilot Extensions were disabled in November 2025.
+
+If this project later needs live tools beyond static skills, prefer an MCP server. If it needs IDE UI integration, consider a VS Code extension. Keep project skills as plain skill packages.
+
+## References
+
+- GitHub Docs: Adding agent skills for GitHub Copilot — https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-skills
+- GitHub Docs: About agent skills — https://docs.github.com/en/copilot/concepts/agents/about-agent-skills
+- GitHub Docs: Running GitHub Copilot CLI programmatically — https://docs.github.com/en/copilot/how-tos/copilot-cli/automate-copilot-cli/run-cli-programmatically
+- GitHub Changelog: Sunset notice for GitHub App-based Copilot Extensions — https://github.blog/changelog/2025-09-24-deprecate-github-copilot-extensions-github-apps/

package/docs/general-skills.md

@@ -0,0 +1,76 @@
+# General Skills MVP
+
+The canonical skill source is the repo-local `.github/skills` directory. This is the GitHub Copilot project-skill location, so no `.agents` or `.claude` compatibility layer is needed.
+
+## Canonical lite skills
+
+| Skill | Capability IDs | Purpose |
+| --- | --- | --- |
+| `/codebase-research` | `codebase-research`, `research.codebase` | Read repo evidence before planning or asking. |
+| `/grill-me` | `grill-me`, `planning.challenge` | Ask one sharp clarification question when ambiguity remains. |
+| `/ralplan` | `ralplan`, `planning.consensus` | Produce implementation-ready plan, tests, and risks. |
+| `/team` | `team`, `execution.parallel` | Split approved work into parallel lanes. |
+| `/ralph` | `ralph`, `execution.single-owner` | Single-owner execute-fix-verify loop. |
+| `/ultrawork` | `ultrawork`, `execution.parallel` | Batch many independent small tasks. |
+| `/ultraqa` | `ultraqa`, `qa.behavioral` | Adversarial behavior and regression QA. |
+| `/omc-autopilot` | `omc-autopilot`, `execution.autonomous` | Lightweight end-to-end flow across the other skills. (Renamed from `/autopilot` to avoid Copilot CLI built-in collision.) |
+| `/code-review` | `code-review`, `review.independent` | Review completed changes before merge or handoff. |
+| `/verify` | `verify`, `verification.evidence` | Prove completion claims with evidence. |
+| `/jira-ticket` | `jira-ticket`, `tracker.ticket` | Render Jira create/comment/safe-update payloads. |
+| `/prototype` | `prototype`, `design.prototype` | Build disposable experiments for design questions. |
+| `/caveman` | `caveman`, `communication.compact` | Ultra-compact response mode. |
+| `/debug` | `debug`, `debug.systematic` | Reproduce, diagnose, fix, and regression-test bugs. |
+| `/tdd` | `tdd`, `testing.tdd` | Red-green-refactor for behavior changes. |
+
+## Repo-local layout
+
+```text
+oh-my-copilot/
+  .github/skills/<skill>/SKILL.md # Copilot project skill source of truth
+```
+
+Rules:
+
+- Edit `.github/skills/*/SKILL.md` first.
+- Use `/skill-name` invocation language.
+- Do not create `.agents` or `.claude` skill roots in this repo.
+- Do not generate `.github/copilot/...` wrappers; Copilot reads project skills directly.
+- Keep each `SKILL.md` small: YAML frontmatter (`name`, `description`) plus focused Markdown instructions.
+- Optional `references/`, `scripts/`, or `assets/` may live beside `SKILL.md` when a fetched skill needs progressive disclosure.
+- Do not add runtime state to the lite skills.
+
+## Fetched skills
+
+Skills fetched in the common `skills/<name>/SKILL.md` package shape can be moved directly to `.github/skills/<name>/SKILL.md`.
+The catalog is optional metadata for the built-in general skill list; Copilot discovery uses `.github/skills` itself.
+
+## Capability semantics
+
+`providerSupport.copilot.state = native` means Copilot can read the repo-local slash skill from `.github/skills`.
+It does not imply a durable execution runtime. Phase 1 execution skills such as `/team`, `/ralph`, `/ultrawork`, and `/omc-autopilot` are plain project-skill instructions, not persisted runtimes.
+
+## Phase 1 flow
+
+```text
+/codebase-research
+  -> /grill-me when unclear or risky
+  -> /ralplan
+  -> /team if lanes are independent, otherwise /ralph or /ultrawork
+  -> /code-review
+  -> /verify or /ultraqa
+  -> /jira-ticket when tracking is requested
+```
+
+## Portability rules
+
+Canonical `.github/skills/*/SKILL.md` bodies should avoid runtime coupling:
+
+- Do not require tmux panes, external agent team state, local orchestration state, or GitHub Issues.
+- Do not embed secrets or Jira credentials.
+- Do not use `$skill` invocation syntax in Copilot project skills.
+- Prefer slash-skill language and plain Markdown instructions over long framework-specific prompt text.
+
+## Migration notes
+
+- `/grill` was folded into `/grill-me` to keep one clarification entrypoint.
+- `/qa` was folded into `/ultraqa` for the adversarial QA pass.

package/docs/jira.md

@@ -0,0 +1,64 @@
+# Jira MVP Adapter
+
+The Jira adapter turns a resolved plan or handoff into Jira-ready payloads. It supports credential-free dry-runs and only performs live writes when configuration is present and a Jira action is requested by the user or workflow.
+
+## Configuration discovery
+
+Configuration is resolved in this order:
+
+1. External/global Jira setup available to the host environment.
+2. Repository `.env` and process environment variables.
+3. Explicit CLI/session flags as overrides.
+
+Supported environment names include:
+
+| Variable | Purpose |
+| --- | --- |
+| `JIRA_BASE_URL` or `JIRA_SITE_URL` | Jira site URL. |
+| `JIRA_EMAIL` | Account email for API auth. |
+| `JIRA_API_TOKEN` | API token. Never commit this value. |
+| `JIRA_PROJECT_KEY` | Default project key for new issues. |
+| `JIRA_DEFAULT_ISSUE_TYPE` | Optional issue type, defaulting to `Task`. |
+| `JIRA_COMPONENTS` | Optional comma-separated components for safe updates. |
+| `JIRA_PRIORITY` | Optional priority name for create/update payloads. |
+
+If required config is missing, commands print fallback payloads instead of guessing or failing silently.
+
+## Supported operations
+
+Phase 1 supports these safe operations:
+
+- Create issue payloads from plans/handoffs.
+- Add comments to existing issues.
+- Safely update summary, description, labels, configured components, configured priority, and acceptance criteria in the description.
+
+Dry-runs must work without credentials.
+
+## Transition and link guardrails
+
+Transitions and issue links are project-specific. The adapter may only perform them live after discovery confirms the exact transition ID/name or link type for the target ticket/project.
+
+If discovery is unavailable or no exact match exists, the adapter emits fallback text:
+
+```md
+## Jira fallback: <operation>
+Reason: <why live operation was not run>
+Target: <ticket key or new issue>
+Payload:
+```json
+{ ...exact Jira REST-style payload... }
+```
+Human action:
+<one concise instruction>
+```
+
+This no-guessing rule keeps workflow changes safe while still giving a human an exact payload to apply.
+
+## Dry-run examples
+
+```bash
+npm run jira:dry-run
+npx tsx src/cli.ts jira render ../.omx/plans/oh-my-copilot-general-skills-ralplan-handoff.md
+```
+
+Expected dry-run evidence includes create/comment/safe-update support and transition/link discovery fallback state.