project-revision

Restructures drifted work folders into trees of per-task subfolders with plan.md files.

Updated Nov 21, 2025
One-click install
npx skills add https://github.com/alatyshau/duet --skill project-revision-alatyshau
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: project-revision
Source: https://github.com/alatyshau/duet/tree/main/packages/skills/tools/project-revision
Command: npx skills add https://github.com/alatyshau/duet --skill project-revision-alatyshau

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Work folders drift over time: plan.md grows past one screen, checkboxes go stale, completed phases aren't reflected, and orphan files pile up without links. This Skill performs a deep audit and rebuilds the folder as a tree of per-task subfolders, each with its own plan.md, so any node can be understood cold in 30 seconds. ## Core Features & Use Cases - Tree restructuring: Applies the "one task = one folder" rule recursively, with TODO_/WIP_ lifecycle prefixes and date-stamped archive/ folders for closed work. - Source-based reconstruction: Rebuilds plans from primary sources (files, git history, conversation context) rather than reformatting the stale old plan. - Naming and linking conventions: Enforces standard file prefixes (design_, review_, research_, handoff_, notes_, playbook_) and requires every reference in plan.md to carry a line of context, never a bare link. - Use Case: A project folder has a 300-line plan.md mixing done and open work. The Skill diagnoses the drift, proposes a tree of WIP_/TODO_/archive subfolders for approval, then writes a one-screen plan.md at every level. ## Quick Start Ask the agent to run a project revision on the work folder whose plan.md has become bloated and hard to scan.

Frequently Asked Questions about project-revision

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

FAQPage Schema
How do I clean up a bloated project plan.md file?

Run a project revision: rename the old plan to plan_old.md, read all primary sources, then rebuild the folder as a tree of per-task subfolders where each bounded task gets its own folder and one-screen plan.md. The parent plan composes itself from child folder statuses.

How should I organize subtasks in a work folder?

Give every bounded task its own folder with its own plan.md, using TODO_ for queued, WIP_ for active, and archive/YYMMDD_slug for closed work. Keep no more than 7 direct children per level and classify by task, never by file role.

When should a subtask get its own folder versus stay as text in the parent plan?

Create a folder when you can state the task's goal and done-criterion in one sentence each. If the boundary isn't clear yet, keep it as a topic in the parent's plan.md and carve the folder out once the task matures.

Does the project revision process delete obsolete files?

No, the agent never deletes files in work folders under any circumstances. Files that look obsolete are extracted retroactively into archive/YYMMDD_slug folders with a plan.md explaining why the artifact is no longer active; cleanup is left to the user.

What file naming conventions does a revised work folder use?

Files use standard type prefixes: design_, review_, research_, handoff_, notes_, and playbook_, with kebab-case slugs. Date-prefixed names are only legal inside archive/ for closed subtask folders, and every folder contains exactly one unprefixed plan.md.