Verwendung
- Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
- Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
- Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/venhdev/zenforge --skill plan-dossierVor dem Start
- Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
- Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.
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
- ZenForge Native Tracking First: The living plan, task DAG, and associated technical specifications live in the
zenftracking plane. If the MCP tracking plane is unavailable or offline, persist artifacts to.agents/scratch/plans/<slug>/. - 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_slugis mandatory for every non-global scope. The daemon automatically injects their briefs intoContextPacket.linked_resourcesfor every task in the plan. - 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. - Targeted Delta Amendment: When requirements change, scope expands, or implementation drifts from the agreed plan:
- Inspect the current state using
zenf_findbefore 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")orzenf_delete. - Update plan technical documentation via
zenf_update(type="resource", items=[...]).
- Human Alignment Gate on Ingest: Stage the proposed plan, task breakdown, and technical documents for affirmative caller confirmation before submitting to the tracking plane.
- 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).
- 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:
- Define the Plan: Name, slug, owning project, and initial version.
- Draft Technical Documents: Architectural seams, API contracts, or verification specs.
- Draft Task DAG: Decompose vertical slices with clear dependencies, priority, risk, target files, acceptance criteria, and verification commands.
- Register in ZenForge:
- Register plan and initial tasks atomically:
zenf_create(type="plan", items=[{
"slug": "<slug>",
"project_slug": "<project_slug>",
"title": "<Plan Title>",
"tasks": [...]
}])- Register accompanying technical documentation:
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>"
}])- Offline Fallback: If MCP is unreachable, write the plan dashboard to
.agents/scratch/plans/<slug>/README.mdalongside01-contracts.mdand02-seam-strategy.md.
2. Targeted Delta Amendment (amend)
When the caller introduces modifications, design changes, or shifts from the original roadmap:
- Find Current Graph:
zenf_find(type="task", filter={"plan_slug": "<slug>"}) and zenf_find(type="plan", ids=["<slug>"])
- Assess Lifecycle Status:
- Do NOT modify tasks already
COMPLETED. - Preserve in-flight tasks (
RUNNING,AWAITING_MERGE) unless the caller explicitly cancels them. agent_slugandauto_runare authoring fields: changing them on aRUNNINGtask is rejected. Reschedule the task (RESET_TO_READYorCANCEL_TASK) before re-assigning it.
- 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=[{...}])withplan_slugand 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
# 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:
PLAN | slug: <slug> | v: <version> | status: <STATUS> | tasks: <completed>/<total>