name: lark-base-project-ops description: "Operate Lark/Feishu Base for project research OSes, Kanban, task lists, and permission-sensitive app/bot workflows." version: 1.0.0

Lark Base Project Ops

Use this skill when the user wants to set up or operate a Lark Base as a project OS for research, planning, or Kanban-style task tracking.

Core workflow

1. Clarify the target system

• Prefer one Base per class of work (e.g. one Policy Lab OS with a Research Project field) unless the user explicitly wants hard separation.
• If the user asks for a project board, propose a single Base with filtered views before proposing many separate Bases.

• Hybrid Design Decision (Jul 2026): For high-fidelity AI operations, use a Hybrid Kanban Pattern. Lark Base serves as the Company State (executive view, human-readable status, deadlines). Hermes Kanban (~/.hermes/kanban.db) serves as the Execution OS (AI agent claim/run/log, decompose, heartbeats). Both systems are linked by the shared Handoff Task ID. See handoff-task skill for the integration spec.

• Inspect current structure before editing

• Read the existing Base/table/field/view structure first.
• Reuse existing fields when possible; only add what is missing.

• Keep the first Base table as the system of record for tasks.

• Recommended Base schema for research work

• Task — primary text field.
• Research Project — select field used to partition multiple projects inside one Base.
• Phase — select field for research lifecycle.
• Status — select field for Kanban grouping.
• Priority — select field.
• Workstream — multi-select field.
• Assigned To — user field.
• Output, Evidence / Source, Notes, Due date, AI follow-up.

• Add Created at and Updated at if not already present.

• View design

• Create a Kanban view grouped by Status.
• Create a Grid view grouped by Phase for planning and review.

• Use the Base's built-in grouping; do not invent a second Kanban system outside the Base unless requested.

• Seed the board

• Start with a few sample tasks only after the schema is approved or clearly aligned with the user’s requested flow.
• Seed tasks should cover setup, question challenge, and first-round viability research so the board is immediately useful.

Permission model and identity pitfalls

• Bot-only is usually enough for creating and managing Base structures, task boards, and records.
• If the user wants to become the real owner of the Base or hit share/permission walls, switching the CLI to user identity can be the fastest fix.
• If the CLI is in strict bot mode, user identity login may be blocked until the policy is changed. Use lark-cli config strict-mode off first (requires explicit user confirmation), then lark-cli auth login --no-wait --json for device flow.
• Bot-created Base ownership pitfall (critical): If a Base is created by the bot/app, the human user does NOT automatically get manage/full access. The user will see "Only users with manage permission…" when trying to share. Owner of the Lark app ≠ owner of the Base document — these are two separate permission layers. The cleanest fix is to recreate the Base under user identity (--as user) rather than trying to transfer ownership from bot.
• When the user hits share/permission walls on a bot-created Base, do NOT spend multiple turns trying to fix permissions on the existing Base. Propose recreating under user identity early.
• Device flow auth: The verification URL from lark-cli auth login --no-wait --json typically includes the user_code as a URL parameter. The user just needs to open the URL and approve — do NOT tell them to separately "enter a code" unless the URL lacks it. After user confirms, run lark-cli auth login --device-code <code> to complete.
• After switching to user identity, all subsequent lark-cli commands must include --as user for user-owned resources. Without it, commands default to bot identity and will get permission errors on user-owned Bases.

CLI / setup pattern

• Prefer the high-level lark-cli ... +shortcut commands over raw API calls.
• Before creating fields, read the field JSON schema/reference for the exact payload shape.
• For Base creation, ensure the app has the required scope first; if scope is missing, surface the exact scope and ask the user to approve that specific permission.
• For selection fields, define the options up front; for research project partitioning, use a Research Project select field with one project value initially.
• +record-batch-create JSON shape (critical): Must use {"fields":["col1","col2",...], "rows":[["val1","val2",...], ...]} — NOT an array of {fields: {...}} objects. Multi-select values must be passed as an array in the cell (e.g. ["Desk Research","Data & Evidence"]).
• +view-set-group JSON shape: Must use {"group_config":[{"field":"FieldName","desc":false}]} — not {"groups":[...]} or a bare array.
• No +base-delete command: lark-cli cannot delete an entire Base, only tables, views, and records. To clean up a bot-owned Base, either mark it as legacy or work with the user to delete it manually via the Lark UI.
• All user-identity commands need --as user flag. Example: lark-cli base +view-create ... --as user. Without this flag, commands fall back to bot identity even after login.
• Strict mode → off → user login sequence: lark-cli config strict-mode off # requires user confirmation first lark-cli auth login --no-wait --json # get device flow URL # user approves URL in browser lark-cli auth login --device-code <device_code> # complete login

Good defaults for Policy Lab OS

• One Base: Policy Lab
• One table: Research Tasks
• Views:
• Kanban Status (Kanban view, grouped by Status)
• Grid View by Phase (Grid view, grouped by Phase)
• Complete seed tasks: Always seed tasks across the complete pipeline (all 9 phases, not just the first 3). E.g.:
• Setup & Scope: System/setup task marked Done.
• Question Challenge: Question definition task marked Next.
• Viability Research: First-round literature search marked Backlog.
• Topic Selection: Regional models assessment marked Backlog.
• Literature Review: National policy collection marked Backlog.
• Policy/Market Analysis: Stakeholder interviews/surveys marked Backlog.
• Synthesis: Expert workshop/panel synthesis marked Backlog.
• Output Drafting: Draft policy brief creation marked Backlog.
• Review & Publish: Peer review and publishing marked Backlog.

Communication style for this class of task

• Be concise when the user asks for a short answer.
• If the user says “don’t repeat the same issue”, avoid re-explaining the same root cause; give the next action or the exact blocker.
• Separate what is already done from what still needs user action.
• When the user wants approval before execution, present the plan first and wait.
• For one-time setup handoffs, do not default to recurring/reporting language; deliver the result immediately and keep the announcement short.

Trigger design for setup announcements

• One-time setup completions should use an event-driven handoff, not polling.
• After a technical setup is completed, immediately deliver the setup summary to the target department/topic in the same turn or via a one-shot delivery mechanism.
• Do not create recurring cron jobs for a one-time announcement. Recurring jobs are only for periodic health checks, reminders, or reports.
• If a department/topic needs the setup record later, write the canonical summary to a shared knowledge file first, then deliver a short notification to the target thread/topic.
• If delivery must be retried, treat it as a failed notification and fix the delivery target/transport rather than switching to a polling schedule.

Shared knowledge and department delivery

• For cross-topic operational state (e.g. “this Base is ready” or “this integration is configured”), store a compact summary in the shared knowledge base first.
• Keep the notification message short and action-oriented, with a link or next step when relevant.
• When a user transfers the handoff manually, treat that as a sign the workflow should be redesigned so the assistant performs the delivery automatically next time.

Verification checklist

• Confirm the Base URL/token returned by the CLI.
• Confirm table IDs and field IDs after creation.
• Confirm the Kanban view groups on the intended field.
• Confirm seeded rows appear in the board.
• If permissions were skipped or partially granted, say exactly which user grant was skipped and why.

Support files

• references/policy-lab-os.md — session-derived setup notes, permission pitfalls, and a compact example schema for research boards.