spequi 0.1.1 → 0.1.2

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.2 — 2026-11-14
4
+
5
+ - Sharpen the README opening, show existing screenshots, and move detailed guidance into dedicated docs.
6
+ - Make the Spequi skill the recommended startup path; clarify agent setup, upgrades, analytics, and preview boundaries.
7
+ - Fix the package audit to allow the published changelog.
8
+
3
9
  ## 0.1.1 — 2026-11-14
4
10
 
5
11
  - Group requests by spec, prioritize unresolved work, and mark pending inbox items in the header.
package/README.md CHANGED
@@ -2,291 +2,112 @@
2
2
 
3
3
  # Spequi
4
4
 
5
- **Plan with your agent. Review every change.**
5
+ **Understand the spec. Guide your agent. Review the implementation.**
6
6
 
7
- A local workspace for planning, implementing, and reviewing [OpenSpec](https://openspec.dev/) changes with the coding agent you already use.
7
+ Spequi brings [OpenSpec](https://openspec.dev/) documents, agent conversations, and code diffs into one local workspace.
8
+ Read the plan, give precise feedback, and review the implementation against requirements with the coding agent you already use.
8
9
 
10
+ [![npm](https://img.shields.io/npm/v/spequi?color=cb3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/spequi)
9
11
  [![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-43853d?logo=node.js&logoColor=white)](https://nodejs.org/)
10
12
  [![License: MIT](https://img.shields.io/badge/License-MIT-3f62b5)](LICENSE)
11
- [![No build step](https://img.shields.io/badge/Frontend-No_build_step-626f83)](#stack)
12
-
13
- [Get started](#get-started) · [Planning and review](#planning-and-review) · [Features](#features) · [How it works](#how-it-works) · [Agent setup](#attach-your-agent)
13
+ [![No build step](https://img.shields.io/badge/Frontend-no%20build%20step-626f83)](docs/architecture.md)
14
14
 
15
15
  </div>
16
16
 
17
- ## Planning and review
18
-
19
- Start with **New spec** to shape an idea with your agent. Ideas save automatically under **Drafts** in the left panel; return there to resume unfinished planning or delete a draft. Draft deletion can also remove its generated planning files after confirmation.
17
+ <table>
18
+ <tr>
19
+ <td><img src="docs/screenshots/build-light.png" alt="Planning a spec beside the agent conversation"></td>
20
+ <td><img src="docs/screenshots/file-review-light.png" alt="Reviewing a diff with spec context and inline comments"></td>
21
+ </tr>
22
+ <tr>
23
+ <td align="center"><sub>Plan beside your agent</sub></td>
24
+ <td align="center"><sub>Review the diff against the spec</sub></td>
25
+ </tr>
26
+ </table>
27
+
28
+ ## Quickstart
29
+
30
+ ```bash
31
+ cd /path/to/your-project # a project that contains OpenSpec files
32
+ npx spequi@latest init # sets up .spequi/ and registers the agent skill
33
+ ```
20
34
 
21
- Select an existing change to read documents, inspect proposed code, and leave feedback. The planning workspace provides spec refinement, implementation preview, validation, and archive. New specs and existing changes use the same planning workspace, retained previews, and conversation. Applying reviewed files always requires explicit confirmation.
35
+ Then invoke the Spequi skill **inside your coding agent**, with the same project open:
22
36
 
23
- Open **Requests** in the header for an inbox grouped by spec. Questions, failures, and stalled work appear first, followed by running and queued work. The badge counts specs needing attention. A collapsed **Recent** section holds the latest five completed specs; cancelled and older work stays in **All history**, with status filters and pagination. **Dismiss** clears settled items from the inbox while preserving requests, previews, and comments. Cancel and supported retry actions remain available; destructive deletion is confined to history. Active work stays visible while you browse another spec. Partially edited planning work must be reviewed before continuing.
37
+ | Agent | Run after `init` |
38
+ | --- | --- |
39
+ | GigaCode CLI | `/skills spequi` or `/spequi` |
40
+ | Claude Code | `/spequi` |
41
+ | Codex | `$spequi` |
42
+ | Other skill-capable agents | load `.agents/skills/spequi/SKILL.md` |
24
43
 
25
- ![An unfinished spec in Drafts, with its planning document beside the retained conversation.](https://raw.githubusercontent.com/rahulnjs/spequi/master/docs/screenshots/build-light.png)
44
+ The skill starts the local server, shares its URL, and handles requests from the UI. Open the URL it provides, normally **http://127.0.0.1:4310**. Keep the agent session running while you work. Reload your agent if the new skill does not appear.
26
45
 
27
- _New spec: shape the plan beside your agent conversation and resume it from Drafts._
46
+ > **Requirements:** Node.js 20+ and npm. For agent-driven work you also need the OpenSpec CLI and its workflow skills
47
+ > (current OpenSpec needs Node.js 22.12+). See [Getting started](docs/getting-started.md).
28
48
 
29
- ![Spequi showing a highlighted implementation diff, an inline review comment, dependency impact, and review feedback.](https://raw.githubusercontent.com/rahulnjs/spequi/master/docs/screenshots/file-review-light.png)
49
+ ## Why Spequi?
30
50
 
31
- _Review: inspect a saved implementation and leave feedback. Screenshots use a local example project._
51
+ Coding agents are fast. Reading what they changed, and checking it against what you *asked for*, is the slow part.
52
+ A plain diff shows **what** changed, not **why**.
32
53
 
33
- <details>
34
- <summary>See planning and review in dark theme</summary>
54
+ - **Spec-linked diffs.** Linked code blocks show the requirement or scenario behind them, with source path and line range. Link coverage depends on the preview; suggested file-level context is labelled separately.
55
+ - **Review implementation before applying.** Implementation previews use an isolated copy. Applying is a separate, explicit step with conflict checks and backups. Planning requests update specification files in your project.
56
+ - **Bring your own agent.** GigaCode, Claude Code, Codex, or any skill-capable agent. No extra model endpoint or provider API key to configure.
57
+ - **Local workspace.** The UI binds to `127.0.0.1`. Browsing and offline analysis do not upload source. Your attached agent may send source to its provider; optional model generation sends selected context to your configured endpoint.
35
58
 
36
- ![The draft planning flow in dark theme.](https://raw.githubusercontent.com/rahulnjs/spequi/master/docs/screenshots/build-dark.png)
59
+ Spequi sends usage and failure analytics, including project folder names, Git user names when configured, and a persistent identifier shared across projects on the same machine account. Source files, prompts, and review comments are excluded. See [Security and limits](docs/security.md#analytics).
37
60
 
38
- ![The same OpenSpec review workspace in dark mode.](https://raw.githubusercontent.com/rahulnjs/spequi/master/docs/screenshots/file-review-dark.png)
61
+ ## How it works
39
62
 
40
- </details>
63
+ 1. **Plan.** Click **New spec**, describe an idea, and shape the plan beside your agent's conversation. Drafts save automatically.
64
+ 2. **Preview.** Open **Implement** and request a preview. The agent builds in a separate copy of your project.
65
+ 3. **Review.** Read Proposal, Design and Tasks, then inspect real diffs with available spec links, dependency impact, and inline comments.
66
+ 4. **Apply.** Confirm explicitly. Spequi checks hashes and baseline conflicts, writes the files, and keeps recoverable backups. Then validate and archive.
41
67
 
42
68
  ## Features
43
69
 
44
- | | What you can do |
45
- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
46
- | **Run the lifecycle** | Create and resume drafts, or open an existing change’s Build workspace to refine the spec, preview and apply code, then validate and archive. Answer agent questions in the app. |
47
- | **Read the plan** | Browse Proposal, Design, Tasks, active changes, archived changes, and specifications. Switch between rendered Markdown and source. |
48
- | **Review real code** | Compare the current project with an agent's isolated implementation. Use highlighted Unified or Split diffs, changed-word emphasis, context folding, and line wrapping. |
49
- | **Trace changes to the spec** | Read quoted requirements beside changed code blocks, with source lines from the preview’s saved plan. Agent links and suggested file context are labelled separately. |
50
- | **Understand impact** | Inspect direct and downstream dependencies, related tests, and export changes, with explicit static-analysis limitations. |
51
- | **Leave precise feedback** | Add file notes or inline comments on code, Markdown passages, and source ranges. Keep the exact reviewed source context. |
52
- | **Refine the specification** | Export an immutable Markdown review brief or queue a planning update for your agent to reconcile with OpenSpec. |
53
- | **Stay in your workflow** | Use a local Node server and your current skill-capable agent. Switch between light and dark mode. |
54
-
55
- ## Get started
56
-
57
- Requires **Node.js 20+**, npm, and a target project containing OpenSpec files.
58
-
59
- For agent-driven planning and implementation, also install the OpenSpec CLI and make the required OpenSpec workflow skills available to your coding agent, then attach it with the `spequi` skill. Initializing this package installs the UI skill and command wrappers; OpenSpec setup and its workflow skills are separate. Browsing, review, offline affected-file analysis, and patch import work without an attached agent.
60
-
61
- The current OpenSpec CLI [requires Node.js 22.12+](https://github.com/Fission-AI/OpenSpec/blob/main/package.json), independently of this UI’s Node.js 20 minimum. Use Node.js 22.12+ for the complete setup with current OpenSpec.
62
-
63
- ### Initialize with npx
64
-
65
- ```sh
66
- cd /path/to/your-project
67
- npx spequi@latest init
68
- ```
70
+ - **Full lifecycle:** drafts, spec refinement, implementation preview, validate, archive
71
+ - **Unified and split diffs** with syntax highlighting, changed-word emphasis, folding and wrapping
72
+ - **Impact analysis:** direct and downstream dependencies, related tests, export changes
73
+ - **Precise feedback:** comments on files, code ranges and Markdown passages; export a review brief or queue a spec update
74
+ - **Requests inbox:** see questions, failures and running work across all specs
75
+ - **Works offline:** browsing, review, affected-file analysis and patch import need no agent
76
+ - **Light and dark themes**
69
77
 
70
- Then invoke the registered viewer skill in your agent, or start the server directly:
78
+ ## Documentation
71
79
 
72
- ```sh
73
- node .spequi/server.mjs
74
- ```
80
+ | | |
81
+ | --- | --- |
82
+ | [Getting started](docs/getting-started.md) | Install, initialize, attach an agent, what `init` creates |
83
+ | [Planning workflow](docs/planning.md) | New specs, drafts, slash commands, planning stages |
84
+ | [Review workflow](docs/review.md) | Diffs, spec context, comments, requests inbox |
85
+ | [Offline tools and model preview](docs/offline-and-model.md) | Affected-file analysis, patch import, optional model endpoint |
86
+ | [Agent workflow](docs/agent-workflow.md) | Queue, heartbeat, questions, MCP reports |
87
+ | [Security and limits](docs/security.md) | Local data, boundaries, known limitations |
88
+ | [Architecture](docs/architecture.md) | Stack, repo layout, development, packaging |
75
89
 
76
- A global installation is also supported:
90
+ ## Status
77
91
 
78
- ```sh
79
- npm install -g spequi
80
- spequi init
81
- spequi start
82
- ```
92
+ Spequi is early. It is tested with Claude Code and Codex flows; continuous polling in a real GigaCode session and
93
+ native Windows execution are not yet verified. Static impact analysis can miss dynamic references and aliases.
94
+ See [Security and limits](docs/security.md) for the full list.
83
95
 
84
- Automatic browser opening is not implemented; open the printed URL or use your agent's browser capabilities.
96
+ Feedback and bug reports are welcome in [Issues](https://github.com/rahulnjs/spequi/issues).
85
97
 
86
- ### Run from source
98
+ ## Contributing
87
99
 
88
- ```sh
100
+ ```bash
89
101
  git clone https://github.com/rahulnjs/spequi.git
90
102
  cd spequi
91
103
  npm ci
92
-
93
- node bin/spequi.mjs init --root "/path/to/your-project"
94
- node bin/spequi.mjs start --root "/path/to/your-project"
95
- ```
96
-
97
- Open the printed URL, normally **http://127.0.0.1:4310**. To choose another port, add `--port 4311` to the start command.
98
-
99
- Point the viewer at your own project. This repository keeps its runtime source and README screenshots; it does not ship sample OpenSpec plans. An empty project shows setup guidance. Initialize OpenSpec separately when needed.
100
-
101
- ## Attach your agent
102
-
103
- GigaCode uses monitored Shell calls with `is_background: true` for the server and five-minute `agent wait` calls. Waiting does not claim a job; the agent claims it in the foreground after receiving the result. Background completion must resume the host session for unattended idle attachment to work. The skill includes a check and a foreground fallback. Closing the coding agent pauses consumption and leaves requests saved.
104
-
105
-
106
- The viewer uses **your existing coding agent**. It does not launch a model or require a separate provider API key.
107
-
108
- | Agent | Invoke after initialization |
109
- | -------------------------- | ---------------------------------------------------------------------- |
110
- | Claude Code | `/spequi`; use `/spequi init` for setup |
111
- | Codex | `$spequi`, or select the viewer skill |
112
- | Sber/GitVerse GigaCode CLI | `/skills spequi` or `/spequi` |
113
- | Other skill-capable agents | Load `.agents/skills/spequi/SKILL.md` using the tool's own convention |
114
-
115
- Reload your agent if newly generated commands or skills do not appear. Command discovery and slash syntax depend on the agent.
116
-
117
- The skill starts the local server and consumes queued requests. Without an attached agent, browsing, review, offline affected-file analysis, and patch import remain available. Agent implementation and planning requests wait in the queue; optional configured model generation can produce proposed edits directly.
118
-
119
- The attached session also runs the installed skills selected by each job: `openspec-apply-change` for preview implementation, `openspec-propose` for proposals, `openspec-update-change` for feedback, and `openspec-archive-change` for archive requests. Exploration and verification use their corresponding installed workflows when available, with read-only fallbacks; impact reports run directly. The agent loads the selected skill in the same session, reports the result, and resumes polling. No second agent process or model connection is started for this handoff. Required missing workflows produce a failed job with an explanation; they are not installed automatically. Preview workflow edits and task updates stay in the isolated copy; viewer log/finish/fail commands run from the original project. Refresh an initialized project's skill with `node .spequi/cli.mjs skill install` to receive these routing instructions.
120
-
121
- ## How it works
122
-
123
- 1. **Initialize and attach.** Create project-local launchers and connect your existing coding agent with the `spequi` skill.
124
- 2. **Plan in Build.** Choose **New spec** to describe an idea, or open an existing change. Create the next planning artifact or a full plan; answer your agent's questions in the conversation.
125
- 3. **Preview in Build.** Open **Implement** and request a preview. Your agent works in a separate project copy; finishing freezes the proposed files for inspection.
126
- 4. **Inspect in Review.** Read Proposal, Design, and Tasks, then inspect Files with actual diffs, quoted spec context at linked change blocks, dependency impact, and inline comments.
127
- 5. **Refine.** Export feedback or select **Update spec** to request a planning revision from that exact snapshot. Generate a fresh preview when the plan changes.
128
- 6. **Apply and finish in Build.** Explicitly apply the reviewed preview, validate the spec, verify implementation with your agent, then sync or archive when ready.
129
-
130
- Spec revisions and implementation previews are separate actions. Exporting feedback does not edit a specification or apply code. The underlying apply API checks retained hashes and baseline conflicts before writing reviewed files and keeping recoverable backups.
131
-
132
- ### Spec context in diffs
133
-
134
- In both modes, linked change blocks show the requirement, scenario, or planning decision behind the edit. Each quote includes its source path and line range from the preview’s retained baseline. Collapse a quote to focus on code; repeated links point back to the first quote.
135
-
136
- The attached agent records code-to-spec locations while implementing. Older previews and imported patches can show **Suggested · file-level** context when the saved plan mentions the file or a changed symbol. Suggestions need reviewer confirmation. Files without a supported match say so explicitly. Refresh an initialized project's skill with `node .spequi/cli.mjs skill install` to enable recorded links for new previews. See the [agent metadata format](docs/agent-workflow.md#spec-links-in-implementation-previews).
137
-
138
- ### What initialization creates
139
-
140
- ```text
141
- your-project/
142
- ├── .spequi/
143
- │ ├── config.json # Port and initialized viewer version
144
- │ ├── cli.mjs # Project command launcher
145
- │ ├── server.mjs # Server launcher
146
- │ ├── jobs/ # Queued agent requests
147
- │ ├── previews/ # Isolated baseline and proposed files
148
- │ └── backups/ # Recoverable applied-file backups
149
- ├── .agents/skills/spequi/SKILL.md
150
- ├── .claude/commands/spequi.md
151
- └── .gigacode/
152
- ├── skills/spequi/SKILL.md
153
- └── commands/spequi.md
154
- ```
155
-
156
- Feedback storage is created when needed. Initialization installs the `/spequi` command wrappers and adds `/.spequi/`, `/.agents/`, `/.claude/`, and `/.gigacode/` to the project's `.gitignore`. Existing ignore rules are preserved; files already tracked by Git remain tracked.
157
-
158
- GigaCode registration follows its documented [skill discovery](https://gitverse.ru/docs/ai/ai-assistant-gigacode/gigacode-cli/skills) and [custom command format](https://gitverse.ru/docs/ai/ai-assistant-gigacode/gigacode-cli/commands), including `{{args}}` for command arguments. `init` and `skill install` register the project; `skill install --global` writes registrations under the user's home directory. Existing initialized projects can refresh with `node .spequi/cli.mjs skill install` when their initialized runtime includes this change. Registration is tested; continuous polling in a real GigaCode session has not yet been verified. Required OpenSpec workflows must be installed separately and discoverable by GigaCode.
159
-
160
- Repeat initialization preserves Spequi configuration, comments, previews, application files, and custom launchers. An explicit reinitialization refreshes managed launchers and agent registration. If the original cached package disappears, the launcher can retrieve the initialized version through npm; registry access is needed for that recovery.
161
-
162
- ## Planning workflow
163
-
164
- ### Start a spec from an idea
165
-
166
- Choose **New spec** in the left panel. Describe the idea and give it an unused lowercase change name. **Start with the next artifact** is the default; **Generate the full plan** requests all required planning artifacts. Continue queues one owned planning request for the attached agent. Its questions stay in the app, replies survive reloads, and the generated change opens in its draft planning workspace when the request completes. Partial plans offer the next schema-ready artifact; planning never automatically starts implementation.
167
-
168
- The **Commands** picker in the planning workspace and slash commands use the same guarded operations. Supported commands are `/new`, `/explore <question>`, `/continue`, `/propose`, `/update <revision>`, `/apply`, `/status`, `/validate`, `/verify`, `/sync`, and `/archive`. `/opsx:<name>` and `/opsx-<name>` aliases also work inside the app. These are app commands, independent of the host's slash-command installation. `/apply` generates an isolated implementation preview; writing reviewed files still requires the separate Apply confirmation. Status and validation use the installed local OpenSpec CLI. Other commands wait for the existing agent session.
169
-
170
- Planning versions are retained under `.spequi/studio/`. A revision stores exact Markdown before a planning request and after it completes; pending writes are not shown as completed revisions. The most recent 40 versions are retained, with at most 8 MiB of planning documents per version. This is local review evidence; the files under `openspec/` remain the source of truth.
171
-
172
- New specs and unfinished drafts keep **Shape spec**, **Implement**, and **Validate & archive** in their header, with the plan beside its retained conversation. Select an existing change in the left panel for document and code review; open **Build** to refine it or run the remaining lifecycle steps. The project panel keeps the same layout in both flows.
173
-
174
- In **Shape spec**, select a planning artifact tab and use **Revise spec** to request an update, or **Ask a question** for a read-only exploration. Changes appear as highlighted sections and a document summary. Capabilities with multiple documents show file tabs below their artifact tab. **Planning actions** offers the next artifact or full plan. Documents remain read-only.
175
-
176
- In **Implement**, generate an isolated preview and choose its version. Browse changed files directly beneath the selected change in the left panel; filenames show their folder and edit counts, with no file search field. The **Files** button brings that list into view for the selected preview. Previous/next file controls, the selected file and diff tools stay above the independently scrolling code. Selecting a file keeps the same preview and planning workspace. Inspect the actual diff, then explicitly confirm **Apply reviewed preview**. A changed spec or source conflict prevents application. **Validate & archive** distinguishes local spec validation from agent implementation verification and exposes sync and archive with their normal prerequisites. Archive confirmations appear in the conversation. **New spec** starts the idea-to-plan flow; old lifecycle URLs redirect to the shared planning workspace.
177
-
178
- Status, task readiness, and strict specification validation use the installed `openspec` CLI locally, with no agent required. Missing/incompatible CLI capabilities disable those actions with an explanation while documents and saved diffs remain readable. Spec validation checks requirements; checked task boxes alone do not prove implementation correctness. Setup and administration stay outside this UI.
179
-
180
- Reasoning and writing requests use the current session running the viewer skill. Refresh the project skill after upgrading with `node .spequi/cli.mjs skill install`. Required workflows must already be installed; the viewer never launches another agent for a skill handoff. The agent uses `agent ask <id> --token <token> --message "question" [--options '["Yes","No"]']`, then `agent input <id> --token <token> --wait 300` until the app replies. The existing job resumes with the same ownership token; queued and awaiting-input requests can be cancelled. A running request can be ended only after its owning session’s heartbeat expires; stop the old agent in your coding tool first, since ending a request does not terminate its process or undo edits. Keep the agent session attached to continue waiting work.
181
-
182
- Implementation previews still use isolated copies and apply only through an explicit, conflict-checked action. Offline affected-file analysis, optional model proposals, and patch import are available in the shared Implement stage; generated source remains reviewable in Files.
183
-
184
- A saved preview becomes stale when its planning documents change. Generate a fresh preview before applying. Spec updates stay in the same page, with active questions and results shown in the main flow.
185
-
186
- ## Review workflow
187
-
188
- Choose **Review — Inspect & comment** to examine a change through **Proposal**, **Design**, **Tasks**, and **Files**. Documents support rendered Markdown and source. Files compares the current and proposed versions with Unified or Split diffs, syntax highlighting, changed-word emphasis, folding, and wrapping. The inspector follows the selected file with dependency impact and saved comments.
189
-
190
- Comment on a whole file, a code range, or a passage in Proposal or Design. Notes retain the exact reviewed version. **Export MD** downloads a feedback brief; **Update spec** queues a planning revision for the attached agent. Return to Build to continue the conversation, generate a new implementation preview, or apply reviewed code.
191
-
192
- ## Agent-free analysis and previews
193
-
194
- Under **Build → Implement → Offline analysis and preview tools**, **Analyze affected files** matches the selected change's planning documents to current source without an agent or network. It explains explicit paths, named symbols, related text, and local dependencies separately from actual changed files. Analysis scans at most 1,000 text files, 512 KB per file, and 8 MiB of source; planning documents are limited to 2 MiB total. Exclusions, skipped files, unresolved references, and stale inputs are disclosed. Dynamic references, aliases, external packages, and dependencies outside supported JS/TS, CSS, and HTML forms can be missed.
195
-
196
- **Import patch** stages a unified patch in a separate project copy without an agent. Patches can add, modify, and delete up to 30 eligible UTF-8 files, within a 1 MiB patch/proposed-content limit. Renames are represented as deletion and addition. Review the saved diff, export it, add comments, or explicitly apply it using the existing baseline conflict checks. A failed import does not publish a partially completed preview.
197
-
198
- For optional generation without an agent session, add `previewModel` to `.spequi/config.json` while preserving its other settings:
199
-
200
- ```json
201
- {
202
- "version": 1,
203
- "port": 4310,
204
- "previewModel": {
205
- "endpoint": "http://127.0.0.1:11434/v1/chat/completions",
206
- "model": "your-installed-model",
207
- "timeoutMs": 120000
208
- }
209
- }
210
- ```
211
-
212
- The endpoint must accept Chat Completions-compatible JSON and return text at `choices[0].message.content`; a compatible local runtime can keep generation offline. No model is installed or downloaded by the viewer. Hosted endpoints require HTTPS; plain HTTP is accepted only for loopback hosts. If authentication is required, set `"apiKeyEnv": "SPEQUI_PREVIEW_API_KEY"` and supply that environment variable to the viewer process. Credentials stay server-side; do not put an API key in the endpoint URL.
213
-
214
- Analyze first, select between 1 and 12 candidate files, and choose **Generate with model**. This action sends the change's planning documents and the selected files to the displayed destination. It sends no other source context. The combined input is limited to 256 KB; output is limited to 30 edits and 1 MiB of proposed source. Stale analyses require a new scan. Existing files outside the selected context, secrets, planning artifacts, agent configuration, and escaping paths cannot be edited. Eligible new source files can be added. The model returns file contents only: the viewer runs no tools, shell commands, installations, or implementation tests. Generated and imported previews show their origin and unrun-check status; review and test before applying.
215
-
216
- All UI styles, scripts (including HTMX), and fonts are served by the local viewer. DM Sans and IBM Plex Mono are bundled with their licenses, so the installed UI needs no CDN or internet access. Installation and package recovery through npm still require registry access unless the packages are already available locally.
217
-
218
- ## Stack
219
-
220
- **Node.js ES modules · server-rendered HTML · HTMX · WebSockets · plain CSS and JavaScript**
221
-
222
- No frontend compilation or hosted backend. Runtime dependencies handle watching, Markdown sanitization, syntax highlighting, diffs, and WebSocket transport.
223
-
224
- ```text
225
- bin/ Executable CLI
226
- src/ Server, project reader, previews, impact, and review implementation
227
- public/ Runtime styles and browser JavaScript
228
- skills/ Maintained portable agent skill
229
- templates/ Self-contained project launcher template
230
- docs/ README screenshots; excluded from the npm package
231
- ```
232
-
233
- ## Local data and boundaries
234
-
235
- Spequi sends usage and failure events to `https://sber.eval.best/spequi/event`. These include a persistent identifier shared across projects on the same machine account, the project folder name, Git `user.name` when configured, timestamps, and event-specific identifiers, counts, and failure categories. Source files, prompts, and review comments are excluded. Delivery is best effort, with no retries. See [release notes](CHANGELOG.md).
236
-
237
- - The server binds to `127.0.0.1`; mutations require local Host/Origin checks and a session token.
238
- - `.spequi/` contains local configuration, requests, previews, feedback, and backups. Keep it out of Git.
239
- - Browsing and offline analysis do not upload project source. Explicit model generation sends the planning documents and selected source to the configured endpoint. Your attached agent retains its own provider and permission settings.
240
- - A preview copy is not an OS security sandbox. The agent must honor its assigned working directory.
241
- - Static impact evidence does not establish complete runtime behavior, dynamic references, aliases, or external-package effects. Scan limitations remain visible.
242
- - LF and CRLF comparisons use normalized display lines; retained hashes, patches, and application preserve the exact reviewed bytes. Native Windows execution remains a release verification item.
243
-
244
- ## Development and packaging
245
-
246
- ```sh
247
- npm ci
248
104
  npm run check
249
- npm pack --dry-run
250
- npm publish --dry-run
251
- ```
252
-
253
- There is no build step. `package.json.files` limits the npm archive to runtime code/assets, the portable skill, launcher template, package metadata, README, and license. Screenshots and local development/sample data are excluded. Publication runs syntax checks first.
254
-
255
- ## Naming and project data
256
-
257
- The app is **Spequi**. Its npm package, shell command, and agent skill are **spequi**: use `$spequi` in Codex, or `/spequi` in tools that support those command wrappers. Reload your agent after registration if it has not discovered the new skill.
258
-
259
- Initialization creates `.spequi/` for local configuration, queued jobs, previews, comments, and backups. Run `spequi init` to refresh managed launchers and skill registrations; custom launchers are preserved. The agent command is `/spequi`.
260
-
261
- Spequi starts fresh in `.spequi/`. Initialization does not import, move, rename, or delete data from earlier tools.
262
-
263
- ## Agent liveness and MCP reports
264
-
265
- For the code-level attachment, skill routing, question and completion flow, see [How the agent workflow works](docs/agent-workflow.md).
266
-
267
- The header's agent indicator reflects a recent agent heartbeat, independently of the browser connection to the local server. It distinguishes live, working, awaiting an answer, not responding, and unattached. Connection details show the last heartbeat and MCP metadata reported by the current session. **Reconnect agent** opens instructions to resume the spequi skill in the same coding session, with a **Check connection** action. Requests and answers stay saved; the viewer does not restart an agent automatically.
268
-
269
- The agent can write a credential-free report under `.spequi`, then run:
270
-
271
- ```sh
272
- node .spequi/cli.mjs agent report --file .spequi/session-report.json --name "Spequi Agent"
273
- ```
274
-
275
- For example, when the host provides authoritative connection status:
276
-
277
- ```json
278
- {
279
- "sessionId": "a-stable-random-id-for-this-attachment",
280
- "mcps": {
281
- "supported": true,
282
- "connections": [{ "name": "Filesystem", "status": "connected" }]
283
- }
284
- }
105
+ node bin/spequi.mjs init --root /path/to/test-project
285
106
  ```
286
107
 
287
- Allowed MCP statuses are `connected`, `disconnected`, `unavailable`, and `unknown`. Only display names and statuses are accepted; omit credentials, server URLs, environment variables and transport configuration. When the agent host cannot enumerate connection status, report `{"mcps":{"supported":false,"connections":[]}}` instead. A tool catalog or configured server alone is insufficient evidence of a healthy connection. Retain the returned session ID for report refreshes, pass it as `agent next --session-id <id>` and use the same agent name when polling, and refresh at least every five minutes or when connections change. Missing, expired and disconnected-session reports display unknown rather than a fabricated count. Reporting does not replace serving the agent queue.
108
+ Open the test project in your coding agent and invoke the Spequi skill to start the workspace.
288
109
 
289
- The header uses **MCPs** when the current session has not supplied connection evidence; the details explain why. **0 MCPs** is shown only when a fresh supported report confirms zero connections. Build keeps the current conversation and document independently scrollable, compacts the composer and action footer, shows current progress without expanding Activity, and collapses older completed exchanges. New documents use normal prose; changed-section highlights begin with revisions to existing text.
110
+ See [Architecture](docs/architecture.md) for the repo layout.
290
111
 
291
112
  ## License
292
113
 
@@ -8,16 +8,16 @@ There is no `await invokeSkill()` implementation. A skill is an instruction docu
8
8
 
9
9
  ## 1. The components
10
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) |
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
21
 
22
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
23
 
@@ -91,14 +91,14 @@ const report = {
91
91
  agent,
92
92
  sessionId: id,
93
93
  reportedAt: Date.now(),
94
- mcps: { supported: mcps.supported, connections }
94
+ mcps: { supported: mcps.supported, connections },
95
95
  };
96
96
 
97
- await writeJSON(runtime(root, 'agent-session.json'), report);
98
- await writeJSON(runtime(root, 'agent.json'), {
97
+ await writeJSON(runtime(root, "agent-session.json"), report);
98
+ await writeJSON(runtime(root, "agent.json"), {
99
99
  agent,
100
100
  sessionId: id,
101
- at: Date.now()
101
+ at: Date.now(),
102
102
  });
103
103
  ```
104
104
 
@@ -132,17 +132,17 @@ For example, a user requests an implementation preview. The browser submits the
132
132
 
133
133
  ```js
134
134
  // Simplified browser request. The selected change must already be ready.
135
- await fetch('/api/lifecycle/actions', {
136
- method: 'POST',
135
+ await fetch("/api/lifecycle/actions", {
136
+ method: "POST",
137
137
  headers: {
138
- 'Content-Type': 'application/json',
139
- Accept: 'application/json',
140
- 'X-CSRF-Token': document.querySelector('meta[name=csrf-token]').content
138
+ "Content-Type": "application/json",
139
+ Accept: "application/json",
140
+ "X-CSRF-Token": document.querySelector("meta[name=csrf-token]").content,
141
141
  },
142
142
  body: JSON.stringify({
143
- action: 'preview',
144
- change: 'example-change'
145
- })
143
+ action: "preview",
144
+ change: "example-change",
145
+ }),
146
146
  });
147
147
  ```
148
148
 
@@ -172,18 +172,18 @@ The action-to-skill mapping currently includes:
172
172
 
173
173
  ```js
174
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 },
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
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 }
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
187
  };
188
188
  ```
189
189
 
@@ -192,18 +192,17 @@ Full-plan `start-plan` requests use the proposal route. Next-artifact requests u
192
192
  After selecting the route, `claimNext()` constructs the workflow:
193
193
 
194
194
  ```js
195
- job.workingDirectory = job.action === 'preview'
196
- ? await createPreview(root, job.id)
197
- : root;
195
+ job.workingDirectory =
196
+ job.action === "preview" ? await createPreview(root, job.id) : root;
198
197
 
199
198
  job.workflow = {
200
- mode: 'same-session',
201
- ...(job.action === 'start-plan' && job.planMode === 'full'
199
+ mode: "same-session",
200
+ ...(job.action === "start-plan" && job.planMode === "full"
202
201
  ? skillRoutes.propose
203
202
  : skillRoutes[job.action]),
204
203
  directory: job.workingDirectory,
205
204
  protocolDirectory: root,
206
- change: job.change
205
+ change: job.change,
207
206
  };
208
207
 
209
208
  job.instructions = instructions(job);
@@ -258,10 +257,10 @@ The behavior contract lives in the [same-session routing section of the skill](.
258
257
 
259
258
  For an implementation preview:
260
259
 
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 |
260
+ | Directory | What happens there |
261
+ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
262
+ | `workflow.directory` | Read the copied planning context, implement, install needed dependencies and run checks inside the isolated copy |
263
+ | `workflow.protocolDirectory` | Run `agent log`, `ask`, `input`, `finish` and `fail` against the original project's queue |
265
264
 
266
265
  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
266
 
@@ -316,11 +315,11 @@ const question = {
316
315
  id: randomUUID(),
317
316
  message: message.trim(),
318
317
  options,
319
- askedAt: new Date().toISOString()
318
+ askedAt: new Date().toISOString(),
320
319
  };
321
320
 
322
321
  (job.questions ||= []).push(question);
323
- job.status = 'awaiting-input';
322
+ job.status = "awaiting-input";
324
323
  ```
325
324
 
326
325
  The agent then waits with:
@@ -343,7 +342,7 @@ POST /api/lifecycle/jobs/<job-id>/reply
343
342
  ```js
344
343
  question.answer = answer.trim();
345
344
  question.answeredAt = new Date().toISOString();
346
- job.status = 'running';
345
+ job.status = "running";
347
346
  ```
348
347
 
349
348
  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.
@@ -379,8 +378,8 @@ node .spequi/cli.mjs agent fail JOB_ID \
379
378
  `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
379
 
381
380
  ```js
382
- job.status = 'completed';
383
- job.result = message || 'Completed';
381
+ job.status = "completed";
382
+ job.result = message || "Completed";
384
383
  ```
385
384
 
386
385
  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.
@@ -457,3 +456,42 @@ sequenceDiagram
457
456
  ```
458
457
 
459
458
  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.
459
+
460
+ # Agent liveness and MCP reports
461
+
462
+ > Merge this section into your existing `docs/agent-workflow.md` (it already covers queue, skill routing and spec links).
463
+
464
+ The header's agent indicator reflects a recent agent heartbeat, independent of the browser's connection to the local server.
465
+ It distinguishes: live, working, awaiting an answer, not responding, and unattached.
466
+ Connection details show the last heartbeat and MCP metadata reported by the current session.
467
+
468
+ **Reconnect agent** opens instructions to resume the spequi skill in the same coding session, with a **Check connection** action.
469
+ Requests and answers stay saved. Spequi never restarts an agent automatically.
470
+
471
+ ## Reporting MCP status
472
+
473
+ The agent can write a credential-free report under `.spequi`, then run:
474
+
475
+ ```bash
476
+ node .spequi/cli.mjs agent report --file .spequi/session-report.json --name "Spequi Agent"
477
+ ```
478
+
479
+ ```json
480
+ {
481
+ "sessionId": "a-stable-random-id-for-this-attachment",
482
+ "mcps": {
483
+ "supported": true,
484
+ "connections": [{ "name": "Filesystem", "status": "connected" }]
485
+ }
486
+ }
487
+ ```
488
+
489
+ - Allowed statuses: `connected`, `disconnected`, `unavailable`, `unknown`.
490
+ - Only display names and statuses are accepted. Omit credentials, server URLs, environment variables and transport configuration.
491
+ - If the host cannot enumerate connection status, report `{"mcps":{"supported":false,"connections":[]}}`.
492
+ - A tool catalog or a configured server alone is not evidence of a healthy connection.
493
+ - Keep the returned session ID for refreshes, pass it as `agent next --session-id <id>`, and use the same agent name when polling.
494
+ - Refresh at least every five minutes or whenever connections change.
495
+ - Missing, expired or disconnected-session reports show as unknown, never as a fabricated count.
496
+ - The header shows **MCPs** when the session has not supplied evidence, and **0 MCPs** only when a fresh supported report confirms zero.
497
+ - Reporting does not replace serving the agent queue.
package/package.json CHANGED
@@ -1,23 +1,25 @@
1
1
  {
2
2
  "name": "spequi",
3
- "version": "0.1.1",
4
- "description": "A local workspace for planning, implementation previews, and OpenSpec code review",
3
+ "version": "0.1.2",
4
+ "description": "Local web UI for OpenSpec: plan specs with your coding agent, review spec-linked diffs, apply only what you approve.",
5
+ "keywords": [
6
+ "openspec",
7
+ "spec-driven-development",
8
+ "code-review",
9
+ "coding-agents",
10
+ "ai-agents",
11
+ "claude-code",
12
+ "codex",
13
+ "diff-viewer"
14
+ ],
15
+ "homepage": "https://github.com/rahulnjs/spequi#readme",
5
16
  "repository": {
6
17
  "type": "git",
7
18
  "url": "git+https://github.com/rahulnjs/spequi.git"
8
19
  },
9
- "homepage": "https://github.com/rahulnjs/spequi#readme",
10
20
  "bugs": {
11
21
  "url": "https://github.com/rahulnjs/spequi/issues"
12
22
  },
13
- "keywords": [
14
- "openspec",
15
- "code-review",
16
- "diff",
17
- "specifications",
18
- "htmx",
19
- "agents"
20
- ],
21
23
  "type": "module",
22
24
  "bin": {
23
25
  "spequi": "bin/spequi.mjs"