diff --git a/.claude/commands/opsx/apply.md b/.claude/commands/opsx/apply.md index bf23721..dc7413e 100644 --- a/.claude/commands/opsx/apply.md +++ b/.claude/commands/opsx/apply.md @@ -1,5 +1,5 @@ --- -name: "OPSX: Apply" +name: 'OPSX: Apply' description: Implement tasks from an OpenSpec change (Experimental) category: Workflow tags: [workflow, artifacts, experimental] @@ -21,9 +21,11 @@ Implement tasks from an OpenSpec change. Always announce: "Using change: " and how to override (e.g., `/opsx:apply `). 2. **Check status to understand the schema** + ```bash openspec status --change "" --json ``` + Parse the JSON to understand: - `schemaName`: The workflow being used (e.g., "spec-driven") - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others) @@ -135,6 +137,7 @@ What would you like to do? ``` **Guardrails** + - Keep going through tasks until done or blocked - Always read context files before starting (from the apply instructions output) - If task is ambiguous, pause and ask before implementing diff --git a/.claude/commands/opsx/archive.md b/.claude/commands/opsx/archive.md index 5e91608..ceeb937 100644 --- a/.claude/commands/opsx/archive.md +++ b/.claude/commands/opsx/archive.md @@ -1,5 +1,5 @@ --- -name: "OPSX: Archive" +name: 'OPSX: Archive' description: Archive a completed change in the experimental workflow category: Workflow tags: [workflow, archive, experimental] @@ -64,6 +64,7 @@ Archive a completed change in the experimental workflow. 5. **Perform the archive** Create the archive directory if it doesn't exist: + ```bash mkdir -p openspec/changes/archive ``` @@ -148,6 +149,7 @@ Target archive directory already exists. ``` **Guardrails** + - Always prompt for change selection if not provided - Use artifact graph (openspec status --json) for completion checking - Don't block archive on warnings - just inform and confirm diff --git a/.claude/commands/opsx/explore.md b/.claude/commands/opsx/explore.md index 30d9c57..ddc7f87 100644 --- a/.claude/commands/opsx/explore.md +++ b/.claude/commands/opsx/explore.md @@ -1,6 +1,6 @@ --- -name: "OPSX: Explore" -description: "Enter explore mode - think through ideas, investigate problems, clarify requirements" +name: 'OPSX: Explore' +description: 'Enter explore mode - think through ideas, investigate problems, clarify requirements' category: Workflow tags: [workflow, explore, experimental, thinking] --- @@ -12,6 +12,7 @@ Enter explore mode. Think deeply. Visualize freely. Follow the conversation wher **This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore. **Input**: The argument after `/opsx:explore` is whatever the user wants to think about. Could be: + - A vague idea: "real-time collaboration" - A specific problem: "the auth system is getting unwieldy" - A change name: "add-dark-mode" (to explore in context of that change) @@ -36,24 +37,28 @@ Enter explore mode. Think deeply. Visualize freely. Follow the conversation wher Depending on what the user brings, you might: **Explore the problem space** + - Ask clarifying questions that emerge from what they said - Challenge assumptions - Reframe the problem - Find analogies **Investigate the codebase** + - Map existing architecture relevant to the discussion - Find integration points - Identify patterns already in use - Surface hidden complexity **Compare options** + - Brainstorm multiple approaches - Build comparison tables - Sketch tradeoffs - Recommend a path (if asked) **Visualize** + ``` ┌─────────────────────────────────────────┐ │ Use ASCII diagrams liberally │ @@ -72,6 +77,7 @@ Depending on what the user brings, you might: ``` **Surface risks and unknowns** + - Identify what could go wrong - Find gaps in understanding - Suggest spikes or investigations @@ -85,11 +91,13 @@ You have full context of the OpenSpec system. Use it naturally, don't force it. ### Check for context At the start, quickly check what exists: + ```bash openspec list --json ``` This tells you: + - If there are active changes - Their names, schemas, and status - What the user might be working on @@ -119,14 +127,14 @@ If the user mentions a change or you detect one is relevant: 3. **Offer to capture when decisions are made** - | Insight Type | Where to Capture | - |--------------|------------------| + | Insight Type | Where to Capture | + | -------------------------- | ---------------------------- | | New requirement discovered | `specs//spec.md` | - | Requirement changed | `specs//spec.md` | - | Design decision made | `design.md` | - | Scope changed | `proposal.md` | - | New work identified | `tasks.md` | - | Assumption invalidated | Relevant artifact | + | Requirement changed | `specs//spec.md` | + | Design decision made | `design.md` | + | Scope changed | `proposal.md` | + | New work identified | `tasks.md` | + | Assumption invalidated | Relevant artifact | Example offers: - "That's a design decision. Capture it in design.md?" diff --git a/.claude/commands/opsx/onboard.md b/.claude/commands/opsx/onboard.md index 7df677c..67afb02 100644 --- a/.claude/commands/opsx/onboard.md +++ b/.claude/commands/opsx/onboard.md @@ -1,5 +1,5 @@ --- -name: "OPSX: Onboard" +name: 'OPSX: Onboard' description: Guided onboarding - walk through a complete OpenSpec workflow cycle with narration category: Workflow tags: [workflow, onboarding, tutorial, learning] @@ -21,6 +21,7 @@ openspec --version 2>&1 || echo "CLI_NOT_INSTALLED" ``` **If CLI not installed:** + > OpenSpec CLI is not installed. Install it first, then come back to `/opsx:onboard`. Stop here if not installed. @@ -65,6 +66,7 @@ Scan the codebase for small improvement opportunities. Look for: 6. **Missing validation** - User input handlers without validation Also check recent git activity: + ```bash # Unix/macOS git log --oneline -10 2>/dev/null || echo "No git history" @@ -103,6 +105,7 @@ Which task interests you? (Pick a number or describe your own) ``` **If nothing found:** Fall back to asking what the user wants to build: + > I didn't find obvious quick wins in your codebase. What's something small you've been meaning to add or fix? ### Scope Guardrail @@ -135,6 +138,7 @@ Before we create a change, let me quickly show you **explore mode**—it's how y ``` Spend 1-2 minutes investigating the relevant code: + - Read the file(s) involved - Draw a quick ASCII diagram if it helps - Note any considerations @@ -160,6 +164,7 @@ Now let's create a change to hold our work. ## Phase 4: Create the Change **EXPLAIN:** + ``` ## Creating a Change @@ -169,21 +174,25 @@ Let me create one for our task. ``` **DO:** Create the change with a derived kebab-case name: + ```bash openspec new change "" ``` **SHOW:** + ``` Created: `openspec/changes//` The folder structure: ``` + openspec/changes// -├── proposal.md ← Why we're doing this (empty, we'll fill it) -├── design.md ← How we'll build it (empty) -├── specs/ ← Detailed requirements (empty) -└── tasks.md ← Implementation checklist (empty) +├── proposal.md ← Why we're doing this (empty, we'll fill it) +├── design.md ← How we'll build it (empty) +├── specs/ ← Detailed requirements (empty) +└── tasks.md ← Implementation checklist (empty) + ``` Now let's fill in the first artifact—the proposal. @@ -194,6 +203,7 @@ Now let's fill in the first artifact—the proposal. ## Phase 5: Proposal **EXPLAIN:** + ``` ## The Proposal @@ -238,9 +248,11 @@ Does this capture the intent? I can adjust before we save it. **PAUSE** - Wait for user approval/feedback. After approval, save the proposal: + ```bash openspec instructions proposal --change "" --json ``` + Then write the content to `openspec/changes//proposal.md`. ``` @@ -254,6 +266,7 @@ Next up: specs. ## Phase 6: Specs **EXPLAIN:** + ``` ## Specs @@ -263,6 +276,7 @@ For a small task like this, we might only need one spec file. ``` **DO:** Create the spec file: + ```bash # Unix/macOS mkdir -p openspec/changes//specs/ @@ -301,6 +315,7 @@ Save to `openspec/changes//specs//spec.md`. ## Phase 7: Design **EXPLAIN:** + ``` ## Design @@ -346,6 +361,7 @@ Save to `openspec/changes//design.md`. ## Phase 8: Tasks **EXPLAIN:** + ``` ## Tasks @@ -384,6 +400,7 @@ Save to `openspec/changes//tasks.md`. ## Phase 9: Apply (Implementation) **EXPLAIN:** + ``` ## Implementation @@ -418,6 +435,7 @@ The change is implemented! One more step—let's archive it. ## Phase 10: Archive **EXPLAIN:** + ``` ## Archiving @@ -427,11 +445,13 @@ Archived changes become your project's decision history—you can always find th ``` **DO:** + ```bash openspec archive "" ``` **SHOW:** + ``` Archived to: `openspec/changes/archive/YYYY-MM-DD-/` diff --git a/.claude/commands/opsx/propose.md b/.claude/commands/opsx/propose.md index 05276f4..2df4c24 100644 --- a/.claude/commands/opsx/propose.md +++ b/.claude/commands/opsx/propose.md @@ -1,5 +1,5 @@ --- -name: "OPSX: Propose" +name: 'OPSX: Propose' description: Propose a new change - create it and generate all artifacts in one step category: Workflow tags: [workflow, artifacts, experimental] @@ -8,6 +8,7 @@ tags: [workflow, artifacts, experimental] Propose a new change - create the change and generate all artifacts in one step. I'll create a change with artifacts: + - proposal.md (what & why) - design.md (how) - tasks.md (implementation steps) @@ -23,6 +24,7 @@ When ready to implement, run /opsx:apply 1. **If no input provided, ask what they want to build** Use the **AskUserQuestion tool** (open-ended, no preset options) to ask: + > "What change do you want to work on? Describe what you want to build or fix." From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`). @@ -30,15 +32,19 @@ When ready to implement, run /opsx:apply **IMPORTANT**: Do NOT proceed without understanding what the user wants to build. 2. **Create the change directory** + ```bash openspec new change "" ``` + This creates a scaffolded change at `openspec/changes//` with `.openspec.yaml`. 3. **Get the artifact build order** + ```bash openspec status --change "" --json ``` + Parse the JSON to get: - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`) - `artifacts`: list of all artifacts with their status and dependencies @@ -50,30 +56,30 @@ When ready to implement, run /opsx:apply Loop through artifacts in dependency order (artifacts with no pending dependencies first): a. **For each artifact that is `ready` (dependencies satisfied)**: - - Get instructions: - ```bash - openspec instructions --change "" --json - ``` - - The instructions JSON includes: - - `context`: Project background (constraints for you - do NOT include in output) - - `rules`: Artifact-specific rules (constraints for you - do NOT include in output) - - `template`: The structure to use for your output file - - `instruction`: Schema-specific guidance for this artifact type - - `outputPath`: Where to write the artifact - - `dependencies`: Completed artifacts to read for context - - Read any completed dependency files for context - - Create the artifact file using `template` as the structure - - Apply `context` and `rules` as constraints - but do NOT copy them into the file - - Show brief progress: "Created " + - Get instructions: + ```bash + openspec instructions --change "" --json + ``` + - The instructions JSON includes: + - `context`: Project background (constraints for you - do NOT include in output) + - `rules`: Artifact-specific rules (constraints for you - do NOT include in output) + - `template`: The structure to use for your output file + - `instruction`: Schema-specific guidance for this artifact type + - `outputPath`: Where to write the artifact + - `dependencies`: Completed artifacts to read for context + - Read any completed dependency files for context + - Create the artifact file using `template` as the structure + - Apply `context` and `rules` as constraints - but do NOT copy them into the file + - Show brief progress: "Created " b. **Continue until all `applyRequires` artifacts are complete** - - After creating each artifact, re-run `openspec status --change "" --json` - - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array - - Stop when all `applyRequires` artifacts are done + - After creating each artifact, re-run `openspec status --change "" --json` + - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array + - Stop when all `applyRequires` artifacts are done c. **If an artifact requires user input** (unclear context): - - Use **AskUserQuestion tool** to clarify - - Then continue with creation + - Use **AskUserQuestion tool** to clarify + - Then continue with creation 5. **Show final status** ```bash @@ -83,6 +89,7 @@ When ready to implement, run /opsx:apply **Output** After completing all artifacts, summarize: + - Change name and location - List of artifacts created with brief descriptions - What's ready: "All artifacts created! Ready for implementation." @@ -99,6 +106,7 @@ After completing all artifacts, summarize: - These guide what you write, but should never appear in the output **Guardrails** + - Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`) - Always read dependency artifacts before creating a new one - If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum diff --git a/.claude/skills/openspec-apply-change/SKILL.md b/.claude/skills/openspec-apply-change/SKILL.md index d474dc1..dd05a96 100644 --- a/.claude/skills/openspec-apply-change/SKILL.md +++ b/.claude/skills/openspec-apply-change/SKILL.md @@ -5,8 +5,8 @@ license: MIT compatibility: Requires openspec CLI. metadata: author: openspec - version: "1.0" - generatedBy: "1.2.0" + version: '1.0' + generatedBy: '1.2.0' --- Implement tasks from an OpenSpec change. @@ -25,9 +25,11 @@ Implement tasks from an OpenSpec change. Always announce: "Using change: " and how to override (e.g., `/opsx:apply `). 2. **Check status to understand the schema** + ```bash openspec status --change "" --json ``` + Parse the JSON to understand: - `schemaName`: The workflow being used (e.g., "spec-driven") - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others) @@ -139,6 +141,7 @@ What would you like to do? ``` **Guardrails** + - Keep going through tasks until done or blocked - Always read context files before starting (from the apply instructions output) - If task is ambiguous, pause and ask before implementing diff --git a/.claude/skills/openspec-archive-change/SKILL.md b/.claude/skills/openspec-archive-change/SKILL.md index 9b1f851..4163d13 100644 --- a/.claude/skills/openspec-archive-change/SKILL.md +++ b/.claude/skills/openspec-archive-change/SKILL.md @@ -5,8 +5,8 @@ license: MIT compatibility: Requires openspec CLI. metadata: author: openspec - version: "1.0" - generatedBy: "1.2.0" + version: '1.0' + generatedBy: '1.2.0' --- Archive a completed change in the experimental workflow. @@ -68,6 +68,7 @@ Archive a completed change in the experimental workflow. 5. **Perform the archive** Create the archive directory if it doesn't exist: + ```bash mkdir -p openspec/changes/archive ``` @@ -105,6 +106,7 @@ All artifacts complete. All tasks complete. ``` **Guardrails** + - Always prompt for change selection if not provided - Use artifact graph (openspec status --json) for completion checking - Don't block archive on warnings - just inform and confirm diff --git a/.claude/skills/openspec-explore/SKILL.md b/.claude/skills/openspec-explore/SKILL.md index ffa10ca..84fbec0 100644 --- a/.claude/skills/openspec-explore/SKILL.md +++ b/.claude/skills/openspec-explore/SKILL.md @@ -5,8 +5,8 @@ license: MIT compatibility: Requires openspec CLI. metadata: author: openspec - version: "1.0" - generatedBy: "1.2.0" + version: '1.0' + generatedBy: '1.2.0' --- Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes. @@ -33,24 +33,28 @@ Enter explore mode. Think deeply. Visualize freely. Follow the conversation wher Depending on what the user brings, you might: **Explore the problem space** + - Ask clarifying questions that emerge from what they said - Challenge assumptions - Reframe the problem - Find analogies **Investigate the codebase** + - Map existing architecture relevant to the discussion - Find integration points - Identify patterns already in use - Surface hidden complexity **Compare options** + - Brainstorm multiple approaches - Build comparison tables - Sketch tradeoffs - Recommend a path (if asked) **Visualize** + ``` ┌─────────────────────────────────────────┐ │ Use ASCII diagrams liberally │ @@ -69,6 +73,7 @@ Depending on what the user brings, you might: ``` **Surface risks and unknowns** + - Identify what could go wrong - Find gaps in understanding - Suggest spikes or investigations @@ -82,11 +87,13 @@ You have full context of the OpenSpec system. Use it naturally, don't force it. ### Check for context At the start, quickly check what exists: + ```bash openspec list --json ``` This tells you: + - If there are active changes - Their names, schemas, and status - What the user might be working on @@ -114,14 +121,14 @@ If the user mentions a change or you detect one is relevant: 3. **Offer to capture when decisions are made** - | Insight Type | Where to Capture | - |--------------|------------------| + | Insight Type | Where to Capture | + | -------------------------- | ---------------------------- | | New requirement discovered | `specs//spec.md` | - | Requirement changed | `specs//spec.md` | - | Design decision made | `design.md` | - | Scope changed | `proposal.md` | - | New work identified | `tasks.md` | - | Assumption invalidated | Relevant artifact | + | Requirement changed | `specs//spec.md` | + | Design decision made | `design.md` | + | Scope changed | `proposal.md` | + | New work identified | `tasks.md` | + | Assumption invalidated | Relevant artifact | Example offers: - "That's a design decision. Capture it in design.md?" @@ -146,6 +153,7 @@ If the user mentions a change or you detect one is relevant: ## Handling Different Entry Points **User brings a vague idea:** + ``` User: I'm thinking about adding real-time collaboration @@ -169,6 +177,7 @@ You: Real-time collab is a big space. Let me think about this... ``` **User brings a specific problem:** + ``` User: The auth system is a mess @@ -200,6 +209,7 @@ You: [reads codebase] ``` **User is stuck mid-implementation:** + ``` User: /opsx:explore add-auth-system The OAuth integration is more complex than expected @@ -217,6 +227,7 @@ You: [reads change artifacts] ``` **User wants to compare options:** + ``` User: Should we use Postgres or SQLite? diff --git a/.claude/skills/openspec-onboard/SKILL.md b/.claude/skills/openspec-onboard/SKILL.md index 9076b5d..9425535 100644 --- a/.claude/skills/openspec-onboard/SKILL.md +++ b/.claude/skills/openspec-onboard/SKILL.md @@ -5,8 +5,8 @@ license: MIT compatibility: Requires openspec CLI. metadata: author: openspec - version: "1.0" - generatedBy: "1.2.0" + version: '1.0' + generatedBy: '1.2.0' --- Guide the user through their first complete OpenSpec workflow cycle. This is a teaching experience—you'll do real work in their codebase while explaining each step. @@ -25,6 +25,7 @@ openspec --version 2>&1 || echo "CLI_NOT_INSTALLED" ``` **If CLI not installed:** + > OpenSpec CLI is not installed. Install it first, then come back to `/opsx:onboard`. Stop here if not installed. @@ -69,6 +70,7 @@ Scan the codebase for small improvement opportunities. Look for: 6. **Missing validation** - User input handlers without validation Also check recent git activity: + ```bash # Unix/macOS git log --oneline -10 2>/dev/null || echo "No git history" @@ -107,6 +109,7 @@ Which task interests you? (Pick a number or describe your own) ``` **If nothing found:** Fall back to asking what the user wants to build: + > I didn't find obvious quick wins in your codebase. What's something small you've been meaning to add or fix? ### Scope Guardrail @@ -139,6 +142,7 @@ Before we create a change, let me quickly show you **explore mode**—it's how y ``` Spend 1-2 minutes investigating the relevant code: + - Read the file(s) involved - Draw a quick ASCII diagram if it helps - Note any considerations @@ -164,6 +168,7 @@ Now let's create a change to hold our work. ## Phase 4: Create the Change **EXPLAIN:** + ``` ## Creating a Change @@ -173,21 +178,25 @@ Let me create one for our task. ``` **DO:** Create the change with a derived kebab-case name: + ```bash openspec new change "" ``` **SHOW:** + ``` Created: `openspec/changes//` The folder structure: ``` + openspec/changes// -├── proposal.md ← Why we're doing this (empty, we'll fill it) -├── design.md ← How we'll build it (empty) -├── specs/ ← Detailed requirements (empty) -└── tasks.md ← Implementation checklist (empty) +├── proposal.md ← Why we're doing this (empty, we'll fill it) +├── design.md ← How we'll build it (empty) +├── specs/ ← Detailed requirements (empty) +└── tasks.md ← Implementation checklist (empty) + ``` Now let's fill in the first artifact—the proposal. @@ -198,6 +207,7 @@ Now let's fill in the first artifact—the proposal. ## Phase 5: Proposal **EXPLAIN:** + ``` ## The Proposal @@ -242,9 +252,11 @@ Does this capture the intent? I can adjust before we save it. **PAUSE** - Wait for user approval/feedback. After approval, save the proposal: + ```bash openspec instructions proposal --change "" --json ``` + Then write the content to `openspec/changes//proposal.md`. ``` @@ -258,6 +270,7 @@ Next up: specs. ## Phase 6: Specs **EXPLAIN:** + ``` ## Specs @@ -267,6 +280,7 @@ For a small task like this, we might only need one spec file. ``` **DO:** Create the spec file: + ```bash # Unix/macOS mkdir -p openspec/changes//specs/ @@ -305,6 +319,7 @@ Save to `openspec/changes//specs//spec.md`. ## Phase 7: Design **EXPLAIN:** + ``` ## Design @@ -350,6 +365,7 @@ Save to `openspec/changes//design.md`. ## Phase 8: Tasks **EXPLAIN:** + ``` ## Tasks @@ -388,6 +404,7 @@ Save to `openspec/changes//tasks.md`. ## Phase 9: Apply (Implementation) **EXPLAIN:** + ``` ## Implementation @@ -422,6 +439,7 @@ The change is implemented! One more step—let's archive it. ## Phase 10: Archive **EXPLAIN:** + ``` ## Archiving @@ -431,11 +449,13 @@ Archived changes become your project's decision history—you can always find th ``` **DO:** + ```bash openspec archive "" ``` **SHOW:** + ``` Archived to: `openspec/changes/archive/YYYY-MM-DD-/` diff --git a/.claude/skills/openspec-propose/SKILL.md b/.claude/skills/openspec-propose/SKILL.md index d27bc53..5ceeeb4 100644 --- a/.claude/skills/openspec-propose/SKILL.md +++ b/.claude/skills/openspec-propose/SKILL.md @@ -5,13 +5,14 @@ license: MIT compatibility: Requires openspec CLI. metadata: author: openspec - version: "1.0" - generatedBy: "1.2.0" + version: '1.0' + generatedBy: '1.2.0' --- Propose a new change - create the change and generate all artifacts in one step. I'll create a change with artifacts: + - proposal.md (what & why) - design.md (how) - tasks.md (implementation steps) @@ -27,6 +28,7 @@ When ready to implement, run /opsx:apply 1. **If no clear input provided, ask what they want to build** Use the **AskUserQuestion tool** (open-ended, no preset options) to ask: + > "What change do you want to work on? Describe what you want to build or fix." From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`). @@ -34,15 +36,19 @@ When ready to implement, run /opsx:apply **IMPORTANT**: Do NOT proceed without understanding what the user wants to build. 2. **Create the change directory** + ```bash openspec new change "" ``` + This creates a scaffolded change at `openspec/changes//` with `.openspec.yaml`. 3. **Get the artifact build order** + ```bash openspec status --change "" --json ``` + Parse the JSON to get: - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`) - `artifacts`: list of all artifacts with their status and dependencies @@ -54,30 +60,30 @@ When ready to implement, run /opsx:apply Loop through artifacts in dependency order (artifacts with no pending dependencies first): a. **For each artifact that is `ready` (dependencies satisfied)**: - - Get instructions: - ```bash - openspec instructions --change "" --json - ``` - - The instructions JSON includes: - - `context`: Project background (constraints for you - do NOT include in output) - - `rules`: Artifact-specific rules (constraints for you - do NOT include in output) - - `template`: The structure to use for your output file - - `instruction`: Schema-specific guidance for this artifact type - - `outputPath`: Where to write the artifact - - `dependencies`: Completed artifacts to read for context - - Read any completed dependency files for context - - Create the artifact file using `template` as the structure - - Apply `context` and `rules` as constraints - but do NOT copy them into the file - - Show brief progress: "Created " + - Get instructions: + ```bash + openspec instructions --change "" --json + ``` + - The instructions JSON includes: + - `context`: Project background (constraints for you - do NOT include in output) + - `rules`: Artifact-specific rules (constraints for you - do NOT include in output) + - `template`: The structure to use for your output file + - `instruction`: Schema-specific guidance for this artifact type + - `outputPath`: Where to write the artifact + - `dependencies`: Completed artifacts to read for context + - Read any completed dependency files for context + - Create the artifact file using `template` as the structure + - Apply `context` and `rules` as constraints - but do NOT copy them into the file + - Show brief progress: "Created " b. **Continue until all `applyRequires` artifacts are complete** - - After creating each artifact, re-run `openspec status --change "" --json` - - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array - - Stop when all `applyRequires` artifacts are done + - After creating each artifact, re-run `openspec status --change "" --json` + - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array + - Stop when all `applyRequires` artifacts are done c. **If an artifact requires user input** (unclear context): - - Use **AskUserQuestion tool** to clarify - - Then continue with creation + - Use **AskUserQuestion tool** to clarify + - Then continue with creation 5. **Show final status** ```bash @@ -87,6 +93,7 @@ When ready to implement, run /opsx:apply **Output** After completing all artifacts, summarize: + - Change name and location - List of artifacts created with brief descriptions - What's ready: "All artifacts created! Ready for implementation." @@ -103,6 +110,7 @@ After completing all artifacts, summarize: - These guide what you write, but should never appear in the output **Guardrails** + - Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`) - Always read dependency artifacts before creating a new one - If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..9fc4771 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,68 @@ +name: CI + +on: + pull_request: + types: [opened, synchronize, reopened] + push: + branches: [main] + +jobs: + test: + name: Test + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + with: + version: 10 + - uses: actions/setup-node@v4 + with: + node-version: '22' + cache: 'pnpm' + - run: pnpm install --frozen-lockfile + - run: pnpm test + + lint: + name: Lint + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + with: + version: 10 + - uses: actions/setup-node@v4 + with: + node-version: '22' + cache: 'pnpm' + - run: pnpm install --frozen-lockfile + - run: pnpm lint + + typecheck: + name: Typecheck + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + with: + version: 10 + - uses: actions/setup-node@v4 + with: + node-version: '22' + cache: 'pnpm' + - run: pnpm install --frozen-lockfile + - run: pnpm typecheck + + format: + name: Format + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + with: + version: 10 + - uses: actions/setup-node@v4 + with: + node-version: '22' + cache: 'pnpm' + - run: pnpm install --frozen-lockfile + - run: pnpm format:check diff --git a/.npmrc b/.npmrc index b5f4cef..17c11a6 100644 --- a/.npmrc +++ b/.npmrc @@ -1,2 +1,4 @@ engine-strict=true shamefully-hoist=false +trusted-dependencies[]=@fission-ai/openspec +trusted-dependencies[]=esbuild diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..556f516 --- /dev/null +++ b/.prettierignore @@ -0,0 +1,4 @@ +node_modules/ +.agents/ +openspec/ +pnpm-lock.yaml diff --git a/CLAUDE.md b/CLAUDE.md index 65a81ba..dbcefd2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,40 +4,46 @@ This file provides guidance to Claude Code when working in this repository. ## What This Repo Is -Mori Design System (森, *mori* = forest) is a shared design language and component framework for a suite of SaaS products targeting the Japanese small business market. It defines design tokens, component specs, layout rules, and Japanese localisation standards used across two initial products: **ShiftMate** (shift scheduling for restaurants & retail) and **FaxBridge** (fax-to-digital automation for manufacturers & wholesalers). Every decision must reduce friction, build trust, and feel familiar — not impressive or clever. +Mori Design System (森, _mori_ = forest) is a shared design language and component framework for a suite of SaaS products targeting the Japanese small business market. It defines design tokens, component specs, layout rules, and Japanese localisation standards used across two initial products: **ShiftMate** (shift scheduling for restaurants & retail) and **FaxBridge** (fax-to-digital automation for manufacturers & wholesalers). Every decision must reduce friction, build trust, and feel familiar — not impressive or clever. -**Design Philosophy:** 自然・簡単・信頼 — *Shizen. Kantan. Shinrai. (Natural. Simple. Trustworthy.)* +**Design Philosophy:** 自然・簡単・信頼 — _Shizen. Kantan. Shinrai. (Natural. Simple. Trustworthy.)_ > Read `PROJECT.md` before writing any code for ShiftMate, FaxBridge, or any future Mori product. ## Commands ### Build + not applicable — this repo is a design system specification, not a runnable application ### Test + ```bash pnpm test ``` ### Lint + ```bash pnpm lint # check pnpm lint:fix # auto-fix ``` ### Typecheck + ```bash pnpm typecheck ``` ### Format + ```bash pnpm format # write pnpm format:check # check only ``` ### Run / Start + not applicable — individual products (ShiftMate, FaxBridge) have their own repos and dev servers ## Architecture @@ -46,16 +52,16 @@ This repo is the single source of truth for the Mori umbrella. `PROJECT.md` defi ## Tech Stack (per-product) -| Layer | Choice | -|---|---| -| Language | TypeScript (strict — no `any`, explicit return types) | -| Framework | Next.js 14 App Router | -| Styling | Tailwind CSS v3 + CSS Variables | -| Components | shadcn/ui (Mori-customised) | -| Database + Auth | Supabase | -| Hosting | Vercel | -| Payments | Stripe | -| Testing | Vitest + Playwright | +| Layer | Choice | +| --------------- | ----------------------------------------------------- | +| Language | TypeScript (strict — no `any`, explicit return types) | +| Framework | Next.js 14 App Router | +| Styling | Tailwind CSS v3 + CSS Variables | +| Components | shadcn/ui (Mori-customised) | +| Database + Auth | Supabase | +| Hosting | Vercel | +| Payments | Stripe | +| Testing | Vitest + Playwright | ## Code Style @@ -83,4 +89,5 @@ This repo is the single source of truth for the Mori umbrella. `PROJECT.md` defi - i18n for languages other than Japanese ## Last Updated + 2026-03-30 diff --git a/JOURNAL.md b/JOURNAL.md index 0a29c0b..57fbc8d 100644 --- a/JOURNAL.md +++ b/JOURNAL.md @@ -3,12 +3,14 @@ _Last updated: 2026-03-30_ ## Current + - [x] Repo initialized with TypeScript, ESLint, Prettier, pnpm - [x] Dialog component spec added to PROJECT.md - [x] Design tokens implemented — `src/tokens/globals.css` (57 CSS vars, 65 Vitest tests) - [x] OpenSpec CLI (@fission-ai/openspec v1.2.0) installed ## Future + - [ ] Remaining component specs: Button, Input, Card, Badge/Tag, Navigation, Loading, Empty States, Toast - [ ] Page layout system spec - [ ] Japanese localisation utilities (date, currency, time formatters) diff --git a/PROJECT.md b/PROJECT.md index e328eb0..8363631 100644 --- a/PROJECT.md +++ b/PROJECT.md @@ -1,4 +1,5 @@ # Mori Design System + # 森 デザインシステム > **This document is the single source of truth for all products built under the Mori umbrella.** @@ -8,11 +9,11 @@ ## Purpose -Mori Design System (森, *mori* = forest in Japanese) is a shared design language and component framework built for a suite of SaaS products targeting the Japanese small business market. Every design decision must reduce friction, build trust, and feel immediately familiar — not impressive or clever. +Mori Design System (森, _mori_ = forest in Japanese) is a shared design language and component framework built for a suite of SaaS products targeting the Japanese small business market. Every design decision must reduce friction, build trust, and feel immediately familiar — not impressive or clever. **Design Philosophy — Three Words** **Shizen. Kantan. Shinrai.** -自然・簡単・信頼 — *Natural. Simple. Trustworthy.* +自然・簡単・信頼 — _Natural. Simple. Trustworthy._ --- @@ -24,9 +25,9 @@ Japanese small business owners — restaurants, retail shops, manufacturers, and ## Products -| Product | Description | Status | -|---|---|---| -| **ShiftMate** (シフトメイト) | Shift scheduling SaaS for small restaurants & retail | 🟡 In development | +| Product | Description | Status | +| ---------------------------------- | --------------------------------------------------------- | ----------------- | +| **ShiftMate** (シフトメイト) | Shift scheduling SaaS for small restaurants & retail | 🟡 In development | | **FaxBridge** (ファックスブリッジ) | Fax-to-digital automation for manufacturers & wholesalers | 🟡 In development | --- @@ -57,19 +58,19 @@ Japanese small business owners — restaurants, retail shops, manufacturers, and ## Tech Stack -| Layer | Choice | Rationale | -|---|---|---| -| Language | TypeScript (strict) | Catches token misuse at compile time across shared components | -| Framework | Next.js 14 (App Router) | Server Components reduce client JS — critical for mobile on Japanese networks | -| Styling | Tailwind CSS v3 + CSS Variables | CSS variables enable the token system shared and extended per product | -| Components | shadcn/ui (Mori-customised) | Copy-paste model means Mori owns the customisations, no override fighting | -| Database + Auth | Supabase (PostgreSQL + Auth + Storage) | Reduces moving parts for small team building two products simultaneously | -| Hosting | Vercel | Zero-config Next.js; edge network reduces latency for Japan | -| Payments | Stripe (Billing + Checkout) | Only mature processor with solid Japan support and yen handling | -| Error tracking | Sentry | Catches production errors before Japanese SMB users abandon silently | -| Analytics | PostHog + Vercel Analytics | PostHog for behavioural funnels; Vercel Analytics for Core Web Vitals | -| Email | Resend | Clean API, good Japan deliverability, pairs with React Email | -| Testing | Vitest + Playwright | Vitest for unit; Playwright for e2e with mobile viewport testing | +| Layer | Choice | Rationale | +| --------------- | -------------------------------------- | ----------------------------------------------------------------------------- | +| Language | TypeScript (strict) | Catches token misuse at compile time across shared components | +| Framework | Next.js 14 (App Router) | Server Components reduce client JS — critical for mobile on Japanese networks | +| Styling | Tailwind CSS v3 + CSS Variables | CSS variables enable the token system shared and extended per product | +| Components | shadcn/ui (Mori-customised) | Copy-paste model means Mori owns the customisations, no override fighting | +| Database + Auth | Supabase (PostgreSQL + Auth + Storage) | Reduces moving parts for small team building two products simultaneously | +| Hosting | Vercel | Zero-config Next.js; edge network reduces latency for Japan | +| Payments | Stripe (Billing + Checkout) | Only mature processor with solid Japan support and yen handling | +| Error tracking | Sentry | Catches production errors before Japanese SMB users abandon silently | +| Analytics | PostHog + Vercel Analytics | PostHog for behavioural funnels; Vercel Analytics for Core Web Vitals | +| Email | Resend | Clean API, good Japan deliverability, pairs with React Email | +| Testing | Vitest + Playwright | Vitest for unit; Playwright for e2e with mobile viewport testing | --- @@ -102,33 +103,33 @@ All values are defined as CSS custom properties on `:root`. **Never hardcode hex ```css :root { /* === Brand === */ - --color-brand: #2D7A4F; /* 森緑 — primary brand green */ - --color-brand-light: #EAF3DE; /* light tint for backgrounds */ - --color-brand-dark: #1A5C38; /* hover / pressed state */ + --color-brand: #2d7a4f; /* 森緑 — primary brand green */ + --color-brand-light: #eaf3de; /* light tint for backgrounds */ + --color-brand-dark: #1a5c38; /* hover / pressed state */ /* === Neutrals === */ - --color-ink: #1A1A1A; /* 森黒 — primary text */ - --color-ink-secondary: #4A4A4A; /* secondary text */ - --color-ink-tertiary: #8A8A8A; /* placeholder, disabled */ + --color-ink: #1a1a1a; /* 森黒 — primary text */ + --color-ink-secondary: #4a4a4a; /* secondary text */ + --color-ink-tertiary: #8a8a8a; /* placeholder, disabled */ /* === Surfaces === */ - --color-surface: #FFFFFF; /* card background */ - --color-surface-raised: #F5F3EF; /* 和紙 — page background */ - --color-surface-sunken: #EDEBE6; /* input background, inset */ + --color-surface: #ffffff; /* card background */ + --color-surface-raised: #f5f3ef; /* 和紙 — page background */ + --color-surface-sunken: #edebe6; /* input background, inset */ /* === Borders === */ - --color-border: #E8E4DC; /* 砂 — default border */ - --color-border-strong: #C8C4BC; /* focused / hover border */ + --color-border: #e8e4dc; /* 砂 — default border */ + --color-border-strong: #c8c4bc; /* focused / hover border */ /* === Semantic === */ - --color-info: #3B82F6; /* 水 — blue */ - --color-info-light: #EFF6FF; - --color-success: #22C55E; /* 若葉 — green */ - --color-success-light: #F0FDF4; - --color-warning: #F59E0B; /* 琥珀 — amber */ - --color-warning-light: #FFFBEB; - --color-error: #EF4444; /* 紅 — red */ - --color-error-light: #FEF2F2; + --color-info: #3b82f6; /* 水 — blue */ + --color-info-light: #eff6ff; + --color-success: #22c55e; /* 若葉 — green */ + --color-success-light: #f0fdf4; + --color-warning: #f59e0b; /* 琥珀 — amber */ + --color-warning-light: #fffbeb; + --color-error: #ef4444; /* 紅 — red */ + --color-error-light: #fef2f2; } ``` @@ -137,28 +138,29 @@ All values are defined as CSS custom properties on `:root`. **Never hardcode hex ```css :root { /* === Font Families === */ - --font-sans: 'Geist', 'Hiragino Kaku Gothic ProN', 'Hiragino Sans', - 'Yu Gothic', 'Meiryo', sans-serif; - --font-mono: 'Geist Mono', 'Osaka-Mono', monospace; + --font-sans: + 'Geist', 'Hiragino Kaku Gothic ProN', 'Hiragino Sans', 'Yu Gothic', 'Meiryo', sans-serif; + --font-mono: 'Geist Mono', 'Osaka-Mono', monospace; /* === Type Scale === */ - --text-xs: 0.75rem; /* 12px — labels, captions */ - --text-sm: 0.875rem; /* 14px — secondary body */ - --text-base: 1rem; /* 16px — primary body */ - --text-lg: 1.125rem; /* 18px — large body */ - --text-xl: 1.25rem; /* 20px — small heading */ - --text-2xl: 1.5rem; /* 24px — heading */ - --text-3xl: 1.875rem; /* 30px — large heading */ - --text-4xl: 2.25rem; /* 36px — display */ + --text-xs: 0.75rem; /* 12px — labels, captions */ + --text-sm: 0.875rem; /* 14px — secondary body */ + --text-base: 1rem; /* 16px — primary body */ + --text-lg: 1.125rem; /* 18px — large body */ + --text-xl: 1.25rem; /* 20px — small heading */ + --text-2xl: 1.5rem; /* 24px — heading */ + --text-3xl: 1.875rem; /* 30px — large heading */ + --text-4xl: 2.25rem; /* 36px — display */ /* === Font Weights === */ - --font-normal: 400; - --font-medium: 500; - --font-semibold: 600; /* use sparingly, headings only */ + --font-normal: 400; + --font-medium: 500; + --font-semibold: 600; /* use sparingly, headings only */ } ``` **Rules:** + - Body text: `--text-base`, `--font-normal`, line-height `1.7` - UI labels: `--text-sm`, `--font-medium` - Headings: `--font-semibold`, never bold (700) in UI @@ -170,16 +172,16 @@ Uses an 8px base grid. All spacing values are multiples of 4px. ```css :root { - --space-1: 0.25rem; /* 4px */ - --space-2: 0.5rem; /* 8px */ - --space-3: 0.75rem; /* 12px */ - --space-4: 1rem; /* 16px */ - --space-5: 1.25rem; /* 20px */ - --space-6: 1.5rem; /* 24px */ - --space-8: 2rem; /* 32px */ - --space-10: 2.5rem; /* 40px */ - --space-12: 3rem; /* 48px */ - --space-16: 4rem; /* 64px */ + --space-1: 0.25rem; /* 4px */ + --space-2: 0.5rem; /* 8px */ + --space-3: 0.75rem; /* 12px */ + --space-4: 1rem; /* 16px */ + --space-5: 1.25rem; /* 20px */ + --space-6: 1.5rem; /* 24px */ + --space-8: 2rem; /* 32px */ + --space-10: 2.5rem; /* 40px */ + --space-12: 3rem; /* 48px */ + --space-16: 4rem; /* 64px */ } ``` @@ -187,11 +189,11 @@ Uses an 8px base grid. All spacing values are multiples of 4px. ```css :root { - --radius-sm: 0.375rem; /* 6px — badges, tags */ - --radius-md: 0.5rem; /* 8px — inputs, buttons */ - --radius-lg: 0.75rem; /* 12px — cards */ - --radius-xl: 1rem; /* 16px — modals, sheets */ - --radius-full: 9999px; /* pills */ + --radius-sm: 0.375rem; /* 6px — badges, tags */ + --radius-md: 0.5rem; /* 8px — inputs, buttons */ + --radius-lg: 0.75rem; /* 12px — cards */ + --radius-xl: 1rem; /* 16px — modals, sheets */ + --radius-full: 9999px; /* pills */ } ``` @@ -201,9 +203,9 @@ Minimal. Only use where elevation is semantically necessary. ```css :root { - --shadow-sm: 0 1px 2px 0 rgba(0,0,0,0.05); - --shadow-md: 0 4px 6px -1px rgba(0,0,0,0.07), 0 2px 4px -2px rgba(0,0,0,0.05); - --shadow-lg: 0 10px 15px -3px rgba(0,0,0,0.07), 0 4px 6px -4px rgba(0,0,0,0.05); + --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05); + --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.07), 0 2px 4px -2px rgba(0, 0, 0, 0.05); + --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.07), 0 4px 6px -4px rgba(0, 0, 0, 0.05); } ``` @@ -211,16 +213,17 @@ Minimal. Only use where elevation is semantically necessary. ```css :root { - --duration-fast: 100ms; - --duration-base: 200ms; - --duration-slow: 300ms; - --ease-default: cubic-bezier(0.4, 0, 0.2, 1); - --ease-in: cubic-bezier(0.4, 0, 1, 1); - --ease-out: cubic-bezier(0, 0, 0.2, 1); + --duration-fast: 100ms; + --duration-base: 200ms; + --duration-slow: 300ms; + --ease-default: cubic-bezier(0.4, 0, 0.2, 1); + --ease-in: cubic-bezier(0.4, 0, 1, 1); + --ease-out: cubic-bezier(0, 0, 0.2, 1); } ``` **Rules:** + - All interactive elements: `transition: all var(--duration-base) var(--ease-default)` - Page transitions: none in MVP - Loading states: skeleton shimmer only, no spinners @@ -251,6 +254,7 @@ lg: 'h-12 px-6 text-base' ``` **Rules:** + - One primary button per page section maximum - Loading state: replace label with spinner icon + "処理中..." text - Destructive actions always require confirmation dialog @@ -269,6 +273,7 @@ error: 'border-[--color-error] focus:border-[--color-error] focus:ring-[--color- ``` Always pair with: + - `