venhdev/zenforge

plan-dossier

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

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/venhdev/zenforge --skill plan-dossier

Vor 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.
Originales Skill-Dokument

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

  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>
aus demselben Repository

Weitere Skills

Alle Skills