Skip to content
Back to search

work-plan

Large project management plugin for Antigravity with Knowledge & Memory (OKF & Markdown Knowledge Packs), task DAGs, and live edit guards (~60% token savings, 2-3x time savings)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/minyaozhu--work-plan/badge.svg)](/listings/minyaozhu--work-plan)

HTML

<a href="/listings/minyaozhu--work-plan"><img src="/api/listings/minyaozhu--work-plan/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Clone this repository directly into Antigravity's global plugins folder (no `npm install` or build step required for end users because `ui/app.html` is pre-bundled):

git clone https://github.com/minyaozhu/work-plan.git ~/.gemini/config/plugins/work-plan

Once installed: - Open **Work Plan** from the conversation side pane **`+` menu**, or ask the agent `"Open Work Plan"` to receive a one-click `[Work Plan](sidecar://work-plan/work_plan/)` pill. - If the plugin was already loaded before updating, toggle **work-plan** off and back on in Customizations (or restart Antigravity) to reload the aux pane.

Try It in 10 Seconds (Examples & Local Browser Preview)

This repository ships ready-to-use samples in [`examples/`](examples/): - [`examples/PLAN.md`](examples/PLAN.md) — seed a multi-phase project immediately via **+ New Project → Markdown plan**. - [`examples/okf-knowledge-pack/`](examples/okf-knowledge-pack/) — link a standards-compliant **OKF v0.2** bundle in **Knowledge & Memory → Knowledge Pack**. - Want to preview the UI in any browser without Antigravity? Run:

npm run start:sidecar
# open http://127.0.0.1:8765

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 123 lines
  1. # Work Plan (`work-plan`)
  2. A zero-ops, fully local **Antigravity** plugin for a single developer managing large, multi-day engineering projects across sequential or concurrent chats — with **no backend servers**, **no external databases**, and **no runtime dependencies**.
  3. > **Why Work Plan?**
  4. > - **Large Project Management with Knowledge & Memory Organization:** Break complex codebases into persistent dependency-tracked task trees (up to 500 tasks, depth 8) paired with structured **Project Memory** and portable **Knowledge Packs** (**OKF** bundles & single **Markdown** files).
  5. > - **Empirical ~60% Token Savings & 2–3× Time Savings:** Eliminates repetitive context re-explaining and redundant repo re-scans across sessions via SHA-deduped `[WORK PLAN]` turn briefs, progressive-disclosure Knowledge Packs, structured task handoffs, and safe parallel multi-chat execution with live file-edit guards.
  6. | Capability | Impact |
  7. | :--- | :--- |
  8. | **Large Project Management + Knowledge & Memory** | Keep multi-day specs, task DAGs, durable memories, and OKF/Markdown Knowledge Packs organized in one local SQLite WAL store. |
  9. | **~60% Empirical Token Savings** | Injects only the focused task brief, upstream handoffs, file-matched memories, and progressive-disclosure KP summaries (SHA-256 deduped per turn). |
  10. | **2–3× Empirical Time Savings** | Launch ready tasks in parallel chats with one click while automatic same-folder/worktree edit guards prevent silent overwrites. |
  11. ## Architecture
  12. ![Work Plan System Architecture](assets/architecture.svg)
  13. ## Screenshots
  14. ### Task Tree & Inspector
  15. ![Task Tree and Inspector](assets/screenshots/tasks-inspector.png)
  16. ### Interactive Dependency Graph
  17. ![Interactive Dependency Graph](assets/screenshots/dependency-graph.png)
  18. ### Knowledge & Memory — Memory
  19. ![Knowledge and Memory — Memory View](assets/screenshots/project-memory.png)
  20. ### Knowledge & Memory — Knowledge Pack (OKF & Single Markdown)
  21. ![Knowledge and Memory — Knowledge Pack](assets/screenshots/knowledge-pack.png)
  22. ### Live Active-Edits Guard
  23. ![Live Active-Edits Guard](assets/screenshots/active-edits.png)
  24. ## Features
  25. - **Persistent Multi-Session Task Tree & Dependency DAG**: Hierarchical tasks (up to depth 8, 500 tasks/project) with automatic parent status roll-up, cycle/paradox prevention via dual-node Kahn topological validation, and `Ready` vs. `Waiting` filtering.
  26. - **Structured Task-to-Task Handoffs**: Record concise `handoff_notes` when completing a task; downstream chats receive them automatically via `task_start` and SHA-deduped `PreInvocation` turn briefs.
  27. - **Automatic Live-Edit Guard**: Zero-ceremony `PreToolUse` + `PostToolUse` + `Stop` lifecycle hooks prevent silent same-folder overwrites (`force_ask`) across parallel Antigravity chats and warn on shared lockfiles/schemas across Git worktrees (`ask`), clearing locks the instant a turn finishes.
  28. - **Project-Scoped Working Notes**: Store `decision`, `gotcha`, `spec`, and `note` entries alongside the project; pin critical invariants (`pinned: true`) into turn briefs.
  29. - **Knowledge & Memory (`Knowledge & Memory` tab: Memory + Knowledge Pack)**: Combines durable, categorized cross-session **Memory** cards with a **Knowledge Pack (KP)** setting supporting both **OKF (Open Knowledge Format)** bundles (`index.md` + frontmatter concept files) and **single Markdown files** (`.md`), with automatic `[WORK PLAN]` turn-brief injection and 1-click import/export.
  30. - **Interactive Dual-Mode Aux Pane UI (`sidecars/work_plan/` + `ui://work-plan/app.html`)**: Ships both an **Antigravity Sidecar Aux Pane** (`sidecars/work_plan/sidecar.json` → `SIDECAR_UI_ENTRYPOINT_AUX_PANE`) for zero-flag out-of-the-box side pane support and a single-file **SEP-1865 MCP App** (`ui://work-plan/app.html`) sharing the same local SQLite WAL store. Features a responsive master-detail Task Tree + Inspector, interactive left-to-right SVG Dependency Graph with hover tooltips, Notes manager, Knowledge & Memory tab, Active Edits tab, built-in **Light / Dark theme toggle**, and one-click **Run in New Chat** / **Run Next Ready**.
  31. ## Knowledge & Memory
  32. The **Knowledge & Memory** tab includes a **`Memory` | `Knowledge Pack`** sub-switch and a persistent Knowledge Pack status bar:
  33. - **Memory**: Store durable, categorized project knowledge (`architecture`, `convention`, `command`, `constraint`, `pitfall`, `context`, `fact`) with idempotent `key` upserts, `always` / file-matched `on_demand` / `disabled` injection modes, confidence tracking (`confirmed`, `inferred`, `stale`), 1-click Markdown export, and agent repo scanning.
  34. - **Knowledge Pack (KP)**: Link a portable, git-native knowledge source on disk via **Browse Folder…** or **Browse .md…**:
  35. - **OKF (Open Knowledge Format) Bundle**: Point to an OKF directory or its root `index.md` (with `okf_version` frontmatter and Markdown links to concept `.md` files carrying YAML frontmatter `type`, `title`, `description`, `resource`, `tags`, `files`).
  36. - **Single Markdown File**: Point to any standalone `.md` file (e.g., `KNOWLEDGE.md`, `AGENTS.md`, `ARCHITECTURE.md`) to parse its headings and sections.
  37. - **Auto-Injection & 1-Click Sync**: Active KPs automatically inject progressive-disclosure summaries (prioritizing concepts/sections matching the bound task's files) into `[WORK PLAN]` turn briefs. Use **⬇ Import KP to Memory** (or per-card **+ To Memory**) to pull items into Memory, or **⬆ Export Memory as OKF** / **⬆ Export Memory as .md** to write your Memory cards out to disk as a standards-compliant OKF v0.2 bundle (`index.md`, `<category>/<slug>.md`, `log.md`) or a single Markdown file.
  38. ## Before vs. After (Why ~60% Token Savings & 2–3× Speed)
  39. Managing a large codebase across multiple AI coding agent chats usually breaks down because every new conversation starts cold:
  40. | Workflow Pain Point | Without Work Plan | With Work Plan |
  41. | :--- | :--- | :--- |
  42. | **Starting a new chat on a large codebase** | Re-paste architecture docs, re-read 5–10 files, and re-explain project conventions every session. | SHA-256-deduped `[WORK PLAN]` brief injects only the bound task, upstream `handoff_notes`, file-matched memories, and progressive-disclosure OKF / Markdown Knowledge Pack summaries. |
  43. | **Multi-day task tracking & dependencies** | Lost in long chat scrollback or stale TODO lists; hard to tell what is blocked vs. ready next. | Persistent SQLite task tree + DAG (`Ready` / `Waiting` badges, interactive SVG graph, automatic parent roll-up). |
  44. | **Running parallel AI coding sessions** | Concurrent chats silently overwrite the same files or clash on `package.json` / schemas across worktrees. | Automatic `PreToolUse` / `PostToolUse` / `Stop` live-edit guards catch same-folder (`force_ask`) and cross-worktree (`ask`) collisions in real time, letting you safely run 2–3 tasks in parallel. |
  45. ## Installation (Antigravity)
  46. Clone this repository directly into Antigravity's global plugins folder (no `npm install` or build step required for end users because `ui/app.html` is pre-bundled):
  47. ```bash
  48. git clone https://github.com/minyaozhu/work-plan.git ~/.gemini/config/plugins/work-plan
  49. ```
  50. Once installed:
  51. - Open **Work Plan** from the conversation side pane **`+` menu**, or ask the agent `"Open Work Plan"` to receive a one-click `[Work Plan](sidecar://work-plan/work_plan/)` pill.
  52. - If the plugin was already loaded before updating, toggle **work-plan** off and back on in Customizations (or restart Antigravity) to reload the aux pane.
  53. ### Try It in 10 Seconds (Examples & Local Browser Preview)
  54. This repository ships ready-to-use samples in [`examples/`](examples/):
  55. - [`examples/PLAN.md`](examples/PLAN.md) — seed a multi-phase project immediately via **+ New Project → Markdown plan**.
  56. - [`examples/okf-knowledge-pack/`](examples/okf-knowledge-pack/) — link a standards-compliant **OKF v0.2** bundle in **Knowledge & Memory → Knowledge Pack**.
  57. - Want to preview the UI in any browser without Antigravity? Run:
  58. ```bash
  59. npm run start:sidecar
  60. # open http://127.0.0.1:8765
  61. ```
  62. ## Requirements
  63. - **Node.js `>= 22.5`** (for built-in `node:sqlite` WAL storage), or Antigravity's bundled `agy-node` fallback (`bin/run.mjs` detects and re-execs automatically).
  64. - Optional: `git` (for canonical repo/worktree normalization and branch metadata) and `gh` CLI (for seeding from GitHub issue URLs).
  65. ## MCP Tools
  66. - **Agent tools**: `project_list`, `project_create`, `project_get`, `task_plan`, `task_start`, `task_update`, `note_save`, `note_list`, `memory_save`, `memory_list`, `memory_delete`
  67. - **UI entrypoints**: `open_work_plan` (`aux_pane` and `global` MCP App views) + `sidecars/work_plan/` (`SIDECAR_UI_ENTRYPOINT_AUX_PANE` at `/`)
  68. - **App-only UI tools** (`visibility: ["app"]`): `ui_get_state`, `ui_select_project`, `ui_bind_conversation`, `ui_create_project`, `ui_update_project`, `ui_archive_project`, `ui_delete_project`, `ui_create_task`, `ui_update_task`, `ui_move_task`, `ui_delete_task`, `ui_set_dep`, `ui_save_note`, `ui_delete_note`, `ui_save_memory`, `ui_delete_memory`, `ui_clear_active_edit`, `ui_browse_dir`
  69. ## Lifecycle Hooks (`hooks.json`)
  70. - `PreToolUse` (`pre-edit`): Fast-exits outside workspace / `os.tmpdir()` / `~/.gemini/`; checks active sibling edits (`force_ask` on same-folder collision, `ask` on cross-worktree shared manifests/schemas).
  71. - `PostToolUse` (`post-edit`, `post-mcp`, `post-command`): Records approved edit locks, binds conversations to tasks after `task_start`/`project_create`, and opportunistically records `branch_name` / `pr_url`.
  72. - `PreInvocation` (`pre-invocation`): Injects SHA-256-deduped `[WORK PLAN]` brief (<40 ms p95).
  73. - `Stop` (`stop`): Immediately clears `ActiveEdits` locks held by the finished conversation.
  74. ## Development & Verification
  75. ```bash
  76. npm install # installs devDependencies only (esbuild + @modelcontextprotocol/ext-apps)
  77. npm run build:ui # bundles ui/src/* -> self-contained ui/app.html
  78. npm run start:sidecar # optional standalone preview at http://127.0.0.1:8765
  79. npm test # runs core, MCP/hooks E2E, sidecar, and UI test suites
  80. ```
  81. ## License
  82. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.