cuj-design

name	cuj-design
description	Design product features from approved critical user journeys, generate CUJ-nested OpenSpec specs, track stacked PR order, and enforce approval gates before spec creation and implementation.

CUJ Feature Design Skill

Design product features from Critical User Journeys (CUJs), then convert those journeys into implementation-ready OpenSpec specifications. Each specification tracks its implementation target as a Git submodule pinned to a target repository and branch. For each CUJ, maintain a stacked PR plan that records review, merge, and deployment order across specs.

Purpose

Use this skill to make feature design repeatable for one product per repository:

1. Capture user-centric flows as CUJ markdown documents.
2. Model each journey with Mermaid journey diagrams.
3. Convert CUJs into OpenSpec specs with clear acceptance criteria.
4. Attach each spec to a target implementation repository via Git submodule.

Why OpenSpec

OpenSpec is chosen over spec-kit in this repository because:

1. It is markdown-native and easy to diff/review.
2. It maps cleanly from CUJ narratives to acceptance criteria.
3. It keeps requirements, constraints, and delivery tracking together.

Repository Conventions

• CUJs live in cuj/<cuj-slug>/cuj.md.
• Each CUJ has cuj/<cuj-slug>/pr-stack.md for stacked PR sequencing.
• Specs for a CUJ live in cuj/<cuj-slug>/specs/<spec-slug>/.
• Each spec includes:
  • spec.md (OpenSpec document)
  • tracking.md (status, decisions, links)
  • target/ (Git submodule to implementation repo)

Workflow

1. Create a CUJ file from templates/cuj-template.md.
2. Validate that the CUJ has actor, trigger, success outcome, and failure/edge paths.
3. Approve the CUJ (approval_status: approved in cuj.md).
4. Create a spec folder from templates/spec-template.md.
5. Fill implementation target metadata in spec frontmatter.
6. Add implementation repository as submodule under target/.
7. Add/update CUJ pr-stack.md with stack position and dependencies.
8. Commit CUJ + spec + pr-stack.md + .gitmodules updates together.

Submodule Requirements

Every spec must define and use:

• target_repo (Git URL)
• target_branch (branch name)
• target_submodule_path (path under the spec folder)

Recommended add command:

git submodule add -b <target_branch> <target_repo> cuj/<cuj-slug>/specs/<spec-slug>/target

Quality Bar

Before considering a spec ready:

1. CUJ includes a Mermaid journey diagram.
2. CUJ has happy path and at least one key alternate path.
3. OpenSpec has measurable acceptance criteria.
4. OpenSpec lists non-goals and constraints.
5. Target repo submodule exists and points to the declared branch.
6. CUJ pr-stack.md defines PR review/merge/deploy order for all specs in scope.
7. CUJ approval gates are satisfied for spec creation and implementation.

Hard Gates

1. Specs cannot be created until the linked CUJ is approved.
2. Specs cannot be implemented until the linked CUJ is approved.

Templates

• templates/cuj-template.md
• templates/pr-stack-template.md
• templates/spec-template.md
• templates/tracking-template.md