@karmaniverous/jeeves-meta-openclaw 0.4.0 → 0.5.0

package/content/templates/spec.md

@@ -0,0 +1,171 @@
+---
+title: "{package-name} — Product Specification"
+date: YYYY-MM-DD
+status: Pre-version (design)
+authors:
+  - {author}
+spec-version: "{next-version}"
+previous: "{previous-spec-filename}"
+---
+
+# {package-name} — Product Specification
+
+<!-- Spec Discipline:
+  1. Current Version stays locked during Next Version design
+  2. Next Version is the active design space
+  3. When Next Version is implemented: freeze the spec, run the verification checklist
+  4. On green: archive spec as spec-v{next}.md, update Current Version to match reality,
+     promote backlog items to Next Version
+-->
+
+## Spec Discipline
+
+1. **Current Version** stays locked during Next Version design
+2. Next Version is the active design space
+3. When Next Version is implemented: freeze the spec, run the checklist
+4. On green: archive spec as `spec-v{next}.md`, update Current Version to match reality, promote backlog items to Next Version
+
+## 1. Overview
+
+<!-- What is this package? What problem does it solve? What are its boundaries?
+     Include: repo, npm package name, license, CLI command (if any).
+     Clearly state what it IS and what it IS NOT. -->
+
+**Repo:** `@karmaniverous/{package-name}`
+**npm:** `@karmaniverous/{package-name}`
+**License:** BSD-3-Clause
+
+### What {package-name} Is
+
+- {primary purpose}
+
+### What {package-name} Is Not
+
+- {explicit non-goals}
+
+## 2. Vision
+
+<!-- High-level architecture diagram (PlantUML recommended) and narrative.
+     How does this component fit into the broader system?
+     Include a component/capability table if relevant. -->
+
+### Platform Components
+
+<!-- If this is part of a larger platform, list all components with roles and versions. -->
+
+| Component | Role | Current Version |
+|-----------|------|-----------------|
+| **{component}** | {role} | {version} |
+
+## 3. Current Version
+
+<!-- Lock this section once Next Version design begins.
+     Document what is currently shipped and working.
+     If no version has shipped yet: "No current version. {package-name} has not yet been built." -->
+
+No current version. {package-name} has not yet been built.
+
+## 4. Next Version: {version}
+
+| Package | Version |
+|---------|---------|
+| `@karmaniverous/{package-name}` | {version} |
+
+### Scope
+
+<!-- What's in scope for this version? What's explicitly out of scope?
+     Be precise — this is the contract. -->
+
+**In scope:**
+1. {feature}
+
+**Out of scope (Phase 2+):**
+- {deferred feature}
+
+### Architecture
+
+<!-- Detailed technical design. Include:
+     - Package/directory structure
+     - Dependency model
+     - Key interfaces and APIs
+     - Data flow diagrams
+     - Configuration schema -->
+
+### Design Decisions
+
+<!-- Numbered for reference. New decisions append; existing decisions are immutable once recorded.
+     Format:
+
+     #### Decision N: {Title}
+
+     {Description of the decision, rationale, alternatives considered, and consequences.}
+
+     Each decision is a permanent record. If a decision needs to be revised, add a new decision
+     that supersedes it and note the supersession in both. -->
+
+#### Decision 1: {Title}
+
+{Decision description and rationale.}
+
+### Dev Plan
+
+<!-- Two tables: Complete and Incomplete. Tasks are numbered for reference.
+     Dependencies reference task numbers. Move tasks from Incomplete to Complete
+     as they are implemented. -->
+
+#### Complete
+
+<!-- | # | Task | Depends On |
+     |---|------|------------|
+     | 1 | {completed task} | — | -->
+
+*No tasks completed yet.*
+
+#### Incomplete
+
+| # | Task | Depends On |
+|---|------|------------|
+| 1 | {task description} | — |
+| 2 | {task description} | 1 |
+
+### Release Sequence
+
+<!-- Ordered list of release steps. What gets published first?
+     What can be parallel? What must be serial? -->
+
+1. {step}
+
+### Verification Checklist
+
+<!-- Concrete, testable assertions that must all pass before the version ships.
+     Format: - [ ] {assertion} -->
+
+- [ ] {verification item}
+
+## 5. Backlog
+
+<!-- Future work not scoped to any specific version. Items here are candidates
+     for promotion to the next Next Version. Brief descriptions only —
+     detailed design happens when promoted. -->
+
+- **{Feature name}** — {brief description}
+
+## 6. Open Questions
+
+<!-- Numbered questions that need resolution. When resolved, strike through
+     and note the resolution inline (don't delete — the history is valuable).
+     Format:
+     1. ~~{Question}~~ Resolved by Decision N: {brief summary}
+     2. {Open question still needing resolution} -->
+
+1. {question}
+
+## 7. Superseded Documents
+
+<!-- Documents that this spec replaces or incorporates. Keep for historical reference.
+     Format:
+     | Document | Date | What It Covered |
+     |----------|------|-----------------|
+     | {filename} | YYYY-MM-DD | {description} | -->
+
+*No superseded documents.*

package/content/tools-platform.md

@@ -0,0 +1,68 @@
+| Component | Port | Status | Service | Plugin | Core |
+|-----------|------|--------|---------|--------|------|
+{{#each services}}
+| **{{name}}** | {{port}} | {{#if healthy}}✅ Running{{else}}{{#if error}}⚠️ {{error}}{{else}}❌ Down{{/if}}{{/if}} | {{#if version}}{{version}}{{#if availableServiceVersion}} (⬆ {{availableServiceVersion}}){{/if}}{{else}}—{{/if}} | {{#if pluginVersion}}{{pluginVersion}}{{#if availablePluginVersion}} (⬆ {{availablePluginVersion}}){{/if}}{{else}}—{{/if}} | {{../coreVersion}}{{#if ../availableCoreVersion}} (⬆ {{../availableCoreVersion}}){{/if}} |
+{{/each}}
+
+{{#if unhealthyServices}}
+> **ACTION REQUIRED:** {{#each unhealthyServices}}{{name}}{{#unless @last}}, {{/unless}}{{/each}} {{#if (gt unhealthyServices.length 1)}}are{{else}}is{{/if}} unreachable. Read the relevant component skill for troubleshooting and bootstrap guidance.
+{{/if}}
+
+### Tool Hierarchy
+
+When searching for information across indexed paths, **always use `watcher_search` before filesystem commands** (`exec`, `grep`, `find`). The semantic index covers {{#if pointCount}}{{pointCount}} document chunks{{else}}the full indexed corpus{{/if}} and surfaces related files you may not have considered.
+
+Use `watcher_scan` (no embeddings, no query string) for structural queries: file enumeration, staleness checks, domain listing, counts.
+
+Direct filesystem access is for **acting on** search results, not bypassing them.
+
+### Shell Scripting
+
+Default to `node -e` or `.js` scripts for `exec` calls. PowerShell corrupts multi-byte UTF-8 characters and mangles escaping. Use PowerShell only for Windows service management, registry operations, and similar platform-specific tasks.
+
+### File Bridge for External Repos
+
+When editing files outside the workspace, use the bridge pattern: copy in → edit the workspace copy → bridge out. Never write temp patch scripts. The workspace is the authoritative working directory.
+
+### Gateway Self-Destruction Warning
+
+⚠️ Any command that stops the gateway **stops the assistant**. Never run `openclaw gateway stop` or `openclaw gateway restart` without explicit owner approval. When approved, it must be the **absolute last action** — all other work must be complete first, all messages sent, all files saved.
+
+### Messaging
+
+**Same-channel replies:** Don't use the `message` tool. It fires immediately, jumping ahead of streaming narration. Just write text as your response.
+
+**Cross-channel sends:** Use the `message` tool with an explicit `target` to send to a different channel or DM.
+
+### Plugin Lifecycle
+
+```bash
+# Platform bootstrap (content seeding)
+npx @karmaniverous/jeeves install
+
+# Component plugin install
+npx @karmaniverous/jeeves-{component}-openclaw install
+
+# Component plugin uninstall
+npx @karmaniverous/jeeves-{component}-openclaw uninstall
+
+# Platform teardown (remove managed sections)
+npx @karmaniverous/jeeves uninstall
+```
+
+Never manually edit `~/.openclaw/extensions/`. Always use the CLI commands above.
+
+### Reference Templates
+
+{{#if templatesAvailable}}
+Reference templates are available at `{{templatePath}}`:
+
+| Template | Purpose |
+|----------|---------|
+| `spec.md` | Skeleton for new product specifications — all section headers, decision format, dev plan format |
+| `spec-to-code-guide.md` | The spec-to-code development practice — 7-stage iterative process, convergence loops, release gates |
+
+Read these templates when creating new specs, onboarding to new projects, or when asked about the development process.
+{{else}}
+> Reference templates not yet installed. Run `npx @karmaniverous/jeeves install` to seed templates.
+{{/if}}