Skip to content

j-mauro-r/SAT-Dengue-V2 / .agents/skills/deepworkplan

deepworkplan

Verified

DeepWorkPlan — 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.

FileKindSize
SKILL.mdskill md12.0 KB
TRUST.mdmarkdown16.1 KB
addons/README.mdmarkdown11.7 KB
addons/machine-installs.mdmarkdown2.9 KB
examples/CREATE_PLAN.mdmarkdown6.9 KB
examples/ORCHESTRATOR_TASK_TEMPLATE_create_child_dwp.mdmarkdown15.0 KB
examples/ORCHESTRATOR_TASK_TEMPLATE_execute_child_dwp.mdmarkdown16.7 KB
examples/ORCHESTRATOR_TASK_TEMPLATE_integration_checkpoint.mdmarkdown9.0 KB
examples/PROMPTS_TEMPLATE.mdmarkdown4.0 KB
examples/TEAM_AGENTS_TASK_TEMPLATE.mdmarkdown5.1 KB
examples/V6_PLAN_EXAMPLE.mdmarkdown5.5 KB
guide/GUIDE.mdmarkdown8.0 KB
guide/authoring.mdmarkdown28.5 KB
guide/execution.mdmarkdown21.0 KB
guide/large-repo-onboarding.mdmarkdown3.3 KB
guide/orchestration-at-scale.mdmarkdown11.4 KB
guide/orchestrator.mdmarkdown37.9 KB
guide/prompts.mdmarkdown10.1 KB
guide/skills-integration.mdmarkdown6.5 KB
guide/structure.mdmarkdown6.2 KB
guide/swarm.mdmarkdown21.2 KB
guide/team-agents.mdmarkdown12.3 KB
shared/adaptation.mdmarkdown2.7 KB
shared/addon_sync.pyscript17.7 KB
shared/benchmark.pyscript97.6 KB
shared/config.pyscript41.5 KB
shared/context.shscript4.2 KB
shared/context_manifest.pyscript40.8 KB
shared/contract_v6.pyscript82.7 KB
shared/delegators.pyscript3.0 KB
shared/dwp-paths.mdmarkdown5.8 KB
shared/finalize_plan.pyscript7.2 KB
shared/install-verification.mdmarkdown1.8 KB
shared/ledger.pyscript141.5 KB
shared/migrate_v6.pyscript46.5 KB
shared/outcomes.pyscript27.2 KB
shared/plan_paths.pyscript4.8 KB
shared/resources.pyscript49.0 KB
shared/scheduler.pyscript41.6 KB
shared/state_contract.pyscript9.8 KB
shared/swarm.pyscript27.3 KB
shared/troubleshooting.mdmarkdown7.4 KB
shared/update-state.pyscript12.5 KB
shared/views.pyscript21.0 KB
shared/working-principles.mdmarkdown7.1 KB
spec/ADDONS.mdmarkdown27.4 KB
spec/AGENT_PROTOCOL.mdmarkdown28.0 KB
spec/ARCHETYPES.mdmarkdown10.6 KB
spec/BENCHMARK.mdmarkdown20.3 KB
spec/CONFIG.mdmarkdown8.7 KB
spec/DOCUMENTATION_STANDARD.mdmarkdown40.7 KB
spec/DWP_SPECIFICATION.mdmarkdown65.1 KB
spec/LITE_PLANS.mdmarkdown4.0 KB
spec/PLAN_STATE.mdmarkdown34.9 KB
spec/README.mdmarkdown11.5 KB
spec/V6_CONTEXT.mdmarkdown6.4 KB
spec/V6_CONTRACT.mdmarkdown12.3 KB
spec/V6_LIFECYCLE.mdmarkdown13.5 KB
spec/V6_RESOURCES.mdmarkdown4.7 KB
spec/V7_ABILITIES.mdmarkdown4.9 KB
spec/V7_CONTRACT.mdmarkdown6.4 KB
spec/V7_ROADMAP.mdmarkdown4.6 KB
spec/schema/addon-descriptor-v1.schema.jsonconfig5.5 KB
spec/schema/benchmark-record.schema.jsonconfig14.0 KB
spec/schema/context-manifest-v6.schema.jsonconfig12.5 KB
spec/schema/dwp-config-v1.schema.jsonconfig3.5 KB
spec/schema/dwp-handoff-v1.schema.jsonconfig3.0 KB
spec/schema/journal-event-v6.schema.jsonconfig22.3 KB
spec/schema/journal-event-v7.schema.jsonconfig24.9 KB
spec/schema/learnings-record.schema.jsonconfig6.0 KB
spec/schema/plan-contract-v6.schema.jsonconfig16.4 KB
spec/schema/plan-contract-v7.schema.jsonconfig16.6 KB
spec/schema/plan-manifest-v2.schema.jsonconfig1.0 KB
spec/schema/plan-manifest-v5.schema.jsonconfig1.3 KB
spec/schema/plan-manifest-v6.schema.jsonconfig2.0 KB
spec/schema/plan-manifest-v7.schema.jsonconfig1.7 KB
spec/schema/plan-manifest.schema.jsonconfig1.8 KB
spec/schema/plan-snapshot-v6.schema.jsonconfig7.8 KB
spec/schema/plan-state-v2.schema.jsonconfig6.4 KB
spec/schema/plan-state-v5.schema.jsonconfig6.7 KB
spec/schema/plan-state.schema.jsonconfig3.7 KB

spec/V6_LIFECYCLE.md

View on GitHub
# V6 Lifecycle — Generation Detection, Materialization, Flow Wiring

> **Status: v6 line.** This document defines how the v6 execution contract
> (`V6_CONTRACT.md`), context selection (`V6_CONTEXT.md`) and resource
> controls (`V6_RESOURCES.md`) are wired into the pack's flows: how a
> plan's generation is detected, how a v6 plan is created and
> materialized, what the execute loop does, which surfaces stay
> read-only, and how v6 and v5 coexist. The design source is
> `docs/evaluations/v6/ARCHITECTURE_RFC.md` (decisions A2–A3, A9, A12,
> D2-10b, D3-1–D3-2, D3-6, §9–§10). It binds **v6 new plans only**; the
> v5 standard is untouched.

All documents in this spec use RFC-2119 language. Where this document and
a shipped helper disagree, that drift is a defect in one of them, never a
feature.

## 1. Generation detection (normative)

A plan folder under `.dwp/plans/` is **v6** if and only if it carries a
`manifest.json` whose `contract` pointer resolves, a `contract.json`, or a
`contracts/` revision chain. Detection MUST be by these artifacts, never
by skill version alone: an installed v6 pack can hold v5 plans, and a v5
pack can encounter a v6 plan folder copied in.

New plan folders use the forward-only `PLAN_<id>_<slug>` naming policy in
`shared/dwp-paths.md`. That policy applies at creation and does not classify a
plan's generation. Existing unnumbered v5 or v6 folders remain valid in their
original locations; no lifecycle flow renames them.

- The v6 flows (`create/v6.md`, `execute/v6.md`) MUST route on this
  detection and nothing else.
- A v1/v2/v5 plan MUST keep its recorded lifecycle (RFC §9.2); no flow
  MAY migrate it to v6 silently. Migration, when it exists at all, is an
  explicit user-initiated act with its own recorded authority.
- A runner that does not implement the v6 loop MUST report a detected v6
  plan as unsupported and stop (D2-10b) — approximating the contract with
  v5 bookkeeping is the failure this rule exists to prevent.

**Contract generations of the record layer (7.0.0 line).** A plan detected
as v6 above carries one of two contract generations, named by the
contract's `schema` URL and mirrored by its manifest and every journal
event:

| Generation | Contract | Journal events | Manifest | Adds |
|---|---|---|---|---|
| v6 | `plan-contract/v6` | `journal-event/v6` | `plan-manifest/v6` | — |
| v7 | `plan-contract/v7` | `journal-event/v7` | `plan-manifest/v7` | `tasks[].parallel_safe`, the `delegation` event ([`V7_CONTRACT.md`](V7_CONTRACT.md)) |

Both generations run through the same loops and helpers and project into
the same `plan-snapshot/v6` shape. A plan never changes generation: a v6
plan keeps v6 forever, and a journal mixing generations is refused.

## 2. Activation (normative)

With the current 7.x pack, new plans use the v7 contract generation by
default (§1 table); an explicit `v6` request materializes a v6 contract. A
developer's explicit v6 request also selects this flow when an older pack
provides it.
A 5.x pack without that request follows its recorded v5 flow. Existing
plans are selected by their artifacts (§1), regardless of installed pack
version; no existing plan changes generation during selection.

## 3. Materialization order (normative — A12)

A v6 plan is materialized by `shared/ledger.py materialize` in exactly
this order — **manifest → contract → approval** — each step idempotent
and resumable:

1. **`manifest.json`** — the identity manifest with the contract pointer
   (`schema/plan-manifest/v6.json`), written FIRST so a plan's v6-ness is
   discoverable even if materialization is interrupted before the
   contract lands.
2. **`contract.json`** — the validated, content-addressed contract
   stamped into the plan folder.
3. **`approval` journal event** — the first journal event, citing the
   contract id and the plan-markdown digest (D3-1/D3-2), actor human.

The approval event is the ONLY thing that opens the task-start gate. A
hand-copied contract without it is refused at `start`; a manifest whose
pointer does not match the materializing contract is refused rather than
rewritten. Refusals that MUST hold:

- A folder with an existing non-v6 manifest is never rewritten (§9.2).
- A materialization never rewrites a stamped contract — a different
  contract is a revision (§5).
- A folder with no plan markdown is not approvable and materialization
  refuses it.

The mechanisms (`plan_authorship`, `pre_authorization`) are mode-uniform
(A2–A3): guided and trust plans gate identically; what differs is the
recorded authority, never the checks.

## 4. The execution boundary (normative — A9, D3-6)

Declared invariants are evaluated at execution boundaries — task start,
gate run and completion — through the shipped helpers, never re-implemented
in flow prose:

- Dispatch comes from `shared/scheduler.py ready`; the core is read-only
  and refuses any task whose declared invariants were never evaluated or
  were evaluated only before the current task start.
- `observed` gate evidence is minted ONLY by `shared/ledger.py gate`; an
  appended `gate_run` without a runner binding is refused.
- **Every declared invariant is plan-scoped** (F-03): it holds across the
  whole plan and is evaluated at each boundary — an observation
  `INV-<id>: pass` or `INV-<id>: fail: <reason>`. `complete` refuses (and
  records the refusal) while any invariant's latest evaluation is
  missing, older than the task's start, or a failure. A property that
  only some tasks must hold is an acceptance criterion of those tasks,
  never an invariant.
- Task completion is DERIVED (every `gate_intent` criterion satisfied
  in-window — the same zero-test predicate the scheduler selects by),
  never declared: `complete` refuses (and records the refusal) while any
  criterion lacks accepted evidence, and the snapshot's task status is a
  projection of that derivation.

## 5. Amendment (normative)

A change to a materialized plan's scope, acceptance criteria, permissions
or envelope is a **contract amendment**, not a task edit: author the
revised contract, record it as a new revision under `contracts/` (chain
rules in `V6_CONTRACT.md` §1), obtain a fresh approval citing the new
contract id, and invalidate the evidence of affected criteria (re-run,
never trust prior results). The manifest's pointer is provenance and is
never edited; the live contract is the highest revision under
`contracts/`.

`python3 shared/ledger.py --plan <dir> amend --contract <draft> --authority
<who> --note <reason> --human-note <file>` is that sequence as one guarded,
resumable verb (F-12). The draft is the revised contract (a copy of the
live one, edited; the next `revision` and `parent_contract_id` are
derived); it MUST keep the plan and its generation and pass the draft
checks (`V6_CONTRACT.md` §2). The order is normative: the revision is
staged as `contracts/.contract.rN.json.pending` (invisible to the
loader); the `amendment` event lists the revised criteria in
`evidence_invalidated` — once the amendment is approved, their earlier
gate runs and control pairs never satisfy them again (an amendment that
never reaches approval invalidates nothing); a fresh `approval` cites the new contract id (human actor, with
the authority marker of `V6_CONTRACT.md` §3); only then does an atomic
rename switch the live contract. Re-running the same amendment after an
interruption resumes at the first missing step without duplicate events;
a different draft is refused while one is pending. Task-level markdown edits (wording, notes, task splits
inside granted authority) go through the recorded refine flow unchanged.

## 6. Read-only surfaces (normative)

`status` and `verify` never write for v6 plans. Their v6 reports are
produced by pure commands — `ledger.py inspect`, `scheduler.py ready`,
`resources.py report|routing|hold`, `outcomes.py receipt`,
`contract_v6.py validate-contract|validate-journal` — plus reading the
generated projections and the human markdown. A finding (torn tail,
missing approval, projection disagreement) is reported with its suggested
repair; the repair itself belongs to the mutating flows. Rendering views
(`views.py render`) writes and therefore belongs to execute/refine, not
status.

## 7. Coexistence (normative)

v5 and v6 plans MAY coexist in one `.dwp/plans/`. Each plan runs under
its own generation for its whole life; no flow upgrades, downgrades or
approximates across generations. The pack's version line governs only
which generation NEW plans get (§2) — never what existing plans become.

## 8. v5 migration (normative — one-directional, explicit)

A v5 plan keeps running under the v5 contract forever (§7); the ONLY thing
that turns it into a v6 plan is `shared/migrate_v6.py`, run on purpose
through `refine`. Migration MUST follow this sequence, and each step is
idempotent and recorded in `migration_v5/PHASE.json` so an interruption at
any point recovers by running the command again:

1. **preview** — integrity check (folder/state identity, known statuses,
   well-formed gates) and the full mapping: task *N* → `T-NN-<slug>`,
   criterion `AC-tNN-<slug>`, one per v5 task, prerequisites mirroring the
   v5 sequential order. A completed task whose gates all recorded
   `passes=true`, exit 0 and a **resolving** evidence pointer closes via
   an `imported` criterion; anything weaker — a failed gate, a missing or
   dangling pointer, an in-progress task, no gates — is a **re-evidence
   criterion**: bar `observed`, blocked by default until the gates re-run
   under v6 (D3-5). The preview names the recorded assumptions (gate cwd
   and timeout are not v5 fields; imported records carry the repository
   root and the executor default) and refuses lossy inputs. No v5 byte is
   touched.
2. **backup** — `manifest.json` + `state.json` copied under
   `migration_v5/backup/` with recorded digests. The manifest swap never
   happens before this exists.
3. **contract** — the synthesized contract is deterministic (timestamps
   anchor to the v5 state's `updated_at`, never the wall clock), validates
   under `contract_v6.py`, and takes the conservative posture: scope
   records-only, no capabilities granted, an advisory unmetered envelope —
   substantive work after migration goes through an amendment (§5).
4. **manifest swap** — the v6 pointer manifest replaces the v5 manifest.
   This is the **single sanctioned rewrite of another generation's
   manifest** in the whole system (§3's refusal is what makes this
   exception safe).
5. **journal** — a `pre_authorization` approval citing the v5 source
   digest (the preview + records ARE the recorded pre-authorization,
   D3-2), one fingerprint-less `task_start` per non-pending task (v5 kept
   no fingerprint; control pairs stay honestly unavailable), every v5
   gate record imported through `Writer.migrated_gate` — `imported` with
   the source digest when the pointer resolves, `asserted` history when it
   does not, `observed` never — and a migration `observation`.
6. **projection** — `state.json` becomes the v6 snapshot; statuses are
   derived (imported-closed tasks `completed`, re-evidence tasks
   `in_progress` at their blocked criteria, pending tasks `pending`).

**rollback** restores the v5 pair byte-identically from the verified
backup and removes the v6 artifacts. It MUST refuse — until `--force` —
when the journal carries more events than the migration minted:
post-migration v6 work is real history, not debris. The reverse migration
(v6 → v5) does not exist; a v6 plan under the v5 runner (the v5
finalization in `verify/plan_contract.py`) is refused naming the contract
pointer (D2-10), while the read-only verifier judges it by its v6 records.

## 9. Cross-agent and cold resume (normative)

The journal is the truth; `state.json` and `views/` are reprojections. A
resuming host MUST recover in this order — inspect (read-only), validate
(read-only), `project`, `render --reconcile` with recorded authority — and
MUST treat stale fingerprints (dirty files, moved workspace, different
revision) as invalidated evidence to re-run, never as reusable results.
Because `.dwp/` is gitignored, a second host has nothing until the sender
exports the bundle (`ledger.py export --dest`: journal, snapshot,
contract chain, and every cited evidence artifact — a dangling cited
pointer is recorded missing, never dropped); a missing `state.json` on the
receiving host is expected and rebuilt by `project`. The journal is never
replayed as conversation context: resumption goes back through the execute
v6 loop with its per-task context manifest.

## 10. Onboarding guidance (normative)

Onboarding a repository that will run v6 plans (§2's activation rule)
adds four records to the generated guidance, taught by the trigger-gated
[`../onboard/v6.md`](../onboard/v6.md) and reconciled under the same
non-destructive rules as every other generated section:

1. a **capability declaration** using exactly the closed ability set of
   `shared/resources.py` — unstated is `false`, an unmeterable limit is
   advisory with the missing ability named, `telemetry` is opt-in, and
   the minimal host is supported;
2. **authority boundaries** drawn from the repository's real approval
   rules — never boilerplate;
3. an **outcome/test mapping** citing the repository's own runnable
   commands — never an invented or aspirational check;
4. **concise working context** — entry-point budget discipline; nothing
   here expands routine per-task reads.

A v5-only repository MUST receive none of these sections. Upgrading a
harness reconciles; it never re-onboards from scratch and never converts
an existing plan across generations (§8). A second pass with unchanged
inputs MUST produce no diff.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall