Name: openspec-backfill
Author: yicone

Prompt file imported from yicone/agent-steward (.windsurf/workflows/openspec-backfill.md). Copyright stays with the author.

Use this workflow when code and behaviour already exist, but there is no corresponding OpenSpec change documenting the current intended behaviour.

This workflow is for backfilling existing behaviour. For future/planned work, use /opsx:propose instead.

1. Confirm this is really a backfill

Use this workflow only when all are true:

The code and externally visible behaviour already exist.
The behaviour is intended to remain.
There is no active OpenSpec change already capturing the same behaviour.

If the behaviour is still under discussion or likely to change during implementation, use /opsx:propose instead.

2. Ensure the repository is initialized for the current CLI

Check whether OpenSpec has been initialized for this repo.
If openspec/changes/ is missing or OpenSpec reports initialization errors, run:
```
openspec init
```
After initialization, prefer the current generated integrations:
- Windsurf workflows: /opsx:propose, /opsx:explore, /opsx:apply, /opsx:archive
- Codex skills: openspec-propose, openspec-explore, openspec-apply-change, openspec-archive-change

3. Choose a verb-led backfill change id

Pick a unique kebab-case, verb-led change id.
Prefer names like:
- backfill-subagent-support
- document-codex-metadata-enrichment
- capture-conversation-filter-behaviour
Check for collisions:
```
openspec list --json
```

4. Create the change with the current CLI flow

Create the change using the current artifact-guided workflow:

openspec new change "<change-id>"
openspec status --change "<change-id>" --json

Do not manually scaffold directories first unless the CLI is unavailable.

5. Build artifacts using CLI instructions

For the new change, use the current CLI instruction flow:

openspec instructions proposal --change "<change-id>" --json
openspec instructions design --change "<change-id>" --json
openspec instructions specs --change "<change-id>" --json
openspec instructions tasks --change "<change-id>" --json

Follow the returned instruction, template, outputPath, and dependency ordering.

Proposal guidance

State that this is a backfill of already-implemented behaviour.
Name the capability or capabilities being introduced or modified.
List the already-implemented code paths affected.

Design guidance

Explain the current architecture and normalization/decision points.
Record current constraints and trade-offs.
Do not invent future behavior unless explicitly requested.

Specs guidance

Create one spec file per capability listed in the proposal.
Use delta sections exactly as required by the CLI:
- ## ADDED Requirements
- ## MODIFIED Requirements
- ## REMOVED Requirements
- ## RENAMED Requirements
Use #### Scenario: blocks with WHEN / THEN format.
For modified requirements, copy the entire existing requirement block before editing.

Tasks guidance

Because this is a backfill, tasks should focus on:

Reviewing current code and behavior
Aligning proposal / design / specs with reality
Running validation
Updating adjacent docs only if needed

Tasks do not need to imply new feature work unless the backfill reveals a real mismatch that must be fixed.

6. Align artifacts with the existing codebase

Cross-check the artifacts against:

Current implementation
Existing tests
Relevant docs
Known shipped behavior in CHANGELOG.md

If you discover a mismatch, choose explicitly:

Fix the code to match intended behavior, then document that behavior
Or accept the current behavior and document it clearly

Avoid leaving hidden behavior undocumented.

7. Validate with the current CLI

Run strict validation on the change:

openspec validate <change-id> --strict

If validation fails, fix the artifacts and rerun until it passes.

Useful follow-up checks:

openspec status --change "<change-id>" --json

8. Hand off or continue

After a successful backfill:

If no code change is needed, stop and report that the spec baseline is ready.
If follow-up implementation is needed, continue with /opsx:apply.
If more design clarification is needed, use /opsx:explore.

9. Archive only after the backfill becomes the accepted baseline

Once the documented behaviour is accepted and deployed as the new truth, archive the change:

openspec archive <change-id> --yes

If the change is docs-only or should not update main specs during archive, decide explicitly whether --skip-specs is appropriate.

Install openspec-backfill and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

Use this workflow when code and behaviour already exist, but there is no corresponding OpenSpec change documenting the current intended behaviour. This workflow is for **backfilling existing behaviour**. For future/planned work, use `/opsx:propose` instead. ## 1. Confirm this is really a backfill Use this workflow only when all are true: - The code and externally visible behaviour already exist. - The behaviour is intended to remain. - There is no active OpenSpec change already capturing the same behaviour. If the behaviour is still under discussion or likely to change during implementation, use `/opsx:propose` instead. ## 2. Ensure the repository is initialized for the current CLI 1. Check whether OpenSpec has been initialized for this repo. 2. If `openspec/changes/` is missing or OpenSpec reports initialization errors, run: ```bash openspec init ``` 3. After initialization, prefer the current generated integrations: - Windsurf workflows: `/opsx:propose`, `/opsx:explore`, `/opsx:apply`, `/opsx:archive` - Codex skills: `openspec-propose`, `openspec-explore`, `openspec-apply-change`, `openspec-archive-change` ## 3. Choose a verb-led backfill change id 1. Pick a unique kebab-case, verb-led change id. 2. Prefer names like: - `backfill-subagent-support` - `document-codex-metadata-enrichment` - `capture-conversation-filter-behaviour` 3. Check for collisions: ```bash openspec list --json ``` ## 4. Create the change with the current CLI flow Create the change using the current artifact-guided workflow: ```bash openspec new change "<change-id>" openspec status --change "<change-id>" --json ``` Do **not** manually scaffold directories first unless the CLI is unavailable. ## 5. Build artifacts using CLI instructions For the new change, use the current CLI instruction flow: ```bash openspec instructions proposal --change "<change-id>" --json openspec instructions design --change "<change-id>" --json openspec instructions specs --change "<change-id>" --json openspec instructions tasks --change "<change-id>" --json ``` Follow the returned `instruction`, `template`, `outputPath`, and dependency ordering. ### Proposal guidance - State that this is a backfill of already-implemented behaviour. - Name the capability or capabilities being introduced or modified. - List the already-implemented code paths affected. ### Design guidance - Explain the current architecture and normalization/decision points. - Record current constraints and trade-offs. - Do not invent future behavior unless explicitly requested. ### Specs guidance - Create one spec file per capability listed in the proposal. - Use delta sections exactly as required by the CLI: - `## ADDED Requirements` - `## MODIFIED Requirements` - `## REMOVED Requirements` - `## RENAMED Requirements` - Use `#### Scenario:` blocks with `WHEN` / `THEN` format. - For modified requirements, copy the entire existing requirement block before editing. ### Tasks guidance Because this is a backfill, tasks should focus on: - Reviewing current code and behavior - Aligning proposal / design / specs with reality - Running validation - Updating adjacent docs only if needed Tasks do **not** need to imply new feature work unless the backfill reveals a real mismatch that must be fixed. ## 6. Align artifacts with the existing codebase Cross-check the artifacts against: - Current implementation - Existing tests - Relevant docs - Known shipped behavior in `CHANGELOG.md` If you discover a mismatch, choose explicitly: - Fix the code to match intended behavior, then document that behavior - Or accept the current behavior and document it clearly Avoid leaving hidden behavior undocumented. ## 7. Validate with the current CLI Run strict validation on the change: ```bash openspec validate <change-id> --strict ``` If validation fails, fix the artifacts and rerun until it passes. Useful follow-up checks: ```bash openspec status --change "<change-id>" --json ``` ## 8. Hand off or continue After a successful backfill: - If no code change is needed, stop and report that the spec baseline is ready. - If follow-up implementation is needed, continue with `/opsx:apply`. - If more design clarification is needed, use `/opsx:explore`. ## 9. Archive only after the backfill becomes the accepted baseline Once the documented behaviour is accepted and deployed as the new truth, archive the change: ```bash openspec archive <change-id> --yes ``` If the change is docs-only or should not update main specs during archive, decide explicitly whether `--skip-specs` is appropriate.

{ "prompt": "Use this workflow when code and behaviour already exist, but there is no corresponding OpenSpec change documenting the current intended behaviour.\n\nThis workflow is for **backfilling existing behaviour**.\nFor future/planned work, use `/opsx:propose` instead.\n\n## 1. Confirm this is really a backfill\n\nUse this workflow only when all are true:\n\n- The code and externally visible behaviour already exist.\n- The behaviour is intended to remain.\n- There is no active OpenSpec change already capturing the same behaviour.\n\nIf the behaviour is still under discussion or likely to change during implementation, use `/opsx:propose` instead.\n\n## 2. Ensure the repository is initialized for the current CLI\n\n1. Check whether OpenSpec has been initialized for this repo.\n2. If `openspec/changes/` is missing or OpenSpec reports initialization errors, run:\n\n ```bash\n openspec init\n ```\n\n3. After initialization, prefer the current generated integrations:\n - Windsurf workflows: `/opsx:propose`, `/opsx:explore`, `/opsx:apply`, `/opsx:archive`\n - Codex skills: `openspec-propose`, `openspec-explore`, `openspec-apply-change`, `openspec-archive-change`\n\n## 3. Choose a verb-led backfill change id\n\n1. Pick a unique kebab-case, verb-led change id.\n2. Prefer names like:\n - `backfill-subagent-support`\n - `document-codex-metadata-enrichment`\n - `capture-conversation-filter-behaviour`\n\n3. Check for collisions:\n\n ```bash\n openspec list --json\n ```\n\n## 4. Create the change with the current CLI flow\n\nCreate the change using the current artifact-guided workflow:\n\n```bash\nopenspec new change \"<change-id>\"\nopenspec status --change \"<change-id>\" --json\n```\n\nDo **not** manually scaffold directories first unless the CLI is unavailable.\n\n## 5. Build artifacts using CLI instructions\n\nFor the new change, use the current CLI instruction flow:\n\n```bash\nopenspec instructions proposal --change \"<change-id>\" --json\nopenspec instructions design --change \"<change-id>\" --json\nopenspec instructions specs --change \"<change-id>\" --json\nopenspec instructions tasks --change \"<change-id>\" --json\n```\n\nFollow the returned `instruction`, `template`, `outputPath`, and dependency ordering.\n\n### Proposal guidance\n\n- State that this is a backfill of already-implemented behaviour.\n- Name the capability or capabilities being introduced or modified.\n- List the already-implemented code paths affected.\n\n### Design guidance\n\n- Explain the current architecture and normalization/decision points.\n- Record current constraints and trade-offs.\n- Do not invent future behavior unless explicitly requested.\n\n### Specs guidance\n\n- Create one spec file per capability listed in the proposal.\n- Use delta sections exactly as required by the CLI:\n - `## ADDED Requirements`\n - `## MODIFIED Requirements`\n - `## REMOVED Requirements`\n - `## RENAMED Requirements`\n- Use `#### Scenario:` blocks with `WHEN` / `THEN` format.\n- For modified requirements, copy the entire existing requirement block before editing.\n\n### Tasks guidance\n\nBecause this is a backfill, tasks should focus on:\n\n- Reviewing current code and behavior\n- Aligning proposal / design / specs with reality\n- Running validation\n- Updating adjacent docs only if needed\n\nTasks do **not** need to imply new feature work unless the backfill reveals a real mismatch that must be fixed.\n\n## 6. Align artifacts with the existing codebase\n\nCross-check the artifacts against:\n\n- Current implementation\n- Existing tests\n- Relevant docs\n- Known shipped behavior in `CHANGELOG.md`\n\nIf you discover a mismatch, choose explicitly:\n\n- Fix the code to match intended behavior, then document that behavior\n- Or accept the current behavior and document it clearly\n\nAvoid leaving hidden behavior undocumented.\n\n## 7. Validate with the current CLI\n\nRun strict validation on the change:\n\n```bash\nopenspec validate <change-id> --strict\n```\n\nIf validation fails, fix the artifacts and rerun until it passes.\n\nUseful follow-up checks:\n\n```bash\nopenspec status --change \"<change-id>\" --json\n```\n\n## 8. Hand off or continue\n\nAfter a successful backfill:\n\n- If no code change is needed, stop and report that the spec baseline is ready.\n- If follow-up implementation is needed, continue with `/opsx:apply`.\n- If more design clarification is needed, use `/opsx:explore`.\n\n## 9. Archive only after the backfill becomes the accepted baseline\n\nOnce the documented behaviour is accepted and deployed as the new truth, archive the change:\n\n```bash\nopenspec archive <change-id> --yes\n```\n\nIf the change is docs-only or should not update main specs during archive, decide explicitly whether `--skip-specs` is appropriate.", "variables": [], "notes": "Backfill an OpenSpec change for behaviour that is already implemented in code", "metadata": { "source": { "provider": "github-windsurf-workflows", "repository": "https://github.com/yicone/agent-steward", "path": ".windsurf/workflows/openspec-backfill.md", "ref": "b218576f2f422c09f27359cc2052fbeaa1714733", "url": "https://github.com/yicone/agent-steward/blob/b218576f2f422c09f27359cc2052fbeaa1714733/.windsurf/workflows/openspec-backfill.md", "key": "yicone/agent-steward/.windsurf/workflows/openspec-backfill.md" } } }

openspec-backfill

About