@haposoft/cafekit 0.8.16 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.8.16",
+  "version": "0.9.0",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",
@@ -43,5 +43,8 @@
   ],
   "engines": {
     "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.15.11"
   }
 }

package/src/claude/CLAUDE.md

@@ -15,7 +15,7 @@ These rules reduce common agent coding failures: hidden assumptions, overbuilt s
 - Do not assume silently. State assumptions when they affect the work.
 - If multiple interpretations are plausible, surface them before implementation.
 - If the simpler option is likely better, say so and push back.
-- If the task/spec is too vague to verify, stop and ask or route back to spec correction.
+- If the task/spec is too vague to verify, use `/hapo:qs` or ask one grounded clarification before planning.
 - Before feature planning or coding, read `./README.md` for project context.
 
 ### 2. Simplicity First
@@ -46,7 +46,7 @@ These rules reduce common agent coding failures: hidden assumptions, overbuilt s
 Use this loop for non-trivial work:
 
 1. **Understand** — read README, relevant docs, active spec/task, and existing code.
-2. **Plan** — choose the smallest coherent path; use `/hapo:specs` for feature specs when needed.
+2. **Plan** — choose the smallest coherent path; use `/hapo:qs` when requirements are unclear and `/hapo:specs` for feature specs when ready.
 3. **Execute** — implement only the active task/scope; no placeholder completion.
 4. **Verify** — run exact task commands first, then repo-level lint/test/build as needed.
 5. **Sync** — mark task state only after proof exists.

package/src/claude/migration-manifest.json

@@ -27,6 +27,7 @@
       "mobile-development",
       "pdf",
       "pptx",
+      "qs",
       "react-best-practices",
       "research",
       "specs",

package/src/claude/rules/skill-domain-routing.md

@@ -29,6 +29,7 @@ User wants to...
 
 ```text
 User wants to...
+├── clarify missing requirements or acceptance criteria   -> /hapo:qs
 ├── find files, locate code, scan project structure       -> /hapo:inspect
 ├── diagnose an error or failing check                    -> /hapo:debug
 ├── understand possible side effects                      -> /hapo:impact-analysis
@@ -41,6 +42,7 @@ Local source truth comes from `/hapo:inspect`; external/current knowledge comes
 
 ```text
 User wants to...
+├── prepare stakeholder/customer questions before docs     -> /hapo:qs --batch
 ├── create missing project docs                           -> /hapo:docs --init
 ├── update docs after source changes                      -> /hapo:docs --update
 ├── summarize codebase quickly                            -> /hapo:docs --summarize

package/src/claude/rules/skill-workflow-routing.md

@@ -7,11 +7,12 @@ Do not inject or force a skill when the user explicitly asks for a direct answer
 ## Core Specification Workflow
 
 ```text
-/hapo:brainstorm -> /hapo:specs -> /hapo:develop -> /hapo:test -> /hapo:code-review -> /hapo:git
+/hapo:qs -> /hapo:brainstorm -> /hapo:specs -> /hapo:develop -> /hapo:test -> /hapo:code-review -> /hapo:git
 ```
 
 | User intent | Suggested start |
 |---|---|
+| vague request, missing acceptance criteria, unclear scope, stakeholder questions | `/hapo:qs` |
 | unclear idea, possible approaches, scope tradeoffs | `/hapo:brainstorm` |
 | create requirements, design, task breakdown, validate spec | `/hapo:specs` |
 | implement an approved spec or a specific task file | `/hapo:develop` |
@@ -81,4 +82,5 @@ Use `/hapo:research` for external knowledge. Use `/hapo:inspect` for local sourc
 - Add a secondary skill only when it materially changes execution.
 - Prefer explicit user commands over this table.
 - If two workflows conflict, ask one concise clarification.
+- If missing information blocks workflow selection, use `/hapo:qs` before choosing brainstorm/specs/develop.
 - If the user asks to "fix" and root cause is unknown, start with `/hapo:debug` unless the issue is trivial and local.

package/src/claude/skills/qs/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: hapo:qs
+description: "Clarify vague requests before planning or implementation. Use when requirements, acceptance criteria, scope, constraints, stakeholder decisions, or next workflow readiness are unclear."
+argument-hint: "<request_or_context> [--batch|--spec-ready|--stakeholder]"
+version: 1.0.0
+---
+
+# QS Skill
+
+`hapo:qs` turns unclear intent into answerable questions and a readiness verdict. It is a clarification gate before `hapo:brainstorm`, `hapo:specs`, `hapo:docs --reconstruct`, `hapo:debug`, or `hapo:develop`.
+
+## Core Stance
+
+- Context before questions. Read the useful project/spec/docs/source context before asking.
+- Questions are work products. Make them specific, prioritized, and easy to answer.
+- One thing at a time in interactive mode.
+- Prefer multiple-choice options with a recommended default when the context supports it.
+- Do not design the solution unless the user explicitly moves to `hapo:brainstorm`.
+- Do not create specs or write code from this skill.
+
+<CLARIFICATION-ONLY-GATE>
+Do NOT implement, scaffold, edit product code, generate full specs, or make architecture decisions as final.
+The output is questions, assumptions, readiness, and next-step guidance.
+</CLARIFICATION-ONLY-GATE>
+
+## When To Use
+
+Use `hapo:qs` when:
+- The request is too vague to verify.
+- Acceptance criteria are missing.
+- Scope boundary is unclear.
+- Stakeholder/customer input is needed before specs.
+- The user asks "what should I ask?", "what is missing?", "can this go to specs?", or "is this clear enough?"
+- A spec/task has ambiguity that would make `hapo:develop` risky.
+- A legacy reconstruction or bug report lacks enough scope to start the correct workflow.
+
+Do not use it when:
+- The user asks for a direct factual answer that can be answered safely.
+- The user already gave exact output, acceptance criteria, scope, constraints, and target files.
+- The right action is clearly `hapo:debug`, `hapo:inspect`, `hapo:research`, or `hapo:docs --reconstruct`.
+
+## Modes
+
+- Default interactive mode: ask one highest-value question, then wait.
+- `--batch`: produce a grouped question list for a stakeholder/customer/team.
+- `--spec-ready`: audit whether the request can move to `hapo:specs`.
+- `--stakeholder`: write business-friendly questions with minimal implementation jargon.
+
+If multiple modes appear, use the most restrictive mode in this order: `--spec-ready`, `--batch`, `--stakeholder`, default.
+
+## Workflow
+
+### 1. Context Scout
+
+Read only enough context to make the questions concrete:
+- `README.md`
+- relevant `docs/`
+- relevant `specs/`
+- relevant source files when the request names a feature, module, API, UI, or bug
+
+Use `hapo:inspect` or focused search when the location is unclear. Do not scan the whole repo unless the question is about the whole repo.
+
+### 2. Build The Clarification Map
+
+Create a private map with these fields:
+
+```text
+Known facts:
+Assumptions:
+Missing decisions:
+Blocking unknowns:
+Non-blocking unknowns:
+Possible next workflow:
+```
+
+Classify each unknown:
+- `P0`: blocks correct next action.
+- `P1`: high-risk ambiguity; should answer before implementation.
+- `P2`: useful detail; can defer.
+
+### 3. Ask Or Report
+
+Default interactive mode:
+- Ask exactly one `P0` question.
+- Make it concrete and grounded in observed context.
+- If possible, provide 2-3 options.
+- Put the recommended option first and explain the tradeoff in one sentence.
+
+`--batch` or `--stakeholder`:
+- Produce grouped questions by priority.
+- Keep each question answerable.
+- Include recommended options only when they are justified by context.
+
+`--spec-ready`:
+- Return a readiness checklist and verdict.
+- Do not ask a long question list unless verdict is `not-ready`.
+
+### 4. Readiness Verdict
+
+End with one of:
+- `not-ready`: missing P0 decisions.
+- `brainstorm-ready`: enough to explore solution options, but not enough for specs.
+- `specs-ready`: enough to run `/hapo:specs <request>`.
+- `develop-ready`: an approved spec/task exists and no blocking ambiguity remains.
+
+### 5. Next Step
+
+Suggest exactly one next command:
+- `/hapo:qs ...` when another clarification round is required.
+- `/hapo:brainstorm ...` when design/options are still open.
+- `/hapo:specs ...` when requirements are clear enough.
+- `/hapo:debug ...` when the issue is a bug with unknown root cause.
+- `/hapo:docs --reconstruct <scope>` when the task is legacy/as-is docs.
+- `/hapo:develop <feature>` only when an approved spec/task is already clear.
+
+## Output Formats
+
+### Default Interactive Output
+
+```markdown
+**Context Read**
+- ...
+
+**Known**
+- ...
+
+**Blocking Unknown**
+- P0: ...
+
+**Question**
+...
+
+**Options**
+- A. ... (Recommended) - ...
+- B. ... - ...
+- C. ... - ...
+
+**Readiness**
+not-ready | brainstorm-ready | specs-ready | develop-ready
+
+**Next**
+/hapo:qs ...
+```
+
+### Batch Output
+
+Use `templates/qs.md` when the user asks to save or document the question set.
+
+```markdown
+**Question Set**
+
+**P0 - Must Answer**
+1. ...
+
+**P1 - Should Answer**
+1. ...
+
+**P2 - Can Defer**
+1. ...
+
+**Assumptions To Confirm**
+- ...
+
+**Readiness**
+...
+
+**Next**
+...
+```
+
+## Quality Bar
+
+- Every P0 question must explain what decision it unlocks.
+- No generic "please clarify" questions.
+- No more than one interactive question per response.
+- No implementation plan unless the next command is `hapo:brainstorm` or `hapo:specs`.
+- If no P0/P1 unknown exists, do not invent questions. Say it is ready and name the next command.

package/src/claude/skills/qs/templates/qs.md

@@ -0,0 +1,30 @@
+# Question Set: {{TITLE}}
+
+## Context Read
+- {{CONTEXT_ITEM}}
+
+## Known Facts
+- {{KNOWN_FACT}}
+
+## Assumptions
+- {{ASSUMPTION}}
+
+## P0 - Must Answer
+1. **Question:** {{P0_QUESTION}}
+   - **Why it matters:** {{WHY_IT_MATTERS}}
+   - **Recommended answer:** {{RECOMMENDED_ANSWER}}
+   - **Other options:** {{OTHER_OPTIONS}}
+
+## P1 - Should Answer
+1. **Question:** {{P1_QUESTION}}
+   - **Risk if unanswered:** {{RISK}}
+
+## P2 - Can Defer
+1. **Question:** {{P2_QUESTION}}
+   - **Can defer until:** {{DEFER_POINT}}
+
+## Readiness Verdict
+`not-ready | brainstorm-ready | specs-ready | develop-ready`
+
+## Next Command
+`/hapo:qs ... | /hapo:brainstorm ... | /hapo:specs ... | /hapo:debug ... | /hapo:docs --reconstruct ... | /hapo:develop ...`

package/src/opencode/AGENTS.md

@@ -0,0 +1,140 @@
+# AGENTS.md
+
+Primary operating instructions for OpenCode using the CafeKit runtime.
+
+## OpenCode Runtime Mapping
+
+- Project instructions live in `AGENTS.md`.
+- CafeKit commands live in `.opencode/commands/` and use OpenCode-native slash names without the `hapo:` prefix.
+- CafeKit subagents live in `.opencode/agents/` using OpenCode frontmatter.
+- CafeKit skills live in `.opencode/skills/` and are read natively by OpenCode.
+- Shared CafeKit support files live in `.opencode/rules/`, `.opencode/scripts/`, `.opencode/references/`, and `.opencode/runtime.json`.
+- OpenCode config is merged into `opencode.json`; keep project-specific model/provider choices there.
+
+## Command Surface
+
+Use these OpenCode commands:
+
+- `/brainstorm <idea-or-problem>`: scout and narrow an unclear idea before specs.
+- `/qs <request-or-context> [--batch|--spec-ready|--stakeholder]`: clarify requirements, missing decisions, and next workflow readiness.
+- `/specs <feature-or-spec-command>`: create, update, validate, or approve specs.
+- `/develop <feature> [task-file] [--flash]`: implement approved spec tasks.
+- `/test [scope|--full]`: verify implementation and collect evidence.
+- `/code-review [scope|--pending]`: review for correctness, regressions, and scope drift.
+- `/debug <issue>`: diagnose root cause without product-code edits.
+- `/hotfix <issue>`: apply a narrow, scout-first production fix.
+- `/docs [--init|--update|--summarize|--reconstruct]`: maintain or reconstruct project docs.
+- `/inspect <target>`: inspect source, artifacts, or external context.
+- `/generate-graph <request>`: generate technical diagrams.
+
+The underlying CafeKit skills are still named `hapo:*` in their documentation. In OpenCode, use the commands above; each command reads the matching skill from `.opencode/skills/<skill>/SKILL.md`.
+
+## Core Objective
+
+Act as the project orchestrator: understand the request, keep scope tight, use the right CafeKit skill/agent, and deliver verified work that follows the project's architecture.
+
+## Core Behavior
+
+These rules reduce common agent coding failures: hidden assumptions, overbuilt solutions, unrelated edits, and unverified completion claims. They take priority over speed-oriented shortcuts.
+
+### 1. Think Before Coding
+
+- Do not assume silently. State assumptions when they affect the work.
+- If multiple interpretations are plausible, surface them before implementation.
+- If the simpler option is likely better, say so and push back.
+- If the task/spec is too vague to verify, use `/qs` or ask one grounded clarification before planning.
+- Before feature planning or coding, read `./README.md` for project context.
+
+### 2. Simplicity First
+
+- Solve the requested problem with the smallest maintainable change.
+- Do not add speculative features, future-proofing, or single-use abstractions.
+- Reuse existing modules before creating new ones.
+- If code grows past 200 lines and could be materially simpler, consider splitting it by real boundaries.
+- Prefer YAGNI, KISS, and DRY in that order.
+
+### 3. Surgical Changes
+
+- Touch only files required by the task.
+- Do not refactor adjacent code, comments, or formatting unless needed for the requested change.
+- Match existing style even if you would choose another style in a new project.
+- Remove only dead code/imports created by your own change.
+- Mention unrelated issues instead of fixing them opportunistically.
+
+### 4. Goal-Driven Execution
+
+- Convert requests into verifiable success criteria.
+- For spec tasks, use `Completion Criteria` and `Evidence` as the source of truth. Existing task files may use `Task Test Plan & Verification Evidence` or legacy `Verification & Evidence`.
+- For bugs, reproduce with a failing test or concrete evidence when feasible before fixing.
+- Loop until verification passes or a real blocker is recorded.
+
+## CafeKit Operating Loop
+
+Use this loop for non-trivial work:
+
+1. Understand: read README, relevant docs, active spec/task, and existing code.
+2. Plan: choose the smallest coherent path; use `/qs` when requirements are unclear and `/specs` for feature specs when ready.
+3. Execute: implement only the active task/scope; no placeholder completion.
+4. Verify: run exact task commands first, then repo-level lint/test/build as needed.
+5. Sync: mark task state only after proof exists.
+
+## OpenCode Runtime Limits And Replacements
+
+- Claude Code hooks/statusline/settings do not run in OpenCode.
+- Treat `.claude/rules/*` as explicit reference material, not injected hook context.
+- When a skill says to use unavailable Claude-specific tools such as `Task`, `TodoWrite`, or `AskUserQuestion`, use OpenCode's agent/subtask flow, a concise markdown checklist, or ask the user directly.
+- Privacy and inspect gates are instruction-level gates in OpenCode unless a project-specific OpenCode plugin adds hard enforcement.
+
+## Operating Discipline
+
+- If a CafeKit skill may apply, read and use that skill before acting.
+- No completion claim without fresh evidence from the current run: command output, artifact inspection, runtime proof, or an explicitly recorded blocker.
+- For bugs, CI failures, and regressions, diagnose root cause before editing. Symptom patches are not completion.
+- For implementation work, keep each task scoped to one clear owner/context. Reviewers should receive task files, diffs, and acceptance criteria, not chat history.
+- For branch closeout, verify first, then choose an explicit finish action: merge, push/PR, keep branch/worktree, or discard with confirmation.
+
+## Definition Of Done
+
+A task is done only when all apply:
+
+- implementation satisfies `Completion Criteria`
+- `Evidence` is satisfied with concrete proof
+- preflight/build/test outcomes are passing or an explicit blocker is recorded
+- code review has no critical issues
+- a verification receipt exists before task state is synced to `done`
+
+`NO_TESTS` and `0 tests + exit 0` are not passing outcomes when the task requires automated tests.
+
+## Rule References
+
+Consult these when the task touches the relevant area:
+
+- Primary workflow: `./.claude/rules/workflow.md`
+- Development rules: `./.claude/rules/ai-dev-rules.md`
+- Subagent coordination: `./.claude/rules/orchestrator.md`
+- Docs maintenance: `./.claude/rules/manage-docs.md`
+- State sync: `./.claude/rules/state-sync.md`
+- Hook handling reference: `./.claude/rules/hook-protocols.md`
+- Other protocols: `./.claude/rules/*`
+
+## Skill And Script Use
+
+- Evaluate the installed skill catalog before work and activate the relevant skill(s).
+- If there is a reasonable chance a skill applies, prefer the skill workflow over ad hoc execution.
+- If modifying skills, edit the current project/runtime files, not `~/.claude/skills` directly.
+- Run Python skill scripts with the skill venv:
+  - macOS/Linux: `.claude/skills/.venv/bin/python3 scripts/<script>.py`
+  - Windows: `.claude\skills\.venv\Scripts\python.exe scripts\<script>.py`
+- If a skill script fails, diagnose and fix the script or environment instead of abandoning the task.
+
+## Git And Reporting
+
+- Use conventional commits.
+- Do not add AI attribution by default.
+- Lint before commit and run the full required verification before push.
+- Keep commits focused on actual changes.
+- Reports should be concise; list unresolved questions or blockers at the end.
+
+## Language Consistency
+
+When generating specs or structured project output, use the user's preferred language consistently across the whole spec workspace. Technical terms, code samples, and file paths may remain English.

package/src/opencode/plugins/docs-sync.ts

@@ -0,0 +1,181 @@
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * OpenCode Plugin — docs-sync.ts
+ *
+ * Port of .claude/hooks/docs-sync.cjs.
+ *
+ * Behavior:
+ * - On session.created: detect if project has source code but no docs/, or if
+ *   docs/.sync_hash is stale relative to current source-only git hash.
+ * - Write banner to `.opencode/session-banner.md` so AGENTS.md / skills can
+ *   surface it (OpenCode event console.log does not flow into assistant
+ *   context, only the server log).
+ * - Also print to stderr so the OpenCode server log records it.
+ *
+ * Disable via `.opencode/runtime.json` { "docsSync": false }.
+ */
+
+import type { Plugin } from "@opencode-ai/plugin";
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  appendFileSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+
+const PLUGIN_DIR = dirname(fileURLToPath(import.meta.url));
+const BANNER_SECTION_START = "<!-- CAFEKIT DOCS SYNC START -->";
+const BANNER_SECTION_END = "<!-- CAFEKIT DOCS SYNC END -->";
+
+function readRuntime(cwd: string): Record<string, any> {
+  try {
+    const file = join(cwd, ".opencode", "runtime.json");
+    return existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+  } catch {
+    return {};
+  }
+}
+
+function resolveDocsDir(cwd: string, runtime: Record<string, any>): string {
+  const configured = runtime.paths?.docs;
+  return join(cwd, typeof configured === "string" && configured ? configured : "docs");
+}
+
+function hasSourceCode(cwd: string): boolean {
+  return (
+    existsSync(join(cwd, "src")) ||
+    existsSync(join(cwd, "app")) ||
+    existsSync(join(cwd, "lib")) ||
+    existsSync(join(cwd, "package.json")) ||
+    existsSync(join(cwd, "index.js")) ||
+    existsSync(join(cwd, "main.py"))
+  );
+}
+
+function currentSourceHash(cwd: string): string {
+  try {
+    return execSync('git log -1 --format="%H" -- . ":(exclude)docs"', {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+function buildMissingDocsBanner(): string {
+  return [
+    "### 🔴 URGENT SYSTEM ACTION: MISSING DOCUMENTATION 🔴",
+    "> BẮT BUỘC (MANDATORY): Hệ thống phát hiện dự án đã có Source Code nhưng thư mục `docs/` chưa tồn tại.",
+    "> Nhiệm vụ ĐẦU TIÊN của bạn trong session này là đọc hiểu mã nguồn hiện tại và tạo ra các tài liệu tiêu chuẩn:",
+    "> 1. `docs/system-architecture.md` (Kiến trúc hệ thống, phân tích flow)",
+    "> 2. `docs/project-overview-pdr.md` (Tổng quan, mục tiêu, tính năng)",
+    "> 3. Khởi tạo file hidden `docs/.sync_hash` để theo dõi cập nhật.",
+    "> ",
+    '> LƯU Ý BẮT BUỘC: Bạn phải chạy lệnh Git này trong Terminal để lấy Hash Code mới nhất: `git log -1 --format="%H" -- . ":(exclude)docs"`',
+    "> Sau đó ghi chuẩn giá trị Hash đó vào file `docs/.sync_hash`.",
+  ].join("\n");
+}
+
+function buildStaleDocsBanner(currentHash: string, lastSyncHash: string): string {
+  return [
+    "### 🔄 CONTINUOUS DOCS SYNC REQUIRED 🔄",
+    `> Source Code vừa có sự thay đổi mới (Git Hash: \`${currentHash}\`) kể từ lần đồng bộ Docs cuối cùng (\`${lastSyncHash || "Chưa gán"}\`).`,
+    "> YÊU CẦU TRƯỚC KHI LÀM THÊM TÍNH NĂNG:",
+    `> 1. Rà soát file bị thay đổi gần đây (dùng \`git diff ${lastSyncHash} ${currentHash}\` hoặc \`git log\`).`,
+    "> 2. Cập nhật lại `docs/system-architecture.md` hoặc các chuẩn code nếu cần thiết.",
+    "> 3. Cập nhật Changelog (nhật ký thay đổi).",
+    `> 4. KHI HOÀN TẤT, BẠN PHẢI GHI ĐÈ GIÁ TRỊ SAU: \`${currentHash}\` VÀO FILE \`docs/.sync_hash\` ĐỂ CHỐT TRẠNG THÁI HIỆN TẠI.`,
+  ].join("\n");
+}
+
+function writeBanner(cwd: string, banner: string | null): void {
+  const target = join(cwd, ".opencode", "session-banner.md");
+  const dir = dirname(target);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  const existing = existsSync(target) ? readFileSync(target, "utf8") : "";
+  const pattern = new RegExp(`${BANNER_SECTION_START}[\\s\\S]*?${BANNER_SECTION_END}\\n?`);
+  const cleaned = existing.replace(pattern, "").trimEnd();
+
+  if (!banner) {
+    if (cleaned !== existing.trimEnd()) {
+      writeFileSync(target, cleaned ? `${cleaned}\n` : "");
+    }
+    return;
+  }
+
+  const block = [BANNER_SECTION_START, banner, BANNER_SECTION_END].join("\n");
+  const next = cleaned ? `${cleaned}\n\n${block}\n` : `${block}\n`;
+  writeFileSync(target, next);
+}
+
+function logCrash(error: unknown): void {
+  try {
+    const logDir = join(PLUGIN_DIR, ".logs");
+    if (!existsSync(logDir)) mkdirSync(logDir, { recursive: true });
+    appendFileSync(
+      join(logDir, "hook-log.jsonl"),
+      JSON.stringify({
+        ts: new Date().toISOString(),
+        hook: "docs-sync",
+        status: "crash",
+        error: error instanceof Error ? error.message : String(error),
+      }) + "\n",
+    );
+  } catch {
+    // fail-open
+  }
+}
+
+export const DocsSync: Plugin = async ({ directory }) => ({
+  event: async ({ event }) => {
+    try {
+      if (event.type !== "session.created") return;
+
+      const cwd = directory;
+      const runtime = readRuntime(cwd);
+      if (runtime.docsSync === false) return;
+
+      if (!hasSourceCode(cwd)) {
+        writeBanner(cwd, null);
+        return;
+      }
+
+      const docsDir = resolveDocsDir(cwd, runtime);
+
+      if (!existsSync(docsDir)) {
+        const banner = buildMissingDocsBanner();
+        writeBanner(cwd, banner);
+        console.error(banner);
+        return;
+      }
+
+      const currentHash = currentSourceHash(cwd);
+      if (!currentHash) {
+        writeBanner(cwd, null);
+        return;
+      }
+
+      const syncFile = join(docsDir, ".sync_hash");
+      const lastSyncHash = existsSync(syncFile) ? readFileSync(syncFile, "utf8").trim() : "";
+
+      if (lastSyncHash === currentHash) {
+        writeBanner(cwd, null);
+        return;
+      }
+
+      const banner = buildStaleDocsBanner(currentHash, lastSyncHash);
+      writeBanner(cwd, banner);
+      console.error(banner);
+    } catch (error) {
+      logCrash(error);
+    }
+  },
+});