feat: add optional opsx brief workflow

[kime541200]

Summary

• add optional /opsx:brief workflow as generated skill/command templates
• include brief in custom workflow selection without adding it to the core profile
• document the workflow and add OpenSpec change artifacts plus generation/profile tests

Verification

• node build.js
• ./node_modules/.bin/eslint src/
• ./node_modules/.bin/vitest run
• node bin/openspec.js validate add-brief-workflow --strict
• node bin/openspec.js status --change add-brief-workflow --json

Summary by CodeRabbit

Release Notes

• New Features

  • Added /opsx:brief to generate a one-page, standalone brief.html review brief from existing change artifacts, including source attribution and explicit handling of missing/uncertain info (no guessing).
  • Best-effort: attempts to open the generated brief in your browser.
  • Available as an optional expanded workflow (not included in the default core set).

• Documentation

  • Updated commands/workflow reference docs and supported tools to include /opsx:brief.

• Tests

  • Extended test coverage to validate the new workflow/command and non-core behavior.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

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: 0a79fc16-6cd9-4010-ba14-4c0067f34acb

📥 Commits

Reviewing files that changed from the base of the PR and between 24fbdd4 and ffb96e3.

📒 Files selected for processing (2)

• docs/commands.md
• docs/opsx.md

✅ Files skipped from review due to trivial changes (2)

• docs/commands.md
• docs/opsx.md

---

📝 Walkthrough

Walkthrough

Adds an optional /opsx:brief workflow that generates a standalone static brief.html from existing OpenSpec change artifacts. The workflow is registered in profiles, template generation, tool detection, drift detection, documentation, and tests.

Changes

Add /opsx:brief workflow

Layer / File(s)	Summary
OpenSpec change artifacts openspec/changes/add-brief-workflow/proposal.md, openspec/changes/add-brief-workflow/design.md, openspec/changes/add-brief-workflow/specs/opsx-brief-skill/spec.md, openspec/changes/add-brief-workflow/tasks.md	Defines /opsx:brief, its inputs, standalone HTML output, non-core profile placement, opener behavior, and implementation checklist.
Workflow registration and detection src/commands/config.ts, src/core/profiles.ts, src/core/init.ts, src/core/profile-sync-drift.ts, src/core/shared/tool-detection.ts	Adds brief to workflow metadata, workflow IDs, skill-dir mappings, and tool-detection name lists.
Template implementation and generation wiring src/core/templates/workflows/brief-change.ts, src/core/templates/skill-templates.ts, src/core/shared/skill-generation.ts	Adds the brief workflow prompt/template module, re-exports it, and registers the new skill and command templates.
Documentation and validation docs/commands.md, docs/opsx.md, docs/supported-tools.md, docs/workflows.md, test/core/profiles.test.ts, test/core/init.test.ts, test/core/update.test.ts, test/core/shared/skill-generation.test.ts, test/core/shared/tool-detection.test.ts, test/core/templates/skill-templates-parity.test.ts, test/utils/command-references.test.ts	Updates command references, workflow guidance, supported tools, and tests for registration, non-core exclusion, generated template counts, instruction constraints, and hash baselines.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Fission-AI/OpenSpec#626: Both PRs touch the /opsx: command reference and command transformation test coverage.
• Fission-AI/OpenSpec#698: Both PRs extend the OPSX workflow/skill generation plumbing with new template exports.
• Fission-AI/OpenSpec#736: Both PRs update shared workflow-to-skill directory mapping and drift-detection wiring.

Suggested reviewers

• TabishB
• alfred-openspec

Poem

🐇 I hopped through artifacts, tidy and bright,
and spun a brief.html in the soft moonlight.
No extra fluff, just facts in a shell,
with source and review notes kept neat and well.
If the browser won’t open, the path still appears—
a small static brief for the warren’s frontiers.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 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: adding an optional /opsx:brief workflow.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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.}

[alfred-openspec]

Thanks for putting this together. I like the shape: optional workflow, not core, generated through the same skill/command pipeline, and the source-attribution guardrails are the right boundary for a non-authoritative HTML review surface.

One change I’d make before merging: the new template names an AskUserQuestion tool for ambiguous change selection. That is not part of the stable cross-agent OpenSpec workflow contract, and these templates install across agents that will not have that tool. Please make this agent-agnostic, for example “ask the user to select from the available changes,” or mirror the wording from the apply/archive templates.

[kime541200]

Addressed in 9141c8f: the brief workflow selection instructions no longer reference the AskUserQuestion tool; they now ask the user to select from available changes in an agent-agnostic way.\n\nVerified with:\n- ./node_modules/.bin/vitest run test/core/templates/skill-templates-parity.test.ts

[alfred-openspec]

Looks good now. The ambiguous-change selection wording is agent-agnostic, and the optional workflow wiring matches the existing profile/template generation pattern.\n\nVerified locally: targeted profile/generation/init/update/reference tests passed (7 files / 183 tests), build passed, and openspec validate add-brief-workflow --strict passed.

[coderabbitai]

Actionable comments posted: 2

🤖 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 `@docs/commands.md`:
- Around line 321-360: The example fences in the /opsx:brief section are missing
a language identifier, causing the markdownlint warning. Update both fenced
blocks in the command example to include the same explicit language tag (use the
fence style already implied by the review comment) so the markdown remains
lint-clean; locate the change in the /opsx:brief documentation example rather
than the prose above or below it.

In `@docs/opsx.md`:
- Around line 206-213: The example fence in the “Review before implementation”
section is missing a language tag, causing the markdownlint warning. Update the
fenced block to use a language identifier such as text in the example around
/opsx:brief add-dark-mode, keeping the rest of the docs content unchanged.

🪄 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: a5a726fe-4393-4acf-ad81-a730ea6d46f8

📥 Commits

Reviewing files that changed from the base of the PR and between 68562ea and 24fbdd4.

📒 Files selected for processing (23)

• docs/commands.md
• docs/opsx.md
• docs/supported-tools.md
• docs/workflows.md
• openspec/changes/add-brief-workflow/design.md
• openspec/changes/add-brief-workflow/proposal.md
• openspec/changes/add-brief-workflow/specs/opsx-brief-skill/spec.md
• openspec/changes/add-brief-workflow/tasks.md
• src/commands/config.ts
• src/core/init.ts
• src/core/profile-sync-drift.ts
• src/core/profiles.ts
• src/core/shared/skill-generation.ts
• src/core/shared/tool-detection.ts
• src/core/templates/skill-templates.ts
• src/core/templates/workflows/brief-change.ts
• test/core/init.test.ts
• test/core/profiles.test.ts
• test/core/shared/skill-generation.test.ts
• test/core/shared/tool-detection.test.ts
• test/core/templates/skill-templates-parity.test.ts
• test/core/update.test.ts
• test/utils/command-references.test.ts

💤 Files with no reviewable changes (14)

• test/utils/command-references.test.ts
• test/core/shared/tool-detection.test.ts
• src/core/templates/skill-templates.ts
• src/core/profiles.ts
• src/core/profile-sync-drift.ts
• src/core/init.ts
• test/core/update.test.ts
• test/core/shared/skill-generation.test.ts
• src/core/templates/workflows/brief-change.ts
• src/core/shared/tool-detection.ts
• test/core/templates/skill-templates-parity.test.ts
• test/core/init.test.ts
• src/core/shared/skill-generation.ts
• test/core/profiles.test.ts

✅ Files skipped from review due to trivial changes (5)

• openspec/changes/add-brief-workflow/tasks.md
• docs/workflows.md
• src/commands/config.ts
• docs/supported-tools.md
• openspec/changes/add-brief-workflow/proposal.md

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

• openspec/changes/add-brief-workflow/specs/opsx-brief-skill/spec.md
• openspec/changes/add-brief-workflow/design.md

[kime541200]

Rebased onto the latest main — the merge conflict (in test/core/templates/skill-templates-parity.test.ts) is resolved, and the new /opsx:brief workflow now interpolates STORE_SELECTION_GUIDANCE so it satisfies the store-selection parity tests added upstream. Also addressed CodeRabbit's markdownlint notes on the doc code fences.

npm run build and the full test suite (1790 tests) pass locally. The PR shows MERGEABLE now; CI is waiting on the action_required approval. Could a maintainer approve the workflow run when convenient? Thanks!