-
Notifications
You must be signed in to change notification settings - Fork 3.9k
feat: add optional opsx brief workflow #1215
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
kime541200
wants to merge
4
commits into
Fission-AI:main
Choose a base branch
from
kime541200:feat/brief-workflow
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
948af51
feat: add optional opsx brief workflow
kime541200 4978ed0
fix: make brief selection prompt agent-agnostic
kime541200 24fbdd4
fix(brief): tighten generated HTML guardrails
kime541200 ffb96e3
docs(brief): add language tags to opsx:brief code fences
kime541200 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| ## Context | ||
|
|
||
| OpenSpec already separates CLI context helpers from agent workflows. Commands such as `/opsx:propose`, `/opsx:apply`, and `/opsx:verify` are generated from workflow templates, while CLI commands provide structured data through `status --json` and `instructions apply --json`. | ||
|
|
||
| The brief workflow should follow that model: agent synthesis belongs in the generated OPSX workflow, not in a deterministic CLI summary command. | ||
|
|
||
| ## Goals / Non-Goals | ||
|
|
||
| Goals: | ||
| - Add `/opsx:brief` as an optional workflow users can select through custom profiles. | ||
| - Generate both skill and slash-command variants through the existing template pipeline. | ||
| - Keep `brief` out of the default `core` profile. | ||
| - Instruct agents to create a static `brief.html` in the change directory. | ||
|
|
||
| Non-goals: | ||
| - Add a new first-class `openspec brief` CLI command. | ||
| - Introduce LLM provider configuration into the CLI. | ||
| - Make `brief.html` authoritative over the original change artifacts. | ||
| - Generate a parallel `brief.md` file. | ||
|
|
||
| ## Decisions | ||
|
|
||
| ### Decision: Model brief as an optional OPSX workflow | ||
|
|
||
| Use the same `SkillTemplate` and `CommandTemplate` pattern as the existing OPSX workflows. This keeps installation, delivery mode, tool adapters, and profile selection consistent with the rest of OpenSpec. | ||
|
|
||
| Alternative considered: add `openspec brief`. That would either be a weak deterministic summary or require provider/key/model concerns in the CLI, which is too broad for this feature. | ||
|
|
||
| ### Decision: Include brief in `ALL_WORKFLOWS`, not `CORE_WORKFLOWS` | ||
|
|
||
| `brief` is useful for review-heavy flows, but not every user needs another command in the default path. Keeping it optional avoids making core setup heavier while still allowing users to install it through `openspec config profile`. | ||
|
|
||
| ### Decision: Write only `brief.html` | ||
|
|
||
| The requested review surface is browser-readable HTML. A second `brief.md` output would create synchronization questions without being needed for the MVP. | ||
|
|
||
| ### Decision: Keep generated HTML self-contained and project-neutral | ||
|
|
||
| The workflow should instruct agents to use inline CSS and system fonts only. It should not pull Google Fonts, CDN assets, remote images, or any other network resources into `brief.html`. | ||
|
|
||
| The generated page should also avoid unrelated product names, project names, footers, and agent-specific implementation labels unless those details come from the source artifacts. This keeps the workflow portable across OpenSpec users and prevents local helper templates from leaking repo- or harness-specific branding into official output. | ||
|
|
||
| ## Risks / Trade-offs | ||
|
|
||
| - [Risk] Agent-generated summaries can be inaccurate. -> Mitigation: require source attribution, require missing information to be called out, and state that original artifacts remain authoritative. | ||
| - [Risk] `open` behavior is platform-specific. -> Mitigation: document best-effort opener commands and treat opener failure as non-fatal. | ||
| - [Risk] Adding a workflow id can affect profile drift detection and generated command cleanup. -> Mitigation: update workflow maps and targeted tests around profile, generation, and tool detection. | ||
| - [Risk] Local or agent-specific brief templates can leak unrelated branding or external assets. -> Mitigation: require standalone, project-neutral HTML and explicitly forbid remote fonts, CDN links, network assets, unrelated footers, and harness-specific labels unless sourced from artifacts. | ||
|
|
||
| ## Migration Plan | ||
|
|
||
| No data migration is required. Existing users keep the same `core` workflow set. Users who want `/opsx:brief` can select it with `openspec config profile` and apply it with `openspec update`. | ||
|
|
||
| ## Open Questions | ||
|
|
||
| None for the MVP. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| ## Why | ||
|
|
||
| OpenSpec changes can contain several authoritative artifacts: `proposal.md`, delta specs, `design.md`, and `tasks.md`. After `/opsx:propose`, users may need to review the resulting intent before implementation, but reading every artifact in full is slow and easy to lose. | ||
|
|
||
| The workflow needs an optional agent-generated review surface that summarizes the change accurately without becoming the source of truth. | ||
|
|
||
| ## What Changes | ||
|
|
||
| - Add an optional `/opsx:brief` workflow that produces a one-page HTML brief for an existing change. | ||
| - The workflow reads the change status and apply context from the OpenSpec CLI, then reads the artifact files listed in `contextFiles`. | ||
| - The agent synthesizes a concise human-readable brief with source attribution, full source artifact coverage, risks, questions, implementation order, and verification plan. | ||
| - The generated HTML is standalone and generic to the OpenSpec change: no external fonts, CDN links, network assets, unrelated branding, or agent-specific implementation labels. | ||
| - The workflow writes `brief.html` inside the change directory and best-effort opens it with the host OS. | ||
| - The workflow is selectable through the custom profile but is not included in the default `core` profile. | ||
|
|
||
| ## Capabilities | ||
|
|
||
| ### New Capabilities | ||
|
|
||
| - `opsx-brief-skill`: Optional OPSX workflow for generating a human-readable one-page HTML brief from change artifacts | ||
|
|
||
| ### Modified Capabilities | ||
|
|
||
| - `command-generation`: Includes the brief workflow in generated skills and slash commands when selected | ||
|
|
||
| ## Impact | ||
|
|
||
| - `src/core/templates/workflows/brief-change.ts` - new skill and command templates | ||
| - `src/core/shared/skill-generation.ts` - include brief templates in the shared generation pipeline | ||
| - `src/core/profiles.ts` and related drift/init/update helpers - include `brief` in all workflows, not core workflows | ||
| - `docs/commands.md`, `docs/workflows.md`, `docs/opsx.md` - document the optional workflow | ||
| - Tests for profile lists, template generation, and install/update behavior |
92 changes: 92 additions & 0 deletions
92
openspec/changes/add-brief-workflow/specs/opsx-brief-skill/spec.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,92 @@ | ||
| ## ADDED Requirements | ||
|
|
||
| ### Requirement: Brief Workflow Invocation | ||
| The system SHALL provide an optional `/opsx:brief` workflow that generates a human-readable HTML brief for an OpenSpec change. | ||
|
|
||
| #### Scenario: Brief with change name | ||
| - **WHEN** the user invokes `/opsx:brief <change-name>` | ||
| - **THEN** the agent SHALL generate a brief for that change | ||
| - **AND** write it to `openspec/changes/<change-name>/brief.html` | ||
|
|
||
| #### Scenario: Brief without change name | ||
| - **WHEN** the user invokes `/opsx:brief` without a change name | ||
| - **THEN** the agent SHALL select a change using the same change-selection conventions as other OPSX change workflows | ||
| - **AND** prompt the user when the change is ambiguous | ||
|
|
||
| ### Requirement: Artifact-Based Synthesis | ||
| The brief workflow SHALL synthesize content from existing OpenSpec artifacts without making the brief authoritative. | ||
|
|
||
| #### Scenario: Load change artifacts | ||
| - **WHEN** generating the brief | ||
| - **THEN** the agent SHALL run `openspec status --change "<name>" --json` | ||
| - **AND** run `openspec instructions apply --change "<name>" --json` | ||
| - **AND** read the artifact paths listed in `contextFiles` | ||
|
|
||
| #### Scenario: Missing artifacts | ||
| - **WHEN** some expected artifacts are missing | ||
| - **THEN** the brief SHALL still be generated from available artifacts | ||
| - **AND** identify missing or unspecified information instead of inventing it | ||
|
|
||
| #### Scenario: Source attribution | ||
| - **WHEN** the brief states a claim derived from an artifact | ||
| - **THEN** the brief SHALL include source attribution to the relevant artifact path or artifact id | ||
|
|
||
| #### Scenario: Source artifact coverage | ||
| - **WHEN** generating the source artifact index | ||
| - **THEN** the brief SHALL include every file path returned in `contextFiles` | ||
| - **AND** SHALL NOT silently omit delta spec files or schema-specific artifacts | ||
|
|
||
| #### Scenario: Inferred impacts | ||
| - **WHEN** the brief includes affected modules, file areas, behavior changes, risks, or questions not explicitly stated by artifacts | ||
| - **THEN** the brief SHALL label them as inference | ||
|
|
||
| ### Requirement: HTML Brief Content | ||
| The generated brief SHALL be concise, readable, and review-oriented. | ||
|
|
||
| #### Scenario: Required sections | ||
| - **WHEN** the brief is generated | ||
| - **THEN** it SHALL include sections for: | ||
| - what the change does | ||
| - explicit non-goals | ||
| - user-visible behavior changes | ||
| - affected modules or file areas | ||
| - key design decisions and trade-offs | ||
| - implementation order | ||
| - testing and verification plan | ||
| - risks and questions requiring user confirmation | ||
| - source artifact index | ||
|
|
||
| #### Scenario: Static local HTML | ||
| - **WHEN** writing `brief.html` | ||
| - **THEN** the file SHALL be standalone static HTML | ||
| - **AND** SHALL NOT depend on external JavaScript, CSS, fonts, CDN links, images, or network resources | ||
| - **AND** SHALL use system fonts instead of remote fonts | ||
|
|
||
| #### Scenario: Generic OpenSpec output | ||
| - **WHEN** writing `brief.html` | ||
| - **THEN** the file SHALL NOT include unrelated product names, project names, footers, or branding unless present in the source artifacts | ||
| - **AND** SHALL NOT include agent- or harness-specific paths or labels unless present in the source artifacts | ||
|
|
||
| ### Requirement: Optional Workflow Installation | ||
| The brief workflow SHALL be available for custom profile selection but not installed by the default core profile. | ||
|
|
||
| #### Scenario: Core profile | ||
| - **WHEN** OpenSpec resolves the default `core` workflow profile | ||
| - **THEN** `brief` SHALL NOT be included | ||
|
|
||
| #### Scenario: Custom profile | ||
| - **WHEN** the user selects `brief` in a custom workflow profile | ||
| - **THEN** OpenSpec SHALL generate the corresponding skill and command files according to the configured delivery mode | ||
|
|
||
| ### Requirement: Best-Effort Opening | ||
| The brief workflow SHALL attempt to open the generated HTML file without treating opener failures as brief generation failures. | ||
|
|
||
| #### Scenario: Open succeeds | ||
| - **WHEN** the agent writes `brief.html` | ||
| - **AND** the host opener command succeeds | ||
| - **THEN** the workflow SHALL report the generated file path and that it was opened | ||
|
|
||
| #### Scenario: Open fails | ||
| - **WHEN** the host opener command fails or is unavailable | ||
| - **THEN** the workflow SHALL report the generated file path clearly | ||
| - **AND** SHALL NOT treat the opener failure as a failed brief generation |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| ## 1. Workflow Template | ||
|
|
||
| - [x] 1.1 Add a brief workflow template module with skill and command variants | ||
| - [x] 1.2 Ensure the workflow selects a change using existing OPSX conventions | ||
| - [x] 1.3 Instruct agents to read `status --json`, `instructions apply --json`, and all `contextFiles` | ||
| - [x] 1.4 Require a static local `brief.html` output with source attribution and no external assets | ||
| - [x] 1.5 Include best-effort OS opener behavior with graceful fallback | ||
| - [x] 1.6 Add fidelity guardrails for source artifact coverage, inferred impacts, task grouping, and project-neutral HTML output | ||
|
|
||
| ## 2. Generation Integration | ||
|
|
||
| - [x] 2.1 Export the brief workflow template through the template facade | ||
| - [x] 2.2 Add `brief` to shared skill and command generation mappings | ||
| - [x] 2.3 Add `brief` to `ALL_WORKFLOWS` without adding it to `CORE_WORKFLOWS` | ||
| - [x] 2.4 Update workflow-to-skill directory mappings used by init/update/drift detection | ||
|
|
||
| ## 3. Documentation | ||
|
|
||
| - [x] 3.1 Document `/opsx:brief` in command reference tables | ||
| - [x] 3.2 Explain when to use brief in the workflow guide | ||
| - [x] 3.3 Clarify that brief is an optional review surface, not a source of truth | ||
|
|
||
| ## 4. Tests | ||
|
|
||
| - [x] 4.1 Update profile tests for the new optional workflow count and ordering | ||
| - [x] 4.2 Update skill-generation tests to include brief templates and filtering | ||
| - [x] 4.3 Update init/update or drift tests affected by the new workflow mapping | ||
| - [x] 4.4 Add focused assertions that core profile excludes `brief` | ||
| - [x] 4.5 Run targeted tests for profiles, skill generation, and changed init/update behavior |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -22,6 +22,7 @@ export const ALL_WORKFLOWS = [ | |
| 'new', | ||
| 'continue', | ||
| 'apply', | ||
| 'brief', | ||
| 'ff', | ||
| 'sync', | ||
| 'archive', | ||
|
|
||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.