venhdev/zenforge

plan-dossier

Coordinate living plans, phase execution, technical contracts, and targeted delta amendments via ZenForge MCP tracking plane with offline scratch fallback.

查看源码

使用方法

  1. 复制安装命令,在自己的智能体环境安装前先检查源码包。
  2. 从原始文档核对所需工具、凭据和支持的宿主。
  3. 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/venhdev/zenforge --skill plan-dossier

开始前需了解

  • 安装不包含模型订阅、API 额度或访问文件的权限。
  • 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
仓库原始内容

按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。

plan-dossier — Living Plan & Targeted Delta Custodian

Coordinates living software execution plans, technical contracts, and DAG task state machines. Operates natively on top of the zenf-mcp tracking plane (zenf_find, zenf_create, zenf_update, transition_task), falling back to local scratch storage (.agents/scratch/plans/<slug>/) only when the MCP server is unreachable.


Operating Invariants

  1. ZenForge Native Tracking First: The living plan, task DAG, and associated technical specifications live in the zenf tracking plane. If the MCP tracking plane is unavailable or offline, persist artifacts to .agents/scratch/plans/<slug>/.
  2. Technical Artifacts as Plan Resources: Accompanying technical specifications, API contracts, and architectural decisions are registered as plan-scoped resources (type="resource", scope="PLAN", project_slug="<project_slug>", scope_ref="<plan_slug>"). project_slug is mandatory for every non-global scope. The daemon automatically injects their briefs into ContextPacket.linked_resources for every task in the plan.
  3. Plan Version Governance: Plans carry an integer version (starting at 1). Every re-ingest or update automatically advances the plan version (v{version}). Tasks and documentation reference the active plan version.
  4. Targeted Delta Amendment: When requirements change, scope expands, or implementation drifts from the agreed plan:
  • Inspect the current state using zenf_find before mutating.
  • Never wipe or blindly recreate the graph.
  • Patch modified tasks via zenf_update(type="task", items=[...]).
  • Ingest newly added vertical slices via zenf_create(type="task", items=[...]).
  • Terminate obsolete tasks via transition_task(action="CANCEL_TASK") or zenf_delete.
  • Update plan technical documentation via zenf_update(type="resource", items=[...]).
  1. Human Alignment Gate on Ingest: Stage the proposed plan, task breakdown, and technical documents for affirmative caller confirmation before submitting to the tracking plane.
  2. Evidence-Backed Verification: Tasks and phases transition to terminal completion strictly when supported by concrete evidence (clean test execution with exit code 0 and git commit SHA).
  3. Drift Breaker: Halt implementation immediately upon encountering architectural divergence. Transition the task to review via transition_task(action="REQUEST_REVIEW") so the caller or orchestrator can steer before applying delta amendments.

Operations & Lifecycle

1. Ingest Living Plan (init)

When initializing an initiative:

  1. Define the Plan: Name, slug, owning project, and initial version.
  2. Draft Technical Documents: Architectural seams, API contracts, or verification specs.
  3. Draft Task DAG: Decompose vertical slices with clear dependencies, priority, risk, target files, acceptance criteria, and verification commands.
  4. Register in ZenForge:
  • Register plan and initial tasks atomically:
json
     zenf_create(type="plan", items=[{
       "slug": "<slug>",
       "project_slug": "<project_slug>",
       "title": "<Plan Title>",
       "tasks": [...]
     }])
  • Register accompanying technical documentation:
json
     zenf_create(type="resource", items=[{
       "project_slug": "<project_slug>",
       "key": "TECH_SPEC",
       "slug": "<slug>-spec",
       "type": "SPEC",
       "scope": "PLAN",
       "scope_ref": "<slug>",
       "title": "Technical Specification",
       "content": "<markdown content>"
     }])
  1. Offline Fallback: If MCP is unreachable, write the plan dashboard to .agents/scratch/plans/<slug>/README.md alongside 01-contracts.md and 02-seam-strategy.md.

2. Targeted Delta Amendment (amend)

When the caller introduces modifications, design changes, or shifts from the original roadmap:

  1. Find Current Graph:

zenf_find(type="task", filter={"plan_slug": "<slug>"}) and zenf_find(type="plan", ids=["<slug>"])

  1. Assess Lifecycle Status:
  • Do NOT modify tasks already COMPLETED.
  • Preserve in-flight tasks (RUNNING, AWAITING_MERGE) unless the caller explicitly cancels them.
  • agent_slug and auto_run are authoring fields: changing them on a RUNNING task is rejected. Reschedule the task (RESET_TO_READY or CANCEL_TASK) before re-assigning it.
  1. Execute Targeted Delta:
  • Update existing tasks: Call zenf_update(type="task", items=[{"id": "<id>", "title": "...", "target_files": [...]}]).
  • Add new tasks: Call zenf_create(type="task", items=[{...}]) with plan_slug and explicit dependency references.
  • Cancel deprecated tasks: Call transition_task(task_ids=["<obsolete_id>"], action="CANCEL_TASK").
  • Revise Plan Specs: Call zenf_update(type="resource", items=[{"id": "<resource_id>", "content": "..."}]).
  • Bumping the plan version tracks the new revision across the web cockpit and worker context packets.

3. Verification & Completion (verify)

  • Execute verification commands.
  • On exit code 0 and valid git commit SHA, complete the task via transition_task(task_ids=["<task_id>"], action="COMPLETE_TASK").
  • Once all plan tasks are verified, archive or complete the plan:

zenf_update(type="plan", items=[{"slug": "<slug>", "status": "COMPLETED"}]).


Canonical Output Contract

markdown
# Plan Dossier: <Initiative Title> (`<slug>`) · <ACTIVE | COMPLETED | DRIFTED>

**Project**: `<project_slug>` | **Version**: `v<version>` | **Store**: `<ZenForge Native | Scratch Fallback>`
**Technical Docs**: `<TECH_SPEC | API_CONTRACT | none>`

## Task State Matrix

| Task ID | Title | Priority | Status | Dependencies | Target Files / Seam |
| :--- | :--- | :--- | :--- | :--- | :--- |
| <id> | <title> | <P0-P3> | <STATUS> | <deps | '-'> | <files | '-'> |

## Delta Summary
*(Include when amending an existing plan)*
- **Added**: `<N>` tasks
- **Modified**: `<N>` tasks
- **Cancelled**: `<N>` tasks
- **Preserved In-Flight**: `<task_ids>`

Autonomous runner micro-token:

text
PLAN | slug: <slug> | v: <version> | status: <STATUS> | tasks: <completed>/<total>
来自同一仓库

更多 Skills

全部 Skills