j-mauro-r/SAT-Dengue-V2 / .agents/skills/deepworkplan
deepworkplan
VerifiedDeepWorkPlan — turn any repo AI-first and run Deep Work Plans. Routes to create, execute, refine, resume, status, verify, upgrade, and repo-onboarding sub-skills based on intent. Use when the developer wants to plan, execute, manage, or verify structured multi-task work, or make a repository AI-agent-ready.
shared/dwp-paths.md
View on GitHub# dwp-paths.md — The `.dwp/` Output Convention
> Source of truth for **where Deep Work Plan outputs live**. Every DeepWorkPlan
> sub-skill reads this to resolve plan paths.
## The convention
All plans live under a single gitignored repo-root directory, `.dwp/`:
```
.dwp/
└── plans/ ← PLAN_001_{name}/, PLAN_002_{name}/, ... (flat)
```
- New plans live at `.dwp/plans/PLAN_<id>_<name>/`, Lite or Full alike.
`id` is an incrementing decimal number with at least three digits, allocated
by `plan_paths.py`. Old `PLAN_{name}/` folders remain valid and stay in place.
At 1000 the ID expands to four digits; `list` still sorts it numerically.
Never renumber or move an existing plan: its basename is referenced by
manifests, contracts, journals, prompts and evidence.
- To select a plan, use `python3 ../shared/plan_paths.py --plans-dir
<dwp_dir>/plans resolve <selector>`. A selector can be the full folder name,
its numeric ID (`1` or `001`), a unique slug, or `latest`. `latest` means the
highest allocated ID when numbered plans exist; otherwise it uses the most
recently modified legacy folder. Ambiguous slugs require the full name or ID.
`list` shows numbered plans in numeric order and then legacy plans.
- The allocator keeps `.next-plan-id` in `plans/`, so deleting an old plan does
not reuse its number. A crash may leave a gap or an empty folder; neither
silently changes the identity of another plan.
- `create` writes the plan folder directly. There is no separate draft artifact
and no `.dwp/drafts/` directory: the Lite plan **is** the reviewable artifact
(`../spec/LITE_PLANS.md`). Both were removed in 2.4.0. A `.dwp/drafts/` folder
left over from an earlier version is inert — DWP neither reads nor writes it.
- Every artifact a plan produces — analysis outputs, gate logs, generated
reports — lives inside **that plan's own folder**, under
`.dwp/plans/<plan>/analysis_results/`. Temporary or analysis results
**MUST NOT** be written to the repository root or to ad-hoc folders elsewhere
in the repo: the plan folder is the single home for a plan's working
artifacts, so a plan can be inspected, archived, or deleted as one unit.
## Default location & override
- **Default:** `<repo-root>/.dwp/`, where `<repo-root>` is the git toplevel (or
the current directory outside a git work tree). `shared/context.sh` resolves
this and emits it as the `dwp_dir` field.
- **Override:** set the `DWP_DIR` environment variable to an absolute path to
relocate the output directory (e.g. for monorepos that keep outputs elsewhere,
or CI sandboxes). `context.sh` honors `DWP_DIR` when present.
## `.dwp/` is gitignored
`.dwp/` **MUST** be ignored by the repository's `.gitignore`. Plans are
working artifacts, not tracked source. The one tracked file it may hold is
the addon registry `.dwp/config.json` (`../spec/CONFIG.md` §1): the rule
`.dwp/*` + `!.dwp/config.json` keeps everything else ignored (a plain
`.dwp/` rule keeps the registry local). (Orchestrator hubs follow the same rule:
child plans live at `repositories/{repo}/.dwp/plans/<plan>/`, also
gitignored; numbering is local to each managed repository.)
## Workspace persistence and transfer
Because `.dwp/` is gitignored, **a fresh `git clone` carries no plan data**.
That is by design — plans are working state, not source — and it has one
consequence a resuming agent MUST state plainly: a checkout without `.dwp/`
has nothing to resume, and progress is never fabricated from commits alone.
**Same workspace.** The plan folder on disk is the whole recovery surface;
`resume/SKILL.md` Step 2 (assess, reconcile, classify the interruption
boundary) needs nothing else.
**Transfer to a new machine (explicit, manual).** The minimum handoff
manifest — everything a resumed session needs, nothing it can reconstruct:
1. **The complete plan folder** `.dwp/plans/<plan>/`: README, task
files, `PROGRESS.md`, `manifest.json`, `state.json`, and
`analysis_results/` **including every gate log cited by a `log=` evidence
pointer** (a dangling pointer is a conformance finding, not reusable
evidence).
2. **Repository revision(s)** the state cites — `git rev-parse HEAD` per
repository, checked out on arrival.
3. **Required dirty work**: any uncommitted changes the checkpoint names,
re-created or carried over (patch, stash bundle, or copy).
4. **Evidence pointers** to external-action receipts (report ids, PR URLs)
recorded in the task logs — the receipts themselves live in their
services and are investigated there when absent.
If the destination will create further plans in the same sequence, also carry
`.dwp/plans/.next-plan-id`. Transferring a single plan folder is enough to
resume that plan; the counter preserves IDs of plans deleted before transfer.
On arrival: restore the folder at the same relative path, check out the
recorded revision, re-create the dirty work, then run the read-only checker
(`verify/plan_contract.py`) before resuming. **Missing-artifact behavior:**
report what is missing and stop at that boundary — never reconstruct history
from memory or guess at absent evidence.
**No infrastructure.** There is no daemon, no auto-upload, and no automatic
unignoring of `.dwp/`, and none may be implied: preservation is a deliberate
copy (archive the plan folder, or move it with the workspace) performed by a
human or an agent acting on explicit instruction.
## Contrast with the legacy path
`.dwp/` **replaces** the legacy DWP output tree:
| Concept | Legacy path | New path |
|---------|-------------|----------|
| Plans | `.agent_commands/agent_deep_work_plans/results/plans/PLAN_{name}/` | `.dwp/plans/<plan>/` |
The legacy `.agent_commands/agent_deep_work_plans/results/` tree **MUST NOT** be
used by repos onboarded to DeepWorkPlan v2; migration moves any existing plans
into `.dwp/`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |