Start on dd-2998002

Author: edburns

80-java-monorepo-add-01-remove-before-merge/20260515-prompts.md

@@ -183,34 +183,354 @@ Phase 0 states:
 - [ ] **Define Freeze window policy** — declare a short freeze window in `copilot-sdk-java` to avoid merge conflicts during migration
 ```
 
-I'm very loath to freeze agentic syncing. How hard would it be to adopt a policy of manually syncing any changes that come in to `copilot-sdk-java-00` during the migration? I'm pretty much the only committer, and the agentic sync workflow is the only one whot that runs regularly and pushes commits. I could change that to once a week on Friday and probably be ok. 
+I'm very loath to freeze agentic syncing. How hard would it be to adopt a policy of manually syncing any changes that come in to `copilot-sdk-java-00` during the migration? I'm pretty much the only committer, and the agentic sync workflow is the only one whot that runs regularly and pushes commits. I could change that to once a week on Friday and probably be ok.
 
 ### 15:06 Response
 
 This is very practical given your situation. The risk calculus:
 
 **Why it's easy:**
+
 - You're the sole human committer — no surprise PRs to worry about
 - Reference-impl-sync changes are predictable: generated code under generated, .lastmerge, package.json, and occasionally hand-written Java adjustments
 - Any drift is trivially detectable: `git log --oneline copilot-sdk-java-00/main` tells you exactly what landed
-- Phase 1 (copy source) is the only phase truly sensitive to drift — Phases 2-4 create *new* monorepo files that don't conflict
+- Phase 1 (copy source) is the only phase truly sensitive to drift — Phases 2-4 create _new_ monorepo files that don't conflict
 
 **Suggested policy instead of a freeze:**
+
 1. Reduce reference-impl-sync to weekly/Friday (as you said)
 2. Do Phase 1 copy early in the week, right after verifying java-00 main is clean
 3. After each sync lands on Friday, forward-port the diff into `copilot-sdk-00/java/` — a straightforward `git diff PREV_HASH..NEW_HASH` in java-00 applied to the monorepo
 4. Once Phase 1 merges and the monorepo is the source of truth, disable the sync workflow entirely
 
-**The one thing to watch:** if a sync lands *during* an active Phase 1 PR review, you'd need to rebase. But since you control the sync schedule, just don't trigger it while a PR is open.
+**The one thing to watch:** if a sync lands _during_ an active Phase 1 PR review, you'd need to rebase. But since you control the sync schedule, just don't trigger it while a PR is open.
 
 A hard freeze is overkill here. Want me to update the plan to reflect this policy?
 
 ### 15:06 Prompt
 
 Yes.
 
-### 15:06 Response
+## dd-2997995-phase-01
+
+### 15:20 Prompt
+
+The plan states
+
+```markdown
+- `instructions/` → `java/instructions/` (or merge into monorepo copilot-instructions)
+```
+
+When I look in the `copilot-sdk-00` I observe there is a SKILL for rust, but I don't see any language specific instructions. Am I missing something? Produce a plan for doing the little sub-step of your Phase 01 here.
+
+### 15:29 Response
+
+Explore instruction/skill structure
+
+Searched for files matching `copilot-sdk-00` · `**/*.instructions.md`, no matches
+
+Searched for files matching `copilot-sdk-java-00` · `**/*.instructions.md`, 1 match
+
+Searched for files matching `copilot-sdk-00` · `**/.copilot`, no matches
+
+Searched for files matching `copilot-sdk-java-00` · `**/.copilot`, no matches
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/.github)
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/.github)
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/.github/skills)
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/.github/skills)
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/.github/agents)
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/.github/agents)
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/.github/skills/rust-coding-skill)
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/.github/skills/agentic-merge-reference-impl)
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/.github/skills/commit-as-pull-request)
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/.github/skills/documentation-coverage)
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/nodejs)
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/python)
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/go)
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/dotnet)
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/rust)
+
+Searched for files matching `copilot-sdk-00` · `*.instructions.md`, no matches
+
+Searched for files matching `copilot-sdk-00` · `nodejs/**/*.instructions.md`, no matches
+
+Searched for files matching `copilot-sdk-00` · `python/**/*.instructions.md`, no matches
+
+Searched for files matching `copilot-sdk-00` · `go/**/*.instructions.md`, no matches
+
+Searched for files matching `copilot-sdk-00` · `dotnet/**/*.instructions.md`, no matches
+
+Searched for files matching `copilot-sdk-00` · `rust/**/*.instructions.md`, no matches
+
+Searched for files matching `copilot-sdk-00` · `**/instructions`, no matches
+
+Searched for files matching `copilot-sdk-java-00` · `**/instructions`, no matches
 
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/instructions)
 
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/instructions/copilot-sdk-java.instructions.md#1-1), lines 1 to 300
 
+Read skill [rust-coding-skill](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/.github/skills/rust-coding-skill/SKILL.md?vscodeLinkType%3Dskill#1-1), lines 1 to 100
+
+Read skill [agentic-merge-reference-impl](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/.github/skills/agentic-merge-reference-impl/SKILL.md?vscodeLinkType%3Dskill)
+
+Read skill [commit-as-pull-request](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/.github/skills/commit-as-pull-request/SKILL.md?vscodeLinkType%3Dskill)
+
+Read skill [documentation-coverage](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/.github/skills/documentation-coverage/SKILL.md?vscodeLinkType%3Dskill)
+
+Read skill [rust-coding-skill](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/.github/skills/rust-coding-skill/SKILL.md?vscodeLinkType%3Dskill)
+
+Read skill `rust-coding-skill`: [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/.github/skills/rust-coding-skill/examples.md#1-1), lines 1 to 150
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/.github/agents/agentic-workflows.agent.md#1-1), lines 1 to 50
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/.github/agents/agentic-workflows.agent.md#1-1), lines 1 to 50
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/instructions/copilot-sdk-java.instructions.md#300-300), lines 300 to 600
+
+Read [](file:///c%3A/Users/edburns/AppData/Roaming/Code%20-%20Insiders/User/prompts)
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/instructions/copilot-sdk-java.instructions.md#600-600), lines 600 to 757
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/.github/prompts)
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/.github/prompts)
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/.github/actions)
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/.github/actions)
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/.github/aw)
+
+Searched for files matching `copilot-sdk-00` · `**/*.prompt.md`, no matches
+
+Searched for files matching `copilot-sdk-java-00` · `**/*.prompt.md`, 4 matches
+
+Searched for files matching `copilot-sdk-00` · `**/*.agent.md`, 2 matches
+
+Searched for files matching `copilot-sdk-java-00` · `**/*.agent.md`, 1 match
+
+Searched for regex `language.*instruction|instructions.*language|rust.*skill|coding.*skill` (`copilot-sdk-00` · `.github/copilot-instructions.md`), no results
+
+Searched for regex `language.*instruction|instructions.*language|skill|agent` (`copilot-sdk-java-00` · `.github/copilot-instructions.md`), 13 results
+
+Read [](file:///c%3A/Users/edburns/AppData/Roaming/Code%20-%20Insiders/User/workspaceStorage/42e680be608c5e153963c50a3611d619/GitHub.copilot-chat/chat-session-resources/7b272067-59c1-463a-b094-300b246bfc71/toolu_vrtx_017hNdUf5o7v8yju8ZR3EbQ1__vscode-1778880555537/content.txt#1-1), lines 1 to 200
+
+You're correct — the monorepo has no per-language instructions directories. The pattern it uses instead is **skills**. The `rust-coding-skill` at rust-coding-skill serves the same purpose as Java's copilot-sdk-java.instructions.md — it provides language-specific coding rules and API patterns.
+
+Here's the sub-plan:
+
+## Plan: Migrate copilot-sdk-java.instructions.md
+
+### Current State
+
+| Repo         | Mechanism                        | Content                                                                    |
+| ------------ | -------------------------------- | -------------------------------------------------------------------------- |
+| **Monorepo** | SKILL.md                         | Rust-specific coding rules, API patterns, idioms (~300 lines)              |
+| **Monorepo** | copilot-instructions.md          | Cross-language repo governance (build commands, architecture, conventions) |
+| **Java SDK** | copilot-sdk-java.instructions.md | Java-specific coding rules, API usage patterns (~1400 lines)               |
+| **Java SDK** | copilot-instructions.md          | Java repo governance (build commands, architecture, conventions)           |
+
+### Approach: Create a `java-coding-skill` (follows the Rust pattern)
+
+**Do NOT** put it at `java/instructions/` — that doesn't match the monorepo convention.
+**Do NOT** merge 1400 lines into copilot-instructions.md — that would bloat the central file.
+
+**Instead**, create `.github/skills/java-coding-skill/SKILL.md` following the `rust-coding-skill` pattern.
+
+### Steps
+
+1. **Create** `.github/skills/java-coding-skill/SKILL.md`
+   - Add YAML frontmatter with `name: java-coding-skill` and a description like `"Use this skill whenever editing *.java files in the java/ SDK..."`
+   - Body = content from copilot-sdk-java.instructions.md
+
+2. **Merge Java repo governance** into monorepo's copilot-instructions.md
+   - The Java SDK's copilot-instructions.md contains build commands (`mvn clean verify`, `mvn spotless:apply`), architecture notes (package structure, handler patterns), and test conventions.
+   - Add a `## Java` section to the monorepo's instructions file (paralleling how it already covers Node, Python, Go, .NET, Rust).
+   - Keep it concise — the detailed API patterns live in the skill.
+
+3. **Do NOT copy** instructions as a directory to `java/instructions/` — the monorepo doesn't use that pattern.
+
+### Result
+
+```
+.github/
+  ├── copilot-instructions.md           # Add Java section (build, test, conventions)
+  ├── skills/
+  │   ├── rust-coding-skill/
+  │   │   ├── SKILL.md
+  │   │   └── examples.md
+  │   └── java-coding-skill/            # NEW
+  │       └── SKILL.md                  # From instructions/copilot-sdk-java.instructions.md
+```
 
+### What This Means for the Plan
+
+The line in Phase 1:
+
+> instructions → `java/instructions/` (or merge into monorepo copilot-instructions)
+
+Should be updated to:
+
+> copilot-sdk-java.instructions.md → `.github/skills/java-coding-skill/SKILL.md` (follows the `rust-coding-skill` pattern); Java repo governance merged into copilot-instructions.md
+
+Want me to execute this, or just update the plan text?
+
+### 15:32 Prompt
+
+Update the plan first.
+
+### 15:34 Response
+
+Compacted conversation
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/80-java-monorepo-add-01-remove-before-merge/dd-2989727-move-java-to-monorepo-plan.md#1-1), lines 1 to 120
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/80-java-monorepo-add-01-remove-before-merge/dd-2989727-move-java-to-monorepo-plan.md#120-120), lines 120 to 200
+
+Let me also check the appendix for any related references.
+
+Searched for text `instructions` (`**/dd-2989727-move-java-to-monorepo-plan.md`), 20 results
+
+Let me read the relevant sections around the other references:
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/80-java-monorepo-add-01-remove-before-merge/dd-2989727-move-java-to-monorepo-plan.md#365-365), lines 365 to 380
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/80-java-monorepo-add-01-remove-before-merge/dd-2989727-move-java-to-monorepo-plan.md#445-445), lines 445 to 465
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/80-java-monorepo-add-01-remove-before-merge/dd-2989727-move-java-to-monorepo-plan.md#500-500), lines 500 to 520
+
+Now I have the full picture. There are four places to update:
+
+1. **Line 49** (Phase 1): instructions → `java/instructions/`
+2. **Line 373** (§6A table): `Move to java/`
+3. **Line 456** (checklist): `copilot-instructions.md includes Java guidance`
+4. **Line ~516** (Appendix A): instructions → `java/instructions/`
+
+Replacing 4 lines with 5 lines in [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/80-java-monorepo-add-01-remove-before-merge/dd-2989727-move-java-to-monorepo-plan.md)
+
+```
+
+```
+
+Updated all four references in the plan:
+
+1. **Phase 1 (line 49):** instructions → now points to `.github/skills/java-coding-skill/SKILL.md`
+2. **§6A inventory table (line 373):** "Move to java" → "Create `.github/skills/java-coding-skill/SKILL.md`"
+3. **Verification checklist (line 456):** Split into two items — one for copilot-instructions.md governance section, one for the new skill file
+4. **Appendix A (line ~516):** "Move → `java/instructions/`" → "Create skill → `.github/skills/java-coding-skill/SKILL.md`"
+
+Made changes.
+
+### 15:37 Prompt
+
+Now that you have updated the plan file, produce a net-new, very focused plan just for this part: making the monorepo smart about Java, while following all conventions. This plan will be executed by a separate agent to do the work, so include everything an agent could possibly need into this prompt. Write the prompt as a sibling to the plan file, but call it `dd-2998002-make-the-monorepo-smart-about-java-plan.md`. Include checkboxes so the agent can follow along and not get confused and lose context. Be explicit about the goals.
+
+### 15:43 Response
+
+Let me gather the exact source materials the agent plan needs to reference.
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/instructions/copilot-sdk-java.instructions.md#1-1), lines 1 to 30
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/.github/copilot-instructions.md)
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/.github/copilot-instructions.md#1-1), lines 1 to 80
+
+Read skill [rust-coding-skill](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/.github/skills/rust-coding-skill/SKILL.md?vscodeLinkType%3Dskill#1-1), lines 1 to 15
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/.github/copilot-instructions.md#80-80), lines 80 to 260
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-java-00/instructions/copilot-sdk-java.instructions.md)
+
+Now I have all the source materials. Let me create the focused plan document.
+
+Created [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/80-java-monorepo-add-01-remove-before-merge/dd-2998002-make-the-monorepo-smart-about-java-plan.md)
+
+Created dd-2998002-make-the-monorepo-smart-about-java-plan.md. It includes:
+
+- **Explicit goals** — two deliverables (skill file + governance merge)
+- **Non-goals** — what NOT to do (no `java/instructions/` directory, no other language changes)
+- **7-step checklist** with checkboxes for the agent to follow
+- **Exact YAML frontmatter** to use (matching the `rust-coding-skill` pattern)
+- **Precise edit instructions** for each section of copilot-instructions.md (6a–6f)
+- **Verification step** with 4 confirmation checks
+- **Appendix A** — describes the Java instructions source file structure (757 lines, 22 sections)
+- **Appendix B** — describes the Java governance content to merge, with guidance on what belongs in governance vs. the skill
+
+Made changes.
+
+### 15:44 Prompt
+
+I intend to use Copilot CLI `copilot --yolo` and ask it to execute the plan as a prompt. It will need to have access to both the monorepo and the java. When I interact with you here in VS Code, that comes by virtue of **Add folder to workspace**. How do I do that with Copilot CLI?
+
+### 15:45 Response
+
+Copilot CLI doesn't have a multi-root workspace concept. It operates from whatever directory you `cd` into. Two practical options:
+
+**Option 1 (recommended): Run from the monorepo, reference Java repo by relative path**
+
+```powershell
+cd c:\Users\edburns\workareas\copilot-sdk-00
+copilot --yolo
+```
+
+Then in your prompt, tell it:
+
+> The Java SDK source repo is at copilot-sdk-java-00. Read copilot-sdk-java.instructions.md for the source content.
+
+This way the monorepo's copilot-instructions.md is automatically discovered (it's in the git root), and the agent can still read files from the sibling repo via copilot-sdk-java-00.
+
+**Option 2: Run from the common parent**
+
+```powershell
+cd c:\Users\edburns\workareas
+copilot --yolo
+```
+
+Both repos are accessible as `copilot-sdk-00/` and `copilot-sdk-java-00/`, but **neither repo's copilot-instructions.md will be auto-loaded** since the parent isn't a git repo.
+
+**I'd go with Option 1** — the monorepo is where all changes land, and the plan document already tells the agent exactly which files to read from the Java repo. You might want to update the plan's Step 2 to explicitly say copilot-sdk-java.instructions.md so the path is unambiguous.
+
+### 15:46 Prompt
+
+Yes, use the relative path option.
+
+Please update the plan to use the relative path thing. Assume `../copilot-sdk-java-00` is the relative path from the `copilot-sdk-00` directory in which I will run copilot --yolo.
+
+### 15:47 Response
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/80-java-monorepo-add-01-remove-before-merge/dd-2998002-make-the-monorepo-smart-about-java-plan.md#1-1), lines 1 to 60
+
+Read [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/80-java-monorepo-add-01-remove-before-merge/dd-2998002-make-the-monorepo-smart-about-java-plan.md#55-55), lines 55 to 120
+
+Now I have the full picture. The references to update are in Steps 2 and 5 where the plan tells the agent where to find files from the Java repo.
+
+Replacing 21 lines with 22 lines in [](file:///c%3A/Users/edburns/workareas/copilot-sdk-00/80-java-monorepo-add-01-remove-before-merge/dd-2998002-make-the-monorepo-smart-about-java-plan.md)
+
+```
+
+```
+
+Updated the plan with four changes:
+
+1. **Added "Execution Context" section** — tells the agent it's running from the monorepo root and the Java repo is at copilot-sdk-java-00 (read-only)
+2. **Step 2** — source file path is now copilot-sdk-java.instructions.md
+3. **Step 3 body content** — references the same copilot-sdk-java-00 path
+4. **Step 5** — governance file path is now copilot-instructions.md
+
+Made changes.