@coralai/sps-cli 0.51.0 → 0.51.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.
Files changed (7) hide show
  1. package/dist/console-assets/assets/index-DRhdpvew.css +10 -0
  2. package/dist/console-assets/assets/{index-Gjim492C.js → index-WUGCBcyb.js} +3 -3
  3. package/dist/console-assets/index.html +2 -2
  4. package/package.json +1 -1
  5. package/skills/sps-memory/SKILL.md +151 -63
  6. package/skills/sps-pipeline/SKILL.md +350 -148
  7. package/dist/console-assets/assets/index-DlwaKe2l.css +0 -10
package/dist/console-assets/index.html CHANGED
@@ -7,8 +7,8 @@
7
7
  <link rel="preconnect" href="https://fonts.googleapis.com">
8
8
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
9
9
  <link href="https://fonts.googleapis.com/css2?family=Fredoka:wght@400;500;600;700&family=DM+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
10
- <script type="module" crossorigin src="/assets/index-Gjim492C.js"></script>
11
- <link rel="stylesheet" crossorigin href="/assets/index-DlwaKe2l.css">
10
+ <script type="module" crossorigin src="/assets/index-WUGCBcyb.js"></script>
11
+ <link rel="stylesheet" crossorigin href="/assets/index-DRhdpvew.css">
12
12
  </head>
13
13
  <body>
14
14
  <div id="root"></div>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@coralai/sps-cli",
3
- "version": "0.51.0",
3
+ "version": "0.51.2",
4
4
  "description": "SPS CLI — AI-driven development pipeline orchestrator",
5
5
  "type": "module",
6
6
  "main": "dist/main.js",
package/skills/sps-memory/SKILL.md CHANGED
@@ -2,97 +2,145 @@
2
2
  name: sps-memory
3
3
  description: |
4
4
  SPS persistent memory system — read and write project knowledge, user preferences,
5
- and agent experience across sessions. Proactively use when the user mentions remembering
6
- something, project conventions, past decisions, or when you discover important information
7
- worth persisting. (🪸 Coral SPS)
5
+ and per-agent observations across sessions. **Auto-injected into Worker prompts**
6
+ by StageEngine (no manual fetch needed inside cards). Proactively use when the
7
+ user mentions remembering something, project conventions, past decisions, or when
8
+ you discover non-obvious information worth persisting. (🪸 Coral SPS, v0.51+)
8
9
  ---
9
10
 
10
- # SPS Memory System
11
+ # SPS Memory (v0.51 — auto-injected into Worker prompts)
11
12
 
12
- You have a three-layer persistent memory system at `~/.coral/memory/`.
13
- Use `cat` to read and `bash` to write. Use `mkdir -p` if a directory does not exist.
13
+ A 3-layer markdown-on-disk persistence used to carry **non-obvious, reusable facts**
14
+ across sessions and across pipeline cards. Lives entirely under `~/.coral/memory/`;
15
+ each layer is a flat directory of `*.md` files plus a `MEMORY.md` index.
14
16
 
15
- ## Three Layers
17
+ ## When SPS injects this for you (pipeline mode)
16
18
 
17
- ### 1. User Memory (`~/.coral/memory/user/`)
18
- Cross-project personal preferences. Shared across all projects and agents.
19
- - Coding style, language preferences, workflow habits
20
- - Example: "prefers Chinese comments", "uses strict TypeScript"
19
+ When a card is dispatched, `StageEngine.buildStagePrompt` calls
20
+ `buildFullMemoryContext({ project, cardSeq })` and folds the result into the prompt's
21
+ `knowledge` section — **before** the task description. So inside a card, **you
22
+ already see relevant memory**; you don't need to `cat` it.
21
23
 
22
- ### 2. Agent Memory (`~/.coral/memory/agents/<session-name>/`)
23
- Your personal experience as a daemon instance. Only you read this.
24
- - User interaction patterns you've observed
25
- - Pitfalls you've encountered
26
- - Communication preferences specific to this user-agent relationship
24
+ What you still need to do:
25
+ 1. **Read more context if relevant** — the auto-inject only includes the headline
26
+ index + recent items. To see a specific memory file, `cat` it.
27
+ 2. **Write new memories when discovery happens** — covered below.
27
28
 
28
- ### 3. Project Memory (`~/.coral/memory/projects/<project-name>/`)
29
- Project-specific knowledge. Shared across all workers on this project.
30
- - Conventions, architecture decisions, lessons learned, external references
29
+ In `sps agent` (harness) mode, memory is **not** auto-injected. Use the `cat`
30
+ patterns at the bottom to pull what you need.
31
31
 
32
- To detect the current project, check if cwd matches any `PROJECT_DIR` in `~/.coral/projects/*/conf`.
32
+ ## Three layers
33
33
 
34
- ## File Format
34
+ | Layer | Path | Scope | When to use |
35
+ |---|---|---|---|
36
+ | **User** | `~/.coral/memory/user/` | Cross-project preferences | Coding style, language, workflow habits ("prefers Chinese comments", "uses strict TypeScript") |
37
+ | **Agent** | `~/.coral/memory/agents/<agentId>/` | Per daemon instance / per-agent identity | User-interaction patterns you observed, communication preferences specific to this agent ↔ user pair |
38
+ | **Project** | `~/.coral/memory/projects/<project-name>/` | Per project | Conventions, architecture decisions, lessons learned, external resource pointers |
35
39
 
36
- Each memory is a markdown file with YAML frontmatter:
40
+ To detect which project the cwd belongs to: scan `~/.coral/projects/*/conf` for a
41
+ matching `PROJECT_DIR=`. Pipeline workers always know via `$SPS_PROJECT` env var.
42
+
43
+ ## File format
37
44
 
38
45
  ```markdown
39
46
  ---
40
47
  name: Short title
41
- description: One-line summary for index search
48
+ description: One-line summary (used by index + future fuzzy search)
42
49
  type: convention | decision | lesson | reference
43
50
  ---
44
51
 
45
- Content here. For decision/lesson types, include:
46
- **Why:** reason
47
- **Scope:** where this applies
48
- ```
49
-
50
- ## Index File (MEMORY.md)
52
+ Body. For decision/lesson types, include:
51
53
 
52
- Each memory directory has a `MEMORY.md` index. After writing a memory file, add one line:
53
-
54
- ```
55
- - [Title](filename.md) — one-line description
54
+ **Why:** the reason / past incident driving this
55
+ **Scope:** where this applies (file glob, module, role, ...)
56
56
  ```
57
57
 
58
- ## Memory Types
58
+ Filename = slugified `name` (lowercase, hyphens). The CLI does this for you; if
59
+ writing by hand, keep it under 50 chars.
60
+
61
+ ## Memory types
59
62
 
60
63
  | Type | Decay | Use for |
61
- |------|-------|---------|
64
+ |---|---|---|
62
65
  | `convention` | Never | Project rules, coding standards, naming conventions |
63
66
  | `decision` | Slow | Architecture choices, technology selections |
64
- | `lesson` | 30 days | Pitfalls, debugging discoveries, things that went wrong |
65
- | `reference` | Never | Links to external docs, tools, dashboards |
67
+ | `lesson` | 30 days | Pitfalls, debugging discoveries, things that broke |
68
+ | `reference` | Never | Pointers to external dashboards, runbooks, dependencies |
69
+
70
+ `convention` and `reference` never expire; `decision` is auto-deprioritized after
71
+ months of no touch; `lesson` decays at 30 days unless re-read.
72
+
73
+ ## Index file (`MEMORY.md`)
74
+
75
+ Each layer's directory has a `MEMORY.md` index — one line per memory file:
76
+
77
+ ```markdown
78
+ - [API uses camelCase](api-naming.md) — All REST endpoints use camelCase
79
+ - [Auth middleware location](auth-middleware.md) — middleware/auth.ts; not in routes
80
+ ```
81
+
82
+ After writing a memory file, **always** append (or update) one line in the
83
+ sibling `MEMORY.md`. The auto-injector reads `MEMORY.md` first to decide what to
84
+ load.
66
85
 
67
- ## When to Read
86
+ ## When to read
68
87
 
69
- - At the start of a conversation or task, read the relevant MEMORY.md index
70
- - Before making a recommendation that could conflict with past decisions
71
- - When the user asks "do you remember" or references prior work
88
+ - At the start of a card or task — auto-injected for you in pipeline mode
89
+ - Before answering a question that could conflict with prior decisions
90
+ - When the user says "do you remember", "we agreed", "我们之前说过"
91
+ - Before recommending a pattern that might violate a known convention
72
92
 
73
93
  ```bash
74
- # Read project memory index
94
+ # Project memory index
75
95
  cat ~/.coral/memory/projects/<project>/MEMORY.md 2>/dev/null
76
96
 
77
- # Read user preferences
97
+ # User preferences (always-applicable)
78
98
  cat ~/.coral/memory/user/MEMORY.md 2>/dev/null
79
99
 
80
- # Read a specific memory file
100
+ # Specific memory file
81
101
  cat ~/.coral/memory/projects/<project>/api-naming.md
82
102
  ```
83
103
 
84
- ## When to Write
104
+ ## When to write
105
+
106
+ Only when **all** are true:
107
+ - The fact is **non-obvious** (not derivable from `git log`, code, or CLAUDE.md)
108
+ - It will be **reusable** across future sessions / cards
109
+ - It's **stable enough** to outlive the current task
85
110
 
86
- - User states a project rule or preference → `convention`
87
- - A technical choice is made or confirmed → `decision`
88
- - Something unexpected happened or a workaround was found → `lesson`
89
- - An external resource location is mentioned → `reference`
90
- - You observe a user communication pattern → write to agent memory
111
+ Trigger words / situations:
112
+ | Situation | Type |
113
+ |---|---|
114
+ | User states a project rule or preference | `convention` |
115
+ | Architectural choice discussed and agreed | `decision` |
116
+ | Bug fixed where the root cause was sneaky / non-obvious | `lesson` |
117
+ | User points to an external dashboard, runbook, or repo | `reference` |
118
+ | You observe a user communication style worth keeping | agent-layer note |
91
119
 
92
- Most conversations do NOT need memory. Only save non-obvious, future-useful information.
120
+ **Most cards do NOT need memory.** If you're unsure → don't write. Memory is
121
+ expensive (read budget on every future card). Empty growth is worse than no
122
+ growth.
123
+
124
+ ## Writing patterns
125
+
126
+ ### Via CLI (recommended for project memories)
127
+
128
+ ```bash
129
+ sps memory add <project> \
130
+ --type convention \
131
+ --name "API uses camelCase" \
132
+ --description "All REST endpoints use camelCase naming" \
133
+ --body "REST API endpoints use camelCase. No snake_case.\n\n**Why:** Frontend SDK auto-generates types from API schema."
134
+ ```
135
+
136
+ The CLI:
137
+ - Slugifies name → filename
138
+ - Writes the file with proper frontmatter
139
+ - Appends/updates the line in `MEMORY.md`
140
+
141
+ ### By hand (for user / agent layer)
93
142
 
94
143
  ```bash
95
- # Write a memory
96
144
  mkdir -p ~/.coral/memory/projects/my-project
97
145
  cat > ~/.coral/memory/projects/my-project/api-naming.md << 'EOF'
98
146
  ---
@@ -105,21 +153,61 @@ REST API endpoints use camelCase. No snake_case.
105
153
  **Why:** Frontend SDK auto-generates types from API schema.
106
154
  EOF
107
155
 
108
- # Update index
109
- echo '- [API naming](api-naming.md) — camelCase for all REST endpoints' >> ~/.coral/memory/projects/my-project/MEMORY.md
156
+ # Update index — keep entry one line, ≤ 100 chars
157
+ echo '- [API naming](api-naming.md) — camelCase for all REST endpoints' \
158
+ >> ~/.coral/memory/projects/my-project/MEMORY.md
110
159
  ```
111
160
 
112
- ## What NOT to Save
161
+ ## What NOT to save
113
162
 
114
- - Code structure, file paths (derivable from reading code)
115
- - Git history (use `git log`)
116
- - Temporary debugging state
117
- - Anything already in CLAUDE.md or project docs
163
+ - **Code structure / file paths** — derivable from `Read` / `Glob`
164
+ - **Git history / blame** — use `git log`
165
+ - **Temporary debugging state** — use the conversation
166
+ - **Anything already in CLAUDE.md or `docs/`** — don't duplicate
167
+ - **Card or task state** — that's runtime, not knowledge
168
+ - **Wiki content** — if it belongs in structured knowledge (modules / decisions /
169
+ lessons cross-linked), use the **wiki-update skill** instead. Memory is for
170
+ ad-hoc / personal facts; Wiki is for structured project knowledge with
171
+ cross-references and 5-layer prompt injection.
118
172
 
119
- ## CLI Commands
173
+ ## CLI commands
120
174
 
121
175
  ```bash
122
- sps memory list <project> # Show memory index
123
- sps memory context <project> # Generate full memory context
124
- sps memory add <project> --type convention --name "title" --body "content"
176
+ sps memory list <project> # show project memory index
177
+ sps memory list # global view (user)
178
+ sps memory list --agent <agentId> # include agent layer
179
+
180
+ sps memory context <project> # ★ preview full inject (debug)
181
+ sps memory context <project> --card <seq> # card-scoped (matches Worker prompt)
182
+
183
+ sps memory add <project> \
184
+ --type convention \
185
+ --name "title" \
186
+ --description "one-line summary" \
187
+ --body "content"
125
188
  ```
189
+
190
+ ## Memory vs Wiki — pick the right tool
191
+
192
+ | Need | Use |
193
+ |---|---|
194
+ | User said "remember I prefer ..." | Memory (`user` or `project` layer) |
195
+ | Decision recorded in a card review | Could be either; prefer **wiki/decisions/** if it's about the project's architecture (linkable, surfacable to all future cards), memory for personal/team workflow choices |
196
+ | Bug fix with non-obvious root cause | **wiki/lessons/** (cross-linked, structured) — memory `lesson` is fallback when wiki not enabled |
197
+ | Module purpose / API contract summary | **wiki/modules/** |
198
+ | External dashboard URL | Memory `reference` |
199
+ | Personal coding style note | Memory (`user`) |
200
+
201
+ **Wiki requires `WIKI_ENABLED=true` in project conf** (v0.51+). When wiki is on,
202
+ prefer it for project-level structured knowledge — it gets cross-references,
203
+ linting, and 5-layer prompt injection. Memory remains the right place for ad-hoc
204
+ flat facts and personal preferences.
205
+
206
+ ## Honesty rules
207
+
208
+ - Don't invent memories. Only write what the user said or you genuinely discovered.
209
+ - Don't echo what's already in `MEMORY.md` index.
210
+ - If a memory turns out wrong later, **edit or delete it** — don't pile a
211
+ contradiction on top.
212
+ - Stale `lesson` (>30 days, no recent reference) — feel free to delete or
213
+ promote to `convention` if it's hardened into project rule.