@trespies-source/dojo-genesis-plugin 1.0.0

package/skills/seed-to-skill-converter/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: seed-to-skill-converter
+description: Elevate a frequently-used Dojo Seed into a fully-fledged reusable Skill with templates and workflows. Use when a seed has proven value and describes a repeatable process. Trigger phrases: "promote this seed to a skill", "convert this seed into a skill", "make this seed into a skill", "formalize this pattern", "turn this seed active".
+---
+
+> **OpenClaw Integration:** This skill is invoked by the Dojo Genesis plugin via `/dojo run seed-to-skill-converter`.
+> The agent receives project context automatically via the `before_agent_start` hook.
+> Use `dojo_get_context` for full state, `dojo_save_artifact` to persist outputs,
+> and `dojo_update_state` to record phase transitions and decisions.
+
+# Seed-to-Skill Converter Skill
+
+**Version:** 1.0  
+**Created:** 2026-02-04  
+**Author:** Manus AI  
+**Purpose:** To provide a structured process for identifying when a Dojo Seed has become important enough to be promoted into a reusable Skill, and to guide the conversion process.
+
+---
+
+## I. The Philosophy: From Insight to Instrument
+
+A Dojo Seed is a potent insight, a moment of clarity captured. It is a reminder of a lesson learned. A Skill is an **instrument**. It is that same lesson transformed into a repeatable, structured process that can be reliably executed by any agent.
+
+The Seed-to-Skill Converter is the alchemical process that turns the passive wisdom of a Seed into the active utility of a Skill. It is the recognition that some insights are so fundamental to our practice that they deserve to be formalized, to become part of the very machinery of our workflow.
+
+---
+
+## II. When to Use This Skill
+
+-   **When a Seed is referenced frequently:** If you find yourself constantly referring back to the same Seed across multiple projects or sprints, it may be ready for promotion.
+-   **When a Seed describes a multi-step process:** If a Seed isn't just a simple reminder but outlines a series of actions, it is a strong candidate for a Skill.
+-   **When a Seed represents a core part of our workflow:** If a Seed is fundamental to how we build, reflect, or collaborate, it should be a Skill.
+-   **During a Retrospective:** A retrospective is a perfect time to ask, "Which of our learnings from this sprint are so important they should become a permanent Skill?"
+
+---
+
+## III. The Conversion Workflow
+
+### Step 1: Identify the Candidate Seed
+
+Select a Dojo Seed that meets the criteria from Section II. Announce the intention to convert it into a Skill.
+
+**Example:** "The Seed 'Workflow as Practice' has become so central to our collaboration that I believe it's time to elevate it into a formal Skill."
+
+### Step 2: Deconstruct the Seed's Wisdom
+
+Analyze the Seed and break down its core components:
+
+-   **The Core Insight:** What is the fundamental truth or idea the Seed represents?
+-   **The Trigger:** When should this wisdom be applied?
+-   **The Process:** What are the concrete steps an agent should take to apply this wisdom?
+-   **The Desired Outcome:** What is the result of applying this wisdom correctly?
+
+### Step 3: Draft the Skill Using the Standard Template
+
+Create a new directory in `SKILLS/` and a `SKILL.md` file. Use the standard Skill template (see `skill-creation` skill) to structure the new Skill. The components deconstructed in Step 2 will form the core of the new Skill's content.
+
+| Seed Component | Skill Section |
+| :--- | :--- |
+| **Core Insight** | `I. The Philosophy` |
+| **Trigger** | `II. When to Use This Skill` |
+| **Process** | `III. The Workflow` |
+| **Desired Outcome** | `IV. Best Practices` / `V. Quality Checklist` |
+
+### Step 4: Define the Workflow and Templates
+
+This is the most critical step. Transform the abstract process from the Seed into a concrete, step-by-step workflow. If the Skill involves creating a document, provide a complete markdown template.
+
+### Step 5: Commit the New Skill
+
+Commit the new Skill to the AROMA repository and copy it to the local `/home/ubuntu/skills/` directory to make it available for immediate use.
+
+---
+
+## IV. Example Conversion: 'Workflow as Practice' Seed
+
+Let's imagine we are converting the Seed: **Seed: Workflow as Practice** — *Why it matters:* It reframes our collaboration from a means to an end to a valuable practice in itself. — *Revisit trigger:* When we feel rushed, frustrated, or focused only on the outcome.
+
+### Deconstruction:
+
+-   **Core Insight:** Our collaboration is a practice, not just a series of tasks.
+-   **Trigger:** Feeling rushed, frustrated, or overly outcome-focused.
+-   **Process:** Pause, re-read the project's `PHILOSOPHY.md` or `STATUS.md`, reflect on the *how* not just the *what*, and consciously choose to slow down to the "pace of understanding."
+-   **Desired Outcome:** A return to a more mindful, less reactive state of work.
+
+### Skill Creation:
+
+This would likely become a Skill called `mindful-workflow-check`. The workflow would guide an agent to:
+1.  Recognize the trigger (frustration, rushing).
+2.  Pause current work.
+3.  Read the project's `STATUS.md` and `PHILOSOPHY.md`.
+4.  Write a brief, private reflection in `thinking/` on how the current work aligns with the project's deeper purpose.
+5.  State a clear intention for how to proceed with the work in a more mindful way.
+
+---
+
+## V. Best Practices
+
+-   **Not Every Seed Needs to Be a Skill:** The beauty of Seeds is their lightness. Only promote a Seed when it has proven its value and utility over time.
+-   **Skills Should Be Actionable:** A Skill must describe a *process*. If a Seed is purely a philosophical reminder, it should remain a Seed.
+-   **Skills Require Maintenance:** Once a Seed becomes a Skill, it is part of our formal infrastructure and must be kept up-to-date.
+-   **The Goal is Utility:** The purpose of this conversion is to create a useful instrument. If the resulting Skill is not useful, the conversion has failed.
+---
+
+## OpenClaw Tool Integration
+
+When running inside the Dojo Genesis plugin:
+
+1. **Start** by calling `dojo_get_context` to retrieve full project state, history, and artifacts
+2. **During** the skill, follow the workflow steps documented above
+3. **Save** outputs using `dojo_save_artifact` with the `artifacts` output directory
+4. **Update** project state by calling `dojo_update_state` to record skill completion and any phase transitions
+

package/skills/seed-to-skill-converter/claw.json

@@ -0,0 +1,12 @@
+{
+  "name": "dojo-genesis-plugin-seed-to-skill-converter",
+  "version": "1.0.0",
+  "description": "Elevate proven seeds into full skills",
+  "author": "dojo-genesis",
+  "license": "MIT",
+  "permissions": [],
+  "entry": "SKILL.md",
+  "tags": ["dojo-genesis", "orchestration", "garden", "memory"],
+  "models": ["claude-*", "gpt-*", "gemini-*"],
+  "minOpenClawVersion": "2026.1.0"
+}

package/skills/semantic-clusters/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: semantic-clusters
+description: Map software system capabilities using action-verb clusters that group components by what they DO rather than where they live. Produces behavioral architecture revealing capabilities, gaps, and architectural confusion. Use when you need to understand what a codebase does, explain a system to others, plan refactors, audit feature coverage, or understand cross-cutting concerns. Trigger phrases: 'what does this app actually do', 'walk me through the features', 'what are the main capabilities', 'map the system architecture', 'understand this codebase'.
+---
+
+> **OpenClaw Integration:** This skill is invoked by the Dojo Genesis plugin via `/dojo run semantic-clusters`.
+> The agent receives project context automatically via the `before_agent_start` hook.
+> Use `dojo_get_context` for full state, `dojo_save_artifact` to persist outputs,
+> and `dojo_update_state` to record phase transitions and decisions.
+
+# Semantic Clusters Skill
+
+**Version:** 1.0
+**Created:** 2026-02-08
+**Author:** Cruz + Manus (Cowork)
+**Origin:** Elevated from the `repo-status` skill's semantic clusters reference, which was codified from a live strategic-scout audit of Dojo Genesis (13 clusters, 333 Go files, 416 frontend files mapped).
+**Lineage:** strategic-scout (exploration) → repo-status (formalization) → this standalone skill.
+
+---
+
+## I. The Philosophy: Behavior Over Location
+
+Every codebase has two architectures:
+
+1. **The filesystem architecture** — where files live. Directories, packages, modules. This is what `ls` shows you.
+2. **The behavioral architecture** — what the system *does*. Capabilities that cross-cut directories, features that span layers.
+
+Most people only see architecture #1. They think in terms of `frontend/`, `backend/`, `utils/`. But understanding comes from architecture #2 — the verbs.
+
+A "chat" feature isn't in one directory. It's a component in the frontend, a handler in the backend, a state engine in a context, a streaming service, an SSE connection, and a set of tools. These parts live in 6 different directories. But they all serve one verb: **CONVERSE**.
+
+Semantic clusters make the behavioral architecture visible. Each cluster is named with an action verb, and every significant component in the codebase maps to one (sometimes two) clusters. The result is a map of *what the system can do* — not just where its files happen to be.
+
+---
+
+## II. When to Use This Skill
+
+- **Exploring a new codebase:** Before diving into files, map the behavioral capabilities to build your mental model.
+- **Explaining a system:** Clusters make better explanations than directory trees because they answer "what does it do?" not "where are the files?"
+- **Planning a refactor:** Clusters reveal which components serve the same capability. Refactoring within a cluster is safer than across clusters.
+- **Auditing feature coverage:** Clusters expose gaps — capabilities the system lacks or has only partially implemented.
+- **Identifying architectural confusion:** If a component maps to 3+ clusters, it's probably doing too much. If a directory has components in 5 different clusters, it may need restructuring.
+- **Writing status documents:** Section 4 of the `status-template` skill uses clusters. This skill provides the methodology.
+
+---
+
+## III. The Starter Verbs
+
+These 13 action verbs cover most software systems. Read `references/verb-catalog.md` for detailed definitions, component examples, and signals for each.
+
+| Verb | What It Means | Example Systems That Need It |
+|------|--------------|---------------------------|
+| **CONVERSE** | Real-time communication with users | Chat apps, messaging, support tools |
+| **REASON** | Thinking, planning, deciding | AI agents, rule engines, recommendation systems |
+| **REMEMBER** | Storing and recalling knowledge | Knowledge bases, caching, memory systems |
+| **OBSERVE** | Watching and reporting | Monitoring, analytics, logging, tracing |
+| **LEARN** | Adapting based on feedback | Calibration, A/B testing, preference learning |
+| **ACT** | Executing side effects | Tool systems, API calls, file operations, cron |
+| **PROTECT** | Enforcing boundaries | Auth, encryption, rate limiting, validation |
+| **CONNECT** | Integrating externally | Plugins, APIs, webhooks, bots, OAuth |
+| **PRESENT** | Rendering UI | Shells, layouts, component libraries, themes |
+| **PERSIST** | Storing data durably | Databases, migrations, ORMs, caches |
+| **BUILD** | Building, testing, shipping | CI/CD, Docker, scripts, test suites |
+| **THINK** | Meta-cognition about itself | Skills, prompts, documentation, retrospectives |
+| **ORCHESTRATE** | Coordinating multi-step work | DAG engines, task queues, workflows, sagas |
+
+Not every project needs all 13. A simple CRUD app might only have CONVERSE, PERSIST, PRESENT, PROTECT, and BUILD. A complex AI platform might use all 13 plus custom ones.
+
+---
+
+## IV. The Clustering Workflow
+
+### Step 1: Inventory First
+
+You can't cluster what you haven't seen. Before clustering, you need a component inventory — a list of every significant component with its location, approximate LOC, and current status.
+
+If you've already run the `repo-status` skill (Phase 2), use that inventory. Otherwise, walk the filesystem yourself:
+
+```bash
+# Get top-level shape
+ls -la project-root/
+
+# Recursively explore significant directories
+find project-root/src -type f | head -50
+find project-root/backend -type d
+
+# Count LOC per directory
+find project-root/backend -name "*.go" | xargs wc -l | tail -1
+```
+
+### Step 2: Assign Verbs
+
+For each significant component in your inventory, ask: **"What verb describes what this does?"**
+
+Rules of thumb:
+- Most components map to **one** verb. If you can't decide, pick the one that best describes the component's *primary purpose*.
+- Some components legitimately serve **two** verbs (cross-cluster). This is fine — note both.
+- If a component maps to **three or more** verbs, it's probably doing too much. Flag it as an architectural concern.
+- If a component doesn't fit any verb, it might be dead code, or you might need a **new verb** (see Section V).
+
+### Step 3: Build Cluster Tables
+
+For each verb that has components, create a subsection:
+
+```markdown
+### [emoji] VERB — [Short Description]
+> [One sentence explaining what this capability means.]
+
+| Component | Location | Status | LOC |
+|-----------|----------|--------|-----|
+| [Name] | [path/] | [emoji] | [~number] |
+
+**Health:** [emoji] [one-line assessment]
+**Audit Notes:** [technical details, constraints, risks — 1-2 lines]
+```
+
+**Choosing emojis for verbs:**
+| Verb | Suggested Emoji |
+|------|----------------|
+| CONVERSE | 🗣️ |
+| REASON | 🧠 |
+| REMEMBER | 💾 |
+| OBSERVE | 👁️ |
+| LEARN | 📚 |
+| ACT | 🔧 |
+| PROTECT | 🛡️ |
+| CONNECT | 🔌 |
+| PRESENT | 🎨 |
+| PERSIST | 💿 |
+| BUILD | 🏗️ |
+| THINK | 💭 |
+| ORCHESTRATE | 🎼 |
+
+### Step 4: Identify Cross-Cluster Components
+
+Some components serve multiple clusters. List these explicitly:
+
+```markdown
+### Cross-Cluster Components
+| Component | Directory | Primary Cluster | Secondary | Notes |
+|-----------|-----------|----------------|-----------|-------|
+| [Name] | [path/] | [VERB] | [VERB] | [Why] |
+```
+
+This table is gold for understanding coupling. Components that are cross-cluster are integration points — they're where changes in one capability can break another.
+
+### Step 5: Identify Orphans
+
+Walk the directory tree and check: **is every significant directory represented in at least one cluster?**
+
+Orphan directories — significant code that doesn't map to any cluster — signal one of three things:
+1. **Dead code** that should be removed.
+2. **An emerging capability** that deserves its own verb.
+3. **A gap in your analysis** that needs a second look.
+
+Document orphans explicitly. Don't sweep them under the rug.
+
+### Step 6: Write Health Assessments
+
+For each cluster, write a 2-line health assessment:
+- **Health line:** Overall emoji + one-sentence verdict.
+- **Audit Notes line:** Key constraints, risks, or technical details.
+
+Be honest. A cluster with 85% test coverage and active development is ✅. A cluster with no tests and a known security gap is ⚠️. A cluster that's completely broken is ❌.
+
+---
+
+## V. Creating New Verbs
+
+The 13 starter verbs are a starting point. Your project may need verbs not on the list.
+
+**Good custom verbs** are specific and immediately communicative:
+| Verb | Use When |
+|------|----------|
+| TRANSLATE | i18n-heavy apps, multi-language support |
+| SIMULATE | Apps with simulation engines, digital twins |
+| COMPOSE | Content creation tools, editors, IDEs |
+| GOVERN | Apps with complex compliance, policy, approval workflows |
+| DISCOVER | Search-heavy apps, recommendation engines, explorers |
+| TRANSFORM | Data pipeline apps, ETL systems, media converters |
+| SCHEDULE | Calendar-heavy apps, booking systems, cron managers |
+| NOTIFY | Apps where notification delivery is a core capability |
+
+**Bad custom verbs** are vague and don't tell you anything:
+- MANAGE (manage *what*?)
+- PROCESS (process *what*?)
+- HANDLE (handle *what*?)
+- DO (everything "does" something)
+
+The test: can someone read just the verb name and guess what kinds of components belong in that cluster? If yes, it's a good verb.
+
+---
+
+## VI. Common Pitfalls
+
+**1. Over-clustering.** Don't create 20 clusters for a 30-file project. If a cluster has only 1-2 components, merge it with a related cluster. A good rule: 4-8 clusters for small projects, 8-15 for large ones.
+
+**2. Under-clustering.** Don't dump everything into PRESENT and PERSIST. If a cluster has 25+ components, consider splitting it. PRESENT might split into PRESENT (layout) and COMPOSE (content editing).
+
+**3. Confusing location with behavior.** A component in `frontend/src/components/` isn't automatically PRESENT. A dashboard that displays traces belongs in OBSERVE. A form that manages API keys belongs in PROTECT. Let the *behavior* dictate the cluster, not the directory.
+
+**4. Ignoring tests.** Tests belong in BUILD, not in the cluster of the code they test. They're infrastructure, not capabilities.
+
+**5. Forgetting infrastructure.** CI/CD, Docker, and deployment configs are real capabilities. BUILD is a real cluster, not an afterthought.
+
+**6. Treating clusters as hierarchical.** Clusters are *flat*. REASON is not "above" ACT. They're peers — different capabilities of the same system. The component tables within each cluster may have internal hierarchy, but the clusters themselves don't.
+
+---
+
+## VII. Using Clusters Beyond Status Documents
+
+Semantic clusters have applications beyond the status-template:
+
+- **Architecture Decision Records (ADRs):** Frame decisions by which cluster they affect. "This ADR impacts REASON and ORCHESTRATE."
+- **Sprint planning:** Assign work by cluster. "This sprint we're focused on OBSERVE and PRESENT."
+- **Code review:** Ask "which cluster does this PR touch?" A PR that modifies 4+ clusters deserves extra scrutiny.
+- **Onboarding:** Walk new team members through clusters, not directories. "Let me explain what this system can DO."
+- **Technical debt tracking:** Rate each cluster's health independently. Focus debt reduction on ⚠️ and ❌ clusters.
+
+---
+
+## VIII. Quality Checklist
+
+Before delivering your semantic cluster map, confirm:
+
+- [ ] Every significant component maps to at least one cluster
+- [ ] No cluster has fewer than 2 components (merge if so)
+- [ ] No cluster has more than 20 components (split if so)
+- [ ] Cross-cluster components are explicitly listed
+- [ ] Orphan directories are documented and explained
+- [ ] Each cluster has a health assessment with emoji + notes
+- [ ] Custom verbs (if any) pass the "can you guess the contents?" test
+- [ ] The cluster map covers both frontend and backend (if applicable)
+- [ ] LOC estimates are approximate but not fictional
+- [ ] The map tells a coherent story about what the system does
+---
+
+## OpenClaw Tool Integration
+
+When running inside the Dojo Genesis plugin:
+
+1. **Start** by calling `dojo_get_context` to retrieve full project state, history, and artifacts
+2. **During** the skill, follow the workflow steps documented above
+3. **Save** outputs using `dojo_save_artifact` with the `artifacts` output directory
+4. **Update** project state by calling `dojo_update_state` to record skill completion and any phase transitions
+

package/skills/semantic-clusters/claw.json

@@ -0,0 +1,12 @@
+{
+  "name": "dojo-genesis-plugin-semantic-clusters",
+  "version": "1.0.0",
+  "description": "Map system capabilities with action-verb clusters",
+  "author": "dojo-genesis",
+  "license": "MIT",
+  "permissions": [],
+  "entry": "SKILL.md",
+  "tags": ["dojo-genesis", "orchestration", "system", "health"],
+  "models": ["claude-*", "gpt-*", "gemini-*"],
+  "minOpenClawVersion": "2026.1.0"
+}

package/skills/semantic-clusters/references/verb-catalog.md

@@ -0,0 +1,267 @@
+# Verb Catalog — Complete Reference
+
+**Purpose:** Detailed definitions, typical components, signals, and examples for each of the 13 starter action verbs plus guidance on creating custom verbs.
+
+---
+
+## The 13 Starter Verbs
+
+### CONVERSE
+**Definition:** The system communicates with users in real-time through conversational interfaces.
+
+**Typical components:**
+- Chat UI components (message lists, input bars, bubbles)
+- WebSocket or SSE handlers for real-time streaming
+- Message models and serialization
+- Command parsers and slash-command handlers
+- Notification/toast systems for message delivery
+- Typing indicators, read receipts, presence
+
+**Signals you need this cluster:** The app has a chat, messaging, real-time communication, or conversational interface.
+
+**Not CONVERSE:** A static contact form (that's PRESENT + ACT). Email sending (that's ACT). Push notifications (that's NOTIFY or ACT).
+
+---
+
+### REASON
+**Definition:** The system thinks, plans, classifies, or makes autonomous decisions.
+
+**Typical components:**
+- AI agents and assistants
+- Intent classifiers and NLU pipelines
+- Orchestration engines and planners
+- Rule engines and decision trees
+- Recommendation algorithms
+- Response caching and deduplication
+
+**Signals:** The app has an AI agent, automated planning, intent classification, or autonomous decision-making that goes beyond simple if/else logic.
+
+**Not REASON:** A form validation rule (that's PROTECT). A simple switch/case router (that's ACT). A user-configured filter (that's PRESENT).
+
+---
+
+### REMEMBER
+**Definition:** The system stores and recalls knowledge over time, beyond simple data persistence.
+
+**Typical components:**
+- Memory managers with multi-tier storage
+- Vector embeddings and semantic search
+- Knowledge base systems
+- Seed/snippet/template libraries
+- Compression and summarization services
+- Context builders that assemble relevant memory
+
+**Signals:** The app has a memory, knowledge base, or learning component that persists across sessions and influences future behavior. Distinct from PERSIST, which is raw data storage.
+
+**Not REMEMBER:** A database table (that's PERSIST). A user preferences file (that's LEARN or PERSIST). A cache layer (that's PERSIST or ACT).
+
+**REMEMBER vs PERSIST:** PERSIST stores data. REMEMBER stores *knowledge* — data with semantic meaning, retrieval by relevance, and influence on system behavior. If the system just saves and loads rows, that's PERSIST. If it embeds, searches by similarity, compresses, and builds context from memories, that's REMEMBER.
+
+---
+
+### OBSERVE
+**Definition:** The system watches itself and reports what it sees — monitoring, tracing, and metrics.
+
+**Typical components:**
+- Trace loggers and span trackers
+- Cost calculators and budget trackers
+- Event buses and event sourcing
+- Metrics collectors and dashboards
+- Audit logs and activity feeds
+- Health check endpoints
+
+**Signals:** The app has logging, tracing, analytics, monitoring, or cost-tracking features. Any form of self-awareness about its own behavior.
+
+**Not OBSERVE:** Application error handling (that's PROTECT). User analytics (that could be OBSERVE or a custom DISCOVER/ANALYZE verb depending on depth).
+
+---
+
+### LEARN
+**Definition:** The system adapts its behavior based on feedback, patterns, or observations.
+
+**Typical components:**
+- Calibration engines
+- Feedback collection and processing
+- Preference systems (user and system)
+- Pattern learners and trend detectors
+- A/B testing frameworks
+- Recommendation tuning
+
+**Signals:** The system changes its behavior over time based on user feedback, observed patterns, or calibration. Not just storing preferences (that's PERSIST) — actually using them to modify behavior.
+
+**LEARN vs REMEMBER:** REMEMBER stores knowledge for retrieval. LEARN changes behavior based on feedback. A system that remembers your name is REMEMBER. A system that learns to give shorter answers because you prefer conciseness is LEARN.
+
+---
+
+### ACT
+**Definition:** The system executes side effects — doing things in the world beyond its own boundaries.
+
+**Typical components:**
+- Tool registries and tool execution engines
+- File operations (read, write, search)
+- API client calls to external services
+- Email/SMS/notification sending
+- Webhook dispatching
+- Cron jobs and scheduled tasks
+- Code execution sandboxes
+
+**Signals:** The app executes side effects — writes files, calls external APIs, sends communications, triggers external systems.
+
+**Not ACT:** Reading data from a database (that's PERSIST). Rendering UI (that's PRESENT). Internal event emission (that's OBSERVE).
+
+---
+
+### PROTECT
+**Definition:** The system enforces boundaries, safety, and security constraints.
+
+**Typical components:**
+- Authentication middleware (JWT, OAuth, sessions)
+- Authorization and RBAC
+- Encryption services (at rest and in transit)
+- Secure storage (keychains, vaults)
+- Rate limiters and throttling
+- Input validation and sanitization
+- CSRF/XSS protection
+- Budget enforcement and spending limits
+
+**Signals:** The app has authentication, authorization, encryption, rate limiting, or any form of boundary enforcement.
+
+---
+
+### CONNECT
+**Definition:** The system integrates with external services and platforms.
+
+**Typical components:**
+- Plugin architectures (gRPC, IPC, WASM)
+- OAuth flows and token management
+- Webhook receivers
+- Bot integrations (Slack, Telegram, Discord)
+- Import/export services
+- Third-party SDK wrappers
+
+**Signals:** The app talks to third-party services, has a plugin system, or supports integrations.
+
+**CONNECT vs ACT:** ACT is about executing a side effect (sending an email, calling an API). CONNECT is about the *infrastructure* for integration — the plugin system, the OAuth flow, the webhook receiver. If you're building a Telegram bot integration, the bot framework is CONNECT; sending a specific message through it is ACT.
+
+---
+
+### PRESENT
+**Definition:** The system renders user interfaces for human interaction.
+
+**Typical components:**
+- Layout shells and responsive containers
+- Routing configurations
+- Component libraries
+- Style systems and themes
+- Sidebar/panel/drawer management
+- Form components and interactive controls
+
+**Signals:** The app has a user-facing frontend — web, mobile, or desktop.
+
+**Caveat:** Not every frontend component is PRESENT. A dashboard showing traces is OBSERVE. A settings page managing API keys is PROTECT. Let the *purpose* of the component determine the cluster, not its location in the frontend directory.
+
+---
+
+### PERSIST
+**Definition:** The system stores data durably and reliably.
+
+**Typical components:**
+- Database managers and connection pools
+- ORMs and query builders
+- Migration systems (schema evolution)
+- Seed data and fixtures
+- Backup and restore scripts
+- Cache layers (Redis, in-memory)
+- File storage services
+
+**Signals:** The app has a database, file storage, or any form of durable state.
+
+---
+
+### BUILD
+**Definition:** The system builds, tests, and ships itself.
+
+**Typical components:**
+- CI/CD workflows (GitHub Actions, Jenkins, CircleCI)
+- Docker configurations
+- Build scripts and Makefiles
+- Test suites (unit, integration, e2e)
+- Linters and formatters
+- Release automation
+- Storybook or component playgrounds
+- Performance benchmarks
+
+**Signals:** The project has CI/CD, Docker, build scripts, or test infrastructure.
+
+---
+
+### THINK
+**Definition:** The system reasons about itself at a meta level — meta-cognition.
+
+**Typical components:**
+- Skills and prompt libraries
+- Knowledge artifacts and compressions
+- Retrospectives and lessons learned
+- Design documents and architectural decision records
+- Template libraries for common tasks
+
+**Signals:** The project has a meta-cognitive layer — skills, prompts, structured thinking artifacts, or self-reflective documentation that influences how the system is built and maintained.
+
+**Not THINK:** A README (that's documentation, part of BUILD). API documentation (that's BUILD). THINK is specifically about meta-cognition — the system's knowledge about how to work on itself.
+
+---
+
+### ORCHESTRATE
+**Definition:** The system coordinates multi-step, potentially parallel work.
+
+**Typical components:**
+- DAG engines and workflow managers
+- Task queue systems
+- Saga patterns and compensating transactions
+- State machines for complex flows
+- Parallel execution coordinators
+- Circuit breakers and retry logic
+
+**Signals:** The app decomposes complex tasks into sub-tasks and manages their execution, potentially in parallel with dependency tracking.
+
+**ORCHESTRATE vs REASON:** REASON decides *what* to do. ORCHESTRATE manages *how* to execute it across multiple steps. An intent classifier is REASON. A DAG engine that runs 5 tasks in parallel with dependency ordering is ORCHESTRATE.
+
+---
+
+## Creating Custom Verbs
+
+When the 13 starters don't cover your system, create new verbs.
+
+### Process
+
+1. **Identify the gap.** You have components that don't fit any existing cluster.
+2. **Name the behavior.** What do these orphan components *do*? Use a single, active verb.
+3. **Test the name.** Can someone unfamiliar with the project guess what components belong in this cluster? If not, try a different verb.
+4. **Pick an emoji.** Visual distinctiveness helps scanning.
+5. **Write a one-sentence definition.** Same format as the starters above.
+
+### Good Custom Verbs
+
+| Verb | Emoji | Use When |
+|------|-------|----------|
+| TRANSLATE | 🌐 | i18n, multi-language, localization is a core feature |
+| SIMULATE | 🧪 | Physics engines, digital twins, what-if scenarios |
+| COMPOSE | ✏️ | Rich text editors, content creation tools |
+| GOVERN | ⚖️ | Compliance, approval workflows, policy engines |
+| DISCOVER | 🔍 | Search, exploration, recommendation discovery |
+| TRANSFORM | 🔄 | Data pipelines, ETL, media conversion |
+| SCHEDULE | 📅 | Booking systems, calendar management, cron |
+| NOTIFY | 🔔 | Notification delivery as a core capability (beyond ACT) |
+| RENDER | 🖼️ | 3D rendering, video processing, image generation |
+| MEASURE | 📊 | Measurement/sensor systems (beyond OBSERVE) |
+
+### Verbs to Avoid
+
+| Bad Verb | Why | Better Alternative |
+|----------|-----|-------------------|
+| MANAGE | Too vague — manage what? | Use the specific behavior verb |
+| PROCESS | Too vague — process what? | TRANSFORM, ANALYZE, CONVERT |
+| HANDLE | Too vague — handle what? | Name the specific handling |
+| DO | Everything "does" something | Not a useful cluster name |
+| RUN | Same as DO | EXECUTE, ORCHESTRATE, or ACT |
+| WORK | Meaningless | Name the specific work |