Codewalla OpenSpec — spec-driven development for AI coding assistants
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
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.
Requires Node.js 20.19.0 or higher.
Install OpenSpec globally:
npm install -g @codewalla_india/openspec@latestThen navigate to your project directory and initialize:
cd your-project
openspec initNote
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.
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
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
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.
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
Upgrade the package
npm install -g @codewalla_india/openspec@latestRefresh agent instructions
Run this inside each project to regenerate AI guidance and ensure the latest slash commands and MCP guidance are active:
openspec updateContext 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.
Telemetry
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.
MIT