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.
examples/ORCHESTRATOR_TASK_TEMPLATE_execute_child_dwp.md
View on GitHub# Task {N}: Hand Off Execution of Child DWP — {Repository Name}
> **Template for orchestrator plans.** Fill in known placeholders when generating a real task file. Resolve each child plan basename from the parent registry after the child has been allocated; never construct an ID from the feature or repository name.
> [!IMPORTANT]
> **This task is a HAND-OFF, not an execution.** The orchestrator agent **must never** execute a child DWP itself in the same session. It must stop at this task, confirm predecessors are ready, emit a ready-to-use execution prompt for the target repository, and wait for the user (or a separate agent session running inside that repo) to execute the child and confirm completion. Only then may the orchestrator agent continue.
>
> **Rationale:** Child DWPs run inside their own repository with their own agent context, tooling, AGENTS.md rules, validation commands, and git history. Executing them from the orchestrator session silently mixes contexts, violates per-repo conventions, hides work from the target repo's audit trail, and can produce invalid commits. The hand-off model keeps each repo's agent autonomous.
> [!TIP]
> **Parallel execution is often possible and preferred.** Check the execution mode declared in the orchestrator plan's README (§4 Child DWP Plans → Execution Mode):
>
> - **Contract-Parallel** (recommended when children share a frozen design spec): emit a SINGLE combined hand-off block listing all eligible children at once; they can run concurrently in separate agent sessions.
> - **Sequential Runtime-Dependent** (rare; only when child B's code literally imports child A's code at build time): emit one hand-off at a time, wait for DONE, then the next.
> - **Fully Parallel / Distributed** (children are independent): same as Contract-Parallel — combined hand-off.
>
> See GUIDE §13.6 for the mode selection algorithm. Default to the most parallel mode your dependency analysis supports.
## 1. Context
**Plan Type:** Orchestrator — Child DWP Execution HAND-OFF
**Target Repository:** `repositories/{repo_name}/`
**Child Plan to Execute (by another agent):** `{CHILD_PLAN_NAME}`
**Child Plan Location:** `repositories/{repo_name}/.dwp/plans/{CHILD_PLAN_NAME}/`
This task verifies predecessors are ready, emits a hand-off prompt for the target repo's agent, and **stops**. It does not execute the child DWP. When the user confirms the child DWP has been executed (all its tasks `[x]`, `state.json` reporting `completed`, declared artifacts on disk), the orchestrator agent updates the manifest and marks this task complete.
### Orchestrator Context
- **Parent Plan:** {PARENT_PLAN_NAME} (this plan, in Core Hub)
- **Feature:** {overall feature description}
- **This repo's role:** {what this repo contributes — e.g., "CRUD API endpoints for user preferences"}
- **Depends on:** {list child plans that must be executed first, or "None — this is the first child DWP"}
- **Depended on by:** {list child plans that depend on this one's outputs, or "None"}
- **Manifest:** `.dwp/plans/{PARENT_PLAN_NAME}/ORCHESTRATOR_MANIFEST.md`
### Predecessor Outputs Required
{If this child has predecessors, list what outputs must be available before hand-off:}
- **{PREDECESSOR_PLAN_NAME}** (must be `[x] Executed`):
- Declared artifacts: `repositories/{predecessor_repo}/.dwp/plans/{PREDECESSOR_PLAN_NAME}/analysis_results/{declared_artifact}`
- Key outputs needed: {specific data this child needs — e.g., "API endpoint paths, data model definitions, error response formats"}
- {Or "None — this is the first child DWP (no predecessors)"}
## 2. Read Before Starting
1. **Orchestrator Manifest:** Read `ORCHESTRATOR_MANIFEST.md` from the parent plan folder.
- Check "Execution State" — verify all predecessors are `[x] Executed`.
- Check "Completed Output References" — confirm each predecessor's declared artifacts are registered.
2. **Predecessor declared artifacts** (if this child has dependencies): confirm they exist on disk (do NOT read through them line-by-line — the target repo's agent will). Check the files the predecessor actually declared; an Executive Report is optional under DWP 2.3.0 and may legitimately not exist.
3. **Child DWP README** (for the hand-off prompt): `repositories/{repo_name}/.dwp/plans/{CHILD_PLAN_NAME}/README.md`.
## 3. Goal
Emit a ready-to-use hand-off prompt for the target repo's agent to execute `{CHILD_PLAN_NAME}`, then pause. When the user confirms execution is complete, register outputs in the orchestrator manifest and mark this task `[x]`.
**Success conditions:**
- Predecessor readiness verified.
- Hand-off prompt emitted and delivered to the user (or separate agent session).
- Orchestrator agent has **NOT** navigated into `repositories/{repo_name}/` with any write intent, has **NOT** run validations, has **NOT** edited or committed anything inside the target repo.
- After user confirmation of execution, manifest and orchestrator README are updated with the executed child's outputs.
## 4. Instructions
> **Before starting:** Re-read the parent plan README section 1 (Goal) to ensure this hand-off aligns with the overall objective.
### Step 1: Verify Hand-Off Readiness (CRITICAL — mode-dependent)
Determine execution mode from the orchestrator plan README (§4). Then apply the appropriate gate (see GUIDE §13.10):
**Contract-Parallel or Fully Parallel:** lenient gate.
- [ ] Design-doc contracts exist on disk (envelope spec / API contract / prompt architecture / etc.).
- [ ] Integration checkpoint PROCEED documented.
- [ ] Sibling child DWP folders exist (each `test -d <path>`).
**Sequential Runtime-Dependent:** strict gate — for this mode only.
- [ ] Predecessor marked `[x] Executed` in manifest Execution State.
- [ ] Every declared predecessor artifact exists at its referenced path.
- [ ] "Completed Output References" has the predecessor entry.
If any required check for the applicable mode fails — STOP:
```
BLOCKED: Cannot hand off {CHILD_PLAN_NAME}
- Mode: {Contract-Parallel | Fully Parallel | Sequential Runtime-Dependent}
- Missing: {what failed}
- Action: {fix the missing piece; do NOT execute the child inline to "unblock"}
```
Log the blocker in §9. Do NOT mark this task complete. Stop and wait.
> **Note:** if multiple hand-off tasks in the same plan can fire together (Contract-Parallel / Fully Parallel), prefer emitting a single combined hand-off block (see the TIP callout at the top of this template).
### Step 2: Emit the Hand-Off Prompt to the User
Present the following ready-to-use execution prompt to the user. The user (or a separate agent session running inside `repositories/{repo_name}/`) will paste it into that repo's agent to execute the child DWP.
**Hand-off prompt (copy verbatim into the user-facing message):**
~~~
# Hand-off — Execute child DWP inside repositories/{repo_name}/
Open a new agent session with its working directory set to `repositories/{repo_name}/`.
(For CLI tools: open a new shell/agent in that folder so the agent's context is the target repo.)
Paste this prompt into that agent:
Execute the plan at: .dwp/plans/{CHILD_PLAN_NAME}/README.md
Important:
- Follow THIS repository's AGENTS.md conventions (validation, commit format, test patterns).
- {Predecessor context note — e.g., "Before Task 1, read: repositories/{predecessor_repo}/.dwp/plans/{PREDECESSOR_PLAN_NAME}/analysis_results/{declared_artifact}"}
- {Any audit-only / behavior notes from the child DWP README}
- Do NOT send Dailybot interim reports if the parent orchestrator will send a single milestone at its final task.
When the child DWP is complete:
1. All its tasks are `[x]` in its README, ending with the Final Review.
2. `state.json` reads `status: completed`, and every declared output artifact
exists in `analysis_results/`.
3. Reply to the orchestrator session with:
"DONE: {CHILD_PLAN_NAME} executed. Declared artifacts at <paths>. Key outputs: <1–3 bullets>."
~~~
### Step 3: Pause and wait for user confirmation
**The orchestrator agent stops here.** Do not proceed until the user confirms the child DWP has been executed.
While waiting, the orchestrator agent:
- MUST NOT `cd` into `repositories/{repo_name}/` with any write or execution intent.
- MUST NOT run the child DWP's tasks inline.
- MUST NOT modify files inside the target repository.
- MAY answer questions about the hand-off prompt or the child DWP README.
- MAY re-emit the hand-off prompt if the user lost it.
### Step 4: Verify child DWP completion (after user confirms)
After the user replies "DONE: …" (or equivalent), verify from Core Hub:
```bash
set -e
CHILD=repositories/{repo_name}/.dwp/plans/{CHILD_PLAN_NAME}
if [ -f "$CHILD/state.json" ]; then
# v2+ plans: the TOP-LEVEL status and EVERY task must be completed. A nested
# task-level "completed" never satisfies this check on its own.
python3 - "$CHILD/state.json" <<'PYCHILD'
import json, sys
state = json.load(open(sys.argv[1]))
assert state.get('status') == 'completed', 'child plan is not complete'
assert state.get('tasks') and all(t.get('status') == 'completed' for t in state['tasks']), 'child tasks are incomplete'
print('PASS: child plan status and all tasks completed')
PYCHILD
else
# Legacy child plan (authored before the v2 state layer). state.json is the
# authority only when it exists; fall back to the child's RECORDED lifecycle
# and never re-derive completion from the orchestrator's own reading.
grep -q -- '- \[ \]' "$CHILD/README.md" && { echo "FAIL: legacy child still has open tasks" >&2; exit 1; }
grep -q -- '- \[x\]' "$CHILD/README.md" && echo "PASS: legacy child tasks all executed (recorded)" \
|| { echo "FAIL: no executed tasks recorded in child README" >&2; exit 1; }
fi
# Run the child's own conformance check from Core Hub — read-only, no cd into
# the child. env -u DWP_DIR stops a hub DWP_DIR override from leaking into the
# child's plan-root resolution. A child without an installed checker keeps
# ownership of its own gates (its session ran them).
CHILD_CHECKER=repositories/{repo_name}/.agents/skills/deepworkplan/verify/conformance.sh
if [ -f "$CHILD_CHECKER" ]; then
if env -u DWP_DIR bash "$CHILD_CHECKER" --plan {CHILD_PLAN_NAME} repositories/{repo_name}; then
echo "PASS: child conformance green"
else
echo "FAIL: child conformance not green (1 = findings, 2 = UNVERIFIED) — ask the child session to resolve before marking Executed" >&2
exit 1
fi
fi
# and each artifact this child declared under "Expected Outputs":
test -f "$CHILD/analysis_results/{declared_artifact}" \
&& echo "PASS: declared artifact present" || { echo "FAIL: declared artifact missing" >&2; exit 1; }
```
If the plan is not complete or a declared artifact is missing, tell the user and
do NOT mark this task complete. Do **not** gate on an Executive Report: under DWP
2.3.0 it is offered once and generated only on request, so its absence is normal.
The conformance line runs the child's own checker against the child plan
(`--plan … <child-dir>`) — read-only, from Core Hub, never a `cd` with execution
intent. Exit 0 confirms the child's evidence shape; exit 1 (findings) or exit 2
(UNVERIFIED) means the child is not verifiably done: ask its session to resolve
that before this task is marked `[x]`. A child repo without the checker
installed keeps ownership of its own gates — its session ran them.
**Legacy children (no `state.json`).** Plans authored before the v2 state layer
have no state file; the block falls back to their recorded lifecycle — every
README task `[x]` plus the declared artifacts on disk. The fallback only
recognizes recorded lifecycle, it never re-derives completion, and `state.json`
stays authoritative whenever it exists.
### Step 5: Register outputs in the orchestrator manifest
Update `ORCHESTRATOR_MANIFEST.md`:
1. §5 Execution State — mark this child `[x] Executed`:
```
| {N} | {CHILD_PLAN_NAME} | [x] | [x] | Available | {short key-outputs list} |
```
2. §5 Completed Output References — add an entry:
```markdown
#### Child #{N}: {CHILD_PLAN_NAME} ({repo_name})
- **Declared artifacts:** `repositories/{repo_name}/.dwp/plans/{CHILD_PLAN_NAME}/analysis_results/{declared_artifact}`
- **Completion evidence:** that plan's `state.json` (`status: completed`) and its Final Review task log.
- **Key outputs:** (from the user's DONE reply + a quick read of the declared artifacts)
- {bullet}
- {bullet}
- **Summary:** {One-line summary of what was produced}
```
3. Orchestrator README — Child DWP Plans table: mark this child `[x] Created / [x] Executed`.
### Step 6: Close this task in Core Hub
- Mark this task `[x]` in the orchestrator README.
- Update `PROGRESS.md` with a 1–2 sentence summary.
- Fill §9 Completion & Log below.
- Commit in Core Hub (tracking files only): `docs(technical): hand-off + register outputs for {repo_name} child DWP - Task {N} of {PARENT_PLAN_NAME}`.
## 5. Acceptance Criteria
- [ ] Hand-off readiness verified (predecessors `[x] Executed`, their declared artifacts on disk).
- [ ] Hand-off prompt emitted to the user.
- [ ] Orchestrator agent did NOT execute the child DWP inline (no `cd` with write intent, no runs, no edits in target repo).
- [ ] User confirmed child DWP execution; the plan reports `completed` and its declared artifacts are on disk.
- [ ] Orchestrator manifest updated (Execution State + Output References).
- [ ] Orchestrator README Child DWP Plans table updated (`[x] Executed`).
- [ ] PROGRESS.md updated, task marked `[x]`, commit made in Core Hub.
## 6. Outputs
- **Emitted:** Ready-to-use execution prompt for the target repo's agent.
- **Verified (after user confirmation):** the child plan's `state.json` reports `completed`, and each declared artifact exists under `repositories/{repo_name}/.dwp/plans/{CHILD_PLAN_NAME}/analysis_results/`.
- **Updated (in Core Hub):** Parent plan ORCHESTRATOR_MANIFEST.md + README.
## 7. Validation
```bash
# Run in Core Hub after the user replies DONE:
set -e
CHILD=repositories/{repo_name}/.dwp/plans/{CHILD_PLAN_NAME}
if [ -f "$CHILD/state.json" ]; then
# Same authoritative check as Step 4: TOP-LEVEL status + every task. A bare
# grep for '"status": "completed"' would also match nested task-level status.
python3 - "$CHILD/state.json" <<'PYCHILD' && echo "PASS: child plan completed" || { echo "FAIL" >&2; exit 1; }
import json, sys
state = json.load(open(sys.argv[1]))
assert state.get('status') == 'completed', 'child plan is not complete'
assert state.get('tasks') and all(t.get('status') == 'completed' for t in state['tasks']), 'child tasks are incomplete'
PYCHILD
else
grep -q -- '- \[ \]' "$CHILD/README.md" && { echo "FAIL: legacy child still has open tasks" >&2; exit 1; }
grep -q -- '- \[x\]' "$CHILD/README.md" && echo "PASS: legacy child tasks executed" || { echo "FAIL" >&2; exit 1; }
fi
test -f "$CHILD/analysis_results/{declared_artifact}" && echo "PASS: declared artifact present" || { echo "FAIL" >&2; exit 1; }
# Verify manifest updated
grep -q "{CHILD_PLAN_NAME}" .dwp/plans/{PARENT_PLAN_NAME}/ORCHESTRATOR_MANIFEST.md && echo "PASS: Manifest has child entry" || { echo "FAIL" >&2; exit 1; }
# Verify orchestrator README marked Executed
grep -E "\[x\].*{CHILD_PLAN_NAME}|{CHILD_PLAN_NAME}.*\[x\] Executed" .dwp/plans/{PARENT_PLAN_NAME}/README.md >/dev/null && echo "PASS: README marks Executed" || echo "CHECK MANUALLY"
```
## 8. Execution Checklist
- [ ] 1. Read this task file fully.
- [ ] 2. Read orchestrator manifest — verify predecessors are `[x] Executed`.
- [ ] 3. Confirm each predecessor's declared artifacts exist on disk.
- [ ] 4. Emit the hand-off prompt to the user (Step 2).
- [ ] 5. **Pause.** Do not navigate into the target repo. Do not run the child DWP. Do not edit target-repo files.
- [ ] 6. Wait for the user's DONE confirmation.
- [ ] 7. Verify the child plan reports `completed` and its declared artifacts exist on disk.
- [ ] 8. Update ORCHESTRATOR_MANIFEST.md (Execution State + Output References).
- [ ] 9. Update orchestrator README Child DWP Plans table.
- [ ] 10. Update PROGRESS.md with summary.
- [ ] 11. Mark this task `[x]` in the plan README.
- [ ] 12. Commit in Core Hub: `git commit -m "docs(technical): hand-off + register outputs for {repo_name} - Task {N} of {PARENT_PLAN_NAME}"`.
- [ ] 13. Update the Log section below.
## 9. Completion & Log (filled by the agent)
- **Status:** (hand-off emitted / blocked waiting / confirmed complete / failed)
- **Timestamp of hand-off:**
- **Timestamp of user confirmation:**
- **Predecessor readiness:** (all `[x]` / blocked on Child #M)
- **User-reported DONE summary:** {one-line summary user provided}
- **Child completion verified on disk:** (yes/no + `state.json` status + declared artifact paths)
- **Key outputs registered in manifest:** {list}
- **Did the orchestrator agent execute any child DWP task inline?:** **Must be NO.** (If yes — violation; document and raise to the user.)
- **Notes / follow-ups:**
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 |