@bvdm/delano 0.1.4 → 0.1.7

package/assets/payload/.project/context/progress.md

@@ -1,23 +1,13 @@
 # Progress
 
 ## What Changed
-- Completed the handbook-theo-method-upgrade implementation bundle across handbook, templates, runtime scripts, hooks/logging, installer messaging, and skill/runbook references.
-- Synced the `.claude` compatibility mirror to the updated `.agents` runtime so canonical and fallback command paths now align.
-- Replaced the placeholder `.project/context/` files with repo-specific context for Delano as both product and reference implementation.
-- Created the `delano-cli-packaging-v1` project with an approved spec, planned delivery plan, four workstreams, and a decomposed task graph.
-- Added the first working `@bvdm/delano` scaffold: package metadata, `delano` bin entrypoint, command dispatch, wrapper commands, install manifest, asset build pipeline, and a conservative install flow.
+- <summarize the most recent meaningful delivery changes>
 
 ## Why It Changed
-- The repo had drift between written process, generated scaffolds, and executable runtime behavior around canonical paths and probe-aware delivery.
-- Closing that drift restores Delano's contract discipline and makes the documented operating model match the runnable one.
-- The repository still lacked living context for Delano itself and needed a clean planning baseline before starting the npm CLI packaging effort.
-- The CLI effort needed a real executable foundation so later bridge, docs, and release work could build on actual package behavior rather than placeholders.
+- <record the decision or trigger behind those changes>
 
 ## What Is Next
-- Use `.agents/scripts/pm/*` as the canonical operator path for future work.
-- Follow up separately on any external documentation that may still teach legacy `.claude` examples.
-- Continue `delano-cli-packaging-v1` with legacy installer alignment, operator docs, and release-focused verification.
+- <list the next expected work or validation steps>
 
 ## Remaining Risks
-- External docs outside this repository may still need the same canonical-path sweep.
-- The CLI packaging project still needs explicit operator documentation and final quality review before the first npm release is ready.
+- <capture the main unresolved risks or open questions>

package/assets/payload/.project/context/project-brief.md

@@ -1,13 +1,13 @@
 # Project Brief
 
 ## Problem
-- Delano is both the product and the reference repository, so this repo needs real execution context inside `.project/context/`, not empty placeholders.
-- The next delivery initiative is a first npm/CLI packaging layer that must wrap the existing runtime without breaking Delano's handbook-first, file-contract-first architecture.
+- <describe the product or operational problem this repository exists to solve>
+- <capture why Delano is being installed or used in this repository now>
 
 ## Target Outcome
-- Keep this repository self-describing for maintainers and coding agents by documenting the actual product purpose, runtime boundaries, operating constraints, and current health.
-- Stand up a handbook-compliant project outline for the v1 CLI packaging effort so execution can start from an approved spec, delivery plan, workstreams, and atomic tasks.
+- <state the measurable delivery outcome for the current scope>
+- <note what should improve if this effort succeeds>
 
 ## Scope Boundaries
-- In scope: repository context for Delano itself, the current canonical runtime model, and the planning/decomposition artifacts for the CLI packaging initiative.
-- Out of scope: implementing the CLI in this setup pass, redefining Delano's core architecture, or changing adapter entrypoint behavior by default.
+- In scope: <list the work Delano should track here>
+- Out of scope: <list nearby work that should stay outside this context pack>

package/assets/payload/.project/context/project-overview.md

@@ -1,14 +1,10 @@
 # Project Overview
 
 ## Mission
-- Delano is an agent-agnostic delivery system that turns outcomes into specs, plans, tasks, execution evidence, and learnings through shared file contracts and runtime scripts.
-- This repository is the canonical source for the handbook, runtime, templates, and reference install path used when Delano is adopted in other repositories.
+- <describe the repository mission and the outcome it supports>
 
 ## Active Delivery Scopes
-- `handbook-theo-method-upgrade` is complete and established the `.agents`-first, probe-aware operating model.
-- `delano-cli-packaging-v1` is the next planned scope: add a thin npm CLI and packaging layer around the existing runtime without turning Delano into a harness.
+- <list the current active or planned Delano project slugs>
 
 ## Current Health
-- Canonical runtime and contract structure are present and `bash .agents/scripts/pm/validate.sh` passes in this environment.
-- `.agents/` is the canonical runtime tree. `.claude/` exists in this repo as a directory mirror with matching contents, not as a symlink.
-- The primary current gap was context quality rather than missing runtime pieces; the context pack should now be maintained as execution memory, not treated as boilerplate.
+- <summarize runtime readiness, major gaps, and known operational concerns>

package/assets/payload/.project/context/project-structure.md

@@ -3,22 +3,17 @@
 Document major repository boundaries and ownership.
 
 ## Canonical Boundaries
-- `HANDBOOK.md`: canonical operating model, governance, contracts, and workflow stages.
-- `.project/`: delivery truth for project specs, plans, workstreams, tasks, updates, decisions, templates, registry state, and shared context.
-- `.agents/`: canonical runtime assets shared across supported coding agents.
-- `.claude/`: compatibility mirror of `.agents/`; present for Claude-style path expectations only.
-- `.delano/`: optional presentation layer; never source of process truth.
+- `HANDBOOK.md`: <describe where operating rules live>
+- `.project/`: <describe the delivery-truth contents for this repository>
+- `.agents/`: <describe the shared runtime assets in use>
+- `.claude/`: <note compatibility expectations if present>
+- `.delano/`: <note any optional presentation or UI layer if present>
 
 ## Runtime Areas
-- `.agents/scripts/pm/`: critical operator commands such as `init.sh`, `validate.sh`, `status.sh`, `next.sh`, and `blocked.sh`.
-- `.agents/skills/`: stage skills and supporting runbooks/templates used to structure work.
-- `.agents/rules/` and `.agents/hooks/`: guardrails and runtime instrumentation.
-- `.agents/adapters/<agent>/`: thin agent-specific notes for Claude, Codex, OpenCode, and Pi.
+- <list the important scripts, skills, rules, hooks, or service areas>
 
 ## Documentation Areas
-- `README.md`: short product/repo overview.
-- `docs/`: operator-facing guidance that expands on the handbook and runtime.
-- Top-level adapter entry files such as `AGENTS.md`, `CLAUDE.md`, and `CODEX.md`: thin pointers into the canonical model.
+- <list the primary operator-facing docs or reference files>
 
 ## Working Notes
-- `tmp/` is scratch space and is not part of Delano's canonical runtime or delivery truth.
+- <capture scratch paths, generated areas, or local-only conventions worth knowing>

package/assets/payload/.project/context/project-style-guide.md

@@ -1,17 +1,10 @@
 # Project Style Guide
 
 ## Naming
-- Use kebab-case for project slugs under `.project/projects/`.
-- Use `WS-<letter>` for workstream identifiers and `T-###` for task identifiers.
-- Keep adapter/runtime references explicit: `.agents` for canonical paths, `.claude` only when discussing compatibility behavior.
+- <record naming rules for project slugs, workstreams, tasks, packages, or services>
 
 ## Documentation Conventions
-- Keep context files short, factual, and current enough for another operator or agent to resume work without rediscovery.
-- Use handbook terminology consistently: outcome, spec, probe decision, workstream, task, evidence, and closeout.
-- Frontmatter timestamps must be ISO8601 UTC.
-- Do not leak machine-specific absolute paths into shared docs or contracts.
+- <record conventions for context updates, timestamps, terminology, and evidence>
 
 ## Review Expectations
-- Changes that touch contracts, templates, runtime scripts, or user-facing docs should be checked for cross-artifact consistency, not reviewed in isolation.
-- Run `bash .agents/scripts/pm/validate.sh` after modifying delivery artifacts or runtime behavior.
-- When planning install or packaging work, prefer conflict-first and non-destructive behavior by default.
+- <record required validation, review scope, and any change-management constraints>

package/assets/payload/.project/context/system-patterns.md

@@ -3,20 +3,16 @@
 Capture architecture and delivery patterns that should be reused.
 
 ## Handbook-First Delivery
-- Changes to runtime behavior, templates, and operator guidance should be aligned with `HANDBOOK.md`, not invented ad hoc in scripts or adapter docs.
-- Planning follows the handbook stages: discovery, optional probe, planning, breakdown, sync, execution, quality, closeout, and learning.
+- <describe how this repository uses Delano's operating model>
 
 ## File-Contract-First State
-- `.project/` is the source of truth for delivery state. Scripts and future tooling should read and respect those contracts instead of replacing them with hidden state.
-- Project context files are part of execution continuity and should be updated when repo reality changes.
+- <describe which files are canonical and how tooling should treat them>
 
 ## Thin Runtime Wrapping
-- Delano favors thin wrappers around existing execution scripts over large rewrites. The current PM scripts are shell/Python-driven and should remain the execution layer unless there is a strong reason to replace them.
-- Adapter entrypoints stay minimal and point back to the shared runtime and handbook.
+- <describe how wrappers or automation should stay conservative>
 
 ## Compatibility Without Dual Truth
-- `.claude/` may mirror `.agents/`, but it is compatibility infrastructure only. New work should treat `.agents/` as canonical and avoid creating a second source of truth.
+- <describe any compatibility mirrors and the canonical runtime boundary>
 
 ## Conservative Installation
-- Installation and packaging flows should compute explicit plans, surface conflicts early, and avoid silently overwriting `.project/` or `.agents/` content.
-- Seeded files may establish a repo, but once installed the consumer repo owns its own `.project` state.
+- <describe any install, bootstrap, or write-safety expectations>

package/assets/payload/.project/context/tech-context.md

@@ -1,19 +1,10 @@
 # Tech Context
 
 ## Stack
-- Markdown contracts and templates for delivery artifacts.
-- Bash for the PM/operator script layer.
-- Python for validation and dependency-graph checks.
-- Git for repository discovery, sparse installs, and sync-oriented workflows.
-- Node/npm is the intended packaging surface for the next CLI initiative, but not yet the execution layer for Delano itself.
+- <list the key languages, frameworks, runtimes, and build tools>
 
 ## Runtime Constraints
-- Current operator environment is Windows-first with PowerShell available; Delano still assumes `bash`, `git`, and a usable Python runtime.
-- Canonical command paths should use `.agents/scripts/...`; `.claude/scripts/...` is compatibility-only when the mirror exists.
-- Shared docs and contracts must avoid absolute path leakage.
-- `.project` and `.agents` are seeded artifacts and runtime assets, not package-owned mutable state after install.
+- <record environment assumptions, platform constraints, and required dependencies>
 
 ## Integration Points
-- `.project/registry/linear-map.json` and `.project/registry/migration-map.json` capture tracker mapping state.
-- `.agents/scripts/pm/init.sh`, `validate.sh`, `status.sh`, `next.sh`, and `blocked.sh` are the current critical-path operator interface.
-- `install-delano.sh` is the current shell-first bootstrap path for installing Delano into another repository.
+- <list the main external systems, internal scripts, or registry files this repo depends on>

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/assets/templates/context/README.md

@@ -0,0 +1,17 @@
+# Delano Context Pack
+
+This folder is seeded by `delano install` with generic starter context.
+
+Update each file to describe this repository's real delivery context before active implementation work begins.
+
+Required context files:
+
+- `project-overview.md`
+- `project-brief.md`
+- `tech-context.md`
+- `project-structure.md`
+- `system-patterns.md`
+- `product-context.md`
+- `project-style-guide.md`
+- `progress.md`
+- `gui-testing.md`

package/assets/templates/context/gui-testing.md

@@ -0,0 +1,16 @@
+# GUI Testing Policy
+
+## Enforcement Mode
+- `<advisory|required>`
+
+## Smoke Routes
+- <list any critical UI routes or state that must be exercised>
+
+## Console Filtering
+- <describe which browser or runtime errors are blocking>
+
+## Evidence Requirements
+- <describe what screenshots, logs, or notes must be captured>
+
+## Design Validation Threshold
+- <describe the usability and visual quality bar for UI work>

package/assets/templates/context/product-context.md

@@ -0,0 +1,10 @@
+# Product Context
+
+## Users
+- <describe the primary operator, maintainer, or end-user groups>
+
+## Core Flows
+- <describe the critical workflows that should remain intact>
+
+## Constraints
+- <record the major product, policy, or architectural constraints>

package/assets/templates/context/progress.md

@@ -0,0 +1,13 @@
+# Progress
+
+## What Changed
+- <summarize the most recent meaningful delivery changes>
+
+## Why It Changed
+- <record the decision or trigger behind those changes>
+
+## What Is Next
+- <list the next expected work or validation steps>
+
+## Remaining Risks
+- <capture the main unresolved risks or open questions>

package/assets/templates/context/project-brief.md

@@ -0,0 +1,13 @@
+# Project Brief
+
+## Problem
+- <describe the product or operational problem this repository exists to solve>
+- <capture why Delano is being installed or used in this repository now>
+
+## Target Outcome
+- <state the measurable delivery outcome for the current scope>
+- <note what should improve if this effort succeeds>
+
+## Scope Boundaries
+- In scope: <list the work Delano should track here>
+- Out of scope: <list nearby work that should stay outside this context pack>

package/assets/templates/context/project-overview.md

@@ -0,0 +1,10 @@
+# Project Overview
+
+## Mission
+- <describe the repository mission and the outcome it supports>
+
+## Active Delivery Scopes
+- <list the current active or planned Delano project slugs>
+
+## Current Health
+- <summarize runtime readiness, major gaps, and known operational concerns>

package/assets/templates/context/project-structure.md

@@ -0,0 +1,19 @@
+# Project Structure
+
+Document major repository boundaries and ownership.
+
+## Canonical Boundaries
+- `HANDBOOK.md`: <describe where operating rules live>
+- `.project/`: <describe the delivery-truth contents for this repository>
+- `.agents/`: <describe the shared runtime assets in use>
+- `.claude/`: <note compatibility expectations if present>
+- `.delano/`: <note any optional presentation or UI layer if present>
+
+## Runtime Areas
+- <list the important scripts, skills, rules, hooks, or service areas>
+
+## Documentation Areas
+- <list the primary operator-facing docs or reference files>
+
+## Working Notes
+- <capture scratch paths, generated areas, or local-only conventions worth knowing>

package/assets/templates/context/project-style-guide.md

@@ -0,0 +1,10 @@
+# Project Style Guide
+
+## Naming
+- <record naming rules for project slugs, workstreams, tasks, packages, or services>
+
+## Documentation Conventions
+- <record conventions for context updates, timestamps, terminology, and evidence>
+
+## Review Expectations
+- <record required validation, review scope, and any change-management constraints>

package/assets/templates/context/system-patterns.md

@@ -0,0 +1,18 @@
+# System Patterns
+
+Capture architecture and delivery patterns that should be reused.
+
+## Handbook-First Delivery
+- <describe how this repository uses Delano's operating model>
+
+## File-Contract-First State
+- <describe which files are canonical and how tooling should treat them>
+
+## Thin Runtime Wrapping
+- <describe how wrappers or automation should stay conservative>
+
+## Compatibility Without Dual Truth
+- <describe any compatibility mirrors and the canonical runtime boundary>
+
+## Conservative Installation
+- <describe any install, bootstrap, or write-safety expectations>

package/assets/templates/context/tech-context.md

@@ -0,0 +1,10 @@
+# Tech Context
+
+## Stack
+- <list the key languages, frameworks, runtimes, and build tools>
+
+## Runtime Constraints
+- <record environment assumptions, platform constraints, and required dependencies>
+
+## Integration Points
+- <list the main external systems, internal scripts, or registry files this repo depends on>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bvdm/delano",
-  "version": "0.1.4",
+  "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

@@ -30,6 +30,7 @@ function readInstallManifest() {
   return {
     manifestPath,
     manifest,
+    entries: normalizeManifestEntries(manifest),
     payloadRoot: path.join(getPackageRoot(), "assets", "payload")
   };
 }
@@ -120,17 +121,17 @@ function parseInstallArgs(args) {
 }
 
 function buildInstallPlan(options) {
-  const { manifest, payloadRoot } = readInstallManifest();
-  const items = manifest.paths.map((relativePath) => {
-    const sourcePath = path.join(payloadRoot, relativePath);
+  const { manifest, entries, payloadRoot } = readInstallManifest();
+  const items = entries.map((entry) => {
+    const sourcePath = path.join(payloadRoot, entry.target);
     if (!existsSync(sourcePath)) {
-      throw new CliError(getMissingPackagedAssetMessage(relativePath), 1);
+      throw new CliError(getMissingPackagedAssetMessage(entry.target), 1);
     }
 
     return {
-      relativePath,
+      relativePath: entry.target,
       sourcePath,
-      targetPath: path.join(options.target, relativePath)
+      targetPath: path.join(options.target, entry.target)
     };
   });
 
@@ -250,6 +251,46 @@ 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) {
+  const entries = Array.isArray(rawManifest.files) ? rawManifest.files : rawManifest.paths;
+  if (!Array.isArray(entries)) {
+    throw new CliError("Install manifest is missing a files array.", 1);
+  }
+
+  const seenTargets = new Set();
+  return entries.map((entry) => {
+    const normalized = typeof entry === "string"
+      ? { source: entry, target: entry }
+      : entry;
+
+    if (!normalized || typeof normalized.source !== "string" || typeof normalized.target !== "string") {
+      throw new CliError("Install manifest entries must be strings or { source, target } objects.", 1);
+    }
+
+    validateManifestPath(normalized.source, "source");
+    validateManifestPath(normalized.target, "target");
+
+    if (seenTargets.has(normalized.target)) {
+      throw new CliError(`Install manifest target is duplicated: ${normalized.target}`, 1);
+    }
+    seenTargets.add(normalized.target);
+
+    return normalized;
+  });
+}
+
+function validateManifestPath(relativePath, fieldName) {
+  if (path.isAbsolute(relativePath)) {
+    throw new CliError(`Install manifest ${fieldName} must be relative: ${relativePath}`, 1);
+  }
+
+  const normalizedPath = path.normalize(relativePath);
+  if (normalizedPath.startsWith("..") || normalizedPath === "..") {
+    throw new CliError(`Install manifest ${fieldName} must stay inside the package root: ${relativePath}`, 1);
+  }
 }
 
 module.exports = {
@@ -258,6 +299,7 @@ module.exports = {
   buildInstallPlan,
   collectConflicts,
   confirmInstall,
+  normalizeManifestEntries,
   parseAgentList,
   parseInstallArgs,
   printConflicts,