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.