venhdev/zenforge

plan-dossier

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

Ver código fuente

Cómo usar

  1. Copia el comando y revisa el paquete antes de instalarlo en tu entorno de agente.
  2. Consulta las herramientas, credenciales y entornos necesarios en el documento original.
  3. Describe las entradas y el resultado deseado; contrasta la salida con las fuentes.
npx skills add https://github.com/venhdev/zenforge --skill plan-dossier

Antes de empezar

  • La instalación no incluye suscripción al modelo, cuota API ni permisos sobre tus archivos.
  • Las estrellas e instalaciones reflejan actividad, no una prueba independiente de calidad o seguridad.
Documento original del Skill

Contenido del repositorio de origen con títulos, ejemplos, código, tablas, enlaces e imágenes preservados.

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>
del mismo repositorio

Más Skills

Todos los Skills