OpenSpec Badge Action — Summary

OpenSpec Badge Action is a GitHub Actions composite action that generates SVG status badges reflecting four OpenSpec project health metrics: number of specs, number of requirements, open changes, and task completion status. The badges are deployed to the gh-pages branch for embedding in READMEs. The action installs the OpenSpec CLI, queries project metrics via openspec spec list --json and openspec list --changes --json, then generates SVGs via badgen (Node.js). It supports two visual styles (classic gradient, flat solid) and an optional label. No LLM interaction, no workflow orchestration, no prompts — it is a pure CI/CD reporting layer that makes OpenSpec project health visible in GitHub repos.

differs_from_seeds: No seed framework provides CI badge generation. This is a narrow infrastructure utility analogous to test coverage badges or build status indicators, but applied to OpenSpec workflow metrics. It differs from all seeds in that it contributes zero runtime agent behavior — its entire value is a static SVG artifact pushed to gh-pages.

OpenSpec Badge Action — Overview

Origin

Published by wearetechnative (TechNative, a cloud-native company) under Apache-2.0 license. Authored in JavaScript with a shell-based composite GitHub Actions workflow. First released in early 2026, tracking the OpenSpec CLI v1.x interface.

Philosophy

Make OpenSpec project health as immediately visible as test coverage badges or CI build status. The README implicitly frames this as "project health indicators at a glance" — the same social proof mechanism as shields.io badges but for spec-driven development metrics.

Manifesto-style statements (from README)

• "A GitHub Action that generates an SVG badge showing OpenSpec metrics for your repository."
• "The badge displays key project health indicators at a glance."
• "This project uses OpenSpec for structured change management."

Target user

Teams maintaining OpenSpec projects on GitHub who want README badges showing their spec-driven development progress. Primary audience is project maintainers and open-source projects wanting to display workflow health publicly.

Metric types supported

OpenSpec Badge Action — Architecture

Distribution

• GitHub Actions composite action (no npm package)
• Referenced via uses: weAretechnative/openspec-badge-action@main

Install method

- uses: actions/checkout@v4
- uses: weAretechnative/openspec-badge-action@main
  with:
    metric_types: number_of_specs,number_of_requirements,tasks_status,open_changes
    badge_style: flat

Tech stack

• Action type: Composite (shell-based steps, no Docker)
• Badge generation: badgen npm package (installed ephemerally in $RUNNER_TEMP)
• Metric collection: OpenSpec CLI (@fission-ai/openspec) + Node.js JSON parsing
• Deployment: git push to gh-pages branch with retry logic (up to 3 attempts)

Directory structure

openspec-badge-action/
├── action.yml          # Composite action definition
├── scripts/
│   └── badge-generator.js  # SVG generation script
├── tests/
├── openspec/           # Uses itself as an OpenSpec project
├── examples/badges/    # Example SVG badge outputs
└── README.md

Required runtime

• GitHub Actions runner (ubuntu-latest)
• Node.js (on runner)
• npm (on runner)
• OpenSpec CLI (installed by action itself: npm install -g @fission-ai/openspec)
• contents: write permission on the repository

Dependencies

• @fission-ai/openspec (installed at action runtime)
• badgen (installed ephemerally in $RUNNER_TEMP/node_modules)

Output location

gh-pages branch → badges/<metric>.svg files

Badge reference syntax

![specs](https://raw.githubusercontent.com/<owner>/<repo>/gh-pages/badges/number_of_specs.svg)

OpenSpec Badge Action — Components

action.yml (composite action steps)

scripts/badge-generator.js

• Node.js script that takes CLI flags: --metric, --spec-count, --req-count, --open-changes, --completed-tasks, --total-tasks, --style, --show-label, --output
• Uses badgen library to produce SVG output

Inputs (action.yml)

No skills, hooks, commands, agents, or MCP servers

Purely a GitHub Actions composite action — no Claude Code or AI-facing primitives.

OpenSpec Badge Action — Uniqueness & Positioning

differs_from_seeds

No seed framework provides CI badge generation for OpenSpec metrics. This is a narrow infrastructure utility without parallel in any of the 11 seeds. Unlike all seed frameworks that add agent behavior, this action adds only passive project health signaling — a downstream artifact of the OpenSpec workflow, not a participant in it.

Positioning

• Category: OpenSpec ecosystem — CI/CD reporting utility
• User: Project maintainers who want to display OpenSpec health metrics in their GitHub README
• Integration: Added to a GitHub Actions workflow alongside existing CI
• Value: Makes spec-driven development progress visible to contributors and reviewers through familiar badge conventions

Observable failure modes

1. OpenSpec CLI version drift: The action installs @fission-ai/openspec@latest — if the CLI interface changes, metric collection commands may break
2. gh-pages branch conflicts: The 3× retry loop handles most conflicts but concurrent runs could still fail
3. contents: write permission required: Projects with strict branch protection or read-only tokens cannot use this action
4. JSON parsing brittleness: Metric collection uses node -p inline JSON evaluation — fragile if CLI output format changes

Cross-references

• Depends on: OpenSpec CLI (@fission-ai/openspec)
• Spek (this batch) also generates badges (scripts/generate-badges.ts) as part of its static export — similar output, different delivery mechanism