@bvdm/delano 0.1.5 → 0.1.8

package/assets/payload/.agents/scripts/propose-closeout-learning.mjs

@@ -0,0 +1,20 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename);
+const repoRoot = resolveRepoRoot(__dirname);
+const project = readOption("--project") || "delano-learning-loop";
+const metricsPath = readOption("--metrics") || path.join(repoRoot, ".agents", "metrics", "delivery-events.jsonl");
+const metrics = readEvents(metricsPath).filter((event)=>event.project === project || !event.project);
+const proposal = {
+  schema_version: 1,
+  mode: "dry-run-proposal",
+  project,
+  apply_posture: "proposal-only-no-mutation",
+  summary: { event_count: metrics.length, recommendation_count: 1, privacy: "summary-only" },
+  recommendations: [{ id: "LP-001", type: "closeout-learning", summary: metrics.length ? "Review summarized delivery metrics during closeout." : "Capture at least one delivery metric event during future closeouts.", evidence: ["scripts/summarize-project-metrics.mjs", ".agents/logs/delivery-metrics.md"] }]
+};
+if (process.argv.includes("--json")) console.log(JSON.stringify(proposal,null,2)); else console.log(`Closeout learning proposal produced ${proposal.summary.recommendation_count} recommendation(s) for ${project}.`);
+function readEvents(filePath){ if(!existsSync(filePath)) return []; return readFileSync(filePath,"utf8").split(/\r?\n/).filter(Boolean).map(line=>JSON.parse(line)); }
+function readOption(name){ const i=process.argv.indexOf(name); return i===-1?"":process.argv[i+1]; }
+function resolveRepoRoot(startDir){ for(const c of [path.resolve(startDir,".."),path.resolve(startDir,"..","..")]) if(existsSync(path.join(c,".agents"))) return c; return path.resolve(startDir,".."); }

package/assets/payload/.agents/scripts/read-local-sync-map.mjs

@@ -0,0 +1,135 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = resolveRepoRoot(__dirname);
+
+export function readLocalSyncMap(root = repoRoot) {
+  const projectsRoot = path.join(root, ".project", "projects");
+  const registryPath = path.join(root, ".project", "registry", "linear-map.json");
+  const registry = readOptionalJson(registryPath) || { projects: {}, tasks: {} };
+  const projects = [];
+
+  for (const projectDir of listProjectDirs(projectsRoot)) {
+    const slug = path.basename(projectDir);
+    const projectRegistry = registry.projects?.[slug] || {};
+    const tasks = [];
+    const tasksDir = path.join(projectDir, "tasks");
+    if (existsSync(tasksDir)) {
+      for (const taskFile of readdirSync(tasksDir, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.endsWith(".md")).map((entry) => path.join(tasksDir, entry.name)).sort()) {
+        const text = readFileSync(taskFile, "utf8");
+        const fm = parseFrontmatter(text);
+        const registryKey = `${slug}/${fm.id || path.basename(taskFile, ".md")}`;
+        const taskRegistry = registry.tasks?.[registryKey] || registry.tasks?.[fm.id] || {};
+        tasks.push({
+          local_id: fm.id || path.basename(taskFile, ".md"),
+          name: fm.name || titleFromMarkdown(text) || path.basename(taskFile, ".md"),
+          status: fm.status || "unknown",
+          workstream: fm.workstream || "",
+          local_path: toRepoPath(root, taskFile),
+          depends_on: parseList(fm.depends_on || "[]"),
+          linear_issue_id: emptyToUndefined(fm.linear_issue_id) || taskRegistry.linear_issue_id,
+          github_issue: emptyToUndefined(fm.github_issue) || taskRegistry.github_issue,
+          github_pr: emptyToUndefined(fm.github_pr) || taskRegistry.github_pr
+        });
+      }
+    }
+    projects.push({
+      slug,
+      local_path: toRepoPath(root, projectDir),
+      linear_project_id: projectRegistry.linear_project_id,
+      github_repo: projectRegistry.github_repo,
+      tasks
+    });
+  }
+
+  return { schema_version: 1, source: "local", projects };
+}
+
+export function validateLocalSyncMap(syncMap) {
+  const errors = [];
+  const seenProjects = new Set();
+  for (const project of syncMap.projects || []) {
+    if (seenProjects.has(project.slug)) errors.push(`duplicate project slug: ${project.slug}`);
+    seenProjects.add(project.slug);
+    if (!/^\.project\/projects\/[^/]+$/.test(project.local_path || "")) errors.push(`invalid project local_path for ${project.slug}: ${project.local_path}`);
+    const seenTasks = new Set();
+    for (const task of project.tasks || []) {
+      if (!/^T-[0-9]{3}$/.test(task.local_id || "")) errors.push(`${project.slug} has invalid task id: ${task.local_id}`);
+      if (seenTasks.has(task.local_id)) errors.push(`${project.slug} has duplicate task id: ${task.local_id}`);
+      seenTasks.add(task.local_id);
+      for (const dependency of task.depends_on || []) {
+        if (!seenTasks.has(dependency) && !(project.tasks || []).some((candidate) => candidate.local_id === dependency)) {
+          errors.push(`${project.slug}/${task.local_id} depends on missing local task ${dependency}`);
+        }
+      }
+      if (task.github_issue && !isUrlOrNumber(task.github_issue)) errors.push(`${project.slug}/${task.local_id} has invalid github_issue: ${task.github_issue}`);
+      if (task.github_pr && !isUrlOrNumber(task.github_pr)) errors.push(`${project.slug}/${task.local_id} has invalid github_pr: ${task.github_pr}`);
+    }
+  }
+  return errors;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const syncMap = readLocalSyncMap(repoRoot);
+  const errors = validateLocalSyncMap(syncMap);
+  if (process.argv.includes("--json")) {
+    console.log(JSON.stringify(syncMap, null, 2));
+  }
+  if (errors.length > 0) {
+    console.error("Local sync map validation failed:");
+    for (const error of errors) console.error(`- ${error}`);
+    process.exit(1);
+  }
+  if (!process.argv.includes("--json")) {
+    const taskCount = syncMap.projects.reduce((sum, project) => sum + project.tasks.length, 0);
+    console.log(`Local sync map check passed for ${syncMap.projects.length} project(s) and ${taskCount} task(s).`);
+  }
+}
+
+function listProjectDirs(projectsRoot) {
+  if (!existsSync(projectsRoot)) return [];
+  return readdirSync(projectsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => path.join(projectsRoot, entry.name)).sort();
+}
+function parseFrontmatter(text) {
+  const match = text.match(/^---\n([\s\S]*?)\n---\n/);
+  if (!match) return {};
+  const result = {};
+  for (const line of match[1].split("\n")) {
+    const index = line.indexOf(":");
+    if (index === -1) continue;
+    result[line.slice(0, index).trim()] = line.slice(index + 1).trim();
+  }
+  return result;
+}
+function parseList(raw) {
+  const value = String(raw || "").trim();
+  if (!value || value === "[]") return [];
+  if (value.startsWith("[") && value.endsWith("]")) return value.slice(1, -1).split(",").map((item) => item.trim().replace(/^['\"]|['\"]$/g, "")).filter(Boolean);
+  return [value.replace(/^['\"]|['\"]$/g, "")].filter(Boolean);
+}
+function titleFromMarkdown(text) {
+  const match = text.match(/^#\s+(.+)$/m);
+  return match ? match[1].replace(/^Task:\s*/, "").trim() : "";
+}
+function emptyToUndefined(value) {
+  const trimmed = String(value || "").trim();
+  return trimmed ? trimmed : undefined;
+}
+function isUrlOrNumber(value) {
+  return /^https?:\/\//.test(value) || /^#?[0-9]+$/.test(value);
+}
+function readOptionalJson(filePath) {
+  if (!existsSync(filePath)) return null;
+  return JSON.parse(readFileSync(filePath, "utf8"));
+}
+function toRepoPath(root, filePath) {
+  return path.relative(root, filePath).split(path.sep).join("/");
+}
+function resolveRepoRoot(startDir) {
+  const candidates = [path.resolve(startDir, ".."), path.resolve(startDir, "..", "..")];
+  for (const candidate of candidates) if (existsSync(path.join(candidate, ".project")) && existsSync(path.join(candidate, ".agents"))) return candidate;
+  return path.resolve(startDir, "..");
+}

package/assets/payload/.agents/scripts/select-next-task.mjs

@@ -0,0 +1,22 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = resolveRepoRoot(__dirname);
+const projectSlug = readOption("--project") || "delano-multi-agent-execution";
+const stream = readOption("--stream") || "default";
+const tasksDir = path.join(repoRoot, ".project", "projects", projectSlug, "tasks");
+const leases = readLeases(readOption("--leases") || path.join(repoRoot, ".agents", "leases", "active-leases.json"));
+const ready = readdirSync(tasksDir).filter((file)=>file.endsWith(".md")).map((file)=>readTask(path.join(tasksDir,file))).filter((task)=>task.status === "ready");
+const activeZones = new Set(leases.filter((l)=>l.status === "active" && new Date(l.expires_at).getTime() > Date.now()).flatMap((l)=>l.conflict_zones || []));
+const candidates = ready.map((task)=>({ ...task, stream, blocked_by_active_zone: task.conflicts_with.some((zone)=>activeZones.has(zone)) })).filter((task)=>!task.blocked_by_active_zone);
+const selected = candidates[0] || null;
+const result = { schema_version: 1, project: projectSlug, stream, ready_count: ready.length, candidate_count: candidates.length, selected: selected && { id: selected.id, file: selected.file, priority: selected.priority } };
+if (process.argv.includes("--json")) console.log(JSON.stringify(result, null, 2)); else console.log(selected ? `Selected ${selected.id} for ${stream}.` : `No unleased ready task for ${stream}.`);
+export function readTask(filePath) { const text=readFileSync(filePath,"utf8"); return { file:path.basename(filePath), id: front(text,"id"), status: front(text,"status"), priority: front(text,"priority"), conflicts_with: list(front(text,"conflicts_with")) }; }
+function front(text,key){ const m=text.match(new RegExp(`^${key}:\\s*(.*)$`,"m")); return m?m[1].trim():""; }
+function list(v){ const m=v.match(/^\[(.*)\]$/); return m?m[1].split(",").map(x=>x.trim()).filter(Boolean):[]; }
+function readLeases(filePath){ if(!existsSync(filePath)) return []; return JSON.parse(readFileSync(filePath,"utf8")).leases || []; }
+function readOption(name){ const i=process.argv.indexOf(name); return i===-1?"":process.argv[i+1]; }
+function resolveRepoRoot(startDir){ for(const c of [path.resolve(startDir,".."),path.resolve(startDir,"..","..")]) if(existsSync(path.join(c,".project"))) return c; return path.resolve(startDir,".."); }

package/assets/payload/.agents/scripts/summarize-project-metrics.mjs

@@ -0,0 +1,15 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename);
+const repoRoot = resolveRepoRoot(__dirname);
+const eventsPath = readOption("--events") || path.join(repoRoot, ".agents", "metrics", "delivery-events.jsonl");
+const project = readOption("--project") || "all";
+const events = readEvents(eventsPath).filter((e)=>project === "all" || e.project === project);
+const byType = Object.create(null);
+for (const e of events) byType[e.event_type] = (byType[e.event_type] || 0) + 1;
+const summary = { schema_version: 1, project, event_count: events.length, by_type: byType, privacy: "summary-only" };
+if (process.argv.includes("--json")) console.log(JSON.stringify(summary, null, 2)); else console.log(`Project metrics summary: ${events.length} event(s), privacy=summary-only.`);
+function readEvents(filePath){ if(!existsSync(filePath)) return []; return readFileSync(filePath,"utf8").split(/\r?\n/).filter(Boolean).map((line)=>JSON.parse(line)); }
+function readOption(name){ const i=process.argv.indexOf(name); return i===-1?"":process.argv[i+1]; }
+function resolveRepoRoot(startDir){ for(const c of [path.resolve(startDir,".."),path.resolve(startDir,"..","..")]) if(existsSync(path.join(c,".agents"))) return c; return path.resolve(startDir,".."); }

package/assets/payload/.agents/skills/README.md

@@ -5,6 +5,7 @@ Handbook-aligned skill contracts.
 Core workflow skills:
 
 - `discovery-skill`
+- `prototype-skill`
 - `planning-skill`
 - `breakdown-skill`
 - `sync-skill`
@@ -13,6 +14,11 @@ Core workflow skills:
 - `closeout-skill`
 - `learning-skill`
 
+Utility skills:
+
+- `manage-context`
+- `onboarding`
+
 Each skill defines:
 - intent and trigger context
 - required inputs

package/assets/payload/.agents/skills/closeout-skill/SKILL.md

@@ -17,11 +17,13 @@ description: Close the delivery loop and capture completion evidence, status upd
 - closure update
 - completion summary
 - updated status in contracts/registry
+- learning proposals for any rule, skill, schema, or fixture changes discovered during closeout
 
 ## Quality checks
 - required tasks resolved
 - evidence package complete
 - outcome review captured
+- learning proposals are reviewed before adoption
 
 ## Failure behavior
 - block closure when evidence is incomplete
@@ -40,3 +42,4 @@ description: Close the delivery loop and capture completion evidence, status upd
 - `references/runbook.md`
 - `templates/outcome-review.md`
 - `templates/closure-checklist.md`
+- `templates/learning-proposal.md`

package/assets/payload/.agents/skills/closeout-skill/references/runbook.md

@@ -3,8 +3,10 @@
 1. Confirm all required tasks are in terminal state.
 2. Ensure quality evidence package is complete.
 3. Write completion summary from template.
-4. Update project status and mapping registry.
-5. Review event log:
+4. Draft a learning proposal for any proposed rule, skill, schema, or fixture update.
+5. Keep learning proposals in `proposed` state until reviewed and explicitly accepted.
+6. Update project status and mapping registry.
+7. Review event log:
    - `bash .agents/scripts/query-log.sh --last 100`
 6. Validate:
    - `bash .agents/scripts/pm/status.sh`
@@ -12,5 +14,6 @@
 
 Exit gate:
 - Outcome review captured
+- Learning proposals reviewed before adoption
 - Evidence complete
 - Delivery state closed cleanly

package/assets/payload/.agents/skills/closeout-skill/templates/closure-checklist.md

@@ -4,4 +4,6 @@
 - [ ] Quality gates passed
 - [ ] Evidence package complete
 - [ ] Registry/state updated
+- [ ] Learning proposals drafted for rule, skill, schema, or fixture changes
+- [ ] Learning proposals reviewed before adoption
 - [ ] Retrospective scheduled

package/assets/payload/.agents/skills/closeout-skill/templates/learning-proposal.md

@@ -0,0 +1,21 @@
+# Closeout Learning Proposal
+
+## Proposal Type
+rule | skill | schema | fixture
+
+## Title
+
+## Rationale
+What happened, what should change, and why the change is worth reviewing.
+
+## Target Paths
+- repo/relative/path
+
+## Evidence
+- command, task, fixture, or local event summary
+
+## Review Gate
+Required before adoption. Do not apply the proposed rule, skill, schema, or fixture change until it has been reviewed and explicitly accepted.
+
+## Adoption Status
+proposed

package/assets/payload/.agents/skills/closeout-skill/templates/learning-proposals.md

@@ -0,0 +1,25 @@
+# Closeout Learning Proposals
+
+Use this during project closeout to propose reusable runtime changes. Proposals are review-first: do not silently adopt changes to shared rules, skills, schemas, or fixtures.
+
+## Proposal Summary
+
+- Project:
+- Source closeout/update:
+- Reviewer:
+- Review status: pending
+
+## Proposed Changes
+
+| Target type | Target path | Change summary | Evidence | Adoption state |
+| --- | --- | --- | --- | --- |
+| rule | `.agents/rules/example.md` | Replace with the observed improvement. | Link task/update evidence. | proposed |
+| skill | `.agents/skills/example-skill/SKILL.md` | Replace with the observed improvement. | Link task/update evidence. | proposed |
+| schema | `.agents/schemas/example.schema.json` | Replace with the observed improvement. | Link task/update evidence. | proposed |
+| fixture | `.agents/validation-fixtures/example.json` | Replace with the observed improvement. | Link task/update evidence. | proposed |
+
+## Review Gate
+
+- [ ] Every proposal cites observed evidence.
+- [ ] No proposal is adopted before review status is approved.
+- [ ] Rejected proposals retain the reason for future context.

package/assets/payload/.agents/skills/manage-context/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: manage-context
+description: Repair and maintain `.project/context/` so it reflects current project reality. Use when context files are stale, contradictory, still template-like, after major scope or architecture changes, before handoff, or when execution friction suggests context debt.
+---
+
+# manage-context
+
+## Trigger context
+- `.project/context/` still contains starter or placeholder language
+- implementation reality has drifted from spec, plan, or workstreams
+- repeated confusion appears around scope, terminology, ownership, architecture, or testing
+- a handoff, restart, or milestone review needs trustworthy context
+- a major scope, workflow, or architecture change landed and context was not refreshed
+
+## Required inputs
+- current `.project/context/` files
+- related project docs (`spec.md`, `plan.md`, `workstreams/*.md`, `decisions.md`, progress notes)
+- recent execution evidence (task state, code changes, review feedback, logs)
+
+## Output schema
+- updated `.project/context/*.md` files where needed
+- context debt summary
+- explicit contradictions or evidence gaps list
+- recommended follow-up actions when context cannot be repaired safely
+
+## Quality checks
+- no obvious template placeholders remain
+- context matches current implementation and delivery reality
+- terminology is consistent across files
+- scope, constraints, and non-goals are explicit
+- progress reflects evidence, not aspiration
+- unresolved uncertainty is stated plainly instead of being hidden
+
+## Failure behavior
+- do not invent missing facts
+- stop short of rewriting uncertain sections as if they were confirmed
+- return evidence gaps and contradiction notes when repair is partial
+- prefer an explicit partial refresh over fake completeness
+
+## Allowed side effects
+- update files under `.project/context/`
+- remove stale placeholder text from context files
+- normalize duplicated or conflicting phrasing across context files
+- add concise dated notes when they improve handoff clarity
+
+## Script hooks
+- `bash .agents/scripts/pm/validate.sh`
+- `bash .agents/scripts/pm/status.sh`
+- `bash .agents/scripts/pm/search.sh "<term>"`
+
+## Execution assets
+- `references/runbook.md`
+- `references/context-audit-checklist.md`
+- `templates/context-debt-report.md`
+- `templates/context-refresh-summary.md`

package/assets/payload/.agents/skills/manage-context/references/context-audit-checklist.md

@@ -0,0 +1,26 @@
+# Context Audit Checklist
+
+Use this checklist before declaring the context pack healthy.
+
+## Reality check
+- Does `project-overview.md` describe the project as it exists now?
+- Does `project-brief.md` still match the active outcome and constraints?
+- Does `tech-context.md` match the real implementation shape?
+- Does `product-context.md` match the real user or delivery problem?
+- Does `progress.md` describe actual current status rather than intended status?
+
+## Drift check
+- Are there claims that conflict with `spec.md`, `plan.md`, or workstreams?
+- Are there terms used inconsistently across context files?
+- Are owners, boundaries, or dependencies implied in one file but absent in others?
+- Are testing expectations current, especially in `gui-testing.md`?
+
+## Template debt check
+- Are placeholder markers or generic starter phrases still present?
+- Are sections filled with boilerplate rather than repo-specific facts?
+- Does the pack still read like an install scaffold instead of a lived project?
+
+## Handoff check
+- Could a new agent or teammate resume work from this context pack without guessing?
+- Are the main constraints, risks, and non-goals easy to find?
+- Are open questions explicit?

package/assets/payload/.agents/skills/manage-context/references/runbook.md

@@ -0,0 +1,26 @@
+# Context Runbook
+
+1. Read `.project/context/README.md` to confirm the expected context pack shape.
+2. Review all current `.project/context/*.md` files.
+3. Cross-check the context pack against the active source of truth:
+   - `.project/projects/<slug>/spec.md`
+   - `.project/projects/<slug>/plan.md`
+   - `.project/projects/<slug>/workstreams/*.md`
+   - `.project/projects/<slug>/decisions.md`
+   - recent task state, code changes, and review feedback
+4. Mark context debt before editing:
+   - stale claims
+   - template placeholders
+   - contradictory terminology
+   - missing constraints or ownership
+   - progress statements without evidence
+5. Repair only what the evidence supports.
+6. Record unresolved contradictions or evidence gaps explicitly.
+7. Validate:
+   - `bash .agents/scripts/pm/validate.sh`
+   - `bash .agents/scripts/pm/status.sh`
+
+Exit gate:
+- context pack is trustworthy enough for handoff or resumed execution
+- open uncertainty is visible
+- no placeholder text remains in edited sections

package/assets/payload/.agents/skills/manage-context/templates/context-debt-report.md

@@ -0,0 +1,22 @@
+# Context Debt Report
+
+## Summary
+
+## Stale or Contradictory Sections
+- File:
+- Issue:
+- Evidence:
+- Action:
+
+## Placeholder or Template Debt
+- File:
+- Section:
+- Replacement needed:
+
+## Missing Context
+- Gap:
+- Why it matters:
+- Best source of truth:
+
+## Recommended Follow-up
+- 

package/assets/payload/.agents/skills/manage-context/templates/context-refresh-summary.md

@@ -0,0 +1,13 @@
+# Context Refresh Summary
+
+## Refreshed Files
+- 
+
+## What Changed
+- 
+
+## Remaining Uncertainty
+- 
+
+## Next Action
+- Resume execution or handoff using the refreshed context pack.

package/assets/payload/.agents/skills/onboarding/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: onboarding
+description: Analyze a repository `AGENTS.md` before broader work begins and improve it only when the user gives explicit approval. Use when the user wants a first-pass review of repo instructions, wants to tighten `AGENTS.md` quality, or needs a compact operating-rules and source-of-truth map for future agent turns.
+---
+
+# onboarding
+
+## Trigger context
+- the user wants an explicit first-turn onboarding pass for a repository
+- `AGENTS.md` exists but may be too thin, stale, or missing key guidance
+- the user asks to review, critique, or improve repo-level agent instructions
+- Delano has just been introduced and `AGENTS.md` should be checked before deeper work starts
+
+## Required inputs
+- repo-root `AGENTS.md`
+- directly relevant source-of-truth docs referenced by `AGENTS.md`
+- explicit user approval before analyzing `AGENTS.md`
+- separate explicit user approval before editing `AGENTS.md`
+
+## Output schema
+- concise gap analysis against `references/agents-md-best-practices.md`
+- keep/add/remove recommendations tied to the repo's actual workflow
+- if edit approval is given, an updated `AGENTS.md` that stays compact and retrieval-oriented
+- explicit note when analysis or edits were skipped because approval was not given
+
+## Quality checks
+- do not analyze `AGENTS.md` until the user explicitly approves the review
+- do not edit `AGENTS.md` until the user explicitly approves changes
+- preserve repo-specific truth instead of pasting generic boilerplate
+- keep `AGENTS.md` compact and point to deeper docs instead of duplicating them
+- make approval boundaries, order of operations, and verification expectations explicit
+
+## Failure behavior
+- if approval is missing, stop and ask plainly
+- if `AGENTS.md` is absent, report that and propose only a minimal skeleton
+- if source-of-truth docs disagree, surface the conflict instead of flattening it
+- if the repo intentionally keeps `AGENTS.md` thin, prefer the minimum coherent improvement
+
+## Allowed side effects
+- read `AGENTS.md` and directly relevant source-of-truth docs
+- update `AGENTS.md` only after explicit edit approval
+- add concise retrieval hints that point to canonical docs
+
+## Script hooks
+- `delano onboarding`
+- `bash .agents/scripts/pm/validate.sh`
+
+## Execution assets
+- `references/agents-md-best-practices.md`

package/assets/payload/.agents/skills/onboarding/references/agents-md-best-practices.md

@@ -0,0 +1,76 @@
+# How to write an AGENTS.md that works
+
+AGENTS.md carries the context the agent needs every turn. Skills and `docs/` hold optional, task-specific workflows. Do not confuse the two.
+
+## What belongs in AGENTS.md
+
+1. Operating rules: startup sequence, approval boundaries, destructive-action handling, definition of done, default workspace.
+2. Source-of-truth map: compact index pointing to where real knowledge lives. Include version-sensitive areas and "if working on X, read Y first" hints.
+3. Order-of-operations: phrase as a sequence, not a blanket rule. Not "always read docs first" but: explore structure -> retrieve relevant docs -> implement -> verify.
+4. Stable, high-impact constraints: repo location, branch policy, style rules, runtime quirks, business-logic conventions. High-frequency, high-impact, easy to miss.
+
+## What does not belong
+
+Long prose, full runbooks, rarely-used procedures, or anything duplicated from `docs/`. Point to it instead.
+
+## Example skeleton (Delano-style)
+
+```markdown
+## Mission
+One line: what this project is, what good work looks like.
+
+## First-Turn Workflow
+1. Inspect repo structure and current git state before assuming shape or ownership.
+2. Read the relevant local source of truth for the area being changed.
+3. Prefer current repo reality over stale plans or model memory.
+4. Make the smallest coherent change that satisfies the task.
+5. Verify with the narrowest meaningful check, then report done / partial / blocked explicitly.
+
+## Source of Truth
+- `HANDBOOK.md`: delivery model, project contracts, evidence, continuity rules.
+- `ARCHITECTURE.md`: product architecture and runtime/orchestration model.
+- `.project/context/`: current project memory - start with `README.md`, then only what is relevant.
+- `.project/projects/<project>/`: active delivery contracts (`spec.md`, `plan.md`, `decisions.md`, `workstreams/`, `tasks/`, `updates/`).
+- `.agents/`: shared delivery/runtime assets, skills, rules, hooks, PM scripts.
+- `README.md`: product status, setup, commands, operational gaps.
+- `src/`, `skills/`, `starter/`, `fixtures/`, `tests/`: implemented surface.
+- `possible-specs.md`: archived only - not active guidance.
+
+## Retrieval Index
+- Delivery workflow -> `HANDBOOK.md` + matching `.agents/skills/<step>-skill/SKILL.md`
+- Active scope / acceptance -> `spec.md` + relevant task files
+- Architecture / runtime -> `ARCHITECTURE.md`, `plan.md`, `.project/context/system-patterns.md`
+- Repo layout -> `.project/context/project-structure.md`
+- Stack / commands -> `.project/context/tech-context.md`, `README.md`, `package.json`
+- Style / docs conventions -> `.project/context/project-style-guide.md`
+- GUI/browser checks -> `.project/context/gui-testing.md`
+- Status / evidence -> `.project/context/progress.md`, `updates/`
+- CRM/provider work -> `src/connectors/`, `fixtures/providers/`, provider tests
+- Starter/runtime assets -> `starter/`, `.runtime/` expectations, starter validation tests
+
+## Delano Order of Operations
+Use the full flow for features, contract changes, or material improvements:
+1. Discovery - define measurable outcome in `spec.md` (`discovery-skill`).
+2. Prototype Probe - time-boxed, only if uncertainty is high; findings back to spec.
+3. Planning - architecture, milestones, rollout, rollback in `plan.md` (`planning-skill`).
+4. Breakdown - atomic tasks, binary acceptance, acyclic dependencies (`breakdown-skill`).
+5. Synchronization - reconcile with Linear/GitHub when tracker state is involved (`sync-skill`).
+6. Execution - dependency-safe tasks inside workstream boundaries, evidence in `updates/` (`execution-skill`).
+7. Quality Ops - risk-based checks, verify acceptance before closure (`quality-skill`).
+8. Closeout - compare to outcome, update project memory, close the loop (`closeout-skill`).
+
+For small local fixes: follow the first-turn workflow; update delivery/context files only when scope, architecture, status, or evidence changes.
+
+## Safety
+- No destructive actions without approval.
+- Prefer recoverable edits.
+- Confirm before outbound/public actions.
+
+## Verification
+- Run lint/test/build when relevant; if skipped, say why.
+- Mark done / partial / blocked explicitly.
+```
+
+## Core principle
+
+AGENTS.md should contain the minimum persistent context needed to make correct decisions reliably, and a compact map for retrieving everything else.

package/assets/payload/.agents/skills/prototype-skill/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: prototype-skill
+description: Run a time-boxed Prototype Probe to retire material uncertainty before spec approval. Use when `spec.md` is still draft, `probe_required: true`, or a narrow experiment is needed to bound technical or delivery risk before planning.
+---
+
+# prototype-skill
+
+## Trigger context
+- `spec.md` is still draft and contains material uncertainty
+- `probe_required: true`
+- approval would otherwise be speculative
+- a narrow experiment can retire a specific technical, UX, integration, or delivery risk faster than discussion alone
+
+## Required inputs
+- `spec.md` with uncertainty and probe fields populated
+- target uncertainty to retire or bound
+- time-box and experiment constraints
+- success or failure evidence expected from the probe
+
+## Output schema
+- updated draft `spec.md`
+- probe findings summary
+- explicit approval recommendation (`approve`, `revise`, or `run another narrow probe`)
+- touched surfaces and footguns list
+
+## Quality checks
+- probe stays time-boxed, normally `<= 1 day`
+- experiment is narrow and directly tied to the uncertainty being tested
+- no production merge happens directly from probe output
+- findings are folded back into `spec.md` before continuation
+- touched surfaces, footguns, and remaining uncertainty are explicit
+
+## Failure behavior
+- stop if the probe is too broad, open-ended, or not tied to a material uncertainty
+- return a narrower probe design when the current one is not safe or useful
+- do not present exploratory output as production-ready implementation
+
+## Allowed side effects
+- update draft `spec.md`
+- create or update temporary probe notes inside the project folder when needed
+- record approval recommendation and follow-up actions
+
+## Script hooks
+- `bash .agents/scripts/pm/validate.sh`
+- `bash .agents/scripts/pm/status.sh`
+
+## Execution assets
+- `references/runbook.md`
+- `references/probe-design-checklist.md`
+- `templates/probe-findings.md`
+- `templates/probe-approval-recommendation.md`