spequi 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/LICENSE +21 -0
  3. package/README.md +292 -2
  4. package/bin/spequi.mjs +80 -0
  5. package/docs/agent-workflow.md +459 -0
  6. package/package.json +79 -4
  7. package/public/app.css +171 -0
  8. package/public/app.js +328 -0
  9. package/public/diff.css +217 -0
  10. package/public/fonts/README.md +22 -0
  11. package/public/fonts/dm-sans-OFL.txt +93 -0
  12. package/public/fonts/dm-sans-variable-latin-ext.woff2 +0 -0
  13. package/public/fonts/dm-sans-variable-latin.woff2 +0 -0
  14. package/public/fonts/ibm-plex-mono-400-cyrillic-ext.woff2 +0 -0
  15. package/public/fonts/ibm-plex-mono-400-cyrillic.woff2 +0 -0
  16. package/public/fonts/ibm-plex-mono-400-latin-ext.woff2 +0 -0
  17. package/public/fonts/ibm-plex-mono-400-latin.woff2 +0 -0
  18. package/public/fonts/ibm-plex-mono-400-vietnamese.woff2 +0 -0
  19. package/public/fonts/ibm-plex-mono-500-cyrillic-ext.woff2 +0 -0
  20. package/public/fonts/ibm-plex-mono-500-cyrillic.woff2 +0 -0
  21. package/public/fonts/ibm-plex-mono-500-latin-ext.woff2 +0 -0
  22. package/public/fonts/ibm-plex-mono-500-latin.woff2 +0 -0
  23. package/public/fonts/ibm-plex-mono-500-vietnamese.woff2 +0 -0
  24. package/public/fonts/ibm-plex-mono-OFL.txt +93 -0
  25. package/public/fonts.css +109 -0
  26. package/public/requests.js +328 -0
  27. package/public/review.css +286 -0
  28. package/public/review.js +361 -0
  29. package/public/session.js +161 -0
  30. package/public/studio.css +259 -0
  31. package/public/studio.js +179 -0
  32. package/public/workflow.js +105 -0
  33. package/skills/spequi/SKILL.md +79 -0
  34. package/src/agent-client.mjs +17 -0
  35. package/src/agent-session.mjs +33 -0
  36. package/src/analytics.mjs +63 -0
  37. package/src/commands.mjs +73 -0
  38. package/src/comment-controls.mjs +10 -0
  39. package/src/comment-view.mjs +52 -0
  40. package/src/creation-view.mjs +13 -0
  41. package/src/diff-comments.mjs +8 -0
  42. package/src/diff-view.mjs +79 -0
  43. package/src/diffs.mjs +88 -0
  44. package/src/direct-preview.mjs +169 -0
  45. package/src/document-view.mjs +75 -0
  46. package/src/drafts.mjs +83 -0
  47. package/src/feedback.mjs +86 -0
  48. package/src/files.mjs +123 -0
  49. package/src/highlighting.mjs +91 -0
  50. package/src/impact-view.mjs +30 -0
  51. package/src/impact.mjs +161 -0
  52. package/src/job-dialogue.mjs +41 -0
  53. package/src/jobs.mjs +269 -0
  54. package/src/lifecycle.mjs +114 -0
  55. package/src/openspec-cli.mjs +40 -0
  56. package/src/preview-view.mjs +96 -0
  57. package/src/previews.mjs +116 -0
  58. package/src/project.mjs +61 -0
  59. package/src/requests.mjs +80 -0
  60. package/src/review-store.mjs +150 -0
  61. package/src/review-view.mjs +23 -0
  62. package/src/server.mjs +305 -0
  63. package/src/source-preview-view.mjs +14 -0
  64. package/src/spec-context-view.mjs +37 -0
  65. package/src/spec-context.mjs +147 -0
  66. package/src/spec-impact.mjs +145 -0
  67. package/src/specs.mjs +80 -0
  68. package/src/studio-documents.mjs +25 -0
  69. package/src/studio-plans.mjs +71 -0
  70. package/src/studio-view.mjs +108 -0
  71. package/src/views.mjs +117 -0
  72. package/src/workspace-state.mjs +48 -0
  73. package/templates/cli.mjs +38 -0
@@ -0,0 +1,459 @@
1
+ # How Spequi attaches an agent and runs skills
2
+
3
+ This document describes the current implementation: how the app hands work to an existing coding agent, how that agent follows another skill, how questions wait for an answer in the UI, and how results return to the app.
4
+
5
+ **The app does not call a model or start a coding agent.** You invoke the `spequi` skill in an existing agent session. That agent runs local CLI commands, reads workflow instructions, performs the work through its tools, and reports completion.
6
+
7
+ There is no `await invokeSkill()` implementation. A skill is an instruction document that the current agent reads and follows. Completion is an explicit job update, not a return value from another skill process.
8
+
9
+ ## 1. The components
10
+
11
+ | Component | Responsibility | Implementation |
12
+ | --- | --- | --- |
13
+ | Browser UI | Submit actions, display progress, collect answers | [public/workflow.js](../public/workflow.js), [src/studio-view.mjs](../src/studio-view.mjs) |
14
+ | Local server | Protect browser mutations, route actions and replies, notify the UI | [src/server.mjs](../src/server.mjs) |
15
+ | Lifecycle layer | Check readiness and enqueue the requested action | [src/lifecycle.mjs](../src/lifecycle.mjs) |
16
+ | Job queue | Persist requests, claim ownership, choose workflows, store results | [src/jobs.mjs](../src/jobs.mjs) |
17
+ | Agent CLI | Report a session, poll, ask, wait, log, finish or fail | [bin/spequi.mjs](../bin/spequi.mjs) |
18
+ | Session evidence | Store credential-free agent/MCP reports and evaluate freshness | [src/agent-session.mjs](../src/agent-session.mjs) |
19
+ | Question storage | Retain questions and answers on the same owned job | [src/job-dialogue.mjs](../src/job-dialogue.mjs) |
20
+ | Agent skill | Instruct the current agent to coordinate the loop | [spequi SKILL.md](../skills/spequi/SKILL.md) |
21
+
22
+ The browser talks to the server over local HTTP and receives WebSocket notifications. The agent’s CLI commands use the project server’s authenticated loopback protocol when it is running. `.spequi/server.json` binds that connection to the project root; an unavailable saved connection is an explicit restart error. Headless commands without a server retain the file protocol. They do not send prompts over the browser's WebSocket connection.
23
+
24
+ Typical retained state looks like:
25
+
26
+ ```text
27
+ .spequi/
28
+ cli.mjs Project launcher for the initialized package
29
+ server.mjs Project server launcher
30
+ server.json Private root-bound agent protocol connection
31
+ drafts/ Autosaved ideas and unfinished planning references
32
+ agent.json Latest agent heartbeat
33
+ agent-session.json Session ID and reported MCP metadata
34
+ jobs/
35
+ <job-id>.json Action, ownership, status, questions, logs and result
36
+ previews/
37
+ <job-id>/
38
+ baseline/ Files captured before implementation
39
+ work/ Isolated project copy assigned to the agent
40
+ proposed/ Frozen changed files after completion
41
+ manifest.json Baseline fingerprints
42
+ result.json Diff metadata and application state
43
+ ```
44
+
45
+ ## 2. Attachment starts in the coding agent
46
+
47
+ The user invokes the installed skill using the host's convention, such as `$spequi` in Codex, `/skills spequi` in Sber/GitVerse GigaCode CLI, or `/spequi` in a CLI with that wrapper. The host makes the skill instructions available to the existing agent session.
48
+
49
+ The skill tells the agent to reuse the project's initialized launcher and existing server. This avoids requiring a global installation or starting a second agent.
50
+
51
+ ### GigaCode registration
52
+
53
+ The installer registers GigaCode alongside the existing agents. Project initialization and `skill install` create:
54
+
55
+ ```text
56
+ .gigacode/
57
+ skills/spequi/SKILL.md
58
+ commands/spequi.md
59
+ ```
60
+
61
+ `skill install --global` creates the same paths under the user's home directory. The command wrappers reference the skill in the matching scope and use GigaCode's `{{args}}` parameter syntax. After discovery, invoke `/skills spequi` or `/spequi`. These paths and formats follow GigaCode's [skills](https://gitverse.ru/docs/ai/ai-assistant-gigacode/gigacode-cli/skills) and [commands](https://gitverse.ru/docs/ai/ai-assistant-gigacode/gigacode-cli/commands) documentation.
62
+
63
+ The installer registers the viewer skill; it does not install other OpenSpec workflows. Those must be discoverable separately. Registration and refresh behavior are tested locally; indefinite polling in a real GigaCode session still requires an integration test.
64
+
65
+ ### Register a session
66
+
67
+ The agent creates a small report under `.spequi`. This is an illustrative report, not a real attachment identifier:
68
+
69
+ ```json
70
+ {
71
+ "sessionId": "example-attachment",
72
+ "mcps": {
73
+ "supported": false,
74
+ "connections": []
75
+ }
76
+ }
77
+ ```
78
+
79
+ Then it runs this command from the project root:
80
+
81
+ ```bash
82
+ node .spequi/cli.mjs agent report \
83
+ --file .spequi/session-report.json \
84
+ --name Codex
85
+ ```
86
+
87
+ `reportSession()` validates the report and stores the attachment evidence. The essential writes are:
88
+
89
+ ```js
90
+ const report = {
91
+ agent,
92
+ sessionId: id,
93
+ reportedAt: Date.now(),
94
+ mcps: { supported: mcps.supported, connections }
95
+ };
96
+
97
+ await writeJSON(runtime(root, 'agent-session.json'), report);
98
+ await writeJSON(runtime(root, 'agent.json'), {
99
+ agent,
100
+ sessionId: id,
101
+ at: Date.now()
102
+ });
103
+ ```
104
+
105
+ Source: [`reportSession()`](../src/agent-session.mjs).
106
+
107
+ This session ID belongs to the viewer attachment. It is not a provider API credential or an integration with the coding tool's internal conversation ID. The agent retains it and uses it on subsequent polls.
108
+
109
+ ### Wait, then claim
110
+
111
+ ```bash
112
+ node .spequi/cli.mjs agent wait --wait 300 \
113
+ --name Codex --session-id example-attachment
114
+ ```
115
+
116
+ In GigaCode, launch this bounded wait and the retained server using the host Shell tool’s `is_background: true` argument. Keep the task ID and monitor the completion result. The wait refreshes consumer liveness and returns `available: true` when work is available, without claiming it. Once this session receives the output, claim in the foreground:
117
+
118
+ ```bash
119
+ node .spequi/cli.mjs agent next --wait 0 \
120
+ --name Codex --session-id example-attachment
121
+ ```
122
+
123
+ A first-attachment `agent wait --wait 1` checks host completion delivery. If GigaCode does not resume the session automatically, use its task monitor or retained foreground polling; a background process alone cannot wake the model. Attachment lasts while the coding session remains open, including idle periods supported by that notification mechanism.
124
+
125
+ Waits are bounded at five minutes and check for work every 250 ms. An empty result includes queue state. Contention and blocked locks are errors, never an empty queue. An owned active request blocks additional claims. Finish or answer it before claiming another; review partial planning work before any retry.
126
+
127
+ Source: [agent CLI](../bin/spequi.mjs), [root-bound client](../src/agent-client.mjs), and [agent protocol routes](../src/server.mjs).
128
+
129
+ ## 3. A UI action becomes a durable job
130
+
131
+ For example, a user requests an implementation preview. The browser submits the selected change to the lifecycle route:
132
+
133
+ ```js
134
+ // Simplified browser request. The selected change must already be ready.
135
+ await fetch('/api/lifecycle/actions', {
136
+ method: 'POST',
137
+ headers: {
138
+ 'Content-Type': 'application/json',
139
+ Accept: 'application/json',
140
+ 'X-CSRF-Token': document.querySelector('meta[name=csrf-token]').content
141
+ },
142
+ body: JSON.stringify({
143
+ action: 'preview',
144
+ change: 'example-change'
145
+ })
146
+ });
147
+ ```
148
+
149
+ The server checks the local request boundary. The lifecycle layer checks whether the selected action is permitted, then creates a queued job. A simplified shape is:
150
+
151
+ ```json
152
+ {
153
+ "id": "example-job-id",
154
+ "action": "preview",
155
+ "change": "example-change",
156
+ "status": "queued",
157
+ "message": ""
158
+ }
159
+ ```
160
+
161
+ The job is written under `.spequi/jobs/`. It remains available if the browser reloads or no agent is currently polling.
162
+
163
+ Source: [`requestLifecycle()`](../src/lifecycle.mjs) and [`createJob()` / `enqueue()`](../src/jobs.mjs).
164
+
165
+ ## 4. Claiming establishes ownership and selects the skill
166
+
167
+ `claimNext()` updates the heartbeat, acquires the queue lock and selects the oldest queued request. It changes the job to `running`, assigns a random claim token and records the agent attachment identity. Only one workflow runs per project. The short claim releases the queue lock before snapshot copying or plan capture; preparation failures are retained as failed requests. Locks record their process owner and recover abandoned dead-owner or aged legacy empty files. Live lock contention remains explicit.
168
+
169
+ The claim token is required for the agent's subsequent log, question, input and completion commands. A second agent cannot complete the same job just by knowing its ID.
170
+
171
+ The action-to-skill mapping currently includes:
172
+
173
+ ```js
174
+ const skillRoutes = {
175
+ explore: { skill: 'openspec-explore', required: false },
176
+ propose: { skill: 'openspec-propose', required: true },
177
+ preview: { skill: 'openspec-apply-change', required: true },
178
+ verify: { skill: 'openspec-verify-change', required: false },
179
+ archive: { skill: 'openspec-archive-change', required: true },
180
+ impact: { skill: null, required: false },
181
+ 'update-specs': { skill: 'openspec-update-change', required: true },
182
+ 'create-change': { skill: null, required: false },
183
+ 'start-plan': { skill: null, required: false },
184
+ 'plan-next': { skill: null, required: false },
185
+ 'revise-plan': { skill: 'openspec-update-change', required: true },
186
+ 'sync-specs': { skill: 'openspec-sync-specs', required: true }
187
+ };
188
+ ```
189
+
190
+ Full-plan `start-plan` requests use the proposal route. Next-artifact requests use the bounded CLI workflow directly; they do not require another skill.
191
+
192
+ After selecting the route, `claimNext()` constructs the workflow:
193
+
194
+ ```js
195
+ job.workingDirectory = job.action === 'preview'
196
+ ? await createPreview(root, job.id)
197
+ : root;
198
+
199
+ job.workflow = {
200
+ mode: 'same-session',
201
+ ...(job.action === 'start-plan' && job.planMode === 'full'
202
+ ? skillRoutes.propose
203
+ : skillRoutes[job.action]),
204
+ directory: job.workingDirectory,
205
+ protocolDirectory: root,
206
+ change: job.change
207
+ };
208
+
209
+ job.instructions = instructions(job);
210
+ ```
211
+
212
+ Source: [`skillRoutes`, `instructions()` and `claimNext()`](../src/jobs.mjs).
213
+
214
+ ## 5. What “invoke another skill” actually means
215
+
216
+ The CLI returns a job containing a workflow such as this abbreviated example:
217
+
218
+ ```json
219
+ {
220
+ "action": "preview",
221
+ "workflow": {
222
+ "mode": "same-session",
223
+ "skill": "openspec-apply-change",
224
+ "required": true,
225
+ "directory": "/project/.spequi/previews/example-job-id/work",
226
+ "protocolDirectory": "/project",
227
+ "change": "example-change"
228
+ }
229
+ }
230
+ ```
231
+
232
+ The returned instructions explicitly tell the agent to load and follow that installed skill in the current session. They also prohibit starting another coding-agent process, subagent or model endpoint for the handoff.
233
+
234
+ The agent locates the skill through its host's skill discovery. In this repository, reading the apply skill can look like:
235
+
236
+ ```bash
237
+ cat .agents/skills/openspec-apply-change/SKILL.md
238
+ ```
239
+
240
+ **Reading that file does not execute a skill.** It gives the agent instructions. The agent then carries out those instructions through its normal tools: resolving OpenSpec status, reading artifacts, editing the assigned files and running checks.
241
+
242
+ For example, the apply workflow includes commands such as:
243
+
244
+ ```bash
245
+ # Run from the job's workflow.directory, which is the isolated copy for previews.
246
+ openspec context --json
247
+ openspec status --change example-change --json
248
+ openspec instructions apply --change example-change --json
249
+ ```
250
+
251
+ The same agent continues the task after reading the skill. There is no separate skill process to await, no injected slash command, and no new model session whose response must be collected.
252
+
253
+ If a required skill is missing, the agent must report failure instead of claiming the workflow ran. Optional read-only workflows have their documented direct-execution fallback.
254
+
255
+ The behavior contract lives in the [same-session routing section of the skill](../skills/spequi/SKILL.md). It is an agent instruction contract, not a JavaScript skill execution engine.
256
+
257
+ ## 6. Preview work uses two different directories
258
+
259
+ For an implementation preview:
260
+
261
+ | Directory | What happens there |
262
+ | --- | --- |
263
+ | `workflow.directory` | Read the copied planning context, implement, install needed dependencies and run checks inside the isolated copy |
264
+ | `workflow.protocolDirectory` | Run `agent log`, `ask`, `input`, `finish` and `fail` against the original project's queue |
265
+
266
+ All implementation edits, including task checkboxes, stay inside the preview copy. The agent must re-resolve OpenSpec roots there and refuse paths that escape it. The snapshot is not an OS sandbox; the agent must honor that boundary.
267
+
268
+ When the agent finishes, the application freezes the resulting changed files. It does not copy them into the original project automatically. The user reviews the diff and explicitly uses **Apply reviewed preview**, which checks for baseline conflicts.
269
+
270
+ Source: [`createPreview()`, `freezePreview()` and `applyPreview()`](../src/previews.mjs).
271
+
272
+ ### Spec links in implementation previews
273
+
274
+ Before finishing, the agent writes `.spequi/spec-links.json` **inside `workingDirectory`**. The job instructions and installed `spequi` skill include this format:
275
+
276
+ ```json
277
+ {
278
+ "version": 1,
279
+ "links": [
280
+ {
281
+ "file": "src/preferences.js",
282
+ "side": "proposed",
283
+ "start": 12,
284
+ "end": 18,
285
+ "spec": "openspec/changes/email-preferences/specs/email-preferences/spec.md",
286
+ "specStart": 3,
287
+ "specEnd": 9
288
+ }
289
+ ]
290
+ }
291
+ ```
292
+
293
+ Code and spec ranges are one-based and inclusive. Use final proposed line numbers for additions or modifications, or `"side": "current"` and baseline line numbers for deletions. Cite the original copied plan, with a range that explains the changed code. Supported sources are Markdown artifacts in the selected change and main specs under `openspec/specs/**/spec.md`. Do not invent links for unexplained edits.
294
+
295
+ On completion, the viewer validates that code ranges overlap actual changes, retains at most eight links per changed file, and verifies up to 80 spec lines per quote against the baseline manifest. It stores locations and fingerprints in `result.json`; quoted text is always read from the retained baseline. Invalid links are omitted with a notice. The report is optional, limited to 64 KiB and 100 links, and excluded from proposed source and application.
296
+
297
+ Both Unified and Split diffs show **Agent linked** quotes beside the corresponding change blocks. Repeated references link to the first quote. Old previews and imported patches without recorded links can receive **Suggested · file-level** quotes based on explicit file paths, unique filenames, or backticked changed identifiers in the saved change artifacts. These are candidate context, not evidence of why a specific block changed. No match or unavailable snapshot remains explicit; the viewer does not substitute the current working plan.
298
+
299
+ Source: [spec-context.mjs](../src/spec-context.mjs), [spec-context-view.mjs](../src/spec-context-view.mjs).
300
+
301
+ ## 7. Questions wait for an answer through the same job
302
+
303
+ If the selected workflow needs clarification or confirmation, the agent runs the following from `workflow.protocolDirectory`. `JOB_ID` and `CLAIM_TOKEN` stand for values returned by the claim; they are not literal identifiers to reuse.
304
+
305
+ ```bash
306
+ node .spequi/cli.mjs agent ask JOB_ID \
307
+ --token CLAIM_TOKEN \
308
+ --message "Which authentication method should this change support?" \
309
+ --options '["OAuth","Environment variable"]'
310
+ ```
311
+
312
+ `askJob()` verifies ownership, saves the question and transitions the job:
313
+
314
+ ```js
315
+ const question = {
316
+ id: randomUUID(),
317
+ message: message.trim(),
318
+ options,
319
+ askedAt: new Date().toISOString()
320
+ };
321
+
322
+ (job.questions ||= []).push(question);
323
+ job.status = 'awaiting-input';
324
+ ```
325
+
326
+ The agent then waits with:
327
+
328
+ ```bash
329
+ node .spequi/cli.mjs agent input JOB_ID \
330
+ --token CLAIM_TOKEN --wait 300
331
+ ```
332
+
333
+ The CLI checks the owned job every 250 ms until the status changes or the bounded wait expires. If it is still `awaiting-input`, the agent repeats the bounded wait. It does not release the job or make a second claim.
334
+
335
+ The user answers through this protected browser route:
336
+
337
+ ```text
338
+ POST /api/lifecycle/jobs/<job-id>/reply
339
+ ```
340
+
341
+ `answerJob()` checks that the submitted question is still current and unanswered, then stores the answer:
342
+
343
+ ```js
344
+ question.answer = answer.trim();
345
+ question.answeredAt = new Date().toISOString();
346
+ job.status = 'running';
347
+ ```
348
+
349
+ The next `agent input` result contains that retained answer. The current agent reads it and resumes the same workflow. If the request is cancelled instead, the agent stops that work rather than continuing or waiting indefinitely. Browser reloads do not discard the question or answer because both are stored on the job.
350
+
351
+ Source: [`askJob()`, `answerJob()` and `jobInput()`](../src/job-dialogue.mjs), plus the reply route in [src/server.mjs](../src/server.mjs).
352
+
353
+ ## 8. Progress and completion are explicit
354
+
355
+ While working, the agent reports meaningful progress:
356
+
357
+ ```bash
358
+ node .spequi/cli.mjs agent log JOB_ID \
359
+ --token CLAIM_TOKEN \
360
+ --message "Implemented the form; checking validation and keyboard behavior."
361
+ ```
362
+
363
+ On success:
364
+
365
+ ```bash
366
+ node .spequi/cli.mjs agent finish JOB_ID \
367
+ --token CLAIM_TOKEN \
368
+ --message "Implemented the requested scope; checks passed."
369
+ ```
370
+
371
+ On failure:
372
+
373
+ ```bash
374
+ node .spequi/cli.mjs agent fail JOB_ID \
375
+ --token CLAIM_TOKEN \
376
+ --message "The required workflow is unavailable; implementation did not run."
377
+ ```
378
+
379
+ `updateJob()` checks the token and current state. It performs action-specific completion checks, such as requiring actual new planning artifacts, checking full-plan readiness, validating an impact report or freezing an implementation preview. It then persists the result:
380
+
381
+ ```js
382
+ job.status = 'completed';
383
+ job.result = message || 'Completed';
384
+ ```
385
+
386
+ The app waits for this explicit completion. It does not infer completion because the agent read a skill, produced a chat response, checked some task boxes, or stopped polling. The checks also do not prove every instruction was followed or every behavior is correct; verification and code review still matter.
387
+
388
+ After finishing or failing, the agent returns to `agent wait`, then claims in the foreground while attached.
389
+
390
+ Source: [`updateJob()`](../src/jobs.mjs).
391
+
392
+ ## 9. Liveness, MCP evidence and recovery
393
+
394
+ The current heartbeat check is:
395
+
396
+ ```js
397
+ const connected = Boolean(state && Date.now() - state.at < 45000);
398
+ ```
399
+
400
+ A recent heartbeat means the attachment has recently communicated. It does not prove a particular model request is progressing. Likewise, a missing heartbeat does not prove the coding process crashed: a long tool call or an agent that stopped running the loop can also make the attachment appear unresponsive.
401
+
402
+ Polling and owned log/input/question calls refresh the heartbeat. A session report alone means connected, not ready. Ready additionally requires a current consumer wait lease; finishing or disconnecting that wait clears readiness. Working and awaiting-input states follow the owned request. The header exposes queued counts, last heartbeat and blocked/stalled ownership separately. The agent must keep communicating during work; the implementation does not start an independent background heartbeat daemon.
403
+
404
+ MCP status is a separate report. The host must supply authoritative connection evidence; a configured server or a tool catalog alone is insufficient. Reports contain display names and allowed connection states, not credentials or transport configuration. MCP evidence also expires after five minutes and must match the current attachment.
405
+
406
+ The header displays **MCPs** when current connection evidence is unavailable. **0 MCPs** requires a fresh supported report confirming zero connected servers.
407
+
408
+ If the agent becomes unresponsive:
409
+
410
+ 1. Resume the `spequi` skill in the existing coding session.
411
+ 2. Check the agent indicator's recovery details and last heartbeat.
412
+ 3. If an old running request is stuck, stop its agent in the coding tool first. The app permits ending that request after its owner's heartbeat expires, then a new request can be submitted.
413
+
414
+ Ending a request changes queue state; it does not terminate an agent process or undo edits. Reattaching does not automatically reclaim or restart an old running job. The app cannot wake a stopped agent session by itself.
415
+
416
+ Source: [`heartbeat()` and `agentStatus()`](../src/jobs.mjs), [session freshness](../src/agent-session.mjs), and [the header/recovery UI](../public/session.js).
417
+
418
+ ## 10. The complete sequence
419
+
420
+ ```mermaid
421
+ sequenceDiagram
422
+ actor User
423
+ participant UI as Browser UI
424
+ participant App as Local server and job files
425
+ participant Agent as Existing coding-agent session
426
+ participant Skill as Installed SKILL.md
427
+
428
+ User->>Agent: Invoke spequi
429
+ Agent->>App: agent report and monitored agent wait
430
+ User->>UI: Request a workflow
431
+ UI->>App: POST lifecycle action
432
+ App->>App: Persist queued job
433
+ Agent->>App: agent next
434
+ App-->>Agent: Owned job, skill name, directories, instructions
435
+ Agent->>Skill: Read the selected skill
436
+ Skill-->>Agent: Workflow instructions
437
+ Note over Agent: The same agent executes the workflow through its tools
438
+ opt Clarification needed
439
+ Agent->>App: agent ask
440
+ App-->>UI: Question available
441
+ par Agent waits
442
+ loop While awaiting-input
443
+ Agent->>App: agent input --wait 300
444
+ App-->>Agent: Current question and status
445
+ end
446
+ and User answers
447
+ User->>UI: Submit answer
448
+ UI->>App: POST job reply
449
+ end
450
+ Note over Agent,App: The input result contains the retained answer and running status
451
+ end
452
+ Agent->>App: agent log
453
+ Agent->>App: agent finish or agent fail
454
+ App->>App: Validate completion and persist result
455
+ App-->>UI: Updated status and result
456
+ Agent->>App: Return to monitored agent wait
457
+ ```
458
+
459
+ The queue, ownership, persistence, questions and status checks are application code. Carrying out a selected skill is the cooperating agent's work in its existing session. Keeping those responsibilities explicit explains both why the flow works across skill-capable coding tools and why it pauses when the agent stops serving the queue.
package/package.json CHANGED
@@ -1,6 +1,81 @@
1
1
  {
2
2
  "name": "spequi",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "A local workspace for planning, implementation previews, and OpenSpec code review",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/rahulnjs/spequi.git"
8
+ },
9
+ "homepage": "https://github.com/rahulnjs/spequi#readme",
10
+ "bugs": {
11
+ "url": "https://github.com/rahulnjs/spequi/issues"
12
+ },
13
+ "keywords": [
14
+ "openspec",
15
+ "code-review",
16
+ "diff",
17
+ "specifications",
18
+ "htmx",
19
+ "agents"
20
+ ],
21
+ "type": "module",
22
+ "bin": {
23
+ "spequi": "bin/spequi.mjs"
24
+ },
25
+ "exports": {
26
+ ".": "./src/server.mjs"
27
+ },
28
+ "files": [
29
+ "bin/",
30
+ "src/",
31
+ "public/app.css",
32
+ "public/app.js",
33
+ "public/fonts.css",
34
+ "public/fonts/",
35
+ "public/diff.css",
36
+ "public/review.css",
37
+ "public/review.js",
38
+ "public/workflow.js",
39
+ "public/studio.css",
40
+ "public/studio.js",
41
+ "skills/",
42
+ "templates/",
43
+ "README.md",
44
+ "CHANGELOG.md",
45
+ "LICENSE",
46
+ "public/session.js",
47
+ "docs/agent-workflow.md",
48
+ "public/requests.js"
49
+ ],
50
+ "scripts": {
51
+ "prepublishOnly": "npm run check",
52
+ "start": "node bin/spequi.mjs start",
53
+ "check": "node --check bin/spequi.mjs && node --check src/server.mjs && node --check src/project.mjs && node --check src/openspec-cli.mjs && node --check src/spec-context.mjs && node --check src/spec-context-view.mjs && node --check templates/cli.mjs && node --check public/app.js && node --check public/review.js && node --check public/workflow.js && node --check public/studio.js && node --check src/studio-view.mjs && node --check src/studio-plans.mjs && node --check src/studio-documents.mjs && node --check src/creation-view.mjs && node --check src/commands.mjs && node --check src/agent-session.mjs && node --check public/session.js && node --check src/files.mjs && node --check src/jobs.mjs && node --check src/drafts.mjs && node --check src/requests.mjs && node --check src/agent-client.mjs && node --check src/workspace-state.mjs && node --check public/requests.js",
54
+ "test": "node --test test/*.test.mjs",
55
+ "check:package": "node scripts/check-package.mjs",
56
+ "smoke:package": "node scripts/smoke-package.mjs",
57
+ "smoke:npx": "node scripts/smoke-npx.mjs",
58
+ "prepare:test-cli": "node scripts/prepare-test-cli.mjs"
59
+ },
60
+ "engines": {
61
+ "node": ">=20"
62
+ },
63
+ "license": "MIT",
64
+ "publishConfig": {
65
+ "access": "public"
66
+ },
67
+ "dependencies": {
68
+ "chokidar": "^4.0.3",
69
+ "diff": "^8.0.2",
70
+ "hast-util-from-html": "~2.0.3",
71
+ "hast-util-sanitize": "^5.0.2",
72
+ "hast-util-to-html": "^9.0.6",
73
+ "htmx.org": "2.0.11",
74
+ "marked": "^17.0.1",
75
+ "shiki": "^4.6.0",
76
+ "ws": "^8.18.3"
77
+ },
78
+ "devDependencies": {
79
+ "linkedom": "^0.18.12"
80
+ }
81
+ }