feat: generate Copilot coding agent files on openspec init (github-copilot)

[NicoAvanzDev]

Restores and updates #858 on top of current main.

Summary

When a user runs openspec init or openspec update with the github-copilot tool configured, OpenSpec generates the GitHub Copilot coding agent support files:

• .github/workflows/copilot-setup-steps.yml
• .github/agents/openspec.agent.md

The generated files are only written when missing, so user customizations are preserved. If github-copilot is no longer configured, openspec update removes the generated cloud-agent files when present.

Drift handled while restoring

• Rebased the original two commits from feat: generate Copilot coding agent files on openspec init (github-copilot) #858 onto current main.
• Updated the custom agent tool aliases to current Copilot custom-agent names (execute, read, search, edit).
• Moved openspec update cloud-file sync so the files are created even when github-copilot is already up to date and smart update exits early.
• Added file-operation coverage for write/skip/force/remove behavior plus an update regression test for the up-to-date path.

Testing

./node_modules/.bin/vitest run test/core/github-copilot-cloud-agent.test.ts test/core/update.test.ts
npm run build --ignore-scripts
git diff --check origin/main...HEAD

Restored from closed PR: #858

Summary by CodeRabbit

• New Features
  • Added GitHub Copilot Cloud support that generates Copilot setup workflow and agent guidance files when Copilot is selected.
  • These files are created during initialization and synchronized during update runs.
• Bug Fixes
  • Copilot Cloud files are removed when Copilot is no longer selected to avoid stale configuration.
  • Update recreates missing/outdated Copilot Cloud files and ignores Copilot sync failures so the update continues.
• Tests
  • Added Vitest coverage for Copilot Cloud file generation, write/force behavior, and safe cleanup that preserves user customizations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: be5d3f3c-6e6b-4d52-a87d-ae6b76230d9e

📥 Commits

Reviewing files that changed from the base of the PR and between 8349bb9 and 4388e7f.

📒 Files selected for processing (2)

• src/core/github-copilot/cloud-agent.ts
• test/core/github-copilot-cloud-agent.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/core/github-copilot/cloud-agent.ts

---

📝 Walkthrough

Walkthrough

Adds a new Copilot cloud-agent module that generates, writes, and removes two .github files. InitCommand and UpdateCommand now sync those files when github-copilot is selected, and tests cover generation plus filesystem behavior.

Changes

Copilot Cloud Agent Files

Layer / File(s)	Summary
cloud-agent.ts: detection, generation, write, and remove src/core/github-copilot/cloud-agent.ts	Defines includesGitHubCopilot, generateCopilotSetupSteps, generateCopilotAgentFile, COPILOT_CLOUD_FILES, writeCopilotCloudFiles, and removeCopilotCloudFiles.
Init and Update command integration src/core/init.ts, src/core/update.ts	Init conditionally writes Copilot cloud files after tool setup with errors swallowed. Update adds syncCopilotCloudFiles and calls it in the no-tools early-return, the up-to-date early-return, and post-update paths; errors are non-fatal.
cloud-agent.ts helpers and filesystem tests test/core/github-copilot-cloud-agent.test.ts	Tests cover detection, both generators, managed file paths, write/remove filesystem behavior, and legacy agent removal handling.
Update command Copilot sync tests test/core/update.test.ts	Tests verify update removes Copilot cloud files when no tools are configured and recreates them when Copilot is up to date.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Fission-AI/OpenSpec#917: Changes Copilot auto-detection to look for the same .github/workflows/copilot-setup-steps.yml and agents paths that this PR generates and syncs.

Suggested reviewers

• TabishB

Poem

A rabbit in .github did hop,
With workflow and agent files at the top.
When Copilot appears, the files come to stay,
And tidy removal can sweep them away.
Hops, sniffles, and scripts in a neat little nest—
OpenSpec’s cloud helpers are doing their best.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: generating GitHub Copilot agent files during openspec init for the github-copilot tool.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/core/github-copilot/cloud-agent.ts`:
- Around line 186-199: The cleanup in removeCopilotCloudFiles currently deletes
any existing file at the Copilot cloud paths, which can remove user-customized
files. Update removeCopilotCloudFiles to only unlink files that are known to be
generated/managed by the extension, and skip files that have been modified or
created by the user; use COPILOT_CLOUD_FILES and FileSystemUtils.fileExists as
the entry points for the check, and add a reliable ownership/safeguard before
calling fs.promises.unlink.

In `@src/core/update.ts`:
- Line 156: The no-tools early return in execute() is skipping Copilot file
cleanup, so stale cloud files can remain when github-copilot is removed. Move
the syncCopilotCloudFiles call in update.ts so it runs before the return path
that handles an empty tools list, and make sure both execute() and the related
sync flow around syncCopilotCloudFiles use the resolvedProjectPath and tool set
consistently even when there are no configured tools.

In `@test/core/github-copilot-cloud-agent.test.ts`:
- Around line 51-60: The test in generateCopilotAgentFile only verifies the
presence of execute, so it can miss regressions in the Copilot agent tool
aliases. Tighten the expectations in github-copilot-cloud-agent.test.ts to
assert all four aliases exposed by the updated contract are present: execute,
read, search, and edit, alongside the existing frontmatter and command checks.
- Around line 63-67: The COPILOT_CLOUD_FILES path assertions are too loose
because `toContain(...)` only checks filenames and can miss incorrect parent
directories or POSIX-only regressions. Update the
`github-copilot-cloud-agent.test.ts` checks to compare the full expected
relative paths using `path.join(...)`, referencing
`COPILOT_CLOUD_FILES.setupSteps` and `COPILOT_CLOUD_FILES.agent` so the test
validates separator behavior on Windows as well.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d3078b54-83db-4187-acde-3e207441355f

📥 Commits

Reviewing files that changed from the base of the PR and between 546224e and 6298928.

📒 Files selected for processing (5)

• src/core/github-copilot/cloud-agent.ts
• src/core/init.ts
• src/core/update.ts
• test/core/github-copilot-cloud-agent.test.ts
• test/core/update.test.ts

[alfred-openspec]

Thanks for restoring this. The current guard is much safer for customized files, but I think the cleanup is now too strict: removeCopilotCloudFiles() only deletes files whose content exactly matches the current generated template.

That means a user who generated these files with an older OpenSpec version, then removed github-copilot, would keep stale generated .github/workflows/copilot-setup-steps.yml / .github/agents/openspec.agent.md files forever. That is the path this PR is explicitly trying to clean up.

I’d change the ownership check to recognize OpenSpec-generated legacy/current variants, e.g. a managed marker in new files plus a conservative legacy recognizer for the two templates this PR introduced. Customized files should still be skipped, but previously generated files should be removable when github-copilot is no longer configured.

Verified locally: pnpm exec vitest run test/core/github-copilot-cloud-agent.test.ts test/core/update.test.ts passes, 70 tests.

[NicoAvanzDev]

Thanks for restoring this. The current guard is much safer for customized files, but I think the cleanup is now too strict: removeCopilotCloudFiles() only deletes files whose content exactly matches the current generated template.

That means a user who generated these files with an older OpenSpec version, then removed github-copilot, would keep stale generated .github/workflows/copilot-setup-steps.yml / .github/agents/openspec.agent.md files forever. That is the path this PR is explicitly trying to clean up.

I’d change the ownership check to recognize OpenSpec-generated legacy/current variants, e.g. a managed marker in new files plus a conservative legacy recognizer for the two templates this PR introduced. Customized files should still be skipped, but previously generated files should be removable when github-copilot is no longer configured.

Verified locally: pnpm exec vitest run test/core/github-copilot-cloud-agent.test.ts test/core/update.test.ts passes, 70 tests.

Thanks for reviewing this, I changed the cleanup logic and added tests for edge cases.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@test/core/github-copilot-cloud-agent.test.ts`:
- Around line 17-45: The synthetic legacy fixture helpers currently use silent
string replacements, so template drift can go unnoticed and the legacy-removal
path may stop being exercised. Harden removeManagedMarker and
generateLegacyCopilotAgentFile by asserting each expected replace target exists
before transforming the content, and fail the test immediately if any marker or
legacy text is missing. This should make the fixture generation loud when
generateCopilotAgentFile changes and keep the markerless/legacy tests
meaningful.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 863f6c2d-366b-4903-b8e9-a310e29e3a28

📥 Commits

Reviewing files that changed from the base of the PR and between e0a33e4 and 8349bb9.

📒 Files selected for processing (2)

• src/core/github-copilot/cloud-agent.ts
• test/core/github-copilot-cloud-agent.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/core/github-copilot/cloud-agent.ts

[alfred-openspec]

Looks good. The latest commits address the legacy cleanup path without deleting customized files, and the fixture hardening makes the markerless legacy tests fail loudly if the generated templates drift.\n\nVerified locally: pnpm exec vitest run test/core/github-copilot-cloud-agent.test.ts test/core/update.test.ts, pnpm run lint, and pnpm run build.