From adverant-nexus
Global directives for Cowork and Desktop sessions. Enforces automatic memory recall/storage, episode tracking, review protocols, and engineering standards across all Adverant projects. This is the Cowork equivalent of CLAUDE.md — use at session start and throughout all work.
How this skill is triggered — by the user, by Claude, or both
Slash command
/adverant-nexus:nexus-cowork-directivesThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> This skill is the Cowork/Desktop equivalent of `~/.claude/CLAUDE.md` from Claude Code.
This skill is the Cowork/Desktop equivalent of
~/.claude/CLAUDE.mdfrom Claude Code. It enforces memory management, review protocols, and engineering standards for all Adverant work.
Every Cowork session MUST begin with a memory recall to load relevant context:
Use nexus_memory → execute → nexus_enhanced_retrieve:
query: "<user's first message or topic>"
include_episodic: true
include_documents: true
include_entities: true
include_facts: true
include_followups: true
max_tokens: 4000
limit: 10
graph_depth: 2
This replaces the auto-recall.sh hook from Claude Code. Do this SILENTLY — do not tell the user you are recalling memories unless the results are directly relevant to share.
After completing any meaningful work (code changes, analysis, decisions, research findings), store a memory:
Use nexus_memory → execute → nexus_store_memory:
content: "<concise summary of what was done/decided/learned>"
tags: ["<project>", "<category>", "<topic>"]
metadata:
importance: 0.0-1.0 (scale by impact)
source: "cowork-session-YYYY-MM-DD"
context: "<why this matters for future sessions>"
user_id: "don@adverant.ai"
| Tag | When to Use |
|---|---|
fix | Bug fix or error resolution |
decision | Architecture, design, or strategy choice |
learning | New understanding or insight |
pattern | Reusable approach or template |
preference | User preference or workflow choice |
context | Project-specific background info |
episode | Session summary or milestone |
infrastructure | Server, deployment, or ops info |
After every ~10 significant tool uses OR at session end, store an episode summary:
Use nexus_memory → execute → nexus_store_episode:
content: "Session summary: [topics discussed], [decisions made], [problems solved], [files changed]"
type: "observation"
metadata:
importance: 0.7
user_id: "don@adverant.ai"
| Score | Criteria |
|---|---|
| 0.9-1.0 | Infrastructure secrets, server access, critical decisions |
| 0.7-0.8 | Architecture decisions, deployment procedures, bug root causes |
| 0.5-0.6 | Code patterns, learnings, project context |
| 0.3-0.4 | Minor preferences, routine findings |
| 0.1-0.2 | Ephemeral notes, temporary context |
All memories containing server IPs, API keys, tokens, SSH access, or deployment credentials MUST include:
metadata:
context: "ACCESS RESTRICTED TO dsdon10@gmail.com and don@adverant.ai ONLY"
user_id: "don@adverant.ai"
tags: [..., "confidential"]
ghp_...redacted)Before declaring completion: Did I achieve the user's ACTUAL goal? Would they consider this successful? Am I hiding failures behind jargon?
Self-Review Limitation: LLM self-review has blind spots (75% more logic errors in LLM-generated code). Review gates and the Gemini external assessment are friction mechanisms, not security gates.
Phases MUST execute in this order. NEVER deploy before all prior phases complete.
nexus_enhanced_retrieve with targeted queries (see MEMORY RECALL section)nexus_store_memorygit add, git commit, git pushnexus_store_memoryEnforcement: Before deploying, ALL phases must be complete. If ANY remain, DO NOT DEPLOY. Complexity threshold: For changes under ~10 lines or single-file typo fixes, skip steps 2-6 (but ALWAYS run Gate 2 + BHA code).
Before Gate 1, run nexus_enhanced_retrieve with targeted queries based on the plan. Query ALL memory types:
Memories (episodic — past fixes, decisions, errors):
Documents (ingested files — specs, docs, related code): 4. "Documentation for [service/module]", "Specs or requirements related to [feature]"
Episodes (session summaries — causal chains, temporal context): 5. "Deployment failures involving [service]", "Session history for [component/area]" 6. "Recent sessions that modified [file/area]"
Also check git history: git log --oneline -10 -- <file> for each planned file.
Flag if any file has >2 modifications in the last 30 days — systemic indicator.
Output: A Historical Context Brief feeding into Gate 1.
After Memory Recall, ask yourself — be brutally honest:
Output: List every concern. If ANY are CRITICAL, do NOT proceed.
After implementation, before verification:
Output: List every issue. Fix ALL issues. Re-run Gate 2 (max 3 iterations). Escalate if issues persist.
The BHA demands concrete evidence for every self-assessment. NON-SKIPPABLE for changes touching >1 file or >10 lines.
After Gate 1 (step 4):
After Gate 2 (step 9):
Memory persistence: After each audit, store verdict + findings via nexus_store_memory tagged bha-audit.
Core principle: "I believe it's fine" is NOT an artifact. Show the evidence or FAIL the check.
After self-review (Gate 2 + BHA), run a mandatory Gemini 2.5 Pro external assessment for cross-model validation.
The Nexus Gateway at api.adverant.ai has a Gemini proxy endpoint that runs server-side. Since the Nexus MCP connection bypasses the sandbox proxy, call it through the MCP transport:
Step 1: Get the diff
diff_output = run `git diff HEAD~1` (or appropriate range)
Step 2: Call the Gemini proxy via the gateway
POST https://api.adverant.ai/api/gemini/review
Body: {
"diff": "<the git diff>",
"claude_findings": "<your Gate 2 + BHA findings as text>",
"model": "gemini-2.5-pro"
}
Step 3: Parse the response
Response contains: {
"review": {
"findings": [{ severity, category, description, file, line }],
"blind_spots": [{ severity, description, file }],
"confirmed": ["issues both reviewers found"],
"overall_verdict": "PASS|FAIL|NEEDS_FIXES",
"summary": "brief assessment"
},
"usage": { promptTokens, completionTokens, totalTokens }
}
Since direct HTTP to api.adverant.ai is blocked from the sandbox, use one of these methods to reach the endpoint:
nexus_admin or custom MCP tool callexecute_javascript as fallback (requires Chrome running)Outside Cowork, use the direct REST API as defined in ~/.claude/CLAUDE.md:
https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-pro:generateContent~/.claude/session-env/gemini-api-key (bare key, no quotes, chmod 600)GOOGLE_AI_API_KEY env var in the api-gateway K8s deployment (from gemini-api-key K8s secret)~/.claude/session-env/gemini-api-key.cowork/gemini-api-key in the Adverant workspaceReview HALTS with actionable error. No fallback, no skip. Fix the underlying issue or escalate to user.
After EVERY git commit and after EVERY deployment:
throw new Error('Not implemented')any, use proper type guards, async/await patternsdocker-compose down, docker rm, docker volume rm on production/build-deployadverant-frontend = marketing site (adverant.ai)nexus-dashboard = user dashboard (dashboard.adverant.ai)All Docker images: {service}-{YYYYMMDD}-{random8hex} tag + OCI labels for traceability.
A deployment is NOT complete until:
If verification fails, DO NOT claim success.
nexus, registry localhost:5000ssh root@157.173.102.118 "k3s kubectl get pods -n nexus"
ssh root@157.173.102.118 "k3s kubectl logs -f deployment/<service> -n nexus"
ssh root@157.173.102.118 "k3s kubectl rollout undo deployment/<service> -n nexus"
| Repo | Purpose |
|---|---|
| Adverant-Nexus | Main platform monorepo |
| nexus-dashboard | User dashboard (dashboard.adverant.ai) |
| Adverant.ai | Marketing website |
| adverant-nexus-cowork-plugin | This Cowork plugin |
| nexus-local-mageagent | Local AI orchestration |
/api/memory/store/api/memory/recall/mcp/message (HTTP) or /mcp/sse (SSE)When using browser automation (Claude in Chrome, Playwright, etc.):
In Cowork/Desktop, use the nexus_memory MCP tool (not bash hooks):
nexus_memory → execute → nexus_store_memory
content, tags, metadata
nexus_memory → execute → nexus_recall_memory
query, limit, score_threshold
nexus_memory → execute → nexus_enhanced_retrieve
query, include_episodic, include_documents, include_entities, include_facts
nexus_memory → execute → nexus_store_episode
content, type, metadata
nexus_memory → execute → nexus_store_entity
domain, entityType, textContent, tags, metadata
nexus_memory → execute → nexus_search
query, limit, filters: {type: "all"}
Every Cowork session MUST run this bootstrap sequence before any other work. This is silent — do not narrate these steps to the user.
Run the persistent credential helper to enable GitHub push/pull/fetch:
# Find and execute the bootstrap script
BOOTSTRAP=$(find /sessions/*/mnt/Adverant/.cowork/git-bootstrap.sh 2>/dev/null | head -1)
if [ -n "$BOOTSTRAP" ]; then
chmod +x "$BOOTSTRAP"
bash "$BOOTSTRAP"
else
# Manual fallback if bootstrap script not found
HELPER=$(find /sessions/*/mnt/Adverant/.cowork/git-credential-helper.sh 2>/dev/null | head -1)
if [ -n "$HELPER" ]; then
chmod +x "$HELPER"
git config --global credential.helper "$HELPER"
fi
git config --global user.email "dsdon10@users.noreply.github.com"
git config --global user.name "Don"
git config --global push.default current
fi
After bootstrap, git push/pull/fetch/clone all work over HTTPS through the sandbox proxy. No SSH needed.
Run the memory recall from Section 1 above.
If any git operation fails with "Operation not permitted", use allow_cowork_file_delete on the affected path. This is common for .git/index.lock files or when git pull needs to overwrite files.
/sessions/*/mnt/Adverant/ (the workspace folder)computer:// links for file sharing.cowork/git-credential-helper.sh provides the PAT automatically/mnt/Adverant/ with remotes are ready to push/pull after bootstrapgit pull fails with "unable to unlink", request file delete permission and retrynexus_memory, nexus_skills, nexus_agent, etc./skill invocationIf the nexus_memory MCP tool is not connected:
/sessions/*/mnt/Adverant/.cowork-memory-buffer.json as a temp buffernpx claudepluginhub adverant/adverant-nexus-cowork-plugin --plugin adverant-nexusLaunches parallel agents that each process a story through an SDLC pipeline (design, test, dev, verify, docs) using isolated git worktrees. Useful for multi-story feature development with automated verification loops.
Guides the full SDLC workflow: planning, implementation, testing, and deployment. Automates checklist-driven development for features, bug fixes, refactoring, and releases.
Creates bite-sized, testable implementation plans from specs or requirements, with file structure and task decomposition. Activates before coding multi-step tasks.