@bvdm/delano 0.1.5 → 0.1.7

package/HANDBOOK.md

@@ -633,6 +633,7 @@ This keeps rapid learning without weakening team governance.
 
 **Primary components**
 
+- skill: `prototype-skill`
 - discovery artifacts from `spec.md`
 - targeted prototype commands or narrow experiments
 - `pm/validate.sh` if probe findings mutate contracts

package/README.md

@@ -16,7 +16,7 @@ The npm package is intentionally thin. It distributes the approved runtime paylo
 
 - Package: `@bvdm/delano`
 - Binary: `delano`
-- Commands: `install`, `init`, `validate`, `status`, `next`
+- Commands: `onboarding`, `install`, `init`, `validate`, `status`, `next`
 - Primary v1.1 goal: bootstrap a repo safely, then stay out of the way
 
 ## One-command bootstrap
@@ -84,9 +84,18 @@ Notes:
 
 ## How to use Delano after install
 
+Recommended first step:
+
+```bash
+delano onboarding
+```
+
+`delano onboarding` searches upward for `AGENTS.md`, asks for explicit approval before it analyzes anything, and prints recommendations using the packaged onboarding skill rubric. It does not edit `AGENTS.md` on its own.
+
 If you bootstrap with one-shot `npx`, keep using `npx` for wrapper commands:
 
 ```bash
+npx -y @bvdm/delano@latest onboarding --approve-agents-analysis
 npx -y @bvdm/delano@latest validate
 npx -y @bvdm/delano@latest status
 npx -y @bvdm/delano@latest next -- --all
@@ -95,6 +104,7 @@ npx -y @bvdm/delano@latest next -- --all
 If the package is installed locally or globally, run these inside the target repository:
 
 ```bash
+delano onboarding
 delano validate
 delano status
 delano next -- --all
@@ -133,6 +143,7 @@ The CLI does not bundle its own shell or Python runtime.
 
 The base install payload intentionally excludes top-level adapter entry docs such as `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `OPENCODE.md`, and `PI.md`. Those remain opt-in only.
 The installable `.project/context/` pack is seeded from generic templates during packaging; it does not ship Delano's own repo-specific context files into consumer repositories.
+After install, the recommended first step is `delano onboarding`, which requires explicit approval before it reviews `AGENTS.md`.
 
 ## Optional AGENTS.md / CLAUDE.md snippet
 

package/assets/install-manifest.json

@@ -49,10 +49,22 @@
     ".agents/skills/closeout-skill/SKILL.md",
     ".agents/skills/closeout-skill/templates/closure-checklist.md",
     ".agents/skills/closeout-skill/templates/outcome-review.md",
+    ".agents/skills/manage-context/references/context-audit-checklist.md",
+    ".agents/skills/manage-context/references/runbook.md",
+    ".agents/skills/manage-context/SKILL.md",
+    ".agents/skills/manage-context/templates/context-debt-report.md",
+    ".agents/skills/manage-context/templates/context-refresh-summary.md",
+    ".agents/skills/onboarding/references/agents-md-best-practices.md",
+    ".agents/skills/onboarding/SKILL.md",
     ".agents/skills/discovery-skill/references/runbook.md",
     ".agents/skills/discovery-skill/SKILL.md",
     ".agents/skills/discovery-skill/templates/clarification-questions.md",
     ".agents/skills/discovery-skill/templates/discovery-summary.md",
+    ".agents/skills/prototype-skill/references/probe-design-checklist.md",
+    ".agents/skills/prototype-skill/references/runbook.md",
+    ".agents/skills/prototype-skill/SKILL.md",
+    ".agents/skills/prototype-skill/templates/probe-approval-recommendation.md",
+    ".agents/skills/prototype-skill/templates/probe-findings.md",
     ".agents/skills/execution-skill/references/runbook.md",
     ".agents/skills/execution-skill/SKILL.md",
     ".agents/skills/execution-skill/templates/blocker-update.md",

package/assets/payload/.agents/scripts/pm/validate.sh

@@ -91,6 +91,7 @@ fi
 # Required skill contracts
 required_skills=(
   discovery-skill
+  prototype-skill
   planning-skill
   breakdown-skill
   sync-skill

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/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`

package/assets/payload/.agents/skills/prototype-skill/references/probe-design-checklist.md

@@ -0,0 +1,26 @@
+# Probe Design Checklist
+
+Use this before running a Prototype Probe.
+
+## Probe quality
+- Is the uncertainty material enough to justify a probe?
+- Is the probe tied to one concrete question?
+- Is the probe smaller than full implementation?
+- Can the result change the spec approval decision?
+
+## Scope control
+- What is explicitly in scope?
+- What is explicitly out of scope?
+- Which surfaces may be touched?
+- What would make this probe too broad?
+
+## Evidence
+- What outcome would justify approval?
+- What outcome would require revision?
+- What outcome would suggest another narrow probe?
+- What footguns or side effects must be recorded even if the probe succeeds?
+
+## Safety
+- Is there any risk of probe code being treated like production-ready output?
+- Is there a clean way to prevent direct merge from probe artifacts?
+- Are follow-up tasks likely to be needed after the probe?

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

@@ -0,0 +1,27 @@
+# Prototype Probe Runbook
+
+1. Read the draft `spec.md` and identify the single material uncertainty to retire or bound.
+2. Confirm `probe_required: true` and keep the probe narrow.
+3. Define the smallest useful experiment:
+   - what is being tested
+   - what evidence is needed
+   - what touched surfaces are in scope
+   - what is explicitly out of scope
+4. Time-box the probe, normally to `<= 1 day`.
+5. Run the experiment using the safest path, CLI-first when feasible.
+6. Do not merge probe output directly into production delivery flow.
+7. Fold findings back into `spec.md`:
+   - what changed after probe
+   - touched surfaces
+   - footguns
+   - remaining uncertainty
+   - approval recommendation
+8. Validate if contracts changed:
+   - `bash .agents/scripts/pm/validate.sh`
+9. Snapshot status when useful:
+   - `bash .agents/scripts/pm/status.sh`
+
+Exit gate:
+- probe findings recorded
+- approval recommendation is clear
+- next step is explicit: approve, revise, or run another narrow probe

package/assets/payload/.agents/skills/prototype-skill/templates/probe-approval-recommendation.md

@@ -0,0 +1,13 @@
+# Probe Approval Recommendation
+
+## Recommendation
+- Approve
+- Revise
+- Run another narrow probe
+
+## Why
+
+## Remaining Uncertainty
+
+## Immediate Next Action
+- 

package/assets/payload/.agents/skills/prototype-skill/templates/probe-findings.md

@@ -0,0 +1,16 @@
+# Probe Findings
+
+## Uncertainty Tested
+
+## Experiment Shape
+
+## Evidence Observed
+
+## Touched Surfaces
+- 
+
+## Footguns
+- 
+
+## What Changed In The Spec
+- 

package/assets/payload/HANDBOOK.md

@@ -633,6 +633,7 @@ This keeps rapid learning without weakening team governance.
 
 **Primary components**
 
+- skill: `prototype-skill`
 - discovery artifacts from `spec.md`
 - targeted prototype commands or narrow experiments
 - `pm/validate.sh` if probe findings mutate contracts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bvdm/delano",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "CLI for the Delano delivery runtime.",
   "license": "UNLICENSED",
   "bin": {

package/src/cli/commands/onboarding.js

@@ -0,0 +1,29 @@
+const { ANALYSIS_APPROVAL_FLAG, runOnboarding } = require("../lib/onboarding");
+
+function getOnboardingHelp() {
+  return [
+    "Usage:",
+    "  delano onboarding [options]",
+    "",
+    "Options:",
+    "  --target <dir>                 Analyze the nearest AGENTS.md starting from this directory.",
+    `  ${ANALYSIS_APPROVAL_FLAG}   Explicitly approve AGENTS.md analysis without an interactive prompt.`,
+    "  -h, --help                    Show command help.",
+    "",
+    "Behavior:",
+    "  - Finds AGENTS.md by searching upward from the target directory.",
+    "  - Requires explicit approval before analyzing the file.",
+    "  - Uses the packaged onboarding skill rubric to print recommendations.",
+    "  - Never edits AGENTS.md; changes remain a separate explicit approval step.",
+    "",
+    "Examples:",
+    "  delano onboarding",
+    `  delano onboarding ${ANALYSIS_APPROVAL_FLAG}`,
+    "  delano onboarding --target ../repo"
+  ].join("\n");
+}
+
+module.exports = {
+  getOnboardingHelp,
+  runOnboarding
+};

package/src/cli/index.js

@@ -3,6 +3,7 @@ const path = require("node:path");
 
 const { CliError } = require("./lib/errors");
 const { getPackageRoot } = require("./lib/runtime");
+const { getOnboardingHelp, runOnboarding } = require("./commands/onboarding");
 const { runInstall, getInstallHelp } = require("./commands/install");
 const { createWrapperCommand } = require("./commands/wrapper");
 
@@ -14,6 +15,11 @@ const wrapperCommands = {
 };
 
 const commands = {
+  onboarding: {
+    description: "Analyze AGENTS.md with the approval-first onboarding skill.",
+    run: runOnboarding,
+    help: getOnboardingHelp
+  },
   install: {
     description: "Install the approved Delano runtime payload into a target repository.",
     run: runInstall,
@@ -84,6 +90,7 @@ function getGeneralHelp() {
     "  delano <command> [options]",
     "",
     "Commands:",
+    "  onboarding Analyze AGENTS.md with the approval-first onboarding skill",
     "  install    Install the approved Delano runtime payload",
     "  init       Run .agents/scripts/pm/init.sh in the current Delano repo",
     "  validate   Run .agents/scripts/pm/validate.sh in the current Delano repo",
@@ -95,6 +102,8 @@ function getGeneralHelp() {
     "  -v, --version   Show version",
     "",
     "Examples:",
+    "  delano onboarding",
+    "  delano onboarding --approve-agents-analysis",
     "  delano --yes",
     "  delano --target ../my-repo --yes",
     "  npx -y @bvdm/delano@latest --yes",
@@ -104,6 +113,9 @@ function getGeneralHelp() {
     "Shorthand:",
     "  delano [install-options] is equivalent to delano install [install-options].",
     "",
+    "Recommended first step after install:",
+    "  Run 'delano onboarding' to review AGENTS.md. The command requires explicit approval before analysis.",
+    "",
     "Use 'delano <command> --help' for command-specific help."
   ].join("\n");
 }

package/src/cli/lib/install.js

@@ -251,6 +251,7 @@ function applyInstallPlan(plan, options) {
 
   console.log("");
   console.log(`Installed ${plan.items.length} files into ${options.target}.`);
+  console.log("Recommended next step: run 'delano onboarding' to review AGENTS.md. The command asks for explicit approval before analysis.");
 }
 
 function normalizeManifestEntries(rawManifest) {

package/src/cli/lib/onboarding.js

@@ -0,0 +1,243 @@
+const { existsSync, readFileSync } = require("node:fs");
+const path = require("node:path");
+const readline = require("node:readline/promises");
+const { stdin, stdout } = require("node:process");
+
+const { CliError } = require("./errors");
+const { getPackageRoot } = require("./runtime");
+
+const ANALYSIS_APPROVAL_FLAG = "--approve-agents-analysis";
+
+function parseOnboardingArgs(args) {
+  const options = {
+    approveAnalysis: false,
+    target: process.cwd()
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--target") {
+      index += 1;
+      if (!args[index]) {
+        throw new CliError("Missing value for --target.", 1);
+      }
+      options.target = args[index];
+      continue;
+    }
+
+    if (arg.startsWith("--target=")) {
+      options.target = arg.slice("--target=".length);
+      continue;
+    }
+
+    if (arg === ANALYSIS_APPROVAL_FLAG) {
+      options.approveAnalysis = true;
+      continue;
+    }
+
+    throw new CliError(`Unknown onboarding option: ${arg}`, 1);
+  }
+
+  options.target = path.resolve(options.target);
+  return options;
+}
+
+function findAgentsFile(startDir = process.cwd()) {
+  let current = path.resolve(startDir);
+  const { root } = path.parse(current);
+
+  while (true) {
+    const candidate = path.join(current, "AGENTS.md");
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+
+    if (current === root) {
+      return null;
+    }
+
+    current = path.dirname(current);
+  }
+}
+
+function getOnboardingGuidePath() {
+  const packageRoot = getPackageRoot();
+  const candidates = [
+    path.join(packageRoot, ".agents", "skills", "onboarding", "references", "agents-md-best-practices.md"),
+    path.join(
+      packageRoot,
+      "assets",
+      "payload",
+      ".agents",
+      "skills",
+      "onboarding",
+      "references",
+      "agents-md-best-practices.md"
+    )
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new CliError(
+    "Could not find the packaged onboarding guide. Rebuild the package assets with 'npm run build:assets'.",
+    1
+  );
+}
+
+function analyzeAgentsContent(content) {
+  const checks = [
+    {
+      label: "mission",
+      presentMessage: "Maps the repository's core operating surface and canonical files.",
+      missingMessage: "Add a one-line mission so each turn starts from the repo's purpose and quality bar.",
+      test: (text) => /(^|\n)##\s+mission\b/i.test(text)
+    },
+    {
+      label: "first-turn workflow",
+      presentMessage: "Provides a reusable first-turn sequence instead of only static rules.",
+      missingMessage: "Add a numbered first-turn workflow so the agent knows how to inspect, retrieve, implement, and verify in order.",
+      test: (text) => /first-turn workflow|first turn workflow/i.test(text)
+        || (/order of operations/i.test(text) && /(^|\n)1\.\s/m.test(text))
+    },
+    {
+      label: "source-of-truth map",
+      presentMessage: "Points to the main sources of truth the agent should trust.",
+      missingMessage: "Keep a compact source-of-truth map and include 'read this first for X' hints where drift would be costly.",
+      test: (text) => /canonical truth|source of truth/i.test(text)
+    },
+    {
+      label: "retrieval index",
+      presentMessage: "Provides retrieval hints for common questions and work areas.",
+      missingMessage: "Add a retrieval index so the agent can jump from a task area to the right file quickly.",
+      test: (text) => /retrieval index/i.test(text)
+    },
+    {
+      label: "stable constraints",
+      presentMessage: "Captures durable repo constraints and runtime shape.",
+      missingMessage: "Call out stable high-impact constraints such as runtime assumptions, branch policy, style rules, or business-logic conventions.",
+      test: (text) => /branch policy|style rules|runtime quirks|default workspace|definition of done|node|bash|python|workspace/i.test(text)
+    },
+    {
+      label: "approval and safety boundaries",
+      presentMessage: "States approval boundaries or destructive-action handling.",
+      missingMessage: "Make approval boundaries explicit, including destructive actions, recoverable edits, and outbound/public actions.",
+      test: (text) => /approval|destructive|recoverable|outbound|public actions|confirm/i.test(text)
+    },
+    {
+      label: "verification expectations",
+      presentMessage: "Tells the agent how to verify work and report completion state.",
+      missingMessage: "Add verification expectations, including when to run lint/test/build and how to report done, partial, or blocked.",
+      test: (text) => /verification|verify|lint|test|build|done|partial|blocked/i.test(text)
+    }
+  ];
+
+  const strengths = [];
+  const gaps = [];
+
+  for (const check of checks) {
+    if (check.test(content)) {
+      strengths.push(check.presentMessage);
+    } else {
+      gaps.push(check.missingMessage);
+    }
+  }
+
+  return { strengths, gaps };
+}
+
+function formatOnboardingReport({ agentsPath, guidePath, review }) {
+  const lines = [
+    "Onboarding review",
+    "-----------------",
+    `AGENTS.md: ${agentsPath}`,
+    `Guide: ${guidePath}`,
+    ""
+  ];
+
+  if (review.strengths.length > 0) {
+    lines.push("Already working well:");
+    for (const strength of review.strengths) {
+      lines.push(`- ${strength}`);
+    }
+    lines.push("");
+  }
+
+  if (review.gaps.length > 0) {
+    lines.push("Improve next:");
+    for (const gap of review.gaps) {
+      lines.push(`- ${gap}`);
+    }
+    lines.push("");
+  } else {
+    lines.push("No major gaps detected against the onboarding guide.");
+    lines.push("");
+  }
+
+  lines.push("No edits were applied.");
+  lines.push("If you want AGENTS.md changed, approve that explicitly in a separate step.");
+
+  return lines.join("\n");
+}
+
+async function confirmAgentsAnalysis(options, agentsPath) {
+  if (options.approveAnalysis) {
+    return true;
+  }
+
+  if (!stdin.isTTY || !stdout.isTTY) {
+    throw new CliError(
+      `Onboarding requires explicit approval. Re-run interactively or pass ${ANALYSIS_APPROVAL_FLAG}.`,
+      1
+    );
+  }
+
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = await rl.question(
+      `Analyze AGENTS.md at ${agentsPath} with the onboarding skill rubric? This only reads the file and prints recommendations. [y/N] `
+    );
+    return /^[Yy](es)?$/.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+
+async function runOnboarding(args) {
+  const options = parseOnboardingArgs(args);
+  const agentsPath = findAgentsFile(options.target);
+
+  if (!agentsPath) {
+    throw new CliError(
+      `Could not find AGENTS.md from ${options.target}. Add AGENTS.md or pass --target to a repository that has one.`,
+      1
+    );
+  }
+
+  const approved = await confirmAgentsAnalysis(options, agentsPath);
+  if (!approved) {
+    console.log("Onboarding skipped. No analysis performed.");
+    return 0;
+  }
+
+  const guidePath = getOnboardingGuidePath();
+  const agentsContent = readFileSync(agentsPath, "utf8");
+  const review = analyzeAgentsContent(agentsContent);
+  console.log(formatOnboardingReport({ agentsPath, guidePath, review }));
+  return 0;
+}
+
+module.exports = {
+  ANALYSIS_APPROVAL_FLAG,
+  analyzeAgentsContent,
+  confirmAgentsAnalysis,
+  findAgentsFile,
+  formatOnboardingReport,
+  getOnboardingGuidePath,
+  parseOnboardingArgs,
+  runOnboarding
+};