Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .claude/commands/opsx/apply.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
name: "OPSX: Apply"
name: 'OPSX: Apply'
description: Implement tasks from an OpenSpec change (Experimental)
category: Workflow
tags: [workflow, artifacts, experimental]
Expand All @@ -21,9 +21,11 @@ Implement tasks from an OpenSpec change.
Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).

2. **Check status to understand the schema**

```bash
openspec status --change "<name>" --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)
Expand Down Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion .claude/commands/opsx/archive.md
Original file line number Diff line number Diff line change
@@ -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]
Expand Down Expand Up @@ -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
```
Expand Down Expand Up @@ -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
Expand Down
26 changes: 17 additions & 9 deletions .claude/commands/opsx/explore.md
Original file line number Diff line number Diff line change
@@ -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]
---
Expand All @@ -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)
Expand All @@ -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 │
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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/<capability>/spec.md` |
| Requirement changed | `specs/<capability>/spec.md` |
| Design decision made | `design.md` |
| Scope changed | `proposal.md` |
| New work identified | `tasks.md` |
| Assumption invalidated | Relevant artifact |
| Requirement changed | `specs/<capability>/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?"
Expand Down
30 changes: 25 additions & 5 deletions .claude/commands/opsx/onboard.md
Original file line number Diff line number Diff line change
@@ -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]
Expand All @@ -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.
Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -160,6 +164,7 @@ Now let's create a change to hold our work.
## Phase 4: Create the Change

**EXPLAIN:**

```
## Creating a Change

Expand All @@ -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 "<derived-name>"
```

**SHOW:**

```
Created: `openspec/changes/<name>/`

The folder structure:
```

openspec/changes/<name>/
├── 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.
Expand All @@ -194,6 +203,7 @@ Now let's fill in the first artifact—the proposal.
## Phase 5: Proposal

**EXPLAIN:**

```
## The Proposal

Expand Down Expand Up @@ -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 "<name>" --json
```

Then write the content to `openspec/changes/<name>/proposal.md`.

```
Expand All @@ -254,6 +266,7 @@ Next up: specs.
## Phase 6: Specs

**EXPLAIN:**

```
## Specs

Expand All @@ -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/<name>/specs/<capability-name>
Expand Down Expand Up @@ -301,6 +315,7 @@ Save to `openspec/changes/<name>/specs/<capability>/spec.md`.
## Phase 7: Design

**EXPLAIN:**

```
## Design

Expand Down Expand Up @@ -346,6 +361,7 @@ Save to `openspec/changes/<name>/design.md`.
## Phase 8: Tasks

**EXPLAIN:**

```
## Tasks

Expand Down Expand Up @@ -384,6 +400,7 @@ Save to `openspec/changes/<name>/tasks.md`.
## Phase 9: Apply (Implementation)

**EXPLAIN:**

```
## Implementation

Expand Down Expand Up @@ -418,6 +435,7 @@ The change is implemented! One more step—let's archive it.
## Phase 10: Archive

**EXPLAIN:**

```
## Archiving

Expand All @@ -427,11 +445,13 @@ Archived changes become your project's decision history—you can always find th
```

**DO:**

```bash
openspec archive "<name>"
```

**SHOW:**

```
Archived to: `openspec/changes/archive/YYYY-MM-DD-<name>/`

Expand Down
Loading
Loading