Refine repo context boundaries and GitHub workflow guidance

.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-17
 
 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
@@ -27,60 +30,10 @@ commands:
   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)
 
-# 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."
-  - "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."
-
-# 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."
-  - "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.
@@ -90,7 +43,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 +69,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
 

.rabbit/dev.kit/lessons-dev.kit-2026-04-15.md

@@ -0,0 +1,84 @@
+# 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`: 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
+
+- [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