From 785db8a08f8882a32dea7651c9d9790c661c7e2a Mon Sep 17 00:00:00 2001 From: Pim Snel Date: Thu, 26 Feb 2026 15:33:21 +0100 Subject: [PATCH] feat: add OpenSpec metric badges to README Add a new row of OpenSpec badges displaying project health metrics: - number_of_specs: specification count - open_changes: active change count - tasks_status: task completion ratio Includes GitHub Actions workflow using weAretechnative/openspec-badge-action to generate badges on push to main. Note: Project owner must enable GitHub Pages (gh-pages branch) after merge for badges to display correctly. Or a shorter version if you prefer: feat: add OpenSpec metric badges to README Add badges for specs count, open changes, and tasks status using openspec-badge-action. Requires GitHub Pages setup post-merge. --- .github/workflows/openspec-badge.yml | 18 ++++++ README.md | 6 ++ .../add-openspec-badges/.openspec.yaml | 2 + .../changes/add-openspec-badges/design.md | 58 +++++++++++++++++++ .../changes/add-openspec-badges/proposal.md | 37 ++++++++++++ .../specs/readme-badges/spec.md | 41 +++++++++++++ openspec/changes/add-openspec-badges/tasks.md | 29 ++++++++++ 7 files changed, 191 insertions(+) create mode 100644 .github/workflows/openspec-badge.yml create mode 100644 openspec/changes/add-openspec-badges/.openspec.yaml create mode 100644 openspec/changes/add-openspec-badges/design.md create mode 100644 openspec/changes/add-openspec-badges/proposal.md create mode 100644 openspec/changes/add-openspec-badges/specs/readme-badges/spec.md create mode 100644 openspec/changes/add-openspec-badges/tasks.md diff --git a/.github/workflows/openspec-badge.yml b/.github/workflows/openspec-badge.yml new file mode 100644 index 000000000..ec698bca5 --- /dev/null +++ b/.github/workflows/openspec-badge.yml @@ -0,0 +1,18 @@ +name: OpenSpec Badge + +on: + push: + branches: [main] + +jobs: + badge: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@v4 + - uses: weAretechnative/openspec-badge-action@main + with: + metric_types: number_of_specs,open_changes,tasks_status + badge_style: classic + show_label: true diff --git a/README.md b/README.md index b8af8ca15..729c09547 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,12 @@ Discord

+

+ Specs + Open Changes + Tasks Status +

+
The most loved spec framework. diff --git a/openspec/changes/add-openspec-badges/.openspec.yaml b/openspec/changes/add-openspec-badges/.openspec.yaml new file mode 100644 index 000000000..85ae75c1f --- /dev/null +++ b/openspec/changes/add-openspec-badges/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-26 diff --git a/openspec/changes/add-openspec-badges/design.md b/openspec/changes/add-openspec-badges/design.md new file mode 100644 index 000000000..292ca2ddd --- /dev/null +++ b/openspec/changes/add-openspec-badges/design.md @@ -0,0 +1,58 @@ +## Context + +The OpenSpec README currently displays standard project badges (CI status, npm version, license, Discord) in a centered paragraph block. We want to add OpenSpec-specific metric badges using the weAretechnative/openspec-badge-action GitHub Action. + +The action generates SVG badges and publishes them to the gh-pages branch. Badges are then referenced via raw.githubusercontent.com URLs. + +## Goals / Non-Goals + +**Goals:** +- Add three OpenSpec metric badges to README: number_of_specs, number_of_open_changes, number_of_open_tasks +- Configure GitHub Action workflow to generate badges on push to main +- Use classic style with labels enabled for visual consistency + +**Non-Goals:** +- Modifying existing badge styling or arrangement +- Adding all available badge types (number_of_requirements, tasks_status) +- Custom badge colors or branding + +## Decisions + +### 1. Badge Selection + +**Decision:** Use `number_of_specs`, `open_changes` (for open changes), and `tasks_status` (shows open tasks ratio) + +**Rationale:** These three metrics provide meaningful insight into project health: +- `number_of_specs` - shows specification coverage +- `open_changes` - shows active development work +- `tasks_status` - shows completion progress (displays as X/Y format) + +**Alternative considered:** Include `number_of_requirements` - decided against to keep the badge row concise. + +### 2. Badge Placement + +**Decision:** Add a new `

` block after the existing badges section (line 15), creating a distinct row for OpenSpec-specific badges. + +**Rationale:** Keeps OpenSpec metrics visually grouped and separate from standard project badges (CI, npm, license, Discord). + +**Alternative considered:** Inline with existing badges - would make the line too long and mix different badge categories. + +### 3. Workflow Trigger + +**Decision:** Trigger badge generation on push to main branch only. + +**Rationale:** Badges should reflect the current state of the main branch. Running on PRs would be wasteful since those badges wouldn't be used. + +### 4. Badge Style + +**Decision:** Use `classic` style with `show_label: true` + +**Rationale:** Classic style provides gradient appearance matching the shield.io badges used elsewhere. Labels provide context for what each metric represents. + +## Risks / Trade-offs + +**[gh-pages branch required]** → The action publishes to gh-pages branch. If the branch doesn't exist, the action will create it. This is expected behavior. + +**[Badge URLs depend on repository path]** → Badge image URLs are hardcoded to the repository path. If the repo is forked, badge URLs would point to the original repo. → This is acceptable for the main repository; forks can update URLs if needed. + +**[Action permissions]** → Workflow requires `contents: write` permission. → Standard for actions that commit to branches. diff --git a/openspec/changes/add-openspec-badges/proposal.md b/openspec/changes/add-openspec-badges/proposal.md new file mode 100644 index 000000000..c235cb532 --- /dev/null +++ b/openspec/changes/add-openspec-badges/proposal.md @@ -0,0 +1,37 @@ +## Why + +The README currently displays CI, npm, license, and Discord badges but lacks visibility into OpenSpec-specific project health metrics. Adding OpenSpec badges will showcase the framework's own capabilities and provide at-a-glance insight into the project's specification coverage and change activity. + +## What Changes + +- Add a new row of OpenSpec badges to the README header section +- Configure the openspec-badge-action GitHub Action to generate badges +- Display three metrics: number of specs, open changes, and open tasks +- Use classic style with labels for consistency and clarity + +## Capabilities + +### New Capabilities + +- `readme-badges`: Configuration and display of OpenSpec metric badges in project README + +### Modified Capabilities + +None - this change adds new content to the README without modifying existing OpenSpec behavior. + +## Impact + +- **README.md**: New badge row added after the existing badges section +- **.github/workflows/**: New workflow file for badge generation +- **gh-pages branch**: Will store generated SVG badge files (created automatically by the action) +- **Repository settings**: Requires `contents: write` permission for the workflow + +## Prerequisites for Project Owner + +Before the badges will display correctly, the project owner must complete these steps after merging: + +1. **Enable GitHub Pages**: Go to repository Settings → Pages → Set source to "Deploy from a branch" and select the `gh-pages` branch (root folder) +2. **Run the workflow**: The badge workflow must run at least once to generate the initial SVG files and create the gh-pages branch +3. **Verify permissions**: Ensure GitHub Actions has write access to the repository (Settings → Actions → General → Workflow permissions → "Read and write permissions") + +Until these steps are completed, the badge images in the README will show as broken/missing. diff --git a/openspec/changes/add-openspec-badges/specs/readme-badges/spec.md b/openspec/changes/add-openspec-badges/specs/readme-badges/spec.md new file mode 100644 index 000000000..43508332b --- /dev/null +++ b/openspec/changes/add-openspec-badges/specs/readme-badges/spec.md @@ -0,0 +1,41 @@ +## ADDED Requirements + +### Requirement: OpenSpec badges displayed in README + +The README SHALL display OpenSpec metric badges in a new row after the existing badges section, showing project health metrics generated by the openspec-badge-action. + +#### Scenario: Badges visible in README +- **WHEN** a user views the README.md file +- **THEN** a row of three OpenSpec badges SHALL be visible below the existing CI/npm/license/Discord badges + +#### Scenario: Badge row contains correct metrics +- **WHEN** the OpenSpec badge row is displayed +- **THEN** it SHALL contain badges for: number_of_specs, open_changes, and tasks_status metrics + +### Requirement: Badge generation workflow + +The repository SHALL include a GitHub Actions workflow that generates OpenSpec metric badges using the weAretechnative/openspec-badge-action. + +#### Scenario: Workflow triggers on main branch push +- **WHEN** code is pushed to the main branch +- **THEN** the badge generation workflow SHALL execute + +#### Scenario: Workflow generates specified metrics +- **WHEN** the badge workflow executes +- **THEN** it SHALL generate badges for: number_of_specs, open_changes, and tasks_status + +#### Scenario: Workflow uses classic style with labels +- **WHEN** the badge workflow executes +- **THEN** it SHALL use `badge_style: classic` and `show_label: true` configuration + +### Requirement: Badge images accessible via gh-pages + +The generated badge SVG files SHALL be published to the gh-pages branch and accessible via raw.githubusercontent.com URLs. + +#### Scenario: Badges published to gh-pages +- **WHEN** the badge workflow completes successfully +- **THEN** SVG badge files SHALL exist in the gh-pages branch under the badges/ directory + +#### Scenario: README references correct badge URLs +- **WHEN** the README displays OpenSpec badges +- **THEN** each badge image URL SHALL follow the pattern: `https://raw.githubusercontent.com/Fission-AI/OpenSpec/gh-pages/badges/.svg` diff --git a/openspec/changes/add-openspec-badges/tasks.md b/openspec/changes/add-openspec-badges/tasks.md new file mode 100644 index 000000000..6d2f2cc96 --- /dev/null +++ b/openspec/changes/add-openspec-badges/tasks.md @@ -0,0 +1,29 @@ +## 1. GitHub Action Workflow + +- [x] 1.1 Create `.github/workflows/openspec-badge.yml` workflow file +- [x] 1.2 Configure workflow to trigger on push to main branch +- [x] 1.3 Add checkout step with actions/checkout@v4 +- [x] 1.4 Configure weAretechnative/openspec-badge-action with metric_types, badge_style, and show_label +- [x] 1.5 Set contents: write permission for the workflow + +## 2. README Badge Integration + +- [x] 2.1 Add new centered paragraph block after existing badges (line 15) +- [x] 2.2 Add number_of_specs badge with raw.githubusercontent.com URL +- [x] 2.3 Add open_changes badge with raw.githubusercontent.com URL +- [x] 2.4 Add tasks_status badge with raw.githubusercontent.com URL + +## 3. Verification + +- [x] 3.1 Verify workflow YAML syntax is valid +- [x] 3.2 Verify README markdown renders correctly + +## 4. Post-Merge (Project Owner) + +> **Note:** These tasks must be completed by the project owner after the PR is merged. +> Badges will appear broken until these steps are done. + +- [ ] 4.1 Verify GitHub Actions workflow permissions allow write access (Settings → Actions → General → Workflow permissions) +- [ ] 4.2 Manually trigger or wait for the badge workflow to run on main branch +- [ ] 4.3 Enable GitHub Pages with gh-pages branch as source (Settings → Pages) +- [ ] 4.4 Verify badges display correctly in README