@karmaniverous/jeeves 0.5.12 → 0.6.0-0

package/content/templates/spec-to-code-guide.md

@@ -1,250 +0,0 @@
-# Spec-to-Code Development Practice
-
-This document defines how developer and AI assistant collaborate to design, build, and ship software using the spec-driven process. It is the authoritative reference for the iterative development practice used across all Jeeves platform components.
-
-## 1. The Spec Format
-
-Every product has a single spec file (`spec.md`) that serves as the source of truth for what exists, what's being built, and what's been decided.
-
-### Section Reference
-
-| Section | Purpose | Mutability |
-|---------|---------|------------|
-| **Overview** | What it is, what it isn't, boundaries | Stable after v1 |
-| **Vision** | Architecture, component relationships | Evolves slowly |
-| **Current Version** | What's shipped and working | **Locked** during Next Version design |
-| **Next Version** | Active design space — scope, architecture, decisions, dev plan | Active |
-| **Backlog** | Future work candidates | Append-only between versions |
-| **Open Questions** | Unresolved issues | Resolve inline, don't delete |
-| **Superseded Documents** | Historical record | Append-only |
-
-### Locking Discipline
-
-- **Current Version** is frozen while Next Version is in progress. It reflects reality, not aspirations.
-- **Design Decisions** are append-only. Once recorded, a decision is immutable. To revise, add a new decision that supersedes the old one and cross-reference both.
-- **Dev Plan tasks** move from Incomplete to Complete. They are not deleted or renumbered.
-
-### Decision Format
-
-Decisions are numbered sequentially and never reordered:
-
-```markdown
-#### Decision N: {Title}
-
-{Description of the decision, rationale, alternatives considered, and consequences.
-Include enough context that someone reading this six months later understands WHY,
-not just WHAT.}
-```
-
-Key principles:
-- **Append-only.** New decisions get the next number. Existing decisions are never edited.
-- **Supersession.** If Decision 5 replaces Decision 2, Decision 5 says "Supersedes Decision 2" and Decision 2 gets a note: "Superseded by Decision 5."
-- **Rationale is mandatory.** A decision without rationale is just an opinion. Include what was considered and why this path was chosen.
-
-## 2. The 7-Stage Iterative Process
-
-### Stage 1: High-Level Design
-
-**Goal:** Establish scope, architecture, and key design decisions for the next version.
-
-**Activities:**
-- Define what's in scope and what's explicitly out
-- Draft architecture (package structure, dependency model, key interfaces)
-- Record initial design decisions
-- Identify open questions
-
-**Output:** A populated Next Version section with Scope, Architecture, initial Decisions, and a skeletal Dev Plan.
-
-**Who drives:** Developer sets direction; assistant drafts, proposes, and challenges.
-
-### Stage 2: Detailed Design & Dev Plan
-
-**Goal:** Break the architecture into concrete, sequenced tasks with explicit dependencies.
-
-**Activities:**
-- Decompose architecture into implementable tasks
-- Identify dependencies between tasks (which must complete before which)
-- Estimate complexity and sequence for optimal flow
-- Resolve open questions that block task definition
-
-**Output:** A complete Dev Plan (Incomplete table) with numbered tasks and dependency chains.
-
-**Convergence signal:** Every architectural element maps to at least one task. Every task has clear inputs and outputs. No circular dependencies.
-
-### Stage 3: Implementation
-
-**Goal:** Execute the dev plan, task by task.
-
-**Activities:**
-- Work through tasks in dependency order
-- For each task: branch, implement, test, commit, push
-- Record any new decisions discovered during implementation
-- Move completed tasks from Incomplete to Complete
-
-**Workflow per task:**
-1. Confirm task scope and acceptance criteria
-2. Create branch (if not already on a feature branch)
-3. Implement with tests
-4. Run all quality checks (lint, typecheck, test)
-5. Commit with meaningful message referencing the task number
-6. Push immediately
-
-**Output:** Working code, passing tests, updated Dev Plan.
-
-### Stage 4: Integration & Verification
-
-**Goal:** Verify that the implemented code meets the spec's verification checklist.
-
-**Activities:**
-- Run the full verification checklist from the spec
-- Fix any failures (new tasks if needed)
-- Integration testing across component boundaries
-- Performance and edge-case validation
-
-**Output:** All checklist items passing. Any new issues tracked as tasks.
-
-### Stage 5: Documentation & Content
-
-**Goal:** Ensure all documentation reflects the implemented reality.
-
-**Activities:**
-- Update README, CHANGELOG, API docs
-- Verify that managed content (TOOLS.md sections, skills) reflects new capabilities
-- Update spec to reflect any implementation-time decisions
-
-**Output:** Documentation that matches code. No stale references.
-
-### Stage 6: Release
-
-**Goal:** Ship the version.
-
-**Activities:**
-- Final quality gate pass (Stage 4 checklist, all green)
-- Version bump (semver)
-- Publish to npm (or equivalent)
-- Create GitHub release with changelog
-- Tag the commit
-
-**Gate:** Developer explicitly approves the release. The assistant prepares but does not execute without approval (Release & Deployment Gate).
-
-### Stage 7: Release Reconciliation
-
-**Goal:** Update the spec to reflect the shipped reality and prepare for the next cycle.
-
-**Activities:**
-- Archive the spec as `spec-v{version}.md`
-- Update Current Version to match what shipped
-- Promote backlog items to the new Next Version (developer's choice)
-- Close resolved Open Questions
-- Add any new backlog items discovered during implementation
-
-**Output:** A clean spec ready for the next design cycle.
-
-## 3. Convergence Loop Patterns
-
-Design and implementation are not strictly linear. Within each stage, the developer and assistant iterate until convergence.
-
-### The Basic Loop
-
-```
-Developer states intent
-  → Assistant proposes design/implementation
-    → Developer reviews, challenges, redirects
-      → Assistant revises
-        → Repeat until convergence
-          → Record decision / commit code / move task
-```
-
-### Convergence Signals
-
-- **Design convergence:** No more open questions blocking the next stage. All stakeholders agree on the approach.
-- **Implementation convergence:** Tests pass, lint clean, typecheck clean, task acceptance criteria met.
-- **Spec convergence:** Every implemented feature maps to a spec section. Every spec assertion is verifiable.
-
-### Anti-Patterns
-
-- **Premature implementation:** Writing code before the design is stable. If you're still debating the interface, don't implement it.
-- **Spec drift:** Implementing something different from what the spec says without updating the spec. The spec is the contract — if reality diverges, update the spec.
-- **Decision avoidance:** Leaving open questions open because they're hard. If a question blocks progress, escalate it — don't work around it.
-- **Gold plating:** Adding features not in the current scope. Backlog them. Ship what was planned.
-
-## 4. Release Gate Passes
-
-Before any release, these gates must pass:
-
-### Quality Gate
-
-- [ ] All tests pass
-- [ ] Zero lint errors AND zero lint warnings
-- [ ] Zero typecheck errors
-- [ ] All verification checklist items from the spec pass
-
-### Documentation Gate
-
-- [ ] README reflects current capabilities
-- [ ] CHANGELOG updated with all changes
-- [ ] API documentation current
-- [ ] Breaking changes documented with migration guide
-
-### Spec Gate
-
-- [ ] Dev Plan: all tasks in Complete
-- [ ] Open Questions: none blocking this release
-- [ ] Verification Checklist: all items checked
-- [ ] Design Decisions: no unrecorded decisions from implementation
-
-### Release Gate (requires explicit developer approval)
-
-- [ ] Version bumped appropriately (semver)
-- [ ] Published to registry
-- [ ] GitHub release created
-- [ ] Spec archived as `spec-v{version}.md`
-
-## 5. Conversation Engine Patterns
-
-The spec-to-code process is a conversation between developer and AI assistant. These patterns describe how that conversation works effectively.
-
-### The Proposal Pattern
-
-The assistant's default mode for design work:
-
-1. **Understand** the developer's intent (ask clarifying questions if ambiguous)
-2. **Propose** a concrete design with rationale
-3. **Present** trade-offs and alternatives considered
-4. **Wait** for feedback before proceeding
-
-Never assume silence is approval. Explicit confirmation before recording decisions or beginning implementation.
-
-### The Checkpoint Pattern
-
-At natural boundaries (end of a stage, completion of a complex task, before a risky action):
-
-1. **Summarize** what was accomplished
-2. **State** the current position in the process
-3. **Propose** the next step
-4. **Confirm** before proceeding
-
-This keeps the developer oriented and prevents runaway work in the wrong direction.
-
-### The Discovery Pattern
-
-When implementation reveals something the design didn't anticipate:
-
-1. **Stop** — don't improvise a solution
-2. **Report** what was discovered and why it matters
-3. **Propose** options (including "do nothing and backlog it")
-4. **Record** the decision if one is made
-5. **Continue** with the updated understanding
-
-Discoveries during implementation are normal and valuable. They become design decisions, not silent workarounds.
-
-### The Escalation Pattern
-
-When the assistant hits something it can't resolve:
-
-1. **State** what was attempted
-2. **Explain** why it's blocked
-3. **Present** the options as understood
-4. **Ask** for direction
-
-Never go dark. Never guess. The developer always has more context than the assistant about business priorities, political constraints, and acceptable trade-offs.

package/content/templates/spec.md

@@ -1,177 +0,0 @@
----
-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
-
-## Spec Hygiene
-
-- **Frontmatter is mandatory.** Every spec must have `version`, `date`, and `status` fields in the YAML frontmatter. The `status` field tracks the spec lifecycle: `Pre-version (design)`, `In progress`, `Complete`, `Archived`.
-- **Decisions are numbered.** Use sequential numbering (`Decision 1`, `Decision 2`, ...) so they can be cross-referenced from dev plan tasks, other decisions, and external documents. Never renumber — append only.
-- **Dev plan tasks have dependency ordering.** Every task in the dev plan table must have a `Depends On` column referencing prerequisite task numbers (or `—` for none). Tasks should be ordered so dependencies come first. This enforces implementation sequencing and makes parallel work visible.
-
-## 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

@@ -1,102 +0,0 @@
-### Tool Hierarchy
-
-When searching for information across indexed paths, **always use `watcher_search` before filesystem commands** (`exec`, `grep`, `find`). The semantic index covers the full indexed corpus 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.
-
-### Slack File Downloads
-
-To download a Slack-hosted file, first try the `message` tool's `download-file` action. If that fails, fall back to a direct HTTP fetch using the bot token:
-
-```js
-fetch(url_private_download, {
-  headers: { Authorization: 'Bearer ' + botToken },
-});
-```
-
-The bot token is at `channels.slack.accounts.default.botToken` in `openclaw.json`.
-
-Never tell the user a file can't be downloaded until both methods have been tried.
-
-### 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 templatePath}}
-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}}
-
-### Post-Upgrade Maintenance
-
-After updating OpenClaw (`npm install -g openclaw@latest` or equivalent), reinstall all Jeeves component plugins to repair install state:
-
-```bash
-npx @karmaniverous/jeeves install
-npx @karmaniverous/jeeves-runner-openclaw install
-npx @karmaniverous/jeeves-watcher-openclaw install
-npx @karmaniverous/jeeves-server-openclaw install
-npx @karmaniverous/jeeves-meta-openclaw install
-```
-
-Then restart the gateway. Plugin installers copy dist files and patch config; reinstalling after an OpenClaw update ensures the extensions directory stays consistent.
-
-### Source Code Preference
-
-{{#if devRepos}}
-When investigating, debugging, or analyzing Jeeves components, always read TypeScript source from dev repos — never compiled `dist/` from the global npm install. Dev repos:
-
-| Component | Dev Repo |
-|-----------|----------|
-{{#each devRepos}}
-| {{@key}} | `{{this}}` |
-{{/each}}
-
-Built code is minified, harder to reason about, and wastes context. Always `git pull` before analysis.
-{{else}}
-> Dev repo paths not configured. Add `core.devRepos` to `jeeves.config.json` to enable source code preference guidance.
-{{/if}}