@bvdm/delano 0.1.0

package/README.md

@@ -0,0 +1,122 @@
+# Delano
+
+Delano is an agent-agnostic, runtime-guided, skill-driven delivery system.
+
+## WHY
+
+AI-assisted delivery is fast, but it easily becomes inconsistent.
+
+Delano exists to keep teams fast **and** reliable by giving one shared way to move from business outcomes to specs, tasks, code, and evidence.
+
+It is designed to reduce:
+- execution drift between planning and implementation
+- tool-specific lock-in
+- undocumented decisions and low-trust delivery flow
+
+## WHAT
+
+Delano is a spec-first runtime for software delivery, backed by explicit file contracts and deterministic scripts.
+
+Core pieces:
+- `HANDBOOK.md` — canonical operating model and governance
+- `.project/` — delivery truth (projects, tasks, context, updates, decisions)
+- `.agents/` — shared runtime (scripts, rules, hooks, skills, adapters)
+- `.claude/` — compatibility mirror for Claude-style paths (symlink where supported, directory mirror otherwise)
+- `.delano/` — optional UI layer
+
+Probe-aware delivery is part of the operating model: draft the spec, make the probe decision explicit, and only approve once uncertainty is retired or consciously accepted.
+
+Supported adapters:
+- Claude Code
+- Codex CLI
+- OpenCode
+- Pi coding agent
+
+## HOW
+
+### Quick start (inside a Delano repo)
+
+```bash
+# 1) Validate the runtime and required assets
+bash .agents/scripts/pm/validate.sh
+
+# 2) Create a new delivery project scaffold
+bash .agents/scripts/pm/init.sh <slug> "<Project Name>" <owner> <lead>
+
+# 3) See portfolio/project status
+bash .agents/scripts/pm/status.sh
+
+# 4) Get next executable tasks
+bash .agents/scripts/pm/next.sh
+```
+
+### CLI v1 (current package work)
+
+Delano now has a thin npm CLI layer with:
+- package name `@bvdm/delano`
+- binary name `delano`
+- embedded install assets instead of a GitHub-fetch wrapper
+- wrapper commands for `install`, `init`, `validate`, `status`, and `next`
+
+Local development examples from this repository:
+
+```bash
+# Build the packaged asset payload
+npm run build:assets
+
+# Inspect the CLI surface
+node bin/delano.js --help
+
+# Install the approved base payload into another repo or scratch target
+node bin/delano.js install --target /path/to/repo --yes
+```
+
+### Daily operating loop
+
+1. Keep project intent and execution synced in `.project/projects/<slug>/`.
+2. Execute work through workstreams and atomic tasks (`tasks/T-xxx.md`).
+3. Record progress/blockers in `updates/*.md`.
+4. Re-run validation before merge/handoff:
+   ```bash
+   bash .agents/scripts/pm/validate.sh
+   ```
+
+### Install Delano into another repository
+
+Preferred v1 path:
+
+```bash
+delano install --target /path/to/repo --yes
+```
+
+Current source-repo development path:
+
+```bash
+node bin/delano.js install --target /path/to/repo --yes
+```
+
+Base install behavior:
+- installs only the approved allowlist payload
+- aborts on existing-path conflicts unless `--force` is used
+- does not install `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `OPENCODE.md`, or `PI.md` by default
+
+Legacy bridge path:
+
+```bash
+./install-delano.sh
+```
+
+The shell installer remains available for migration, but it is broader than the npm base install path and should be treated as the compatibility bridge rather than the preferred v1 behavior.
+
+Legacy non-interactive example:
+
+```bash
+./install-delano.sh --target /path/to/repo --agents claude,codex --yes
+```
+
+### Read next
+
+- `docs/user-guide.md` for the user-facing overview
+- `HANDBOOK.md` for full operating semantics
+- `.agents/scripts/README.md` for runtime script inventory
+- `AGENTS.md` and adapter entrypoints (`CLAUDE.md`, `CODEX.md`, etc.) for agent-specific bootstraps

package/assets/install-manifest.json

@@ -0,0 +1,102 @@
+{
+  "version": 1,
+  "paths": [
+    ".agents/adapters/claude/README.md",
+    ".agents/adapters/codex/README.md",
+    ".agents/adapters/opencode/README.md",
+    ".agents/adapters/pi/README.md",
+    ".agents/common/README.md",
+    ".agents/hooks/bash-worktree-fix.sh",
+    ".agents/hooks/post-tool-logger.js",
+    ".agents/hooks/README.md",
+    ".agents/hooks/session-tracker.js",
+    ".agents/hooks/user-prompt-logger.js",
+    ".agents/logs/.gitkeep",
+    ".agents/logs/schema.md",
+    ".agents/README.md",
+    ".agents/rules/agent-coordination.md",
+    ".agents/rules/datetime.md",
+    ".agents/rules/frontmatter-operations.md",
+    ".agents/rules/github-operations.md",
+    ".agents/rules/path-standards.md",
+    ".agents/rules/README.md",
+    ".agents/rules/test-execution.md",
+    ".agents/rules/worktree-operations.md",
+    ".agents/scripts/check-path-standards.sh",
+    ".agents/scripts/fix-path-standards.sh",
+    ".agents/scripts/git-sparse-download.sh",
+    ".agents/scripts/log-event.js",
+    ".agents/scripts/log-event.sh",
+    ".agents/scripts/pm/blocked.sh",
+    ".agents/scripts/pm/epic-list.sh",
+    ".agents/scripts/pm/in-progress.sh",
+    ".agents/scripts/pm/init.sh",
+    ".agents/scripts/pm/next.sh",
+    ".agents/scripts/pm/prd-list.sh",
+    ".agents/scripts/pm/search.sh",
+    ".agents/scripts/pm/standup.sh",
+    ".agents/scripts/pm/status.sh",
+    ".agents/scripts/pm/validate.sh",
+    ".agents/scripts/query-log.sh",
+    ".agents/scripts/README.md",
+    ".agents/scripts/test-and-log.sh",
+    ".agents/skills/.gitkeep",
+    ".agents/skills/breakdown-skill/references/runbook.md",
+    ".agents/skills/breakdown-skill/SKILL.md",
+    ".agents/skills/breakdown-skill/templates/ambiguity-report.md",
+    ".agents/skills/breakdown-skill/templates/task-batch-summary.md",
+    ".agents/skills/closeout-skill/references/runbook.md",
+    ".agents/skills/closeout-skill/SKILL.md",
+    ".agents/skills/closeout-skill/templates/closure-checklist.md",
+    ".agents/skills/closeout-skill/templates/outcome-review.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/execution-skill/references/runbook.md",
+    ".agents/skills/execution-skill/SKILL.md",
+    ".agents/skills/execution-skill/templates/blocker-update.md",
+    ".agents/skills/execution-skill/templates/stream-update.md",
+    ".agents/skills/learning-skill/references/runbook.md",
+    ".agents/skills/learning-skill/SKILL.md",
+    ".agents/skills/learning-skill/templates/improvement-backlog.md",
+    ".agents/skills/learning-skill/templates/retrospective.md",
+    ".agents/skills/planning-skill/references/runbook.md",
+    ".agents/skills/planning-skill/SKILL.md",
+    ".agents/skills/planning-skill/templates/architecture-decision.md",
+    ".agents/skills/planning-skill/templates/workstream-definition.md",
+    ".agents/skills/quality-skill/references/runbook.md",
+    ".agents/skills/quality-skill/SKILL.md",
+    ".agents/skills/quality-skill/templates/gate-decision.md",
+    ".agents/skills/quality-skill/templates/quality-evidence.md",
+    ".agents/skills/README.md",
+    ".agents/skills/sync-skill/references/runbook.md",
+    ".agents/skills/sync-skill/SKILL.md",
+    ".agents/skills/sync-skill/templates/conflict-resolution-actions.md",
+    ".agents/skills/sync-skill/templates/drift-report.md",
+    ".delano/README.md",
+    ".gitattributes",
+    ".gitignore",
+    ".project/context/gui-testing.md",
+    ".project/context/product-context.md",
+    ".project/context/progress.md",
+    ".project/context/project-brief.md",
+    ".project/context/project-overview.md",
+    ".project/context/project-structure.md",
+    ".project/context/project-style-guide.md",
+    ".project/context/README.md",
+    ".project/context/system-patterns.md",
+    ".project/context/tech-context.md",
+    ".project/projects/.gitkeep",
+    ".project/registry/linear-map.json",
+    ".project/registry/migration-map.json",
+    ".project/templates/completion-summary.md",
+    ".project/templates/plan.md",
+    ".project/templates/progress-update.md",
+    ".project/templates/spec.md",
+    ".project/templates/task.md",
+    ".project/templates/workstream.md",
+    "HANDBOOK.md",
+    "install-delano.sh"
+  ]
+}

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

@@ -0,0 +1,12 @@
+# .agents
+
+Canonical shared runtime for Delano.
+
+- `scripts/`, `rules/`, `hooks/`, `skills/`, `logs/` -> shared Delano runtime assets
+- `adapters/claude/` -> Claude adapter notes
+- `adapters/codex/` -> Codex adapter notes
+- `adapters/opencode/` -> OpenCode adapter notes
+- `adapters/pi/` -> Pi adapter notes
+- `common/` -> shared adapter docs/policies
+
+The compatibility path `.claude/` may mirror this runtime for agents that still expect Claude-style paths.

package/assets/payload/.agents/adapters/claude/README.md

@@ -0,0 +1,5 @@
+# Claude adapter
+
+- Start from `AGENTS.md`
+- Shared runtime is in `.agents/` (available at `.claude/` via symlink)
+- Keep Claude-specific behavior in `CLAUDE.md` and this adapter folder

package/assets/payload/.agents/adapters/codex/README.md

@@ -0,0 +1,5 @@
+# Codex adapter
+
+- Start from `AGENTS.md`
+- Use `.project/` as source of truth
+- Reuse runtime scripts via `.agents/scripts/*` (or `.claude/scripts/*` compatibility symlink)

package/assets/payload/.agents/adapters/opencode/README.md

@@ -0,0 +1,5 @@
+# OpenCode adapter
+
+- Start from `AGENTS.md`
+- Use `.project/` as source of truth
+- Reuse runtime scripts via `.agents/scripts/*` (or `.claude/scripts/*` compatibility symlink)

package/assets/payload/.agents/adapters/pi/README.md

@@ -0,0 +1,5 @@
+# Pi adapter
+
+- Start from `AGENTS.md`
+- Use `.project/` as source of truth
+- Reuse runtime scripts via `.agents/scripts/*` (or `.claude/scripts/*` compatibility symlink)

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

@@ -0,0 +1,3 @@
+# Common adapter guidance
+
+All adapters must operate against `.project/` contracts and follow `HANDBOOK.md` gates.

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

@@ -0,0 +1,11 @@
+# Delano Hook Layer
+
+This directory contains optional runtime hooks for session and mutation tracking.
+
+Default hooks:
+- `session-tracker.js`
+- `post-tool-logger.js`
+- `user-prompt-logger.js`
+- `bash-worktree-fix.sh`
+
+All hooks append JSONL records in `.agents/logs/`.

package/assets/payload/.agents/hooks/bash-worktree-fix.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Ensure shell starts in repository root when invoked from nested worktree paths.
+root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$root"
+echo "worktree context set: $root"

package/assets/payload/.agents/hooks/post-tool-logger.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+const payload = process.argv[2] ? JSON.parse(process.argv[2]) : { type: 'tool_mutation' };
+const root = process.cwd();
+const dir = path.join(root, '.agents', 'logs');
+const file = path.join(dir, 'changes.jsonl');
+fs.mkdirSync(dir, { recursive: true });
+
+const row = {
+  timestamp: new Date().toISOString(),
+  type: payload.type || 'tool_mutation',
+  actor: payload.actor || 'runtime',
+  meta: payload.meta || {}
+};
+
+fs.appendFileSync(file, JSON.stringify(row) + '\n', 'utf8');

package/assets/payload/.agents/hooks/session-tracker.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+const [action = 'start', sessionId = 'unknown'] = process.argv.slice(2);
+const root = process.cwd();
+const dir = path.join(root, '.agents', 'logs');
+const file = path.join(dir, 'sessions.jsonl');
+fs.mkdirSync(dir, { recursive: true });
+
+const row = {
+  timestamp: new Date().toISOString(),
+  action,
+  sessionId
+};
+
+fs.appendFileSync(file, JSON.stringify(row) + '\n', 'utf8');

package/assets/payload/.agents/hooks/user-prompt-logger.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+const prompt = process.argv.slice(2).join(' ');
+if (!prompt) process.exit(0);
+
+const root = process.cwd();
+const dir = path.join(root, '.agents', 'logs');
+const file = path.join(dir, 'prompts.jsonl');
+fs.mkdirSync(dir, { recursive: true });
+
+const row = {
+  timestamp: new Date().toISOString(),
+  prompt
+};
+
+fs.appendFileSync(file, JSON.stringify(row) + '\n', 'utf8');

package/assets/payload/.agents/logs/schema.md

@@ -0,0 +1,42 @@
+# Log Schema
+
+## `changes.jsonl`
+
+```json
+{
+  "timestamp": "ISO8601 UTC",
+  "type": "event_type",
+  "actor": "system|agent|user",
+  "meta": {}
+}
+```
+
+## `sessions.jsonl`
+
+```json
+{
+  "timestamp": "ISO8601 UTC",
+  "action": "start|end",
+  "sessionId": "string"
+}
+```
+
+## `prompts.jsonl`
+
+```json
+{
+  "timestamp": "ISO8601 UTC",
+  "prompt": "string"
+}
+```
+
+## `test-runs.jsonl`
+
+```json
+{
+  "timestamp": "ISO8601 UTC",
+  "command": "string",
+  "exit_code": 0,
+  "log_file": ".agents/logs/tests/<id>.log"
+}
+```

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

@@ -0,0 +1,12 @@
+# Delano Rule Pack
+
+Rules encode the guardrails described in `HANDBOOK.md`.
+
+Core rule scopes:
+
+- datetime + frontmatter integrity
+- GitHub safety checks
+- path privacy
+- branch/worktree safety
+- test execution hygiene
+- agent coordination protocol

package/assets/payload/.agents/rules/agent-coordination.md

@@ -0,0 +1,5 @@
+# Agent Coordination Rule
+
+- Use multi-stream orchestration only after explicit threshold check.
+- Declare stream scope and conflict zones before execution.
+- Synchronize at dependency boundaries and escalate overlap early.

package/assets/payload/.agents/rules/datetime.md

@@ -0,0 +1,5 @@
+# Datetime Rule
+
+- Use UTC ISO8601 (`YYYY-MM-DDTHH:MM:SSZ`) for `created`, `updated`, and update timestamps.
+- `created` is immutable after file creation.
+- `updated` must reflect real mutation time.

package/assets/payload/.agents/rules/frontmatter-operations.md

@@ -0,0 +1,6 @@
+# Frontmatter Rule
+
+- Contract keys in handbook templates are mandatory.
+- Do not remove required keys.
+- Status values must stay inside the canonical status set.
+- Frontmatter must remain the first block in contract files.

package/assets/payload/.agents/rules/github-operations.md

@@ -0,0 +1,5 @@
+# GitHub Safety Rule
+
+- Verify target remote before issue or PR mutations.
+- Avoid destructive operations without explicit confirmation.
+- Merge only after required quality gates and review semantics are satisfied.

package/assets/payload/.agents/rules/path-standards.md

@@ -0,0 +1,5 @@
+# Path Privacy Rule
+
+- Do not store absolute user-specific paths in shared project artifacts.
+- Prefer repository-relative paths in docs and logs.
+- Run `.agents/scripts/check-path-standards.sh` before publishing major updates.

package/assets/payload/.agents/rules/test-execution.md

@@ -0,0 +1,5 @@
+# Test Hygiene Rule
+
+- Run quality gates based on risk profile.
+- Persist execution evidence in task evidence logs and `.agents/logs`.
+- Do not bypass required quality checks silently.

package/assets/payload/.agents/rules/worktree-operations.md

@@ -0,0 +1,5 @@
+# Branch and Worktree Rule
+
+- Keep one stream owner per shared file at a time.
+- Sequence shared contract edits instead of concurrent mutation.
+- Escalate contested file ownership immediately.

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

@@ -0,0 +1,31 @@
+# Delano Runtime Scripts
+
+This folder contains the script runtime described in `HANDBOOK.md`.
+
+Canonical path: `.agents/scripts/...`
+
+Compatibility path: `.claude/scripts/...` when the mirror is present.
+
+## PM scripts (`.agents/scripts/pm/`)
+
+Critical path:
+- `init.sh`
+- `validate.sh`
+- `status.sh`
+- `next.sh`
+- `blocked.sh`
+
+Operational:
+- `standup.sh`
+- `in-progress.sh`
+- `prd-list.sh`
+- `epic-list.sh`
+- `search.sh`
+
+## Audit and utility
+- `log-event.sh` / `log-event.js`
+- `query-log.sh`
+- `test-and-log.sh`
+- `check-path-standards.sh`
+- `fix-path-standards.sh`
+- `git-sparse-download.sh`

package/assets/payload/.agents/scripts/check-path-standards.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$root"
+
+matches_file="$(mktemp)"
+trap 'rm -f "$matches_file"' EXIT
+
+compat_paths=()
+if [[ -e .claude || -L .claude ]]; then
+  compat_paths+=(.claude)
+fi
+
+if find .project .agents "${compat_paths[@]}" \
+  -type f \
+  \( -name '*.md' -o -name '*.json' -o -name '*.yaml' -o -name '*.yml' \) \
+  -not -path '.agents/logs/*' \
+  -not -path '.claude/logs/*' \
+  -print0 | xargs -0 grep -nE '(/home/[^[:space:]]+|/Users/[^[:space:]]+|[A-Za-z]:\\[^[:space:]]+)' > "$matches_file" 2>/dev/null; then
+  echo "Absolute path violations found:"
+  cat "$matches_file"
+  exit 1
+fi
+
+echo "Path standards check passed."

package/assets/payload/.agents/scripts/fix-path-standards.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+  echo "Usage: $0 <file...>"
+  echo "Replaces absolute user paths with <ABS_PATH> in the provided files."
+  exit 1
+fi
+
+for file in "$@"; do
+  [[ -f "$file" ]] || { echo "Skip missing file: $file"; continue; }
+  perl -0777 -i -pe 's#/home/[^\s)]+#<ABS_PATH>#g; s#/Users/[^\s)]+#<ABS_PATH>#g; s#[A-Za-z]:\\[^\s)]+#<ABS_PATH>#g' "$file"
+  echo "Normalized paths in: $file"
+done