mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-09-14 20:16:53 +08:00
Tabish Bidiwale
29 lines
2.4 KiB
Markdown
29 lines
2.4 KiB
Markdown
# Add AGENTS.md Standard Support To Init/Update
|
|
|
|
## Summary
|
|
- Teach `openspec init` to manage a root-level `AGENTS.md` file using the same marker system as `CLAUDE.md`.
|
|
- Allow `openspec update` to refresh or scaffold that root `AGENTS.md` so AGENTS-compatible tools always receive current instructions.
|
|
- Keep the existing `openspec/AGENTS.md` template as the canonical source while ensuring assistants that read `AGENTS.md` opt-in instructions get the latest guidance automatically.
|
|
|
|
## Motivation
|
|
The README now points teams to AGENTS.md-compatible assistants, but the CLI only manages `CLAUDE.md`. Projects must hand-roll a root `AGENTS.md` file to benefit from the standard, and updates will drift unless maintainers remember to copy content manually. Extending `init` and `update` closes that gap so OpenSpec actually delivers on the promise of first-class AGENTS support.
|
|
|
|
## Proposal
|
|
1. Extend the `openspec init` selection flow with an "AGENTS.md standard" option that creates or refreshes a root `AGENTS.md` file wrapped in OpenSpec markers, mirroring the existing CLAUDE integration.
|
|
2. When generating the file, pull the managed content from the same template used in `openspec/AGENTS.md`, ensuring both locations stay in sync.
|
|
3. Update `openspec update` so it always refreshes the root `AGENTS.md` (creating it if missing) alongside `openspec/AGENTS.md` and any other configured assistants.
|
|
4. Document the new behavior in CLI specs and verify marker handling (no duplicates, preserve user content outside the block) with tests for both commands.
|
|
|
|
## Out of Scope
|
|
- Adding additional AGENTS-specific prompts or workflows beyond the shared instructions block.
|
|
- Non-interactive flags or bulk configuration for multiple standards in one run.
|
|
- Broader restructuring of how templates are stored or loaded.
|
|
|
|
## Risks & Mitigations
|
|
- **Risk:** Accidentally overwriting user-edited content surrounding the managed block.
|
|
- **Mitigation:** Reuse the existing marker-update helper shared with `CLAUDE.md`, and add tests that cover files containing custom text before and after the block.
|
|
- **Risk:** Divergence between `openspec/AGENTS.md` and the root file.
|
|
- **Mitigation:** Source the root file content from the canonical template rather than duplicating strings inline.
|
|
- **Risk:** Confusion about when the file is created.
|
|
- **Mitigation:** Log creation vs update, and ensure help text references the AGENTS option during `init`.
|