Osx Concepts

OpenSpec-extended for AI Agents

Framework reference for OpenSpec-extended. Covers the framework (repo layout, artifacts, resource taxonomy, glossary) and decision guidance.

---

TL;DR — mental model in 30 seconds

What OpenSpec-extended is: a spec-driven development framework where you agree on WHAT to build before writing code. All artifacts live in the repository so humans and AI can collaborate.

Skill split (read both):

1. This skill (osx-concepts) — framework, repo layout, 4 artifacts, delta specs, resource taxonomy, decision guidance, glossary
2. osx-workflow — 4 tool layers (openspec, openspec-extended, osx CLI, osx lib) and the 7-phase autonomous loop driven by openspec-extended orchestrate

Skip OpenSpec when: 1-2 line fix, emergency hotfix, pure debugging.

---

§1 Philosophy

Traditional workflows pretend work is linear (plan → implement → done). Real work isn't: you implement, realize the design is wrong, update specs, continue. OpenSpec uses fluid actions, not rigid phases — skills are things you can do anytime.

| Principle | Meaning | |-----------|---------| | Fluid not rigid | No phase gates — work happens iteratively | | Iterative not waterfall | Learn as you build; refine as you go | | Easy not complex | Minimal ceremony; get started in seconds | | Brownfield-first | Works with existing code; most work modifies systems |

---

§2 The Framework

2.1 Repository layout

openspec/
├── specs/                    # Source of truth (current behavior)
│   └── /
│       └── /
│           └── spec.md
└── changes/                  # In-progress proposals
    ├── /        # Active change
    │   ├── proposal.md
    │   ├── design.md
    │   ├── tasks.md
    │   └── specs/            # Delta specs (ADDED/MODIFIED/REMOVED)
    └── archive/              # Completed history (date-prefixed)
        └── YYYY-MM-DD-/

2.2 Artifacts

| Artifact | Purpose | |----------|---------| | proposal.md | Why & what — intent, scope, capabilities, impact | | specs/ (delta) | Requirements as ## ADDED / ## MODIFIED / ## REMOVED / ## RENAMED sections | | design.md | How — context, decisions, tradeoffs | | tasks.md | Checklist — - [ ] (todo) / - [x] (done) |

2.3 Delta operations

| Section | On archive | |---------|-----------| | ## ADDED Requirements | Append to main spec | | ## MODIFIED Requirements | Replace existing requirement | | ## REMOVED Requirements | Delete from main spec | | ## RENAMED Requirements | Rename in main spec |

2.4 Artifact state machine

| State | Symbol | Meaning | |-------|--------|---------| | BLOCKED | ○ | Dependencies not met | | READY | ◆ | Can create now | | DONE | ✓ | File exists |

Query: openspec status --change --json returns the full state per artifact (see references/cli-reference.md for the verified v1.4.1 JSON shape).

2.5 Resource taxonomy

Core skills (osc-* — 11, renamed from upstream openspec-* by installer)

| Skill | Purpose | |-------|---------| | osc-propose | Create change + all artifacts in one step | | osc-explore | Think through ideas without committing | | osc-new-change | Create change folder | | osc-continue-change | Create next artifact incrementally | | osc-ff-change | Create all artifacts at once | | osc-apply-change | Implement tasks from tasks.md | | osc-verify-change | Verify implementation matches artifacts | | osc-sync-specs | Merge delta specs into main specs | | osc-archive-change | Complete a single change | | osc-bulk-archive-change | Complete multiple changes with conflict detection | | osc-onboard | Guided tutorial for first-time users |

Extended skills (osx-* — 8, local enhancements)

| Skill | Purpose | |-------|---------| | osx-concepts | This skill — framework, repo layout, artifacts, decision guidance | | osx-workflow | 4 tool layers, 7-phase autonomous workflow (paired with this skill) | | osx-review-artifacts | Pre-implementation quality check | | osx-modify-artifacts | Edit artifacts with dependency tracking | | osx-review-test-compliance | Spec-to-test alignment analysis | | osx-maintain-ai-docs | Update AGENTS.md and CLAUDE.md | | osx-generate-changelog | Generate CHANGELOG.md from archive | | osx-commit | Create commits matching project style |

> After this skill: 8 extended skills total. The taxonomy above lists all of them.

Agents (3 — orchestrator-dispatched)

| Agent | Phases | Permissions | Temp | |-------|--------|-------------|------| | osx-analyzer | PHASE0, PHASE2, PHASE5 | read-only (edit: deny) | 0.1 | | osx-builder | PHASE1 | full read/write | 0.4 | | osx-maintainer | PHASE3, PHASE4, PHASE6 | full read/write | 0.3 |

Commands (12)

| Type | Command | Dispatched by | |------|---------|---------------| | Phase | osx-phase0 … osx-phase6 | Orchestrator only | | Workflow | osx-modify, osx-review, osx-verify-tests, osx-changelog, osx-maintain-docs | User/agent ad-hoc |

---

§3 Decision guidance

Use OpenSpec when: multi-step (3+ tasks), refactors, architectural changes, unclear requirements, work spanning multiple sessions.

Skip OpenSpec when: single obvious fixes (1-2 lines), emergency hotfixes, pure debugging.

Update vs new change:

• Update existing if: same intent, refined execution; >50% scope overlap; original can't finish without these changes
• Start new if: intent fundamentally changed; <50% overlap; original is done standalone

Continue vs fast-forward:

• osc-ff-change (fast-forward) when requirements are clear, ready to build
• osc-continue-change (incremental) when exploring or wanting step-by-step control

For detailed guidance (including parallel changes, bulk archive, naming): references/change-guidance.md.

---

§4 Glossary

| Term | Definition | |------|------------| | Artifact | A document within a change: proposal.md, specs/, design.md, tasks.md | | Archive | Process of completing a change and merging its deltas into main specs | | Change | A proposed modification, packaged as a folder with artifacts | | Delta spec | Spec describing changes (ADDED/MODIFIED/REMOVED/RENAMED) relative to current specs | | Domain | A logical grouping for specs (e.g., auth/, payments/) | | Requirement | A specific behavior the system must have (SHALL/MUST/SHOULD) | | Scenario | A concrete example in GIVEN/WHEN/THEN format | | Source of truth | The openspec/specs/ directory with current behavior |

---

§5 References

| File | Load when | |------|-----------| | ../osx-workflow/SKILL.md | Running the 7-phase autonomous workflow (paired skill) | | ../osx-workflow/references/autonomous-workflow.md | Per-phase protocol, transition logic, error recovery | | references/artifact-formats.md | Creating or modifying any artifact | | references/cli-reference.md | Need JSON output schema for any CLI command | | references/change-guidance.md | Deciding update vs new, parallel work, bulk archive | | references/anti-patterns.md | Made a mistake; need full catalog of what to avoid |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: amauryconstant
• Source: amauryconstant/openspec-extended
• License: MIT

Install and usage instructions live in the source repository linked above.