Skip to content

Commit 5337b57

Browse files
theagenticguytheagenticguy
authored
feat: add ralph watch command for iterative repo discovery (#31)
Adds a new `ralph watch` command that discovers trending GitHub repositories through iterative deep research using Kiro CLI with existing MCP search servers (exa, brave-search, tavily). Key features: - `ralph watch` — fire-and-forget discovery run (min 3, max 10 iterations) - `ralph watch init` — scaffolds agent, steering, MCP config, and manifest - `ralph watch results [id]` — display results by task ID - `ralph watch ls` — list recent watch runs - Manifest lifecycle: auto-add high-signal repos, freshness tracking, pruning suggestions, and append-only discovery log - Results folder per run with iteration snapshots, discovery.json, summary.md Architecture: - Reuses existing loop runner with new LoopResult return type (fixes process.exit bug that prevented caller cleanup) - JSON manifest (watch-manifest.json) as single source of truth - Kiro agent + steering file with iterative deepening strategy - .mcp.json.example for open source (no committed API keys) Docs: - 4 ADRs (watch architecture, iterative deepening, MCP reuse, manifest lifecycle) - OpenSpec spec with 11 requirements - OpenSpec initialized with Claude Code + Kiro support
1 parent e7c3f3a commit 5337b57

32 files changed

Lines changed: 2782 additions & 7 deletions

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -635,3 +635,10 @@ $RECYCLE.BIN/
635635
# End of https://www.toptal.com/developers/gitignore/api/linux,python,windows,macOS,VisualStudioCode,jetbrains+all,pycharm+all,node,amplify,sam,typescript,vue,idea,terraform,kubernetes,docker
636636

637637
.claude
638+
639+
# Project Watcher
640+
results/
641+
watch-manifest.json
642+
.kiro/settings/mcp.json
643+
.kiro/ralph-loop.local.json
644+
.kiro/ralph-session.json

‎.kiro/agents/project-watcher.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"name": "project-watcher",
3+
"description": "Iterative deep research agent for discovering trending GitHub repos matching watched topics and languages",
4+
"tools": [
5+
"read",
6+
"write",
7+
"@brave-search",
8+
"@tavily",
9+
"@exa"
10+
],
11+
"allowedTools": [
12+
"*"
13+
],
14+
"includeMcpJson": true,
15+
"resources": [
16+
"file://../../watch-manifest.json",
17+
"file://../ralph-loop.local.json"
18+
],
19+
"prompt": "file://../steering/watcher-context.md"
20+
}

‎.kiro/prompts/opsx-apply.prompt.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
description: Implement tasks from an OpenSpec change (Experimental)
3+
---
4+
5+
Implement tasks from an OpenSpec change.
6+
7+
**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.
8+
9+
**Steps**
10+
11+
1. **Select the change**
12+
13+
If a name is provided, use it. Otherwise:
14+
- Infer from conversation context if the user mentioned a change
15+
- Auto-select if only one active change exists
16+
- If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
17+
18+
Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
19+
20+
2. **Check status to understand the schema**
21+
```bash
22+
openspec status --change "<name>" --json
23+
```
24+
Parse the JSON to understand:
25+
- `schemaName`: The workflow being used (e.g., "spec-driven")
26+
- Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
27+
28+
3. **Get apply instructions**
29+
30+
```bash
31+
openspec instructions apply --change "<name>" --json
32+
```
33+
34+
This returns:
35+
- Context file paths (varies by schema)
36+
- Progress (total, complete, remaining)
37+
- Task list with status
38+
- Dynamic instruction based on current state
39+
40+
**Handle states:**
41+
- If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue`
42+
- If `state: "all_done"`: congratulate, suggest archive
43+
- Otherwise: proceed to implementation
44+
45+
4. **Read context files**
46+
47+
Read the files listed in `contextFiles` from the apply instructions output.
48+
The files depend on the schema being used:
49+
- **spec-driven**: proposal, specs, design, tasks
50+
- Other schemas: follow the contextFiles from CLI output
51+
52+
5. **Show current progress**
53+
54+
Display:
55+
- Schema being used
56+
- Progress: "N/M tasks complete"
57+
- Remaining tasks overview
58+
- Dynamic instruction from CLI
59+
60+
6. **Implement tasks (loop until done or blocked)**
61+
62+
For each pending task:
63+
- Show which task is being worked on
64+
- Make the code changes required
65+
- Keep changes minimal and focused
66+
- Mark task complete in the tasks file: `- [ ]` → `- [x]`
67+
- Continue to next task
68+
69+
**Pause if:**
70+
- Task is unclear → ask for clarification
71+
- Implementation reveals a design issue → suggest updating artifacts
72+
- Error or blocker encountered → report and wait for guidance
73+
- User interrupts
74+
75+
7. **On completion or pause, show status**
76+
77+
Display:
78+
- Tasks completed this session
79+
- Overall progress: "N/M tasks complete"
80+
- If all done: suggest archive
81+
- If paused: explain why and wait for guidance
82+
83+
**Output During Implementation**
84+
85+
```
86+
## Implementing: <change-name> (schema: <schema-name>)
87+
88+
Working on task 3/7: <task description>
89+
[...implementation happening...]
90+
✓ Task complete
91+
92+
Working on task 4/7: <task description>
93+
[...implementation happening...]
94+
✓ Task complete
95+
```
96+
97+
**Output On Completion**
98+
99+
```
100+
## Implementation Complete
101+
102+
**Change:** <change-name>
103+
**Schema:** <schema-name>
104+
**Progress:** 7/7 tasks complete ✓
105+
106+
### Completed This Session
107+
- [x] Task 1
108+
- [x] Task 2
109+
...
110+
111+
All tasks complete! You can archive this change with `/opsx:archive`.
112+
```
113+
114+
**Output On Pause (Issue Encountered)**
115+
116+
```
117+
## Implementation Paused
118+
119+
**Change:** <change-name>
120+
**Schema:** <schema-name>
121+
**Progress:** 4/7 tasks complete
122+
123+
### Issue Encountered
124+
<description of the issue>
125+
126+
**Options:**
127+
1. <option 1>
128+
2. <option 2>
129+
3. Other approach
130+
131+
What would you like to do?
132+
```
133+
134+
**Guardrails**
135+
- Keep going through tasks until done or blocked
136+
- Always read context files before starting (from the apply instructions output)
137+
- If task is ambiguous, pause and ask before implementing
138+
- If implementation reveals issues, pause and suggest artifact updates
139+
- Keep code changes minimal and scoped to each task
140+
- Update task checkbox immediately after completing each task
141+
- Pause on errors, blockers, or unclear requirements - don't guess
142+
- Use contextFiles from CLI output, don't assume specific file names
143+
144+
**Fluid Workflow Integration**
145+
146+
This skill supports the "actions on a change" model:
147+
148+
- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
149+
- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly

‎.kiro/prompts/opsx-archive.prompt.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
description: Archive a completed change in the experimental workflow
3+
---
4+
5+
Archive a completed change in the experimental workflow.
6+
7+
**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.
8+
9+
**Steps**
10+
11+
1. **If no change name provided, prompt for selection**
12+
13+
Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
14+
15+
Show only active changes (not already archived).
16+
Include the schema used for each change if available.
17+
18+
**IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
19+
20+
2. **Check artifact completion status**
21+
22+
Run `openspec status --change "<name>" --json` to check artifact completion.
23+
24+
Parse the JSON to understand:
25+
- `schemaName`: The workflow being used
26+
- `artifacts`: List of artifacts with their status (`done` or other)
27+
28+
**If any artifacts are not `done`:**
29+
- Display warning listing incomplete artifacts
30+
- Prompt user for confirmation to continue
31+
- Proceed if user confirms
32+
33+
3. **Check task completion status**
34+
35+
Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
36+
37+
Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
38+
39+
**If incomplete tasks found:**
40+
- Display warning showing count of incomplete tasks
41+
- Prompt user for confirmation to continue
42+
- Proceed if user confirms
43+
44+
**If no tasks file exists:** Proceed without task-related warning.
45+
46+
4. **Assess delta spec sync state**
47+
48+
Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
49+
50+
**If delta specs exist:**
51+
- Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
52+
- Determine what changes would be applied (adds, modifications, removals, renames)
53+
- Show a combined summary before prompting
54+
55+
**Prompt options:**
56+
- If changes needed: "Sync now (recommended)", "Archive without syncing"
57+
- If already synced: "Archive now", "Sync anyway", "Cancel"
58+
59+
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.
60+
61+
5. **Perform the archive**
62+
63+
Create the archive directory if it doesn't exist:
64+
```bash
65+
mkdir -p openspec/changes/archive
66+
```
67+
68+
Generate target name using current date: `YYYY-MM-DD-<change-name>`
69+
70+
**Check if target already exists:**
71+
- If yes: Fail with error, suggest renaming existing archive or using different date
72+
- If no: Move the change directory to archive
73+
74+
```bash
75+
mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
76+
```
77+
78+
6. **Display summary**
79+
80+
Show archive completion summary including:
81+
- Change name
82+
- Schema that was used
83+
- Archive location
84+
- Spec sync status (synced / sync skipped / no delta specs)
85+
- Note about any warnings (incomplete artifacts/tasks)
86+
87+
**Output On Success**
88+
89+
```
90+
## Archive Complete
91+
92+
**Change:** <change-name>
93+
**Schema:** <schema-name>
94+
**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
95+
**Specs:** ✓ Synced to main specs
96+
97+
All artifacts complete. All tasks complete.
98+
```
99+
100+
**Output On Success (No Delta Specs)**
101+
102+
```
103+
## Archive Complete
104+
105+
**Change:** <change-name>
106+
**Schema:** <schema-name>
107+
**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
108+
**Specs:** No delta specs
109+
110+
All artifacts complete. All tasks complete.
111+
```
112+
113+
**Output On Success With Warnings**
114+
115+
```
116+
## Archive Complete (with warnings)
117+
118+
**Change:** <change-name>
119+
**Schema:** <schema-name>
120+
**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
121+
**Specs:** Sync skipped (user chose to skip)
122+
123+
**Warnings:**
124+
- Archived with 2 incomplete artifacts
125+
- Archived with 3 incomplete tasks
126+
- Delta spec sync was skipped (user chose to skip)
127+
128+
Review the archive if this was not intentional.
129+
```
130+
131+
**Output On Error (Archive Exists)**
132+
133+
```
134+
## Archive Failed
135+
136+
**Change:** <change-name>
137+
**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
138+
139+
Target archive directory already exists.
140+
141+
**Options:**
142+
1. Rename the existing archive
143+
2. Delete the existing archive if it's a duplicate
144+
3. Wait until a different date to archive
145+
```
146+
147+
**Guardrails**
148+
- Always prompt for change selection if not provided
149+
- Use artifact graph (openspec status --json) for completion checking
150+
- Don't block archive on warnings - just inform and confirm
151+
- Preserve .openspec.yaml when moving to archive (it moves with the directory)
152+
- Show clear summary of what happened
153+
- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven)
154+
- If delta specs exist, always run the sync assessment and show the combined summary before prompting

0 commit comments

Comments
 (0)