plan-convergence

Compares an approved plan's tasks against current repository evidence to classify convergence gaps.

Updated Aug 5, 2026
One-click install
npx skills add https://github.com/ahsanghalib/ai-workflow --skill plan-convergence-ahsanghalib
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: plan-convergence
Source: https://github.com/ahsanghalib/ai-workflow/tree/main/skills/plan-convergence
Command: npx skills add https://github.com/ahsanghalib/ai-workflow --skill plan-convergence-ahsanghalib

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? During or after implementation, teams lose track of whether the actual code matches the approved plan. This Skill performs a read-only reconciliation between an approved plan, its tasks, and the current repository state, so drift, missing work, and unplanned changes are surfaced with evidence instead of guesswork. ## Core Features & Use Cases - Task-to-evidence tracing: Maps every plan task to concrete evidence in code, tests, configuration, or documentation, classified as complete, partial, missing, stale, blocked, or unplanned. - Drift and gap detection: Identifies stale tasks, unplanned changes, missing validation, and test-first violations without editing plans or source code. - Structured convergence report: Produces a Markdown report with an evidence table, validation status, unplanned changes, and required approvals. - Use Case: After a sprint of implementation, ask the assistant to check the approved plan against the current diff and receive a per-task convergence verdict with cited file and line evidence. ## Quick Start Ask the assistant to compare the approved plan at docs/plans/checkout-redesign.md with the current repository state and report which tasks are complete, partial, or missing.

Frequently Asked Questions about plan-convergence

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check if implementation matches an approved plan?▼

Provide the exact plan path and ask for a convergence check. The workflow reads the plan, its tasks, and referenced design artifacts, then traces each task to evidence in code, tests, and validation output, classifying each as complete, partial, missing, stale, blocked, or unplanned.

How to detect unplanned changes in a repository diff?▼

The comparison workflow inspects git status and the current diff, then flags any changes that fall outside the selected plan's scope as unplanned. These are listed separately in the report so they are not counted as plan completion.

Does plan convergence checking modify my plans or code?▼

No. The workflow is strictly read-only: it never edits plans, changes task status, commits, pushes, or modifies source code. It only reports findings and proposes advisory next actions that a human or the project-init workflow must authorize.

What happens if the plan is not marked Approved?▼

If the plan's status is not Approved, convergence tracking is not authorized. The workflow reports that limitation and stops after the available read-only comparison rather than inferring approval.

When should I not use a convergence report as a sign-off?▼

A clean convergence report is not a code review approval or production readiness signal. It only confirms that planned tasks have current evidence; correctness, security, and release readiness still require separate review and validation workflows.