OpenSpec.sh

openspec-sh · biancalana/OpenSpec.sh · ★ 3 · last commit 2026-01-19

POSIX bash reimplementation of OpenSpec for environments without Node.js — dependency-free spec-driven workflow scaffold.

Best whenSpec-driven development tooling should be distributable as a single shell script with zero external dependencies.

Skip ifRequiring npm/Node.js for basic spec file management

vs seeds

openspec/changes/, proposal.md, tasks.md). This is a POSIX bash reimplementat…

Primitive shape

No installable primitives

Summary

OpenSpec.sh — Summary

OpenSpec.sh is a POSIX bash reimplementation of the OpenSpec CLI, designed for environments without Node.js. It provides core spec-driven workflow functionality (init, list, validate, archive) using only standard POSIX utilities (find, mkdir, grep, sed, cat, echo). The tool supports two AI coding tools (Crush and GitHub Copilot) with agent integration files generated during openspec init --tools crush,github-copilot. With 3 stars and version 0.16.0, it is a lightweight portability layer — not a feature-equivalent replacement for the npm OpenSpec CLI, but a functional starting point for teams on restricted environments (embedded systems, minimal Linux, restricted CI).

Compared to seeds: closest to openspec as a direct implementation of the same concept in a different runtime. The architectural delta is maximally reduced: no schema plugin system, no AI tool skill generation for the 29+ tools OpenSpec supports, no delta spec tracking — only file structure creation, basic validation, and manual spec archiving.

Overview

OpenSpec.sh — Overview

Origin

Created by GitHub user biancalana. Published January 2026. No license file found. Shell script at version 0.16.0.

Philosophy

From README:

"This is a minimal POSIX bash rewrite of the OpenSpec CLI tool, designed to run in environments without Node.js. It provides the core functionality for spec-driven development while maintaining compatibility across Unix-like systems."

The project explicitly positions itself as a bridge:

"For teams that need the full OpenSpec experience: 1. Start with POSIX version for basic spec management. 2. Install Node.js when more features are needed. 3. Migrate to full version with existing openspec/ directory."

Explicit Limitations (vs. npm OpenSpec)

No interactive prompts or wizards
No syntax highlighting or spinners
Basic validation (no complex schema checking)
No AI tool integration or slash command generation (except Crush + GitHub Copilot)
Manual spec merging (no delta tracking)
No concurrent processing

POSIX Compliance

Uses /bin/sh — portable to dash, ash, busybox sh
No bash-specific extensions
Standard utilities only: find, mkdir, grep, sed, cat, echo
Cross-platform: Linux, macOS, BSD, WSL

AI Tool Integration

Despite the "no AI tool integration" disclaimer in limitations, the script does generate agent integration files for:

Crush: agents/tools/crush.sh — generates Crush-specific AGENTS.md
GitHub Copilot: agents/tools/github-copilot.sh — generates Copilot-specific instructions

Architecture

OpenSpec.sh — Architecture

Distribution

Type: bash-script-bundle
Install: sudo cp openspec.sh /usr/local/bin/openspec && sudo chmod +x /usr/local/bin/openspec
Or run directly: ./openspec.sh init

Runtime Requirements

POSIX shell (sh, bash, dash, ash, busybox sh)
Standard POSIX utilities: find, mkdir, grep, sed, cat, echo, tput (optional, for colors)
No Node.js required
No package manager required

Repository Structure

OpenSpec.sh/
├── README.md
├── openspec.sh       # Main script (~400 lines)
└── agents/
    ├── registry.sh   # Tool registry (crush, github-copilot)
    ├── detection.sh  # AI tool detection logic
    ├── templates.sh  # AGENTS.md template generator
    └── tools/
        ├── crush.sh           # Crush integration
        └── github-copilot.sh  # GitHub Copilot integration

Generated Directory Structure

openspec/
├── specs/          # Canonical specifications (source of truth)
├── changes/        # Change proposals
│   ├── [change-name]/
│   │   ├── proposal.md
│   │   ├── tasks.md
│   │   └── specs/  # Spec updates
│   └── archive/    # Archived changes
└── project.md      # Project context

Install Procedure

# Copy to path
sudo cp openspec.sh /usr/local/bin/openspec
sudo chmod +x /usr/local/bin/openspec

# Or validate syntax
shellcheck openspec.sh

Supported Platforms

Linux, macOS, BSD, WSL2. Not tested on Windows native.

Components

OpenSpec.sh — Components

CLI Binary: `openspec` (or `openspec.sh`)

Command	Description
`openspec init [path]`	Initialize OpenSpec directory structure + project.md + AGENTS.md
`openspec list [--specs]`	List changes or specifications
`openspec validate <name>`	Validate change or spec structure
`openspec archive <name>`	Archive completed change + merge specs

The --tools flag to init accepts: none, all, crush, github-copilot, or comma-separated.

Agent Integration Modules

Module	Purpose
`agents/registry.sh`	Tool registry (`SUPPORTED_TOOLS="crush github-copilot"`)
`agents/detection.sh`	Detect which AI tools are configured in the project
`agents/templates.sh`	Generate AGENTS.md content
`agents/tools/crush.sh`	Configure Crush-specific integration
`agents/tools/github-copilot.sh`	Configure GitHub Copilot-specific integration

Templates (inline in script)

The main script generates:

openspec/project.md — project context template
openspec/changes/TEMPLATE.md — change proposal template
AGENTS.md — AI tool-specific instructions (if tools configured)

Commands/Skills/Hooks

None for Claude Code. The tool generates AGENTS.md for the configured AI tools.

Scripts

The main openspec.sh is itself the script. The agents/ submodules are sourced (not executed) by the main script.

Prompts

OpenSpec.sh — Prompts

Excerpt 1: Generated project.md template

From openspec.sh (inline here-doc):

cat > "$target_path/$OPENSPEC_DIR/project.md" << 'EOF'
# Project Context

## Project Overview
<!-- Add project description and goals -->

## Tech Stack
<!-- List your technologies and frameworks -->

## Conventions
<!-- Document your coding standards and patterns -->

## Architecture
<!-- Describe system architecture and key components -->
EOF

Technique: Passive context injection. The project.md file is read by AI tools as background context. The comment-based structure guides humans on what to fill in.

Excerpt 2: Generated change template

cat > "$target_path/$OPENSPEC_DIR/changes/TEMPLATE.md" << 'EOF'
# Change: [feature-name]

## Proposal
<!-- What and why -->

## Tasks
- [ ] Task 1: Description
- [ ] Task 2: Description

## Design Notes
<!-- Technical decisions (optional) -->
EOF

Technique: Minimal change format. Unlike full OpenSpec which generates separate proposal.md, specs/, design.md, tasks.md — this packs everything into a single file, appropriate for the minimal POSIX implementation.

Note on Prompt Depth

OpenSpec.sh is a scaffold/lifecycle manager, not a prompt framework. Its "prompts" are template stubs that humans fill in. The substantive agent instructions live in the generated AGENTS.md (tool-specific, contents not publicly visible in the repo's agent tool scripts).

Uniqueness

OpenSpec.sh — Uniqueness

differs_from_seeds

Closest seed: openspec (same directory structure, same concept). This is a POSIX bash reimplementation of OpenSpec — same openspec/specs/, openspec/changes/, proposal.md, tasks.md conventions, but implemented as a dependency-free shell script. The key architectural delta from the npm OpenSpec: no schema plugin system, no AI tool skill/command file generation for 29+ tools, no delta spec merge at archive time, no .openspec.yaml per-change state tracking. The functional surface is approximately 15% of the npm version. Closest seed after openspec would be agent-os which also ships a bash bundle for creating scaffolding files, but agent-os targets Claude Code conventions (CLAUDE.md, standards/) while this targets the OpenSpec directory convention.

Positioning

The "air-gap install" version of OpenSpec. Useful for:

CI environments without npm
Embedded Linux systems
Minimal Docker images
Restricted enterprise environments with no internet access for npm install

Observable Failure Modes

No schema validation: openspec validate checks file existence, not content structure — a malformed spec.md passes validation
No delta merge: archive does a flat file copy, not the ADDED/MODIFIED/REMOVED delta processing that enables brownfield spec evolution
Only 2 AI tools supported: Crush and GitHub Copilot — teams using Claude Code, Cursor, or other tools get no AGENTS.md
No cross-change context: no mechanism to see which capabilities have been specified across archived changes
Version drift: as the npm OpenSpec CLI evolves, OpenSpec.sh will fall further behind in features and directory conventions

Workflow

OpenSpec.sh — Workflow

Initialization Phase

openspec init my-project

Creates:

my-project/openspec/specs/
my-project/openspec/changes/
my-project/openspec/changes/archive/
my-project/openspec/project.md
my-project/openspec/changes/TEMPLATE.md
my-project/AGENTS.md (if tools configured)

Change Workflow (Manual)

Step	Action	Gate
1. Create change	`mkdir -p openspec/changes/add-feature`	—
2. Write proposal	Edit `openspec/changes/add-feature/proposal.md`	—
3. Write tasks	Edit `openspec/changes/add-feature/tasks.md`	—
4. Validate	`openspec validate add-feature`	Structure check
5. Implement	(manual coding)	—
6. Archive	`openspec archive add-feature`	—

Validation

openspec validate add-feature

Checks:

Change directory exists
proposal.md exists
tasks.md exists (if present)
Spec files have correct structure

Approval Gates

None automated. All review is manual — the script provides structure but no AI-integration gates.

Memory Context

OpenSpec.sh — Memory & Context

State Storage

File-based, minimal:

openspec/
├── project.md           # Project context (human-edited)
├── specs/               # Canonical specs
│   └── <capability>/spec.md
├── changes/
│   └── <change-name>/
│       ├── proposal.md  (or combined TEMPLATE.md)
│       ├── tasks.md
│       └── specs/
└── changes/archive/     # Archived changes

Persistence

Scope: project
Cross-session: Yes — files persist
No compaction, no delta tracking

Memory Type

File-based. The AI tool reads project.md and AGENTS.md for context. No database, no vector store.

Limitations

No delta tracking: archive command does basic file copy, not OpenSpec's delta merge
No cross-session handoff: no artifacts that encode which artifact phase is next
No state files: no .openspec.yaml per-change state tracking (unlike npm OpenSpec)

AGENTS.md

The generated AGENTS.md (Crush or GitHub Copilot-specific) contains AI tool instructions for working within the OpenSpec directory structure. Content is tool-specific and generated by agents/tools/<tool>.sh.

Orchestration

OpenSpec.sh — Orchestration

Multi-Agent

No.

Orchestration Pattern

None. The script is a file scaffold manager — it creates directories and template files. All workflow execution is manual.

Isolation Mechanism

None.

Multi-Model

No.

Execution Mode

One-shot CLI invocations. No continuous loop, no daemon, no hooks.

Prompt Chaining

No. The script does not chain prompts or pass outputs between stages.

Crash Recovery

N/A — each CLI invocation is independent. No state to recover.

Notes

OpenSpec.sh is fundamentally a workflow scaffold, not a workflow orchestrator. It creates the file structure that a human (or AI tool reading AGENTS.md) then operates within manually. Compared to the npm OpenSpec CLI which has the /opsx:* command surface driving artifact generation, OpenSpec.sh relies entirely on human judgment to advance through phases.

Ui Cli Surface

OpenSpec.sh — UI & CLI Surface

Dedicated CLI Binary

Yes (bash script, not a compiled binary).

Binary name: openspec (after install to PATH)
Script file: openspec.sh

Subcommands

Command	Description
`openspec init [path]`	Initialize OpenSpec structure
`openspec list [--specs]`	List changes or specs
`openspec validate <name>`	Validate change structure
`openspec archive <name>`	Archive and merge specs

No Local UI

No web dashboard, no TUI, no IDE extension.

Color Support

Basic ANSI colors via tput if the terminal supports it. Falls back to plain text.

Validation Output

openspec validate add-feature
# Outputs: ✓ or ✗ for each checked property

Install as CLI

sudo cp openspec.sh /usr/local/bin/openspec
sudo chmod +x /usr/local/bin/openspec

Or call directly without installing:

./openspec.sh init

Portability

The entire tool is one ~400-line bash file + 4 sourced module files. No external dependencies. Can be embedded in a Docker image or CI container without npm/node.

Related frameworks

same archetype · same primary tool · same memory type

BMAD-METHOD ★ 48k

A4 Markdown scaffold

Provides a full agile delivery lifecycle with named expert-persona AI collaborators that elicit the human's best thinking rather…

Agent OS ★ 4.6k

A4 Markdown scaffold

Extracts implicit codebase conventions into token-efficient markdown standards files and injects them selectively into AI agent…

Claude Conductor ★ 367

A4 Markdown scaffold

Gives Claude Code a persistent, cross-linked, auto-analyzed documentation system so it retains codebase context across sessions.

Spec-Driver (Greenfield Spec-Driven Development) ★ 25

A4 Markdown scaffold

Prevents spec rot in AI-assisted development by making implementation changes flow back into evergreen, authoritative specs via…

Anthropic Knowledge Work Plugins ★ 16k

A4 Markdown scaffold

Role-specialized plugin bundles with live MCP connectors that turn Claude into a domain expert for enterprise knowledge workers.

Codex Integration for Claude Code (skill-codex) ★ 1.3k

A4 Markdown scaffold

Single Claude Code skill that handles Codex CLI invocation correctly (stdin blocking, thinking token suppression, session resume)…

Distribution

Type: bash-script-bundle
Install: one-liner
Version: 0.16.0

Surfaces

CLI binary: openspec
CLI subcmds: 4
Local UI: No

Components

Commands: 0
Skills: 0
Subagents: 0
Hooks: 0
MCP servers: 0
MCP tools: 0
Scripts: 5
Templates: 3

Workflow

Phases: 6
Approval gates: 0
Spec format: markdown
Spec storage: per-feature-folder
Delta or full: whole-file

Orchestration

Multi-agent: No
Pattern: none
Max concurrent: 1
Isolation: none
Consensus: none
Prompt chaining: No

Multi-model

Multi-model: No
BYOK: Yes
Modal: text

Execution

Mode: one-shot
Crash recovery: No
Compaction: No
Session handoff: No
Streaming: No

Memory

Type: file-based
Persistence: project
Search: none
State files: 4 files

Quality

TDD: No
TDD mechanism: none
Self-review: none

Git / Observability

Auto commit: No
Auto PR: No
Auto merge: No
Worktree/feat: No
Audit log: No
Audit format: none
Replay: No

Tools

Targets: 2
Portability: medium

Signals

Stars: 3
Last commit: 2026-01-19
Contributors: 1
Maintainer: dormant
Quality score: 0/10

Summary

OpenSpec.sh — Summary

Overview

OpenSpec.sh — Overview

Origin

Philosophy

Explicit Limitations (vs. npm OpenSpec)

POSIX Compliance

AI Tool Integration

Architecture

OpenSpec.sh — Architecture

Distribution

Runtime Requirements

Repository Structure

Generated Directory Structure

Install Procedure

Supported Platforms

Components

OpenSpec.sh — Components

CLI Binary: openspec (or openspec.sh)

Agent Integration Modules

Templates (inline in script)

Commands/Skills/Hooks

Scripts

Prompts

OpenSpec.sh — Prompts

Excerpt 1: Generated project.md template

Excerpt 2: Generated change template

Note on Prompt Depth

Uniqueness

OpenSpec.sh — Uniqueness

differs_from_seeds

Positioning

Observable Failure Modes

Workflow

OpenSpec.sh — Workflow

Initialization Phase

Change Workflow (Manual)

Validation

Archive

Approval Gates

Memory Context

OpenSpec.sh — Memory & Context

State Storage

Persistence

Memory Type

Limitations

AGENTS.md

Orchestration

OpenSpec.sh — Orchestration

Multi-Agent

Orchestration Pattern

Isolation Mechanism

Multi-Model

Execution Mode

Prompt Chaining

Crash Recovery

Notes

Ui Cli Surface

OpenSpec.sh — UI & CLI Surface

Dedicated CLI Binary

Subcommands

No Local UI

Color Support

Validation Output

Install as CLI

Portability

Related frameworks

CLI Binary: `openspec` (or `openspec.sh`)