Add OpenSpec phase-1-mvp change with full specifications
OpenSpec initialized with Claude Code integration. Created phase-1-mvp change with all artifacts: - proposal.md: 9 new capabilities covering Planner, Journal, and infrastructure - design.md: 8 technical decisions with alternatives considered - specs/: 9 capability specs with testable WHEN/THEN scenarios - planner-session, brouter-integration, map-display - journal-auth, route-management, planner-journal-handoff - activity-feed, shared-packages, infrastructure - tasks.md: 11 task groups, 74 implementation tasks Ready for implementation via /opsx:apply Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ullrich Schäfer
parent
5b4d072741
commit
da2f3c04ba
21 changed files with 2061 additions and 0 deletions
152
.claude/commands/opsx/apply.md
Normal file
152
.claude/commands/opsx/apply.md
Normal file
|
|
@ -0,0 +1,152 @@
|
||||||
|
---
|
||||||
|
name: "OPSX: Apply"
|
||||||
|
description: Implement tasks from an OpenSpec change (Experimental)
|
||||||
|
category: Workflow
|
||||||
|
tags: [workflow, artifacts, experimental]
|
||||||
|
---
|
||||||
|
|
||||||
|
Implement tasks from an OpenSpec change.
|
||||||
|
|
||||||
|
**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
|
||||||
|
|
||||||
|
**Steps**
|
||||||
|
|
||||||
|
1. **Select the change**
|
||||||
|
|
||||||
|
If a name is provided, use it. Otherwise:
|
||||||
|
- Infer from conversation context if the user mentioned a change
|
||||||
|
- Auto-select if only one active change exists
|
||||||
|
- If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
|
||||||
|
|
||||||
|
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)
|
||||||
|
|
||||||
|
3. **Get apply instructions**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
openspec instructions apply --change "<name>" --json
|
||||||
|
```
|
||||||
|
|
||||||
|
This returns:
|
||||||
|
- Context file paths (varies by schema)
|
||||||
|
- Progress (total, complete, remaining)
|
||||||
|
- Task list with status
|
||||||
|
- Dynamic instruction based on current state
|
||||||
|
|
||||||
|
**Handle states:**
|
||||||
|
- If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue`
|
||||||
|
- If `state: "all_done"`: congratulate, suggest archive
|
||||||
|
- Otherwise: proceed to implementation
|
||||||
|
|
||||||
|
4. **Read context files**
|
||||||
|
|
||||||
|
Read the files listed in `contextFiles` from the apply instructions output.
|
||||||
|
The files depend on the schema being used:
|
||||||
|
- **spec-driven**: proposal, specs, design, tasks
|
||||||
|
- Other schemas: follow the contextFiles from CLI output
|
||||||
|
|
||||||
|
5. **Show current progress**
|
||||||
|
|
||||||
|
Display:
|
||||||
|
- Schema being used
|
||||||
|
- Progress: "N/M tasks complete"
|
||||||
|
- Remaining tasks overview
|
||||||
|
- Dynamic instruction from CLI
|
||||||
|
|
||||||
|
6. **Implement tasks (loop until done or blocked)**
|
||||||
|
|
||||||
|
For each pending task:
|
||||||
|
- Show which task is being worked on
|
||||||
|
- Make the code changes required
|
||||||
|
- Keep changes minimal and focused
|
||||||
|
- Mark task complete in the tasks file: `- [ ]` → `- [x]`
|
||||||
|
- Continue to next task
|
||||||
|
|
||||||
|
**Pause if:**
|
||||||
|
- Task is unclear → ask for clarification
|
||||||
|
- Implementation reveals a design issue → suggest updating artifacts
|
||||||
|
- Error or blocker encountered → report and wait for guidance
|
||||||
|
- User interrupts
|
||||||
|
|
||||||
|
7. **On completion or pause, show status**
|
||||||
|
|
||||||
|
Display:
|
||||||
|
- Tasks completed this session
|
||||||
|
- Overall progress: "N/M tasks complete"
|
||||||
|
- If all done: suggest archive
|
||||||
|
- If paused: explain why and wait for guidance
|
||||||
|
|
||||||
|
**Output During Implementation**
|
||||||
|
|
||||||
|
```
|
||||||
|
## Implementing: <change-name> (schema: <schema-name>)
|
||||||
|
|
||||||
|
Working on task 3/7: <task description>
|
||||||
|
[...implementation happening...]
|
||||||
|
✓ Task complete
|
||||||
|
|
||||||
|
Working on task 4/7: <task description>
|
||||||
|
[...implementation happening...]
|
||||||
|
✓ Task complete
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output On Completion**
|
||||||
|
|
||||||
|
```
|
||||||
|
## Implementation Complete
|
||||||
|
|
||||||
|
**Change:** <change-name>
|
||||||
|
**Schema:** <schema-name>
|
||||||
|
**Progress:** 7/7 tasks complete ✓
|
||||||
|
|
||||||
|
### Completed This Session
|
||||||
|
- [x] Task 1
|
||||||
|
- [x] Task 2
|
||||||
|
...
|
||||||
|
|
||||||
|
All tasks complete! You can archive this change with `/opsx:archive`.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output On Pause (Issue Encountered)**
|
||||||
|
|
||||||
|
```
|
||||||
|
## Implementation Paused
|
||||||
|
|
||||||
|
**Change:** <change-name>
|
||||||
|
**Schema:** <schema-name>
|
||||||
|
**Progress:** 4/7 tasks complete
|
||||||
|
|
||||||
|
### Issue Encountered
|
||||||
|
<description of the issue>
|
||||||
|
|
||||||
|
**Options:**
|
||||||
|
1. <option 1>
|
||||||
|
2. <option 2>
|
||||||
|
3. Other approach
|
||||||
|
|
||||||
|
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
|
||||||
|
- If implementation reveals issues, pause and suggest artifact updates
|
||||||
|
- Keep code changes minimal and scoped to each task
|
||||||
|
- Update task checkbox immediately after completing each task
|
||||||
|
- Pause on errors, blockers, or unclear requirements - don't guess
|
||||||
|
- Use contextFiles from CLI output, don't assume specific file names
|
||||||
|
|
||||||
|
**Fluid Workflow Integration**
|
||||||
|
|
||||||
|
This skill supports the "actions on a change" model:
|
||||||
|
|
||||||
|
- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
|
||||||
|
- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
|
||||||
157
.claude/commands/opsx/archive.md
Normal file
157
.claude/commands/opsx/archive.md
Normal file
|
|
@ -0,0 +1,157 @@
|
||||||
|
---
|
||||||
|
name: "OPSX: Archive"
|
||||||
|
description: Archive a completed change in the experimental workflow
|
||||||
|
category: Workflow
|
||||||
|
tags: [workflow, archive, experimental]
|
||||||
|
---
|
||||||
|
|
||||||
|
Archive a completed change in the experimental workflow.
|
||||||
|
|
||||||
|
**Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
|
||||||
|
|
||||||
|
**Steps**
|
||||||
|
|
||||||
|
1. **If no change name provided, prompt for selection**
|
||||||
|
|
||||||
|
Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
|
||||||
|
|
||||||
|
Show only active changes (not already archived).
|
||||||
|
Include the schema used for each change if available.
|
||||||
|
|
||||||
|
**IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
|
||||||
|
|
||||||
|
2. **Check artifact completion status**
|
||||||
|
|
||||||
|
Run `openspec status --change "<name>" --json` to check artifact completion.
|
||||||
|
|
||||||
|
Parse the JSON to understand:
|
||||||
|
- `schemaName`: The workflow being used
|
||||||
|
- `artifacts`: List of artifacts with their status (`done` or other)
|
||||||
|
|
||||||
|
**If any artifacts are not `done`:**
|
||||||
|
- Display warning listing incomplete artifacts
|
||||||
|
- Prompt user for confirmation to continue
|
||||||
|
- Proceed if user confirms
|
||||||
|
|
||||||
|
3. **Check task completion status**
|
||||||
|
|
||||||
|
Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
|
||||||
|
|
||||||
|
Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
|
||||||
|
|
||||||
|
**If incomplete tasks found:**
|
||||||
|
- Display warning showing count of incomplete tasks
|
||||||
|
- Prompt user for confirmation to continue
|
||||||
|
- Proceed if user confirms
|
||||||
|
|
||||||
|
**If no tasks file exists:** Proceed without task-related warning.
|
||||||
|
|
||||||
|
4. **Assess delta spec sync state**
|
||||||
|
|
||||||
|
Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
|
||||||
|
|
||||||
|
**If delta specs exist:**
|
||||||
|
- Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
|
||||||
|
- Determine what changes would be applied (adds, modifications, removals, renames)
|
||||||
|
- Show a combined summary before prompting
|
||||||
|
|
||||||
|
**Prompt options:**
|
||||||
|
- If changes needed: "Sync now (recommended)", "Archive without syncing"
|
||||||
|
- If already synced: "Archive now", "Sync anyway", "Cancel"
|
||||||
|
|
||||||
|
If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
|
||||||
|
|
||||||
|
5. **Perform the archive**
|
||||||
|
|
||||||
|
Create the archive directory if it doesn't exist:
|
||||||
|
```bash
|
||||||
|
mkdir -p openspec/changes/archive
|
||||||
|
```
|
||||||
|
|
||||||
|
Generate target name using current date: `YYYY-MM-DD-<change-name>`
|
||||||
|
|
||||||
|
**Check if target already exists:**
|
||||||
|
- If yes: Fail with error, suggest renaming existing archive or using different date
|
||||||
|
- If no: Move the change directory to archive
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
|
||||||
|
```
|
||||||
|
|
||||||
|
6. **Display summary**
|
||||||
|
|
||||||
|
Show archive completion summary including:
|
||||||
|
- Change name
|
||||||
|
- Schema that was used
|
||||||
|
- Archive location
|
||||||
|
- Spec sync status (synced / sync skipped / no delta specs)
|
||||||
|
- Note about any warnings (incomplete artifacts/tasks)
|
||||||
|
|
||||||
|
**Output On Success**
|
||||||
|
|
||||||
|
```
|
||||||
|
## Archive Complete
|
||||||
|
|
||||||
|
**Change:** <change-name>
|
||||||
|
**Schema:** <schema-name>
|
||||||
|
**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
|
||||||
|
**Specs:** ✓ Synced to main specs
|
||||||
|
|
||||||
|
All artifacts complete. All tasks complete.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output On Success (No Delta Specs)**
|
||||||
|
|
||||||
|
```
|
||||||
|
## Archive Complete
|
||||||
|
|
||||||
|
**Change:** <change-name>
|
||||||
|
**Schema:** <schema-name>
|
||||||
|
**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
|
||||||
|
**Specs:** No delta specs
|
||||||
|
|
||||||
|
All artifacts complete. All tasks complete.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output On Success With Warnings**
|
||||||
|
|
||||||
|
```
|
||||||
|
## Archive Complete (with warnings)
|
||||||
|
|
||||||
|
**Change:** <change-name>
|
||||||
|
**Schema:** <schema-name>
|
||||||
|
**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
|
||||||
|
**Specs:** Sync skipped (user chose to skip)
|
||||||
|
|
||||||
|
**Warnings:**
|
||||||
|
- Archived with 2 incomplete artifacts
|
||||||
|
- Archived with 3 incomplete tasks
|
||||||
|
- Delta spec sync was skipped (user chose to skip)
|
||||||
|
|
||||||
|
Review the archive if this was not intentional.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output On Error (Archive Exists)**
|
||||||
|
|
||||||
|
```
|
||||||
|
## Archive Failed
|
||||||
|
|
||||||
|
**Change:** <change-name>
|
||||||
|
**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
|
||||||
|
|
||||||
|
Target archive directory already exists.
|
||||||
|
|
||||||
|
**Options:**
|
||||||
|
1. Rename the existing archive
|
||||||
|
2. Delete the existing archive if it's a duplicate
|
||||||
|
3. Wait until a different date to archive
|
||||||
|
```
|
||||||
|
|
||||||
|
**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
|
||||||
|
- Preserve .openspec.yaml when moving to archive (it moves with the directory)
|
||||||
|
- Show clear summary of what happened
|
||||||
|
- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven)
|
||||||
|
- If delta specs exist, always run the sync assessment and show the combined summary before prompting
|
||||||
173
.claude/commands/opsx/explore.md
Normal file
173
.claude/commands/opsx/explore.md
Normal file
|
|
@ -0,0 +1,173 @@
|
||||||
|
---
|
||||||
|
name: "OPSX: Explore"
|
||||||
|
description: "Enter explore mode - think through ideas, investigate problems, clarify requirements"
|
||||||
|
category: Workflow
|
||||||
|
tags: [workflow, explore, experimental, thinking]
|
||||||
|
---
|
||||||
|
|
||||||
|
Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
|
||||||
|
|
||||||
|
**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
|
||||||
|
|
||||||
|
**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)
|
||||||
|
- A comparison: "postgres vs sqlite for this"
|
||||||
|
- Nothing (just enter explore mode)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The Stance
|
||||||
|
|
||||||
|
- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
|
||||||
|
- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
|
||||||
|
- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
|
||||||
|
- **Adaptive** - Follow interesting threads, pivot when new information emerges
|
||||||
|
- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
|
||||||
|
- **Grounded** - Explore the actual codebase when relevant, don't just theorize
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What You Might Do
|
||||||
|
|
||||||
|
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 │
|
||||||
|
├─────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌────────┐ ┌────────┐ │
|
||||||
|
│ │ State │────────▶│ State │ │
|
||||||
|
│ │ A │ │ B │ │
|
||||||
|
│ └────────┘ └────────┘ │
|
||||||
|
│ │
|
||||||
|
│ System diagrams, state machines, │
|
||||||
|
│ data flows, architecture sketches, │
|
||||||
|
│ dependency graphs, comparison tables │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**Surface risks and unknowns**
|
||||||
|
- Identify what could go wrong
|
||||||
|
- Find gaps in understanding
|
||||||
|
- Suggest spikes or investigations
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## OpenSpec Awareness
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
If the user mentioned a specific change name, read its artifacts for context.
|
||||||
|
|
||||||
|
### When no change exists
|
||||||
|
|
||||||
|
Think freely. When insights crystallize, you might offer:
|
||||||
|
|
||||||
|
- "This feels solid enough to start a change. Want me to create a proposal?"
|
||||||
|
- Or keep exploring - no pressure to formalize
|
||||||
|
|
||||||
|
### When a change exists
|
||||||
|
|
||||||
|
If the user mentions a change or you detect one is relevant:
|
||||||
|
|
||||||
|
1. **Read existing artifacts for context**
|
||||||
|
- `openspec/changes/<name>/proposal.md`
|
||||||
|
- `openspec/changes/<name>/design.md`
|
||||||
|
- `openspec/changes/<name>/tasks.md`
|
||||||
|
- etc.
|
||||||
|
|
||||||
|
2. **Reference them naturally in conversation**
|
||||||
|
- "Your design mentions using Redis, but we just realized SQLite fits better..."
|
||||||
|
- "The proposal scopes this to premium users, but we're now thinking everyone..."
|
||||||
|
|
||||||
|
3. **Offer to capture when decisions are made**
|
||||||
|
|
||||||
|
| 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 |
|
||||||
|
|
||||||
|
Example offers:
|
||||||
|
- "That's a design decision. Capture it in design.md?"
|
||||||
|
- "This is a new requirement. Add it to specs?"
|
||||||
|
- "This changes scope. Update the proposal?"
|
||||||
|
|
||||||
|
4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What You Don't Have To Do
|
||||||
|
|
||||||
|
- Follow a script
|
||||||
|
- Ask the same questions every time
|
||||||
|
- Produce a specific artifact
|
||||||
|
- Reach a conclusion
|
||||||
|
- Stay on topic if a tangent is valuable
|
||||||
|
- Be brief (this is thinking time)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ending Discovery
|
||||||
|
|
||||||
|
There's no required ending. Discovery might:
|
||||||
|
|
||||||
|
- **Flow into a proposal**: "Ready to start? I can create a change proposal."
|
||||||
|
- **Result in artifact updates**: "Updated design.md with these decisions"
|
||||||
|
- **Just provide clarity**: User has what they need, moves on
|
||||||
|
- **Continue later**: "We can pick this up anytime"
|
||||||
|
|
||||||
|
When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Guardrails
|
||||||
|
|
||||||
|
- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
|
||||||
|
- **Don't fake understanding** - If something is unclear, dig deeper
|
||||||
|
- **Don't rush** - Discovery is thinking time, not task time
|
||||||
|
- **Don't force structure** - Let patterns emerge naturally
|
||||||
|
- **Don't auto-capture** - Offer to save insights, don't just do it
|
||||||
|
- **Do visualize** - A good diagram is worth many paragraphs
|
||||||
|
- **Do explore the codebase** - Ground discussions in reality
|
||||||
|
- **Do question assumptions** - Including the user's and your own
|
||||||
106
.claude/commands/opsx/propose.md
Normal file
106
.claude/commands/opsx/propose.md
Normal file
|
|
@ -0,0 +1,106 @@
|
||||||
|
---
|
||||||
|
name: "OPSX: Propose"
|
||||||
|
description: Propose a new change - create it and generate all artifacts in one step
|
||||||
|
category: Workflow
|
||||||
|
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)
|
||||||
|
|
||||||
|
When ready to implement, run /opsx:apply
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Input**: The argument after `/opsx:propose` is the change name (kebab-case), OR a description of what the user wants to build.
|
||||||
|
|
||||||
|
**Steps**
|
||||||
|
|
||||||
|
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`).
|
||||||
|
|
||||||
|
**IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
|
||||||
|
|
||||||
|
2. **Create the change directory**
|
||||||
|
```bash
|
||||||
|
openspec new change "<name>"
|
||||||
|
```
|
||||||
|
This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
|
||||||
|
|
||||||
|
3. **Get the artifact build order**
|
||||||
|
```bash
|
||||||
|
openspec status --change "<name>" --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
|
||||||
|
|
||||||
|
4. **Create artifacts in sequence until apply-ready**
|
||||||
|
|
||||||
|
Use the **TodoWrite tool** to track progress through the artifacts.
|
||||||
|
|
||||||
|
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 <artifact-id> --change "<name>" --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 <artifact-id>"
|
||||||
|
|
||||||
|
b. **Continue until all `applyRequires` artifacts are complete**
|
||||||
|
- After creating each artifact, re-run `openspec status --change "<name>" --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
|
||||||
|
|
||||||
|
5. **Show final status**
|
||||||
|
```bash
|
||||||
|
openspec status --change "<name>"
|
||||||
|
```
|
||||||
|
|
||||||
|
**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."
|
||||||
|
- Prompt: "Run `/opsx:apply` to start implementing."
|
||||||
|
|
||||||
|
**Artifact Creation Guidelines**
|
||||||
|
|
||||||
|
- Follow the `instruction` field from `openspec instructions` for each artifact type
|
||||||
|
- The schema defines what each artifact should contain - follow it
|
||||||
|
- Read dependency artifacts for context before creating new ones
|
||||||
|
- Use `template` as the structure for your output file - fill in its sections
|
||||||
|
- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
|
||||||
|
- Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
|
||||||
|
- 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
|
||||||
|
- If a change with that name already exists, ask if user wants to continue it or create a new one
|
||||||
|
- Verify each artifact file exists after writing before proceeding to next
|
||||||
156
.claude/skills/openspec-apply-change/SKILL.md
Normal file
156
.claude/skills/openspec-apply-change/SKILL.md
Normal file
|
|
@ -0,0 +1,156 @@
|
||||||
|
---
|
||||||
|
name: openspec-apply-change
|
||||||
|
description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
|
||||||
|
license: MIT
|
||||||
|
compatibility: Requires openspec CLI.
|
||||||
|
metadata:
|
||||||
|
author: openspec
|
||||||
|
version: "1.0"
|
||||||
|
generatedBy: "1.2.0"
|
||||||
|
---
|
||||||
|
|
||||||
|
Implement tasks from an OpenSpec change.
|
||||||
|
|
||||||
|
**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
|
||||||
|
|
||||||
|
**Steps**
|
||||||
|
|
||||||
|
1. **Select the change**
|
||||||
|
|
||||||
|
If a name is provided, use it. Otherwise:
|
||||||
|
- Infer from conversation context if the user mentioned a change
|
||||||
|
- Auto-select if only one active change exists
|
||||||
|
- If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
|
||||||
|
|
||||||
|
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)
|
||||||
|
|
||||||
|
3. **Get apply instructions**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
openspec instructions apply --change "<name>" --json
|
||||||
|
```
|
||||||
|
|
||||||
|
This returns:
|
||||||
|
- Context file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
|
||||||
|
- Progress (total, complete, remaining)
|
||||||
|
- Task list with status
|
||||||
|
- Dynamic instruction based on current state
|
||||||
|
|
||||||
|
**Handle states:**
|
||||||
|
- If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change
|
||||||
|
- If `state: "all_done"`: congratulate, suggest archive
|
||||||
|
- Otherwise: proceed to implementation
|
||||||
|
|
||||||
|
4. **Read context files**
|
||||||
|
|
||||||
|
Read the files listed in `contextFiles` from the apply instructions output.
|
||||||
|
The files depend on the schema being used:
|
||||||
|
- **spec-driven**: proposal, specs, design, tasks
|
||||||
|
- Other schemas: follow the contextFiles from CLI output
|
||||||
|
|
||||||
|
5. **Show current progress**
|
||||||
|
|
||||||
|
Display:
|
||||||
|
- Schema being used
|
||||||
|
- Progress: "N/M tasks complete"
|
||||||
|
- Remaining tasks overview
|
||||||
|
- Dynamic instruction from CLI
|
||||||
|
|
||||||
|
6. **Implement tasks (loop until done or blocked)**
|
||||||
|
|
||||||
|
For each pending task:
|
||||||
|
- Show which task is being worked on
|
||||||
|
- Make the code changes required
|
||||||
|
- Keep changes minimal and focused
|
||||||
|
- Mark task complete in the tasks file: `- [ ]` → `- [x]`
|
||||||
|
- Continue to next task
|
||||||
|
|
||||||
|
**Pause if:**
|
||||||
|
- Task is unclear → ask for clarification
|
||||||
|
- Implementation reveals a design issue → suggest updating artifacts
|
||||||
|
- Error or blocker encountered → report and wait for guidance
|
||||||
|
- User interrupts
|
||||||
|
|
||||||
|
7. **On completion or pause, show status**
|
||||||
|
|
||||||
|
Display:
|
||||||
|
- Tasks completed this session
|
||||||
|
- Overall progress: "N/M tasks complete"
|
||||||
|
- If all done: suggest archive
|
||||||
|
- If paused: explain why and wait for guidance
|
||||||
|
|
||||||
|
**Output During Implementation**
|
||||||
|
|
||||||
|
```
|
||||||
|
## Implementing: <change-name> (schema: <schema-name>)
|
||||||
|
|
||||||
|
Working on task 3/7: <task description>
|
||||||
|
[...implementation happening...]
|
||||||
|
✓ Task complete
|
||||||
|
|
||||||
|
Working on task 4/7: <task description>
|
||||||
|
[...implementation happening...]
|
||||||
|
✓ Task complete
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output On Completion**
|
||||||
|
|
||||||
|
```
|
||||||
|
## Implementation Complete
|
||||||
|
|
||||||
|
**Change:** <change-name>
|
||||||
|
**Schema:** <schema-name>
|
||||||
|
**Progress:** 7/7 tasks complete ✓
|
||||||
|
|
||||||
|
### Completed This Session
|
||||||
|
- [x] Task 1
|
||||||
|
- [x] Task 2
|
||||||
|
...
|
||||||
|
|
||||||
|
All tasks complete! Ready to archive this change.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output On Pause (Issue Encountered)**
|
||||||
|
|
||||||
|
```
|
||||||
|
## Implementation Paused
|
||||||
|
|
||||||
|
**Change:** <change-name>
|
||||||
|
**Schema:** <schema-name>
|
||||||
|
**Progress:** 4/7 tasks complete
|
||||||
|
|
||||||
|
### Issue Encountered
|
||||||
|
<description of the issue>
|
||||||
|
|
||||||
|
**Options:**
|
||||||
|
1. <option 1>
|
||||||
|
2. <option 2>
|
||||||
|
3. Other approach
|
||||||
|
|
||||||
|
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
|
||||||
|
- If implementation reveals issues, pause and suggest artifact updates
|
||||||
|
- Keep code changes minimal and scoped to each task
|
||||||
|
- Update task checkbox immediately after completing each task
|
||||||
|
- Pause on errors, blockers, or unclear requirements - don't guess
|
||||||
|
- Use contextFiles from CLI output, don't assume specific file names
|
||||||
|
|
||||||
|
**Fluid Workflow Integration**
|
||||||
|
|
||||||
|
This skill supports the "actions on a change" model:
|
||||||
|
|
||||||
|
- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
|
||||||
|
- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
|
||||||
114
.claude/skills/openspec-archive-change/SKILL.md
Normal file
114
.claude/skills/openspec-archive-change/SKILL.md
Normal file
|
|
@ -0,0 +1,114 @@
|
||||||
|
---
|
||||||
|
name: openspec-archive-change
|
||||||
|
description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
|
||||||
|
license: MIT
|
||||||
|
compatibility: Requires openspec CLI.
|
||||||
|
metadata:
|
||||||
|
author: openspec
|
||||||
|
version: "1.0"
|
||||||
|
generatedBy: "1.2.0"
|
||||||
|
---
|
||||||
|
|
||||||
|
Archive a completed change in the experimental workflow.
|
||||||
|
|
||||||
|
**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
|
||||||
|
|
||||||
|
**Steps**
|
||||||
|
|
||||||
|
1. **If no change name provided, prompt for selection**
|
||||||
|
|
||||||
|
Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
|
||||||
|
|
||||||
|
Show only active changes (not already archived).
|
||||||
|
Include the schema used for each change if available.
|
||||||
|
|
||||||
|
**IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
|
||||||
|
|
||||||
|
2. **Check artifact completion status**
|
||||||
|
|
||||||
|
Run `openspec status --change "<name>" --json` to check artifact completion.
|
||||||
|
|
||||||
|
Parse the JSON to understand:
|
||||||
|
- `schemaName`: The workflow being used
|
||||||
|
- `artifacts`: List of artifacts with their status (`done` or other)
|
||||||
|
|
||||||
|
**If any artifacts are not `done`:**
|
||||||
|
- Display warning listing incomplete artifacts
|
||||||
|
- Use **AskUserQuestion tool** to confirm user wants to proceed
|
||||||
|
- Proceed if user confirms
|
||||||
|
|
||||||
|
3. **Check task completion status**
|
||||||
|
|
||||||
|
Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
|
||||||
|
|
||||||
|
Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
|
||||||
|
|
||||||
|
**If incomplete tasks found:**
|
||||||
|
- Display warning showing count of incomplete tasks
|
||||||
|
- Use **AskUserQuestion tool** to confirm user wants to proceed
|
||||||
|
- Proceed if user confirms
|
||||||
|
|
||||||
|
**If no tasks file exists:** Proceed without task-related warning.
|
||||||
|
|
||||||
|
4. **Assess delta spec sync state**
|
||||||
|
|
||||||
|
Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
|
||||||
|
|
||||||
|
**If delta specs exist:**
|
||||||
|
- Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
|
||||||
|
- Determine what changes would be applied (adds, modifications, removals, renames)
|
||||||
|
- Show a combined summary before prompting
|
||||||
|
|
||||||
|
**Prompt options:**
|
||||||
|
- If changes needed: "Sync now (recommended)", "Archive without syncing"
|
||||||
|
- If already synced: "Archive now", "Sync anyway", "Cancel"
|
||||||
|
|
||||||
|
If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
|
||||||
|
|
||||||
|
5. **Perform the archive**
|
||||||
|
|
||||||
|
Create the archive directory if it doesn't exist:
|
||||||
|
```bash
|
||||||
|
mkdir -p openspec/changes/archive
|
||||||
|
```
|
||||||
|
|
||||||
|
Generate target name using current date: `YYYY-MM-DD-<change-name>`
|
||||||
|
|
||||||
|
**Check if target already exists:**
|
||||||
|
- If yes: Fail with error, suggest renaming existing archive or using different date
|
||||||
|
- If no: Move the change directory to archive
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
|
||||||
|
```
|
||||||
|
|
||||||
|
6. **Display summary**
|
||||||
|
|
||||||
|
Show archive completion summary including:
|
||||||
|
- Change name
|
||||||
|
- Schema that was used
|
||||||
|
- Archive location
|
||||||
|
- Whether specs were synced (if applicable)
|
||||||
|
- Note about any warnings (incomplete artifacts/tasks)
|
||||||
|
|
||||||
|
**Output On Success**
|
||||||
|
|
||||||
|
```
|
||||||
|
## Archive Complete
|
||||||
|
|
||||||
|
**Change:** <change-name>
|
||||||
|
**Schema:** <schema-name>
|
||||||
|
**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
|
||||||
|
**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
|
||||||
|
|
||||||
|
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
|
||||||
|
- Preserve .openspec.yaml when moving to archive (it moves with the directory)
|
||||||
|
- Show clear summary of what happened
|
||||||
|
- If sync is requested, use openspec-sync-specs approach (agent-driven)
|
||||||
|
- If delta specs exist, always run the sync assessment and show the combined summary before prompting
|
||||||
288
.claude/skills/openspec-explore/SKILL.md
Normal file
288
.claude/skills/openspec-explore/SKILL.md
Normal file
|
|
@ -0,0 +1,288 @@
|
||||||
|
---
|
||||||
|
name: openspec-explore
|
||||||
|
description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
|
||||||
|
license: MIT
|
||||||
|
compatibility: Requires openspec CLI.
|
||||||
|
metadata:
|
||||||
|
author: openspec
|
||||||
|
version: "1.0"
|
||||||
|
generatedBy: "1.2.0"
|
||||||
|
---
|
||||||
|
|
||||||
|
Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
|
||||||
|
|
||||||
|
**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
|
||||||
|
|
||||||
|
**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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The Stance
|
||||||
|
|
||||||
|
- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
|
||||||
|
- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
|
||||||
|
- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
|
||||||
|
- **Adaptive** - Follow interesting threads, pivot when new information emerges
|
||||||
|
- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
|
||||||
|
- **Grounded** - Explore the actual codebase when relevant, don't just theorize
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What You Might Do
|
||||||
|
|
||||||
|
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 │
|
||||||
|
├─────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌────────┐ ┌────────┐ │
|
||||||
|
│ │ State │────────▶│ State │ │
|
||||||
|
│ │ A │ │ B │ │
|
||||||
|
│ └────────┘ └────────┘ │
|
||||||
|
│ │
|
||||||
|
│ System diagrams, state machines, │
|
||||||
|
│ data flows, architecture sketches, │
|
||||||
|
│ dependency graphs, comparison tables │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**Surface risks and unknowns**
|
||||||
|
- Identify what could go wrong
|
||||||
|
- Find gaps in understanding
|
||||||
|
- Suggest spikes or investigations
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## OpenSpec Awareness
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
### When no change exists
|
||||||
|
|
||||||
|
Think freely. When insights crystallize, you might offer:
|
||||||
|
|
||||||
|
- "This feels solid enough to start a change. Want me to create a proposal?"
|
||||||
|
- Or keep exploring - no pressure to formalize
|
||||||
|
|
||||||
|
### When a change exists
|
||||||
|
|
||||||
|
If the user mentions a change or you detect one is relevant:
|
||||||
|
|
||||||
|
1. **Read existing artifacts for context**
|
||||||
|
- `openspec/changes/<name>/proposal.md`
|
||||||
|
- `openspec/changes/<name>/design.md`
|
||||||
|
- `openspec/changes/<name>/tasks.md`
|
||||||
|
- etc.
|
||||||
|
|
||||||
|
2. **Reference them naturally in conversation**
|
||||||
|
- "Your design mentions using Redis, but we just realized SQLite fits better..."
|
||||||
|
- "The proposal scopes this to premium users, but we're now thinking everyone..."
|
||||||
|
|
||||||
|
3. **Offer to capture when decisions are made**
|
||||||
|
|
||||||
|
| 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 |
|
||||||
|
|
||||||
|
Example offers:
|
||||||
|
- "That's a design decision. Capture it in design.md?"
|
||||||
|
- "This is a new requirement. Add it to specs?"
|
||||||
|
- "This changes scope. Update the proposal?"
|
||||||
|
|
||||||
|
4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What You Don't Have To Do
|
||||||
|
|
||||||
|
- Follow a script
|
||||||
|
- Ask the same questions every time
|
||||||
|
- Produce a specific artifact
|
||||||
|
- Reach a conclusion
|
||||||
|
- Stay on topic if a tangent is valuable
|
||||||
|
- Be brief (this is thinking time)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Handling Different Entry Points
|
||||||
|
|
||||||
|
**User brings a vague idea:**
|
||||||
|
```
|
||||||
|
User: I'm thinking about adding real-time collaboration
|
||||||
|
|
||||||
|
You: Real-time collab is a big space. Let me think about this...
|
||||||
|
|
||||||
|
COLLABORATION SPECTRUM
|
||||||
|
════════════════════════════════════════════
|
||||||
|
|
||||||
|
Awareness Coordination Sync
|
||||||
|
│ │ │
|
||||||
|
▼ ▼ ▼
|
||||||
|
┌────────┐ ┌────────┐ ┌────────┐
|
||||||
|
│Presence│ │Cursors │ │ CRDT │
|
||||||
|
│ "3 │ │ Multi │ │Conflict│
|
||||||
|
│online" │ │ select │ │ free │
|
||||||
|
└────────┘ └────────┘ └────────┘
|
||||||
|
│ │ │
|
||||||
|
trivial moderate complex
|
||||||
|
|
||||||
|
Where's your head at?
|
||||||
|
```
|
||||||
|
|
||||||
|
**User brings a specific problem:**
|
||||||
|
```
|
||||||
|
User: The auth system is a mess
|
||||||
|
|
||||||
|
You: [reads codebase]
|
||||||
|
|
||||||
|
┌─────────────────────────────────────────────┐
|
||||||
|
│ CURRENT AUTH FLOW │
|
||||||
|
└─────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌─────────────┼─────────────┐
|
||||||
|
▼ ▼ ▼
|
||||||
|
┌─────────┐ ┌─────────┐ ┌─────────┐
|
||||||
|
│ Google │ │ GitHub │ │ Email │
|
||||||
|
│ OAuth │ │ OAuth │ │ Magic │
|
||||||
|
└────┬────┘ └────┬────┘ └────┬────┘
|
||||||
|
│ │ │
|
||||||
|
└─────────────┼─────────────┘
|
||||||
|
▼
|
||||||
|
┌───────────┐
|
||||||
|
│ Session │
|
||||||
|
└─────┬─────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌───────────┐
|
||||||
|
│ Perms │
|
||||||
|
└───────────┘
|
||||||
|
|
||||||
|
I see three tangles. Which one's burning?
|
||||||
|
```
|
||||||
|
|
||||||
|
**User is stuck mid-implementation:**
|
||||||
|
```
|
||||||
|
User: /opsx:explore add-auth-system
|
||||||
|
The OAuth integration is more complex than expected
|
||||||
|
|
||||||
|
You: [reads change artifacts]
|
||||||
|
|
||||||
|
You're on task 4: "Implement OAuth flow"
|
||||||
|
|
||||||
|
Let me trace what's involved...
|
||||||
|
|
||||||
|
[draws diagram, explores options, suggests paths]
|
||||||
|
|
||||||
|
Want to update the design to reflect this?
|
||||||
|
Or add a spike task to investigate?
|
||||||
|
```
|
||||||
|
|
||||||
|
**User wants to compare options:**
|
||||||
|
```
|
||||||
|
User: Should we use Postgres or SQLite?
|
||||||
|
|
||||||
|
You: Generic answer is boring. What's the context?
|
||||||
|
|
||||||
|
User: A CLI tool that tracks local dev environments
|
||||||
|
|
||||||
|
You: That changes everything.
|
||||||
|
|
||||||
|
┌─────────────────────────────────────────────────┐
|
||||||
|
│ CLI TOOL DATA STORAGE │
|
||||||
|
└─────────────────────────────────────────────────┘
|
||||||
|
|
||||||
|
Key constraints:
|
||||||
|
• No daemon running
|
||||||
|
• Must work offline
|
||||||
|
• Single user
|
||||||
|
|
||||||
|
SQLite Postgres
|
||||||
|
Deployment embedded ✓ needs server ✗
|
||||||
|
Offline yes ✓ no ✗
|
||||||
|
Single file yes ✓ no ✗
|
||||||
|
|
||||||
|
SQLite. Not even close.
|
||||||
|
|
||||||
|
Unless... is there a sync component?
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ending Discovery
|
||||||
|
|
||||||
|
There's no required ending. Discovery might:
|
||||||
|
|
||||||
|
- **Flow into a proposal**: "Ready to start? I can create a change proposal."
|
||||||
|
- **Result in artifact updates**: "Updated design.md with these decisions"
|
||||||
|
- **Just provide clarity**: User has what they need, moves on
|
||||||
|
- **Continue later**: "We can pick this up anytime"
|
||||||
|
|
||||||
|
When it feels like things are crystallizing, you might summarize:
|
||||||
|
|
||||||
|
```
|
||||||
|
## What We Figured Out
|
||||||
|
|
||||||
|
**The problem**: [crystallized understanding]
|
||||||
|
|
||||||
|
**The approach**: [if one emerged]
|
||||||
|
|
||||||
|
**Open questions**: [if any remain]
|
||||||
|
|
||||||
|
**Next steps** (if ready):
|
||||||
|
- Create a change proposal
|
||||||
|
- Keep exploring: just keep talking
|
||||||
|
```
|
||||||
|
|
||||||
|
But this summary is optional. Sometimes the thinking IS the value.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Guardrails
|
||||||
|
|
||||||
|
- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
|
||||||
|
- **Don't fake understanding** - If something is unclear, dig deeper
|
||||||
|
- **Don't rush** - Discovery is thinking time, not task time
|
||||||
|
- **Don't force structure** - Let patterns emerge naturally
|
||||||
|
- **Don't auto-capture** - Offer to save insights, don't just do it
|
||||||
|
- **Do visualize** - A good diagram is worth many paragraphs
|
||||||
|
- **Do explore the codebase** - Ground discussions in reality
|
||||||
|
- **Do question assumptions** - Including the user's and your own
|
||||||
110
.claude/skills/openspec-propose/SKILL.md
Normal file
110
.claude/skills/openspec-propose/SKILL.md
Normal file
|
|
@ -0,0 +1,110 @@
|
||||||
|
---
|
||||||
|
name: openspec-propose
|
||||||
|
description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
|
||||||
|
license: MIT
|
||||||
|
compatibility: Requires openspec CLI.
|
||||||
|
metadata:
|
||||||
|
author: openspec
|
||||||
|
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)
|
||||||
|
|
||||||
|
When ready to implement, run /opsx:apply
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
|
||||||
|
|
||||||
|
**Steps**
|
||||||
|
|
||||||
|
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`).
|
||||||
|
|
||||||
|
**IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
|
||||||
|
|
||||||
|
2. **Create the change directory**
|
||||||
|
```bash
|
||||||
|
openspec new change "<name>"
|
||||||
|
```
|
||||||
|
This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
|
||||||
|
|
||||||
|
3. **Get the artifact build order**
|
||||||
|
```bash
|
||||||
|
openspec status --change "<name>" --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
|
||||||
|
|
||||||
|
4. **Create artifacts in sequence until apply-ready**
|
||||||
|
|
||||||
|
Use the **TodoWrite tool** to track progress through the artifacts.
|
||||||
|
|
||||||
|
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 <artifact-id> --change "<name>" --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 <artifact-id>"
|
||||||
|
|
||||||
|
b. **Continue until all `applyRequires` artifacts are complete**
|
||||||
|
- After creating each artifact, re-run `openspec status --change "<name>" --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
|
||||||
|
|
||||||
|
5. **Show final status**
|
||||||
|
```bash
|
||||||
|
openspec status --change "<name>"
|
||||||
|
```
|
||||||
|
|
||||||
|
**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."
|
||||||
|
- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
|
||||||
|
|
||||||
|
**Artifact Creation Guidelines**
|
||||||
|
|
||||||
|
- Follow the `instruction` field from `openspec instructions` for each artifact type
|
||||||
|
- The schema defines what each artifact should contain - follow it
|
||||||
|
- Read dependency artifacts for context before creating new ones
|
||||||
|
- Use `template` as the structure for your output file - fill in its sections
|
||||||
|
- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
|
||||||
|
- Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
|
||||||
|
- 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
|
||||||
|
- If a change with that name already exists, ask if user wants to continue it or create a new one
|
||||||
|
- Verify each artifact file exists after writing before proceeding to next
|
||||||
2
openspec/changes/phase-1-mvp/.openspec.yaml
Normal file
2
openspec/changes/phase-1-mvp/.openspec.yaml
Normal file
|
|
@ -0,0 +1,2 @@
|
||||||
|
schema: spec-driven
|
||||||
|
created: 2026-03-22
|
||||||
130
openspec/changes/phase-1-mvp/design.md
Normal file
130
openspec/changes/phase-1-mvp/design.md
Normal file
|
|
@ -0,0 +1,130 @@
|
||||||
|
## Context
|
||||||
|
|
||||||
|
trails.cool is a new platform with two apps: a collaborative route Planner and
|
||||||
|
a federated activity Journal. The full architecture is documented in
|
||||||
|
docs/architecture.md with 19 resolved design decisions. Phase 1 builds the
|
||||||
|
foundation — both apps with minimal features, shared packages, and deployment
|
||||||
|
infrastructure.
|
||||||
|
|
||||||
|
The Planner is stateless and ephemeral — it runs collaborative editing sessions
|
||||||
|
via Yjs and computes routes via BRouter. The Journal is stateful — it stores
|
||||||
|
user accounts, routes, and activities in PostgreSQL with PostGIS.
|
||||||
|
|
||||||
|
Both apps share a TypeScript/React stack (React Router 7, Tailwind) and are
|
||||||
|
deployed to a single Hetzner CX21 server via Docker Compose.
|
||||||
|
|
||||||
|
## Goals / Non-Goals
|
||||||
|
|
||||||
|
**Goals:**
|
||||||
|
- Working Planner with collaborative waypoint editing and BRouter route computation
|
||||||
|
- Working Journal with user accounts, route CRUD, and activity feed
|
||||||
|
- Seamless handoff between Journal and Planner (open route in Planner, save back)
|
||||||
|
- Shared packages for types, UI components, map rendering, GPX parsing, i18n
|
||||||
|
- Deployable to Hetzner via Terraform + Docker Compose
|
||||||
|
- Germany map coverage (~750 MB RD5 segments)
|
||||||
|
|
||||||
|
**Non-Goals:**
|
||||||
|
- ActivityPub federation (Phase 2)
|
||||||
|
- Following/followers, likes, comments (Phase 2)
|
||||||
|
- Photo attachments (Phase 2)
|
||||||
|
- Route sharing permissions beyond basic CRUD (Phase 2)
|
||||||
|
- Mobile app or offline support (Phase 3)
|
||||||
|
- Multi-day route planning UI (Phase 3)
|
||||||
|
- WASM compilation of BRouter (Phase 3)
|
||||||
|
- Monitoring stack (Grafana/Prometheus — add when needed)
|
||||||
|
|
||||||
|
## Decisions
|
||||||
|
|
||||||
|
### D1: React Router 7 for both apps
|
||||||
|
|
||||||
|
Both Planner and Journal use React Router 7 (Remix stack) as their full-stack
|
||||||
|
framework. This gives SSR for Journal (SEO, initial load), API routes, and
|
||||||
|
loader/action patterns.
|
||||||
|
|
||||||
|
**Alternative considered**: Separate frameworks (e.g., Next.js for Journal, Vite
|
||||||
|
SPA for Planner). Rejected because maintaining two frameworks doubles learning
|
||||||
|
curve and prevents sharing server-side code patterns.
|
||||||
|
|
||||||
|
### D2: BRouter wrapped as HTTP proxy in Planner backend
|
||||||
|
|
||||||
|
The Planner's React Router 7 server proxies BRouter API calls. Clients never
|
||||||
|
talk to BRouter directly. This allows rate limiting, request validation, and
|
||||||
|
later caching at the proxy layer.
|
||||||
|
|
||||||
|
**Alternative considered**: Expose BRouter directly. Rejected because BRouter
|
||||||
|
has no built-in auth, rate limiting, or CORS support.
|
||||||
|
|
||||||
|
### D3: Yjs with y-websocket for CRDT sync
|
||||||
|
|
||||||
|
Use y-websocket for the Planner's real-time sync. The WebSocket server runs
|
||||||
|
as part of the Planner's Node.js process (not a separate service). Yjs documents
|
||||||
|
are persisted to PostgreSQL for crash recovery.
|
||||||
|
|
||||||
|
**Alternative considered**: Separate y-websocket service. Rejected for Phase 1
|
||||||
|
simplicity — one process is easier to deploy and debug. Can extract later.
|
||||||
|
|
||||||
|
### D4: PostgreSQL shared instance, separate schemas
|
||||||
|
|
||||||
|
One PostgreSQL instance with two schemas:
|
||||||
|
- `planner` — Yjs session documents, session metadata
|
||||||
|
- `journal` — users, routes, activities, media references
|
||||||
|
|
||||||
|
**Alternative considered**: Separate PostgreSQL instances. Rejected — unnecessary
|
||||||
|
overhead for 100 users. Single instance is simpler to backup and manage.
|
||||||
|
|
||||||
|
### D5: Routing host election via Yjs awareness
|
||||||
|
|
||||||
|
Only one client per session talks to BRouter (the "routing host"). The host is
|
||||||
|
the session initiator; on disconnect, the longest-connected client takes over.
|
||||||
|
This avoids redundant BRouter API calls.
|
||||||
|
|
||||||
|
**Alternative considered**: Server-side route computation (Planner backend
|
||||||
|
watches Yjs changes and computes routes). Better long-term but more complex.
|
||||||
|
Client-side host election is simpler for Phase 1.
|
||||||
|
|
||||||
|
### D6: Scoped JWT for Planner-Journal callback
|
||||||
|
|
||||||
|
When the Journal opens a Planner session, it generates a scoped JWT token
|
||||||
|
embedded in the callback URL. The Planner sends this JWT when saving GPX back.
|
||||||
|
The Journal validates the JWT signature to authorize the write.
|
||||||
|
|
||||||
|
**Alternative considered**: Session cookies / OAuth flow. Rejected — the Planner
|
||||||
|
is stateless and doesn't have access to the Journal's session.
|
||||||
|
|
||||||
|
### D7: Leaflet with plugin-based layers
|
||||||
|
|
||||||
|
Leaflet (not Mapbox GL) for map rendering. Leaflet is lighter, has no API key
|
||||||
|
requirement, and has mature plugin ecosystem for OSM tiles.
|
||||||
|
|
||||||
|
**Alternative considered**: Mapbox GL JS. Rejected — requires API key, larger
|
||||||
|
bundle, and commercial license for heavy usage.
|
||||||
|
|
||||||
|
### D8: pnpm + Turborepo for monorepo
|
||||||
|
|
||||||
|
pnpm workspaces for dependency management, Turborepo for build orchestration
|
||||||
|
and caching. This is the standard monorepo toolchain for TypeScript projects.
|
||||||
|
|
||||||
|
**Alternative considered**: Nx. Rejected — heavier setup, more opinionated.
|
||||||
|
Turborepo is simpler and sufficient for our needs.
|
||||||
|
|
||||||
|
## Risks / Trade-offs
|
||||||
|
|
||||||
|
**[BRouter Java dependency]** → The Planner requires a JVM to run BRouter.
|
||||||
|
This adds Docker image size (~200 MB) and memory usage (~128 MB heap).
|
||||||
|
Mitigation: BRouter runs in its own container with constrained resources.
|
||||||
|
|
||||||
|
**[Yjs document size growth]** → Long editing sessions could grow Yjs documents.
|
||||||
|
Mitigation: Monitor document sizes in PostgreSQL. Add compaction if needed.
|
||||||
|
|
||||||
|
**[Single server SPOF]** → All services on one Hetzner CX21.
|
||||||
|
Mitigation: Acceptable for 100 users. Daily backups to Hetzner Storage Box.
|
||||||
|
Scale to multiple servers in Phase 2 if needed.
|
||||||
|
|
||||||
|
**[BRouter segment freshness]** → RD5 segments are updated weekly on brouter.de.
|
||||||
|
Stale data could cause routing on newly built roads to fail.
|
||||||
|
Mitigation: Weekly cron job to download updated segments.
|
||||||
|
|
||||||
|
**[Cross-origin Planner-Journal integration]** → Planner and Journal are on
|
||||||
|
different subdomains (planner.trails.cool vs trails.cool). Cookie sharing
|
||||||
|
won't work.
|
||||||
|
Mitigation: JWT-based callback (Decision D6). No cookies needed.
|
||||||
43
openspec/changes/phase-1-mvp/proposal.md
Normal file
43
openspec/changes/phase-1-mvp/proposal.md
Normal file
|
|
@ -0,0 +1,43 @@
|
||||||
|
## Why
|
||||||
|
|
||||||
|
trails.cool needs its foundation: a working Planner for collaborative route
|
||||||
|
editing and a Journal for managing routes and activities. Without Phase 1,
|
||||||
|
nothing can be tested or shown to users. The architecture plan is finalized
|
||||||
|
(see docs/architecture.md) — now we need a working MVP to validate the
|
||||||
|
product-market fit with 100 European users, primarily in Germany.
|
||||||
|
|
||||||
|
## What Changes
|
||||||
|
|
||||||
|
- Set up the monorepo build toolchain (Turborepo, pnpm, TypeScript, React Router 7, Tailwind)
|
||||||
|
- Build the Planner app: real-time collaborative route editing via Yjs, BRouter integration for route computation, Leaflet map with OSM tiles, session sharing via link, GPX export
|
||||||
|
- Build the Journal app: user accounts, route CRUD, start Planner sessions from routes via callback, GPX import/export, basic profile page, activity feed
|
||||||
|
- Deploy BRouter as a Docker service with Germany RD5 segments (~750 MB)
|
||||||
|
- Set up infrastructure as code (Terraform + Docker Compose) for Hetzner Cloud
|
||||||
|
- Establish shared packages: types, UI components, map utilities, GPX parsing, i18n
|
||||||
|
|
||||||
|
## Capabilities
|
||||||
|
|
||||||
|
### New Capabilities
|
||||||
|
|
||||||
|
- `planner-session`: Collaborative route editing sessions with Yjs CRDTs, shareable links, guest access, session lifecycle (create, join, save, close, expire)
|
||||||
|
- `brouter-integration`: BRouter HTTP API wrapper, routing host election, route computation from waypoints, profile selection (bike/hike)
|
||||||
|
- `map-display`: Leaflet map with OSM/OpenTopoMap/CyclOSM base layers, waypoint editing, route visualization, elevation profile display
|
||||||
|
- `journal-auth`: User accounts with federated identity structure (@user@instance), registration, login, profile pages
|
||||||
|
- `route-management`: Route CRUD, GPX import/export, route metadata envelope, PostGIS spatial storage, route versioning (sequential)
|
||||||
|
- `planner-journal-handoff`: Callback-based integration between Journal and Planner — open Planner from route, save GPX back via scoped JWT token
|
||||||
|
- `activity-feed`: Activity CRUD, activity feed (own activities), link activities to routes (1:N blueprint model)
|
||||||
|
- `shared-packages`: Monorepo shared packages — @trails-cool/types, @trails-cool/ui, @trails-cool/map, @trails-cool/gpx, @trails-cool/i18n
|
||||||
|
- `infrastructure`: Terraform for Hetzner Cloud, Docker Compose for services, CI/CD via GitHub Actions
|
||||||
|
|
||||||
|
### Modified Capabilities
|
||||||
|
|
||||||
|
(None — this is the initial build, no existing capabilities to modify.)
|
||||||
|
|
||||||
|
## Impact
|
||||||
|
|
||||||
|
- **New apps**: `apps/planner` and `apps/journal` (React Router 7)
|
||||||
|
- **New packages**: `packages/types`, `packages/ui`, `packages/map`, `packages/gpx`, `packages/i18n`
|
||||||
|
- **Infrastructure**: Hetzner CX21 server, PostgreSQL + PostGIS, Garage (S3), BRouter Docker container
|
||||||
|
- **External dependencies**: React Router 7, Yjs, Leaflet, Fedify (stub for Phase 1), BRouter (Java), Tailwind CSS, react-i18next
|
||||||
|
- **Data**: Germany RD5 segments from brouter.de (~750 MB), PostgreSQL schemas (planner.*, activity.*)
|
||||||
|
- **Domains**: trails.cool (Journal), planner.trails.cool (Planner)
|
||||||
44
openspec/changes/phase-1-mvp/specs/activity-feed/spec.md
Normal file
44
openspec/changes/phase-1-mvp/specs/activity-feed/spec.md
Normal file
|
|
@ -0,0 +1,44 @@
|
||||||
|
## ADDED Requirements
|
||||||
|
|
||||||
|
### Requirement: Create activity
|
||||||
|
The Journal SHALL allow authenticated users to create an activity by uploading a GPX trace and adding a description.
|
||||||
|
|
||||||
|
#### Scenario: Create activity with GPX
|
||||||
|
- **WHEN** a user uploads a GPX file and enters a description
|
||||||
|
- **THEN** an activity is created with the GPS trace, computed distance and duration, and stored in the database
|
||||||
|
|
||||||
|
#### Scenario: Create activity linked to route
|
||||||
|
- **WHEN** a user creates an activity and selects an existing route
|
||||||
|
- **THEN** the activity is linked to that route (route_id foreign key)
|
||||||
|
|
||||||
|
### Requirement: Activity feed
|
||||||
|
The Journal SHALL display a chronological feed of the authenticated user's activities.
|
||||||
|
|
||||||
|
#### Scenario: View own activity feed
|
||||||
|
- **WHEN** a logged-in user navigates to their feed
|
||||||
|
- **THEN** they see their activities in reverse chronological order with name, date, distance, and duration
|
||||||
|
|
||||||
|
### Requirement: Activity detail page
|
||||||
|
The Journal SHALL display an activity detail page with map, stats, and description.
|
||||||
|
|
||||||
|
#### Scenario: View activity detail
|
||||||
|
- **WHEN** a user navigates to an activity URL
|
||||||
|
- **THEN** they see the activity name, description, a map with the GPS trace, distance, duration, and elevation stats
|
||||||
|
|
||||||
|
### Requirement: Link activity to route
|
||||||
|
Users SHALL be able to link an existing activity to a route, or create a route from an activity trace.
|
||||||
|
|
||||||
|
#### Scenario: Link activity to existing route
|
||||||
|
- **WHEN** a user selects "Link to Route" on an activity and chooses a route
|
||||||
|
- **THEN** the activity's route_id is set to the selected route
|
||||||
|
|
||||||
|
#### Scenario: Create route from activity
|
||||||
|
- **WHEN** a user selects "Create Route from Activity"
|
||||||
|
- **THEN** a new route is created using the activity's GPX trace
|
||||||
|
|
||||||
|
### Requirement: Activity without route
|
||||||
|
Activities SHALL be allowed to exist without a linked route.
|
||||||
|
|
||||||
|
#### Scenario: Standalone activity
|
||||||
|
- **WHEN** a user imports a GPX activity without linking to a route
|
||||||
|
- **THEN** the activity is stored with route_id as null
|
||||||
|
|
@ -0,0 +1,58 @@
|
||||||
|
## ADDED Requirements
|
||||||
|
|
||||||
|
### Requirement: Route computation from waypoints
|
||||||
|
The Planner SHALL compute a route between ordered waypoints by calling the BRouter HTTP API and returning the result as GeoJSON.
|
||||||
|
|
||||||
|
#### Scenario: Compute route with two waypoints
|
||||||
|
- **WHEN** the routing host submits two waypoints (start, end) with profile "trekking"
|
||||||
|
- **THEN** the BRouter API returns a GeoJSON route within 2 seconds
|
||||||
|
|
||||||
|
#### Scenario: Compute route with via points
|
||||||
|
- **WHEN** the routing host submits three or more waypoints
|
||||||
|
- **THEN** the BRouter API returns a route passing through all waypoints in order
|
||||||
|
|
||||||
|
### Requirement: Routing host election
|
||||||
|
The Planner SHALL elect one participant per session as the "routing host" who is responsible for sending waypoint changes to BRouter. Only the host SHALL make BRouter API calls.
|
||||||
|
|
||||||
|
#### Scenario: Initial host assignment
|
||||||
|
- **WHEN** a session is created
|
||||||
|
- **THEN** the session creator is assigned as the routing host via Yjs awareness state
|
||||||
|
|
||||||
|
#### Scenario: Host failover
|
||||||
|
- **WHEN** the current routing host disconnects
|
||||||
|
- **THEN** the longest-connected remaining participant becomes the new host within 5 seconds
|
||||||
|
|
||||||
|
### Requirement: Route broadcast
|
||||||
|
The routing host SHALL store computed route results in the Yjs document so that all participants receive route updates automatically.
|
||||||
|
|
||||||
|
#### Scenario: Route update propagation
|
||||||
|
- **WHEN** the routing host receives a new route from BRouter
|
||||||
|
- **THEN** the route GeoJSON is stored in a Y.Map field and all participants see the updated route on their maps
|
||||||
|
|
||||||
|
### Requirement: Profile selection
|
||||||
|
The Planner SHALL support selecting a routing profile that determines how BRouter computes the route.
|
||||||
|
|
||||||
|
#### Scenario: Switch routing profile
|
||||||
|
- **WHEN** a user changes the routing profile from "trekking" to "shortest"
|
||||||
|
- **THEN** the profile change syncs via Yjs and the routing host recomputes the route
|
||||||
|
|
||||||
|
### Requirement: BRouter API proxy
|
||||||
|
The Planner backend SHALL proxy all BRouter API calls. Clients SHALL NOT communicate with BRouter directly.
|
||||||
|
|
||||||
|
#### Scenario: Proxied route request
|
||||||
|
- **WHEN** the routing host client requests a route computation
|
||||||
|
- **THEN** the Planner backend forwards the request to BRouter, applies rate limiting, and returns the response
|
||||||
|
|
||||||
|
### Requirement: Rate limiting
|
||||||
|
The Planner backend SHALL rate limit BRouter API calls to prevent abuse.
|
||||||
|
|
||||||
|
#### Scenario: Rate limit exceeded
|
||||||
|
- **WHEN** a session exceeds 60 route computations per hour
|
||||||
|
- **THEN** subsequent requests receive a 429 response with a Retry-After header
|
||||||
|
|
||||||
|
### Requirement: BRouter Docker deployment
|
||||||
|
BRouter SHALL run as a separate Docker container with Germany RD5 segments mounted as a volume.
|
||||||
|
|
||||||
|
#### Scenario: BRouter container starts
|
||||||
|
- **WHEN** the Docker Compose stack starts
|
||||||
|
- **THEN** the BRouter container is reachable at its internal HTTP port and can compute routes using the mounted RD5 segments
|
||||||
65
openspec/changes/phase-1-mvp/specs/infrastructure/spec.md
Normal file
65
openspec/changes/phase-1-mvp/specs/infrastructure/spec.md
Normal file
|
|
@ -0,0 +1,65 @@
|
||||||
|
## ADDED Requirements
|
||||||
|
|
||||||
|
### Requirement: Terraform Hetzner provisioning
|
||||||
|
Infrastructure SHALL be provisioned on Hetzner Cloud using Terraform with the Hetzner provider.
|
||||||
|
|
||||||
|
#### Scenario: Provision server
|
||||||
|
- **WHEN** `terraform apply` is run
|
||||||
|
- **THEN** a Hetzner CX21 server (2 vCPU, 4 GB RAM, 40 GB SSD) is created with Docker installed
|
||||||
|
|
||||||
|
### Requirement: Docker Compose deployment
|
||||||
|
All services SHALL be deployed via Docker Compose on the Hetzner server.
|
||||||
|
|
||||||
|
#### Scenario: Start all services
|
||||||
|
- **WHEN** `docker compose up -d` is run on the server
|
||||||
|
- **THEN** the Journal, Planner, BRouter, PostgreSQL, and Garage containers start and are reachable
|
||||||
|
|
||||||
|
### Requirement: Service configuration
|
||||||
|
Each service SHALL be configured via environment variables defined in Docker Compose.
|
||||||
|
|
||||||
|
#### Scenario: Journal configuration
|
||||||
|
- **WHEN** the Journal container starts
|
||||||
|
- **THEN** it reads DOMAIN, DATABASE_URL, PLANNER_URL, S3_ENDPOINT, and S3_BUCKET from environment variables
|
||||||
|
|
||||||
|
#### Scenario: Planner configuration
|
||||||
|
- **WHEN** the Planner container starts
|
||||||
|
- **THEN** it reads BROUTER_URL and DATABASE_URL from environment variables
|
||||||
|
|
||||||
|
### Requirement: PostgreSQL with PostGIS
|
||||||
|
The database SHALL be PostgreSQL with the PostGIS extension for spatial queries.
|
||||||
|
|
||||||
|
#### Scenario: PostGIS available
|
||||||
|
- **WHEN** the PostgreSQL container starts
|
||||||
|
- **THEN** the PostGIS extension is available and can be enabled with `CREATE EXTENSION postgis`
|
||||||
|
|
||||||
|
### Requirement: BRouter segment management
|
||||||
|
The infrastructure SHALL support downloading and updating Germany RD5 segments from brouter.de.
|
||||||
|
|
||||||
|
#### Scenario: Download segments
|
||||||
|
- **WHEN** the segment download script is run
|
||||||
|
- **THEN** Germany RD5 files (E5_N45, E5_N50, E10_N45, E10_N50) are downloaded to the segments volume
|
||||||
|
|
||||||
|
#### Scenario: Weekly segment update
|
||||||
|
- **WHEN** the weekly cron job runs
|
||||||
|
- **THEN** RD5 segments are updated from brouter.de and the BRouter container is restarted
|
||||||
|
|
||||||
|
### Requirement: CI/CD pipeline
|
||||||
|
GitHub Actions SHALL build and deploy both apps on push to main.
|
||||||
|
|
||||||
|
#### Scenario: Push triggers deployment
|
||||||
|
- **WHEN** code is pushed to the main branch
|
||||||
|
- **THEN** GitHub Actions builds Docker images, pushes to ghcr.io/trails-cool/, and deploys to the Hetzner server
|
||||||
|
|
||||||
|
### Requirement: Backup strategy
|
||||||
|
The infrastructure SHALL include daily backups of the PostgreSQL database.
|
||||||
|
|
||||||
|
#### Scenario: Daily backup
|
||||||
|
- **WHEN** the daily backup cron runs
|
||||||
|
- **THEN** a PostgreSQL dump is uploaded to the Hetzner Storage Box
|
||||||
|
|
||||||
|
### Requirement: Domain and TLS
|
||||||
|
The infrastructure SHALL configure DNS and TLS for trails.cool and planner.trails.cool.
|
||||||
|
|
||||||
|
#### Scenario: HTTPS access
|
||||||
|
- **WHEN** a user navigates to https://trails.cool
|
||||||
|
- **THEN** the connection is secured with a valid TLS certificate
|
||||||
52
openspec/changes/phase-1-mvp/specs/journal-auth/spec.md
Normal file
52
openspec/changes/phase-1-mvp/specs/journal-auth/spec.md
Normal file
|
|
@ -0,0 +1,52 @@
|
||||||
|
## ADDED Requirements
|
||||||
|
|
||||||
|
### Requirement: User registration
|
||||||
|
The Journal SHALL allow new users to create an account with email and password.
|
||||||
|
|
||||||
|
#### Scenario: Successful registration
|
||||||
|
- **WHEN** a user submits a valid email and password on the registration page
|
||||||
|
- **THEN** a new user account is created and the user is logged in
|
||||||
|
|
||||||
|
#### Scenario: Duplicate email
|
||||||
|
- **WHEN** a user submits an email that is already registered
|
||||||
|
- **THEN** the system displays an error indicating the email is already in use
|
||||||
|
|
||||||
|
### Requirement: User login
|
||||||
|
The Journal SHALL allow existing users to log in with email and password.
|
||||||
|
|
||||||
|
#### Scenario: Successful login
|
||||||
|
- **WHEN** a user submits valid credentials
|
||||||
|
- **THEN** the user is authenticated and redirected to their activity feed
|
||||||
|
|
||||||
|
#### Scenario: Invalid credentials
|
||||||
|
- **WHEN** a user submits invalid credentials
|
||||||
|
- **THEN** the system displays an error without revealing which field is wrong
|
||||||
|
|
||||||
|
### Requirement: User profile page
|
||||||
|
Each user SHALL have a public profile page displaying their username and routes.
|
||||||
|
|
||||||
|
#### Scenario: View own profile
|
||||||
|
- **WHEN** a logged-in user navigates to their profile
|
||||||
|
- **THEN** they see their username, bio, and a list of their routes
|
||||||
|
|
||||||
|
#### Scenario: View other user's profile
|
||||||
|
- **WHEN** a user navigates to another user's profile URL
|
||||||
|
- **THEN** they see that user's username, bio, and public routes
|
||||||
|
|
||||||
|
### Requirement: Federated identity structure
|
||||||
|
User accounts SHALL follow the federated identity pattern (`@user@instance`) to prepare for ActivityPub federation in Phase 2.
|
||||||
|
|
||||||
|
#### Scenario: Username format
|
||||||
|
- **WHEN** a user registers with username "alice" on trails.cool
|
||||||
|
- **THEN** their full identity is stored as `@alice@trails.cool`
|
||||||
|
|
||||||
|
### Requirement: Session management
|
||||||
|
The Journal SHALL maintain authenticated sessions using secure HTTP-only cookies.
|
||||||
|
|
||||||
|
#### Scenario: Session persistence
|
||||||
|
- **WHEN** a logged-in user closes and reopens their browser
|
||||||
|
- **THEN** they remain logged in if the session has not expired
|
||||||
|
|
||||||
|
#### Scenario: Logout
|
||||||
|
- **WHEN** a user clicks "Log out"
|
||||||
|
- **THEN** their session is invalidated and they are redirected to the login page
|
||||||
52
openspec/changes/phase-1-mvp/specs/map-display/spec.md
Normal file
52
openspec/changes/phase-1-mvp/specs/map-display/spec.md
Normal file
|
|
@ -0,0 +1,52 @@
|
||||||
|
## ADDED Requirements
|
||||||
|
|
||||||
|
### Requirement: Map rendering with OSM tiles
|
||||||
|
The Planner and Journal SHALL render interactive maps using Leaflet with OpenStreetMap tiles as the default base layer.
|
||||||
|
|
||||||
|
#### Scenario: Default map view
|
||||||
|
- **WHEN** a user opens the Planner or a route view in the Journal
|
||||||
|
- **THEN** an interactive map is displayed with OpenStreetMap tiles centered on the route or a default location (Germany)
|
||||||
|
|
||||||
|
### Requirement: Base layer switching
|
||||||
|
The map SHALL support switching between multiple base tile layers.
|
||||||
|
|
||||||
|
#### Scenario: Switch to OpenTopoMap
|
||||||
|
- **WHEN** a user selects "OpenTopoMap" from the layer switcher
|
||||||
|
- **THEN** the map tiles change to topographic tiles from OpenTopoMap
|
||||||
|
|
||||||
|
#### Scenario: Available base layers
|
||||||
|
- **WHEN** a user opens the layer switcher
|
||||||
|
- **THEN** the options include OpenStreetMap, OpenTopoMap, and CyclOSM
|
||||||
|
|
||||||
|
### Requirement: Waypoint editing on map
|
||||||
|
The Planner map SHALL allow users to add, move, and delete waypoints by interacting with the map.
|
||||||
|
|
||||||
|
#### Scenario: Add waypoint by clicking
|
||||||
|
- **WHEN** a user clicks on the map
|
||||||
|
- **THEN** a new waypoint is added at the clicked location and synced via Yjs
|
||||||
|
|
||||||
|
#### Scenario: Move waypoint by dragging
|
||||||
|
- **WHEN** a user drags an existing waypoint marker
|
||||||
|
- **THEN** the waypoint coordinates update and sync via Yjs
|
||||||
|
|
||||||
|
#### Scenario: Delete waypoint
|
||||||
|
- **WHEN** a user right-clicks a waypoint and selects "Delete"
|
||||||
|
- **THEN** the waypoint is removed and the change syncs via Yjs
|
||||||
|
|
||||||
|
### Requirement: Route visualization
|
||||||
|
The map SHALL display the computed route as a polyline on the map.
|
||||||
|
|
||||||
|
#### Scenario: Display route
|
||||||
|
- **WHEN** BRouter returns a route GeoJSON
|
||||||
|
- **THEN** the route is rendered as a colored polyline on the map
|
||||||
|
|
||||||
|
#### Scenario: Route updates on waypoint change
|
||||||
|
- **WHEN** a waypoint is added, moved, or deleted
|
||||||
|
- **THEN** the route polyline updates after BRouter recomputes the route
|
||||||
|
|
||||||
|
### Requirement: Elevation profile display
|
||||||
|
The Planner SHALL display an elevation profile chart for the current route.
|
||||||
|
|
||||||
|
#### Scenario: Show elevation profile
|
||||||
|
- **WHEN** a route is computed
|
||||||
|
- **THEN** an elevation profile chart is displayed below the map showing distance vs elevation with total ascent/descent statistics
|
||||||
|
|
@ -0,0 +1,41 @@
|
||||||
|
## ADDED Requirements
|
||||||
|
|
||||||
|
### Requirement: Open Planner from Journal
|
||||||
|
The Journal SHALL allow a route owner to open a route in the Planner for collaborative editing.
|
||||||
|
|
||||||
|
#### Scenario: Start editing session
|
||||||
|
- **WHEN** a route owner clicks "Edit in Planner" on a route detail page
|
||||||
|
- **THEN** the Journal generates a scoped JWT token and redirects to `planner.trails.cool/new?callback=<url>&token=<jwt>` with the route's current GPX
|
||||||
|
|
||||||
|
### Requirement: Save from Planner to Journal
|
||||||
|
The Planner SHALL save route edits back to the Journal via the callback URL provided at session creation.
|
||||||
|
|
||||||
|
#### Scenario: Save route back
|
||||||
|
- **WHEN** a user clicks "Save" in the Planner and a callback URL exists
|
||||||
|
- **THEN** the Planner POSTs the current GPX and metadata to the callback URL with the JWT token
|
||||||
|
|
||||||
|
#### Scenario: Journal receives save callback
|
||||||
|
- **WHEN** the Journal receives a POST to the callback endpoint with a valid JWT
|
||||||
|
- **THEN** the Journal creates a new route version with the GPX and credits the contributor
|
||||||
|
|
||||||
|
### Requirement: Scoped JWT token
|
||||||
|
The Journal SHALL generate scoped JWT tokens for Planner callbacks containing the instance URL, route ID, permissions, and expiry.
|
||||||
|
|
||||||
|
#### Scenario: Valid token accepted
|
||||||
|
- **WHEN** the Planner sends a save request with a valid, non-expired JWT
|
||||||
|
- **THEN** the Journal accepts the request and saves the route
|
||||||
|
|
||||||
|
#### Scenario: Expired token rejected
|
||||||
|
- **WHEN** the Planner sends a save request with an expired JWT
|
||||||
|
- **THEN** the Journal returns a 401 error
|
||||||
|
|
||||||
|
#### Scenario: Invalid token rejected
|
||||||
|
- **WHEN** the Planner sends a save request with a tampered JWT
|
||||||
|
- **THEN** the Journal returns a 401 error
|
||||||
|
|
||||||
|
### Requirement: Return to Journal after save
|
||||||
|
After saving, the Planner SHALL provide a link back to the route in the Journal.
|
||||||
|
|
||||||
|
#### Scenario: Return link displayed
|
||||||
|
- **WHEN** a save to the Journal succeeds
|
||||||
|
- **THEN** the Planner displays a success message with a link to the route in the Journal
|
||||||
73
openspec/changes/phase-1-mvp/specs/planner-session/spec.md
Normal file
73
openspec/changes/phase-1-mvp/specs/planner-session/spec.md
Normal file
|
|
@ -0,0 +1,73 @@
|
||||||
|
## ADDED Requirements
|
||||||
|
|
||||||
|
### Requirement: Create collaborative session
|
||||||
|
The Planner SHALL allow creating a new editing session that generates a unique shareable URL. Sessions SHALL be created either from the Planner directly (empty route) or via a Journal callback (with initial GPX data).
|
||||||
|
|
||||||
|
#### Scenario: Create empty session
|
||||||
|
- **WHEN** a user navigates to planner.trails.cool
|
||||||
|
- **THEN** a new Yjs session is created with an empty waypoint list and the user is redirected to `/session/<session-id>`
|
||||||
|
|
||||||
|
#### Scenario: Create session from Journal callback
|
||||||
|
- **WHEN** the Journal opens `planner.trails.cool/new?callback=<url>&token=<jwt>&gpx=<encoded-gpx>`
|
||||||
|
- **THEN** a new Yjs session is created with waypoints parsed from the GPX and the callback URL is stored for later save operations
|
||||||
|
|
||||||
|
### Requirement: Join session via link
|
||||||
|
The Planner SHALL allow any user (including guests without accounts) to join an existing session by navigating to its URL.
|
||||||
|
|
||||||
|
#### Scenario: Join active session
|
||||||
|
- **WHEN** a user navigates to `planner.trails.cool/session/<session-id>`
|
||||||
|
- **THEN** the user connects to the Yjs document and sees the current route state with all other participants' cursors
|
||||||
|
|
||||||
|
#### Scenario: Join expired session
|
||||||
|
- **WHEN** a user navigates to a session URL that has expired
|
||||||
|
- **THEN** the system displays an error message indicating the session no longer exists
|
||||||
|
|
||||||
|
### Requirement: Real-time collaborative editing
|
||||||
|
The Planner SHALL synchronize waypoint edits across all connected participants in real-time using Yjs CRDTs.
|
||||||
|
|
||||||
|
#### Scenario: Add waypoint
|
||||||
|
- **WHEN** participant A adds a waypoint to the map
|
||||||
|
- **THEN** participant B sees the waypoint appear within 500ms
|
||||||
|
|
||||||
|
#### Scenario: Reorder waypoints
|
||||||
|
- **WHEN** participant A drags a waypoint to reorder it
|
||||||
|
- **THEN** participant B sees the updated waypoint order within 500ms
|
||||||
|
|
||||||
|
#### Scenario: Concurrent edits
|
||||||
|
- **WHEN** participant A and B both add waypoints simultaneously
|
||||||
|
- **THEN** both waypoints appear for both participants without conflict
|
||||||
|
|
||||||
|
### Requirement: Session persistence
|
||||||
|
The Planner SHALL persist Yjs session state to PostgreSQL so that sessions survive server restarts.
|
||||||
|
|
||||||
|
#### Scenario: Server restart recovery
|
||||||
|
- **WHEN** the Planner server restarts while a session is active
|
||||||
|
- **THEN** reconnecting clients recover the full session state from PostgreSQL
|
||||||
|
|
||||||
|
### Requirement: Session expiry
|
||||||
|
The Planner SHALL automatically expire sessions after a configurable period of inactivity (default: 7 days, max: 30 days).
|
||||||
|
|
||||||
|
#### Scenario: Session expires
|
||||||
|
- **WHEN** no edits are made to a session for 7 days
|
||||||
|
- **THEN** the session is deleted from PostgreSQL and its URL returns a 404
|
||||||
|
|
||||||
|
### Requirement: Manual session close
|
||||||
|
The session owner (initiator) SHALL be able to manually close a session.
|
||||||
|
|
||||||
|
#### Scenario: Owner closes session
|
||||||
|
- **WHEN** the session owner clicks "Close Session"
|
||||||
|
- **THEN** all connected participants are notified, the session triggers auto-save if a callback exists, and the session becomes inaccessible
|
||||||
|
|
||||||
|
### Requirement: User presence
|
||||||
|
The Planner SHALL display presence indicators showing which users are currently connected to a session.
|
||||||
|
|
||||||
|
#### Scenario: Show connected users
|
||||||
|
- **WHEN** multiple users are connected to a session
|
||||||
|
- **THEN** each user sees a list of other connected users with assigned colors
|
||||||
|
|
||||||
|
### Requirement: No user data collection
|
||||||
|
The Planner SHALL NOT collect, store, or track any personal user data. Sessions are anonymous by default.
|
||||||
|
|
||||||
|
#### Scenario: Anonymous session participation
|
||||||
|
- **WHEN** a user joins a session without any account
|
||||||
|
- **THEN** the user is assigned a random color and temporary display name with no data persisted about their identity
|
||||||
75
openspec/changes/phase-1-mvp/specs/route-management/spec.md
Normal file
75
openspec/changes/phase-1-mvp/specs/route-management/spec.md
Normal file
|
|
@ -0,0 +1,75 @@
|
||||||
|
## ADDED Requirements
|
||||||
|
|
||||||
|
### Requirement: Create route
|
||||||
|
The Journal SHALL allow authenticated users to create a new route with a name and optional description.
|
||||||
|
|
||||||
|
#### Scenario: Create empty route
|
||||||
|
- **WHEN** a user clicks "New Route" and enters a name
|
||||||
|
- **THEN** a new route record is created in PostgreSQL and the user is redirected to the route detail page
|
||||||
|
|
||||||
|
### Requirement: View route
|
||||||
|
The Journal SHALL display route details including map, metadata, and elevation stats.
|
||||||
|
|
||||||
|
#### Scenario: View route detail
|
||||||
|
- **WHEN** a user navigates to a route's URL
|
||||||
|
- **THEN** they see the route name, description, a map with the route polyline, distance, and elevation gain/loss
|
||||||
|
|
||||||
|
### Requirement: Update route
|
||||||
|
The Journal SHALL allow the route owner to update the route name, description, and GPX.
|
||||||
|
|
||||||
|
#### Scenario: Update route metadata
|
||||||
|
- **WHEN** a route owner edits the route name or description and saves
|
||||||
|
- **THEN** the route record is updated and a new version is created
|
||||||
|
|
||||||
|
### Requirement: Delete route
|
||||||
|
The Journal SHALL allow the route owner to delete a route.
|
||||||
|
|
||||||
|
#### Scenario: Delete route with confirmation
|
||||||
|
- **WHEN** a route owner clicks "Delete" and confirms
|
||||||
|
- **THEN** the route and all its versions are permanently deleted
|
||||||
|
|
||||||
|
### Requirement: GPX import
|
||||||
|
The Journal SHALL allow users to create or update a route by uploading a GPX file.
|
||||||
|
|
||||||
|
#### Scenario: Import GPX as new route
|
||||||
|
- **WHEN** a user uploads a GPX file on the "Import" page
|
||||||
|
- **THEN** a new route is created with waypoints and track parsed from the GPX, and route geometry is stored in PostGIS
|
||||||
|
|
||||||
|
#### Scenario: Import GPX to existing route
|
||||||
|
- **WHEN** a route owner uploads a GPX file on an existing route's page
|
||||||
|
- **THEN** the route GPX is replaced and a new version is created
|
||||||
|
|
||||||
|
### Requirement: GPX export
|
||||||
|
The Journal SHALL allow users to download any route as a GPX file.
|
||||||
|
|
||||||
|
#### Scenario: Export route as GPX
|
||||||
|
- **WHEN** a user clicks "Export GPX" on a route detail page
|
||||||
|
- **THEN** a GPX file is downloaded containing the route track and waypoints
|
||||||
|
|
||||||
|
### Requirement: Route versioning
|
||||||
|
The Journal SHALL store sequential versions of each route. Each GPX update creates a new version.
|
||||||
|
|
||||||
|
#### Scenario: View version history
|
||||||
|
- **WHEN** a route owner views the route detail page
|
||||||
|
- **THEN** they see a list of versions with version number, date, and contributor
|
||||||
|
|
||||||
|
### Requirement: Route list
|
||||||
|
The Journal SHALL display a list of the authenticated user's routes.
|
||||||
|
|
||||||
|
#### Scenario: View my routes
|
||||||
|
- **WHEN** a logged-in user navigates to their route list
|
||||||
|
- **THEN** they see all their routes with name, distance, and last updated date
|
||||||
|
|
||||||
|
### Requirement: PostGIS spatial storage
|
||||||
|
Route geometries SHALL be stored as PostGIS LineString geometries extracted from the GPX.
|
||||||
|
|
||||||
|
#### Scenario: Spatial data stored on import
|
||||||
|
- **WHEN** a GPX file is imported or a route is saved from the Planner
|
||||||
|
- **THEN** the route geometry is extracted and stored as a PostGIS LineString for future spatial queries
|
||||||
|
|
||||||
|
### Requirement: Route metadata envelope
|
||||||
|
Routes SHALL be stored with a metadata envelope containing computed statistics (distance, elevation gain/loss), routing profile, contributor list, and tags.
|
||||||
|
|
||||||
|
#### Scenario: Metadata computed on save
|
||||||
|
- **WHEN** a route GPX is saved
|
||||||
|
- **THEN** distance and elevation statistics are computed from the GPX and stored in the metadata
|
||||||
56
openspec/changes/phase-1-mvp/specs/shared-packages/spec.md
Normal file
56
openspec/changes/phase-1-mvp/specs/shared-packages/spec.md
Normal file
|
|
@ -0,0 +1,56 @@
|
||||||
|
## ADDED Requirements
|
||||||
|
|
||||||
|
### Requirement: Shared types package
|
||||||
|
The `@trails-cool/types` package SHALL export TypeScript interfaces for Route, Activity, Waypoint, RouteVersion, and RouteMetadata used by both apps.
|
||||||
|
|
||||||
|
#### Scenario: Import types in Planner
|
||||||
|
- **WHEN** the Planner app imports `@trails-cool/types`
|
||||||
|
- **THEN** it has access to the Waypoint, Route, and RouteMetadata interfaces
|
||||||
|
|
||||||
|
#### Scenario: Import types in Journal
|
||||||
|
- **WHEN** the Journal app imports `@trails-cool/types`
|
||||||
|
- **THEN** it has access to Route, Activity, RouteVersion, and RouteMetadata interfaces
|
||||||
|
|
||||||
|
### Requirement: GPX parsing package
|
||||||
|
The `@trails-cool/gpx` package SHALL parse GPX XML into structured data (waypoints, tracks, elevation) and generate GPX XML from structured data.
|
||||||
|
|
||||||
|
#### Scenario: Parse GPX to waypoints
|
||||||
|
- **WHEN** the gpx package parses a valid GPX file
|
||||||
|
- **THEN** it returns an array of Waypoint objects with lat, lon, and optional name
|
||||||
|
|
||||||
|
#### Scenario: Generate GPX from waypoints
|
||||||
|
- **WHEN** the gpx package is given an array of waypoints and a track
|
||||||
|
- **THEN** it generates a valid GPX XML string
|
||||||
|
|
||||||
|
#### Scenario: Extract elevation data
|
||||||
|
- **WHEN** the gpx package parses a GPX file with elevation data
|
||||||
|
- **THEN** it returns elevation gain, loss, and a profile array of distance/elevation pairs
|
||||||
|
|
||||||
|
### Requirement: Map rendering package
|
||||||
|
The `@trails-cool/map` package SHALL provide React components for rendering Leaflet maps with configurable base layers and route overlays.
|
||||||
|
|
||||||
|
#### Scenario: Render map component
|
||||||
|
- **WHEN** the map package's MapView component is rendered with a center and zoom
|
||||||
|
- **THEN** a Leaflet map is displayed with the default OSM tile layer
|
||||||
|
|
||||||
|
#### Scenario: Display route on map
|
||||||
|
- **WHEN** the map package's RouteLayer component receives GeoJSON
|
||||||
|
- **THEN** it renders a polyline on the map
|
||||||
|
|
||||||
|
### Requirement: UI component package
|
||||||
|
The `@trails-cool/ui` package SHALL provide shared React components (buttons, layout, form elements) styled with Tailwind CSS.
|
||||||
|
|
||||||
|
#### Scenario: Use Button component
|
||||||
|
- **WHEN** an app renders the Button component from `@trails-cool/ui`
|
||||||
|
- **THEN** a styled button is displayed consistent with the trails.cool design
|
||||||
|
|
||||||
|
### Requirement: i18n package
|
||||||
|
The `@trails-cool/i18n` package SHALL provide react-i18next configuration and translation strings starting with English and German.
|
||||||
|
|
||||||
|
#### Scenario: Display German translation
|
||||||
|
- **WHEN** a user's browser locale is set to German
|
||||||
|
- **THEN** UI strings are displayed in German
|
||||||
|
|
||||||
|
#### Scenario: Fallback to English
|
||||||
|
- **WHEN** a user's browser locale is not supported
|
||||||
|
- **THEN** UI strings fall back to English
|
||||||
114
openspec/changes/phase-1-mvp/tasks.md
Normal file
114
openspec/changes/phase-1-mvp/tasks.md
Normal file
|
|
@ -0,0 +1,114 @@
|
||||||
|
## 1. Monorepo Toolchain Setup
|
||||||
|
|
||||||
|
- [ ] 1.1 Install pnpm and Turborepo, configure workspaces
|
||||||
|
- [ ] 1.2 Set up TypeScript config (base tsconfig, per-package extends)
|
||||||
|
- [ ] 1.3 Set up Tailwind CSS (shared config, content paths for monorepo)
|
||||||
|
- [ ] 1.4 Set up ESLint and Prettier (shared config)
|
||||||
|
- [ ] 1.5 Scaffold Planner app with React Router 7 (`apps/planner`)
|
||||||
|
- [ ] 1.6 Scaffold Journal app with React Router 7 (`apps/journal`)
|
||||||
|
- [ ] 1.7 Verify `turbo dev` starts both apps and `turbo build` succeeds
|
||||||
|
|
||||||
|
## 2. Shared Packages
|
||||||
|
|
||||||
|
- [ ] 2.1 Implement `@trails-cool/types` — Route, Activity, Waypoint, RouteVersion, RouteMetadata interfaces
|
||||||
|
- [ ] 2.2 Implement `@trails-cool/gpx` — GPX parser (XML → waypoints/tracks/elevation) and GPX generator (waypoints/tracks → XML)
|
||||||
|
- [ ] 2.3 Implement `@trails-cool/map` — MapView React component (Leaflet + OSM), RouteLayer component (GeoJSON polyline), layer switcher (OSM/OpenTopoMap/CyclOSM)
|
||||||
|
- [ ] 2.4 Implement `@trails-cool/ui` — Button, Input, Card, Layout components with Tailwind styling
|
||||||
|
- [ ] 2.5 Implement `@trails-cool/i18n` — react-i18next config, English + German translation files, LanguageSwitcher component
|
||||||
|
- [ ] 2.6 Verify all packages are importable from both apps
|
||||||
|
|
||||||
|
## 3. Infrastructure
|
||||||
|
|
||||||
|
- [ ] 3.1 Create Terraform config for Hetzner CX21 with Docker installed
|
||||||
|
- [ ] 3.2 Create Docker Compose for all services (Journal, Planner, BRouter, PostgreSQL+PostGIS, Garage)
|
||||||
|
- [ ] 3.3 Create BRouter Dockerfile with segment volume mount
|
||||||
|
- [ ] 3.4 Create segment download script (Germany: E5_N45, E5_N50, E10_N45, E10_N50)
|
||||||
|
- [ ] 3.5 Configure DNS for trails.cool and planner.trails.cool with TLS (Caddy or Traefik)
|
||||||
|
- [ ] 3.6 Set up GitHub Actions CI pipeline (build, typecheck, lint)
|
||||||
|
- [ ] 3.7 Set up GitHub Actions CD pipeline (build Docker images, push to ghcr.io, deploy to Hetzner)
|
||||||
|
- [ ] 3.8 Set up PostgreSQL backup cron (daily pg_dump to Hetzner Storage Box)
|
||||||
|
|
||||||
|
## 4. Planner — Session Management
|
||||||
|
|
||||||
|
- [ ] 4.1 Set up Yjs with y-websocket in Planner backend (WebSocket endpoint at /sync)
|
||||||
|
- [ ] 4.2 Implement Yjs persistence to PostgreSQL (planner schema, sessions table)
|
||||||
|
- [ ] 4.3 Implement session creation endpoint (POST /api/sessions → returns session ID)
|
||||||
|
- [ ] 4.4 Implement session creation with initial GPX (parse GPX → Yjs document with waypoints)
|
||||||
|
- [ ] 4.5 Implement session join page (GET /session/:id → connect to Yjs document)
|
||||||
|
- [ ] 4.6 Implement session expiry (garbage collection cron, configurable TTL)
|
||||||
|
- [ ] 4.7 Implement manual session close (owner action, notify participants)
|
||||||
|
- [ ] 4.8 Implement user presence display (Yjs awareness, colors, names)
|
||||||
|
|
||||||
|
## 5. Planner — BRouter Integration
|
||||||
|
|
||||||
|
- [ ] 5.1 Implement BRouter HTTP proxy endpoint (POST /api/route → forward to BRouter)
|
||||||
|
- [ ] 5.2 Implement rate limiting middleware (60 requests/session/hour)
|
||||||
|
- [ ] 5.3 Implement routing host election via Yjs awareness (host/participant roles)
|
||||||
|
- [ ] 5.4 Implement routing host failover (detect disconnect, elect new host by join timestamp)
|
||||||
|
- [ ] 5.5 Implement route computation trigger (host watches waypoint changes, debounce 500ms, call BRouter)
|
||||||
|
- [ ] 5.6 Implement route broadcast (host stores GeoJSON result in Y.Map, syncs to all)
|
||||||
|
- [ ] 5.7 Implement profile selection (sync profile choice via Y.Map, trigger recompute)
|
||||||
|
|
||||||
|
## 6. Planner — Map UI
|
||||||
|
|
||||||
|
- [ ] 6.1 Integrate MapView component in Planner with full-screen layout
|
||||||
|
- [ ] 6.2 Implement waypoint add (click map → add to Y.Array)
|
||||||
|
- [ ] 6.3 Implement waypoint drag (move marker → update Y.Array)
|
||||||
|
- [ ] 6.4 Implement waypoint delete (right-click → remove from Y.Array)
|
||||||
|
- [ ] 6.5 Implement waypoint list sidebar (draggable reorder, synced with Y.Array)
|
||||||
|
- [ ] 6.6 Implement route polyline display (render GeoJSON from Y.Map)
|
||||||
|
- [ ] 6.7 Implement elevation profile chart (parse elevation from route GeoJSON, render chart)
|
||||||
|
- [ ] 6.8 Implement profile selector UI (dropdown, synced via Y.Map)
|
||||||
|
- [ ] 6.9 Implement GPX export button (generate GPX from current waypoints and route)
|
||||||
|
|
||||||
|
## 7. Journal — Auth
|
||||||
|
|
||||||
|
- [ ] 7.1 Set up PostgreSQL schema (journal.users table with id, email, password_hash, username, bio, created_at)
|
||||||
|
- [ ] 7.2 Implement registration page and API (POST /api/auth/register)
|
||||||
|
- [ ] 7.3 Implement login page and API (POST /api/auth/login, session cookie)
|
||||||
|
- [ ] 7.4 Implement logout (POST /api/auth/logout, invalidate session)
|
||||||
|
- [ ] 7.5 Implement session middleware (validate cookie, load user in loader context)
|
||||||
|
- [ ] 7.6 Implement user profile page (GET /users/:username)
|
||||||
|
- [ ] 7.7 Store federated identity format (@user@domain) in user record
|
||||||
|
|
||||||
|
## 8. Journal — Route Management
|
||||||
|
|
||||||
|
- [ ] 8.1 Set up PostgreSQL schema (journal.routes table with PostGIS geometry column, journal.route_versions table)
|
||||||
|
- [ ] 8.2 Implement route creation page (form: name, description, optional GPX upload)
|
||||||
|
- [ ] 8.3 Implement route detail page (map, metadata, version history)
|
||||||
|
- [ ] 8.4 Implement route edit page (update name, description)
|
||||||
|
- [ ] 8.5 Implement route deletion (with confirmation dialog)
|
||||||
|
- [ ] 8.6 Implement GPX import (parse GPX, extract geometry for PostGIS, compute stats)
|
||||||
|
- [ ] 8.7 Implement GPX export (generate GPX from stored data, download)
|
||||||
|
- [ ] 8.8 Implement route versioning (create new version on each GPX update)
|
||||||
|
- [ ] 8.9 Implement route list page (user's routes, sorted by last updated)
|
||||||
|
- [ ] 8.10 Implement route metadata computation (distance, elevation gain/loss from GPX)
|
||||||
|
|
||||||
|
## 9. Planner-Journal Handoff
|
||||||
|
|
||||||
|
- [ ] 9.1 Implement JWT token generation in Journal (scoped to route_id, with expiry)
|
||||||
|
- [ ] 9.2 Implement "Edit in Planner" button on Journal route detail page (redirect with callback + token + GPX)
|
||||||
|
- [ ] 9.3 Implement callback URL handling in Planner (store callback URL in session metadata)
|
||||||
|
- [ ] 9.4 Implement "Save to Journal" button in Planner (POST GPX + JWT to callback URL)
|
||||||
|
- [ ] 9.5 Implement callback endpoint in Journal (POST /api/routes/:id/callback — validate JWT, save new version)
|
||||||
|
- [ ] 9.6 Implement "Return to Journal" link after successful save
|
||||||
|
|
||||||
|
## 10. Journal — Activity Feed
|
||||||
|
|
||||||
|
- [ ] 10.1 Set up PostgreSQL schema (journal.activities table with route_id FK, gpx, stats)
|
||||||
|
- [ ] 10.2 Implement activity creation page (GPX upload, description, optional route link)
|
||||||
|
- [ ] 10.3 Implement activity detail page (map with GPS trace, stats, description)
|
||||||
|
- [ ] 10.4 Implement activity feed page (chronological list of own activities)
|
||||||
|
- [ ] 10.5 Implement "Link to Route" action (select existing route to link)
|
||||||
|
- [ ] 10.6 Implement "Create Route from Activity" action (create route from activity GPX)
|
||||||
|
|
||||||
|
## 11. Testing & Polish
|
||||||
|
|
||||||
|
- [ ] 11.1 End-to-end test: Create route in Journal → Edit in Planner → Save back to Journal
|
||||||
|
- [ ] 11.2 End-to-end test: Two users collaboratively edit waypoints in Planner
|
||||||
|
- [ ] 11.3 End-to-end test: Import GPX → view route on map → export GPX
|
||||||
|
- [ ] 11.4 Test BRouter routing with Germany segments (Berlin → Munich route)
|
||||||
|
- [ ] 11.5 Test session expiry and manual close
|
||||||
|
- [ ] 11.6 Verify i18n works (English and German)
|
||||||
|
- [ ] 11.7 Basic responsive layout testing (desktop, tablet)
|
||||||
|
- [ ] 11.8 Deploy to Hetzner and verify production setup
|
||||||
Loading…
Add table
Add a link
Reference in a new issue