|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +_Auto-generated by `dev.kit agent`. Source of truth: `.rabbit/context.yaml`._ |
| 4 | + |
| 5 | +## Rules |
| 6 | + |
| 7 | +1. **Do NOT scan the filesystem.** No `find`, `ls -R`, `glob`, or recursive directory walks. All paths you need are listed in this file. |
| 8 | +2. **Read only files listed in Priority refs and Config manifests.** If a file is not listed, do not read it unless a listed file explicitly references it. |
| 9 | +3. **Verify locally before committing.** Run the verify command below before reporting work as done. Do not skip this step. |
| 10 | +4. **Follow the Workflow below as your execution contract.** Do not invent ad hoc steps or skip workflow phases. |
| 11 | +5. **Use config manifests as traceable dependencies.** When you need to understand how something works, check the YAML manifest that defines it — not the code that reads it. |
| 12 | + |
| 13 | +## Repo: dev.kit |
| 14 | + |
| 15 | +- archetype: library-cli |
| 16 | +- profile: shell |
| 17 | + |
| 18 | +## Commands |
| 19 | + |
| 20 | +``` |
| 21 | + verify: make test |
| 22 | + build: make build |
| 23 | + run: make run |
| 24 | +``` |
| 25 | + |
| 26 | +## Priority refs |
| 27 | + |
| 28 | +Read these for full context. Do not explore beyond them. |
| 29 | + |
| 30 | + - ./README.md |
| 31 | + - ./docs/architecture.md |
| 32 | + - ./docs |
| 33 | + - ./.rabbit |
| 34 | + - ./.github/workflows |
| 35 | + - ./Makefile |
| 36 | + - ./deploy.yml |
| 37 | + - ./lib |
| 38 | + - ./src |
| 39 | + - ./tests |
| 40 | + |
| 41 | +## Config manifests |
| 42 | + |
| 43 | +These YAML files define the project workflow, tooling, and behavior. Trace dependencies here before reading shell code. |
| 44 | + |
| 45 | + - src/configs/archetype-rules.yaml (archetypeRules) |
| 46 | + - src/configs/archetype-signals.yaml (archetypeSignals) |
| 47 | + - src/configs/audit-rules.yaml (auditRules) |
| 48 | + - src/configs/context-config.yaml (contextConfig) |
| 49 | + - src/configs/detection-patterns.yaml (detectionPatterns) |
| 50 | + - src/configs/detection-signals.yaml (detectionSignals) |
| 51 | + - src/configs/development-practices.yaml (developmentPractices) |
| 52 | + - src/configs/development-workflows.yaml (developmentWorkflows) |
| 53 | + - src/configs/github-issues.yaml (githubIssues) |
| 54 | + - src/configs/github-prs.yaml (githubPullRequests) |
| 55 | + - src/configs/knowledge-base.yaml (knowledgeBase) |
| 56 | + - src/configs/learning-workflows.yaml (learningWorkflows) |
| 57 | + - src/configs/repo-scaffold.yaml (repoScaffold) |
| 58 | + - .github/workflows/context7-ops.yml |
| 59 | + - deploy.yml |
| 60 | + |
| 61 | +## Gaps |
| 62 | + |
| 63 | + - architecture (partial) |
| 64 | + - config (partial) |
| 65 | + - runtime (partial) |
| 66 | + |
| 67 | +## Workflow |
| 68 | + |
| 69 | +Follow these steps in order. Steps with notes contain operational guidance — read them. |
| 70 | + |
| 71 | + - 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. |
| 72 | + - 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. |
| 73 | + - Inspect git status |
| 74 | + - Analyze local changes |
| 75 | + - Analyze branch state |
| 76 | + - Group logical commits |
| 77 | + - Bump version and changelog if supported |
| 78 | + - Create or validate feature branch |
| 79 | + - Push branch to remote |
| 80 | + - 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. |
| 81 | + - Create pull request |
| 82 | + - 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. |
| 83 | + - 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. |
| 84 | + - 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. |
| 85 | + - 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. |
| 86 | + |
| 87 | +## Engineering practices |
| 88 | + |
| 89 | + - 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. |
| 90 | + - Prefer repo-centric mechanisms that discover workflows, tools, formats, and refs dynamically instead of hardcoding per-agent assumptions. |
| 91 | + - Keep markdown, yaml, diagrams, tests, and command contracts self-contained in the repo so local and remote UDX workflows stay aligned. |
| 92 | + - 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. |
| 93 | + - 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. |
| 94 | + - Make sure to develop and test incrementally, so it is easier to detect problems early and build on verified behavior. |
| 95 | + - Make sure to protect development executions with scoped and limited tasks, so failures are easier to isolate and blast radius stays low. |
| 96 | + |
| 97 | +## Lessons from prior sessions |
| 98 | + |
| 99 | +Read these before starting work. They contain workflow rules and operational patterns learned from real agent sessions. |
| 100 | + |
| 101 | + - .rabbit/dev.kit/lessons-dev.kit-2026-04-14.md |
| 102 | + |
0 commit comments