From d84c0a466f4d569f9e4b947f3eb7cfa799b842bb Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Thu, 16 Apr 2026 17:44:03 +0300 Subject: [PATCH 01/11] add dynamic GitHub PR/issue guides and lesson injection to AGENTS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AGENTS.md now generates PR description templates and issue update patterns dynamically from actual GitHub history via gh api. Learned workflow rules from session artifacts are injected directly into the workflow section. Repos with richer history get richer agent guidance — the virtuous cycle. Co-Authored-By: Claude Opus 4.6 (1M context) --- changes.md | 7 ++ lib/commands/agent.sh | 91 ++++++++++++++ lib/commands/learn.sh | 15 +++ lib/modules/learning_sources.sh | 210 ++++++++++++++++++++++++++++++++ package.json | 2 +- 5 files changed, 324 insertions(+), 1 deletion(-) diff --git a/changes.md b/changes.md index e378de7..01ac195 100644 --- a/changes.md +++ b/changes.md @@ -1,5 +1,12 @@ # Changes +### 0.7.0 + +- Dynamic PR description guide in AGENTS.md — fetches recent merged PRs via `gh api`, detects common section headings, includes best-structured PR as a reference example +- Dynamic issue update guide in AGENTS.md — detects comment patterns (checklists, structured sections, status tracking) from the authenticated user's recent issue comments +- Inject learned workflow rules from lesson artifacts into AGENTS.md — session-derived patterns appear directly in the workflow section, not just as file refs +- Fix bare template IDs in lesson artifacts — add flow template cases for `docs-first-alignment`, `workflow-tracing`, `verification-scope`, `legacy-reduction`, `agent-handoff` + ### 0.6.0 - Switch default branch from `main` to `latest` so `npm create` tags align with the branch name diff --git a/lib/commands/agent.sh b/lib/commands/agent.sh index b4f481a..cfa5a90 100644 --- a/lib/commands/agent.sh +++ b/lib/commands/agent.sh @@ -245,6 +245,97 @@ dev_kit_agent_write_agents_md() { printf '%s\n\n' "$_workflow" fi + # ── Learned workflow rules (from agent session lessons) ──────────────── + local _learned_rules _learned_templates + _learned_rules="$(dev_kit_learning_lesson_rules "$repo_dir")" + _learned_templates="$(dev_kit_learning_lesson_templates "$repo_dir")" + if [ -n "$_learned_rules" ] || [ -n "$_learned_templates" ]; then + printf '### Learned from prior sessions\n\n' + printf 'Patterns detected from agent sessions on this repo. Follow these in addition to the workflow above.\n\n' + if [ -n "$_learned_rules" ]; then + while IFS= read -r _rule; do + [ -n "$_rule" ] || continue + printf -- '- %s\n' "$_rule" + done </dev/null || true)" + if [ -n "$_pr_bodies" ]; then + _pr_headings="$(dev_kit_learning_github_pr_heading_pattern "$_pr_bodies")" + _pr_example="$(dev_kit_learning_github_best_pr_example "$_pr_bodies")" + + if [ -n "$_pr_headings" ] || [ -n "$_pr_example" ]; then + printf '## PR description guide\n\n' + printf '_Detected from recent merged PRs in this repo. Follow this structure when creating PRs._\n\n' + + if [ -n "$_pr_headings" ]; then + printf '**Common sections** (appear in multiple PRs):\n\n' + while IFS= read -r _h; do + [ -n "$_h" ] || continue + printf -- '- %s\n' "$_h" + done </dev/null || true)" + if [ -n "$_issue_comments" ]; then + _issue_patterns="$(dev_kit_learning_github_issue_update_detect "$_issue_comments")" + _issue_example="$(dev_kit_learning_github_best_issue_comment "$_issue_comments")" + + if [ -n "$_issue_patterns" ] || [ -n "$_issue_example" ]; then + printf '## Issue update guide\n\n' + printf '_Detected from recent issue comments by the authenticated user. Follow this style when posting updates._\n\n' + + if [ -n "$_issue_patterns" ]; then + printf '**Detected patterns:**\n\n' + while IFS= read -r _p; do + [ -n "$_p" ] || continue + printf -- '- %s\n' "$_p" + done </dev/null || true)" + if [[ "$origin_url" =~ github\.com[:/]([^/]+/[^/]+)(\.git)?$ ]]; then + local result="${BASH_REMATCH[1]}" + printf "%s" "${result%.git}" + fi +} + +# Fetch recent merged PR bodies as delimited blocks. +# Output: ---PR#number title---\nbody\n---PR_END--- per PR +dev_kit_learning_github_recent_pr_bodies() { + local repo_dir="${1:-$(pwd)}" + local sample_size="${2:-8}" + local owner_repo + owner_repo="$(dev_kit_learning_github_owner_repo "$repo_dir")" + [ -n "$owner_repo" ] || return 0 + dev_kit_sync_can_run_gh || return 0 + [ "$(dev_kit_sync_gh_auth_state)" = "available" ] || return 0 + + gh api "repos/${owner_repo}/pulls?state=closed&sort=updated&direction=desc&per_page=${sample_size}" \ + 2>/dev/null | jq -r ' + [.[]? | select(.merged_at != null and (.body // "" | length) > 30)] | + sort_by(.merged_at) | reverse | .[:8][] | + "---PR#\(.number) \(.title)---\n\(.body)\n---PR_END---" + ' 2>/dev/null || true +} + +# Detect common ## headings across PR bodies — returns headings found in 2+ PRs. +dev_kit_learning_github_pr_heading_pattern() { + local pr_bodies="$1" + [ -n "$pr_bodies" ] || return 0 + printf '%s\n' "$pr_bodies" | awk ' + /^---PR#/ { pr_idx++; in_pr=1; next } + /^---PR_END---/ { in_pr=0; next } + in_pr && /^##[[:space:]]/ { + heading = $0 + sub(/^##[[:space:]]+/, "", heading) + sub(/[[:space:]]+$/, "", heading) + if (heading != "" && !seen[pr_idx,heading]++) count[heading]++ + } + END { + for (h in count) { + if (count[h] >= 2) printf "%d|%s\n", count[h], h + } + } + ' | sort -t'|' -k1,1rn | cut -d'|' -f2 +} + +# Find the best-structured PR body (most headings) as a reference example. +# Output: PR number on line 1, body on remaining lines. +dev_kit_learning_github_best_pr_example() { + local pr_bodies="$1" + [ -n "$pr_bodies" ] || return 0 + printf '%s\n' "$pr_bodies" | awk ' + /^---PR#/ { + if (heading_count > best_count) { + best_count = heading_count + best_title = current_title + best_body = current_body + } + sub(/^---PR#/, "") + sub(/---$/, "") + current_title = $0 + current_body = "" + heading_count = 0 + in_pr = 1 + next + } + /^---PR_END---/ { + if (heading_count > best_count) { + best_count = heading_count + best_title = current_title + best_body = current_body + } + in_pr = 0 + next + } + in_pr { + current_body = current_body $0 "\n" + if ($0 ~ /^##[[:space:]]/) heading_count++ + } + END { + if (best_count > 0) { + print best_title + printf "%s", best_body + } + } + ' +} + +# Fetch recent issue comments by the authenticated user. +# Output: delimited comment blocks. +dev_kit_learning_github_recent_issue_comments() { + local repo_dir="${1:-$(pwd)}" + local sample_size="${2:-20}" + local owner_repo gh_user + owner_repo="$(dev_kit_learning_github_owner_repo "$repo_dir")" + [ -n "$owner_repo" ] || return 0 + dev_kit_sync_can_run_gh || return 0 + [ "$(dev_kit_sync_gh_auth_state)" = "available" ] || return 0 + + gh_user="$(gh api user --jq '.login' 2>/dev/null || true)" + [ -n "$gh_user" ] || return 0 + + gh api "repos/${owner_repo}/issues/comments?sort=created&direction=desc&per_page=${sample_size}" \ + 2>/dev/null | jq -r --arg user "$gh_user" ' + [.[]? | select(.user.login == $user and (.body | length) > 40)] | .[:8][] | + "---COMMENT_START---\n\(.body)\n---COMMENT_END---" + ' 2>/dev/null || true +} + +# Detect common patterns in issue comments — checklists, status headers, structured updates. +# Returns a short description of the detected pattern. +dev_kit_learning_github_issue_update_detect() { + local comments="$1" + [ -n "$comments" ] || return 0 + printf '%s\n' "$comments" | awk ' + /^---COMMENT_START---/ { comment_count++; in_c=1; has_checklist=0; has_heading=0; has_status=0; next } + /^---COMMENT_END---/ { + if (has_checklist) checklist_count++ + if (has_heading) heading_count++ + if (has_status) status_count++ + in_c=0; next + } + in_c && /^- \[[ x]\]/ { has_checklist=1 } + in_c && /^##[[:space:]]/ { has_heading=1 } + in_c && /[Ss]tatus:|[Uu]pdate:|[Pp]rogress:|[Dd]one:|[Nn]ext:/ { has_status=1 } + END { + if (comment_count == 0) exit + if (checklist_count >= 2) printf "checklist-driven updates (%d/%d comments use task checklists)\n", checklist_count, comment_count + if (heading_count >= 2) printf "structured sections (%d/%d comments use markdown headings)\n", heading_count, comment_count + if (status_count >= 2) printf "status/progress tracking (%d/%d comments include status labels)\n", status_count, comment_count + } + ' +} + +# Extract a good issue comment example (longest with structure). +dev_kit_learning_github_best_issue_comment() { + local comments="$1" + [ -n "$comments" ] || return 0 + printf '%s\n' "$comments" | awk ' + /^---COMMENT_START---/ { + if (length(current_body) > length(best_body) && current_structure > 0) { + best_body = current_body + } + current_body = "" + current_structure = 0 + in_c = 1 + next + } + /^---COMMENT_END---/ { + if (length(current_body) > length(best_body) && current_structure > 0) { + best_body = current_body + } + in_c = 0 + next + } + in_c { + current_body = current_body $0 "\n" + if ($0 ~ /^##[[:space:]]/ || $0 ~ /^- \[[ x]\]/ || $0 ~ /[Ss]tatus:|[Uu]pdate:/) current_structure++ + } + END { + if (best_body != "") printf "%s", best_body + } + ' +} + +# Extract lesson artifact workflow rules and templates for AGENTS.md injection. +dev_kit_learning_lesson_rules() { + local repo_dir="$1" + local lessons_dir="${repo_dir}/.rabbit/dev.kit" + [ -d "$lessons_dir" ] || return 0 + local latest + latest="$(find "$lessons_dir" -maxdepth 1 -type f -name 'lessons-*.md' 2>/dev/null | sort -r | head -1)" + [ -f "$latest" ] || return 0 + + awk ' + /^## Workflow rules/ { in_section=1; next } + /^## / && in_section { exit } + in_section && /^- / { + sub(/^- /, "") + print + } + ' "$latest" +} + +dev_kit_learning_lesson_templates() { + local repo_dir="$1" + local lessons_dir="${repo_dir}/.rabbit/dev.kit" + [ -d "$lessons_dir" ] || return 0 + local latest + latest="$(find "$lessons_dir" -maxdepth 1 -type f -name 'lessons-*.md' 2>/dev/null | sort -r | head -1)" + [ -f "$latest" ] || return 0 + + awk ' + /^## Ready templates/ { in_section=1; next } + /^## / && in_section { exit } + in_section && /^- / { + sub(/^- /, "") + print + } + ' "$latest" +} diff --git a/package.json b/package.json index 84d277b..4ce8770 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@udx/dev-kit", - "version": "0.6.0", + "version": "0.7.0", "description": "Context-driven engineering toolkit for AI agents and developers", "license": "MIT", "repository": { From d0996a4fd03b5559b699853f7e913079da4e62ff Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Thu, 16 Apr 2026 17:57:19 +0300 Subject: [PATCH 02/11] address Copilot review: fix sample_size, header provenance, body truncation - Pass sample_size through to jq instead of hard-coded .[:8] slice - Update AGENTS.md header to reflect all three sources - Cap best-example bodies at 60 lines to limit exposure Co-Authored-By: Claude Opus 4.6 (1M context) --- lib/commands/agent.sh | 2 +- lib/modules/learning_sources.sh | 18 ++++++++++++------ 2 files changed, 13 insertions(+), 7 deletions(-) diff --git a/lib/commands/agent.sh b/lib/commands/agent.sh index cfa5a90..2124518 100644 --- a/lib/commands/agent.sh +++ b/lib/commands/agent.sh @@ -93,7 +93,7 @@ dev_kit_agent_write_agents_md() { { printf '# AGENTS.md\n\n' - printf '_Auto-generated by `dev.kit agent`. Source of truth: `.rabbit/context.yaml`._\n\n' + printf '_Auto-generated by `dev.kit agent`. Sources: `.rabbit/context.yaml`, lesson artifacts, GitHub history._\n\n' if [ ! -f "$context_yaml" ]; then printf 'Run `dev.kit repo` to generate context.\n' diff --git a/lib/modules/learning_sources.sh b/lib/modules/learning_sources.sh index 20efcd9..0bfe6a0 100644 --- a/lib/modules/learning_sources.sh +++ b/lib/modules/learning_sources.sh @@ -859,9 +859,9 @@ dev_kit_learning_github_recent_pr_bodies() { [ "$(dev_kit_sync_gh_auth_state)" = "available" ] || return 0 gh api "repos/${owner_repo}/pulls?state=closed&sort=updated&direction=desc&per_page=${sample_size}" \ - 2>/dev/null | jq -r ' + 2>/dev/null | jq -r --argjson n "$sample_size" ' [.[]? | select(.merged_at != null and (.body // "" | length) > 30)] | - sort_by(.merged_at) | reverse | .[:8][] | + sort_by(.merged_at) | reverse | .[:$n][] | "---PR#\(.number) \(.title)---\n\(.body)\n---PR_END---" ' 2>/dev/null || true } @@ -923,7 +923,9 @@ dev_kit_learning_github_best_pr_example() { END { if (best_count > 0) { print best_title - printf "%s", best_body + n = split(best_body, lines, "\n") + limit = (n < 60) ? n : 60 + for (i = 1; i <= limit; i++) printf "%s\n", lines[i] } } ' @@ -944,8 +946,8 @@ dev_kit_learning_github_recent_issue_comments() { [ -n "$gh_user" ] || return 0 gh api "repos/${owner_repo}/issues/comments?sort=created&direction=desc&per_page=${sample_size}" \ - 2>/dev/null | jq -r --arg user "$gh_user" ' - [.[]? | select(.user.login == $user and (.body | length) > 40)] | .[:8][] | + 2>/dev/null | jq -r --arg user "$gh_user" --argjson n "$sample_size" ' + [.[]? | select(.user.login == $user and (.body | length) > 40)] | .[:$n][] | "---COMMENT_START---\n\(.body)\n---COMMENT_END---" ' 2>/dev/null || true } @@ -1001,7 +1003,11 @@ dev_kit_learning_github_best_issue_comment() { if ($0 ~ /^##[[:space:]]/ || $0 ~ /^- \[[ x]\]/ || $0 ~ /[Ss]tatus:|[Uu]pdate:/) current_structure++ } END { - if (best_body != "") printf "%s", best_body + if (best_body != "") { + n = split(best_body, lines, "\n") + limit = (n < 60) ? n : 60 + for (i = 1; i <= limit; i++) printf "%s\n", lines[i] + } } ' } From d730be59bc63c4a92745607c509c65f9b4fbcde6 Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Thu, 16 Apr 2026 20:15:26 +0300 Subject: [PATCH 03/11] fix installer cleanup between npm and curl installs --- bin/scripts/install.sh | 54 ++++++++++++++++++++++++++++++++-- bin/scripts/npm-postinstall.sh | 44 +++++++++++++++++++++++++++ package.json | 3 ++ tests/suite.sh | 30 ++++++++++++++++++- 4 files changed, 128 insertions(+), 3 deletions(-) create mode 100755 bin/scripts/npm-postinstall.sh diff --git a/bin/scripts/install.sh b/bin/scripts/install.sh index efa27b0..e96d05c 100755 --- a/bin/scripts/install.sh +++ b/bin/scripts/install.sh @@ -6,7 +6,29 @@ DEV_KIT_HOME="${DEV_KIT_HOME:-$HOME/.udx/dev.kit}" DEV_KIT_INSTALL_REPO="${DEV_KIT_INSTALL_REPO:-udx/dev.kit}" DEV_KIT_INSTALL_REF="${DEV_KIT_INSTALL_REF:-latest}" DEV_KIT_INSTALL_ARCHIVE_URL="${DEV_KIT_INSTALL_ARCHIVE_URL:-https://codeload.github.com/${DEV_KIT_INSTALL_REPO}/tar.gz/refs/heads/${DEV_KIT_INSTALL_REF}}" -DEV_KIT_INSTALL_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +dev_kit_install_script_path() { + if [ -n "${BASH_SOURCE[0]-}" ]; then + printf '%s\n' "${BASH_SOURCE[0]}" + return 0 + fi + + if [ "${0:-}" != "bash" ] && [ "${0:-}" != "-bash" ] && [ -n "${0:-}" ]; then + printf '%s\n' "$0" + return 0 + fi + + return 1 +} + +dev_kit_install_script_dir() { + local script_path="" + + script_path="$(dev_kit_install_script_path)" || return 1 + cd "$(dirname "$script_path")" && pwd +} + +DEV_KIT_INSTALL_SCRIPT_DIR="$(dev_kit_install_script_dir 2>/dev/null || true)" DEV_KIT_INSTALL_REPO_DIR="$(cd "${DEV_KIT_INSTALL_SCRIPT_DIR}/../.." 2>/dev/null && pwd || true)" if [ -f "$DEV_KIT_INSTALL_REPO_DIR/lib/modules/output.sh" ]; then @@ -26,7 +48,7 @@ dev_kit_install_repo_dir() { local script_dir="" local repo_dir="" - script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + script_dir="$(dev_kit_install_script_dir)" || return 1 repo_dir="$(cd "${script_dir}/../.." 2>/dev/null && pwd || true)" if [ -n "$repo_dir" ] && [ -f "$repo_dir/bin/dev-kit" ] && [ -d "$repo_dir/lib" ] && [ -d "$repo_dir/src" ]; then @@ -55,6 +77,32 @@ dev_kit_install_download() { exit 1 } +dev_kit_install_remove_npm_install() { + if ! command -v npm >/dev/null 2>&1; then + return 0 + fi + + if ! npm list -g @udx/dev-kit --depth=0 >/dev/null 2>&1; then + return 0 + fi + + echo "" + echo "dev.kit: detected previous npm installation" + echo " package: @udx/dev-kit" + + if npm uninstall -g @udx/dev-kit >/dev/null 2>&1; then + echo "" + echo " removed — curl version is now the single install" + echo "" + return 0 + fi + + echo "" + echo " warning: failed to remove npm installation automatically" + echo "" + return 0 +} + dev_kit_install_extract_root() { local archive_file="$1" local extract_dir="$2" @@ -111,6 +159,8 @@ main() { exit 1 fi + dev_kit_install_remove_npm_install + source_dir="$(dev_kit_install_source_dir)" target="${DEV_KIT_BIN_DIR}/dev.kit" diff --git a/bin/scripts/npm-postinstall.sh b/bin/scripts/npm-postinstall.sh new file mode 100755 index 0000000..2fa2033 --- /dev/null +++ b/bin/scripts/npm-postinstall.sh @@ -0,0 +1,44 @@ +#!/usr/bin/env bash +# npm postinstall: detect and remove curl-based dev.kit installation. +# Runs silently when no curl install is found. Never fails the npm install. + +curl_home="${DEV_KIT_HOME:-$HOME/.udx/dev.kit}" +curl_bin="${DEV_KIT_BIN_DIR:-$HOME/.local/bin}/dev.kit" + +# Nothing to do if neither artifact exists. +[ -d "$curl_home" ] || [ -e "$curl_bin" ] || [ -L "$curl_bin" ] || exit 0 + +# If the symlink exists, verify it points to the curl install home. +# If it points elsewhere (local clone, another tool), leave it alone. +if [ -L "$curl_bin" ]; then + link_target="$(readlink "$curl_bin" 2>/dev/null || true)" + case "$link_target" in + "$curl_home"/*) ;; + *) exit 0 ;; + esac +fi + +echo "" +echo "dev.kit: detected previous curl-based installation" +[ -d "$curl_home" ] && echo " home: $curl_home" +[ -e "$curl_bin" ] || [ -L "$curl_bin" ] && echo " binary: $curl_bin" + +# Remove the binary symlink / file. +if [ -L "$curl_bin" ] || [ -f "$curl_bin" ]; then + rm -f "$curl_bin" 2>/dev/null || true +fi + +# Remove the curl install home directory. +if [ -d "$curl_home" ]; then + rm -rf "$curl_home" 2>/dev/null || true +fi + +# Clean up empty parent dirs left behind. +curl_bin_dir="$(dirname "$curl_bin" 2>/dev/null || true)" +if [ -n "$curl_bin_dir" ] && [ -d "$curl_bin_dir" ] && [ -z "$(ls -A "$curl_bin_dir" 2>/dev/null)" ]; then + rmdir "$curl_bin_dir" 2>/dev/null || true +fi + +echo "" +echo " removed — npm version is now the single install" +echo "" diff --git a/package.json b/package.json index 4ce8770..8cf65bf 100644 --- a/package.json +++ b/package.json @@ -9,6 +9,9 @@ }, "homepage": "https://github.com/udx/dev.kit", "bugs": "https://github.com/udx/dev.kit/issues", + "scripts": { + "postinstall": "bash bin/scripts/npm-postinstall.sh || true" + }, "bin": { "dev.kit": "bin/dev-kit", "dev-kit": "bin/dev-kit" diff --git a/tests/suite.sh b/tests/suite.sh index 3215c74..fc76421 100644 --- a/tests/suite.sh +++ b/tests/suite.sh @@ -245,24 +245,52 @@ fi if should_run "install" && [ -n "${CI:-}" ]; then INSTALLER_COPY="$TEST_HOME/install.sh" ARCHIVE_FILE="$TEST_HOME/dev-kit-main.tar.gz" + FAKE_BIN_DIR="$TEST_HOME/fake-bin" + FAKE_NPM_LOG="$TEST_HOME/fake-npm.log" cp "$REPO_DIR/bin/scripts/install.sh" "$INSTALLER_COPY" tar -czf "$ARCHIVE_FILE" --exclude=".git" --exclude="node_modules" --exclude="vendor" \ -C "$(dirname "$REPO_DIR")" "$(basename "$REPO_DIR")" + mkdir -p "$FAKE_BIN_DIR" + cat > "$FAKE_BIN_DIR/npm" <> "$FAKE_NPM_LOG" +if [ "\${1:-}" = "list" ] && [ "\${2:-}" = "-g" ] && [ "\${3:-}" = "@udx/dev-kit" ] && [ "\${4:-}" = "--depth=0" ]; then + exit 0 +fi +if [ "\${1:-}" = "uninstall" ] && [ "\${2:-}" = "-g" ] && [ "\${3:-}" = "@udx/dev-kit" ]; then + exit 0 +fi +exit 1 +EOF + chmod +x "$FAKE_BIN_DIR/npm" unset DEV_KIT_HOME DEV_KIT_BIN_DIR - INSTALL_OUTPUT="$(DEV_KIT_INSTALL_ARCHIVE_URL="file://$ARCHIVE_FILE" HOME="$TEST_HOME" bash "$INSTALLER_COPY")" + INSTALL_OUTPUT="$(PATH="$FAKE_BIN_DIR:$PATH" DEV_KIT_INSTALL_ARCHIVE_URL="file://$ARCHIVE_FILE" HOME="$TEST_HOME" bash "$INSTALLER_COPY")" DEV_KIT_HOME="$TEST_HOME/.udx/dev.kit" DEV_KIT_BIN_DIR="$TEST_HOME/.local/bin" + assert_contains "$INSTALL_OUTPUT" "detected previous npm installation" "install: detects npm install" + assert_contains "$INSTALL_OUTPUT" "curl version is now the single install" "install: removes npm install" assert_contains "$INSTALL_OUTPUT" "Installed dev.kit" "install: reports success" assert_file_exists "$DEV_KIT_HOME/bin/dev-kit" "install: command binary present" assert_file_exists "$DEV_KIT_HOME/lib/commands/repo.sh" "install: repo command present" assert_symlink_target "$DEV_KIT_BIN_DIR/dev.kit" "$DEV_KIT_HOME/bin/dev-kit" "install: global symlink correct" + assert_contains "$(cat "$FAKE_NPM_LOG")" "list -g @udx/dev-kit --depth=0" "install: checks npm install" + assert_contains "$(cat "$FAKE_NPM_LOG")" "uninstall -g @udx/dev-kit" "install: uninstalls npm package" UNINSTALL_OUTPUT="$(HOME="$TEST_HOME" "$DEV_KIT_HOME/bin/dev-kit" uninstall --yes)" assert_contains "$UNINSTALL_OUTPUT" "Removed dev.kit" "uninstall: reports removal" assert_file_missing "$DEV_KIT_BIN_DIR/dev.kit" "uninstall: removes symlink" assert_file_missing "$DEV_KIT_HOME" "uninstall: removes home" + + : > "$FAKE_NPM_LOG" + INSTALL_OUTPUT_STDIN="$(PATH="$FAKE_BIN_DIR:$PATH" DEV_KIT_INSTALL_ARCHIVE_URL="file://$ARCHIVE_FILE" HOME="$TEST_HOME" bash < "$INSTALLER_COPY")" + assert_contains "$INSTALL_OUTPUT_STDIN" "detected previous npm installation" "install stdin: detects npm install" + assert_contains "$INSTALL_OUTPUT_STDIN" "Installed dev.kit" "install stdin: reports success" + assert_file_exists "$DEV_KIT_HOME/bin/dev-kit" "install stdin: command binary present" + assert_symlink_target "$DEV_KIT_BIN_DIR/dev.kit" "$DEV_KIT_HOME/bin/dev-kit" "install stdin: global symlink correct" + assert_contains "$(cat "$FAKE_NPM_LOG")" "uninstall -g @udx/dev-kit" "install stdin: uninstalls npm package" elif should_run "install"; then pass "install group skipped outside CI (run with CI=1 to enable)" fi From 81a0e7c7da6e42b1da7861f0fd234e97c7c8fb05 Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Thu, 16 Apr 2026 20:15:33 +0300 Subject: [PATCH 04/11] docs clarify context and agent contract --- .rabbit/context.yaml | 24 ++-- .rabbit/dev.kit/lessons-dev.kit-2026-04-15.md | 85 +++++++++++++ AGENTS.md | 56 +++++--- README.md | 29 +++-- docs/agents.md | 120 ++++++++++++++++++ docs/architecture.md | 110 ---------------- docs/commands.md | 93 -------------- docs/context.md | 113 +++++++++++++++++ docs/detection-facets.md | 53 -------- docs/installation.md | 94 ++++++++++++++ docs/integration.md | 102 +++++++++++++++ docs/overview.md | 63 --------- docs/workflow.md | 102 --------------- src/configs/context-config.yaml | 10 +- src/configs/repo-scaffold.yaml | 3 +- 15 files changed, 588 insertions(+), 469 deletions(-) create mode 100644 .rabbit/dev.kit/lessons-dev.kit-2026-04-15.md create mode 100644 docs/agents.md delete mode 100644 docs/architecture.md delete mode 100644 docs/commands.md create mode 100644 docs/context.md delete mode 100644 docs/detection-facets.md create mode 100644 docs/installation.md create mode 100644 docs/integration.md delete mode 100644 docs/overview.md delete mode 100644 docs/workflow.md diff --git a/.rabbit/context.yaml b/.rabbit/context.yaml index 81debcc..07185f4 100644 --- a/.rabbit/context.yaml +++ b/.rabbit/context.yaml @@ -2,7 +2,7 @@ # Run `dev.kit repo` to refresh. kind: repoContext version: udx.io/dev.kit/v1 -generated: 2026-04-15 +generated: 2026-04-16 repo: name: dev.kit @@ -11,7 +11,10 @@ repo: refs: - ./README.md - - ./docs/architecture.md + - ./docs/installation.md + - ./docs/context.md + - ./docs/agents.md + - ./docs/integration.md - ./docs - ./.rabbit - ./.github/workflows @@ -21,24 +24,14 @@ refs: - ./lib - ./src - ./tests + - https://raw.githubusercontent.com/udx/dev.kit/latest/.github/ISSUE_TEMPLATE + - https://raw.githubusercontent.com/udx/dev.kit/latest/.github/PULL_REQUEST_TEMPLATE.md commands: verify: make test build: make build run: make run -# GitHub context — development signals from repo history -github: - repo: udx/dev.kit - recent_prs: - - "#16 restructure AGENTS.md as execution contract, add GitHub context" - - "#15 bump version to 0.2.1" - - "#14 fix release workflow trigger" - - "#13 add package-lock.json for CI cache" - - "#12 add npm release workflow, versioning, and changelog" - open_prs: - - "#17 slim factors, widen tracing, bump to 0.5.0" - # Gaps — factors that are missing or partial gaps: - config (partial) @@ -62,6 +55,7 @@ practices: - "Run the smallest local check that proves the current change. Defer heavyweight coverage to CI and call that tradeoff out explicitly." - "Make sure to develop and test incrementally, so it is easier to detect problems early and build on verified behavior." - "Make sure to protect development executions with scoped and limited tasks, so failures are easier to isolate and blast radius stays low." + - "Use the linked GitHub issue as the cross-repo context root. When work spans multiple repos, the issue URL anchors scope, acceptance criteria, and follow-up across all of them." # Canonical agent workflow workflow: @@ -90,7 +84,6 @@ dependencies: resolved: true archetype: workflow-repo profile: unknown - description: Reusable GitHub Actions workflow templates for CI/CD used_by: - .github/workflows/context7-ops.yml - .github/workflows/npm-release-ops.yml @@ -117,5 +110,6 @@ manifests: # Lessons from agent sessions lessons: + - .rabbit/dev.kit/lessons-dev.kit-2026-04-15.md - .rabbit/dev.kit/lessons-dev.kit-2026-04-14.md diff --git a/.rabbit/dev.kit/lessons-dev.kit-2026-04-15.md b/.rabbit/dev.kit/lessons-dev.kit-2026-04-15.md new file mode 100644 index 0000000..ee8fd3e --- /dev/null +++ b/.rabbit/dev.kit/lessons-dev.kit-2026-04-15.md @@ -0,0 +1,85 @@ +# Lessons — dev.kit — 2026-04-15 + +Sources: claude (1 session(s)), codex (0 session(s)) + +## Workflow rules + +- Verify the build or runtime locally before running deploy-oriented workflow assets or reporting the change as complete. +- Use repo workflow assets like deploy.yml, workflow files, and repo docs as the execution contract instead of inventing an ad hoc deploy path. +- Keep the delivery chain explicit: create or sync the branch, prepare the PR, and connect the related GitHub issue before close-out. +- Report outcomes with exact URLs, versions, findings deltas, and next steps so the follow-up can be reused by humans and agents without drift. +- Use README, docs, and tests as the first alignment surface before broad refactors so the implementation stays anchored to an explicit workflow. +- Keep local verification targeted and lightweight during iteration, then move broader or slower validation into GitHub Actions or other CI gates. +- Treat cleanup of legacy modules, configs, and leftovers as part of the feature work so the repo keeps converging on the new operating model. +- Prefer reusable YAML/manifests plus small shell wrappers over embedding policy directly into imperative scripts. +- Package agent context from repo artifacts and manifests so the workflow stays repo-centric and does not depend on ad hoc prompt memory. +- Express repo rules in YAML/manifests first, then keep shell glue thin and composable. +- Refresh repo context and AGENTS.md from repo artifacts before deeper agent work so the workflow stays repo-centric. + +## Operational references + +- https://github.com/icamiami/icamiami.org/issues/1897 +- https://github.com/test/repo/issues/42 +- https://github.com/org/repo/issues/42 +- https://github.com/udx/next.reddoorcompany.com/issues/1292 +- https://github.com/udx/next.reddoorcompany.com/issues/1250 +- https://github.com/icamiami/icamiami.org/issues/1895 +- https://github.com/udx/next.reddoorcompany.com/issues/1299 +- https://github.com/udx/worker-tooling/pull/57 +- https://github.com/udx/dev.kit/pull/10 +- https://github.com/udx/dev.kit/pull/11 +- https://github.com/org/repo/pull/15 +- https://github.com/test/repo/pull/5 +- https://github.com/udx/next.reddoorcompany.com/pull/1298 +- https://github.com/icamiami/gala-2024.icamiami.org/pull/6 +- https://github.com/udx/rabbit-automation-action/pull/231 +- https://github.com/udx/next.reddoorcompany.com/pull/1301 +- https://github.com/udx/api.encerp.com/pull/197 +- https://github.com/test/repo/pull/9 +- https://github.com/udx/worker-engine/pull/83 +- https://github.com/udx/reusable-workflows/pull/32 +- https://github.com/udx/azure-apim-backup/issues/81 +- https://github.com/icamiami/gala-2026.icamiami.org/issues/38 +- https://github.com/udx/dev.kit/pull/11#discussion_r3080697741 +- https://github.com/udx/dev.kit/pull/11#discussion_r3080697958 +- https://github.com/udx/dev.kit/pull/11#discussion_r3080698102 +- https://github.com/udx/dev.kit/pull/11#discussion_r3080698254 +- https://github.com/udx/dev.kit/pull/12 +- https://github.com/udx/dev.kit/pull/13 +- https://github.com/udx/dev.kit/pull/14 +- https://github.com/udx/dev.kit/pull/15 +- https://github.com/icamiami/gala-2026.icamiami.org/pull/86 +- https://github.com/udx/dev.kit/pull/16 +- https://github.com/udx/cms.reddoorcompany.com/issues/206 +- https://github.com/udx/dev.kit/pull/17 +- https://github.com/udx/dev.kit/pull/18 + +## Ready templates + +- `Issue-to-scope`: start from the linked issue, confirm repo/workspace match, and restate the exact scope before changing code. +- `Workflow tracing`: locate the actual workflow file or deploy source first, then trace the commands and supporting docs that really drive execution. +- `Verify-before-sync`: run the relevant local build/test check before syncing, reporting completion, or preparing the PR. +- `Delivery chain`: sync the branch, prepare the PR in repo style, and connect the related issue before close-out. +- `Post-merge follow-up`: gather release/workflow evidence and post a concise update with links, findings delta, and next steps. +- `Docs-first cleanup loop`: review README/docs/tests, restate the target workflow, then simplify code and remove mismatched legacy paths in the same pass. +- `Verification scope`: run the smallest local check that proves the current change, defer heavyweight smoke coverage to CI, and call that tradeoff out explicitly. +- `Legacy reduction`: when a new direction is accepted, archive or delete conflicting old modules/configs instead of carrying both models forward. +- `Config-over-code`: express repo rules in YAML/manifests first, then keep shell glue thin and composable. +- `Agent handoff`: refresh repo context, manifest, and AGENTS instructions before deeper agent work so the repo contract is the source of truth. +- docs-first-alignment +- workflow-tracing +- verification-scope +- legacy-reduction +- agent-handoff + +## Evidence highlights + +- [claude] I'm planning refactoring/re-thinking my dev.kit tool, please explore it, get familiar and validate againts my new plan [Pasted text #1 +69 lines] +- [claude] ok, let's start phase 1, break into smaller iterations if make sense, I would probably start by readme/docs, tests and basic scripts end goal is to have smart and flexible development workflow that helps improve local env, repo(s), and provide context for claud agent so no engineering drift happening and development... +- [claude] before running test we need to ensure perfomance and make sure it's not running too long, also, I see you haven't updated Readme fully, let's loop once again readme/docs, tests feel free to cleanup/consolidate/whatever, it's a first version so nobody using it so no back-compability needed +- [claude] when I said about perfomance I particularly meant tests +- [claude] so, do we understand "happy path" for refactor to new concept? [Pasted text #1 +69 lines] +- [claude] [Pasted text #1 +131 lines] +- [claude] make sure to explore lessons and overall flow, I want - dev.kit - dev.kit repo (generate repo context + experienced knowledge and dev workflow(s)) - dev.kit agent (generate correct flexible agent instructions based on context) - dev.kit learn (generate analyzed agents sessions) use learned lessons to improve dev.kit... +- [claude] before make changes would be useful to sync uncommited to git + diff --git a/AGENTS.md b/AGENTS.md index 2e3fbcf..7017053 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md -_Auto-generated by `dev.kit agent`. Source of truth: `.rabbit/context.yaml`._ +_Auto-generated by `dev.kit agent`. Sources: `.rabbit/context.yaml`, lesson artifacts, GitHub history._ ## Contract @@ -71,26 +71,10 @@ YAML definitions are first-class interfaces. They control repo behavior — trac Cross-repo and upstream references. Same-org repos are resolved with metadata. Trace these for infrastructure, deployment, and build logic. -- **udx/reusable-workflows** (reusable workflow) — workflow-repo — Reusable GitHub Actions workflow templates for CI/CD +- **udx/reusable-workflows** (reusable workflow) — workflow-repo - `.github/workflows/context7-ops.yml` - `.github/workflows/npm-release-ops.yml` -### GitHub context - -Development signals from [udx/dev.kit](https://github.com/udx/dev.kit). - -**Open PRs:** - - - #17 slim factors, widen tracing, bump to 0.5.0 - -**Recent PRs:** - - - #16 restructure AGENTS.md as execution contract, add GitHub context - - #15 bump version to 0.2.1 - - #14 fix release workflow trigger - - #13 add package-lock.json for CI cache - - #12 add npm release workflow, versioning, and changelog - ### Gaps Incomplete factors. Address within the workflow, not as separate tasks. @@ -105,6 +89,7 @@ Incomplete factors. Address within the workflow, not as separate tasks. Prior session lessons — read before starting work: + - .rabbit/dev.kit/lessons-dev.kit-2026-04-15.md - .rabbit/dev.kit/lessons-dev.kit-2026-04-14.md ## Workflow @@ -127,6 +112,40 @@ The dev.kit lifecycle: **repo → agent → work → PR → merge**. Follow thes - Post close-out comment on linked issue: After PR is created, post a brief comment on the linked issue with the PR URL, what changed, and any follow-up items. GitHub auto-closes the issue on merge when "Closes #N" is in the PR body — do not close manually. - Post-merge close-out and backlog: After merge: verify issue auto-closed, post close-out comment, open issues for any backlog items from the PR, verify monitoring changes are live. See post_merge steps in github-prs.yaml. +### Learned from prior sessions + +Patterns detected from agent sessions on this repo. Follow these in addition to the workflow above. + +- Verify the build or runtime locally before running deploy-oriented workflow assets or reporting the change as complete. +- Use repo workflow assets like deploy.yml, workflow files, and repo docs as the execution contract instead of inventing an ad hoc deploy path. +- Keep the delivery chain explicit: create or sync the branch, prepare the PR, and connect the related GitHub issue before close-out. +- Report outcomes with exact URLs, versions, findings deltas, and next steps so the follow-up can be reused by humans and agents without drift. +- Use README, docs, and tests as the first alignment surface before broad refactors so the implementation stays anchored to an explicit workflow. +- Keep local verification targeted and lightweight during iteration, then move broader or slower validation into GitHub Actions or other CI gates. +- Treat cleanup of legacy modules, configs, and leftovers as part of the feature work so the repo keeps converging on the new operating model. +- Prefer reusable YAML/manifests plus small shell wrappers over embedding policy directly into imperative scripts. +- Package agent context from repo artifacts and manifests so the workflow stays repo-centric and does not depend on ad hoc prompt memory. +- Express repo rules in YAML/manifests first, then keep shell glue thin and composable. +- Refresh repo context and AGENTS.md from repo artifacts before deeper agent work so the workflow stays repo-centric. + +**Reusable templates:** + +- `Issue-to-scope`: start from the linked issue, confirm repo/workspace match, and restate the exact scope before changing code. +- `Workflow tracing`: locate the actual workflow file or deploy source first, then trace the commands and supporting docs that really drive execution. +- `Verify-before-sync`: run the relevant local build/test check before syncing, reporting completion, or preparing the PR. +- `Delivery chain`: sync the branch, prepare the PR in repo style, and connect the related issue before close-out. +- `Post-merge follow-up`: gather release/workflow evidence and post a concise update with links, findings delta, and next steps. +- `Docs-first cleanup loop`: review README/docs/tests, restate the target workflow, then simplify code and remove mismatched legacy paths in the same pass. +- `Verification scope`: run the smallest local check that proves the current change, defer heavyweight smoke coverage to CI, and call that tradeoff out explicitly. +- `Legacy reduction`: when a new direction is accepted, archive or delete conflicting old modules/configs instead of carrying both models forward. +- `Config-over-code`: express repo rules in YAML/manifests first, then keep shell glue thin and composable. +- `Agent handoff`: refresh repo context, manifest, and AGENTS instructions before deeper agent work so the repo contract is the source of truth. +- docs-first-alignment +- workflow-tracing +- verification-scope +- legacy-reduction +- agent-handoff + ## Engineering practices - Keep the repository as the primary source of truth so context-driven engineering comes from repo contracts, docs, tests, config, and repo-native notes instead of agent memory. @@ -146,4 +165,5 @@ The dev.kit lifecycle: **repo → agent → work → PR → merge**. Follow thes - Run the smallest local check that proves the current change. Defer heavyweight coverage to CI and call that tradeoff out explicitly. - Make sure to develop and test incrementally, so it is easier to detect problems early and build on verified behavior. - Make sure to protect development executions with scoped and limited tasks, so failures are easier to isolate and blast radius stays low. + - Use the linked GitHub issue as the cross-repo context root. When work spans multiple repos, the issue URL anchors scope, acceptance criteria, and follow-up across all of them. diff --git a/README.md b/README.md index b449980..9cf4a69 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ -**Dynamic repo context for developers and AI agents.** +**Simple session flow for developers and AI agents.** -dev.kit scans what humans and agents shouldn't scan manually — tools, factors, dependencies, cross-repo relationships. It produces one context file. Developers read it. Agents execute from it. +dev.kit separates repo facts from agent behavior. It generates `.rabbit/context.yaml` as the structured repo contract, then generates `AGENTS.md` as the execution contract that tells agents how to use that context plus workflow, GitHub, and learning signals. ```bash npm install -g @udx/dev-kit @@ -22,7 +22,7 @@ detect archetype trace dependencies write execution contract guide to next write context.yaml from context.yaml ``` -Each command enriches context and guides to the next. Run at every session start. +Each command moves the session forward and tells the next actor what to do. Agents should rerun the flow at each new interaction or session so context, workflow, and repo state stay synced. --- @@ -37,9 +37,9 @@ dev.kit agent # generate AGENTS.md execution contract --- -## What gets generated +## Generated Context And Workflow -**`.rabbit/context.yaml`** — one file, complete repo context: +**`.rabbit/context.yaml`** — generated repo map from repo definitions, source files, detected commands, traced dependencies, gaps, and other serializable repo signals: ```yaml repo: @@ -49,7 +49,6 @@ repo: refs: - ./README.md - - ./docs/architecture.md - ./package.json commands: @@ -68,7 +67,7 @@ gaps: - config (partial) ``` -**`AGENTS.md`** — execution contract with 8 rules, commands, refs, dependencies, workflow, practices. Works with Claude, Codex, Gemini, Copilot — any agent that reads files. +**`AGENTS.md`** — generated execution contract for agents. It tells them how to start, what to read first, how to use `context.yaml`, how to verify work, and how to follow repo workflow using current GitHub and learned context without relying on stale session memory. --- @@ -86,6 +85,10 @@ All commands support `--json` for machine-readable output. --- +## Repo Context + +Repo context comes from repo source first: README, docs, workflows, manifests, tests, and other declared refs. That data is serialized into `context.yaml`. `AGENTS.md` then turns that repo map into an operating contract for agents, using workflow guidance, GitHub context, and lessons where available. + ## Cross-repo tracing Traces dependencies from 6 sources: workflow reuse, GitHub actions, Docker images, versioned YAML, GitHub URLs, npm packages. @@ -113,15 +116,17 @@ dependencies: # npm (recommended) npm install -g @udx/dev-kit -# or curl +# no npm? curl -fsSL https://raw.githubusercontent.com/udx/dev.kit/latest/bin/scripts/install.sh | bash ``` +Use one install path at a time. Installing with npm removes the curl-managed `~/.udx/dev.kit` home and shim. Installing with curl removes the global `@udx/dev-kit` package before laying down the local shim and home directory. + --- ## Docs -- [Overview](docs/overview.md) — design principles and phases -- [Commands](docs/commands.md) — full command reference with output details -- [Workflow](docs/workflow.md) — pipeline phases, factors, session flow -- [Architecture](docs/architecture.md) — config catalog, module map, data flow +- [Installation](docs/installation.md) — npm and curl installs, cleanup, uninstall, and verification +- [Context](docs/context.md) — `.rabbit/context.yaml`, its sections, and how it is generated +- [Agents](docs/agents.md) — `AGENTS.md` generation and how agents use it +- [Integration](docs/integration.md) — how the CLI, repo context, and agent workflow fit together diff --git a/docs/agents.md b/docs/agents.md new file mode 100644 index 0000000..e0338bb --- /dev/null +++ b/docs/agents.md @@ -0,0 +1,120 @@ +# Agents + +`dev.kit agent` turns repo context into agent instructions. + +Its main output is `AGENTS.md`, generated from `.rabbit/context.yaml` plus the repo's workflow, practice, and learning inputs. + +## Role + +If `context.yaml` answers what is known, `AGENTS.md` answers how an agent should operate. + +This is the behavior layer. It tells an agent how to use the fetched repo contract efficiently and with minimal drift. + +One core rule should stay explicit: start each new interaction or session by rerunning: + +```bash +dev.kit +dev.kit repo +dev.kit agent +``` + +That keeps repo context, workflow expectations, and generated instructions in sync before deeper work. + +## What It Generates + +Run: + +```bash +dev.kit agent +``` + +This writes `AGENTS.md`. If `.rabbit/context.yaml` does not exist yet, `dev.kit agent` generates context first. + +## Why `AGENTS.md` Exists + +Raw repo facts are not enough. Agents still need explicit operating instructions for how to read, decide, verify, and hand work off. + +`AGENTS.md` exists to define: + +- session-start and interaction-start behavior +- context boundaries +- what to read first +- how to prioritize manifests over implementation +- how to follow the repo workflow +- how to verify before reporting completion +- how to use repo history, lessons, and GitHub context without drifting + +## Inputs + +`AGENTS.md` is generated from repo evidence, not handwritten prompt text: + +- `.rabbit/context.yaml` +- YAML workflow and practice catalogs in `src/configs/` +- GitHub repo context when available +- lessons from prior agent sessions + +That keeps the instructions grounded and refreshable. + +## Main Sections + +The generated contract typically includes: + +- rules +- repo commands +- priority refs +- config manifests +- external dependencies +- GitHub context +- workflow steps +- learned practices + +## What Belongs Here + +`AGENTS.md` is where dynamic execution guidance belongs. + +That includes: + +- how an agent should start each session +- how an agent should interpret repo context +- how an agent should use GitHub issues, PRs, and recent history +- how an agent should sequence work and verification +- how an agent should avoid scanning and guesswork + +This is the layer that combines static repo contract with current repo experience. + +## Relationship To `.rabbit/context.yaml` + +`.rabbit/context.yaml` is the structured repo map. + +`AGENTS.md` is the agent-facing execution contract built on top of that map. + +A useful shorthand is: + +- `context.yaml` = fetched and serialized repo knowledge +- `AGENTS.md` = instructions for using that knowledge well + +They should stay separate, but tightly coupled. + +## Efficiency Goal + +The best result is a short path from repo state to grounded agent action: + +1. `context.yaml` tells the agent what exists and what was detected. +2. `AGENTS.md` tells the agent how to act on that information. +3. The agent spends less time rediscovering the repo and more time doing scoped work. + +## JSON Surface + +For machine-readable agent integration, use: + +```bash +dev.kit agent --json +``` + +The JSON template for that surface is: + +- `src/templates/agent.json` + +## Provider-Agnostic + +`AGENTS.md` is not tied to one model or tool. The goal is a repo-native execution contract that can guide Codex, Claude, Gemini, Copilot, or other agents without rewriting the repo’s expectations for each provider. diff --git a/docs/architecture.md b/docs/architecture.md deleted file mode 100644 index 5882d94..0000000 --- a/docs/architecture.md +++ /dev/null @@ -1,110 +0,0 @@ -# Architecture - -## Config Catalog - -The `src/configs/` directory is the knowledge library that drives all detection, classification, and output. Shell modules read from it — they never hardcode the same values. This makes the detection layer extensible without changing CLI code. - -| File | Kind | Role | -|---|---|---| -| `context-config.yaml` | contextConfig | Root file/dir markers and priority reference paths | -| `detection-signals.yaml` | detectionSignals | File globs, dir lists, architecture thresholds | -| `detection-patterns.yaml` | detectionPatterns | Regex patterns for verification, build, run, env vars | -| `archetype-signals.yaml` | archetypeSignals | File/dir signals per archetype (wordpress, kubernetes, …) | -| `archetype-rules.yaml` | archetypeRules | Precedence order, required + supporting facets per archetype | -| `development-workflows.yaml` | developmentWorkflows | Git workflow steps and capabilities | -| `development-practices.yaml` | developmentPractices | Engineering principles surfaced in guidance output | -| `github-issues.yaml` | githubIssues | Issue templates, labels, and agent issue workflow | -| `github-prs.yaml` | githubPullRequests | PR templates, bot reviewers, and post-merge checklist | -| `knowledge-base.yaml` | knowledgeBase | Local and remote repo hierarchy roots, GitHub context sources | -| `learning-workflows.yaml` | learningWorkflows | Agent session flow patterns and routing rules | -| `repo-scaffold.yaml` | repoScaffold | Baseline dirs/files and per-archetype scaffold definitions | - -All catalogs use the same schema: `kind`, `version`, `config`. Parsed by `lib/modules/config_catalog.sh` via `dev_kit_catalog_value()`. - -## Module Map - -``` -lib/modules/ - bootstrap.sh — env setup, DEV_KIT_HOME, module path list - config_catalog.sh — YAML catalog reader (awk-based, no yq dependency) - local_env.sh — tool validation, capabilities, env text output - output.sh — terminal formatting (title, section, row, list) - utils.sh — JSON escaping, CSV/array helpers, YAML parsing - repo_signals.sh — repo root detection, file/glob/pattern matching - repo_archetypes.sh — facet detection, archetype classification - repo_factors.sh — 12-factor analysis (present/partial/missing) - repo_reports.sh — factor summary JSON, agent contract - repo_workflows.sh — entrypoints JSON, workflow contract - repo_scaffold.sh — context.yaml generation, dependency resolution, gaps analysis - dev_sync.sh — git state, gh auth, branch analysis, next hint - learning_sources.sh — agent session discovery and flow scoring - template_renderer.sh — mustache-style template rendering - -lib/commands/ - repo.sh — learn/check modes, writes context.yaml - agent.sh — reads manifest, outputs AI context - learn.sh — lessons-learned from agent sessions - uninstall.sh — removes dev.kit installation -``` - -## Data Flow - -``` -bin/dev-kit - │ - ├─ dev_kit_run_home() ← Phase 1: env + context + repo summary - │ ├─ local_env.sh → tool validation, capabilities - │ ├─ repo_signals.sh → repo root detection, markers - │ ├─ repo_archetypes.sh → archetype + profile - │ └─ dev_sync.sh → git state, next action hint - │ - ├─ dev_kit_cmd_repo() ← Phase 2: repo analysis + manifest - │ └─ repo.sh → renders repo.json template - │ ├─ repo_signals.sh - │ ├─ repo_archetypes.sh - │ ├─ repo_factors.sh - │ ├─ repo_reports.sh → factor summary JSON - │ ├─ repo_workflows.sh → entrypoints, workflow contract - │ └─ repo_scaffold.sh → context.yaml generation - │ - ├─ dev_kit_cmd_agent() ← Phase 3: AI context + AGENTS.md - │ └─ agent.sh → renders agent.json template - │ └─ auto-generates .rabbit/context.yaml if missing, writes AGENTS.md - │ - └─ dev_kit_cmd_learn() ← Phase 4: lessons from agent sessions - └─ learn.sh → renders learn.json template - └─ learning_sources.sh → session discovery + flow scoring -``` - -## Context Artifact - -`.rabbit/context.yaml` is the handoff artifact between `dev.kit repo` and `dev.kit agent`. Written by `repo_scaffold.sh`, read by `agent.sh` via awk. If missing, `dev.kit agent` auto-generates it. - -Fields: `repo` (name, archetype, profile), `refs`, `commands`, `github` (open issues, recent PRs, security alerts via `gh api`), `gaps`, `dependencies` (structured cross-repo tracing with resolution), `practices`, `workflow`, `manifests`, `lessons`. - -## Environment Detection - -`dev.kit` detects available tools on every run (no cache). Tools are grouped by category: - -- **required**: `git`, `gh`, `npm`, `docker`, `yq`, `jq` -- **cloud**: `aws`, `gcloud`, `az` -- **recommended**: `@udx/worker-deployment`, `@udx/mcurl` - -Capabilities are derived from tool availability and gate downstream features: - -``` -github_enrichment = gh available + auth ok -yaml_parsing = yq available -json_parsing = jq available -cloud_aws/gcp/az = respective CLI available -``` - -## Output Contract - -Every command supports `--json` for machine-readable output. The JSON schemas are defined in `src/templates/`: - -- `repo.json` — archetype, profile, markers, factors, gaps, dependencies, manifest path -- `agent.json` — repo context, priority refs, entrypoints, workflow contract, dependencies -- `learn.json` — session, flow, destinations, shared context - -These templates are the stable contract for agents and automation. Shell output (no `--json`) is for humans only and may change freely. diff --git a/docs/commands.md b/docs/commands.md deleted file mode 100644 index 0ad2c93..0000000 --- a/docs/commands.md +++ /dev/null @@ -1,93 +0,0 @@ -# Commands - -## `dev.kit` — environment - -Run from any directory. Validates the local software environment, detects the repo, and guides to the next pipeline step. - -**What it checks:** - -- Required: `git`, `gh`, `npm`, `docker`, `yq`, `jq` — each shown with what it enables -- Cloud CLIs: `aws`, `gcloud`, `az` (optional) -- Recommended: `@udx/worker-deployment`, `@udx/mcurl` (optional) - -Capabilities derived from tool availability: - -| Capability | Requires | -|---|---| -| `yaml_parsing` | `yq` available | -| `json_parsing` | `jq` available | -| `github_enrichment` | `gh` available and authenticated | -| `cloud_aws/gcp/azure` | respective CLI available | - -Use `dev.kit --json` to inspect the full `localhost_tools` inventory and `global_context.capabilities` block. - -## `dev.kit repo` — repo context - -Analyzes the repository against 4 engineering factors (documentation, dependencies, config, pipeline) and writes `.rabbit/context.yaml` — the canonical context artifact. Detects config manifests (YAML files that define workflow and tooling). - -Two modes: - -- **learn** (default): analyze repo, pull GitHub context, trace dependencies, write `.rabbit/context.yaml` -- **--check**: report gaps without writing anything -- **--force**: re-resolve all dependency repos from scratch (skip cached context.yaml in sibling repos) - -```bash -dev.kit repo -dev.kit repo --check -dev.kit repo --force -dev.kit repo --json -``` - -Output includes: archetype, profile, factors (✓ present / ◦ partial / ✗ missing), gaps, dependencies, and context path. - -### Dependency tracing - -`dev.kit repo` traces dependencies from 6 sources (all config-driven from `detection-signals.yaml`): - -1. **Reusable workflows** — `uses: org/repo/.github/workflows/...@ref` -2. **GitHub actions** — `uses: org/repo@ref` (direct action references) -3. **Docker images** — `FROM` in Dockerfiles, `image:` in Compose and workflow files, `uses: docker://` -4. **Versioned YAML configs** — `version: domain/repo/module/v1` URIs in `.rabbit/` -5. **GitHub URLs** — `github.com/org/repo` patterns in YAML and markdown -6. **npm packages** — `dependencies` and `devDependencies` from `package.json` - -Resolution: -- **Same-org repos**: resolved via `gh api` (primary) then sibling directory lookup. Returns archetype, profile, description. -- **Docker images**: if the Docker Hub org differs from the GitHub org, the image name is matched against same-org repos (e.g., `usabilitydynamics/udx-worker-tooling` → `udx/worker-tooling`). -- **External deps**: listed with `resolved: false` for agent reference. No nested scanning. - -Each dependency includes `used_by` — the specific files in the current repo that reference it. - -## `dev.kit agent` — execution contract - -Generates `AGENTS.md` — a deterministic execution contract with strict rules, commands, priority refs, config manifests, GitHub context, full workflow, engineering practices, and versioned workflow artifacts. - -Auto-generates `.rabbit/context.yaml` if missing — no manual `dev.kit repo` step required. - -```bash -dev.kit agent -dev.kit agent --json -``` - -AGENTS.md includes: -- **Contract** — 8 rules: no scanning, strict boundaries, manifests before code, context over memory, verify locally, follow workflow, reuse over invention, remember context -- **Config manifests** — traceable YAML dependencies with kind labels -- **GitHub context** — open issues, recent PRs, security alerts (via `gh api`) -- **Full workflow** — execution sequence with operational notes -- **Engineering practices** — 17 principles from lessons learned - -## `dev.kit learn` — agent experience - -Scans recent Claude and Codex agent sessions, extracts workflow patterns and operational references, and writes a lessons artifact at `.rabbit/dev.kit/lessons-*.md`. - -Lessons feed back into `.rabbit/context.yaml` on next `dev.kit repo` run and are referenced from `AGENTS.md`. - -```bash -dev.kit learn -dev.kit learn --json -dev.kit learn --sources claude -``` - -## `dev.kit uninstall` - -Removes the local install from `~/.udx/dev.kit` and the `~/.local/bin/dev.kit` symlink. Does not modify shell profiles. diff --git a/docs/context.md b/docs/context.md new file mode 100644 index 0000000..f77a93c --- /dev/null +++ b/docs/context.md @@ -0,0 +1,113 @@ +# Context + +`.rabbit/context.yaml` is the structured repo contract produced by `dev.kit repo`. + +It should answer: what can be fetched from this repo programmatically, what was detected, what is missing, and what other repos or workflows this repo depends on. + +## Role + +`context.yaml` is the machine-friendly map of the repository. It is not the place for agent policy, step-by-step behavior, or prompt-style instructions. + +Use it for facts such as: + +- repo identity +- priority refs +- canonical commands +- detected gaps +- manifests that define behavior +- traced dependencies and where they are used +- workflow and practice data that can be emitted from repo-owned config + +## How It Is Produced + +Run: + +```bash +dev.kit repo +``` + +That command inspects repo-native signals, resolves what it can deterministically, and writes `.rabbit/context.yaml`. + +If the file is missing, `dev.kit agent` can generate it first before writing `AGENTS.md`. + +## What Feeds It + +`context.yaml` comes from evidence `dev.kit` can fetch or derive from the repo and its configured integrations: + +- README and docs +- manifests like `package.json`, `composer.json`, `Dockerfile` +- `.github/workflows/*` +- `deploy.yml` +- tests and command surfaces +- YAML config catalogs in `src/configs/` +- GitHub repo signals when available + +The key boundary is simple: if `dev.kit` can detect it, trace it, or serialize it, it belongs here. + +## Main Sections + +The generated file in this repo currently includes: + +- `repo` +- `refs` +- `commands` +- `gaps` +- `practices` +- `workflow` +- `dependencies` +- `manifests` +- `lessons` + +Depending on available integrations, it may also include GitHub-derived data. + +## What Each Section Means + +`repo` identifies the repository through values such as `name`, `archetype`, and `profile`. + +`refs` is the priority reading list. It tells an agent or tool which files and directories matter first. + +`commands` is the detected execution surface, such as `verify`, `build`, and `run`. + +`dependencies` is cross-repo tracing. Each entry explains what external repo, package, or workflow was referenced and which local files use it. + +`gaps` is a checklist of missing or partial factors `dev.kit` could detect programmatically. + +`manifests` lists the config files that define repo behavior. In `dev.kit`, these are first-class interfaces. + +`practices` and `workflow` are still structured repo data. They come from repo-owned catalogs, not from prompt-time improvisation. + +`lessons` links prior session artifacts produced by `dev.kit learn`. + +## What Does Not Belong Here + +`context.yaml` should not try to be the final agent prompt. + +It is not where you explain: + +- how an agent should interpret ambiguity +- how an agent should sequence work for a user +- how an agent should balance repo context against current task context + +That layer belongs in `AGENTS.md`. + +## Efficiency Goal + +The point of `context.yaml` is compression without losing structure. + +It should let an agent answer questions like: + +- What commands exist? +- What docs and manifests matter first? +- What dependencies are real, and where are they used? +- Which engineering factors are missing? +- What workflow steps are already declared by the repo? + +If that data is available in `context.yaml`, the agent does not need to rediscover it by scanning. + +## JSON Contract + +For automation, the repo command JSON surface is defined by: + +- `src/templates/repo.json` + +That JSON output and `.rabbit/context.yaml` are the stable structured surfaces from `dev.kit repo`. diff --git a/docs/detection-facets.md b/docs/detection-facets.md deleted file mode 100644 index fbbfc22..0000000 --- a/docs/detection-facets.md +++ /dev/null @@ -1,53 +0,0 @@ -# Detection Facets - -`dev.kit` exposes coarse, integration-friendly facets in `dev.kit repo --json` and `dev.kit agent --json`. - -The current design goal is stability, not exhaustiveness. Facets should describe durable repo traits that are cheap to detect and useful for automation. - -## Current Facets - -- `framework:wordpress` -- `platform:kubernetes` -- `runtime:container` -- `workflow:github` -- `repo:workflow-primary` -- `package:node` -- `package:composer` -- `deploy:terraform` -- `deploy:kubernetes-manifests` -- `lifecycle:build` -- `lifecycle:runtime` -- `lifecycle:deploy` - -## Detection Phases - -`dev.kit` should detect repo identity with the cheapest signals first: - -1. Root files and well-known top-level directories -2. Small targeted manifests such as workflow files and deploy configs -3. Broader glob scans only when the repo is still ambiguous - -Generated and dependency-heavy directories are pruned by default to keep detection interactive. - -## Key Distinctions - -- `deploy:terraform` fires when `.tf` files or a `terraform/` directory exist — regardless of whether Kubernetes manifests are also present. -- `platform:kubernetes` requires actual K8s manifests (`k8s/*.yaml`, `Chart.yaml`, `helmfile.yaml`) or Helm chart directories. Terraform alone does not imply Kubernetes. -- `repo:workflow-primary` fires when `action.yml`/`action.yaml` is present at the root, or when GitHub workflows are the only primary artifact (no app code, no K8s manifests, no package.json). - -## Reading Priority - -For repo exploration and agent grounding, `dev.kit` should prefer standard engineering refs before anything custom: - -1. `README.md` or `readme.md` -2. `docs/` -3. workflow and delivery contracts such as `.github/workflows/`, `.rabbit/`, `deploy.yml`, and `Makefile` -4. runtime and dependency contracts such as `package.json`, `composer.json`, and `Dockerfile` -5. framework-specific roots such as `wp-config.php` and `wp-content/` - -## Extension Rules - -- Add new file and directory signals in `src/configs/detection-signals.yaml` or `src/configs/archetype-signals.yaml`. -- Add new content patterns in `src/configs/detection-patterns.yaml`. -- Prefer coarse facets over highly specific one-off labels. -- Keep archetypes high-level and let facets explain why an archetype matched. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..1d3ea26 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,94 @@ +# Installation + +`dev.kit` supports two install paths: + +- `npm install -g @udx/dev-kit` +- `curl -fsSL https://raw.githubusercontent.com/udx/dev.kit/latest/bin/scripts/install.sh | bash` + +Whichever path you use last becomes the active install. The installer cleans up the other path first so one install owns `dev.kit` at a time. + +## Recommended Path + +Use npm when it is available: + +```bash +npm install -g @udx/dev-kit +``` + +This is the default path. + +## Curl Install + +Use curl when npm is not available or not desired: + +```bash +curl -fsSL https://raw.githubusercontent.com/udx/dev.kit/latest/bin/scripts/install.sh | bash +``` + +The curl installer creates: + +- `~/.udx/dev.kit` as the install home +- `~/.local/bin/dev.kit` as the executable shim + +It does not edit shell profile files. If `~/.local/bin` is not already in `PATH`, the installer tells you what to export manually. + +## Smart Cleanup + +Install cleanup is symmetric: + +- npm install removes a prior curl-managed install from `~/.udx/dev.kit` and `~/.local/bin/dev.kit` +- curl install removes a prior global npm package install of `@udx/dev-kit` + +This keeps users from ending up with conflicting binaries or stale install homes. + +## npm Install + +The npm package runs a postinstall hook. That hook checks for the curl-managed home and shim. If they exist and the shim points at the curl install, it removes them and leaves the npm install as the only active one. + +## Curl Install Behavior + +The curl installer checks whether `@udx/dev-kit` is already installed globally through npm. If it is, the installer removes that package first and then lays down the curl-managed home and shim. + +The installer also supports both execution styles: + +- `bash install.sh` +- `bash < install.sh` + +That matters because the public curl flow pipes the script into `bash`. + +## Uninstall + +The curl-managed install can be removed with: + +```bash +dev.kit uninstall +``` + +Or non-interactively: + +```bash +dev.kit uninstall --yes +``` + +This removes: + +- `~/.local/bin/dev.kit` +- `~/.udx/dev.kit` + +It does not modify shell profile files. + +For npm-managed installs, remove the package with: + +```bash +npm uninstall -g @udx/dev-kit +``` + +## Verify + +After either install path, verify the active install with: + +```bash +dev.kit +``` + +That confirms the command resolves correctly and shows the next step in the session flow. diff --git a/docs/integration.md b/docs/integration.md new file mode 100644 index 0000000..7c6198d --- /dev/null +++ b/docs/integration.md @@ -0,0 +1,102 @@ +# Integration + +`dev.kit` works because it separates repo knowledge from agent behavior, then links them in one session flow. + +The goal is not to generate more files. The goal is to reduce uncertainty about what exists, what matters, and how to act. + +## Core Flow + +The integration model starts with three commands: + +```bash +dev.kit +dev.kit repo +dev.kit agent +``` + +Those commands connect four layers: + +1. local environment detection +2. structured repo context generation +3. agent contract generation +4. human or agent execution + +For agents, this is not only a first-time setup flow. It is the resync loop. On each new interaction or session, rerun the flow so the next action starts from current repo context rather than stale memory. + +## Separation Of Responsibilities + +The split should stay explicit: + +- `dev.kit repo` produces `.rabbit/context.yaml` +- `dev.kit agent` produces `AGENTS.md` + +`context.yaml` is the fetched map of the repo and its detectable signals. + +`AGENTS.md` is the operating contract that tells an agent how to use that map together with workflow expectations, GitHub context, and learned patterns. + +That separation keeps both artifacts smaller and more reliable. + +## Developer Integration + +For developers, `dev.kit` provides: + +- a quick environment check +- a generated summary of repo factors and gaps +- a canonical command surface for verify, build, and run +- a repeatable way to understand repo expectations before changing code + +This reduces time spent rediscovering how a repo works. + +## Agent Integration + +For agents, `dev.kit` provides: + +- a structured reading surface in `context.yaml` +- config and workflow manifests as first-class interfaces +- a behavior contract in `AGENTS.md` +- JSON output for automation and toolchains + +This means agents can spend less effort on discovery and more effort on scoped execution. + +## GitHub And History + +GitHub and learning data are most useful when they support agent decisions, not when they blur the repo map. + +In practice: + +- repo and integration signals can be serialized into `context.yaml` +- current issues, PRs, lessons, and workflow expectations become most useful in `AGENTS.md` + +That gives agents both structure and recency without mixing roles. + +## Workflow Integration + +The generated workflow is intended to fit into normal engineering work: + +1. start the session with `dev.kit`, `dev.kit repo`, and `dev.kit agent` +2. read the generated repo contract and agent contract +3. do the actual implementation or review work +4. verify with repo-declared commands +5. optionally run `dev.kit learn` so session outcomes feed future runs + +## Config-Driven Integration + +`dev.kit` does not rely on hidden prompt rules. It integrates through repo-owned config and workflow assets: + +- `src/configs/*.yaml` +- workflow files +- repo manifests +- docs +- tests + +That makes behavior inspectable, versioned, and reusable. + +## Efficiency Goal + +The best integration is: + +- `context.yaml` stays factual and structured +- `AGENTS.md` stays directive and execution-oriented +- both are regenerated cheaply at session start + +That gives developers and agents one contract with two surfaces instead of two competing sources of truth. diff --git a/docs/overview.md b/docs/overview.md deleted file mode 100644 index 85ddda9..0000000 --- a/docs/overview.md +++ /dev/null @@ -1,63 +0,0 @@ -# Overview - -`dev.kit` produces dynamic repo context. Developers and AI agents consume the same output — no separate workflows. - -## The split - -dev.kit handles deterministic work that should be repeatable: -- Tool detection and environment validation -- Repo factor analysis (documentation, dependencies, config, pipeline) -- Cross-repo dependency tracing and resolution -- GitHub signal collection (issues, PRs, security alerts) -- Context artifact generation - -Agents and developers handle judgment: -- Code changes, refactoring, feature implementation -- PR creation and review -- Architecture decisions -- Gap prioritization - -## Phases - -``` -dev.kit → dev.kit repo → dev.kit agent → dev.kit learn -───────────────── ────────────────── ────────────────── ────────────────── -check environment analyze factors generate AGENTS.md scan agent sessions -detect archetype trace dependencies write execution extract patterns -guide to next write context.yaml contract write lessons -``` - -### 1. env — `dev.kit` - -Validates the local software environment. Each tool is shown with what it enables. Capabilities gate downstream features: - -| Capability | Requires | If missing | -|---|---|---| -| `github_enrichment` | `gh` authenticated | GitHub API enrichment skipped | -| `yaml_parsing` | `yq` | Fallback to awk parsing | -| `json_parsing` | `jq` | Fallback parsing | -| `cloud_aws/gcp/azure` | respective CLI | Cloud context skipped | - -### 2. repo — `dev.kit repo` - -Analyzes the repository against 4 factors (documentation, dependencies, config, pipeline). Traces cross-repo dependencies from 6 sources. Pulls live GitHub signals. Writes `.rabbit/context.yaml`. - -Flags: `--check` (read-only), `--force` (re-resolve dependencies). - -### 3. agent — `dev.kit agent` - -Generates `AGENTS.md` — a deterministic execution contract with 8 rules, commands, refs, dependencies, workflow, and practices. Auto-generates `.rabbit/context.yaml` if missing. - -### 4. learn — `dev.kit learn` - -Scans recent Claude and Codex agent sessions, extracts workflow patterns and operational references, writes a lessons artifact at `.rabbit/dev.kit/lessons-*.md`. Lessons feed back into context.yaml on next run. - -## Design principles - -**Standard signals first** — README, docs, tests, manifests, workflows, deploy config. No custom metadata files required. - -**Config over code** — detection patterns, archetype rules, workflow steps all defined in YAML. Shell is thin glue. - -**Deterministic scanning** — dev.kit produces the same context from the same repo state. No randomness, no LLM calls. - -**One file handoff** — `.rabbit/context.yaml` is the single artifact between dev.kit and everything downstream. diff --git a/docs/workflow.md b/docs/workflow.md deleted file mode 100644 index ae579eb..0000000 --- a/docs/workflow.md +++ /dev/null @@ -1,102 +0,0 @@ -# Workflow Model - -For the product summary see [docs/overview.md](overview.md). For command reference see [docs/commands.md](commands.md). - -## Phases - -dev.kit operates as a pipeline. Each phase builds on the previous — global context from the env phase gates what subsequent phases can do. - -``` -dev.kit → dev.kit repo → dev.kit agent → dev.kit learn -───────────────── ───────────────── ───────────────── ───────────────── -validate env analyze factors write AGENTS.md scan agent sessions -detect repo detect manifests auto-generate extract patterns -show next steps write context.yaml context if needed write lessons artifact -``` - -### Phase 1 — env (`dev.kit`) - -Validates the local software environment, detects the current repo, and guides to the next pipeline step. Each tool is shown with what it enables. - -Capabilities that gate downstream phases: - -| Capability | Requires | If missing | -|---|---|---| -| `github_enrichment` | `gh` authenticated | GH API enrichment skipped | -| `yaml_parsing` | `yq` | Fallback to awk parsing | -| `json_parsing` | `jq` | Fallback parsing | -| `cloud_aws/gcp/azure` | respective CLI | Cloud context skipped | - -### Phase 2 — repo (`dev.kit repo`) - -Analyzes the repository against 4 factors (documentation, dependencies, config, pipeline). Detects config manifests (YAML files that define workflow and tooling). Writes `.rabbit/context.yaml`. - -Three modes: - -- **learn** (default): analyze, trace dependencies, pull GitHub context, and write `.rabbit/context.yaml` -- **--check**: report gaps without writing anything -- **--force**: re-resolve all dependency repos from scratch - -### Phase 3 — agent (`dev.kit agent`) - -Generates `AGENTS.md` — a comprehensive agent guide with anti-drift rules, commands, priority refs, config manifests, full workflow, and lessons. Auto-generates `.rabbit/context.yaml` if missing. - -### Phase 4 — learn (`dev.kit learn`) - -Scans recent Claude and Codex agent sessions, extracts workflow patterns, and writes a lessons artifact at `.rabbit/dev.kit/lessons-*.md`. Lessons feed back into context.yaml on next `dev.kit repo` run. - -## Pipeline Usage - -The intended flow for starting a development session: - -```bash -cd -dev.kit -dev.kit repo -dev.kit agent -# ... do work ... -dev.kit learn -``` - -`dev.kit agent` auto-generates context if `.rabbit/context.yaml` is absent — `dev.kit repo` is not a hard prerequisite. Agents use `dev.kit agent --json` as the machine-readable contract. `AGENTS.md` is the provider-agnostic guide. - -## Separation of Responsibilities - -- **Config and scripts** own deterministic workflow logic: discovery, detection, validation, policy -- **AI agents** consume the output contract and add judgment for non-deterministic work -- **Anything repeatable** should live in the repo — not only in a prompt - -## Standard Repo First - -dev.kit works from standard repository evidence without requiring custom metadata: - -- `README` and docs -- manifests: `package.json`, `composer.json`, `Dockerfile` -- `.github/workflows/*`, `deploy.yml`, command layers -- `tests/`, verified entrypoints, runtime and build commands - -Custom overlays (`AGENTS.md`, `CLAUDE.md`) are optional and secondary to repo-native sources. - -## `dev.kit learn` - -`dev.kit learn` scans recent Claude and Codex agent sessions, extracts workflow patterns and operational references, and writes a durable lessons artifact. - -Supported sources: - -- Claude: auto-discovered from `~/.claude/projects/` and `~/.claude/history.jsonl` -- Codex: auto-discovered from `$CODEX_HOME/sessions/` - -Use `--sources claude` or `--sources codex` to limit to one source. Without agent sessions, learn reports the configured workflow destinations but has no data to evaluate. - -## Factors - -dev.kit evaluates what it can detect and advise on programmatically. App architecture and runtime are left to agents and developers. - -| Factor | Detects | -|---|---| -| `documentation` | README, docs/ | -| `dependencies` | package.json, composer.json, requirements.txt, go.mod, etc. | -| `config` | .env files, documented environment variables | -| `pipeline` | CI workflows, test commands, deploy configs, infra dirs | - -Each factor is reported as `present`, `partial`, or `missing` with evidence and improvement guidance. diff --git a/src/configs/context-config.yaml b/src/configs/context-config.yaml index a9c5ec6..f9e9bba 100644 --- a/src/configs/context-config.yaml +++ b/src/configs/context-config.yaml @@ -35,7 +35,10 @@ config: priority_paths: - README.md - readme.md - - docs/architecture.md + - docs/installation.md + - docs/context.md + - docs/agents.md + - docs/integration.md - docs/lessons-learned.md - docs - .rabbit @@ -64,8 +67,11 @@ config: - AGENTS.md - README.md - readme.md + - docs/installation.md + - docs/context.md + - docs/agents.md + - docs/integration.md - docs/lessons-learned.md - - docs/architecture.md - docs - .rabbit/dev.kit marker_groups: diff --git a/src/configs/repo-scaffold.yaml b/src/configs/repo-scaffold.yaml index e2a3a7e..a91e5ef 100644 --- a/src/configs/repo-scaffold.yaml +++ b/src/configs/repo-scaffold.yaml @@ -62,7 +62,8 @@ config: documentation: files: - README.md - - docs/overview.md + - docs/integration.md + - docs/context.md config: files: - .env.example From 886742b283cc83e36599167dfbfdd9036a50f0d9 Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Thu, 16 Apr 2026 20:15:37 +0300 Subject: [PATCH 05/11] chore remove local github templates and hook --- .githooks/commit-msg | 21 --------------- .github/ISSUE_TEMPLATE/bug.yml | 42 ------------------------------ .github/ISSUE_TEMPLATE/feature.yml | 28 -------------------- .github/ISSUE_TEMPLATE/infra.yml | 34 ------------------------ .github/PULL_REQUEST_TEMPLATE.md | 30 --------------------- 5 files changed, 155 deletions(-) delete mode 100755 .githooks/commit-msg delete mode 100644 .github/ISSUE_TEMPLATE/bug.yml delete mode 100644 .github/ISSUE_TEMPLATE/feature.yml delete mode 100644 .github/ISSUE_TEMPLATE/infra.yml delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.githooks/commit-msg b/.githooks/commit-msg deleted file mode 100755 index 595b0cd..0000000 --- a/.githooks/commit-msg +++ /dev/null @@ -1,21 +0,0 @@ -#!/usr/bin/env bash - -set -euo pipefail - -message_file=${1:?commit message file is required} -subject=$(sed -n '1s/[[:space:]]*$//p' "$message_file") - -case "$subject" in - "") - exit 0 - ;; - Merge\ *|Revert\ *|fixup!\ *|squash!\ *) - exit 0 - ;; -esac - -if printf '%s' "$subject" | rg -q '[A-Z]'; then - printf 'dev.kit hook: commit subject must be lowercase\n' >&2 - printf 'received: %s\n' "$subject" >&2 - exit 1 -fi diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml deleted file mode 100644 index 2efc1ca..0000000 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ /dev/null @@ -1,42 +0,0 @@ -name: Bug report -description: Something isn't working -labels: ["type:bug"] -body: - - type: textarea - id: summary - attributes: - label: Summary - description: One sentence — what is broken and where. - validations: - required: true - - - type: textarea - id: reproduce - attributes: - label: Steps to reproduce - description: Minimal set of commands or actions that trigger the problem. - placeholder: | - 1. Run `…` - 2. Observe `…` - validations: - required: true - - - type: textarea - id: expected - attributes: - label: Expected behavior - validations: - required: true - - - type: textarea - id: actual - attributes: - label: Actual behavior - validations: - required: true - - - type: textarea - id: context - attributes: - label: Context - description: Relevant files, logs, environment details, related issue or PR URLs. diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml deleted file mode 100644 index 64552ff..0000000 --- a/.github/ISSUE_TEMPLATE/feature.yml +++ /dev/null @@ -1,28 +0,0 @@ -name: Feature / task -description: New capability, improvement, or work item -labels: ["type:feature"] -body: - - type: textarea - id: goal - attributes: - label: Goal - description: What capability is being added and why it matters. - validations: - required: true - - - type: textarea - id: acceptance - attributes: - label: Acceptance criteria - description: Bullet list — each item must be verifiable and map to a testable condition. - placeholder: | - - [ ] … - - [ ] … - validations: - required: true - - - type: textarea - id: context - attributes: - label: Context - description: Relevant files, constraints, related issues or PRs, cross-repo links. diff --git a/.github/ISSUE_TEMPLATE/infra.yml b/.github/ISSUE_TEMPLATE/infra.yml deleted file mode 100644 index b5c6943..0000000 --- a/.github/ISSUE_TEMPLATE/infra.yml +++ /dev/null @@ -1,34 +0,0 @@ -name: Infrastructure / ops -description: Infrastructure, deployment, or operational change -labels: ["type:infra"] -body: - - type: textarea - id: goal - attributes: - label: Goal - description: What is being changed and what outcome is expected. - validations: - required: true - - - type: textarea - id: scope - attributes: - label: Scope - description: Which services, environments, clusters, or repos are affected. - - - type: textarea - id: acceptance - attributes: - label: Acceptance criteria - description: Observable evidence that the change is live and stable. - placeholder: | - - [ ] … - - [ ] … - validations: - required: true - - - type: textarea - id: context - attributes: - label: Context - description: Deploy config, workflow files, infra docs, runbook links. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index a417713..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,30 +0,0 @@ - - - -Closes # - -## Changes - - -## Pre-merge gates - - -## Review notes - - -## Backlog from this investigation - From a7ce8bf27a6db2672b2dd1e81f6e5d0d84e98072 Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Thu, 16 Apr 2026 20:57:35 +0300 Subject: [PATCH 06/11] refactor context contract and simplify agents artifact --- .rabbit/context.yaml | 5 +- AGENTS.md | 60 +++----------- README.md | 12 ++- docs/agents.md | 26 +++++- docs/context.md | 27 ++++++- docs/integration.md | 18 ++++- lib/commands/agent.sh | 75 +++-------------- lib/modules/config_catalog.sh | 26 +----- lib/modules/repo_signals.sh | 108 ------------------------- src/configs/context-config.yaml | 8 -- src/configs/detection-patterns.yaml | 1 - src/configs/detection-signals.yaml | 66 --------------- src/configs/development-practices.yaml | 2 + src/configs/development-workflows.yaml | 4 +- src/configs/knowledge-base.yaml | 15 +++- tests/suite.sh | 7 ++ 16 files changed, 122 insertions(+), 338 deletions(-) diff --git a/.rabbit/context.yaml b/.rabbit/context.yaml index 07185f4..25d4883 100644 --- a/.rabbit/context.yaml +++ b/.rabbit/context.yaml @@ -24,8 +24,6 @@ refs: - ./lib - ./src - ./tests - - https://raw.githubusercontent.com/udx/dev.kit/latest/.github/ISSUE_TEMPLATE - - https://raw.githubusercontent.com/udx/dev.kit/latest/.github/PULL_REQUEST_TEMPLATE.md commands: verify: make test @@ -43,6 +41,7 @@ practices: - "Keep markdown, yaml, diagrams, tests, and command contracts self-contained in the repo so local and remote UDX workflows stay aligned." - "Keep deterministic workflow logic in repo config and scripts, and reserve AI agents for reading that contract, generating grounded summaries, and handling non-deterministic judgment without inventing hidden rules." - "Operate from repo-declared context at all times. Do not carry assumptions across sessions or rely on prompt history when the repo contract is available on disk." + - "After loading the repo contract, prefer current GitHub issues, pull requests, review state, and commit history as the primary dynamic source for agent decisions. Use repo workflow and practice catalogs as fallback defaults when live GitHub signal is missing or thin." - "When understanding behavior, read the YAML manifest that defines it before reading the code that implements it. Manifests are the interface — code is the mechanism." - "Check existing org patterns, configs, workflows, and templates before creating new ones. Reuse declared patterns instead of inventing alternatives." - "Execute verification, builds, and tests locally before any remote operation. Local execution is part of the reproducible repo contract, not a preference." @@ -59,7 +58,7 @@ practices: # Canonical agent workflow workflow: - - "Refresh repo context: Run `dev.kit` → `dev.kit repo` → `dev.kit agent` before starting work. Each command guides to the next required step. This resyncs repo context, environment state, and the AGENTS.md execution contract. A current context.yaml is the source of truth for refs, commands, gaps, and lessons. Do not rely on ad hoc prompt memory when the repo contract can be read from disk." + - "Refresh repo context: Run `dev.kit` → `dev.kit repo` → `dev.kit agent` before starting work. Each command guides to the next required step. This resyncs repo context, environment state, and the AGENTS.md execution contract. A current context.yaml is the source of truth for refs, commands, gaps, and lessons. Do not rely on ad hoc prompt memory when the repo contract can be read from disk. When GitHub context is available, prefer current issues, pull requests, review state, and commit history over stale memory or generic workflow defaults." - "Read linked GitHub issue and confirm scope: If a GitHub issue URL is available, read the full body and comments, confirm the repo matches the issue scope, and map acceptance criteria before writing any code. Use the issue URL as the cross-repo context root." - "Inspect git status" - "Analyze local changes" diff --git a/AGENTS.md b/AGENTS.md index 7017053..d196d25 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md -_Auto-generated by `dev.kit agent`. Sources: `.rabbit/context.yaml`, lesson artifacts, GitHub history._ +_Auto-generated by `dev.kit agent`. Sources: `.rabbit/context.yaml`, GitHub history, lesson artifacts._ ## Contract @@ -15,12 +15,14 @@ This repository is a deterministic execution contract. Agents MUST interpret dec 5. **Verify locally before committing.** Run the verify command before reporting work as done. Local execution is part of the contract. 6. **Follow the Workflow below.** Do not invent ad hoc steps or skip phases. The workflow is the execution sequence. 7. **Reuse over invention.** Check existing org patterns, configs, and workflows before creating new ones. -8. **Remember this context.** If your agent supports persistent memory, save that this repo uses `dev.kit` for context management. Start every session — or after merges, config changes, or workflow updates — by running: `dev.kit` → `dev.kit repo` → `dev.kit agent`. Each command guides to the next required step. This resyncs repo context, environment state, and the execution contract before any work begins. +8. **Prefer live GitHub experience over generic defaults.** After loading the repo contract, use current issues, pull requests, review state, and commit history as the primary dynamic source. Fall back to workflow and practice catalogs when GitHub signal is missing, thin, or irrelevant. +9. **Remember this context.** If your agent supports persistent memory, save that this repo uses `dev.kit` for context management. Start every session — or after merges, config changes, or workflow updates — by running: `dev.kit` → `dev.kit repo` → `dev.kit agent`. Each command guides to the next required step. This resyncs repo context, environment state, and the execution contract before any work begins. ## Repo: dev.kit - archetype: library-cli - profile: node +- context: ./.rabbit/context.yaml ### Commands @@ -30,50 +32,11 @@ This repository is a deterministic execution contract. Agents MUST interpret dec run: make run ``` -### Priority refs - -These files plus config manifests define the complete allowed surface. Do not explore beyond them. - - - ./README.md - - ./docs/architecture.md - - ./docs - - ./.rabbit - - ./.github/workflows - - ./Makefile - - ./package.json - - ./deploy.yml - - ./lib - - ./src - - ./tests - -### Config manifests - -YAML definitions are first-class interfaces. They control repo behavior — trace dependencies here, not in implementation code. - - - src/configs/archetype-rules.yaml — archetype definitions and matching rules - - src/configs/archetype-signals.yaml — file/dir signals for framework and platform detection - - src/configs/audit-rules.yaml — factor gap messages and improvement guidance - - src/configs/context-config.yaml — repo root markers and priority paths - - src/configs/detection-patterns.yaml — regex patterns for build/verify/run command detection - - src/configs/detection-signals.yaml — file/dir/glob patterns for factor analysis - - src/configs/development-practices.yaml — engineering principles inlined into repo context - - src/configs/development-workflows.yaml — git workflow steps, PR process, and operational notes - - src/configs/github-issues.yaml — issue templates, labels, and agent issue workflow - - src/configs/github-prs.yaml — PR templates, bot reviewers, and post-merge checklist - - src/configs/knowledge-base.yaml — org hierarchy and preferred knowledge sources - - src/configs/learning-workflows.yaml — agent session discovery and lesson extraction rules - - src/configs/repo-scaffold.yaml — baseline dirs/files per archetype and factor - - .github/workflows/context7-ops.yml - - .github/workflows/npm-release-ops.yml - - deploy.yml - -### External dependencies - -Cross-repo and upstream references. Same-org repos are resolved with metadata. Trace these for infrastructure, deployment, and build logic. - -- **udx/reusable-workflows** (reusable workflow) — workflow-repo - - `.github/workflows/context7-ops.yml` - - `.github/workflows/npm-release-ops.yml` +## Use context.yaml + +All refs, config manifests, command surfaces, dependencies, and gaps live in `.rabbit/context.yaml`. + +Do not duplicate that inventory here. Read `context.yaml` first, then use this file for operating rules, workflow, and dynamic guidance. ### Gaps @@ -94,9 +57,9 @@ Prior session lessons — read before starting work: ## Workflow -The dev.kit lifecycle: **repo → agent → work → PR → merge**. Follow these steps in order. Steps with notes contain operational guidance. +The dev.kit lifecycle: **repo → agent → work → PR → merge**. Follow these steps in order. Use them as repo-declared defaults when live GitHub context does not provide a more specific current signal. Steps with notes contain operational guidance. - - Refresh repo context: Run `dev.kit` → `dev.kit repo` → `dev.kit agent` before starting work. Each command guides to the next required step. This resyncs repo context, environment state, and the AGENTS.md execution contract. A current context.yaml is the source of truth for refs, commands, gaps, and lessons. Do not rely on ad hoc prompt memory when the repo contract can be read from disk. + - Refresh repo context: Run `dev.kit` → `dev.kit repo` → `dev.kit agent` before starting work. Each command guides to the next required step. This resyncs repo context, environment state, and the AGENTS.md execution contract. A current context.yaml is the source of truth for refs, commands, gaps, and lessons. Do not rely on ad hoc prompt memory when the repo contract can be read from disk. When GitHub context is available, prefer current issues, pull requests, review state, and commit history over stale memory or generic workflow defaults. - Read linked GitHub issue and confirm scope: If a GitHub issue URL is available, read the full body and comments, confirm the repo matches the issue scope, and map acceptance criteria before writing any code. Use the issue URL as the cross-repo context root. - Inspect git status - Analyze local changes @@ -153,6 +116,7 @@ Patterns detected from agent sessions on this repo. Follow these in addition to - Keep markdown, yaml, diagrams, tests, and command contracts self-contained in the repo so local and remote UDX workflows stay aligned. - Keep deterministic workflow logic in repo config and scripts, and reserve AI agents for reading that contract, generating grounded summaries, and handling non-deterministic judgment without inventing hidden rules. - Operate from repo-declared context at all times. Do not carry assumptions across sessions or rely on prompt history when the repo contract is available on disk. + - After loading the repo contract, prefer current GitHub issues, pull requests, review state, and commit history as the primary dynamic source for agent decisions. Use repo workflow and practice catalogs as fallback defaults when live GitHub signal is missing or thin. - When understanding behavior, read the YAML manifest that defines it before reading the code that implements it. Manifests are the interface — code is the mechanism. - Check existing org patterns, configs, workflows, and templates before creating new ones. Reuse declared patterns instead of inventing alternatives. - Execute verification, builds, and tests locally before any remote operation. Local execution is part of the reproducible repo contract, not a preference. diff --git a/README.md b/README.md index 9cf4a69..a55ec1a 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,13 @@ **Simple session flow for developers and AI agents.** -dev.kit separates repo facts from agent behavior. It generates `.rabbit/context.yaml` as the structured repo contract, then generates `AGENTS.md` as the execution contract that tells agents how to use that context plus workflow, GitHub, and learning signals. +dev.kit separates three concerns: + +- base repo context signals +- deterministic tracing and mapping +- agent execution behavior + +It generates `.rabbit/context.yaml` as the structured repo contract, then generates `AGENTS.md` as a built execution artifact that tells agents how to use that context with current GitHub experience first, and repo-declared workflow defaults when GitHub does not provide enough signal. ```bash npm install -g @udx/dev-kit @@ -67,7 +73,7 @@ gaps: - config (partial) ``` -**`AGENTS.md`** — generated execution contract for agents. It tells them how to start, what to read first, how to use `context.yaml`, how to verify work, and how to follow repo workflow using current GitHub and learned context without relying on stale session memory. +**`AGENTS.md`** — generated execution artifact for agents. It should stay simpler than `context.yaml`: rules, workflow, verification, and how to use current GitHub and learned context without duplicating refs, manifests, or dependency maps already serialized in `context.yaml`. --- @@ -87,7 +93,7 @@ All commands support `--json` for machine-readable output. ## Repo Context -Repo context comes from repo source first: README, docs, workflows, manifests, tests, and other declared refs. That data is serialized into `context.yaml`. `AGENTS.md` then turns that repo map into an operating contract for agents, using workflow guidance, GitHub context, and lessons where available. +Repo context comes from repo source first: README, docs, workflows, manifests, tests, and other declared refs. `dev.kit repo` then traces and maps dependencies, commands, gaps, and other serializable signals into `context.yaml`. `AGENTS.md` turns that repo map into an operating contract for agents, using current GitHub context as the primary dynamic input and repo workflow/practice catalogs as fallback defaults. ## Cross-repo tracing diff --git a/docs/agents.md b/docs/agents.md index e0338bb..666ab54 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -10,6 +10,8 @@ If `context.yaml` answers what is known, `AGENTS.md` answers how an agent should This is the behavior layer. It tells an agent how to use the fetched repo contract efficiently and with minimal drift. +`AGENTS.md` should stay simpler than `context.yaml`. It is a built artifact, not the full repo map. + One core rule should stay explicit: start each new interaction or session by rerunning: ```bash @@ -42,7 +44,8 @@ Raw repo facts are not enough. Agents still need explicit operating instructions - how to prioritize manifests over implementation - how to follow the repo workflow - how to verify before reporting completion -- how to use repo history, lessons, and GitHub context without drifting +- how to use current GitHub history as the primary dynamic source +- how to fall back to repo workflow, practice catalogs, and lessons without drifting ## Inputs @@ -55,6 +58,13 @@ Raw repo facts are not enough. Agents still need explicit operating instructions That keeps the instructions grounded and refreshable. +The intended decision order is: + +1. current repo contract from `.rabbit/context.yaml` +2. current GitHub experience for this repo +3. repo-declared default workflows and practices +4. prior lessons and other secondary history + ## Main Sections The generated contract typically includes: @@ -76,10 +86,18 @@ That includes: - how an agent should start each session - how an agent should interpret repo context -- how an agent should use GitHub issues, PRs, and recent history +- how an agent should use GitHub issues, PRs, and recent history first - how an agent should sequence work and verification - how an agent should avoid scanning and guesswork +It should not restate: + +- priority refs +- manifest inventories +- dependency maps + +Those already belong in `.rabbit/context.yaml`. + This is the layer that combines static repo contract with current repo experience. ## Relationship To `.rabbit/context.yaml` @@ -95,6 +113,10 @@ A useful shorthand is: They should stay separate, but tightly coupled. +`context.yaml` should stay factual and serializable. + +`AGENTS.md` should stay directive, current-state aware, and smaller. + ## Efficiency Goal The best result is a short path from repo state to grounded agent action: diff --git a/docs/context.md b/docs/context.md index f77a93c..5ec7b1b 100644 --- a/docs/context.md +++ b/docs/context.md @@ -8,6 +8,11 @@ It should answer: what can be fetched from this repo programmatically, what was `context.yaml` is the machine-friendly map of the repository. It is not the place for agent policy, step-by-step behavior, or prompt-style instructions. +Its boundary is best understood as two layers combined into one artifact: + +- base repo context signals +- deterministic tracing and mapping built from those signals + Use it for facts such as: - repo identity @@ -42,6 +47,19 @@ If the file is missing, `dev.kit agent` can generate it first before writing `AG - YAML config catalogs in `src/configs/` - GitHub repo signals when available +The important split is: + +- signals are the raw repo-facing inputs +- tracing and mapping are the deterministic transforms `dev.kit` performs on top of them + +Examples of tracing and mapping include: + +- detecting canonical verify, build, and run commands +- mapping reusable workflows to upstream repos +- mapping Docker images to likely source repos +- mapping versioned YAML contracts to upstream modules or repos +- mapping dependencies to the local files that use them + The key boundary is simple: if `dev.kit` can detect it, trace it, or serialize it, it belongs here. ## Main Sections @@ -58,7 +76,7 @@ The generated file in this repo currently includes: - `manifests` - `lessons` -Depending on available integrations, it may also include GitHub-derived data. +Depending on available integrations, it may also include GitHub-derived data. GitHub belongs here only when it can be fetched and serialized as repo experience data. It does not replace the repo contract. ## What Each Section Means @@ -66,6 +84,8 @@ Depending on available integrations, it may also include GitHub-derived data. `refs` is the priority reading list. It tells an agent or tool which files and directories matter first. +This is the only place refs should live. `AGENTS.md` should point to `context.yaml`, not repeat the ref list. + `commands` is the detected execution surface, such as `verify`, `build`, and `run`. `dependencies` is cross-repo tracing. Each entry explains what external repo, package, or workflow was referenced and which local files use it. @@ -74,7 +94,7 @@ Depending on available integrations, it may also include GitHub-derived data. `manifests` lists the config files that define repo behavior. In `dev.kit`, these are first-class interfaces. -`practices` and `workflow` are still structured repo data. They come from repo-owned catalogs, not from prompt-time improvisation. +`practices` and `workflow` are still structured repo data. They come from repo-owned catalogs, not from prompt-time improvisation. They are repo-declared defaults that agents can fall back to when current GitHub history is thin or absent. `lessons` links prior session artifacts produced by `dev.kit learn`. @@ -98,9 +118,10 @@ It should let an agent answer questions like: - What commands exist? - What docs and manifests matter first? +- What repo signals were used? - What dependencies are real, and where are they used? - Which engineering factors are missing? -- What workflow steps are already declared by the repo? +- What workflow defaults are already declared by the repo? If that data is available in `context.yaml`, the agent does not need to rediscover it by scanning. diff --git a/docs/integration.md b/docs/integration.md index 7c6198d..dc9d01c 100644 --- a/docs/integration.md +++ b/docs/integration.md @@ -18,8 +18,9 @@ Those commands connect four layers: 1. local environment detection 2. structured repo context generation -3. agent contract generation -4. human or agent execution +3. deterministic tracing and mapping +4. agent contract generation +5. human or agent execution For agents, this is not only a first-time setup flow. It is the resync loop. On each new interaction or session, rerun the flow so the next action starts from current repo context rather than stale memory. @@ -32,10 +33,15 @@ The split should stay explicit: `context.yaml` is the fetched map of the repo and its detectable signals. -`AGENTS.md` is the operating contract that tells an agent how to use that map together with workflow expectations, GitHub context, and learned patterns. +`AGENTS.md` is the operating contract that tells an agent how to use that map together with current GitHub context, learned patterns, and repo workflow defaults. That separation keeps both artifacts smaller and more reliable. +In practice: + +- `context.yaml` owns refs, manifests, commands, dependencies, and gaps +- `AGENTS.md` points back to `context.yaml` and stays focused on behavior + ## Developer Integration For developers, `dev.kit` provides: @@ -65,7 +71,9 @@ GitHub and learning data are most useful when they support agent decisions, not In practice: - repo and integration signals can be serialized into `context.yaml` -- current issues, PRs, lessons, and workflow expectations become most useful in `AGENTS.md` +- current issues, PRs, and repo history are the primary dynamic inputs in `AGENTS.md` +- workflow expectations and practice catalogs act as fallback defaults in `AGENTS.md` +- lessons remain secondary memory that should not outrank live repo or GitHub state That gives agents both structure and recency without mixing roles. @@ -96,7 +104,9 @@ That makes behavior inspectable, versioned, and reusable. The best integration is: - `context.yaml` stays factual and structured +- tracing and mapping stay deterministic - `AGENTS.md` stays directive and execution-oriented +- GitHub experience stays the primary dynamic source for agent judgment - both are regenerated cheaply at session start That gives developers and agents one contract with two surfaces instead of two competing sources of truth. diff --git a/lib/commands/agent.sh b/lib/commands/agent.sh index 2124518..2a4d620 100644 --- a/lib/commands/agent.sh +++ b/lib/commands/agent.sh @@ -80,7 +80,7 @@ dev_kit_cmd_agent() { dev_kit_output_section "ready" dev_kit_output_list_item "Context synced. Start your session following AGENTS.md workflow." - dev_kit_output_list_item "Run dev.kit at each session start or after repo updates to resync." + dev_kit_output_list_item "Run dev.kit → dev.kit repo → dev.kit agent at each new interaction or after repo updates to resync." } # Write AGENTS.md — the repo's execution contract for AI agents. @@ -93,7 +93,7 @@ dev_kit_agent_write_agents_md() { { printf '# AGENTS.md\n\n' - printf '_Auto-generated by `dev.kit agent`. Sources: `.rabbit/context.yaml`, lesson artifacts, GitHub history._\n\n' + printf '_Auto-generated by `dev.kit agent`. Sources: `.rabbit/context.yaml`, GitHub history, lesson artifacts._\n\n' if [ ! -f "$context_yaml" ]; then printf 'Run `dev.kit repo` to generate context.\n' @@ -110,9 +110,10 @@ dev_kit_agent_write_agents_md() { printf '5. **Verify locally before committing.** Run the verify command before reporting work as done. Local execution is part of the contract.\n' printf '6. **Follow the Workflow below.** Do not invent ad hoc steps or skip phases. The workflow is the execution sequence.\n' printf '7. **Reuse over invention.** Check existing org patterns, configs, and workflows before creating new ones.\n' - printf '8. **Remember this context.** If your agent supports persistent memory, save that this repo uses `dev.kit` for context management. Start every session — or after merges, config changes, or workflow updates — by running: `dev.kit` → `dev.kit repo` → `dev.kit agent`. Each command guides to the next required step. This resyncs repo context, environment state, and the execution contract before any work begins.\n\n' + printf '8. **Prefer live GitHub experience over generic defaults.** After loading the repo contract, use current issues, pull requests, review state, and commit history as the primary dynamic source. Fall back to workflow and practice catalogs when GitHub signal is missing, thin, or irrelevant.\n' + printf '9. **Remember this context.** If your agent supports persistent memory, save that this repo uses `dev.kit` for context management. Start every session — or after merges, config changes, or workflow updates — by running: `dev.kit` → `dev.kit repo` → `dev.kit agent`. Each command guides to the next required step. This resyncs repo context, environment state, and the execution contract before any work begins.\n\n' - # ── Repo layer — identity, commands, allowed surface ───────────────────── + # ── Repo layer — identity, commands, and source artifact ───────────────── local _name _arch _profile _name="$(awk '/^repo:/{f=1} f && /^ name:/ {sub(/.*name:[[:space:]]*/,""); print; exit}' "$context_yaml")" _arch="$(awk '/^repo:/{f=1} f && /^ archetype:/{sub(/.*archetype:[[:space:]]*/,""); print; exit}' "$context_yaml")" @@ -120,6 +121,7 @@ dev_kit_agent_write_agents_md() { printf '## Repo: %s\n\n' "${_name:-unknown}" [ -n "$_arch" ] && printf -- '- archetype: %s\n' "$_arch" [ -n "$_profile" ] && printf -- '- profile: %s\n' "$_profile" + printf -- '- context: ./.rabbit/context.yaml\n' printf '\n' # ── commands ───────────────────────────────────────────────────────────── @@ -129,64 +131,9 @@ dev_kit_agent_write_agents_md() { printf '### Commands\n\n```\n%s\n```\n\n' "$_cmds" fi - # ── priority refs ──────────────────────────────────────────────────────── - local _refs - _refs="$(awk '/^refs:/{f=1;next} f && /^[a-zA-Z#]/{f=0} f && /^ - /' "$context_yaml")" - if [ -n "$_refs" ]; then - printf '### Priority refs\n\n' - printf 'These files plus config manifests define the complete allowed surface. Do not explore beyond them.\n\n' - printf '%s\n\n' "$_refs" - fi - - # ── config manifests ───────────────────────────────────────────────────── - local _manifests - _manifests="$(awk '/^manifests:/{f=1;next} f && /^[a-zA-Z#]/{f=0} f && /^ - /' "$context_yaml")" - if [ -n "$_manifests" ]; then - printf '### Config manifests\n\n' - printf 'YAML definitions are first-class interfaces. They control repo behavior — trace dependencies here, not in implementation code.\n\n' - printf '%s\n\n' "$_manifests" - fi - - # ── external dependencies ────────────────────────────────────────────── - local _deps_block - _deps_block="$(awk '/^dependencies:/{f=1;next} f && /^[a-zA-Z#]/{f=0} f{print}' "$context_yaml")" - if [ -n "$_deps_block" ]; then - printf '### External dependencies\n\n' - printf 'Cross-repo and upstream references. Same-org repos are resolved with metadata. Trace these for infrastructure, deployment, and build logic.\n\n' - # Parse structured dependency blocks into markdown - printf '%s\n' "$_deps_block" | awk ' - /^ - repo:/ { - if (repo != "") flush() - sub(/.*repo:[[:space:]]*/, "") - repo = $0; type = ""; resolved = ""; arch = ""; desc = ""; local_p = "" - ub_count = 0; in_ub = 0 - next - } - /^ type:/ { sub(/.*type:[[:space:]]*/, ""); type = $0; next } - /^ resolved:/ { sub(/.*resolved:[[:space:]]*/, ""); resolved = $0; next } - /^ archetype:/ { sub(/.*archetype:[[:space:]]*/, ""); arch = $0; next } - /^ description:/ { sub(/.*description:[[:space:]]*"?/, ""); sub(/"$/, ""); desc = $0; next } - /^ local_path:/ { sub(/.*local_path:[[:space:]]*/, ""); local_p = $0; next } - /^ used_by:/ { in_ub = 1; next } - in_ub && /^ - / { ub_count++; sub(/^[[:space:]]*- /, ""); ub[ub_count] = $0; next } - in_ub && !/^ / { in_ub = 0 } - - function flush() { - printf "- **%s**", repo - if (type != "") printf " (%s)", type - if (resolved == "true" && arch != "") printf " — %s", arch - if (desc != "") printf " — %s", desc - printf "\n" - if (ub_count > 0) { - for (i = 1; i <= ub_count; i++) - printf " - `%s`\n", ub[i] - } - printf "\n" - } - - END { if (repo != "") flush() } - ' - fi + printf '## Use context.yaml\n\n' + printf 'All refs, config manifests, command surfaces, dependencies, and gaps live in `.rabbit/context.yaml`.\n\n' + printf 'Do not duplicate that inventory here. Read `context.yaml` first, then use this file for operating rules, workflow, and dynamic guidance.\n\n' # ── GitHub context ───────────────────────────────────────────────────── # Items in context.yaml are 4-space indented under github subsections. @@ -195,7 +142,7 @@ dev_kit_agent_write_agents_md() { _gh_repo="$(awk '/^github:/{f=1} f && /^ repo:/{sub(/.*repo:[[:space:]]*/,""); print; exit}' "$context_yaml")" if [ -n "$_gh_repo" ]; then printf '### GitHub context\n\n' - printf 'Development signals from [%s](https://github.com/%s).\n\n' "$_gh_repo" "$_gh_repo" + printf 'Development signals from [%s](https://github.com/%s). Treat this as the primary dynamic source for current repo experience.\n\n' "$_gh_repo" "$_gh_repo" # Helper: extract github subsection, strip indent and YAML quotes for markdown _gh_extract() { @@ -241,7 +188,7 @@ dev_kit_agent_write_agents_md() { _workflow="$(awk '/^workflow:/{f=1;next} f && /^[a-zA-Z#]/{f=0} f && /^ - /{gsub(/^ - "/, " - "); sub(/"$/, ""); gsub(/\\"/, "\""); gsub(/\\\\/, "\\"); print}' "$context_yaml")" if [ -n "$_workflow" ]; then printf '## Workflow\n\n' - printf 'The dev.kit lifecycle: **repo → agent → work → PR → merge**. Follow these steps in order. Steps with notes contain operational guidance.\n\n' + printf 'The dev.kit lifecycle: **repo → agent → work → PR → merge**. Follow these steps in order. Use them as repo-declared defaults when live GitHub context does not provide a more specific current signal. Steps with notes contain operational guidance.\n\n' printf '%s\n\n' "$_workflow" fi diff --git a/lib/modules/config_catalog.sh b/lib/modules/config_catalog.sh index 10eb1d0..583cb8d 100644 --- a/lib/modules/config_catalog.sh +++ b/lib/modules/config_catalog.sh @@ -77,33 +77,9 @@ EOF printf "%s" "$refs" | dev_kit_unique_lines_ci } -dev_kit_repo_kit_source_refs() { - local repo_dir="${1:-$(pwd)}" - local path="" - local _gh_raw="https://raw.githubusercontent.com/udx/dev.kit/latest" - local _gh_tree="https://github.com/udx/dev.kit/tree/latest" - - while IFS= read -r path; do - [ -n "$path" ] || continue - # Skip if already present in the target repo - [ -e "$repo_dir/$path" ] && continue - # Directories use tree URL (raw 404s on dirs), files use raw URL - if [ -d "$REPO_DIR/$path" ]; then - printf "%s/%s\n" "$_gh_tree" "$path" - else - printf "%s/%s\n" "$_gh_raw" "$path" - fi - done < 0 { exit 0 } $1 <= 0 { exit 1 }'; then - count=$((count + 1)) - fi - - if dev_kit_repo_count_dir_hits_from_list "$repo_dir" "architecture_logic_dirs" | awk '$1 > 0 { exit 0 } $1 <= 0 { exit 1 }'; then - count=$((count + 1)) - fi - - if dev_kit_repo_count_dir_hits_from_list "$repo_dir" "architecture_view_dirs" | awk '$1 > 0 { exit 0 } $1 <= 0 { exit 1 }'; then - count=$((count + 1)) - fi - - if dev_kit_repo_count_dir_hits_from_list "$repo_dir" "architecture_config_dirs" | awk '$1 > 0 { exit 0 } $1 <= 0 { exit 1 }'; then - count=$((count + 1)) - fi - - printf '%s' "$count" -} - -dev_kit_repo_max_lines_in_dirs() { - local repo_dir="$1" - local dir_list="$2" - local max_lines=0 - local dir_path="" - local pattern="" - local file_path="" - local line_count=0 - - while IFS= read -r dir_path; do - [ -n "$dir_path" ] || continue - [ -d "$repo_dir/$dir_path" ] || continue - - while IFS= read -r pattern; do - [ -n "$pattern" ] || continue - while IFS= read -r file_path; do - [ -n "$file_path" ] || continue - line_count="$(wc -l < "$file_path" | tr -d ' ')" - if [ "$line_count" -gt "$max_lines" ]; then - max_lines="$line_count" - fi - done < 0 { exit 0 } $1 <= 0 { exit 1 }'; then - return 1 - fi - - max_lines="$(dev_kit_repo_max_lines_in_dirs "$repo_dir" "architecture_command_dirs")" - [ -n "$max_lines" ] || max_lines=0 - [ "$max_lines" -le "$threshold" ] -} - -dev_kit_repo_has_oversized_module() { - local repo_dir="$1" - local max_lines="" - local threshold="" - - threshold="$(dev_kit_detection_scalar "architecture_module_max_lines")" - [ -n "$threshold" ] || threshold=400 - - max_lines="$(dev_kit_repo_max_lines_in_dirs "$repo_dir" "architecture_logic_dirs")" - [ -n "$max_lines" ] || max_lines=0 - [ "$max_lines" -gt "$threshold" ] -} - dev_kit_repo_profiles() { local repo_dir="$1" local profiles="" diff --git a/src/configs/context-config.yaml b/src/configs/context-config.yaml index f9e9bba..0a4ebc2 100644 --- a/src/configs/context-config.yaml +++ b/src/configs/context-config.yaml @@ -24,14 +24,6 @@ config: - CONTEXT.md - refs.md - REFS.md - # Paths relative to DEV_KIT_HOME surfaced as fallback refs when absent from target repo. - # Local absolute path if dev.kit is installed; GitHub raw URL otherwise. - kit_source_refs: - - src/configs/github-issues.yaml - - src/configs/github-prs.yaml - - .github/ISSUE_TEMPLATE - - .github/PULL_REQUEST_TEMPLATE.md - priority_paths: - README.md - readme.md diff --git a/src/configs/detection-patterns.yaml b/src/configs/detection-patterns.yaml index da34972..1e0449d 100644 --- a/src/configs/detection-patterns.yaml +++ b/src/configs/detection-patterns.yaml @@ -9,4 +9,3 @@ config: env_var: ([A-Z][A-Z0-9_]{2,}=|\$\{[A-Z][A-Z0-9_]{2,}\}) workflow_contract: (workflow_call:|workflow_dispatch:|inputs:|outputs:) documentation_sections: (##[[:space:]]+(Quick Start|Usage|Development|Examples|Resources|Docs|Documentation)) - architecture_sections: (##[[:space:]]+(Architecture|Structure|Layout|Design)) diff --git a/src/configs/detection-signals.yaml b/src/configs/detection-signals.yaml index 31a201b..11c549e 100644 --- a/src/configs/detection-signals.yaml +++ b/src/configs/detection-signals.yaml @@ -101,68 +101,6 @@ config: - terraform - k8s - cd - architecture_layer_dirs: - - lib/commands - - lib/modules - - src/templates - - src/configs - - app/controllers - - app/models - - app/views - - app/services - - src/controllers - - src/models - - src/views - - src/services - - internal - - cmd - - templates - - configs - architecture_partial_dirs: - - lib - - src - - app - - modules - - services - - controllers - - models - - views - - templates - - configs - - docs - architecture_command_dirs: - - lib/commands - - app/controllers - - src/controllers - - cmd - architecture_logic_dirs: - - lib/modules - - app/models - - app/services - - src/models - - src/services - - internal - - modules - - services - architecture_view_dirs: - - src/templates - - app/views - - src/views - - templates - architecture_config_dirs: - - src/configs - - config - - configs - architecture_source_globs: - - *.sh - - *.js - - *.cjs - - *.mjs - - *.ts - - *.tsx - - *.php - - *.py - - *.rb verification_files: - phpunit.xml - phpunit.xml.dist @@ -208,7 +146,3 @@ config: - docker-compose.yaml - Chart.yaml - helmfile.yaml - architecture_command_max_lines: 120 - architecture_module_max_lines: 400 - architecture_present_category_min: 3 - architecture_partial_category_min: 2 diff --git a/src/configs/development-practices.yaml b/src/configs/development-practices.yaml index 5277bf9..385508d 100644 --- a/src/configs/development-practices.yaml +++ b/src/configs/development-practices.yaml @@ -13,6 +13,8 @@ config: message: Keep deterministic workflow logic in repo config and scripts, and reserve AI agents for reading that contract, generating grounded summaries, and handling non-deterministic judgment without inventing hidden rules. - id: context-over-memory message: Operate from repo-declared context at all times. Do not carry assumptions across sessions or rely on prompt history when the repo contract is available on disk. + - id: github-history-primary + message: After loading the repo contract, prefer current GitHub issues, pull requests, review state, and commit history as the primary dynamic source for agent decisions. Use repo workflow and practice catalogs as fallback defaults when live GitHub signal is missing or thin. - id: manifests-before-code message: When understanding behavior, read the YAML manifest that defines it before reading the code that implements it. Manifests are the interface — code is the mechanism. - id: reuse-over-invention diff --git a/src/configs/development-workflows.yaml b/src/configs/development-workflows.yaml index 20dba8c..eb114a8 100644 --- a/src/configs/development-workflows.yaml +++ b/src/configs/development-workflows.yaml @@ -37,7 +37,9 @@ config: environment state, and the AGENTS.md execution contract. A current context.yaml is the source of truth for refs, commands, gaps, and lessons. Do not rely on ad hoc prompt memory when the repo contract can be read - from disk. + from disk. When GitHub context is available, prefer current issues, + pull requests, review state, and commit history over stale memory or + generic workflow defaults. - id: issue_scope label: Read linked GitHub issue and confirm scope check: issue_scope diff --git a/src/configs/knowledge-base.yaml b/src/configs/knowledge-base.yaml index b5b9f81..d3284c7 100644 --- a/src/configs/knowledge-base.yaml +++ b/src/configs/knowledge-base.yaml @@ -5,16 +5,27 @@ config: hierarchy: local_repos_root: git/udx remote_org_root: github.com/udx + agent_experience: + order: + - repo_contract + - github_history + - repo_defaults + - lessons + notes: + - Start from the current repo contract on disk. + - Use live GitHub issues, pull requests, review state, and commit history as the primary dynamic source. + - Fall back to repo-owned workflow and practice catalogs when GitHub history is missing, sparse, or not applicable. + - Treat lessons as supporting memory, not as a source of truth. sources: preferred: items: - repo docs, configs, templates, and tests - repo TODO, context, and refs files when present + - remote repos, issues, pull requests, and commit history under github.com/udx/* - local repos under git/udx - - remote repos and pull requests under github.com/udx/* - codex sessions under ~/.codex/sessions when available github: - description: GitHub experience history enriches repo context with development signals beyond code + description: GitHub experience history is the primary dynamic input for agent decisions once the repo contract is loaded method: gh api (prefer REST API via gh api over gh subcommands for consistency and reliability) items: - open issues (scope, labels, assignees) diff --git a/tests/suite.sh b/tests/suite.sh index fc76421..a801086 100644 --- a/tests/suite.sh +++ b/tests/suite.sh @@ -109,13 +109,20 @@ if should_run "core"; then assert_contains "$agent_json" "\"archetype\":" "agent: auto-generates context on demand" assert_contains "$agent_json" "\"workflow_contract\":" "agent: reports workflow contract" + agent_text="$(cd "$SIMPLE_ACTION_REPO" && dev.kit agent)" + assert_contains "$agent_text" "dev.kit → dev.kit repo → dev.kit agent" "agent: text output reminds session resync flow" + context_yaml="${SIMPLE_ACTION_REPO}/.rabbit/context.yaml" assert_file_exists "$context_yaml" "agent: creates .rabbit/context.yaml" assert_contains "$(cat "$context_yaml")" "kind: repoContext" "agent: context.yaml has kind header" assert_contains "$(cat "$context_yaml")" "version: udx.io/dev.kit" "agent: context.yaml has version" assert_contains "$(cat "$context_yaml")" "refs:" "agent: context.yaml has refs section" + assert_contains "$(cat "$context_yaml")" "./package.json" "agent: context.yaml keeps repo refs" assert_not_contains "$(cat "$context_yaml")" "/Users/" "agent: context.yaml has no absolute paths (macOS)" assert_not_contains "$(cat "$context_yaml")" "/home/" "agent: context.yaml has no absolute paths (Linux)" + assert_contains "$(cat "${SIMPLE_ACTION_REPO}/AGENTS.md")" "Prefer live GitHub experience over generic defaults." "agent: AGENTS.md prefers live GitHub context" + assert_contains "$(cat "${SIMPLE_ACTION_REPO}/AGENTS.md")" 'All refs, config manifests, command surfaces, dependencies, and gaps live in `.rabbit/context.yaml`.' "agent: AGENTS.md points inventory back to context" + assert_not_contains "$(cat "${SIMPLE_ACTION_REPO}/AGENTS.md")" "### Priority refs" "agent: AGENTS.md does not duplicate refs" fi # ── archetypes ───────────────────────────────────────────────────────────────── From 50a08f0f7687450bd0c538e2a0e98b3e51c137e0 Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Fri, 17 Apr 2026 20:56:30 +0300 Subject: [PATCH 07/11] Refine repo context boundaries and GitHub workflow guidance --- .rabbit/context.yaml | 42 +-------- AGENTS.md | 14 +-- README.md | 19 +++- docs/agents.md | 27 +++++- docs/context.md | 19 ++-- docs/installation.md | 19 ++++ docs/integration.md | 18 ++-- docs/todo.md | 29 +++++++ lib/commands/agent.sh | 116 +++++++++++++++++++++---- lib/commands/learn.sh | 17 ++-- lib/modules/dev_sync.sh | 2 +- lib/modules/repo_scaffold.sh | 59 ------------- src/configs/development-practices.yaml | 10 ++- src/configs/development-workflows.yaml | 30 ++++++- src/configs/github-prs.yaml | 16 +++- src/configs/learning-workflows.yaml | 42 ++++++--- tests/suite.sh | 5 ++ 17 files changed, 323 insertions(+), 161 deletions(-) create mode 100644 docs/todo.md diff --git a/.rabbit/context.yaml b/.rabbit/context.yaml index 25d4883..972cd34 100644 --- a/.rabbit/context.yaml +++ b/.rabbit/context.yaml @@ -2,7 +2,7 @@ # Run `dev.kit repo` to refresh. kind: repoContext version: udx.io/dev.kit/v1 -generated: 2026-04-16 +generated: 2026-04-17 repo: name: dev.kit @@ -34,46 +34,6 @@ commands: gaps: - config (partial) -# Engineering practices -practices: - - "Keep the repository as the primary source of truth so context-driven engineering comes from repo contracts, docs, tests, config, and repo-native notes instead of agent memory." - - "Prefer repo-centric mechanisms that discover workflows, tools, formats, and refs dynamically instead of hardcoding per-agent assumptions." - - "Keep markdown, yaml, diagrams, tests, and command contracts self-contained in the repo so local and remote UDX workflows stay aligned." - - "Keep deterministic workflow logic in repo config and scripts, and reserve AI agents for reading that contract, generating grounded summaries, and handling non-deterministic judgment without inventing hidden rules." - - "Operate from repo-declared context at all times. Do not carry assumptions across sessions or rely on prompt history when the repo contract is available on disk." - - "After loading the repo contract, prefer current GitHub issues, pull requests, review state, and commit history as the primary dynamic source for agent decisions. Use repo workflow and practice catalogs as fallback defaults when live GitHub signal is missing or thin." - - "When understanding behavior, read the YAML manifest that defines it before reading the code that implements it. Manifests are the interface — code is the mechanism." - - "Check existing org patterns, configs, workflows, and templates before creating new ones. Reuse declared patterns instead of inventing alternatives." - - "Execute verification, builds, and tests locally before any remote operation. Local execution is part of the reproducible repo contract, not a preference." - - "Keep the delivery chain explicit — branch, PR, and issue must be connected before close-out. Do not treat any step as done until the link to the next step is visible." - - "Report outcomes with exact URLs, versions, findings deltas, and next steps so follow-up can be reused by humans and agents without drift." - - "Use README, docs, and tests as the first alignment surface before broad refactors. Read the declared workflow before changing the implementation." - - "Do not require custom repo files for dev.kit to work. Prefer standard engineering signals such as README, docs, tests, manifests, workflows, and deployment config, with dev.kit-owned continuity treated as optional acceleration only." - - "Express repo rules in YAML manifests first, then keep shell glue thin and composable. Policy belongs in config, not buried in imperative scripts." - - "When a new direction is accepted, archive or delete conflicting old modules and configs instead of carrying both models forward." - - "Run the smallest local check that proves the current change. Defer heavyweight coverage to CI and call that tradeoff out explicitly." - - "Make sure to develop and test incrementally, so it is easier to detect problems early and build on verified behavior." - - "Make sure to protect development executions with scoped and limited tasks, so failures are easier to isolate and blast radius stays low." - - "Use the linked GitHub issue as the cross-repo context root. When work spans multiple repos, the issue URL anchors scope, acceptance criteria, and follow-up across all of them." - -# Canonical agent workflow -workflow: - - "Refresh repo context: Run `dev.kit` → `dev.kit repo` → `dev.kit agent` before starting work. Each command guides to the next required step. This resyncs repo context, environment state, and the AGENTS.md execution contract. A current context.yaml is the source of truth for refs, commands, gaps, and lessons. Do not rely on ad hoc prompt memory when the repo contract can be read from disk. When GitHub context is available, prefer current issues, pull requests, review state, and commit history over stale memory or generic workflow defaults." - - "Read linked GitHub issue and confirm scope: If a GitHub issue URL is available, read the full body and comments, confirm the repo matches the issue scope, and map acceptance criteria before writing any code. Use the issue URL as the cross-repo context root." - - "Inspect git status" - - "Analyze local changes" - - "Analyze branch state" - - "Group logical commits" - - "Bump version and changelog if supported" - - "Create or validate feature branch" - - "Push branch to remote" - - "Generate pull request description: Pick the PR template type from src/configs/github-prs.yaml (feature, deployment, ops, hotfix). Fill every required section. Include \"Closes #N\" for linked issues. Add a \"Backlog from this investigation\" section for any new gaps found. Use .github/PULL_REQUEST_TEMPLATE.md as the base form." - - "Create pull request" - - "Read and respond to automated reviews: After PR creation, wait for Copilot, Devin, and CodeQL reviews. Read each review from github-prs.yaml bot guidance. Address actionable findings — reply to each bot comment. Do not request human review while bot findings are unaddressed." - - "Verify required status checks: All required checks must pass before requesting human review. For infra PRs, open check details and review the Terraform plan output. For CodeQL, review findings in the Security tab." - - "Post close-out comment on linked issue: After PR is created, post a brief comment on the linked issue with the PR URL, what changed, and any follow-up items. GitHub auto-closes the issue on merge when \"Closes #N\" is in the PR body — do not close manually." - - "Post-merge close-out and backlog: After merge: verify issue auto-closed, post close-out comment, open issues for any backlog items from the PR, verify monitoring changes are live. See post_merge steps in github-prs.yaml." - # External dependencies — cross-repo and upstream references # Trace these to find infrastructure, deployment, and build logic outside this repo. # Same-org deps are resolved with metadata. External deps listed for agent reference. diff --git a/AGENTS.md b/AGENTS.md index d196d25..43cf211 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,7 +12,7 @@ This repository is a deterministic execution contract. Agents MUST interpret dec 2. **Context boundaries are strict.** Read only files in Priority refs and Config manifests. If a file is not listed, do not read it unless a listed file explicitly references it. 3. **Manifests before code.** When you need to understand behavior, read the YAML manifest that defines it — not the code that implements it. Manifests are the interface. 4. **Context over memory.** Operate from repo-declared context. Do not carry assumptions from prior sessions or rely on prompt history when the contract is on disk. -5. **Verify locally before committing.** Run the verify command before reporting work as done. Local execution is part of the contract. +5. **Prefer workflow verification, not automatic local enforcement.** Detect the repo verify command from `context.yaml`, prefer GitHub workflow executions when the repo already has CI coverage, and use local verification to reproduce failures, debug quickly, or cover workflow gaps. 6. **Follow the Workflow below.** Do not invent ad hoc steps or skip phases. The workflow is the execution sequence. 7. **Reuse over invention.** Check existing org patterns, configs, and workflows before creating new ones. 8. **Prefer live GitHub experience over generic defaults.** After loading the repo contract, use current issues, pull requests, review state, and commit history as the primary dynamic source. Fall back to workflow and practice catalogs when GitHub signal is missing, thin, or irrelevant. @@ -61,6 +61,7 @@ The dev.kit lifecycle: **repo → agent → work → PR → merge**. Follow thes - Refresh repo context: Run `dev.kit` → `dev.kit repo` → `dev.kit agent` before starting work. Each command guides to the next required step. This resyncs repo context, environment state, and the AGENTS.md execution contract. A current context.yaml is the source of truth for refs, commands, gaps, and lessons. Do not rely on ad hoc prompt memory when the repo contract can be read from disk. When GitHub context is available, prefer current issues, pull requests, review state, and commit history over stale memory or generic workflow defaults. - Read linked GitHub issue and confirm scope: If a GitHub issue URL is available, read the full body and comments, confirm the repo matches the issue scope, and map acceptance criteria before writing any code. Use the issue URL as the cross-repo context root. + - Reuse GitHub repo patterns: Before creating a branch, PR, issue, or status update, inspect the repo's recent GitHub history and reuse its established naming and writing patterns. Treat existing branch names, PR titles and bodies, issue templates, and close-out comments as the default style guide. - Inspect git status - Analyze local changes - Analyze branch state @@ -70,8 +71,9 @@ The dev.kit lifecycle: **repo → agent → work → PR → merge**. Follow thes - Push branch to remote - Generate pull request description: Pick the PR template type from src/configs/github-prs.yaml (feature, deployment, ops, hotfix). Fill every required section. Include "Closes #N" for linked issues. Add a "Backlog from this investigation" section for any new gaps found. Use .github/PULL_REQUEST_TEMPLATE.md as the base form. - Create pull request - - Read and respond to automated reviews: After PR creation, wait for Copilot, Devin, and CodeQL reviews. Read each review from github-prs.yaml bot guidance. Address actionable findings — reply to each bot comment. Do not request human review while bot findings are unaddressed. - - Verify required status checks: All required checks must pass before requesting human review. For infra PRs, open check details and review the Terraform plan output. For CodeQL, review findings in the Security tab. + - Monitor related workflow executions: After PR creation, monitor the related GitHub workflow runs and status checks. Open the run details when needed, watch for failed or stuck jobs, and treat GitHub workflow execution as the primary verification path when the repo already has CI coverage. + - Loop automated review feedback: After PR creation, wait for Copilot, Devin, and CodeQL reviews. Read each review from github-prs.yaml bot guidance. Address actionable findings with code changes, reply to each bot comment, and resolve the thread when handled. Repeat this loop after each push until bot feedback is clean. Do not request human review while bot findings are unaddressed. + - Verify required status checks: All required checks must pass before requesting human review. For infra PRs, open check details and review the Terraform plan output. For CodeQL, review findings in the Security tab. When the repo already has GitHub workflow coverage, prefer those executions as the primary verification path and monitor them closely. Use local verification to reproduce failures or cover gaps, not as a universal gate. - Post close-out comment on linked issue: After PR is created, post a brief comment on the linked issue with the PR URL, what changed, and any follow-up items. GitHub auto-closes the issue on merge when "Closes #N" is in the PR body — do not close manually. - Post-merge close-out and backlog: After merge: verify issue auto-closed, post close-out comment, open issues for any backlog items from the PR, verify monitoring changes are live. See post_merge steps in github-prs.yaml. @@ -117,16 +119,18 @@ Patterns detected from agent sessions on this repo. Follow these in addition to - Keep deterministic workflow logic in repo config and scripts, and reserve AI agents for reading that contract, generating grounded summaries, and handling non-deterministic judgment without inventing hidden rules. - Operate from repo-declared context at all times. Do not carry assumptions across sessions or rely on prompt history when the repo contract is available on disk. - After loading the repo contract, prefer current GitHub issues, pull requests, review state, and commit history as the primary dynamic source for agent decisions. Use repo workflow and practice catalogs as fallback defaults when live GitHub signal is missing or thin. + - Reuse the repo's current GitHub patterns for branch names, PR titles and descriptions, issue writeups, and follow-up comments instead of inventing a new style for each change. - When understanding behavior, read the YAML manifest that defines it before reading the code that implements it. Manifests are the interface — code is the mechanism. - Check existing org patterns, configs, workflows, and templates before creating new ones. Reuse declared patterns instead of inventing alternatives. - - Execute verification, builds, and tests locally before any remote operation. Local execution is part of the reproducible repo contract, not a preference. + - Detect the repo's canonical verification surface from context, but prefer GitHub workflow executions and monitor their outcomes when the repo already has CI coverage. Use local verification for quick scoped debugging, missing CI coverage, or reproducing workflow failures. + - After a PR exists, read automated review feedback, fix actionable findings, reply to false positives, resolve threads, and repeat until workflow state and bot feedback are clean. - Keep the delivery chain explicit — branch, PR, and issue must be connected before close-out. Do not treat any step as done until the link to the next step is visible. - Report outcomes with exact URLs, versions, findings deltas, and next steps so follow-up can be reused by humans and agents without drift. - Use README, docs, and tests as the first alignment surface before broad refactors. Read the declared workflow before changing the implementation. - Do not require custom repo files for dev.kit to work. Prefer standard engineering signals such as README, docs, tests, manifests, workflows, and deployment config, with dev.kit-owned continuity treated as optional acceleration only. - Express repo rules in YAML manifests first, then keep shell glue thin and composable. Policy belongs in config, not buried in imperative scripts. - When a new direction is accepted, archive or delete conflicting old modules and configs instead of carrying both models forward. - - Run the smallest local check that proves the current change. Defer heavyweight coverage to CI and call that tradeoff out explicitly. + - If local verification is needed, run the smallest local check that proves the current change. Prefer broader or slower coverage in GitHub workflows, monitor the workflow run, and call the tradeoff out explicitly. - Make sure to develop and test incrementally, so it is easier to detect problems early and build on verified behavior. - Make sure to protect development executions with scoped and limited tasks, so failures are easier to isolate and blast radius stays low. - Use the linked GitHub issue as the cross-repo context root. When work spans multiple repos, the issue URL anchors scope, acceptance criteria, and follow-up across all of them. diff --git a/README.md b/README.md index a55ec1a..3a129d1 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ -**Simple session flow for developers and AI agents.** +**GitHub-first session flow for developers and AI agents.** dev.kit separates three concerns: @@ -12,6 +12,8 @@ dev.kit separates three concerns: It generates `.rabbit/context.yaml` as the structured repo contract, then generates `AGENTS.md` as a built execution artifact that tells agents how to use that context with current GitHub experience first, and repo-declared workflow defaults when GitHub does not provide enough signal. +In practice, dev.kit is middleware between repo facts and live GitHub experience. It keeps each work session anchored to the repo contract, then pushes developers and agents to use current issues, pull requests, review threads, workflow runs, and prior repo patterns before inventing new approaches. + ```bash npm install -g @udx/dev-kit ``` @@ -41,6 +43,14 @@ dev.kit repo # analyze factors, trace deps, write .rabbit/context.yaml dev.kit agent # generate AGENTS.md execution contract ``` +The intended operating loop is: + +1. install `dev.kit` +2. start work with `dev.kit`, `dev.kit repo`, and `dev.kit agent` +3. read `.rabbit/context.yaml` and `AGENTS.md` +4. do the actual implementation using current GitHub repo experience first +5. resync the same flow at the next interaction or after repo changes + --- ## Generated Context And Workflow @@ -75,6 +85,11 @@ gaps: **`AGENTS.md`** — generated execution artifact for agents. It should stay simpler than `context.yaml`: rules, workflow, verification, and how to use current GitHub and learned context without duplicating refs, manifests, or dependency maps already serialized in `context.yaml`. +Together, these two artifacts create a disciplined loop: + +- `context.yaml` says what the repo declares and what dev.kit could trace +- `AGENTS.md` says how to act on that contract using live GitHub experience first + --- ## Commands @@ -95,6 +110,8 @@ All commands support `--json` for machine-readable output. Repo context comes from repo source first: README, docs, workflows, manifests, tests, and other declared refs. `dev.kit repo` then traces and maps dependencies, commands, gaps, and other serializable signals into `context.yaml`. `AGENTS.md` turns that repo map into an operating contract for agents, using current GitHub context as the primary dynamic input and repo workflow/practice catalogs as fallback defaults. +That means dev.kit does not just tell an agent what files exist. It also pushes the session toward the repo's real delivery loop: branch naming based on repo history, issue and PR writing based on existing patterns, bot feedback loops, and workflow status checks before close-out. + ## Cross-repo tracing Traces dependencies from 6 sources: workflow reuse, GitHub actions, Docker images, versioned YAML, GitHub URLs, npm packages. diff --git a/docs/agents.md b/docs/agents.md index 666ab54..a955a59 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -43,9 +43,10 @@ Raw repo facts are not enough. Agents still need explicit operating instructions - what to read first - how to prioritize manifests over implementation - how to follow the repo workflow -- how to verify before reporting completion +- how to choose between GitHub workflow verification and local verification - how to use current GitHub history as the primary dynamic source - how to fall back to repo workflow, practice catalogs, and lessons without drifting +- how to loop on PR reviews, status checks, and follow-up comments until delivery is actually clean ## Inputs @@ -65,6 +66,8 @@ The intended decision order is: 3. repo-declared default workflows and practices 4. prior lessons and other secondary history +That order matters. `AGENTS.md` should keep agents from skipping straight to implementation when the repo already has issue history, open PR discussion, branch conventions, workflow results, or bot feedback that should shape the next action. + ## Main Sections The generated contract typically includes: @@ -90,6 +93,28 @@ That includes: - how an agent should sequence work and verification - how an agent should avoid scanning and guesswork +This is also where dev.kit can keep common GitHub-facing behaviors explicit, for example: + +- derive branch, issue, and PR naming from current repo patterns +- write PR bodies and issue updates in the style the repo already uses +- monitor workflow runs after a push +- read bot feedback, reply, fix, and resolve threads before human review + +Verification should follow the same priority: + +1. detect the repo's canonical verify surface from `context.yaml` +2. prefer GitHub workflow executions and monitor them when the repo already has CI coverage +3. use local verification when GitHub coverage is missing, when a workflow failure needs local reproduction, or when a quick scoped local check is the fastest way to debug + +So `AGENTS.md` should acknowledge local verify commands from repo context, but it should not enforce local execution as a universal rule. + +After a PR exists, the same contract should stay explicit: + +1. monitor related GitHub workflow executions and status checks +2. loop bot feedback on the PR +3. fix issues, reply to comments, and resolve threads +4. repeat until workflow state and bot feedback are clean + It should not restate: - priority refs diff --git a/docs/context.md b/docs/context.md index 5ec7b1b..7fa6f3e 100644 --- a/docs/context.md +++ b/docs/context.md @@ -21,7 +21,7 @@ Use it for facts such as: - detected gaps - manifests that define behavior - traced dependencies and where they are used -- workflow and practice data that can be emitted from repo-owned config +- GitHub-derived repo experience that can be serialized cleanly ## How It Is Produced @@ -70,14 +70,21 @@ The generated file in this repo currently includes: - `refs` - `commands` - `gaps` -- `practices` -- `workflow` - `dependencies` - `manifests` - `lessons` Depending on available integrations, it may also include GitHub-derived data. GitHub belongs here only when it can be fetched and serialized as repo experience data. It does not replace the repo contract. +Examples of GitHub-derived data that fit here: + +- open pull requests +- recent pull request history +- linked issue references +- repo URLs that anchor the current work + +Those belong here because they can be serialized as current repo experience. Review decisions, step-by-step agent behavior, and how to respond to live findings still belong in `AGENTS.md`. + ## What Each Section Means `repo` identifies the repository through values such as `name`, `archetype`, and `profile`. @@ -94,8 +101,6 @@ This is the only place refs should live. `AGENTS.md` should point to `context.ya `manifests` lists the config files that define repo behavior. In `dev.kit`, these are first-class interfaces. -`practices` and `workflow` are still structured repo data. They come from repo-owned catalogs, not from prompt-time improvisation. They are repo-declared defaults that agents can fall back to when current GitHub history is thin or absent. - `lessons` links prior session artifacts produced by `dev.kit learn`. ## What Does Not Belong Here @@ -107,6 +112,8 @@ It is not where you explain: - how an agent should interpret ambiguity - how an agent should sequence work for a user - how an agent should balance repo context against current task context +- how an agent should loop on bot review comments +- how an agent should decide between local verification and GitHub workflow verification That layer belongs in `AGENTS.md`. @@ -121,7 +128,7 @@ It should let an agent answer questions like: - What repo signals were used? - What dependencies are real, and where are they used? - Which engineering factors are missing? -- What workflow defaults are already declared by the repo? +- Which repo facts and traced signals are already available? If that data is available in `context.yaml`, the agent does not need to rediscover it by scanning. diff --git a/docs/installation.md b/docs/installation.md index 1d3ea26..6c85326 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -7,6 +7,16 @@ Whichever path you use last becomes the active install. The installer cleans up the other path first so one install owns `dev.kit` at a time. +Installation only puts the command on the machine. The normal operating loop starts after install: + +```bash +dev.kit +dev.kit repo +dev.kit agent +``` + +That loop refreshes repo context, regenerates `AGENTS.md`, and makes the next work step explicit before an agent or developer starts changing the repo. + ## Recommended Path Use npm when it is available: @@ -92,3 +102,12 @@ dev.kit ``` That confirms the command resolves correctly and shows the next step in the session flow. + +After that, continue with: + +```bash +dev.kit repo +dev.kit agent +``` + +The goal is not only to confirm that the binary works. The goal is to start the session from current repo contract and current GitHub-aware workflow guidance rather than stale local memory. diff --git a/docs/integration.md b/docs/integration.md index dc9d01c..5661876 100644 --- a/docs/integration.md +++ b/docs/integration.md @@ -4,6 +4,8 @@ The goal is not to generate more files. The goal is to reduce uncertainty about what exists, what matters, and how to act. +Another way to say it: dev.kit is middleware between repo-declared context and live GitHub experience. It keeps agents and developers grounded in the repo contract, then points them toward the current issue, PR, review, and workflow state that should drive the next decision. + ## Core Flow The integration model starts with three commands: @@ -14,7 +16,7 @@ dev.kit repo dev.kit agent ``` -Those commands connect four layers: +Those commands connect five layers: 1. local environment detection 2. structured repo context generation @@ -40,7 +42,7 @@ That separation keeps both artifacts smaller and more reliable. In practice: - `context.yaml` owns refs, manifests, commands, dependencies, and gaps -- `AGENTS.md` points back to `context.yaml` and stays focused on behavior +- `AGENTS.md` points back to `context.yaml` and stays focused on workflow, practices, and behavior ## Developer Integration @@ -53,6 +55,8 @@ For developers, `dev.kit` provides: This reduces time spent rediscovering how a repo works. +It also shortens common GitHub loops. Instead of inventing a new branch name, PR structure, or issue update style each time, the repo contract can point the session back to current repo patterns and current review state first. + ## Agent Integration For agents, `dev.kit` provides: @@ -64,6 +68,8 @@ For agents, `dev.kit` provides: This means agents can spend less effort on discovery and more effort on scoped execution. +That execution should stay GitHub-aware. The intended behavior is not just "read files, then code." It is "refresh repo contract, inspect current GitHub experience, act, then loop on workflows and automated review until the change is actually ready." + ## GitHub And History GitHub and learning data are most useful when they support agent decisions, not when they blur the repo map. @@ -83,9 +89,11 @@ The generated workflow is intended to fit into normal engineering work: 1. start the session with `dev.kit`, `dev.kit repo`, and `dev.kit agent` 2. read the generated repo contract and agent contract -3. do the actual implementation or review work -4. verify with repo-declared commands -5. optionally run `dev.kit learn` so session outcomes feed future runs +3. inspect current GitHub issue, PR, review, and branch context before inventing a new path +4. do the actual implementation or review work +5. verify through the repo-declared surface, preferring GitHub workflow runs when the repo already has CI coverage +6. loop on bot reviews, workflow failures, and follow-up comments until the delivery chain is clean +7. optionally run `dev.kit learn` so session outcomes feed future runs ## Config-Driven Integration diff --git a/docs/todo.md b/docs/todo.md new file mode 100644 index 0000000..c2ef286 --- /dev/null +++ b/docs/todo.md @@ -0,0 +1,29 @@ +# dev.kit improvement backlog + +## Product direction + +- [ ] Keep `dev.kit` centered on GitHub-first development and agent execution. +- [ ] Make the session contract explicit: each work session should start with `dev.kit`, `dev.kit repo`, and `dev.kit agent`, then continue from `context.yaml` and `AGENTS.md`. +- [ ] Keep the product simple. `dev.kit` should stay middleware between repo-declared context and live GitHub experience, not a second workflow system. + +## GitHub pattern reuse + +- [ ] Generate branch names from current repo naming patterns. +- [ ] Generate PR titles and descriptions from recent repo PR style and structure. +- [ ] Generate issue titles and descriptions from recent repo issue style and structure. +- [ ] Generate issue and PR comments from existing repo follow-up and close-out patterns. + +## Review and verification loop + +- [ ] Make bot-review handling explicit: read feedback from Copilot, CodeQL, Devin, and similar reviewers, fix or reply, then resolve threads. +- [ ] Make workflow monitoring explicit: inspect related GitHub workflow runs after pushes and use failures as a fix loop, not just a status badge. +- [ ] Keep local verification scoped and lightweight when GitHub workflows already provide the primary verification surface. + +## History-aware debugging + +- [ ] When debugging, use related issues, PRs, and commit history to understand prior changes and possible regressions before inventing a new theory. +- [ ] Use the linked GitHub issue as the cross-repo context root when work spans multiple repos. + +## Why this matters + +`dev.kit` should keep reminding agents to use dev, team, and org experience from GitHub repos as part of the actual work loop. It should also surface repo gaps and push that learning back into repo contracts so the next session starts from better context. diff --git a/lib/commands/agent.sh b/lib/commands/agent.sh index 2a4d620..3b09469 100644 --- a/lib/commands/agent.sh +++ b/lib/commands/agent.sh @@ -83,6 +83,97 @@ dev_kit_cmd_agent() { dev_kit_output_list_item "Run dev.kit → dev.kit repo → dev.kit agent at each new interaction or after repo updates to resync." } +dev_kit_agent_context_list() { + local context_yaml="$1" + local section_name="$2" + + awk -v section_name="$section_name" ' + $0 == section_name ":" { in_section = 1; next } + in_section && /^[a-zA-Z#]/ { exit } + in_section && /^ - / { + gsub(/^ - "/, " - ") + sub(/"$/, "") + gsub(/\\"/, "\"") + gsub(/\\\\/, "\\") + print + } + ' "$context_yaml" +} + +dev_kit_agent_context_multiline_block() { + local context_yaml="$1" + local section_name="$2" + + awk -v section_name="$section_name" ' + $0 == section_name ":" { in_section = 1; next } + in_section && /^[a-zA-Z#]/ { exit } + in_section { print } + ' "$context_yaml" +} + +dev_kit_agent_github_section() { + local context_yaml="$1" + local section_name="$2" + + awk -v key="^ " section_name ":" ' + $0 ~ key { in_section = 1; next } + in_section && /^ - / { + sub(/^ - "?/, " - ") + sub(/"$/, "") + gsub(/\\"/, "\"") + gsub(/\\\\/, "\\") + print + next + } + in_section && /^[^ ]|^ [a-z]/ { exit } + ' "$context_yaml" +} + +dev_kit_agent_practice_lines() { + local practices_file="" + practices_file="$(dev_kit_practices_config_path)" + [ -f "$practices_file" ] || return 0 + + awk ' + $1 == "config:" { in_config = 1; next } + in_config && $1 == "practices:" { in_practices = 1; next } + in_practices && $1 == "-" && $2 == "id:" { next } + in_practices && $1 == "message:" { + $1 = "" + sub(/^ /, "") + printf " - %s\n", $0 + } + ' "$practices_file" +} + +dev_kit_agent_workflow_lines() { + local workflow_file="" + workflow_file="$(dev_kit_workflow_config_path)" + + if [ -f "$workflow_file" ]; then + awk ' + /^ - id:/ { flush(); label=""; note=""; in_note=0; next } + /^ label:/ { sub(/^[[:space:]]*label:[[:space:]]*/, "", $0); label=$0; next } + /^ note:[[:space:]]*>/ { in_note=1; next } + in_note && /^ / { + sub(/^[[:space:]]+/, "", $0) + note = (note == "") ? $0 : note " " $0 + next + } + in_note { flush(); in_note=0 } + function flush() { + if (label == "") return + if (note != "") printf " - %s: %s\n", label, note + else printf " - %s\n", label + } + END { flush() } + ' "$workflow_file" + return 0 + fi + + dev_kit_repo_workflow_json "${1:-$(pwd)}" | jq -r '.[]? | " - " + .label' 2>/dev/null || true +} + # Write AGENTS.md — the repo's execution contract for AI agents. # All content is derived from context.yaml. Agents operate from this file, # not from filesystem discovery. @@ -107,7 +198,7 @@ dev_kit_agent_write_agents_md() { printf '2. **Context boundaries are strict.** Read only files in Priority refs and Config manifests. If a file is not listed, do not read it unless a listed file explicitly references it.\n' printf '3. **Manifests before code.** When you need to understand behavior, read the YAML manifest that defines it — not the code that implements it. Manifests are the interface.\n' printf '4. **Context over memory.** Operate from repo-declared context. Do not carry assumptions from prior sessions or rely on prompt history when the contract is on disk.\n' - printf '5. **Verify locally before committing.** Run the verify command before reporting work as done. Local execution is part of the contract.\n' + printf '5. **Prefer workflow verification, not automatic local enforcement.** Detect the repo verify command from `context.yaml`, prefer GitHub workflow executions when the repo already has CI coverage, and use local verification to reproduce failures, debug quickly, or cover workflow gaps.\n' printf '6. **Follow the Workflow below.** Do not invent ad hoc steps or skip phases. The workflow is the execution sequence.\n' printf '7. **Reuse over invention.** Check existing org patterns, configs, and workflows before creating new ones.\n' printf '8. **Prefer live GitHub experience over generic defaults.** After loading the repo contract, use current issues, pull requests, review state, and commit history as the primary dynamic source. Fall back to workflow and practice catalogs when GitHub signal is missing, thin, or irrelevant.\n' @@ -126,7 +217,7 @@ dev_kit_agent_write_agents_md() { # ── commands ───────────────────────────────────────────────────────────── local _cmds - _cmds="$(awk '/^commands:/{f=1;next} f && /^[a-zA-Z#]/{f=0} f' "$context_yaml")" + _cmds="$(dev_kit_agent_context_multiline_block "$context_yaml" "commands")" if [ -n "$_cmds" ]; then printf '### Commands\n\n```\n%s\n```\n\n' "$_cmds" fi @@ -144,27 +235,22 @@ dev_kit_agent_write_agents_md() { printf '### GitHub context\n\n' printf 'Development signals from [%s](https://github.com/%s). Treat this as the primary dynamic source for current repo experience.\n\n' "$_gh_repo" "$_gh_repo" - # Helper: extract github subsection, strip indent and YAML quotes for markdown - _gh_extract() { - awk -v key="^ ${1}:" '$0 ~ key {f=1;next} f && /^ - /{sub(/^ - "?/, " - "); sub(/"$/, ""); gsub(/\\"/, "\""); gsub(/\\\\/, "\\"); print; next} f && /^[^ ]|^ [a-z]/{f=0}' "$context_yaml" - } - - _gh_section="$(_gh_extract open_issues)" + _gh_section="$(dev_kit_agent_github_section "$context_yaml" "open_issues")" [ -n "$_gh_section" ] && printf '**Open issues:**\n\n%s\n\n' "$_gh_section" - _gh_section="$(_gh_extract open_prs)" + _gh_section="$(dev_kit_agent_github_section "$context_yaml" "open_prs")" [ -n "$_gh_section" ] && printf '**Open PRs:**\n\n%s\n\n' "$_gh_section" - _gh_section="$(_gh_extract recent_prs)" + _gh_section="$(dev_kit_agent_github_section "$context_yaml" "recent_prs")" [ -n "$_gh_section" ] && printf '**Recent PRs:**\n\n%s\n\n' "$_gh_section" - _gh_section="$(_gh_extract security_alerts)" + _gh_section="$(dev_kit_agent_github_section "$context_yaml" "security_alerts")" [ -n "$_gh_section" ] && printf '**Security alerts:**\n\n%s\n\n' "$_gh_section" fi # ── gaps ───────────────────────────────────────────────────────────────── local _gaps - _gaps="$(awk '/^gaps:/{f=1;next} f && /^[a-zA-Z#]/{f=0} f && /^ - /' "$context_yaml")" + _gaps="$(dev_kit_agent_context_list "$context_yaml" "gaps")" if [ -n "$_gaps" ]; then printf '### Gaps\n\n' printf 'Incomplete factors. Address within the workflow, not as separate tasks.\n\n' @@ -173,7 +259,7 @@ dev_kit_agent_write_agents_md() { # ── Versioned workflow artifacts ───────────────────────────────────────── local _lessons - _lessons="$(awk '/^lessons:/{f=1;next} f && /^[a-zA-Z#]/{f=0} f && /^ - /' "$context_yaml")" + _lessons="$(dev_kit_agent_context_list "$context_yaml" "lessons")" printf '## Versioned workflow artifacts\n\n' printf '`.rabbit/` contains generated context downstream of repo signals. These are versioned artifacts, not primary sources.\n\n' printf ' - `.rabbit/context.yaml` — generated execution contract (source of truth for this file)\n' @@ -185,7 +271,7 @@ dev_kit_agent_write_agents_md() { # ── Execution — workflow ───────────────────────────────────────────────── local _workflow - _workflow="$(awk '/^workflow:/{f=1;next} f && /^[a-zA-Z#]/{f=0} f && /^ - /{gsub(/^ - "/, " - "); sub(/"$/, ""); gsub(/\\"/, "\""); gsub(/\\\\/, "\\"); print}' "$context_yaml")" + _workflow="$(dev_kit_agent_workflow_lines "$repo_dir")" if [ -n "$_workflow" ]; then printf '## Workflow\n\n' printf 'The dev.kit lifecycle: **repo → agent → work → PR → merge**. Follow these steps in order. Use them as repo-declared defaults when live GitHub context does not provide a more specific current signal. Steps with notes contain operational guidance.\n\n' @@ -285,7 +371,7 @@ EOF # ── Principles — engineering practices ─────────────────────────────────── local _practices - _practices="$(awk '/^practices:/{f=1;next} f && /^[a-zA-Z#]/{f=0} f && /^ - /{gsub(/^ - "/, " - "); sub(/"$/, ""); gsub(/\\"/, "\""); gsub(/\\\\/, "\\"); print}' "$context_yaml")" + _practices="$(dev_kit_agent_practice_lines)" if [ -n "$_practices" ]; then printf '## Engineering practices\n\n%s\n\n' "$_practices" fi diff --git a/lib/commands/learn.sh b/lib/commands/learn.sh index 0f0d064..c7903ff 100644 --- a/lib/commands/learn.sh +++ b/lib/commands/learn.sh @@ -352,7 +352,11 @@ dev_kit_learning_merge_unique_lines() { { gsub(/^[[:space:]]+|[[:space:]]+$/, "", $0) if ($0 == "") next - if (seen[$0]++) next + key = $0 + if (match($0, /^`[^`]+`:/)) { + key = substr($0, RSTART, RLENGTH) + } + if (seen[key]++) next print } ' @@ -423,15 +427,15 @@ dev_kit_learning_flow_template() { issue-scope) printf '%s' '`Issue-to-scope`: start from the linked issue, confirm repo/workspace match, and restate the exact scope before changing code.' ;; - workflow-source) - printf '%s' '`Workflow tracing`: locate the actual workflow file or deploy source first, then trace the commands and supporting docs that really drive execution.' - ;; verify-before-sync) - printf '%s' '`Verify-before-sync`: run the relevant local build/test check before syncing, reporting completion, or preparing the PR.' + printf '%s' '`Verify-before-sync`: detect the repo verification surface, prefer GitHub workflow runs when the repo already has CI coverage, and use local checks for scoped debugging or reproduction.' ;; pr-chain) printf '%s' '`Delivery chain`: sync the branch, prepare the PR in repo style, and connect the related issue before close-out.' ;; + github-style-reuse) + printf '%s' '`GitHub style reuse`: inspect recent branch names, PRs, issues, and close-out comments, then reuse the repo'\''s current naming and writing patterns.' + ;; post-follow-up) printf '%s' '`Post-merge follow-up`: gather release/workflow evidence and post a concise update with links, findings delta, and next steps.' ;; @@ -450,6 +454,9 @@ dev_kit_learning_flow_template() { agent-handoff) printf '%s' '`Agent handoff`: refresh repo context, manifests, and AGENTS.md before deeper agent work so the repo contract is the source of truth.' ;; + history-debugging) + printf '%s' '`History-aware debugging`: use related issues, PRs, and recent repo history first to understand prior changes and likely regressions before widening scope.' + ;; *) printf '%s' "$1" ;; diff --git a/lib/modules/dev_sync.sh b/lib/modules/dev_sync.sh index 4b32165..73cbc2d 100644 --- a/lib/modules/dev_sync.sh +++ b/lib/modules/dev_sync.sh @@ -280,7 +280,7 @@ dev_kit_sync_hook_recommendation() { fi if [ "$hook_name" = "pre-push" ] && rg -n "bash tests/run.sh" "$hook_file" >/dev/null 2>&1; then - printf "%s" "Before push, make sure the local verification runtime is ready for bash tests/run.sh." + printf "%s" "Before push, identify the repo verification surface; prefer GitHub workflow runs when available, and use local execution to reproduce or isolate failures." return 0 fi diff --git a/lib/modules/repo_scaffold.sh b/lib/modules/repo_scaffold.sh index 271820e..b92e81a 100644 --- a/lib/modules/repo_scaffold.sh +++ b/lib/modules/repo_scaffold.sh @@ -329,65 +329,6 @@ dev_kit_context_yaml_write() { printf '%s\n\n' "$_gaps_yaml" fi - # Practices — inlined from dev.kit development-practices.yaml - local _practices_file _practices_yaml - _practices_file="$(dev_kit_config_path "$DEV_KIT_PRACTICES_CONFIG_FILE")" - if [ -f "$_practices_file" ]; then - _practices_yaml="$(awk ' - /^ practices:/ { in_p=1; next } - in_p && /^ [a-zA-Z]/ { in_p=0 } - in_p && /^ message:/ { - sub(/^[[:space:]]*message:[[:space:]]*/, "", $0) - gsub(/"/, "\\\"", $0) - printf " - \"%s\"\n", $0 - } - ' "$_practices_file")" - if [ -n "$_practices_yaml" ]; then - printf '# Engineering practices\n' - printf 'practices:\n' - printf '%s\n\n' "$_practices_yaml" - fi - fi - - # Workflow — inlined from dev.kit development-workflows.yaml with operational notes - local _workflow_file _workflow_yaml - _workflow_file="$(dev_kit_config_path "$DEV_KIT_WORKFLOW_CONFIG_FILE")" - if [ -f "$_workflow_file" ]; then - _workflow_yaml="$(awk ' - /^ - id:/ { flush(); label=""; note=""; in_note=0 } - /^ label:/ { sub(/^[[:space:]]*label:[[:space:]]*/, "", $0); label=$0 } - /^ note:[[:space:]]*>/ { in_note=1; next } - in_note && /^ / { - sub(/^[[:space:]]+/, "", $0) - note = (note == "") ? $0 : note " " $0 - next - } - in_note { flush(); in_note=0 } - function flush() { - if (label != "") { - gsub(/"/, "\\\"", label) - gsub(/"/, "\\\"", note) - if (note != "") printf " - \"%s: %s\"\n", label, note - else printf " - \"%s\"\n", label - } - } - END { flush() } - ' "$_workflow_file")" - if [ -n "$_workflow_yaml" ]; then - printf '# Canonical agent workflow\n' - printf 'workflow:\n' - printf '%s\n\n' "$_workflow_yaml" - fi - else - # Fallback to repo-derived steps when dev.kit workflow config is absent - local _fallback_yaml - _fallback_yaml="$(dev_kit_repo_workflow_json "$repo_root" | jq -r '.[]? | " - " + .label' 2>/dev/null)" - if [ -n "$_fallback_yaml" ]; then - printf 'workflow:\n' - printf '%s\n\n' "$_fallback_yaml" - fi - fi - # ── External dependencies — structured cross-repo tracing ────────────── # Collect (dep_id|type|source_file) triples from multiple sources, # then group by dep and resolve same-org repos for rich metadata. diff --git a/src/configs/development-practices.yaml b/src/configs/development-practices.yaml index 385508d..183e57a 100644 --- a/src/configs/development-practices.yaml +++ b/src/configs/development-practices.yaml @@ -15,12 +15,16 @@ config: message: Operate from repo-declared context at all times. Do not carry assumptions across sessions or rely on prompt history when the repo contract is available on disk. - id: github-history-primary message: After loading the repo contract, prefer current GitHub issues, pull requests, review state, and commit history as the primary dynamic source for agent decisions. Use repo workflow and practice catalogs as fallback defaults when live GitHub signal is missing or thin. + - id: github-style-reuse + message: Reuse the repo's current GitHub patterns for branch names, PR titles and descriptions, issue writeups, and follow-up comments instead of inventing a new style for each change. - id: manifests-before-code message: When understanding behavior, read the YAML manifest that defines it before reading the code that implements it. Manifests are the interface — code is the mechanism. - id: reuse-over-invention message: Check existing org patterns, configs, workflows, and templates before creating new ones. Reuse declared patterns instead of inventing alternatives. - - id: localhost-first - message: Execute verification, builds, and tests locally before any remote operation. Local execution is part of the reproducible repo contract, not a preference. + - id: workflow-first-verification + message: Detect the repo's canonical verification surface from context, but prefer GitHub workflow executions and monitor their outcomes when the repo already has CI coverage. Use local verification for quick scoped debugging, missing CI coverage, or reproducing workflow failures. + - id: bot-feedback-loop + message: After a PR exists, read automated review feedback, fix actionable findings, reply to false positives, resolve threads, and repeat until workflow state and bot feedback are clean. - id: delivery-chain-traceability message: Keep the delivery chain explicit — branch, PR, and issue must be connected before close-out. Do not treat any step as done until the link to the next step is visible. - id: structured-outcome-reporting @@ -34,7 +38,7 @@ config: - id: legacy-reduction message: When a new direction is accepted, archive or delete conflicting old modules and configs instead of carrying both models forward. - id: verification-scope - message: Run the smallest local check that proves the current change. Defer heavyweight coverage to CI and call that tradeoff out explicitly. + message: If local verification is needed, run the smallest local check that proves the current change. Prefer broader or slower coverage in GitHub workflows, monitor the workflow run, and call the tradeoff out explicitly. - id: incremental-development message: Make sure to develop and test incrementally, so it is easier to detect problems early and build on verified behavior. - id: scoped-execution diff --git a/src/configs/development-workflows.yaml b/src/configs/development-workflows.yaml index eb114a8..6d63fac 100644 --- a/src/configs/development-workflows.yaml +++ b/src/configs/development-workflows.yaml @@ -48,6 +48,15 @@ config: If a GitHub issue URL is available, read the full body and comments, confirm the repo matches the issue scope, and map acceptance criteria before writing any code. Use the issue URL as the cross-repo context root. + - id: github_pattern_reuse + label: Reuse GitHub repo patterns + check: github_pattern_reuse + optional: true + note: > + Before creating a branch, PR, issue, or status update, inspect the + repo's recent GitHub history and reuse its established naming and + writing patterns. Treat existing branch names, PR titles and bodies, + issue templates, and close-out comments as the default style guide. - id: worktree_status label: Inspect git status check: git_status @@ -80,15 +89,25 @@ config: - id: pr_create label: Create pull request check: pr_create + - id: workflow_monitor + label: Monitor related workflow executions + check: workflow_monitor + optional: true + note: > + After PR creation, monitor the related GitHub workflow runs and status + checks. Open the run details when needed, watch for failed or stuck jobs, + and treat GitHub workflow execution as the primary verification path when + the repo already has CI coverage. - id: bot_review - label: Read and respond to automated reviews + label: Loop automated review feedback check: bot_review optional: true note: > After PR creation, wait for Copilot, Devin, and CodeQL reviews. Read each review from github-prs.yaml bot guidance. Address actionable - findings — reply to each bot comment. Do not request human review while - bot findings are unaddressed. + findings with code changes, reply to each bot comment, and resolve the + thread when handled. Repeat this loop after each push until bot feedback + is clean. Do not request human review while bot findings are unaddressed. - id: checks_verify label: Verify required status checks check: checks_verify @@ -96,7 +115,10 @@ config: note: > All required checks must pass before requesting human review. For infra PRs, open check details and review the Terraform plan output. - For CodeQL, review findings in the Security tab. + For CodeQL, review findings in the Security tab. When the repo already + has GitHub workflow coverage, prefer those executions as the primary + verification path and monitor them closely. Use local verification to + reproduce failures or cover gaps, not as a universal gate. - id: issue_update label: Post close-out comment on linked issue check: issue_update diff --git a/src/configs/github-prs.yaml b/src/configs/github-prs.yaml index fcce583..d6ff27d 100644 --- a/src/configs/github-prs.yaml +++ b/src/configs/github-prs.yaml @@ -185,10 +185,12 @@ config: # ── Agent workflow for PRs ────────────────────────────────────────────────── agent_workflow: before_creating: - - id: verify-locally + - id: verify-surface message: > - Run the canonical verify command (make test or equivalent) locally before - pushing. Do not open a PR with failing local checks. + Detect the canonical verify command from repo context and note it in your + working plan, but prefer GitHub workflow executions when the repo already + has CI coverage. Use local verification for scoped debugging, reproducing + workflow failures, or covering gaps in workflow coverage. - id: pick-template message: > Pick the PR template type (feature, deployment, ops, hotfix) that matches @@ -200,6 +202,12 @@ config: (cross-repo dependencies), call them out explicitly in the PR body. after_creating: + - id: monitor-workflows + message: > + After the PR is created, monitor the related GitHub workflow runs and + status checks. Open failing or slow runs, review the logs, and treat + workflow execution as the primary verification path when the repo already + has CI coverage. - id: read-bot-reviews message: > After the PR is created, wait for automated reviews: Copilot, Devin, @@ -208,7 +216,7 @@ config: with brief explanations. Resolve every conversation thread after addressing it — unresolved threads block merge even when all checks pass. Loop through bot feedback after each push until all threads are - resolved and merge state is CLEAN. + resolved, comments are answered, and merge state is CLEAN. - id: check-status message: > Verify all required status checks pass. For infrastructure PRs, open diff --git a/src/configs/learning-workflows.yaml b/src/configs/learning-workflows.yaml index d954eb5..780ac28 100644 --- a/src/configs/learning-workflows.yaml +++ b/src/configs/learning-workflows.yaml @@ -13,7 +13,7 @@ config: workflows: pr-lessons: name: dev.learn pr - description: Generate lightweight lessons-learned from recent pull requests and route follow-ups into durable repo artifacts + description: Generate lightweight lessons-learned from recent pull requests and agent sessions, then route reusable workflow patterns into durable repo artifacts sources: - recent pull requests - docs/pull-requests.md @@ -33,16 +33,9 @@ config: - /issues/ - issue details - affected code path - workflow-source: - threshold: 2 - message: Locate the repo workflow source that actually drives execution, such as deploy.yml or an explicit workflow file. - patterns: - - deploy.yml - - workflow - - what deploy.yml actually does verify-before-sync: threshold: 2 - message: Run local verification before syncing or reporting completion. + message: Prefer GitHub workflow verification when the repo has CI coverage, monitor the run, and use local verification only when you need a quick scoped check or a reproduction path. patterns: - make build - confirm build @@ -54,6 +47,14 @@ config: - sync to remote - brief pr - related github issue + github-style-reuse: + threshold: 2 + message: Before creating a branch, PR, issue, or GitHub update, inspect recent repo history and reuse the repo's established naming and writing patterns. + patterns: + - previous prs + - repo style + - branch name + - title and description post-follow-up: threshold: 2 message: After merge or release, collect workflow and artifact evidence, then post a concise linked update with next steps. @@ -75,12 +76,15 @@ config: message: Locate the actual workflow or deploy file first, then trace the commands and supporting docs that drive execution. patterns: - deploy.yml + - .github/workflows - workflow file + - workflow gaps + - what deploy.yml actually does - what actually runs - trace verification-scope: threshold: 2 - message: Run the smallest local check that proves the current change, defer heavyweight coverage to CI, and call the tradeoff out explicitly. + message: If local verification is needed, run the smallest local check that proves the current change. Prefer broader or slower coverage in GitHub workflows, monitor the run, and call the tradeoff out explicitly. patterns: - make test - local check @@ -102,10 +106,18 @@ config: - dev.kit agent - refresh context - agents.md + history-debugging: + threshold: 2 + message: When debugging or widening scope, use related GitHub issues, PRs, and recent repo history first to understand prior changes and possible regressions. + patterns: + - previous changes + - breaking change + - related prs + - debug session_rules: verify-before-deploy: threshold: 2 - message: Verify the build or runtime locally before running deploy-oriented workflow assets or reporting the change as complete. + message: Prefer the repo's GitHub workflow executions for build or runtime verification before deploy-oriented steps, and use local verification when you need to reproduce or isolate a failure. patterns: - make build - confirm build @@ -124,6 +136,14 @@ config: - sync to remote - brief pr - related github issue + bot-review-loop: + threshold: 2 + message: After a PR exists, read automated review feedback, fix actionable findings, reply to false positives, resolve the threads, and repeat until bot feedback is clean. + patterns: + - codeql + - copilot + - devin + - review comment source-backed-updates: threshold: 3 message: Report outcomes with exact URLs, versions, findings deltas, and next steps so the follow-up can be reused by humans and agents without drift. diff --git a/tests/suite.sh b/tests/suite.sh index a801086..3f474b6 100644 --- a/tests/suite.sh +++ b/tests/suite.sh @@ -120,7 +120,12 @@ if should_run "core"; then assert_contains "$(cat "$context_yaml")" "./package.json" "agent: context.yaml keeps repo refs" assert_not_contains "$(cat "$context_yaml")" "/Users/" "agent: context.yaml has no absolute paths (macOS)" assert_not_contains "$(cat "$context_yaml")" "/home/" "agent: context.yaml has no absolute paths (Linux)" + assert_not_contains "$(cat "$context_yaml")" "practices:" "agent: context.yaml does not inline engineering practices" + assert_not_contains "$(cat "$context_yaml")" "workflow:" "agent: context.yaml does not inline agent workflow" assert_contains "$(cat "${SIMPLE_ACTION_REPO}/AGENTS.md")" "Prefer live GitHub experience over generic defaults." "agent: AGENTS.md prefers live GitHub context" + assert_contains "$(cat "${SIMPLE_ACTION_REPO}/AGENTS.md")" "Prefer workflow verification, not automatic local enforcement." "agent: AGENTS.md prefers workflow verification" + assert_contains "$(cat "${SIMPLE_ACTION_REPO}/AGENTS.md")" "Monitor related workflow executions" "agent: AGENTS.md includes workflow monitoring loop" + assert_contains "$(cat "${SIMPLE_ACTION_REPO}/AGENTS.md")" "Loop automated review feedback" "agent: AGENTS.md includes bot feedback loop" assert_contains "$(cat "${SIMPLE_ACTION_REPO}/AGENTS.md")" 'All refs, config manifests, command surfaces, dependencies, and gaps live in `.rabbit/context.yaml`.' "agent: AGENTS.md points inventory back to context" assert_not_contains "$(cat "${SIMPLE_ACTION_REPO}/AGENTS.md")" "### Priority refs" "agent: AGENTS.md does not duplicate refs" fi From ff1abbe421da00aa452b03575428e96b7e610856 Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Fri, 17 Apr 2026 21:14:05 +0300 Subject: [PATCH 08/11] Bump version to 0.8.0 and update changes --- changes.md | 7 +++++++ package.json | 2 +- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/changes.md b/changes.md index 01ac195..100ab7b 100644 --- a/changes.md +++ b/changes.md @@ -1,5 +1,12 @@ # Changes +### 0.8.0 + +- Keep `.rabbit/context.yaml` focused on repo facts and tracing instead of inlining engineering practices and agent workflow guidance +- Generate workflow and practice guidance for `AGENTS.md` directly from the config catalogs, keeping the repo context and agent contract boundaries cleaner +- Refine the GitHub-first workflow language across docs, configs, and generated agent guidance +- Simplify lesson generation by consolidating workflow-tracing signals, deduping reusable templates by template name, and adding GitHub-style/history-aware guidance + ### 0.7.0 - Dynamic PR description guide in AGENTS.md — fetches recent merged PRs via `gh api`, detects common section headings, includes best-structured PR as a reference example diff --git a/package.json b/package.json index 8cf65bf..f1c89cb 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@udx/dev-kit", - "version": "0.7.0", + "version": "0.8.0", "description": "Context-driven engineering toolkit for AI agents and developers", "license": "MIT", "repository": { From 056799916df857b829a8911b924327ea93da7c5e Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Fri, 17 Apr 2026 21:23:02 +0300 Subject: [PATCH 09/11] Clean generated artifacts and tighten agent output --- AGENTS.md | 5 - changes.md | 10 +- docs/todo.md | 29 ----- lib/commands/agent.sh | 4 +- lib/modules/learning_sources.sh | 1 + tests/fixtures/docker-repo/AGENTS.md | 36 ------ .../fixtures/documented-shell-repo/AGENTS.md | 109 ------------------ tests/fixtures/simple-repo/AGENTS.md | 19 --- tests/fixtures/wordpress-repo/AGENTS.md | 32 ----- tests/suite.sh | 2 +- 10 files changed, 10 insertions(+), 237 deletions(-) delete mode 100644 docs/todo.md delete mode 100644 tests/fixtures/docker-repo/AGENTS.md delete mode 100644 tests/fixtures/documented-shell-repo/AGENTS.md delete mode 100644 tests/fixtures/simple-repo/AGENTS.md delete mode 100644 tests/fixtures/wordpress-repo/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index 43cf211..30b1b44 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -105,11 +105,6 @@ Patterns detected from agent sessions on this repo. Follow these in addition to - `Legacy reduction`: when a new direction is accepted, archive or delete conflicting old modules/configs instead of carrying both models forward. - `Config-over-code`: express repo rules in YAML/manifests first, then keep shell glue thin and composable. - `Agent handoff`: refresh repo context, manifest, and AGENTS instructions before deeper agent work so the repo contract is the source of truth. -- docs-first-alignment -- workflow-tracing -- verification-scope -- legacy-reduction -- agent-handoff ## Engineering practices diff --git a/changes.md b/changes.md index 100ab7b..6cbdec7 100644 --- a/changes.md +++ b/changes.md @@ -2,10 +2,12 @@ ### 0.8.0 -- Keep `.rabbit/context.yaml` focused on repo facts and tracing instead of inlining engineering practices and agent workflow guidance -- Generate workflow and practice guidance for `AGENTS.md` directly from the config catalogs, keeping the repo context and agent contract boundaries cleaner -- Refine the GitHub-first workflow language across docs, configs, and generated agent guidance -- Simplify lesson generation by consolidating workflow-tracing signals, deduping reusable templates by template name, and adding GitHub-style/history-aware guidance +- Keep `.rabbit/context.yaml` focused on repo facts, tracing, commands, and gaps instead of inlining engineering practices and canonical workflow text +- Generate workflow and practice guidance for `AGENTS.md` directly from the config catalogs and learning sources, simplifying the boundary between repo context and agent behavior +- Rework the docs surface around that model: simplify the README, add focused `installation`, `context`, `agents`, and `integration` docs, and remove older overlapping overview/workflow/architecture pages +- Tighten GitHub-first workflow guidance across configs, generated agent instructions, and learned templates, including repo-pattern reuse, history-aware debugging, and bot-feedback loops +- Simplify lesson/template generation by consolidating workflow-tracing signals, deduping reusable templates by template name, and filtering unresolved placeholder template IDs from generated output +- Clean up install and packaging flow with npm postinstall support and explicit npm-versus-curl ownership rules ### 0.7.0 diff --git a/docs/todo.md b/docs/todo.md deleted file mode 100644 index c2ef286..0000000 --- a/docs/todo.md +++ /dev/null @@ -1,29 +0,0 @@ -# dev.kit improvement backlog - -## Product direction - -- [ ] Keep `dev.kit` centered on GitHub-first development and agent execution. -- [ ] Make the session contract explicit: each work session should start with `dev.kit`, `dev.kit repo`, and `dev.kit agent`, then continue from `context.yaml` and `AGENTS.md`. -- [ ] Keep the product simple. `dev.kit` should stay middleware between repo-declared context and live GitHub experience, not a second workflow system. - -## GitHub pattern reuse - -- [ ] Generate branch names from current repo naming patterns. -- [ ] Generate PR titles and descriptions from recent repo PR style and structure. -- [ ] Generate issue titles and descriptions from recent repo issue style and structure. -- [ ] Generate issue and PR comments from existing repo follow-up and close-out patterns. - -## Review and verification loop - -- [ ] Make bot-review handling explicit: read feedback from Copilot, CodeQL, Devin, and similar reviewers, fix or reply, then resolve threads. -- [ ] Make workflow monitoring explicit: inspect related GitHub workflow runs after pushes and use failures as a fix loop, not just a status badge. -- [ ] Keep local verification scoped and lightweight when GitHub workflows already provide the primary verification surface. - -## History-aware debugging - -- [ ] When debugging, use related issues, PRs, and commit history to understand prior changes and possible regressions before inventing a new theory. -- [ ] Use the linked GitHub issue as the cross-repo context root when work spans multiple repos. - -## Why this matters - -`dev.kit` should keep reminding agents to use dev, team, and org experience from GitHub repos as part of the actual work loop. It should also surface repo gaps and push that learning back into repo contracts so the next session starts from better context. diff --git a/lib/commands/agent.sh b/lib/commands/agent.sh index 3b09469..9458faf 100644 --- a/lib/commands/agent.sh +++ b/lib/commands/agent.sh @@ -115,8 +115,8 @@ dev_kit_agent_github_section() { local context_yaml="$1" local section_name="$2" - awk -v key="^ " section_name ":" ' - $0 ~ key { in_section = 1; next } + awk -v section_name="$section_name" ' + $0 == " " section_name ":" { in_section = 1; next } in_section && /^ - / { sub(/^ - "?/, " - ") sub(/"$/, "") diff --git a/lib/modules/learning_sources.sh b/lib/modules/learning_sources.sh index 0bfe6a0..8d2209b 100644 --- a/lib/modules/learning_sources.sh +++ b/lib/modules/learning_sources.sh @@ -1044,6 +1044,7 @@ dev_kit_learning_lesson_templates() { /^## / && in_section { exit } in_section && /^- / { sub(/^- /, "") + if ($0 ~ /^[a-z0-9_-]+$/) next print } ' "$latest" diff --git a/tests/fixtures/docker-repo/AGENTS.md b/tests/fixtures/docker-repo/AGENTS.md deleted file mode 100644 index d8ffaf5..0000000 --- a/tests/fixtures/docker-repo/AGENTS.md +++ /dev/null @@ -1,36 +0,0 @@ -# AGENTS.md - -> Start with `.rabbit/context.yaml` for full repo context. Run `dev.kit repo` to refresh. - -## docker-repo - -Container image — a Dockerfile-based service built and published as a container image - -## Start here - -- ./.rabbit/context.yaml -- ./README.md -- ./.rabbit -- ./Makefile -- ./Dockerfile -- ./deploy.yml - -## Commands - -- **verify**: `make test` -- **build**: `make build` -- **run**: `make run` - -## Gaps - -- **dependencies** (partial) — Runtime signals exist, but the dependency contract is incomplete. Prefer an explicit language or package manifest over container-only dependency discovery. -- **config** (partial) — Config signals exist, but the environment contract is only partially documented. Add an example env file or clearer config documentation. - -## Workflow - -- Read the highest-priority repo refs first: ./.rabbit/context.yaml, ./README.md, ./.rabbit, ./Makefile, ./Dockerfile, ./deploy.yml, ./lib, ./src, https://raw.githubusercontent.com/udx/dev.kit/latest/.github/ISSUE_TEMPLATE, https://raw.githubusercontent.com/udx/dev.kit/latest/.github/PULL_REQUEST_TEMPLATE.md, https://raw.githubusercontent.com/udx/dev.kit/latest/src/configs/github-issues.yaml, https://raw.githubusercontent.com/udx/dev.kit/latest/src/configs/github-prs.yaml -- Run the canonical verification command: `make test` -- Run the canonical build command when needed: `make build` -- Use the canonical runtime command instead of ad hoc startup paths: `make run` -- Review lessons-learned and follow-up outputs after changes stabilize: `dev.kit learn` - diff --git a/tests/fixtures/documented-shell-repo/AGENTS.md b/tests/fixtures/documented-shell-repo/AGENTS.md deleted file mode 100644 index d669c31..0000000 --- a/tests/fixtures/documented-shell-repo/AGENTS.md +++ /dev/null @@ -1,109 +0,0 @@ -# AGENTS.md - -_Auto-generated by `dev.kit agent`. Source of truth: `.rabbit/context.yaml`._ - -## Contract - -This repository is a deterministic execution contract. Agents MUST interpret declared context — no scanning, no guesswork, no invention. - -### Rules - -1. **Do NOT scan the filesystem.** No `find`, `ls -R`, `glob`, or recursive directory walks. All paths you need are listed below. -2. **Context boundaries are strict.** Read only files in Priority refs and Config manifests. If a file is not listed, do not read it unless a listed file explicitly references it. -3. **Manifests before code.** When you need to understand behavior, read the YAML manifest that defines it — not the code that implements it. Manifests are the interface. -4. **Context over memory.** Operate from repo-declared context. Do not carry assumptions from prior sessions or rely on prompt history when the contract is on disk. -5. **Verify locally before committing.** Run the verify command before reporting work as done. Local execution is part of the contract. -6. **Follow the Workflow below.** Do not invent ad hoc steps or skip phases. The workflow is the execution sequence. -7. **Reuse over invention.** Check existing org patterns, configs, and workflows before creating new ones. - -## Repo: documented-shell-repo - -- archetype: library-cli -- profile: shell - -### Commands - -``` - verify: bash tests/run.sh -``` - -### Priority refs - -These files plus config manifests define the complete allowed surface. Do not explore beyond them. - - - ./README.md - - ./docs - - ./.rabbit - - ./lib - - ./src - - ./scripts - - ./tests - - https://raw.githubusercontent.com/udx/dev.kit/latest/src/configs/github-issues.yaml - - https://raw.githubusercontent.com/udx/dev.kit/latest/src/configs/github-prs.yaml - - https://raw.githubusercontent.com/udx/dev.kit/latest/.github/ISSUE_TEMPLATE - - https://raw.githubusercontent.com/udx/dev.kit/latest/.github/PULL_REQUEST_TEMPLATE.md - -### GitHub context - -Development signals from [udx/dev.kit](https://github.com/udx/dev.kit). - -**Recent PRs:** - - - #15 bump version to 0.2.1 - - #14 fix release workflow trigger - - #13 add package-lock.json for CI cache - - #12 add npm release workflow, versioning, and changelog - - #11 redesign dev.kit: context.yaml pipeline, AGENTS.md with rules + manifests, promptfoo eval - -### Gaps - -Incomplete factors. Address within the workflow, not as separate tasks. - - - config (missing) - -## Versioned workflow artifacts - -`.rabbit/` contains generated context downstream of repo signals. These are versioned artifacts, not primary sources. - - - `.rabbit/context.yaml` — generated execution contract (source of truth for this file) - -## Workflow - -The dev.kit lifecycle: **repo → agent → work → PR → merge**. Follow these steps in order. Steps with notes contain operational guidance. - - - Refresh repo context: If .rabbit/context.yaml is stale or absent, run `dev.kit repo` then `dev.kit agent` before starting work. A current context.yaml is the source of truth for refs, commands, gaps, and lessons. Do not rely on ad hoc prompt memory when the repo contract can be read from disk. Locate the actual workflow and deploy files (deploy.yml, .github/workflows) first — trace commands and supporting docs from there. - - Read linked GitHub issue and confirm scope: If a GitHub issue URL is available, read the full body and comments, confirm the repo matches the issue scope, and map acceptance criteria before writing any code. Use the issue URL as the cross-repo context root. - - Inspect git status - - Analyze local changes - - Analyze branch state - - Group logical commits - - Bump version and changelog if supported - - Create or validate feature branch - - Push branch to remote - - Generate pull request description: Pick the PR template type from src/configs/github-prs.yaml (feature, deployment, ops, hotfix). Fill every required section. Include "Closes #N" for linked issues. Add a "Backlog from this investigation" section for any new gaps found. Use .github/PULL_REQUEST_TEMPLATE.md as the base form. - - Create pull request - - Read and respond to automated reviews: After PR creation, wait for Copilot, Devin, and CodeQL reviews. Read each review from github-prs.yaml bot guidance. Address actionable findings — reply to each bot comment. Do not request human review while bot findings are unaddressed. - - Verify required status checks: All required checks must pass before requesting human review. For infra PRs, open check details and review the Terraform plan output. For CodeQL, review findings in the Security tab. - - Post close-out comment on linked issue: After PR is created, post a brief comment on the linked issue with the PR URL, what changed, and any follow-up items. GitHub auto-closes the issue on merge when "Closes #N" is in the PR body — do not close manually. - - Post-merge close-out and backlog: After merge: verify issue auto-closed, post close-out comment, open issues for any backlog items from the PR, verify monitoring changes are live. See post_merge steps in github-prs.yaml. - -## Engineering practices - - - Keep the repository as the primary source of truth so context-driven engineering comes from repo contracts, docs, tests, config, and repo-native notes instead of agent memory. - - Prefer repo-centric mechanisms that discover workflows, tools, formats, and refs dynamically instead of hardcoding per-agent assumptions. - - Keep markdown, yaml, diagrams, tests, and command contracts self-contained in the repo so local and remote UDX workflows stay aligned. - - Keep deterministic workflow logic in repo config and scripts, and reserve AI agents for reading that contract, generating grounded summaries, and handling non-deterministic judgment without inventing hidden rules. - - Operate from repo-declared context at all times. Do not carry assumptions across sessions or rely on prompt history when the repo contract is available on disk. - - When understanding behavior, read the YAML manifest that defines it before reading the code that implements it. Manifests are the interface — code is the mechanism. - - Check existing org patterns, configs, workflows, and templates before creating new ones. Reuse declared patterns instead of inventing alternatives. - - Execute verification, builds, and tests locally before any remote operation. Local execution is part of the reproducible repo contract, not a preference. - - Keep the delivery chain explicit — branch, PR, and issue must be connected before close-out. Do not treat any step as done until the link to the next step is visible. - - Report outcomes with exact URLs, versions, findings deltas, and next steps so follow-up can be reused by humans and agents without drift. - - Use README, docs, and tests as the first alignment surface before broad refactors. Read the declared workflow before changing the implementation. - - Do not require custom repo files for dev.kit to work. Prefer standard engineering signals such as README, docs, tests, manifests, workflows, and deployment config, with dev.kit-owned continuity treated as optional acceleration only. - - Express repo rules in YAML manifests first, then keep shell glue thin and composable. Policy belongs in config, not buried in imperative scripts. - - When a new direction is accepted, archive or delete conflicting old modules and configs instead of carrying both models forward. - - Run the smallest local check that proves the current change. Defer heavyweight coverage to CI and call that tradeoff out explicitly. - - Make sure to develop and test incrementally, so it is easier to detect problems early and build on verified behavior. - - Make sure to protect development executions with scoped and limited tasks, so failures are easier to isolate and blast radius stays low. - diff --git a/tests/fixtures/simple-repo/AGENTS.md b/tests/fixtures/simple-repo/AGENTS.md deleted file mode 100644 index 3d15962..0000000 --- a/tests/fixtures/simple-repo/AGENTS.md +++ /dev/null @@ -1,19 +0,0 @@ -# AGENTS.md - -> Generated by dev.kit. Do not edit manually — run `dev.kit repo` to refresh. - -## Repo - -- **Name**: simple-repo -- **Archetype**: library-cli -- **Profile**: node - - -## Read first - -- ./package.json -- ./tests - -## Entrypoints - - diff --git a/tests/fixtures/wordpress-repo/AGENTS.md b/tests/fixtures/wordpress-repo/AGENTS.md deleted file mode 100644 index 226b041..0000000 --- a/tests/fixtures/wordpress-repo/AGENTS.md +++ /dev/null @@ -1,32 +0,0 @@ -# AGENTS.md - -> Start with `.rabbit/context.yaml` for full repo context. Run `dev.kit repo` to refresh. - -## wordpress-repo - -WordPress website — application code, theme, and plugin assets deployed to a WordPress host - -## Start here - -- ./.rabbit/context.yaml -- ./README.md -- ./.rabbit/infra_configs -- ./.rabbit -- ./.github/workflows -- ./package.json - -## Commands - -- **verify**: `npm test` - -## Gaps - -- **architecture** (partial) — Some architectural boundaries are visible, but the repository structure is not fully normalized yet. Separate commands, modules, templates, and config more explicitly. -- **config** (missing) — Externalize configuration and document the environment contract so the repo can move cleanly across environments. - -## Workflow - -- Read the highest-priority repo refs first: ./.rabbit/context.yaml, ./README.md, ./.rabbit/infra_configs, ./.rabbit, ./.github/workflows, ./package.json, ./wp-config.php, https://raw.githubusercontent.com/udx/dev.kit/latest/.github/ISSUE_TEMPLATE, https://raw.githubusercontent.com/udx/dev.kit/latest/.github/PULL_REQUEST_TEMPLATE.md, https://raw.githubusercontent.com/udx/dev.kit/latest/src/configs/github-issues.yaml, https://raw.githubusercontent.com/udx/dev.kit/latest/src/configs/github-prs.yaml -- Run the canonical verification command: `npm test` -- Review lessons-learned and follow-up outputs after changes stabilize: `dev.kit learn` - diff --git a/tests/suite.sh b/tests/suite.sh index 3f474b6..f02ce66 100644 --- a/tests/suite.sh +++ b/tests/suite.sh @@ -266,7 +266,7 @@ if should_run "install" && [ -n "${CI:-}" ]; then cat > "$FAKE_BIN_DIR/npm" <> "$FAKE_NPM_LOG" +echo "$*" >> "$FAKE_NPM_LOG" if [ "\${1:-}" = "list" ] && [ "\${2:-}" = "-g" ] && [ "\${3:-}" = "@udx/dev-kit" ] && [ "\${4:-}" = "--depth=0" ]; then exit 0 fi From 8a909383e78d9230db8244fe45f17346661f1b75 Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Fri, 17 Apr 2026 21:25:53 +0300 Subject: [PATCH 10/11] Normalize learned templates and PR guidance --- .rabbit/dev.kit/lessons-dev.kit-2026-04-15.md | 11 +++++------ AGENTS.md | 2 +- lib/commands/learn.sh | 19 ++++++++++++++++++- src/configs/development-workflows.yaml | 3 ++- 4 files changed, 26 insertions(+), 9 deletions(-) diff --git a/.rabbit/dev.kit/lessons-dev.kit-2026-04-15.md b/.rabbit/dev.kit/lessons-dev.kit-2026-04-15.md index ee8fd3e..ca2beb4 100644 --- a/.rabbit/dev.kit/lessons-dev.kit-2026-04-15.md +++ b/.rabbit/dev.kit/lessons-dev.kit-2026-04-15.md @@ -66,11 +66,11 @@ Sources: claude (1 session(s)), codex (0 session(s)) - `Legacy reduction`: when a new direction is accepted, archive or delete conflicting old modules/configs instead of carrying both models forward. - `Config-over-code`: express repo rules in YAML/manifests first, then keep shell glue thin and composable. - `Agent handoff`: refresh repo context, manifest, and AGENTS instructions before deeper agent work so the repo contract is the source of truth. -- docs-first-alignment -- workflow-tracing -- verification-scope -- legacy-reduction -- agent-handoff +- `Docs-first alignment`: review README, docs, and tests before refactoring, restate the target workflow, then simplify code and remove mismatched legacy paths. +- `Workflow tracing`: locate the actual workflow or deploy file first, then trace the commands and supporting docs that drive execution. +- `Verification scope`: run the smallest local check that proves the current change, defer heavyweight coverage to CI, and call the tradeoff out explicitly. +- `Legacy reduction`: when a new direction is accepted, archive or delete conflicting old modules/configs instead of carrying both models forward. +- `Agent handoff`: refresh repo context, manifests, and AGENTS.md before deeper agent work so the repo contract is the source of truth. ## Evidence highlights @@ -82,4 +82,3 @@ Sources: claude (1 session(s)), codex (0 session(s)) - [claude] [Pasted text #1 +131 lines] - [claude] make sure to explore lessons and overall flow, I want - dev.kit - dev.kit repo (generate repo context + experienced knowledge and dev workflow(s)) - dev.kit agent (generate correct flexible agent instructions based on context) - dev.kit learn (generate analyzed agents sessions) use learned lessons to improve dev.kit... - [claude] before make changes would be useful to sync uncommited to git - diff --git a/AGENTS.md b/AGENTS.md index 30b1b44..325e68c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -69,7 +69,7 @@ The dev.kit lifecycle: **repo → agent → work → PR → merge**. Follow thes - Bump version and changelog if supported - Create or validate feature branch - Push branch to remote - - Generate pull request description: Pick the PR template type from src/configs/github-prs.yaml (feature, deployment, ops, hotfix). Fill every required section. Include "Closes #N" for linked issues. Add a "Backlog from this investigation" section for any new gaps found. Use .github/PULL_REQUEST_TEMPLATE.md as the base form. + - Generate pull request description: Pick the PR template type from src/configs/github-prs.yaml (feature, deployment, ops, hotfix). Fill every required section. Include "Closes #N" for linked issues. Add a "Backlog from this investigation" section for any new gaps found. Use github-prs.yaml and current GitHub PR/body patterns in this repo as the base guidance. - Create pull request - Monitor related workflow executions: After PR creation, monitor the related GitHub workflow runs and status checks. Open the run details when needed, watch for failed or stuck jobs, and treat GitHub workflow execution as the primary verification path when the repo already has CI coverage. - Loop automated review feedback: After PR creation, wait for Copilot, Devin, and CodeQL reviews. Read each review from github-prs.yaml bot guidance. Address actionable findings with code changes, reply to each bot comment, and resolve the thread when handled. Repeat this loop after each push until bot feedback is clean. Do not request human review while bot findings are unaddressed. diff --git a/lib/commands/learn.sh b/lib/commands/learn.sh index c7903ff..32b01c4 100644 --- a/lib/commands/learn.sh +++ b/lib/commands/learn.sh @@ -216,7 +216,10 @@ dev_kit_learning_write_artifact() { mkdir -p "${repo_dir}/.rabbit/dev.kit" 2>/dev/null || true previous_workflow_rules="$(dev_kit_learning_previous_section_lines "$previous_artifact" "Workflow rules")" previous_references="$(dev_kit_learning_previous_section_lines "$previous_artifact" "Operational references")" - previous_templates="$(dev_kit_learning_previous_section_lines "$previous_artifact" "Ready templates")" + previous_templates="$( + dev_kit_learning_previous_section_lines "$previous_artifact" "Ready templates" \ + | dev_kit_learning_normalize_template_lines + )" previous_evidence="$(dev_kit_learning_previous_section_lines "$previous_artifact" "Evidence highlights")" { @@ -362,6 +365,20 @@ dev_kit_learning_merge_unique_lines() { ' } +dev_kit_learning_normalize_template_lines() { + while IFS= read -r line; do + [ -n "$line" ] || continue + case "$line" in + '`'*) + printf '%s\n' "$line" + ;; + *) + printf '%s\n' "$(dev_kit_learning_flow_template "$line")" + ;; + esac + done +} + dev_kit_learning_evidence_highlights() { local refs="$1" local repo_dir="${2:-$(pwd)}" diff --git a/src/configs/development-workflows.yaml b/src/configs/development-workflows.yaml index 6d63fac..10ee35d 100644 --- a/src/configs/development-workflows.yaml +++ b/src/configs/development-workflows.yaml @@ -85,7 +85,8 @@ config: Pick the PR template type from src/configs/github-prs.yaml (feature, deployment, ops, hotfix). Fill every required section. Include "Closes #N" for linked issues. Add a "Backlog from this investigation" section for any - new gaps found. Use .github/PULL_REQUEST_TEMPLATE.md as the base form. + new gaps found. Use github-prs.yaml and current GitHub PR/body patterns + in this repo as the base guidance. - id: pr_create label: Create pull request check: pr_create From 79a5358a7984641085598522361b1b1500871b1b Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Fri, 17 Apr 2026 21:30:53 +0300 Subject: [PATCH 11/11] Gate npm postinstall cleanup to global installs --- changes.md | 2 +- package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/changes.md b/changes.md index 6cbdec7..409058a 100644 --- a/changes.md +++ b/changes.md @@ -7,7 +7,7 @@ - Rework the docs surface around that model: simplify the README, add focused `installation`, `context`, `agents`, and `integration` docs, and remove older overlapping overview/workflow/architecture pages - Tighten GitHub-first workflow guidance across configs, generated agent instructions, and learned templates, including repo-pattern reuse, history-aware debugging, and bot-feedback loops - Simplify lesson/template generation by consolidating workflow-tracing signals, deduping reusable templates by template name, and filtering unresolved placeholder template IDs from generated output -- Clean up install and packaging flow with npm postinstall support and explicit npm-versus-curl ownership rules +- Clean up install and packaging flow with global npm postinstall cleanup and explicit npm-versus-curl ownership rules ### 0.7.0 diff --git a/package.json b/package.json index f1c89cb..df1ea17 100644 --- a/package.json +++ b/package.json @@ -10,7 +10,7 @@ "homepage": "https://github.com/udx/dev.kit", "bugs": "https://github.com/udx/dev.kit/issues", "scripts": { - "postinstall": "bash bin/scripts/npm-postinstall.sh || true" + "postinstall": "if [ \"$npm_config_global\" = \"true\" ]; then bash bin/scripts/npm-postinstall.sh || true; fi" }, "bin": { "dev.kit": "bin/dev-kit",