@litfamily/litopencode 1.0.34 → 1.0.35

package/CHANGELOG.md

@@ -5,6 +5,14 @@ are tracked separately from this product history.
 
 ## Unreleased
 
+## 1.0.35 - 2026-10-31
+
+- `lit adhd` counts the other lanes before it offers to resume this session's own work. A session that had started herdr lanes (or sat beside other running sessions) was still told to continue its paused discipline with `go` while they worked; now the box says to wait for them, arms nothing and ends with "Do not type `go` until they finish." A pending approval is still offered, and without lanes the paused discipline is offered as before.
+
+- OpenCode reads one global instruction file at the start of every session, `AGENTS.md` in its config folder, and until now LitOpenCode never put anything there. The installer can now add a short block to it that says what `lit` means, where plans, the handoff and run state live, and that nothing is pushed, published, tagged or version-bumped without your yes. An interactive install asks once, `--yes` adds it, `--no-agent-file` skips it for a run, and an install with no terminal and no `--yes` never writes it. Your own text stays byte for byte, the first change keeps one backup copy, and `litopencode agent-file remove` takes the block out and returns the file to what it was. `litopencode agent-file off` removes it and keeps the choice in `litopencode.json`; `on` brings it back; `doctor` prints the block's state. OpenCode falls back to `~/.claude/CLAUDE.md` only while its own `AGENTS.md` is missing, so the installer never creates that file over an existing `CLAUDE.md`. `litopencode agent-file project` writes the matching project block into a repo's `AGENTS.md`, and `lit-init` points to it.
+
+- `lit adhd` no longer offers `go` while other lanes work: other running sessions and, under `HERDR_ENV=1`, herdr agents in this workspace or repo make the box say to wait for them. Its HANDOFF step skips items already marked done and reads the newest handoff file first, another session's running start-work is never a `go` step here, and `go` re-checks that the recorded run is still this session's before it says keep working.
+
 ## 1.0.34 - 2026-10-29
 
 - Releases are now built and published from GitHub Actions with npm provenance. The npm page shows a green check that links each version to this repository and the commit it was built from.

package/README-Ko-KR.md

@@ -1,13 +1,13 @@
-<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/docs/assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 일곱 로봇 패널이 차례로 켜지고, LitOpenCode 로봇의 눈과 테두리가 빛난 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
+<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/docs/assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 일곱 로봇 패널이 차례로 켜지고, LitOpenCode 로봇의 눈과 테두리가 빛난 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
 
 # LitOpenCode
 
 **LitOpenCode는 OpenCode용 워크플로 플러그인입니다. 프롬프트에 `lit`만 붙이면 계획하고, 만들고, 확인하고, 기록까지 남겨서 다음 세션이 어디서 멈췄는지 바로 압니다.**
 
 <p align="center">
-<a href="https://www.npmjs.com/package/@litfamily/litopencode"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/docs/assets/readme/badge-version.svg" alt="1.0.34" /></a>
+<a href="https://www.npmjs.com/package/@litfamily/litopencode"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/docs/assets/readme/badge-version.svg" alt="1.0.35" /></a>
 <a href="https://www.npmjs.com/package/@litfamily/litopencode"><img src="https://img.shields.io/npm/dm/@litfamily/litopencode?label=downloads&color=D7F75B" alt="월간 npm 다운로드 수" /></a>
-<a href="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/docs/assets/readme/badge-license.svg" alt="MIT 라이선스" /></a>
+<a href="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/docs/assets/readme/badge-license.svg" alt="MIT 라이선스" /></a>
 <a href="https://github.com/wjgoarxiv/litopencode"><img src="https://img.shields.io/github/stars/wjgoarxiv/litopencode?style=social" alt="GitHub 스타" /></a>
 </p>
 
@@ -57,9 +57,9 @@ npm uninstall -g @litfamily/litopencode
 ## 더 보기
 
 - [GitHub의 사용 안내](https://github.com/wjgoarxiv/litopencode/blob/main/docs/guide-Ko-KR.md): 설치 옵션, 자동 인수인계, 문제 해결, 제거
-- [워크플로 상세 안내](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/docs/reference-Ko-KR.md) · [English reference](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/docs/reference.md)
-- [마이그레이션 안내](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/docs/migration.md) · [Changelog](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/CHANGELOG.md) · [개인정보와 네트워크 동작](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/docs/privacy.md)
-- [LitFamily 허브](https://github.com/wjgoarxiv/litfamily) · [MIT 라이선스](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/LICENSE) · [상표 정책](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/TRADEMARK.md) · [ASCII 글꼴 라이선스](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/docs/assets/readme/JetBrainsMono-OFL.txt)
+- [워크플로 상세 안내](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/docs/reference-Ko-KR.md) · [English reference](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/docs/reference.md)
+- [마이그레이션 안내](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/docs/migration.md) · [Changelog](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/CHANGELOG.md) · [개인정보와 네트워크 동작](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/docs/privacy.md)
+- [LitFamily 허브](https://github.com/wjgoarxiv/litfamily) · [MIT 라이선스](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/LICENSE) · [상표 정책](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/TRADEMARK.md) · [ASCII 글꼴 라이선스](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/docs/assets/readme/JetBrainsMono-OFL.txt)
 
 <details>
 <summary>ASCII 로고 복사</summary>

package/README.md

@@ -1,13 +1,13 @@
-<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/docs/assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: seven armored robots power on one by one, the LitOpenCode robot wakes with glowing eyes and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
+<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/docs/assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: seven armored robots power on one by one, the LitOpenCode robot wakes with glowing eyes and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
 
 # LitOpenCode
 
 **LitOpenCode is a workflow plugin for OpenCode. Add `lit` to a prompt and the work gets planned, built, checked and written down, so the next session knows where you stopped.**
 
 <p align="center">
-<a href="https://www.npmjs.com/package/@litfamily/litopencode"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/docs/assets/readme/badge-version.svg" alt="1.0.34" /></a>
+<a href="https://www.npmjs.com/package/@litfamily/litopencode"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/docs/assets/readme/badge-version.svg" alt="1.0.35" /></a>
 <a href="https://www.npmjs.com/package/@litfamily/litopencode"><img src="https://img.shields.io/npm/dm/@litfamily/litopencode?label=downloads&color=D7F75B" alt="npm downloads per month" /></a>
-<a href="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/docs/assets/readme/badge-license.svg" alt="MIT license" /></a>
+<a href="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/docs/assets/readme/badge-license.svg" alt="MIT license" /></a>
 <a href="https://github.com/wjgoarxiv/litopencode"><img src="https://img.shields.io/github/stars/wjgoarxiv/litopencode?style=social" alt="GitHub stars" /></a>
 </p>
 
@@ -57,9 +57,9 @@ npm uninstall -g @litfamily/litopencode
 ## More
 
 - [Guide on GitHub](https://github.com/wjgoarxiv/litopencode/blob/main/docs/guide.md): install options, automatic handoff, troubleshooting and removal.
-- [Workflow reference](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/docs/reference.md)
-- [Migration notes](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/docs/migration.md) · [Changelog](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/CHANGELOG.md) · [Privacy and network behavior](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/docs/privacy.md)
-- [LitFamily hub](https://github.com/wjgoarxiv/litfamily) · [MIT license](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/LICENSE) · [Trademark policy](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/TRADEMARK.md) · [ASCII font license](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.34/docs/assets/readme/JetBrainsMono-OFL.txt)
+- [Workflow reference](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/docs/reference.md)
+- [Migration notes](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/docs/migration.md) · [Changelog](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/CHANGELOG.md) · [Privacy and network behavior](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/docs/privacy.md)
+- [LitFamily hub](https://github.com/wjgoarxiv/litfamily) · [MIT license](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/LICENSE) · [Trademark policy](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/TRADEMARK.md) · [ASCII font license](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.35/docs/assets/readme/JetBrainsMono-OFL.txt)
 
 <details>
 <summary>Copy ASCII logo</summary>

package/dist/adhd-next.d.ts

@@ -1,6 +1,6 @@
 import { type ActivationMemory } from "./activation-reentry.ts";
 import type { ChatActivationMode } from "./activation-routing.ts";
-import type { BoundedAuthorityOptions } from "./bounded-authority.ts";
+import { type BoundedAuthorityOptions } from "./bounded-authority.ts";
 export declare const adhdNextSchema = "litopencode.adhd-next/v1";
 export declare const adhdNextTtlMs: number;
 export type NextKind = "continue" | "work" | "plan" | "elsewhere";

package/dist/adhd-next.js

@@ -3,6 +3,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { createActivationMemory, decideReentry } from "./activation-reentry.js";
 import { startWorkPromptInjection } from "./activation-workflow-prompts.js";
+import { createBoundedAuthorityLifecycle } from "./bounded-authority.js";
 import { answerBoundary, boundaryVerdict, startTypedWork } from "./start-work-typed.js";
 import { createRuntimePaths } from "./state.js";
 // The brief from lit-adhd ends with one recommended next step and the word `go`. The collector writes that
@@ -115,6 +116,16 @@ export async function routeGo(input) {
         };
     }
     if (record.kind === "work") {
+        // The brief saw this session's run active; go re-checks that before it says keep working.
+        const state = await createBoundedAuthorityLifecycle(input.projectRoot, input.boundedAuthority).read().catch(() => undefined);
+        if (state?.status !== "active" || state.sessionID !== input.sessionID) {
+            const why = state === undefined ? "there is no start-work run any more" : state.sessionID !== input.sessionID ? "the start-work run now belongs to another session" : `the start-work run is ${state.status}`;
+            return {
+                text: `LitOpenCode: the user answered go to the lit-adhd brief, but its step no longer holds: ${why}. Say so in one line and start nothing; \`lit adhd\` gives a fresh step.`,
+                mode: "lit-adhd",
+                kind: "elsewhere"
+            };
+        }
         return {
             text: "LitOpenCode: the user answered go to the brief's next step, which is the running start-work run. Keep working from the checked plan; do not restart it, replan or widen what it may touch. A pending boundary still needs `lit approve` from the user.",
             mode: "start-work",

package/dist/cli/agent-file-command.d.ts

@@ -0,0 +1,21 @@
+import { type AgentFileMode } from "./agent-file.ts";
+import type { CliResult, ParsedArgs } from "./types.ts";
+type InstallInput = {
+    readonly root: string;
+    readonly version: string;
+    readonly assumeYes: boolean;
+    readonly skip: boolean;
+};
+export type AgentFilePlan = {
+    readonly path: string;
+    readonly state: string;
+    readonly mode: AgentFileMode | "unset";
+    readonly action: "add" | "refresh" | "ask" | "none" | "off" | "skipped-claude-fallback";
+};
+/** What an install would do to the global file, without asking or writing. */
+export declare function planAgentFile(input: InstallInput, env?: NodeJS.ProcessEnv): Promise<AgentFilePlan>;
+/** The install step: adds on a yes, refreshes a block already there, leaves everything else as it is. */
+export declare function installAgentFile(input: InstallInput, env?: NodeJS.ProcessEnv, ask?: () => Promise<boolean>): Promise<string>;
+/** `litopencode agent-file on|off|remove|project`. */
+export declare function runAgentFileCommand(parsed: ParsedArgs, version: string, env?: NodeJS.ProcessEnv): Promise<CliResult>;
+export {};

package/dist/cli/agent-file-command.js

@@ -0,0 +1,99 @@
+// The install-time step and the `litopencode agent-file` command around the LitFamily block: one place
+// that decides whether OpenCode's global AGENTS.md gets the block, and says so in one `AGENT_FILE:` line.
+import fs from "node:fs";
+import path from "node:path";
+import { agentFileBody, agentFileLine, agentFileState, applyAgentFile, claudeFallbackFile, globalAgentFilePath, readAgentFileMode, writeAgentFileMode } from "./agent-file.js";
+import { createPromptReader } from "./model-routing.js";
+const QUESTION = "Add the short LitFamily block to OpenCode's global AGENTS.md? Your own text stays as it is. [Y/n] ";
+const SHADOW_HINT = "OpenCode reads ~/.claude/CLAUDE.md while this file is missing, and a new AGENTS.md would hide it; create the file yourself first, or set OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1";
+function shouldAsk(env) {
+    if (env.LITOPENCODE_AGENT_FILE_PROMPT === "1")
+        return true;
+    if (env.LITOPENCODE_AGENT_FILE_PROMPT === "0")
+        return false;
+    return process.stdin.isTTY === true && process.stdout.isTTY === true && env.CI === undefined;
+}
+async function askYes() {
+    const reader = createPromptReader();
+    try {
+        return !/^\s*n/iu.test(await reader.question(QUESTION));
+    }
+    finally {
+        reader.close();
+    }
+}
+const note = (status, filePath, hint) => `AGENT_FILE: ${status} ${filePath} (${hint})`;
+/** What an install would do to the global file, without asking or writing. */
+export async function planAgentFile(input, env = process.env) {
+    const filePath = globalAgentFilePath(input.root);
+    const mode = await readAgentFileMode(input.root, env);
+    const state = agentFileState({ path: filePath, version: input.version });
+    const base = { path: filePath, state, mode };
+    if (input.skip || mode === "off")
+        return { ...base, action: "off" };
+    if (state.startsWith("present"))
+        return { ...base, action: "none" };
+    if (state.startsWith("stale"))
+        return { ...base, action: "refresh" };
+    // A malformed, linked or non-UTF-8 file goes through the writer, which refuses it and says why.
+    if (state !== "absent")
+        return { ...base, action: "refresh" };
+    if (!fs.existsSync(filePath) && claudeFallbackFile(env) !== null)
+        return { ...base, action: "skipped-claude-fallback" };
+    return { ...base, action: input.assumeYes ? "add" : "ask" };
+}
+/** The install step: adds on a yes, refreshes a block already there, leaves everything else as it is. */
+export async function installAgentFile(input, env = process.env, ask = askYes) {
+    const plan = await planAgentFile(input, env);
+    const write = () => agentFileLine(applyAgentFile({ path: plan.path, version: input.version, body: agentFileBody("global"), action: "install" }));
+    switch (plan.action) {
+        case "off":
+            return note("off", plan.path, "left as it is; turn on: litopencode agent-file on");
+        case "none":
+            return agentFileLine({ status: "unchanged", path: plan.path });
+        case "refresh":
+        case "add":
+            return write();
+        case "skipped-claude-fallback":
+            return note("skipped-claude-fallback", plan.path, SHADOW_HINT);
+        case "ask":
+            if (!shouldAsk(env))
+                return note("skipped", plan.path, "add the LitFamily block: litopencode agent-file on");
+            if (await ask())
+                return write();
+            await writeAgentFileMode(input.root, "off");
+            return note("off", plan.path, "turn on later: litopencode agent-file on");
+    }
+}
+/** `litopencode agent-file on|off|remove|project`. */
+export async function runAgentFileCommand(parsed, version, env = process.env) {
+    const action = parsed.agentFileAction;
+    const failed = (result) => (result.status.startsWith("refused-") ? 1 : 0);
+    if (action === "project") {
+        const dir = path.resolve(parsed.agentFileDir ?? process.cwd());
+        if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory())
+            return { exitCode: 2, stderr: `agent-file project: ${dir} is not a folder` };
+        const result = applyAgentFile({ path: path.join(dir, "AGENTS.md"), version, body: agentFileBody("project"), action: "install", dryRun: parsed.dryRun, backup: false });
+        return { exitCode: failed(result), stdout: agentFileLine(result) };
+    }
+    const filePath = globalAgentFilePath(parsed.root);
+    const lines = [];
+    if (action === "on" || action === "off") {
+        if (!parsed.dryRun)
+            await writeAgentFileMode(parsed.root, action);
+        lines.push(`AGENT_FILE: ${action}`);
+    }
+    if (action === "on" && !fs.existsSync(filePath) && claudeFallbackFile(env) !== null) {
+        lines.push(note("skipped-claude-fallback", filePath, SHADOW_HINT));
+        return { exitCode: 0, stdout: lines.join("\n") };
+    }
+    const result = applyAgentFile({
+        path: filePath,
+        version,
+        body: agentFileBody("global"),
+        action: action === "on" ? "install" : "uninstall",
+        dryRun: parsed.dryRun
+    });
+    lines.push(agentFileLine(result));
+    return { exitCode: failed(result), stdout: lines.join("\n") };
+}

package/dist/cli/agent-file.d.ts

@@ -0,0 +1,46 @@
+export declare const AGENT_FILE_ID = "litopencode";
+export declare const AGENT_FILE_MODES: readonly ["on", "off"];
+export type AgentFileMode = (typeof AGENT_FILE_MODES)[number];
+export declare const AGENT_FILE_MAX_BYTES = 1200;
+/** The shipped block text: `global` for OpenCode's AGENTS.md, `project` for a repo's AGENTS.md. */
+export declare function agentFileBody(kind?: "global" | "project"): string;
+export declare function globalAgentFilePath(root: string): string;
+/**
+ * OpenCode reads the first of `<config root>/AGENTS.md` and `~/.claude/CLAUDE.md` that exists. A new
+ * AGENTS.md would therefore hide the user's CLAUDE.md from OpenCode, unless the host's own
+ * OPENCODE_DISABLE_CLAUDE_CODE_PROMPT switch has already turned that fallback off.
+ */
+export declare function claudeFallbackFile(env?: NodeJS.ProcessEnv): string | null;
+export type AgentFileStatus = "created" | "updated" | "unchanged" | "removed" | "absent" | "dry-run" | "refused-symlink" | "refused-not-file" | "refused-not-utf8" | "refused-malformed" | "refused-io";
+export type AgentFileResult = {
+    readonly status: AgentFileStatus;
+    readonly path: string;
+    readonly backup?: string;
+    readonly preview?: string;
+    readonly error?: string;
+};
+/**
+ * Installs or removes block `id` in `path`. `backup: false` skips the first-insert copy (a repo's
+ * AGENTS.md, where a copy would sit beside tracked files).
+ */
+export declare function applyAgentFile(input: {
+    readonly path: string;
+    readonly id?: string;
+    readonly version: string;
+    readonly body: string;
+    readonly action: "install" | "uninstall";
+    readonly dryRun?: boolean;
+    readonly now?: Date;
+    readonly backup?: boolean;
+}): AgentFileResult;
+/** `present v=<x>`, `stale v=<x>` (an older install's block), `absent`, `malformed`, or `symlink` / `not-file` / `not-utf8`. */
+export declare function agentFileState(input: {
+    readonly path: string;
+    readonly id?: string;
+    readonly version: string;
+}): string;
+export declare function agentFileLine(result: AgentFileResult): string;
+/** The stored setting in litopencode.json; LITOPENCODE_AGENT_FILE=on|off overrides it. A missing or unreadable value is `unset`. */
+export declare function readAgentFileMode(root: string, env?: NodeJS.ProcessEnv): Promise<AgentFileMode | "unset">;
+/** Stores the setting, keeping every other key; a missing litopencode.json starts from the install defaults. */
+export declare function writeAgentFileMode(root: string, mode: AgentFileMode): Promise<void>;

package/dist/cli/agent-file.js

@@ -0,0 +1,197 @@
+// The LitFamily block on disk: OpenCode's global AGENTS.md at `<config root>/AGENTS.md` (the folder
+// OpenCode itself reads, `$XDG_CONFIG_HOME/opencode` or `~/.config/opencode`), and a repo's own
+// AGENTS.md. Writes go through a temporary file and a rename and keep the file's mode. A symlink, a
+// non-regular file or a non-UTF-8 file is refused rather than rewritten, and a file system error comes
+// back as `refused-io` instead of stopping the installer. The user's original global file is copied
+// once, the first time a block goes in. The on/off setting is `agentFile` in litopencode.json.
+import { randomUUID } from "node:crypto";
+import fsSync from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { defaultGlobalConfigJson } from "../config.js";
+import { litOpenCodeConfigFileForOpenCodeRoot } from "../state.js";
+import { isRecord, readJsonObjectIfPresent } from "./json.js";
+import { inspectBlock, ManagedBlockError, removeBlock, upsertBlock } from "./managed-block.js";
+export const AGENT_FILE_ID = "litopencode";
+export const AGENT_FILE_MODES = ["on", "off"];
+// OpenCode reads the global file on every turn of every session, so the block stays small.
+export const AGENT_FILE_MAX_BYTES = 1200;
+const globalBody = `## LitFamily · LitOpenCode
+
+LitOpenCode adds the lit workflows to OpenCode (lit-plan, start-work, lit-loop, review-work, lit-adhd,
+litresearch). Its plugin hooks load the full rules each turn, so this block only sets the ground rules.
+
+- \`lit\` at the start of a prompt is LitOpenCode's activation word, not the Lit web library.
+- Plans live in \`plans/\`, the session handoff in \`HANDOFF.md\`, run state in \`.litopencode/\`. Read them
+  before resuming work in a repo.
+- Never push, publish, tag or bump a version without the user's explicit yes for that action.
+- Call work done only after its tests pass and the changed surface was checked for real.
+- In a new repo, \`lit-init\` writes a short project \`AGENTS.md\` with these conventions.
+- Turn this block off with \`litopencode agent-file off\`.
+`;
+const projectBody = `## LitFamily · project conventions
+
+This repo is worked with LitOpenCode's lit workflows (lit-plan, start-work, lit-loop, review-work).
+
+- Plans live in \`plans/\`, the session handoff in \`HANDOFF.md\`, run state in \`.litopencode/\` (keep it out
+  of commits). Read the handoff and the active plan before resuming.
+- Never push, publish, tag or bump a version without the user's explicit yes for that action.
+- Pair every behaviour change with a test that failed first, and check the changed surface for real
+  before calling it done.
+`;
+/** The shipped block text: `global` for OpenCode's AGENTS.md, `project` for a repo's AGENTS.md. */
+export function agentFileBody(kind = "global") {
+    return kind === "global" ? globalBody : projectBody;
+}
+export function globalAgentFilePath(root) {
+    return path.join(path.resolve(root), "AGENTS.md");
+}
+/**
+ * OpenCode reads the first of `<config root>/AGENTS.md` and `~/.claude/CLAUDE.md` that exists. A new
+ * AGENTS.md would therefore hide the user's CLAUDE.md from OpenCode, unless the host's own
+ * OPENCODE_DISABLE_CLAUDE_CODE_PROMPT switch has already turned that fallback off.
+ */
+export function claudeFallbackFile(env = process.env) {
+    const disabled = env.OPENCODE_DISABLE_CLAUDE_CODE_PROMPT;
+    if (disabled !== undefined && disabled !== "" && disabled !== "0" && disabled.toLowerCase() !== "false")
+        return null;
+    const home = env.OPENCODE_TEST_HOME ?? (process.platform === "win32" ? env.USERPROFILE : env.HOME) ?? os.homedir();
+    const candidate = path.join(home, ".claude", "CLAUDE.md");
+    return fsSync.existsSync(candidate) ? candidate : null;
+}
+function entryKind(filePath) {
+    try {
+        const stats = fsSync.lstatSync(filePath);
+        return stats.isSymbolicLink() ? "symlink" : stats.isFile() ? "file" : "other";
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "missing";
+        throw error;
+    }
+}
+// The text, or null for a file that is not UTF-8 (UTF-16 from a Windows editor, Latin-1): rewriting
+// one would corrupt the user's bytes outside the markers.
+function readUtf8(filePath) {
+    const bytes = fsSync.readFileSync(filePath);
+    const utf16 = (bytes[0] === 0xff && bytes[1] === 0xfe) || (bytes[0] === 0xfe && bytes[1] === 0xff);
+    if (bytes.includes(0) || utf16)
+        return null;
+    try {
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        return null;
+    }
+}
+// A unique staging name, so a leftover from a crashed run never blocks the next one.
+function writeAtomic(filePath, text) {
+    fsSync.mkdirSync(path.dirname(filePath), { recursive: true });
+    const staging = `${filePath}.litfamily-${randomUUID()}.tmp`;
+    let mode = null;
+    try {
+        mode = fsSync.statSync(filePath).mode & 0o7777;
+    }
+    catch {
+        // A new file takes the default mode.
+    }
+    try {
+        fsSync.writeFileSync(staging, text, { flag: "wx" });
+        if (mode !== null)
+            fsSync.chmodSync(staging, mode);
+        fsSync.renameSync(staging, filePath);
+    }
+    finally {
+        fsSync.rmSync(staging, { force: true });
+    }
+}
+/**
+ * Installs or removes block `id` in `path`. `backup: false` skips the first-insert copy (a repo's
+ * AGENTS.md, where a copy would sit beside tracked files).
+ */
+export function applyAgentFile(input) {
+    const { path: filePath, id = AGENT_FILE_ID, version, body, action, dryRun = false, now = new Date(), backup = true } = input;
+    try {
+        const kind = entryKind(filePath);
+        if (kind === "symlink")
+            return { status: "refused-symlink", path: filePath };
+        if (kind === "other")
+            return { status: "refused-not-file", path: filePath };
+        const text = kind === "file" ? readUtf8(filePath) : "";
+        if (text === null)
+            return { status: "refused-not-utf8", path: filePath };
+        let next;
+        try {
+            next = action === "uninstall" ? removeBlock(text, id) : upsertBlock(text, { id, version, body }, { created: kind === "missing" });
+        }
+        catch (error) {
+            if (error instanceof ManagedBlockError)
+                return { status: "refused-malformed", path: filePath };
+            throw error;
+        }
+        if (!next.changed)
+            return { status: action === "uninstall" ? "absent" : "unchanged", path: filePath };
+        if (dryRun)
+            return { status: "dry-run", path: filePath, preview: next.text };
+        if (action === "uninstall") {
+            if (next.text === "" && next.created === true)
+                fsSync.unlinkSync(filePath);
+            else
+                writeAtomic(filePath, next.text);
+            return { status: "removed", path: filePath };
+        }
+        let copy;
+        if (backup && kind === "file" && inspectBlock(text, id).state === "absent") {
+            copy = `${filePath}.litfamily-backup-${now.toISOString().replace(/[:.]/gu, "-")}`;
+            fsSync.copyFileSync(filePath, copy);
+        }
+        writeAtomic(filePath, next.text);
+        return { status: kind === "file" ? "updated" : "created", path: filePath, ...(copy === undefined ? {} : { backup: copy }) };
+    }
+    catch (error) {
+        const code = error?.code;
+        return { status: "refused-io", path: filePath, error: code ?? (error instanceof Error ? error.message : String(error)) };
+    }
+}
+/** `present v=<x>`, `stale v=<x>` (an older install's block), `absent`, `malformed`, or `symlink` / `not-file` / `not-utf8`. */
+export function agentFileState(input) {
+    const kind = entryKind(input.path);
+    if (kind === "missing")
+        return "absent";
+    if (kind === "symlink")
+        return "symlink";
+    if (kind === "other")
+        return "not-file";
+    const text = readUtf8(input.path);
+    if (text === null)
+        return "not-utf8";
+    const found = inspectBlock(text, input.id ?? AGENT_FILE_ID);
+    if (found.state !== "present")
+        return found.state;
+    return `${found.version === input.version ? "present" : "stale"} v=${found.version}`;
+}
+export function agentFileLine(result) {
+    return `AGENT_FILE: ${result.status} ${result.path}${result.backup === undefined ? "" : ` (backup: ${result.backup})`}`;
+}
+/** The stored setting in litopencode.json; LITOPENCODE_AGENT_FILE=on|off overrides it. A missing or unreadable value is `unset`. */
+export async function readAgentFileMode(root, env = process.env) {
+    const override = (env.LITOPENCODE_AGENT_FILE ?? "").trim().toLowerCase();
+    if (override === "on" || override === "off")
+        return override;
+    try {
+        const stored = (await readJsonObjectIfPresent(litOpenCodeConfigFileForOpenCodeRoot(root)))?.agentFile;
+        return stored === "on" || stored === "off" ? stored : "unset";
+    }
+    catch {
+        return "unset";
+    }
+}
+/** Stores the setting, keeping every other key; a missing litopencode.json starts from the install defaults. */
+export async function writeAgentFileMode(root, mode) {
+    const filePath = litOpenCodeConfigFileForOpenCodeRoot(root);
+    const existing = await readJsonObjectIfPresent(filePath);
+    const base = isRecord(existing) ? existing : defaultGlobalConfigJson();
+    if (base.agentFile === mode)
+        return;
+    writeAtomic(filePath, JSON.stringify({ ...base, agentFile: mode }, null, 2) + "\n");
+}

package/dist/cli/args.d.ts

@@ -1,5 +1,6 @@
 import type { ParsedArgs } from "./types.ts";
 export declare const loopCommands: readonly ["create-goals", "status", "record-evidence", "checkpoint", "steer", "complete-goals", "record-review-blockers"];
+export declare const agentFileActions: readonly ["on", "off", "remove", "project"];
 export type LoopCommand = (typeof loopCommands)[number];
 export declare function isLoopCommand(command: string | undefined): command is LoopCommand;
 export declare function parseArgs(argv: readonly string[]): ParsedArgs;

package/dist/cli/args.js

@@ -11,6 +11,7 @@ export const loopCommands = [
     "complete-goals",
     "record-review-blockers"
 ];
+export const agentFileActions = ["on", "off", "remove", "project"];
 export function isLoopCommand(command) {
     return loopCommands.some((candidate) => candidate === command);
 }
@@ -56,6 +57,8 @@ export function parseArgs(argv) {
     let directive;
     let resolve;
     let host = "auto";
+    let agentFile = "auto";
+    let agentFileDir;
     if (command === "--help" || command === "-h") {
         command = "help";
     }
@@ -71,7 +74,11 @@ export function parseArgs(argv) {
     const tuiAction = command === "tui" ? argv[1] : undefined;
     if (command === "tui" && tuiAction !== "remove")
         throw new Error("tui requires an action: remove");
-    const firstOptionIndex = command === "fetch-public" || command === "tui" ? 2 : 1;
+    const agentFileAction = command === "agent-file" ? argv[1] : undefined;
+    if (command === "agent-file" && !agentFileActions.some((action) => action === agentFileAction)) {
+        throw new Error(`agent-file requires an action: ${agentFileActions.join(", ")}`);
+    }
+    const firstOptionIndex = command === "fetch-public" || command === "tui" || command === "agent-file" ? 2 : 1;
     if (command === "fetch-public") {
         fetchPublicUrl = cleanOption(argv[1], "fetch-public URL");
         if (!fetchPublicUrl)
@@ -91,6 +98,19 @@ export function parseArgs(argv) {
             dryRun = true;
             continue;
         }
+        if (arg === "--no-agent-file") {
+            if (command !== "install")
+                throw new Error(`Unknown argument: ${arg}`);
+            agentFile = "skip";
+            continue;
+        }
+        if (arg === "--dir") {
+            if (agentFileAction !== "project")
+                throw new Error(`Unknown argument: ${arg}`);
+            agentFileDir = cleanOption(argv[index + 1], arg);
+            index += 1;
+            continue;
+        }
         if (arg === "--no-auto-update") {
             continue;
         }
@@ -315,6 +335,10 @@ export function parseArgs(argv) {
         modelPrompt: yes ? "never" : modelPrompt,
         outputStylePrompt: yes ? "never" : "auto",
         ...(tuiAction === undefined ? {} : { tuiAction }),
+        ...(agentFileAction === undefined ? {} : { agentFileAction }),
+        ...(agentFileDir === undefined ? {} : { agentFileDir }),
+        agentFile,
+        assumeYes: yes,
         host,
         loop: {
             projectRoot,

package/dist/cli/doctor.js

@@ -14,6 +14,7 @@ import { inspectHostCompactionPoint, inspectHostLimits } from "./host-limits.js"
 import { autoHandoffEnvEnabled, autoHandoffEnvPercent, createAutoHandoffSettings } from "../auto-handoff.js";
 import { inspectLspCapability } from "./lsp-capability.js";
 import { probeMotionRuntime } from "./motion-runtime.js";
+import { agentFileState, globalAgentFilePath, readAgentFileMode } from "./agent-file.js";
 import { isLitOpenCodeEntry } from "./plugin-mutation.js";
 import { inspectTuiPlugin, planCliJsonCleanup } from "./tui-config.js";
 import { detectOpenCodeHosts, targetsV1, targetsV2 } from "./host-detect.js";
@@ -256,10 +257,19 @@ export async function doctor(root, hostChoice = "auto") {
     if (autoHandoff.enabled && autoHandoff.percent !== null && hostCompaction.percent !== null && autoHandoff.percent >= hostCompaction.percent) {
         autoHandoffWarnings.push(`OpenCode compacts on its own at about ${hostCompaction.percent}% of the context window. Your ${autoHandoff.percent}% is at or above that, so the host compacts first and the handoff has no time to run. Choose a percent below ${hostCompaction.percent}.`);
     }
+    const agentFilePath = globalAgentFilePath(root);
+    const agentFileMode = await readAgentFileMode(root);
+    const agentFileBlock = agentFileMode === "off" ? "off" : agentFileState({ path: agentFilePath, version: metadata.version });
     return {
         exitCode: 0,
         stdout: JSON.stringify({
             package: metadata,
+            agentFile: {
+                path: agentFilePath,
+                state: agentFileBlock,
+                mode: agentFileMode,
+                line: `AGENT_FILE: ${agentFileBlock} (${agentFilePath}; change: litopencode agent-file on|off)`
+            },
             capabilities: openCodeHostCapabilities(),
             hostLimits: { path: hostConfig.path, ...inspectHostLimits(hostConfig.config) },
             host: {

package/dist/cli/install.d.ts

@@ -7,4 +7,7 @@ import { type HostChoice } from "./host-detect.ts";
  */
 export declare function withoutV2PluginEntries(config: Record<string, unknown> | null): Record<string, unknown> | null;
 export declare function assertNoHostOnlyKeysAdded(before: Record<string, unknown> | null, next: Record<string, unknown> | null): void;
-export declare function install(root: string, dryRun: boolean, modelSelection?: InstallModelSelection | undefined, modelPrompt?: ModelPromptMode, permissionMode?: InstallPermissionMode, permissionModeExplicit?: boolean, permissionPrompt?: PermissionPromptMode, progress?: InstallProgress, outputStylePrompt?: PermissionPromptMode, host?: HostChoice): Promise<CliResult>;
+export declare function install(root: string, dryRun: boolean, modelSelection?: InstallModelSelection | undefined, modelPrompt?: ModelPromptMode, permissionMode?: InstallPermissionMode, permissionModeExplicit?: boolean, permissionPrompt?: PermissionPromptMode, progress?: InstallProgress, outputStylePrompt?: PermissionPromptMode, host?: HostChoice, agentFileChoice?: {
+    readonly assumeYes: boolean;
+    readonly skip: boolean;
+}): Promise<CliResult>;