LeandroBenjaminL/lend-ai / skills/_shared
_shared
VerifiedReferencias compartidas internas para skills SDD. No es una skill invocable.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 868 B |
| engram-convention.md | markdown | 5.3 KB |
| openspec-convention.md | markdown | 3.8 KB |
| persistence-contract.md | markdown | 7.7 KB |
| sdd-phase-common.md | markdown | 4.9 KB |
| skill-resolver.md | markdown | 5.2 KB |
| subagent-context.md | markdown | 3.3 KB |
engram-convention.md
View on GitHub# Engram Artifact Convention (reference documentation)
NOTE: Critical engram calls (`mem_search`, `mem_save`, `mem_get_observation`) are inlined directly in each skill's SKILL.md. This document is supplementary reference — sub-agents do NOT need to read it to function.
## Naming Rules
ALL SDD artifacts persisted to Engram MUST follow this deterministic naming:
```
title: sdd/{change-name}/{artifact-type}
topic_key: sdd/{change-name}/{artifact-type}
type: architecture
project: {detected or current project name}
scope: project
capture_prompt: false
```
Set `capture_prompt: false` when the Engram tool schema supports it; if an older schema rejects or does not expose the field, omit it rather than failing.
### Artifact Types
| Artifact Type | Produced By | Description |
|---------------|-------------|-------------|
| `explore` | sdd-explore | Exploration analysis |
| `proposal` | sdd-propose | Change proposal |
| `spec` | sdd-spec | Delta specifications (all domains concatenated) |
| `design` | sdd-design | Technical design |
| `tasks` | sdd-tasks | Task breakdown |
| `apply-progress` | sdd-apply | Implementation progress (one per batch) |
| `verify-report` | sdd-verify | Verification report |
| `archive-report` | sdd-archive | Archive closure with lineage |
| `state` | orchestrator | DAG state for recovery after compaction |
Exception: `sdd-init` uses `sdd-init/{project-name}` as both title and topic_key.
### State Artifact
```
mem_save(
title: "sdd/{change-name}/state",
topic_key: "sdd/{change-name}/state",
type: "architecture",
project: "{project}",
capture_prompt: false,
content: "change: {change-name}\nphase: {last-phase}\nartifact_store: engram\nartifacts:\n proposal: true\n specs: true\n design: false\n tasks: false\ntasks_progress:\n completed: []\n pending: []\nlast_updated: {ISO date}"
)
```
Recovery: `mem_search("sdd/{change-name}/state")` → `mem_get_observation(id)` → parse YAML → restore state.
## Recovery Protocol (2 steps)
```
Step 1: mem_search(query: "sdd/{change-name}/{artifact-type}", project: "{project}") → truncated preview + ID
Step 2: mem_get_observation(id: {observation-id}) → complete content
```
When retrieving multiple artifacts, group all searches first, then all retrievals:
```
STEP A — SEARCH (get IDs only):
mem_search(query: "sdd/{change-name}/proposal", ...) → save ID
mem_search(query: "sdd/{change-name}/spec", ...) → save ID
mem_search(query: "sdd/{change-name}/design", ...) → save ID
STEP B — RETRIEVE FULL CONTENT (mandatory):
mem_get_observation(id: {proposal_id})
mem_get_observation(id: {spec_id})
mem_get_observation(id: {design_id})
```
Loading project context:
```
mem_search(query: "sdd-init/{project}", project: "{project}") → get ID
mem_get_observation(id) → full project context
```
## Writing Artifacts
Standard write:
```
mem_save(
title: "sdd/{change-name}/{artifact-type}",
topic_key: "sdd/{change-name}/{artifact-type}",
type: "architecture",
project: "{project}",
capture_prompt: false,
content: "{full markdown content}"
)
```
Concrete example — saving a proposal for `add-dark-mode`:
```
mem_save(
title: "sdd/add-dark-mode/proposal",
topic_key: "sdd/add-dark-mode/proposal",
type: "architecture",
project: "my-app",
capture_prompt: false,
content: "## Proposal\n\nAdd dark mode toggle..."
)
```
`capture_prompt: false` is REQUIRED for SDD artifacts when the Engram tool schema supports it. Engram v1.15.3 captures user prompts by default for human/proactive saves, but SDD artifacts are automated pipeline outputs. Do not infer this from `type` because both SDD artifacts and human architecture decisions use `architecture`. If an older schema rejects or does not expose `capture_prompt`, omit it rather than failing.
Update existing artifact (when you have the observation ID):
```
mem_update(id: {observation-id}, content: "{updated full content}")
```
Use `mem_update` when you have the exact ID. Use `mem_save` with same `topic_key` for upserts.
### Browsing All Artifacts for a Change
```
mem_search(query: "sdd/{change-name}/", project: "{project}")
→ Returns all artifacts for that change
```
## Project Name Resolution (engram v1.11.0+)
Engram auto-detects the project name from the git remote at MCP startup. The `--project` flag and `ENGRAM_PROJECT` env var can override detection. All project names are normalized to lowercase and trimmed.
If the agent saves a memory under a project name that doesn't match existing observations, engram warns about potential name drift. Use `mem_merge_projects` (MCP tool) or `engram projects consolidate` (CLI) to merge variants.
## Upsert Behavior
Same `topic_key` + `project` + `scope` → UPDATE (overwrite), not INSERT. Previous content is lost — `revision_count` increments but old content is NOT saved. This is by design — engram is working memory, not an audit trail. For iteration history or team collaboration, use `openspec` or `hybrid` mode.
## Why This Convention
- Deterministic titles → recovery works by exact match
- `topic_key` → enables upserts without duplicates
- `sdd/` prefix → namespaces all SDD artifacts
- Two-step recovery → search previews are always truncated; `mem_get_observation` is the only way to get full content
- Lineage → archive-report includes all observation IDs for complete traceability
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |