@inharness-ai/claude4spec 1.0.1 → 1.0.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 +12 -0
- package/README.md +117 -18
- package/package.json +4 -3
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [1.0.2] - 2026-05-14
|
|
9
|
+
|
|
10
|
+
### Changed
|
|
11
|
+
- Rewrote `README.md` with new positioning ("plan the whole system before your agent writes a line of code"), badges, requirements section, screenshot embeds, and clearer CLI/MCP guidance.
|
|
12
|
+
- Updated `package.json` `description` to match the new positioning.
|
|
13
|
+
- Polished marketing site (`site/index.html`): chat-overlay mock layout, copy refinements, command-box width.
|
|
14
|
+
|
|
15
|
+
### Added
|
|
16
|
+
- `docs/screenshots/hero.png` and `docs/screenshots/hero-dark.png` referenced by the README.
|
|
17
|
+
|
|
8
18
|
## [1.0.1] - 2026-05-13
|
|
9
19
|
|
|
10
20
|
### Fixed
|
|
@@ -22,3 +32,5 @@ Initial public release.
|
|
|
22
32
|
- Skills `c4s-spec-reader` and `c4s-brief-implementer` for Claude Code integration.
|
|
23
33
|
- Acceptance Criteria entity and tooling.
|
|
24
34
|
- Briefs and patches workflow for spec-driven implementation.
|
|
35
|
+
|
|
36
|
+
[1.0.2]: https://github.com/InHarness/claude4spec/compare/v1.0.1...v1.0.2
|
package/README.md
CHANGED
|
@@ -1,49 +1,148 @@
|
|
|
1
1
|
# claude4spec
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> Plan the whole system before your agent writes a line of code.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/@inharness-ai/claude4spec)
|
|
6
|
+
[](https://nodejs.org)
|
|
7
|
+
[](./LICENSE)
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
`claude4spec` is a local-first planning layer for software built with AI agents. You describe the system as structured entities — endpoints, DTOs, tables, acceptance criteria, UI views — with typed relations and version history. Your agent then generates against the plan, not against chat logs.
|
|
8
10
|
|
|
9
|
-
|
|
10
|
-
-
|
|
11
|
-
|
|
12
|
-
|
|
11
|
+
<picture>
|
|
12
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/hero-dark.png">
|
|
13
|
+
<img alt="claude4spec editor with sidebar, page editor, and agent chat" src="docs/screenshots/hero.png">
|
|
14
|
+
</picture>
|
|
13
15
|
|
|
14
|
-
##
|
|
16
|
+
## Why claude4spec
|
|
17
|
+
|
|
18
|
+
- **Structured plan, not prose.** Endpoints, DTOs, and database tables are first-class records with typed relations, tags, and version history. Your agent queries structure, not paragraphs.
|
|
19
|
+
- **The plan survives refactors.** Rename a slug — every reference updates. Edit a section — dependents are flagged stale. Impact is visible before the agent ships code.
|
|
20
|
+
- **Local-first.** Your spec is a directory of files in your repo, diff-able in PRs. No SaaS, no telemetry, no vendor lock-in.
|
|
21
|
+
- **Agent over MCP.** A built-in MCP server exposes entities to any MCP-aware client — Claude Code, Cursor, Windsurf — alongside the in-app agent.
|
|
22
|
+
|
|
23
|
+
## Install
|
|
15
24
|
|
|
16
25
|
```bash
|
|
17
26
|
npx @inharness-ai/claude4spec
|
|
18
27
|
```
|
|
19
28
|
|
|
20
|
-
|
|
29
|
+
Launches the editor on `http://localhost:3000` and creates a `.claude4spec/` directory (config + SQLite store) in the current working directory.
|
|
21
30
|
|
|
22
|
-
|
|
31
|
+
Global install:
|
|
23
32
|
|
|
24
33
|
```bash
|
|
25
34
|
npm i -g @inharness-ai/claude4spec
|
|
26
35
|
claude4spec
|
|
27
36
|
```
|
|
28
37
|
|
|
38
|
+
## Requirements
|
|
39
|
+
|
|
40
|
+
- Node.js 20+
|
|
41
|
+
- `claude` CLI installed and signed in — required only for the in-app agent; the editor, entities, and graph work standalone.
|
|
42
|
+
- macOS, Linux, Windows.
|
|
43
|
+
- Zero extra cost if you already run Claude Code.
|
|
44
|
+
|
|
29
45
|
## CLIs
|
|
30
46
|
|
|
31
|
-
| Command | Purpose
|
|
32
|
-
|
|
33
|
-
| `claude4spec` | Launch the
|
|
34
|
-
| `c4s` | Read specification entities from the terminal (`c4s endpoint <slug>`).
|
|
35
|
-
| `c4s-mcp` | MCP server exposing
|
|
47
|
+
| Command | Purpose |
|
|
48
|
+
| ------------- | ------------------------------------------------------------------------------ |
|
|
49
|
+
| `claude4spec` | Launch the editor on `http://localhost:3000`. |
|
|
50
|
+
| `c4s` | Read specification entities from the terminal (e.g. `c4s endpoint <slug>`). |
|
|
51
|
+
| `c4s-mcp` | MCP server exposing entities to MCP-aware clients (Cursor, Windsurf, others). |
|
|
52
|
+
|
|
53
|
+
## How it works
|
|
54
|
+
|
|
55
|
+
Three layers, one mental model:
|
|
56
|
+
|
|
57
|
+
- **Pages** — plain `.md` files under `pages/`. Git-friendly, editable in any IDE.
|
|
58
|
+
- **Entities** — endpoints, DTOs, database tables, acceptance criteria, UI views stored in a single SQLite file with slugs, tags, full-text search, and a timeline of versions.
|
|
59
|
+
- **Bridge** — inline XML tags resolve entity slugs into rendered components in the editor and into structured data for the agent. Slug renames propagate across every page automatically.
|
|
60
|
+
|
|
61
|
+
Example page fragment:
|
|
62
|
+
|
|
63
|
+
```markdown
|
|
64
|
+
## User registration
|
|
65
|
+
|
|
66
|
+
The frontend calls <inline_mention type="endpoint" slug="create-user"/> with the payload:
|
|
67
|
+
|
|
68
|
+
<single_element type="dto" slug="CreateUserRequest"/>
|
|
69
|
+
|
|
70
|
+
The response matches any DTO tagged with `auth`:
|
|
71
|
+
|
|
72
|
+
<tagged_list type="dto" tags="auth" filter="or"/>
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## References
|
|
76
|
+
|
|
77
|
+
Six XML reference types — plain tags in markdown, structured pointers for the agent.
|
|
78
|
+
|
|
79
|
+
| Type | When to use |
|
|
80
|
+
| ------------------- | ---------------------------------------------------------- |
|
|
81
|
+
| `inline_mention` | A mention inside a prose sentence. |
|
|
82
|
+
| `single_element` | A standalone card describing one entity. |
|
|
83
|
+
| `element_list` | A hand-picked group of a single type. |
|
|
84
|
+
| `tagged_list` | A dynamic, tag-filtered list of one type. |
|
|
85
|
+
| `tagged_list_mixed` | A multi-type list (endpoints + DTOs) grouped by type. |
|
|
86
|
+
| `section_ref` | A link to another section with a typed relation. |
|
|
36
87
|
|
|
37
88
|
## Claude Code integration
|
|
38
89
|
|
|
39
|
-
|
|
90
|
+
Two skills install with the package:
|
|
40
91
|
|
|
41
92
|
- **`c4s-spec-reader`** — resolves XML entity tags (`<inline_mention/>`, `<single_element/>`, `<tagged_list/>`) in markdown pages into full entity data.
|
|
42
93
|
- **`c4s-brief-implementer`** — implements features described in self-contained briefs from `.claude4spec/briefs/`.
|
|
43
94
|
|
|
44
|
-
##
|
|
95
|
+
## Architecture
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
99
|
+
│ npx @inharness-ai/claude4spec │
|
|
100
|
+
│ │
|
|
101
|
+
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
|
102
|
+
│ │ Sidebar │ │ Editor │ │ Agent │ │
|
|
103
|
+
│ │ Pages + │ │ prose + │ │ in-app + │ │
|
|
104
|
+
│ │ Entities │ │ entity nodes │ │ MCP server │ │
|
|
105
|
+
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
|
106
|
+
│ │ │ │ │
|
|
107
|
+
│ └────────────────────┼──────────────────────┘ │
|
|
108
|
+
│ │ REST + SSE + WS │
|
|
109
|
+
│ ┌────────────▼──────────────┐ │
|
|
110
|
+
│ │ Local API server │ │
|
|
111
|
+
│ └────────────┬──────────────┘ │
|
|
112
|
+
│ ┌───────────────────────┼───────────────────────┐ │
|
|
113
|
+
│ │ │ │ │
|
|
114
|
+
│ ┌─────▼─────┐ ┌──────▼──────┐ ┌───────▼────────┐ │
|
|
115
|
+
│ │ Filesystem│ │ SQLite │ │ Agent runtime │ │
|
|
116
|
+
│ │ pages/*.md│ │ entities.db │ │ (claude CLI) │ │
|
|
117
|
+
│ └───────────┘ └─────────────┘ └────────────────┘ │
|
|
118
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## FAQ
|
|
122
|
+
|
|
123
|
+
**How is this different from a general knowledge base?**
|
|
124
|
+
A general knowledge base stores prose. `claude4spec` is a planning layer with first-class entities, typed relations, slug-rename propagation, and impact analysis — none of which a prose tool gives you.
|
|
125
|
+
|
|
126
|
+
**Is it free?**
|
|
127
|
+
Yes — MIT-licensed. The in-app agent runs against your existing Claude Code session, so there is zero extra cost if you already run Claude Code. The editor, entities, and graph work without any agent.
|
|
128
|
+
|
|
129
|
+
**Isn't this just a wrapper around an agent?**
|
|
130
|
+
No. The editor, entity store, version history, and reference graph are independent of any agent. The in-app agent is one of several ways to interact — you can use the UI alone, or drive entities from Cursor / Windsurf over MCP.
|
|
131
|
+
|
|
132
|
+
**Does it support team collaboration?**
|
|
133
|
+
Through git — both `pages/*.md` and the SQLite file are committed alongside your code. Realtime collaboration (yjs) is on the roadmap, not in today's release.
|
|
134
|
+
|
|
135
|
+
**What happens when I rename an entity slug?**
|
|
136
|
+
The rename propagates across every `pages/*.md` file via the reference layer. Inline mentions, single-element cards, and hand-picked lists all update.
|
|
137
|
+
|
|
138
|
+
**How do I uninstall?**
|
|
139
|
+
`npx` installs nothing globally. To clean up a project, delete its `.claude4spec/` directory and `pages/`.
|
|
140
|
+
|
|
141
|
+
## Links
|
|
45
142
|
|
|
46
|
-
-
|
|
143
|
+
- Landing page: [`site/index.html`](./site/index.html)
|
|
144
|
+
- Issues: <https://github.com/InHarness/claude4spec/issues>
|
|
145
|
+
- Changelog: [`CHANGELOG.md`](./CHANGELOG.md)
|
|
47
146
|
|
|
48
147
|
## License
|
|
49
148
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@inharness-ai/claude4spec",
|
|
3
|
-
"version": "1.0.
|
|
4
|
-
"description": "Local-first
|
|
3
|
+
"version": "1.0.2",
|
|
4
|
+
"description": "Plan the whole system before your agent writes a line of code. Local-first planning layer with structured entities and typed relations.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Michael Tomala <mi.tomala@gmail.com>",
|
|
7
7
|
"homepage": "https://github.com/InHarness/claude4spec#readme",
|
|
@@ -55,9 +55,9 @@
|
|
|
55
55
|
"@inharness-ai/agent-adapters": "^0.4.0",
|
|
56
56
|
"@inharness-ai/agent-chat": "^0.2.0",
|
|
57
57
|
"@modelcontextprotocol/sdk": "^1.29.0",
|
|
58
|
+
"@monaco-editor/react": "^4.7.0",
|
|
58
59
|
"@openai/codex-sdk": "^0.130.0",
|
|
59
60
|
"@opencode-ai/sdk": "^1.14.48",
|
|
60
|
-
"@monaco-editor/react": "^4.7.0",
|
|
61
61
|
"@tanstack/react-query": "^5.62.11",
|
|
62
62
|
"@tanstack/react-router": "^1.168.23",
|
|
63
63
|
"@tiptap/extension-placeholder": "^2.11.3",
|
|
@@ -101,6 +101,7 @@
|
|
|
101
101
|
"@types/ws": "^8.5.13",
|
|
102
102
|
"@vitejs/plugin-react": "^4.3.4",
|
|
103
103
|
"autoprefixer": "^10.4.20",
|
|
104
|
+
"playwright": "^1.60.0",
|
|
104
105
|
"postcss": "^8.4.49",
|
|
105
106
|
"tailwindcss": "^3.4.17",
|
|
106
107
|
"tsx": "^4.19.2",
|