How we integrated OpenSpec into a pnpm monorepo with custom schema

[CS-Tao]

Hi! Here's how we're using OpenSpec in our frontend monorepo (pnpm workspaces with React + TypeScript).

Setup

1. Installed OpenSpec as a project dev dependency - so team members don't need to install it globally, just run pnpm openspec
2. Renamed /opsx:* commands to /sdd:* - "Spec-Driven Development" is easier for our team to remember
3. Created a custom PRD-driven schema - tailored to our development workflow

How We Update OpenSpec Commands

We built a custom CLI command that:

1. Ensures the global @fission-ai/openspec CLI is installed and up-to-date
2. Runs openspec init in a temp directory to fetch the latest upstream commands/skills
3. Uses an AI agent to transform and sync the upstream content with customizations:
   • Namespace conversion (openspec-* → sdd-*, /opsx:* → /sdd:*)
   • CLI prefix replacement (openspec → pnpm openspec)
   • Changes/specs naming constraints
   • Translate content to Chinese so the AI tends to communicate with us in Chinese

This keeps our commands in sync with upstream while maintaining our local setup.

Our Custom Schema: anchor-prd-driven

We defined a 5-artifact workflow that matches how our team works with Product Managers and Designers:

# summarized from openspec/schemas/anchor-prd-driven/schema.yaml
name: anchor-prd-driven
version: 1
description: PRD-driven OpenSpec workflow - proposal → specs → drd → design → tasks

artifacts:
  - id: proposal
    generates: proposal.md
    description: Initial proposal - supports loading Lark docs via MCP tool
    requires: []

  - id: specs
    generates: 'specs/**/*.md'
    description: Detailed specifications with ADDED/MODIFIED/REMOVED requirements
    requires: [proposal]

  - id: drd
    generates: 'drd/*.md'
    description: Design Review Documents - asks user for Figma links and parses via MCP tool
    requires: [specs]

  - id: design
    generates: design.md
    description: Technical design following project conventions and coding standards
    requires: [specs, drd]

  - id: tasks
    generates: tasks.md
    description: Implementation checklist with mandatory steps + sdd-code-reviewer subagent for final review
    requires: [design]

apply:
  requires: [tasks]
  tracks: tasks.md

Questions We'd Love to Discuss

1. Post-archive modifications - After a change is archived, what's the recommended workflow if we need to update both specs and code? Should we create a new change referencing the old one?

2. Partial team adoption - Some team members use SDD workflow, others don't. How do we ensure specs stay in sync with code when changes are made outside the OpenSpec workflow?

3. Anything else? - Happy to answer questions and open to suggestions!

[JayceZhang9602]

Great discussion on integrating OpenSpec into your pnpm monorepo! I have a question about how you maintain specs within the monorepo structure:

Do you keep specs in a flat, single-level directory structure, or do you support nested/tree-like organization? For example, if you have multiple packages with different domains, do you:

• Keep all specs in a single flat specs directory?
• • Or organize specs hierarchically (e.g., specs/package-a/, specs/package-b/, etc.)?
    This would be really helpful to understand for teams planning similar setups. Thanks!

[CS-Tao]

We noticed that OpenSpec doesn't currently support organizing specs in a hierarchical/nested directory structure (e.g., specs/package-a/, specs/package-b/). So we adopted a flat structure with naming conventions to achieve similar organizational benefits.

We've documented our naming conventions in:

• openspec/AGENTS.md (agent instructions)
• The /opsx:new workflow prompts
• Schema configuration during the proposal/specs creation phase

Our naming format:

Type	Format
Specs	{platform}-{module}[-{feature}]
Changes	{verb}-{platform}-{module}[-{feature}]

Both platform and verb are constrained to a predefined set of allowed values to ensure consistency across the team.

We'd also love to see OpenSpec support hierarchical directory organization for specs in the future!

[JayceZhang9602]

Thanks for sharing this detailed writeup!
I've experimented with maintaining specs under sub-project directories in our team's monorepo (e.g., apps/projectA/specs/{feature}), and used AGENTS.md constraints to enforce that any spec-related changes and openspec CLI commands must be executed from within the sub-project directory (e.g., cd apps/projectA/specs/{feature} && openspec list --specs).

This approach is somewhat workable, but in practice I've found that AI tools and models don't always follow these constraints reliably. For example, proposal changes sometimes end up being created under the root-level openspec/changes directory, or modifications get archived into the root-level openspec/specs instead of the sub-project's directory.

It's clear that this requires much stronger workflow/skills constraints to work correctly. Really looking forward to seeing official monorepo support from OpenSpec!

[CS-Tao]

@TabishB Can we provide a command like /sdd:load that loads a specific change into the context and waits for the user's next action, such as modifying specs, running /sdd:continue, /sdd:apply, etc.?

[j2h4u]

The SDD world don't need another OCD framework

[TabishB]

@j2h4u Yeah it's tricky to balance utility. Everyone uses OpenSpec differently and has different levels of complexity.

I think what we need to think about is a how to setup a dual experience where we have "simple mode" for basic users but "advanced" mode for power users.

For what it's worth we try and ensure every command provides real value. Usually because we've run into the problem before.

Every OpenSpec user after using it for a while starts to ask for more commands as they start to get more comfortable with the framework and how it works.

Let me know your thoughts!

[j2h4u]

@TabishB Yeah, thanks for asking!

I'd be totally fine with keeping the three familiar commands and letting new ones gradually extend or nuance the behavior -- very much in line with the Open–Closed Principle. I'd also be fine with truly incremental changes, even adding a single new command at a time.

What's been hard for me is that the three existing commands were threw under the bus and replaced with 3х more under fancy different names. I've been using (pun IS intended) OpenSpec for about four months, and at this point a lot of it is pure muscle memory -- it’s literally at my fingertips.

Right now my brain is already running hot -- smokin' hot Claude Code Max 20 sub, a mountain of projects, constant multitasking -- so I don't really have the bandwidth and luxuries to relearn core interactions or rethink my workflow. That's why I've been holding off on updating OpenSpec

[j2h4u]

Never say never --those fancy command slowly winning me over

[TabishB]

@j2h4u I think what we're considering is making extra commands optionally installable. I sat down with a new user today and I could see how it can feel overwhelming and scary.

So we're trying to figure out how we could get users started with just 3 but then allow them to install extra ones as they see fit?

Maybe this could be a good middle ground? 🤔