[!TIP] Codewalla workflow: Propose from a Jira ticket or plain description, revise with /opsx:modify, then apply.

Run /opsx:propose CW-1234 add dark mode or /opsx:propose "your idea" to get started. → Jira integration · MCP setup

See it in action

You: /opsx:explore
AI:  What would you like to explore?
You: I want dark mode but I'm not sure how to do it cleanly.
AI:  Let me look at your styling setup...
     Cleanest path here: CSS variables + a small theme context,
     with system-preference detection. No new dependencies. Scope it?
You: Yes, let's do it.

You: /opsx:propose CW-1234 add-dark-mode
AI:  Found CW-1234: 'Add dark mode'. Creating change from Jira ticket...
     ✓ proposal.md  (Impact: Jira: CW-1234)
     ✓ specs/ui/    (requirements from Jira ACs)
     ✓ design.md    — technical approach
     ✓ plan.md      — file-level code map
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

You: /opsx:modify add-dark-mode design use CSS variables instead of hardcoded colors
AI:  Updated design.md → propagated to plan.md and tasks.md
     Run /opsx:apply when ready.

You: /opsx:apply
AI:  Jira context: CW-1234 — all ACs covered ✓
     Comprehension check — 7 questions on proposal, design, specs, plan, and tasks...
     ✓ 86% — ready to implement.
     Implementing tasks...
     ✓ 1.1 Add theme context provider
     ✓ 1.2 Create toggle component
     ✓ 2.1 Add CSS variables
     ✓ 2.2 Wire up localStorage
     All tasks complete!

You: /opsx:archive
AI:  Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
     Specs updated. Ready for the next feature.

Quick Start

Requires Node.js 20.19.0 or higher.

Install OpenSpec globally:

npm install -g @codewalla_india/openspec@latest

Then navigate to your project directory and initialize:

cd your-project
openspec init

[!NOTE] Codewalla identity: openspec init prompts for your Codewalla email or username. All commands require telemetry identity. CI runners should pre-provision ~/.config/openspec/telemetry-identity.json or set OPENSPEC_TELEMETRY_USER.

Now talk to your AI:

• Not sure what you want to build yet? Start with /opsx:explore, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before anything is written. (Explore guide)
• Already know what you want? Go straight to /opsx:propose <what-you-want-to-build> or /opsx:propose CW-1234 <summary> to import from Jira.
• Need to revise the plan before coding? Run /opsx:modify — pre-apply only; propagates changes to downstream artifacts. (Editing a change)
• Ready to implement? Run /opsx:apply — a short comprehension quiz checks you understand the proposal, design, specs, plan, and tasks before any code is written.

The default core profile includes /opsx:explore, /opsx:propose, /opsx:modify, /opsx:apply, /opsx:sync, and /opsx:archive. If you want the expanded workflow (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard), select it with openspec config profile and apply with openspec update.

[!NOTE] Not sure if your tool is supported? View the full list – we support 25+ tools and growing.

Also works with pnpm, yarn, bun, and nix. See installation options.

Codewalla workflow & MCPs

OpenSpec workflows integrate with MCP servers in your AI tool. MCPs are optional — workflows degrade gracefully when a server is unavailable.

| MCP | Workflow | Behavior | |-----|----------|----------| | Atlassian | /opsx:propose, /opsx:apply | Import Jira tickets; enrich and cross-check ACs vs tasks; skips if unavailable | | Context7 | /opsx:apply | Fetch current library docs when tasks reference packages; max 3 calls per session | | Browser | /opsx:verify (expanded profile) | Screenshots, a11y snapshot, console errors; not run during apply |

→ MCP Setup guide — enable servers in Cursor or your AI tool → Jira integration — naming conventions and ticket flows

Docs

Start here: the Documentation Home maps everything. New to OpenSpec? Read Getting Started, then How Commands Work (where you actually type /opsx:propose).

→ Getting Started: first steps → Explore First: think it through with /opsx:explore before you commit → How Commands Work: where slash commands run vs the CLI → Core Concepts at a Glance: the whole mental model, one page → Examples & Recipes: real changes, start to finish → Workflows: combos and patterns → MCP Setup: Atlassian, Context7, and browser MCPs → Existing Projects: adopt OpenSpec on a brownfield codebase → Editing a Change: update artifacts, go back, reconcile manual edits → Commands: slash commands & skills → CLI: terminal reference → Stores: plan in a separate repo, shared across your team (beta) → Supported Tools: tool integrations & install paths → Concepts: how it all fits → Multi-Language: multi-language support → Customization: make it yours → FAQ · Troubleshooting · Glossary: quick help

Community schemas

Third-party schema bundles distributed via standalone repositories — these provide opinionated workflows that integrate OpenSpec with other tools, similar to how github/spec-kit's community extension catalog handles tool integrations.

→ Browse the catalog in the customization docs.

Why OpenSpec?

AI coding assistants are powerful but unpredictable when requirements live only in chat history. OpenSpec adds a lightweight spec layer so you agree on what to build before any code is written.

• Agree before you build — human and AI align on specs before code gets written
• Stay organized — each change gets its own folder with proposal, specs, design, plan, and tasks
• Work fluidly — update any artifact anytime with /opsx:modify; no rigid phase gates
• Jira-native workflow — propose from ticket keys, enrich from Jira during apply, traceability in proposal Impact
• MCP-powered — Atlassian, Context7, and browser MCPs built into generated skills
• Use your tools — works with 20+ AI assistants via slash commands

Updating OpenSpec

Upgrade the package

npm install -g @codewalla_india/openspec@latest

Refresh agent instructions

Run this inside each project to regenerate AI guidance and ensure the latest slash commands and MCP guidance are active:

openspec update

Usage Notes

Context hygiene: OpenSpec benefits from a clean context window. Clear your context before starting implementation and maintain good context hygiene throughout your session.

Modify before apply: /opsx:modify revises planning artifacts and propagates changes downstream. It is pre-apply only — once tasks are checked off in /opsx:apply, use manual edits or start a new change.

Comprehension check: /opsx:apply runs a short quiz (enabled by default) on proposal, design, specs, plan, and pending tasks before implementation. Questions test holistic understanding of the change, not task numbers or checklist trivia; plan receives the majority of questions when present. You need ≥ 80% to proceed. Disable with comprehension.enabled: false in openspec/config.yaml. See Workflows.

Other

Codewalla OpenSpec collects mandatory usage analytics tied to your email or username. Identity is collected during interactive openspec init or openspec update and stored at ~/.config/openspec/telemetry-identity.json (never committed). All other commands require identity. CI runners should pre-provision that file or set OPENSPEC_TELEMETRY_USER.

Events include command names, workflow metrics, change names, workflow input text (via --workflow-input on new change), and modify requests (artifact_modify_requested with modify input) — not file paths or artifact/spec body content.

License

MIT