@moreih29/nexus-core 0.5.0 → 0.6.0
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/conformance/README.md +10 -17
- package/conformance/lifecycle/README.md +1 -3
- package/conformance/lifecycle/agent-spawn.json +0 -6
- package/conformance/schema/fixture.schema.json +3 -3
- package/docs/consumer-implementation-guide.md +6 -10
- package/docs/nexus-layout.md +0 -15
- package/docs/nexus-outputs-contract.md +5 -25
- package/docs/nexus-state-overview.md +0 -19
- package/manifest.json +46 -46
- package/package.json +1 -1
- package/conformance/lifecycle/session-end.json +0 -32
- package/conformance/lifecycle/session-start.json +0 -38
- package/conformance/state-schemas/runtime.schema.json +0 -34
package/conformance/README.md
CHANGED
|
@@ -105,18 +105,16 @@ Each fixture must contain exactly one of: `action` (single tool invocation), `ev
|
|
|
105
105
|
|
|
106
106
|
## Event-based (Lifecycle) Fixtures
|
|
107
107
|
|
|
108
|
-
|
|
108
|
+
`agent-tracker.json`은 MCP tool이 아니라 harness의 session hook이 관리한다. 이 파일의 구조적 정확성을 검증하기 위해 `action` 대신 `event` 필드를 사용하는 lifecycle fixture를 사용한다.
|
|
109
109
|
|
|
110
110
|
Event fixture는 "harness가 특정 event를 실행한 후 state 파일의 구조가 올바른가"를 선언적으로 명세한다. Tool invocation 없이 event 트리거만으로 postcondition을 검증한다.
|
|
111
111
|
|
|
112
112
|
### Event types
|
|
113
113
|
|
|
114
|
-
`event.type`은 다음
|
|
114
|
+
`event.type`은 다음 3종 중 하나여야 한다:
|
|
115
115
|
|
|
116
116
|
| Event type | 책임 범위 |
|
|
117
117
|
|---|---|
|
|
118
|
-
| `session_start` | `runtime.json` 초기화, `agent-tracker.json` 빈 배열 생성 |
|
|
119
|
-
| `session_end` | `runtime.json` 삭제, `agent-tracker.json` 삭제 |
|
|
120
118
|
| `agent_spawn` | `agent-tracker.json`에 신규 항목 생성 (running 상태) |
|
|
121
119
|
| `agent_complete` | `agent-tracker.json` 항목을 완료 상태로 전환 |
|
|
122
120
|
| `agent_resume` | `agent-tracker.json` 재개 카운터 증가 및 상태 복귀 |
|
|
@@ -125,20 +123,20 @@ Event fixture는 "harness가 특정 event를 실행한 후 state 파일의 구
|
|
|
125
123
|
|
|
126
124
|
```json
|
|
127
125
|
{
|
|
128
|
-
"test_id": "
|
|
126
|
+
"test_id": "agent_spawn_creates_entry",
|
|
129
127
|
"description": "...",
|
|
130
128
|
"covers": {
|
|
131
129
|
"state_schemas": {
|
|
132
|
-
"
|
|
130
|
+
"agent-tracker.schema.json": ["harness_id", "agent_name", "agent_id", "status"]
|
|
133
131
|
}
|
|
134
132
|
},
|
|
135
133
|
"event": {
|
|
136
|
-
"type": "
|
|
134
|
+
"type": "agent_spawn",
|
|
137
135
|
"params": { ... }
|
|
138
136
|
},
|
|
139
137
|
"postcondition": {
|
|
140
138
|
"state_files": {
|
|
141
|
-
".nexus/state/
|
|
139
|
+
".nexus/state/agent-tracker.json": { "$[0].status": "running" }
|
|
142
140
|
}
|
|
143
141
|
}
|
|
144
142
|
}
|
|
@@ -146,12 +144,10 @@ Event fixture는 "harness가 특정 event를 실행한 후 state 파일의 구
|
|
|
146
144
|
|
|
147
145
|
### Lifecycle fixture 목록
|
|
148
146
|
|
|
149
|
-
`conformance/lifecycle/` 디렉토리에
|
|
147
|
+
`conformance/lifecycle/` 디렉토리에 3개 파일이 존재한다:
|
|
150
148
|
|
|
151
149
|
| 파일 | Event type | 검증 대상 |
|
|
152
150
|
|---|---|---|
|
|
153
|
-
| `session-start.json` | `session_start` | `runtime.json` 초기화, `agent-tracker.json` 빈 배열 |
|
|
154
|
-
| `session-end.json` | `session_end` | `runtime.json` 삭제, `agent-tracker.json` 삭제 |
|
|
155
151
|
| `agent-spawn.json` | `agent_spawn` | `agent-tracker.json` 첫 항목 생성 (running 상태) |
|
|
156
152
|
| `agent-complete.json` | `agent_complete` | `agent-tracker.json` 항목 완료 상태 전환 |
|
|
157
153
|
| `agent-resume.json` | `agent_resume` | `agent-tracker.json` 재개 카운터 및 상태 복귀 |
|
|
@@ -281,29 +277,26 @@ for (const fixture of fixtures) {
|
|
|
281
277
|
| `context` | Read or write .nexus/context/ knowledge files | `tools/context.json` |
|
|
282
278
|
| `artifact_write` | Write an artifact output file | `tools/artifact-write.json` |
|
|
283
279
|
|
|
284
|
-
### Lifecycle events (
|
|
280
|
+
### Lifecycle events (3/3 커버됨)
|
|
285
281
|
|
|
286
282
|
| Event type | Fixture file |
|
|
287
283
|
|---|---|
|
|
288
|
-
| `session_start` | `lifecycle/session-start.json` |
|
|
289
|
-
| `session_end` | `lifecycle/session-end.json` |
|
|
290
284
|
| `agent_spawn` | `lifecycle/agent-spawn.json` |
|
|
291
285
|
| `agent_complete` | `lifecycle/agent-complete.json` |
|
|
292
286
|
| `agent_resume` | `lifecycle/agent-resume.json` |
|
|
293
287
|
|
|
294
288
|
### State-schema field coverage
|
|
295
289
|
|
|
296
|
-
|
|
290
|
+
4개 state-schema의 모든 필드가 100% 커버된다:
|
|
297
291
|
|
|
298
292
|
| Schema | 검증 도구 |
|
|
299
293
|
|---|---|
|
|
300
294
|
| `plan.schema.json` | `tools/plan-*.json` fixtures |
|
|
301
295
|
| `tasks.schema.json` | `tools/task-*.json` fixtures |
|
|
302
296
|
| `history.schema.json` | `tools/history-search.json`, `tools/task-close.json` |
|
|
303
|
-
| `runtime.schema.json` | `lifecycle/session-*.json` fixtures |
|
|
304
297
|
| `agent-tracker.schema.json` | `lifecycle/agent-*.json` fixtures |
|
|
305
298
|
|
|
306
|
-
|
|
299
|
+
Validator 통과 결과 예시: `✓ All state-schema fields covered: 4 schemas across fixture suite`
|
|
307
300
|
|
|
308
301
|
## Excluded tools
|
|
309
302
|
|
|
@@ -6,12 +6,10 @@
|
|
|
6
6
|
|
|
7
7
|
| Fixture | Event Type | 검증 대상 |
|
|
8
8
|
|---|---|---|
|
|
9
|
-
| `session-start.json` | `session_start` | `runtime.json` 초기화, `agent-tracker.json` 빈 배열 |
|
|
10
|
-
| `session-end.json` | `session_end` | `runtime.json` 삭제, `agent-tracker.json` 삭제 |
|
|
11
9
|
| `agent-spawn.json` | `agent_spawn` | `agent-tracker.json` 첫 항목 생성 (running 상태) |
|
|
12
10
|
| `agent-complete.json` | `agent_complete` | `agent-tracker.json` 항목 완료 상태 전환 |
|
|
13
11
|
| `agent-resume.json` | `agent_resume` | `agent-tracker.json` 재개 카운터 및 상태 복귀 |
|
|
14
12
|
|
|
15
13
|
## Tool-action 대신 Event 트리거 사용
|
|
16
14
|
|
|
17
|
-
각 fixture는 `action` (tool invocation) 대신 `event` 필드를 사용한다. `
|
|
15
|
+
각 fixture는 `action` (tool invocation) 대신 `event` 필드를 사용한다. `agent-tracker.json`은 harness의 session hook이 관리하며, MCP tool이 직접 쓰지 않는다. Event fixture는 "harness가 event를 실행한 후 state 파일의 구조가 올바른가"를 선언적으로 명세한다.
|
|
@@ -3,12 +3,6 @@
|
|
|
3
3
|
"description": "Verifies that agent_spawn appends a new running agent entry to agent-tracker.json with required fields initialized correctly",
|
|
4
4
|
"precondition": {
|
|
5
5
|
"state_files": {
|
|
6
|
-
".nexus/state/runtime.json": {
|
|
7
|
-
"teams_enabled": true,
|
|
8
|
-
"session_started_at": "2026-04-13T00:00:00.000Z",
|
|
9
|
-
"harness_id": "claude-nexus",
|
|
10
|
-
"harness_version": "0.25.0"
|
|
11
|
-
},
|
|
12
6
|
".nexus/state/agent-tracker.json": []
|
|
13
7
|
}
|
|
14
8
|
},
|
|
@@ -160,14 +160,14 @@
|
|
|
160
160
|
},
|
|
161
161
|
"event": {
|
|
162
162
|
"type": "object",
|
|
163
|
-
"description": "A lifecycle event that triggers harness-level behavior without a direct tool call. Used for verifying
|
|
163
|
+
"description": "A lifecycle event that triggers harness-level behavior without a direct tool call. Used for verifying agent-tracker.json state changes.",
|
|
164
164
|
"additionalProperties": false,
|
|
165
165
|
"required": ["type"],
|
|
166
166
|
"properties": {
|
|
167
167
|
"type": {
|
|
168
168
|
"type": "string",
|
|
169
|
-
"enum": ["
|
|
170
|
-
"description": "Lifecycle event type.
|
|
169
|
+
"enum": ["agent_spawn", "agent_complete", "agent_resume"],
|
|
170
|
+
"description": "Lifecycle event type. agent_spawn/agent_complete/agent_resume: agent instance lifecycle."
|
|
171
171
|
},
|
|
172
172
|
"params": {
|
|
173
173
|
"type": "object",
|
|
@@ -97,7 +97,7 @@ A complete Nexus consumer comprises nine components. They have hard dependencies
|
|
|
97
97
|
| # | Component | Description |
|
|
98
98
|
|---|-----------|-------------|
|
|
99
99
|
| 1 | `.nexus/` Directory Initialization | Create the required directory tree and `.gitignore` at session start |
|
|
100
|
-
| 2 | State File Management | Read/write plan.json, tasks.json, history.json,
|
|
100
|
+
| 2 | State File Management | Read/write plan.json, tasks.json, history.json, agent-tracker.json |
|
|
101
101
|
| 3 | MCP Tool Implementation | Concrete implementations of the 11 abstract Nexus tools |
|
|
102
102
|
| 4 | Capability Mapping | Local file translating abstract capability IDs to concrete disallowed tools |
|
|
103
103
|
| 5 | Agent Catalog | Load nexus-core agents, apply capability-map, register with harness |
|
|
@@ -159,7 +159,6 @@ Nexus state is split into two categories with different scopes, persistence, and
|
|
|
159
159
|
├── state/ ← session-scoped (not git-tracked)
|
|
160
160
|
│ ├── plan.json
|
|
161
161
|
│ ├── tasks.json
|
|
162
|
-
│ ├── runtime.json
|
|
163
162
|
│ ├── agent-tracker.json
|
|
164
163
|
│ ├── tool-log.jsonl
|
|
165
164
|
│ ├── edit-tracker.json
|
|
@@ -182,9 +181,8 @@ At session start, your harness must:
|
|
|
182
181
|
1. Create `.nexus/` if it does not exist.
|
|
183
182
|
2. Create `.nexus/state/` if it does not exist.
|
|
184
183
|
3. Write `.nexus/.gitignore` with content `state/` if the file does not exist.
|
|
185
|
-
4.
|
|
186
|
-
5.
|
|
187
|
-
6. Check for stale state files from a prior crashed session. If `plan.json` or `tasks.json` exist without a running session, warn the user that a previous session may not have closed cleanly.
|
|
184
|
+
4. Initialize `.nexus/state/agent-tracker.json` as an empty array `[]`.
|
|
185
|
+
5. Check for stale state files from a prior crashed session. If `plan.json` or `tasks.json` exist without a running session, warn the user that a previous session may not have closed cleanly.
|
|
188
186
|
|
|
189
187
|
### Key state files
|
|
190
188
|
|
|
@@ -192,7 +190,6 @@ At session start, your harness must:
|
|
|
192
190
|
|------|-------|------------|------------|------------|
|
|
193
191
|
| `state/plan.json` | Session | No | `plan_start` tool | `task_close` tool |
|
|
194
192
|
| `state/tasks.json` | Session | No | `task_add` tool (first call) | `task_close` tool |
|
|
195
|
-
| `state/runtime.json` | Session | No | session_start hook | session_end hook |
|
|
196
193
|
| `state/agent-tracker.json` | Session | No | session_start hook | session_end hook |
|
|
197
194
|
| `state/tool-log.jsonl` | Session | No | post_tool_use hook | session_end hook |
|
|
198
195
|
| `state/edit-tracker.json` | Session | No | post_tool_use hook (first edit) | task_close / session_end |
|
|
@@ -200,7 +197,7 @@ At session start, your harness must:
|
|
|
200
197
|
|
|
201
198
|
### Schema validation
|
|
202
199
|
|
|
203
|
-
JSON Schema definitions for all state files are available in `conformance/state-schemas/`. The schemas cover `plan.json`, `tasks.json`, `history.json`,
|
|
200
|
+
JSON Schema definitions for all state files are available in `conformance/state-schemas/`. The schemas cover `plan.json`, `tasks.json`, `history.json`, and `agent-tracker.json`. Validate state files against these schemas in your test suite.
|
|
204
201
|
|
|
205
202
|
For full lifecycle and tool access details, see [nexus-state-overview.md](./nexus-state-overview.md) and [nexus-layout.md](./nexus-layout.md).
|
|
206
203
|
|
|
@@ -526,7 +523,6 @@ Identify the equivalent events in your harness's plugin system and implement the
|
|
|
526
523
|
**Expected consumer behavior:**
|
|
527
524
|
- Create `.nexus/` and `.nexus/state/` directories if they do not exist.
|
|
528
525
|
- Write `.nexus/.gitignore` with `state/` if it does not exist.
|
|
529
|
-
- Write `.nexus/state/runtime.json` with session metadata: session ID, harness version, start timestamp, and any environment properties your harness tracks.
|
|
530
526
|
- Initialize `.nexus/state/agent-tracker.json` as `[]`.
|
|
531
527
|
- Check for stale state from a prior crashed session: if `plan.json` or `tasks.json` exist, warn the user that these may be leftover from an unclean shutdown.
|
|
532
528
|
- Load the knowledge index: list files in `.nexus/memory/`, `.nexus/context/`, and `.nexus/rules/` to build the reference index that will be injected into subagent spawns.
|
|
@@ -607,7 +603,7 @@ Read-only tools (query tools, status reads) are never blocked by capability gate
|
|
|
607
603
|
**Expected consumer behavior:**
|
|
608
604
|
- Check for pending tasks: if `tasks.json` exists and contains incomplete tasks (status `pending` or `in_progress`), warn the user that the session is ending with unfinished work and suggest calling `task_close` to archive before exiting.
|
|
609
605
|
- Check for an active plan: if `plan.json` exists, warn that the plan session will be lost if not archived.
|
|
610
|
-
- Delete `
|
|
606
|
+
- Delete `agent-tracker.json` (a session-scoped file that has no value beyond the session).
|
|
611
607
|
- Optionally rotate or archive `tool-log.jsonl` if your harness supports log retention.
|
|
612
608
|
- Do not delete `history.json`, `memory/`, `context/`, or `rules/` — these are project-scoped and must persist.
|
|
613
609
|
|
|
@@ -807,7 +803,7 @@ Implement tag detection in your `user_message` hook. When `[plan]` is detected,
|
|
|
807
803
|
|
|
808
804
|
| Event | Minimum required behavior |
|
|
809
805
|
|-------|--------------------------|
|
|
810
|
-
| `session_start` | Create `.nexus/state/` directory;
|
|
806
|
+
| `session_start` | Create `.nexus/state/` directory; initialize `agent-tracker.json` as `[]` |
|
|
811
807
|
| `user_message` | Detect `[plan]` tag; load `skills/nx-plan/body.md`; inject into Lead's context |
|
|
812
808
|
| `session_end` | Check for `tasks.json`; if present with incomplete tasks, warn the user |
|
|
813
809
|
|
package/docs/nexus-layout.md
CHANGED
|
@@ -11,7 +11,6 @@ This document is the canonical reference for the `.nexus/` directory structure u
|
|
|
11
11
|
├── state/ ← session/branch-scoped (ephemeral)
|
|
12
12
|
│ ├── plan.json
|
|
13
13
|
│ ├── tasks.json
|
|
14
|
-
│ ├── runtime.json
|
|
15
14
|
│ ├── agent-tracker.json
|
|
16
15
|
│ ├── tool-log.jsonl
|
|
17
16
|
│ ├── edit-tracker.json
|
|
@@ -73,20 +72,6 @@ This document is the canonical reference for the `.nexus/` directory structure u
|
|
|
73
72
|
|
|
74
73
|
---
|
|
75
74
|
|
|
76
|
-
#### `state/runtime.json`
|
|
77
|
-
|
|
78
|
-
**Purpose.** Harness-internal session state that does not belong in plan or task records (e.g., active agent registrations, session-level flags).
|
|
79
|
-
|
|
80
|
-
**Scope.** Session-scoped.
|
|
81
|
-
|
|
82
|
-
**Git tracking.** Ignored.
|
|
83
|
-
|
|
84
|
-
**Lifecycle.** Created at session start. Discarded at session end.
|
|
85
|
-
|
|
86
|
-
**Owner.** Harness runtime.
|
|
87
|
-
|
|
88
|
-
---
|
|
89
|
-
|
|
90
75
|
#### `state/agent-tracker.json`
|
|
91
76
|
|
|
92
77
|
**Purpose.** Records which subagents have been spawned in the current session, their assigned tasks, and their resume-tier classification.
|
|
@@ -18,7 +18,7 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
|
|
|
18
18
|
| 카테고리 | 책임 주체 | 예시 파일 |
|
|
19
19
|
|---|---|---|
|
|
20
20
|
| Tool-produced | MCP tool 계약 (nexus-tools-contract.md 정의) | `plan.json`, `tasks.json`, `history.json` |
|
|
21
|
-
| Harness-produced | Session hook (하네스 구현 책임) | `
|
|
21
|
+
| Harness-produced | Session hook (하네스 구현 책임) | `agent-tracker.json` |
|
|
22
22
|
| Agent-produced (ephemeral) | `artifact_write` 도구 (에이전트가 호출) | `artifacts/*.md` (등 임의 파일명) |
|
|
23
23
|
|
|
24
24
|
카테고리 간 경계는 "누가 파일을 만드는가"로 정의된다. MCP tool이 직접 write하면 Tool-produced, 하네스 hook이 세션 초기화·종료 시 관리하면 Harness-produced, 에이전트가 `artifact_write`를 통해 기록하면 Agent-produced다.
|
|
@@ -88,25 +88,6 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
|
|
|
88
88
|
|
|
89
89
|
## Harness-produced 산출물
|
|
90
90
|
|
|
91
|
-
### `runtime.json` — 세션 런타임 메타데이터
|
|
92
|
-
|
|
93
|
-
**책임 주체**: Session hook (하네스 구현 책임). 어떤 MCP tool도 이 파일을 write해서는 안 된다.
|
|
94
|
-
|
|
95
|
-
**생성 trigger**: 하네스는 세션 초기화 시 MUST `runtime.json`을 생성해야 한다. 이 파일은 MCP tool 호출이 시작되기 전에 존재해야 한다.
|
|
96
|
-
|
|
97
|
-
**삭제 trigger**: 하네스는 세션 종료 시 MUST `runtime.json`을 삭제해야 한다.
|
|
98
|
-
|
|
99
|
-
**Schema reference**: `conformance/state-schemas/runtime.schema.json`
|
|
100
|
-
|
|
101
|
-
**Interop requirement**:
|
|
102
|
-
- 하네스는 `runtime.json`을 기록할 때 MUST `conformance/state-schemas/runtime.schema.json`에 유효한 JSON을 기록해야 한다.
|
|
103
|
-
- 다른 하네스의 session hook이 이 파일을 read할 경우 schema에 정의된 필드에만 의존해야 한다. MUST NOT schema 외부의 하네스 전용 필드에 의존해서는 안 된다.
|
|
104
|
-
- `runtime.json`은 MUST NOT git-tracked 상태로 commit되어서는 안 된다.
|
|
105
|
-
|
|
106
|
-
**Conformance fixture reference**: 해당 없음. `runtime.json`은 MCP tool behavioral fixture 범위 외에 있으며 하네스 session hook이 전적으로 책임진다.
|
|
107
|
-
|
|
108
|
-
---
|
|
109
|
-
|
|
110
91
|
### `agent-tracker.json` — 에이전트 인스턴스 추적
|
|
111
92
|
|
|
112
93
|
**책임 주체**: Session hook (하네스 구현 책임). 어떤 MCP tool도 이 파일에 직접 write해서는 안 된다.
|
|
@@ -161,7 +142,7 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
|
|
|
161
142
|
|
|
162
143
|
4. **append-only ledger 보전**: `history.json`은 모든 하네스 간에 MUST append-only로 처리되어야 한다. 기존 cycle 레코드를 수정하거나 삭제하는 하네스는 cross-harness 호환성 보장 대상에서 제외된다.
|
|
163
144
|
|
|
164
|
-
5. **session-scoped 파일 격리**: `plan.json`, `tasks.json`, `
|
|
145
|
+
5. **session-scoped 파일 격리**: `plan.json`, `tasks.json`, `agent-tracker.json`, `artifacts/` 디렉토리는 MUST git-tracked 상태로 commit되어서는 안 된다. 이 파일들은 세션 범위에 속하며 프로젝트 영구 기록이 아니다. 하네스는 MUST `.gitignore`에 이 경로들을 포함해야 한다.
|
|
165
146
|
|
|
166
147
|
6. **Tool 이름 참조 금지**: 산출물 파일 내용 안에 harness-specific tool 이름(하네스별 MCP prefix, 하네스별 도구 식별자 등)을 MUST NOT 기록해서는 안 된다. 산출물은 harness-neutral해야 한다.
|
|
167
148
|
|
|
@@ -204,7 +185,7 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
|
|
|
204
185
|
- **MUST**: 하네스 고유 파일(독립 파일 + extension)은 모두 `.nexus/state/{harness-id}/` 하위에만 배치한다.
|
|
205
186
|
- **MUST NOT**: `.nexus/state/` 루트에 신규 하네스 파일을 추가한다.
|
|
206
187
|
- **MUST NOT**: 다른 하네스의 namespace 디렉토리에 쓰거나 읽는다.
|
|
207
|
-
- **MUST NOT**: `{harness-id}/` 하위에서 공통 schema 파일명(plan.json, tasks.json, history.json,
|
|
188
|
+
- **MUST NOT**: `{harness-id}/` 하위에서 공통 schema 파일명(plan.json, tasks.json, history.json, agent-tracker.json)을 재사용한다. 예: `.nexus/state/claude-nexus/plan.json` 금지.
|
|
208
189
|
- **예외**: v0.3.x 이하에 루트 경로로 등록된 legacy 2종(`edit-tracker.json`, `reopen-tracker.json`)은 `task_close` tool 계약에 묶여 있어 backward-compat으로 루트 유지 허용한다. 신규 파일에는 예외 편승 금지.
|
|
209
190
|
|
|
210
191
|
### Archive 정책
|
|
@@ -224,7 +205,6 @@ Nexus 산출물은 생성 책임 주체에 따라 세 카테고리로 분류된
|
|
|
224
205
|
.nexus/state/
|
|
225
206
|
├── plan.json ← 공통, strict
|
|
226
207
|
├── tasks.json
|
|
227
|
-
├── runtime.json
|
|
228
208
|
├── agent-tracker.json
|
|
229
209
|
├── artifacts/
|
|
230
210
|
└── claude-nexus/ ← namespace 디렉토리
|
|
@@ -260,7 +240,7 @@ fixture 통과 = schema field 100% coverage ≠ 산출물 제어 의무 이행.
|
|
|
260
240
|
|
|
261
241
|
fixture는 도구 호출의 반환값과 state file postcondition을 검증하지만, 아래 항목은 fixture만으로 검증되지 않는다.
|
|
262
242
|
|
|
263
|
-
- Harness-produced 산출물(`
|
|
243
|
+
- Harness-produced 산출물(`agent-tracker.json`)의 생성·삭제 타이밍
|
|
264
244
|
- Cross-harness interop 의무(다른 하네스가 생성한 파일을 읽을 수 있는가)
|
|
265
245
|
- Forward-compatible schema 유지 의무
|
|
266
246
|
- git-tracking 격리 의무
|
|
@@ -271,7 +251,7 @@ fixture는 도구 호출의 반환값과 state file postcondition을 검증하
|
|
|
271
251
|
|
|
272
252
|
`conformance/README.md`가 정의하는 schema field coverage 의무: 모든 state-schema field는 최소 하나의 fixture의 `covers` 항목에 등장해야 한다. 이 의무는 fixture suite가 schema 전체를 검증함을 보장한다.
|
|
273
253
|
|
|
274
|
-
본 문서는 이 의무가 **Tool-produced 산출물에 대해서만** 적용됨을 명시한다. Harness-produced 산출물(`
|
|
254
|
+
본 문서는 이 의무가 **Tool-produced 산출물에 대해서만** 적용됨을 명시한다. Harness-produced 산출물(`agent-tracker.json`)의 field coverage는 하네스 자체 테스트 suite의 책임이다.
|
|
275
255
|
|
|
276
256
|
schema field가 신규 추가되었을 때, nexus-core 관리자는 MUST 해당 field를 cover하는 fixture를 추가하거나 기존 fixture를 갱신해야 한다. field를 schema에 추가하면서 fixture를 갱신하지 않는 것은 coverage 의무 위반이다.
|
|
277
257
|
|
|
@@ -91,25 +91,6 @@ The Nexus state layout is divided into two categories:
|
|
|
91
91
|
|
|
92
92
|
---
|
|
93
93
|
|
|
94
|
-
### `.nexus/state/runtime.json`
|
|
95
|
-
|
|
96
|
-
| Attribute | Value |
|
|
97
|
-
|-----------|-------|
|
|
98
|
-
| Scope | Session |
|
|
99
|
-
| Git-tracked | No |
|
|
100
|
-
| Created by | Session start (harness hook) |
|
|
101
|
-
| Deleted by | Session end (harness hook) |
|
|
102
|
-
|
|
103
|
-
**Purpose.** Holds session-level runtime metadata established when the harness initializes (e.g., session identifiers, harness version, environment properties). This file is managed entirely by the harness layer; no Nexus MCP tool writes to it.
|
|
104
|
-
|
|
105
|
-
**Creation trigger.** Written by the harness during session initialization before any tool is called.
|
|
106
|
-
|
|
107
|
-
**Deletion trigger.** Removed by the harness upon session teardown.
|
|
108
|
-
|
|
109
|
-
**Tool access.** Read-only by the harness infrastructure. No Nexus MCP tool listed in this specification reads or writes this file directly.
|
|
110
|
-
|
|
111
|
-
---
|
|
112
|
-
|
|
113
94
|
### `.nexus/state/agent-tracker.json`
|
|
114
95
|
|
|
115
96
|
| Attribute | Value |
|
package/manifest.json
CHANGED
|
@@ -1,24 +1,8 @@
|
|
|
1
1
|
{
|
|
2
|
-
"nexus_core_version": "0.
|
|
3
|
-
"nexus_core_commit": "
|
|
2
|
+
"nexus_core_version": "0.6.0",
|
|
3
|
+
"nexus_core_commit": "bcde383b56308b86006babe73f87fed9222c0761",
|
|
4
4
|
"schema_contract_version": "2.0",
|
|
5
5
|
"agents": [
|
|
6
|
-
{
|
|
7
|
-
"name": "designer",
|
|
8
|
-
"description": "UX/UI design — evaluates user experience, interaction patterns, and how users will experience the product",
|
|
9
|
-
"task": "UI/UX design, interaction patterns, user experience",
|
|
10
|
-
"alias_ko": "디자이너",
|
|
11
|
-
"category": "how",
|
|
12
|
-
"resume_tier": "persistent",
|
|
13
|
-
"model_tier": "high",
|
|
14
|
-
"capabilities": [
|
|
15
|
-
"no_file_edit",
|
|
16
|
-
"no_task_create",
|
|
17
|
-
"no_task_update"
|
|
18
|
-
],
|
|
19
|
-
"id": "designer",
|
|
20
|
-
"body_hash": "sha256:88ac56147d0e5bdf23fa591ce570a9c2d0eb1338df4ec2219f6238ddfcb65df4"
|
|
21
|
-
},
|
|
22
6
|
{
|
|
23
7
|
"name": "architect",
|
|
24
8
|
"description": "Technical design — evaluates How, reviews architecture, advises on implementation approach",
|
|
@@ -50,6 +34,22 @@
|
|
|
50
34
|
"id": "reviewer",
|
|
51
35
|
"body_hash": "sha256:f04d15249601b14046e7e40a4475defb289436c4474afbd89986964f8c3e7c2f"
|
|
52
36
|
},
|
|
37
|
+
{
|
|
38
|
+
"name": "designer",
|
|
39
|
+
"description": "UX/UI design — evaluates user experience, interaction patterns, and how users will experience the product",
|
|
40
|
+
"task": "UI/UX design, interaction patterns, user experience",
|
|
41
|
+
"alias_ko": "디자이너",
|
|
42
|
+
"category": "how",
|
|
43
|
+
"resume_tier": "persistent",
|
|
44
|
+
"model_tier": "high",
|
|
45
|
+
"capabilities": [
|
|
46
|
+
"no_file_edit",
|
|
47
|
+
"no_task_create",
|
|
48
|
+
"no_task_update"
|
|
49
|
+
],
|
|
50
|
+
"id": "designer",
|
|
51
|
+
"body_hash": "sha256:88ac56147d0e5bdf23fa591ce570a9c2d0eb1338df4ec2219f6238ddfcb65df4"
|
|
52
|
+
},
|
|
53
53
|
{
|
|
54
54
|
"name": "strategist",
|
|
55
55
|
"description": "Business strategy — evaluates market positioning, competitive landscape, and business viability of decisions",
|
|
@@ -80,6 +80,21 @@
|
|
|
80
80
|
"id": "engineer",
|
|
81
81
|
"body_hash": "sha256:3d58b1b490c2f93cace2eedd0f04ec000f84514388eb086768cf53f8fa33db01"
|
|
82
82
|
},
|
|
83
|
+
{
|
|
84
|
+
"name": "researcher",
|
|
85
|
+
"description": "Independent investigation — conducts web searches, gathers evidence, and reports findings with citations",
|
|
86
|
+
"task": "Web search, independent investigation",
|
|
87
|
+
"alias_ko": "리서처",
|
|
88
|
+
"category": "do",
|
|
89
|
+
"resume_tier": "persistent",
|
|
90
|
+
"model_tier": "standard",
|
|
91
|
+
"capabilities": [
|
|
92
|
+
"no_file_edit",
|
|
93
|
+
"no_task_create"
|
|
94
|
+
],
|
|
95
|
+
"id": "researcher",
|
|
96
|
+
"body_hash": "sha256:fc79bafec05503327bd51a0b84b6e642d304bd79c45b78db6448b112793c143e"
|
|
97
|
+
},
|
|
83
98
|
{
|
|
84
99
|
"name": "postdoc",
|
|
85
100
|
"description": "Research methodology and synthesis — designs investigation approach, evaluates evidence quality, writes synthesis documents",
|
|
@@ -111,21 +126,6 @@
|
|
|
111
126
|
"id": "tester",
|
|
112
127
|
"body_hash": "sha256:4dd04e1c93ff9c0c9fa6aebb60ece3f9719e82f9714b13feea01b6163633caec"
|
|
113
128
|
},
|
|
114
|
-
{
|
|
115
|
-
"name": "researcher",
|
|
116
|
-
"description": "Independent investigation — conducts web searches, gathers evidence, and reports findings with citations",
|
|
117
|
-
"task": "Web search, independent investigation",
|
|
118
|
-
"alias_ko": "리서처",
|
|
119
|
-
"category": "do",
|
|
120
|
-
"resume_tier": "persistent",
|
|
121
|
-
"model_tier": "standard",
|
|
122
|
-
"capabilities": [
|
|
123
|
-
"no_file_edit",
|
|
124
|
-
"no_task_create"
|
|
125
|
-
],
|
|
126
|
-
"id": "researcher",
|
|
127
|
-
"body_hash": "sha256:fc79bafec05503327bd51a0b84b6e642d304bd79c45b78db6448b112793c143e"
|
|
128
|
-
},
|
|
129
129
|
{
|
|
130
130
|
"name": "writer",
|
|
131
131
|
"description": "Technical writing — transforms research findings, code, and analysis into clear documents and presentations for the intended audience",
|
|
@@ -155,19 +155,6 @@
|
|
|
155
155
|
"id": "nx-run",
|
|
156
156
|
"body_hash": "sha256:6c8d1a36626d4034209ff83780dec6238297ec4710612441b2ef09daac714ca8"
|
|
157
157
|
},
|
|
158
|
-
{
|
|
159
|
-
"name": "nx-plan",
|
|
160
|
-
"description": "Structured multi-perspective analysis to decompose issues, align on decisions, and produce an enriched plan before execution. Plan only — does not execute.",
|
|
161
|
-
"summary": "Structured planning — subagent-based analysis, deliberate decisions, produce execution plan",
|
|
162
|
-
"triggers": [
|
|
163
|
-
"plan"
|
|
164
|
-
],
|
|
165
|
-
"harness_docs_refs": [
|
|
166
|
-
"resume_invocation"
|
|
167
|
-
],
|
|
168
|
-
"id": "nx-plan",
|
|
169
|
-
"body_hash": "sha256:85b858089bd3dc276be61baa3f5265bc107a85470f169983e710fecb404bb4b1"
|
|
170
|
-
},
|
|
171
158
|
{
|
|
172
159
|
"name": "nx-sync",
|
|
173
160
|
"description": "Context knowledge synchronization — scans project state and updates .nexus/context/ design documents",
|
|
@@ -188,6 +175,19 @@
|
|
|
188
175
|
],
|
|
189
176
|
"id": "nx-init",
|
|
190
177
|
"body_hash": "sha256:3c8230ecc0f87c541ec0ff80492a28f28bf173d0b9781901adadfae69a54b8ed"
|
|
178
|
+
},
|
|
179
|
+
{
|
|
180
|
+
"name": "nx-plan",
|
|
181
|
+
"description": "Structured multi-perspective analysis to decompose issues, align on decisions, and produce an enriched plan before execution. Plan only — does not execute.",
|
|
182
|
+
"summary": "Structured planning — subagent-based analysis, deliberate decisions, produce execution plan",
|
|
183
|
+
"triggers": [
|
|
184
|
+
"plan"
|
|
185
|
+
],
|
|
186
|
+
"harness_docs_refs": [
|
|
187
|
+
"resume_invocation"
|
|
188
|
+
],
|
|
189
|
+
"id": "nx-plan",
|
|
190
|
+
"body_hash": "sha256:85b858089bd3dc276be61baa3f5265bc107a85470f169983e710fecb404bb4b1"
|
|
191
191
|
}
|
|
192
192
|
],
|
|
193
193
|
"vocabulary": {
|
package/package.json
CHANGED
|
@@ -1,32 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"test_id": "session_end",
|
|
3
|
-
"description": "Verifies that session_end removes runtime.json and agent-tracker.json, completing the full session lifecycle deletion",
|
|
4
|
-
"precondition": {
|
|
5
|
-
"state_files": {
|
|
6
|
-
".nexus/state/runtime.json": {
|
|
7
|
-
"teams_enabled": true,
|
|
8
|
-
"session_started_at": "2026-04-13T00:00:00.000Z",
|
|
9
|
-
"harness_id": "claude-nexus",
|
|
10
|
-
"harness_version": "0.25.0"
|
|
11
|
-
},
|
|
12
|
-
".nexus/state/agent-tracker.json": []
|
|
13
|
-
}
|
|
14
|
-
},
|
|
15
|
-
"event": {
|
|
16
|
-
"type": "session_end",
|
|
17
|
-
"description": "Harness session hook fires at shutdown, cleaning up all runtime state files"
|
|
18
|
-
},
|
|
19
|
-
"postcondition": {
|
|
20
|
-
"state_files": {
|
|
21
|
-
".nexus/state/runtime.json": null,
|
|
22
|
-
".nexus/state/agent-tracker.json": null
|
|
23
|
-
}
|
|
24
|
-
},
|
|
25
|
-
"covers": {
|
|
26
|
-
"state_schemas": {
|
|
27
|
-
"runtime.schema.json": ["teams_enabled", "session_started_at", "harness_id", "harness_version"],
|
|
28
|
-
"agent-tracker.schema.json": []
|
|
29
|
-
},
|
|
30
|
-
"description": "Covers deletion aspect of the full runtime/agent-tracker lifecycle — absence of both files after session_end"
|
|
31
|
-
}
|
|
32
|
-
}
|
|
@@ -1,38 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"test_id": "session_start",
|
|
3
|
-
"description": "Verifies that session_start writes runtime.json with required fields and initializes agent-tracker.json as an empty array",
|
|
4
|
-
"precondition": {
|
|
5
|
-
"state_files": {
|
|
6
|
-
".nexus/state/runtime.json": null,
|
|
7
|
-
".nexus/state/agent-tracker.json": null
|
|
8
|
-
}
|
|
9
|
-
},
|
|
10
|
-
"event": {
|
|
11
|
-
"type": "session_start",
|
|
12
|
-
"params": {
|
|
13
|
-
"teams_enabled": true,
|
|
14
|
-
"harness_id": "claude-nexus",
|
|
15
|
-
"harness_version": "0.25.0"
|
|
16
|
-
},
|
|
17
|
-
"description": "Harness session hook fires at startup, injecting runtime configuration and initializing the agent registry"
|
|
18
|
-
},
|
|
19
|
-
"postcondition": {
|
|
20
|
-
"state_files": {
|
|
21
|
-
".nexus/state/runtime.json": {
|
|
22
|
-
"$.teams_enabled": true,
|
|
23
|
-
"$.session_started_at": { "type": "iso8601" },
|
|
24
|
-
"$.harness_id": "claude-nexus",
|
|
25
|
-
"$.harness_version": { "type": "string", "minLength": 1 }
|
|
26
|
-
},
|
|
27
|
-
".nexus/state/agent-tracker.json": {
|
|
28
|
-
"$.length": 0
|
|
29
|
-
}
|
|
30
|
-
}
|
|
31
|
-
},
|
|
32
|
-
"covers": {
|
|
33
|
-
"state_schemas": {
|
|
34
|
-
"runtime.schema.json": ["schema_version", "teams_enabled", "session_started_at", "harness_id", "harness_version"],
|
|
35
|
-
"agent-tracker.schema.json": []
|
|
36
|
-
}
|
|
37
|
-
}
|
|
38
|
-
}
|
|
@@ -1,34 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
-
"$id": "conformance/state-schemas/runtime.schema.json",
|
|
4
|
-
"title": "Nexus Runtime State",
|
|
5
|
-
"description": "Schema for .nexus/state/runtime.json — ephemeral runtime configuration written by the harness at session start",
|
|
6
|
-
"type": "object",
|
|
7
|
-
"additionalProperties": false,
|
|
8
|
-
"required": ["teams_enabled", "session_started_at", "harness_id", "harness_version"],
|
|
9
|
-
"properties": {
|
|
10
|
-
"schema_version": {
|
|
11
|
-
"type": "string",
|
|
12
|
-
"pattern": "^\\d+\\.\\d+$",
|
|
13
|
-
"description": "nexus-core version that introduced this schema shape (e.g. '0.5'). Optional in v0.5.0 — candidate for required in v1.0.0 (Phase 2 entry)."
|
|
14
|
-
},
|
|
15
|
-
"teams_enabled": {
|
|
16
|
-
"type": "boolean",
|
|
17
|
-
"description": "Whether multi-agent team orchestration is active in this session"
|
|
18
|
-
},
|
|
19
|
-
"session_started_at": {
|
|
20
|
-
"type": "string",
|
|
21
|
-
"format": "date-time",
|
|
22
|
-
"description": "ISO 8601 timestamp when the current harness session was started"
|
|
23
|
-
},
|
|
24
|
-
"harness_id": {
|
|
25
|
-
"type": "string",
|
|
26
|
-
"pattern": "^[a-z][a-z0-9-]*$",
|
|
27
|
-
"description": "Identifier of the harness that owns this runtime state (e.g. 'claude-nexus', 'opencode-nexus'). Free string — nexus-core does not enumerate harnesses."
|
|
28
|
-
},
|
|
29
|
-
"harness_version": {
|
|
30
|
-
"type": "string",
|
|
31
|
-
"description": "Semver-like version string of the harness plugin that wrote this file."
|
|
32
|
-
}
|
|
33
|
-
}
|
|
34
|
-
}
|