hoomanjs 1.40.1 → 1.40.2

package/dist/core/skills/built-in/hooman-channels/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hooman-channels
-description: Add and configure Hooman channel MCP servers for cron, Slack, Telegram, WhatsApp, and Jira. Use when the user asks to connect event-driven channels, schedulers, messaging apps, or Jira webhooks to a Hooman agent or daemon.
+description: Add and configure Hooman channel MCP servers for cron, Slack, Telegram, WhatsApp, and Jira in ~/.hooman/mcp.json. Use when the user asks for scheduled or recurring prompts, cron jobs, messaging-app or chatbot integration, inbound webhooks, daemon automation, or connecting any event-driven channel to a Hooman agent or daemon. For ordinary (non-channel) MCP server edits use hooman-mcp.
 ---
 
 # Hooman Channels
@@ -9,18 +9,19 @@ Use this skill when the user asks to add channel-driven MCP integrations to Hoom
 
 ## Source Of Truth
 
-- MCP servers live in `~/.hooman/mcp.json` under top-level `mcpServers`.
+- MCP servers live in `~/.hooman/mcp.json` under top-level `mcpServers` (minimal shape: `{"mcpServers": {}}`).
 - Restart the running Hooman session or daemon after changing `mcp.json`.
-- Run the long-lived listener with `hooman daemon --channels`.
-- Use `hooman daemon --channels --yolo` only when the user explicitly accepts automatic tool approval risk.
+- Run the long-lived listener with `hooman daemon --channels`. Use `--yolo` only when the user explicitly accepts automatic tool approval risk.
 
-Minimal `mcp.json` shape:
+## Reference File
 
-```json
-{
-  "mcpServers": {}
-}
-```
+Read `channels.md` (next to this SKILL.md) for the exact `mcpServers` JSON entry, requirements, configure steps, allowlists, metadata shape, and webhook/credential details of each channel before adding or troubleshooting it. Supported channels and packages:
+
+- `cron` — `cronmcp` (scheduler)
+- `slack` — `slackxmcp`
+- `telegram` — `tgfmcp`
+- `whatsapp` — `wappmcp`
+- `jira` — `jiraxmcp` (webhooks; credentials via server `env`)
 
 ## Operating Rules
 
@@ -33,144 +34,6 @@ Minimal `mcp.json` shape:
 7. For Slack, Telegram, and WhatsApp, run each package's `configure` command first when local credentials or allowlists are not already configured.
 8. For Jira, place credentials in the server `env` map or ensure the daemon's shell environment provides them.
 
-## Common Channel Server Entries
-
-Add any requested entries under `mcpServers`.
-
-Cron scheduler:
-
-```json
-{
-  "cron": {
-    "type": "stdio",
-    "command": "npx",
-    "args": ["-y", "cronmcp", "mcp", "--channels"]
-  }
-}
-```
-
-Slack:
-
-```json
-{
-  "slack": {
-    "type": "stdio",
-    "command": "npx",
-    "args": ["-y", "slackxmcp", "mcp", "--channels"]
-  }
-}
-```
-
-Telegram:
-
-```json
-{
-  "telegram": {
-    "type": "stdio",
-    "command": "npx",
-    "args": ["-y", "tgfmcp", "mcp", "--channels"]
-  }
-}
-```
-
-WhatsApp:
-
-```json
-{
-  "whatsapp": {
-    "type": "stdio",
-    "command": "npx",
-    "args": ["-y", "wappmcp", "mcp", "--channels"]
-  }
-}
-```
-
-Jira:
-
-```json
-{
-  "jira": {
-    "type": "stdio",
-    "command": "npx",
-    "args": ["-y", "jiraxmcp", "mcp", "--channels"],
-    "env": {
-      "JIRA_HOST": "https://your-domain.atlassian.net",
-      "JIRA_EMAIL": "you@example.com",
-      "JIRA_API_TOKEN": "...",
-      "JIRA_WEBHOOK_HOST": "127.0.0.1",
-      "JIRA_WEBHOOK_PORT": "6543",
-      "JIRA_WEBHOOK_SECRET": "..."
-    }
-  }
-}
-```
-
-For Jira, either use `JIRA_EMAIL` plus `JIRA_API_TOKEN`, or use `JIRA_ACCESS_TOKEN` instead. `JIRA_WEBHOOK_SECRET` is optional; include it when Jira admin webhooks are configured with a secret.
-
-## Setup By Channel
-
-### Cron
-
-- Requirements: Node.js `24+`.
-- Start package: `npx cronmcp mcp --channels`.
-- Tools include `cron_list_jobs`, `cron_add_job`, `cron_update_job`, and `cron_remove_job`.
-- Schedules are local-time 5-field cron expressions: `minute hour day-of-month month day-of-week`.
-- Local state is stored under `~/.cronmcp/`; jobs are JSONL records in `~/.cronmcp/crontab`.
-- Limits and behavior: at most 50 jobs, next run must be within one year, recurring jobs auto-expire after 7 days, `once: true` jobs are removed after the first successful tick.
-- Channel metadata: `meta.source` is `cron`, `meta.user` is `scheduler`, `meta.session` is the cron job ID, and `meta.thread` is omitted.
-
-Example scheduled prompt request after the server is connected:
-
-```text
-Use cron_add_job with schedule "*/15 * * * *" and prompt "Check failed builds and report anything urgent".
-```
-
-### Slack
-
-- Requirements: Node.js `24+` and a Slack app with Socket Mode enabled.
-- Configure first with `npx slackxmcp configure`; it writes `~/.slackxmcp/config.json`.
-- The configure UI manages app token, bot token, user token, allowed users, and allowed channels.
-- Minimum Slack app setup: Socket Mode app token with `connections:write`; token scopes for the surfaces used, commonly `channels:read`, `groups:read`, `im:read`, `mpim:read`, history scopes for those surfaces, `chat:write`, `reactions:write`, and `users:read`.
-- Add event subscriptions for needed message surfaces, such as `message.channels`, `message.groups`, `message.im`, and `message.mpim`.
-- `slack_search_messages` usually requires a user token with `search:read`.
-- For permission prompts in Slack, enable Slack app Interactivity so Block Kit button actions are delivered over Socket Mode.
-- Channel events obey configured allowlists. If no allowed users or channels are configured, all inbound events are emitted.
-- Channel metadata: `meta.source` is `slack`, `meta.user` is the sender user ID, `meta.session` is the conversation ID, and `meta.thread` is the thread timestamp or message timestamp.
-
-### Telegram
-
-- Requirements: Node.js `24+` and a Telegram bot token.
-- Configure first with `npx tgfmcp configure`; it writes `~/.tgfmcp/config.json`.
-- The configure UI manages bot token, allowed users, and allowed chats.
-- To enroll users or chats, use the configure UI's generated short code and send it from the target Telegram user or chat.
-- Telegram bots can only interact with chats where the bot has been added, contacted, or otherwise permitted.
-- Incoming media is downloaded under `~/.tgfmcp/attachments/` and included as local attachment paths.
-- Channel events obey configured allowlists. If no allowed users or chats are configured, all inbound events are emitted.
-- Channel metadata: `meta.source` is `telegram`, `meta.user` is the sender identity seed, `meta.session` is the chat identity seed, and `meta.thread` is the Telegram message ID.
-- Permission prompts are posted back into the originating chat with inline approval buttons.
-
-### WhatsApp
-
-- Requirements: Node.js `24+` and a local Chrome or Chromium installation that Puppeteer can launch.
-- If browser auto-detection fails, set `WAPPMCP_BROWSER_PATH` or `PUPPETEER_EXECUTABLE_PATH`.
-- Configure first with `npx wappmcp configure`; it writes `~/.wappmcp/config.json`.
-- First login requires scanning a WhatsApp Web QR code. Session data lives under `~/.wappmcp/profile`.
-- The configure UI manages connect/disconnect, allowed users, and allowed chats.
-- Incoming media and quoted-parent media are downloaded under `~/.wappmcp/attachments/`.
-- Channel events obey configured allowlists. If no allowed users or chats are configured, all inbound events are emitted.
-- Channel metadata: `meta.source` is `whatsapp`, `meta.user` is the sender identity seed, `meta.session` is the chat identity seed, and `meta.thread` is the WhatsApp message ID.
-- Permission prompts are posted back into the originating WhatsApp chat; supported replies are `yes`, `always`, and `no`.
-
-### Jira
-
-- Requirements: Node.js `24+`, Jira Cloud `JIRA_HOST`, and either `JIRA_EMAIL` plus `JIRA_API_TOKEN` or `JIRA_ACCESS_TOKEN`.
-- Start package: `npx jiraxmcp mcp --channels`.
-- For webhook channels, configure Jira admin webhooks to call `http://your-host:6543/webhook` by default.
-- `JIRA_WEBHOOK_PORT` overrides `6543`; `JIRA_WEBHOOK_HOST` defaults to `127.0.0.1`. Use `0.0.0.0` only when the listener must accept traffic from another machine.
-- If Jira webhooks use a secret, set `JIRA_WEBHOOK_SECRET`; incoming `X-Hub-Signature` headers are verified before events are emitted.
-- Local data is stored under `~/.jiraxmcp/`; downloaded attachments are saved under `~/.jiraxmcp/attachments/`.
-- Channel metadata: `meta.source` is `jira`, `meta.user` is the best available Jira actor ID, `meta.session` is usually the issue key, and `meta.thread` is omitted.
-
 ## Verification
 
 After setup:

package/dist/core/skills/built-in/hooman-channels/channels.md

@@ -0,0 +1,117 @@
+# Channel Setup Reference
+
+Per-channel `mcp.json` entries, requirements, and setup details. Add requested entries under top-level `mcpServers`.
+
+## Cron
+
+```json
+{
+  "cron": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "cronmcp", "mcp", "--channels"]
+  }
+}
+```
+
+- Requirements: Node.js `24+`.
+- Tools include `cron_list_jobs`, `cron_add_job`, `cron_update_job`, and `cron_remove_job`.
+- Schedules are local-time 5-field cron expressions: `minute hour day-of-month month day-of-week`.
+- Local state is stored under `~/.cronmcp/`; jobs are JSONL records in `~/.cronmcp/crontab`.
+- Limits and behavior: at most 50 jobs, next run must be within one year, recurring jobs auto-expire after 7 days, `once: true` jobs are removed after the first successful tick.
+- Channel metadata: `meta.source` is `cron`, `meta.user` is `scheduler`, `meta.session` is the cron job ID, and `meta.thread` is omitted.
+
+Example scheduled prompt request after the server is connected:
+
+```text
+Use cron_add_job with schedule "*/15 * * * *" and prompt "Check failed builds and report anything urgent".
+```
+
+## Slack
+
+```json
+{
+  "slack": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "slackxmcp", "mcp", "--channels"]
+  }
+}
+```
+
+- Requirements: Node.js `24+` and a Slack app with Socket Mode enabled.
+- Configure first with `npx slackxmcp configure`; it writes `~/.slackxmcp/config.json`. The configure UI manages app token, bot token, user token, allowed users, and allowed channels.
+- Minimum Slack app setup: Socket Mode app token with `connections:write`; token scopes for the surfaces used, commonly `channels:read`, `groups:read`, `im:read`, `mpim:read`, history scopes for those surfaces, `chat:write`, `reactions:write`, and `users:read`.
+- Add event subscriptions for needed message surfaces, such as `message.channels`, `message.groups`, `message.im`, and `message.mpim`.
+- `slack_search_messages` usually requires a user token with `search:read`.
+- For permission prompts in Slack, enable Slack app Interactivity so Block Kit button actions are delivered over Socket Mode.
+- Channel events obey configured allowlists. If no allowed users or channels are configured, all inbound events are emitted.
+- Channel metadata: `meta.source` is `slack`, `meta.user` is the sender user ID, `meta.session` is the conversation ID, and `meta.thread` is the thread timestamp or message timestamp.
+
+## Telegram
+
+```json
+{
+  "telegram": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "tgfmcp", "mcp", "--channels"]
+  }
+}
+```
+
+- Requirements: Node.js `24+` and a Telegram bot token.
+- Configure first with `npx tgfmcp configure`; it writes `~/.tgfmcp/config.json`. The configure UI manages bot token, allowed users, and allowed chats.
+- To enroll users or chats, use the configure UI's generated short code and send it from the target Telegram user or chat.
+- Telegram bots can only interact with chats where the bot has been added, contacted, or otherwise permitted.
+- Incoming media is downloaded under `~/.tgfmcp/attachments/` and included as local attachment paths.
+- Channel events obey configured allowlists. If no allowed users or chats are configured, all inbound events are emitted.
+- Channel metadata: `meta.source` is `telegram`, `meta.user` is the sender identity seed, `meta.session` is the chat identity seed, and `meta.thread` is the Telegram message ID.
+- Permission prompts are posted back into the originating chat with inline approval buttons.
+
+## WhatsApp
+
+```json
+{
+  "whatsapp": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "wappmcp", "mcp", "--channels"]
+  }
+}
+```
+
+- Requirements: Node.js `24+` and a local Chrome or Chromium installation that Puppeteer can launch. If browser auto-detection fails, set `WAPPMCP_BROWSER_PATH` or `PUPPETEER_EXECUTABLE_PATH`.
+- Configure first with `npx wappmcp configure`; it writes `~/.wappmcp/config.json`. The configure UI manages connect/disconnect, allowed users, and allowed chats.
+- First login requires scanning a WhatsApp Web QR code. Session data lives under `~/.wappmcp/profile`.
+- Incoming media and quoted-parent media are downloaded under `~/.wappmcp/attachments/`.
+- Channel events obey configured allowlists. If no allowed users or chats are configured, all inbound events are emitted.
+- Channel metadata: `meta.source` is `whatsapp`, `meta.user` is the sender identity seed, `meta.session` is the chat identity seed, and `meta.thread` is the WhatsApp message ID.
+- Permission prompts are posted back into the originating WhatsApp chat; supported replies are `yes`, `always`, and `no`.
+
+## Jira
+
+```json
+{
+  "jira": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "jiraxmcp", "mcp", "--channels"],
+    "env": {
+      "JIRA_HOST": "https://your-domain.atlassian.net",
+      "JIRA_EMAIL": "you@example.com",
+      "JIRA_API_TOKEN": "...",
+      "JIRA_WEBHOOK_HOST": "127.0.0.1",
+      "JIRA_WEBHOOK_PORT": "6543",
+      "JIRA_WEBHOOK_SECRET": "..."
+    }
+  }
+}
+```
+
+- Requirements: Node.js `24+`, Jira Cloud `JIRA_HOST`, and either `JIRA_EMAIL` plus `JIRA_API_TOKEN` or `JIRA_ACCESS_TOKEN`.
+- For webhook channels, configure Jira admin webhooks to call `http://your-host:6543/webhook` by default.
+- `JIRA_WEBHOOK_PORT` overrides `6543`; `JIRA_WEBHOOK_HOST` defaults to `127.0.0.1`. Use `0.0.0.0` only when the listener must accept traffic from another machine.
+- If Jira webhooks use a secret, set `JIRA_WEBHOOK_SECRET`; incoming `X-Hub-Signature` headers are verified before events are emitted. Otherwise it is optional.
+- Local data is stored under `~/.jiraxmcp/`; downloaded attachments are saved under `~/.jiraxmcp/attachments/`.
+- Channel metadata: `meta.source` is `jira`, `meta.user` is the best available Jira actor ID, `meta.session` is usually the issue key, and `meta.thread` is omitted.

package/dist/core/skills/built-in/hooman-coding/SKILL.md

@@ -1,71 +1,76 @@
 ---
 name: hooman-coding
-description: Required coding playbook for this workspace—load via filesystem before writing source, adding deps, or running package/build commands. Applies to every programming task, regardless of simplicity or complexity, even one-file scripts or spikes. Covers research, security, tests, lint/format/build verification, and RCA for bugs.
+description: Required playbook for every programming task — load before the first implementation tool call whenever you will write or edit code, fix a bug, add or upgrade dependencies, scaffold a project, or run package/build/test commands, even for one-file scripts or spikes. Covers workflow, conventions, tests, verification, security, debugging/RCA, and greenfield setup. Skip only when purely reading or explaining code with no changes planned.
 ---
 
 # Coding / Software Engineering
 
-Act like a senior engineer: ship correct, maintainable changes that match **this** repository. Prefer **local** patterns, tooling, and conventions over generic or invented architecture—then align those choices with current industry practice where it helps.
+Act like a senior engineer: ship correct, maintainable changes that match **this** repository. Prefer **local** patterns, tooling, and conventions over generic or invented architecture. Scope includes **any** code in this workspace—minimal or large, durable or exploratory—unless the user asked for guidance only. Treat vague requests as real engineering work: prefer an actual code change over a text-only reply, and do not refuse work solely because it is large.
 
-Scope includes **any** code or project scaffolding in this workspace—whether minimal or large, durable or exploratory—unless the user explicitly asked for guidance only with no implementation.
+Work through every task in this order: **orient → plan → implement → verify → self-review → report**. Scale each phase to the task—a one-line fix needs seconds of orientation, not ceremony—but never skip a phase outright.
 
-## Before you implement
+## Reference files
 
-- **Research**: Combine what you know with targeted lookup when needed—official docs, release notes, GitHub issues/PRs, Stack Overflow, migration guides, and security advisories. Prefer solutions and APIs that are widely used, documented, and actively maintained.
-- **Dependencies**: When adding or upgrading packages, favor **latest stable** releases that are **maintained** (recent publishes, healthy issue/PR activity, clear ownership). Avoid abandoned forks and deprecated APIs unless the project already depends on them or the user directs otherwise.
-- **Conventions**: Infer structure, naming, formatting, and architectural boundaries from existing code and project docs (`CONTRIBUTING`, linters, CI). Match the house style; do not impose a different framework or layout without a strong, stated reason.
+Read these siblings (next to this SKILL.md) when they apply:
 
-## Implementation discipline
+- `debugging.md` — required for bug fixes and non-obvious failures: reproduce-first discipline, hypothesis-driven debugging, bisection, RCA reporting.
+- `new-project.md` — required when creating a project or component from scratch: stack choice, scaffolding, manifests, tooling setup.
 
-- Treat vague requests as **real engineering work** in repo context: prefer an actual code change over a superficial text-only reply.
-- Respect the user’s scope; do not refuse work solely because it is large—confirm only when ambiguity would cause harm.
-- **Read** surrounding code and **open a file before editing it**. Preserve public behavior unless the user asked for a change or the behavior is clearly wrong.
-- Keep edits **narrow**, **coherent**, and easy to review. Prefer **simple** code that fully solves the problem over clever or over-generalized designs.
-- Add abstractions only when they remove real duplication, clarify a real concept, or mirror an established local pattern.
-- Avoid throwaway compatibility shims, placeholder re-exports, “removed” tombstones, and legacy aliases when old code can be deleted cleanly.
-- **Comments**: do not add them by default. Add only for non-obvious constraints, invariants, workarounds, or surprising behavior.
-- Avoid drive-by changes: no unrelated types, docstrings, formatting-only edits, new files, features, config knobs, speculative validation, feature flags, or defensive branches for impossible scenarios. Do not invent one-off helpers for hypothetical futures.
+## Orient
 
-## Testing
+Build real understanding before editing; this phase determines the quality of everything after it.
 
-- **Default**: add or update **unit tests** and/or **integration tests** that match the project’s existing test stack and locations—unless the user **explicitly** asks to skip tests or the repo genuinely has no test harness for that layer.
-- Prefer focused tests that lock in the behavior you changed or fixed; follow existing patterns (fixtures, mocks, snapshots) instead of introducing a parallel style.
+- **Locate the code path**: search for the relevant symbols, then read definitions _and_ call sites—never change a signature or behavior without knowing who depends on it. Read a module's tests to learn its actual contract.
+- **Copy the house pattern**: when adding a feature, find the closest existing sibling feature and use it as the template for structure, naming, and wiring. Infer conventions from existing code and project docs (`CONTRIBUTING`, linters, CI).
+- **Detect the environment**: package manager from the lockfile (npm/pnpm/yarn/bun, pip/uv/poetry, …), runtime pins (`.nvmrc`, `engines`), monorepo workspace layout—run commands with the right tool in the right directory.
+- **Research when needed**: targeted lookup of official docs, release notes, issues/PRs, migration guides, advisories. Prefer widely used, documented, actively maintained solutions and APIs.
 
-## Verification each turn
+## Plan
 
-When the project provides the hooks, **after substantive edits** in a turn:
+- Identify the **minimal change set** that fully solves the request, and its blast radius. Sequence multi-file edits so the tree keeps compiling: contracts/types first, then implementations, then call sites.
+- For wide mechanical changes, convert **one instance**, verify it, then replicate the pattern.
+- **Ambiguity protocol**: when a decision is low-risk and reversible, pick the option most consistent with the codebase, **state the assumption in your reply**, and proceed. Ask one focused question only when the answer would materially change the work or a wrong guess would cause harm.
+- If the task reveals a deeper design problem, flag it and stay scoped—do not silently expand into a redesign.
 
-1. Run **formatter** and **linter** using the repo’s configured commands (or IDE-equivalent rules).
-2. Run **build** (compile/bundle) if applicable.
-3. Run **tests** relevant to the change (full suite when reasonable and fast enough; otherwise the narrowest meaningful subset).
+## Implement
 
-If a command fails, **diagnose from output** before retrying or changing approach; do not mask failures.
+- **Read before writing**: open a file before editing it. Preserve public behavior unless the user asked for a change or it is clearly wrong.
+- Keep edits **narrow, coherent, and easy to review**. Prefer simple code that fully solves the problem over clever or over-generalized designs. Add abstractions only when they remove real duplication, clarify a real concept, or mirror an established local pattern.
+- **Dependencies**: favor latest stable, maintained releases. Avoid abandoned forks and deprecated APIs unless the project already depends on them or the user directs otherwise.
+- No drive-by changes: no unrelated types, docstrings, formatting-only edits, features, config knobs, feature flags, speculative validation, compatibility shims, or defensive branches for impossible scenarios. Delete old code cleanly instead of aliasing it.
+- **Comments**: none by default; only for non-obvious constraints, invariants, workarounds, or surprising behavior.
+- **Edge-case reflex**: for the paths you touched, consider empties, nulls, unicode, timezones, boundary indices, concurrency, idempotency—handle what is reachable, skip what is impossible.
+- **Performance**: optimize only with evidence, but notice obvious N+1s or quadratic loops on hot paths you touch—fix in scope, otherwise flag.
 
-## Security and correctness
+## Verify
 
-- **Credentials**: Keep secrets out of source. Prefer **environment variables**, **per-environment** local files when the stack uses them (e.g. `.env`, `.env.local`, `.env.development`), or **dedicated secrets files** under paths the project already documents (plus provider secret stores in deployed environments). In a **Git** repo, ensure those paths are **`.gitignore`d** (or equivalent) so keys never get committed; wire reads through the stack’s normal config loader. Do not embed API keys, tokens, or passwords in code, fixtures, or checked-in JSON unless the user explicitly demands it—and still prefer env or secret injection.
-- Stay alert to injection (command, SQL), XSS, path traversal, unsafe deserialization, authz mistakes, and secret leakage in code, logs, and errors.
-- Prefer **structured parsers and APIs** over fragile string parsing for structured data.
-- Treat generated artifacts, lockfiles, migrations, and shared config as **contracts**: touch them only when the task requires it, and keep them consistent.
-- Do not swallow errors with broad catches, silent fallbacks, disabled hooks, or weakened checks unless the codebase already establishes that pattern for a good reason.
+- **Tests**: add or update unit/integration tests that lock in the behavior you changed, matching the project's existing stack, locations, and patterns—unless the user explicitly skips tests or the repo has no harness for that layer.
+- After substantive edits, when the project provides the hooks: run **formatter**, **linter**, **build**, and tests—**narrowest meaningful check first** (the one test file, the one workspace package), full suite only when blast radius warrants and it is reasonably fast.
+- **Never claim a check passed without running it.** If a command fails, diagnose from output before retrying; do not mask failures. Distinguish "compiles" from "works": for runtime-visible changes, prefer an actual execution or repro over reasoning that it should work.
+
+## Self-review
 
-## Bug fixes: root cause first
+Before reporting, reread your own diff as a reviewer would:
 
-1. **Gather evidence**: logs, stack traces, CI output, terminal repro, failing tests, and user steps.
-2. **Trace**: follow the failure from symptom to the responsible code path; form a **root cause hypothesis** (RCA) before editing.
-3. **Fix**: apply the smallest change that addresses the cause, with tests when appropriate.
-4. **Close the loop**: at the end of the turn, give the user a concise **RCA** (what broke and why) and a **fix summary** (what changed and how it resolves the issue). If certainty is limited, say what remains unproven and what would verify it.
+- leftover debug prints, unused imports, dead code, stray TODOs;
+- naming and style inconsistent with the surrounding file;
+- accidentally weakened types, broadened catches, or disabled checks;
+- comments/docs now stale because behavior changed;
+- generated artifacts, lockfiles, migrations, and shared config treated as contracts—touched only when the task required it, kept consistent.
 
-Avoid blind retries; if blocked after investigation, ask **one focused question**.
+## Security and correctness
+
+- **Credentials**: keep secrets out of source. Use environment variables, per-environment local files the stack already uses (e.g. `.env.local`), or documented secrets paths—**`.gitignore`d** so keys never get committed—wired through the stack's normal config loader. Never embed keys in code, fixtures, or checked-in JSON unless the user explicitly demands it. If credentials appear exposed, warn **without repeating** the secret.
+- Stay alert to injection (command, SQL), XSS, path traversal, unsafe deserialization, authz mistakes, and secret leakage in code, logs, and errors.
+- Prefer structured parsers and APIs over fragile string parsing. Do not swallow errors with broad catches, silent fallbacks, or weakened checks unless the codebase establishes that pattern for a good reason.
 
 ## Project hygiene
 
-- Work on the **current** working tree; do not revert user changes unless asked.
-- If unrelated local changes affect the task, inspect and adapt; ask only when safe progress is impossible.
-- Do **not** create commits, push, amend, force-push, or alter remotes unless the user explicitly requests it.
-- Never put secrets in commits, patches, or user-facing text; align with **`.gitignore`d** env/secrets files when adding new credential plumbing. If credentials appear exposed, warn **without repeating** the secret.
+- Work on the **current** working tree; do not revert user changes unless asked. If unrelated local changes affect the task, inspect and adapt; ask only when safe progress is impossible.
+- Do **not** commit, push, amend, force-push, or alter remotes unless the user explicitly requests it. Never put secrets in commits, patches, or user-facing text.
 
-## Communication
+## Report
 
-- Skip time estimates; describe what you did and what remains.
-- When research influenced a decision (e.g., a known framework bug or recommended API), mention it briefly so the user can trace it.
+- State the outcome, what you verified (and how), and any assumption made under the ambiguity protocol.
+- For bug fixes, give a concise RCA and fix summary; if certainty is limited, say what remains unproven and what would verify it.
+- When research influenced a decision, mention it briefly. Skip time estimates; describe what you did and what remains.

package/dist/core/skills/built-in/hooman-coding/debugging.md

@@ -0,0 +1,26 @@
+# Debugging And Bug Fixes
+
+Root cause first. Never fix by guesswork or blind retries.
+
+## Reproduce first
+
+1. **Reproduce the failure before touching code.** Gather logs, stack traces, CI output, failing tests, and user steps; turn them into a concrete repro you can run—ideally a **failing test** in the project's existing harness, which later becomes the regression test.
+2. If you cannot reproduce, say so and instrument instead of guessing: add targeted logging or assertions around the suspected path, run, and read the evidence.
+3. **Minimize the repro** when the failure is noisy: cut inputs, config, and steps until the smallest case that still fails remains.
+
+## Trace to root cause
+
+- Work **hypothesis-driven**: form an explicit hypothesis about the cause, pick the cheapest observation that would confirm or kill it, run it, repeat. Do not shotgun edits.
+- Read stack traces from the **deepest frame you own** upward; the top frame is often a symptom.
+- Follow the failure from symptom to responsible code path; verify assumptions at each hop (actual values, not expected ones).
+- **Bisect** when the cause is not obvious: halve the input, disable half the suspects, or bisect history—`git log`/`git blame` on the failing path, or `git bisect` with the repro when the bug is a regression.
+- Check the boring causes early: stale build artifacts, wrong environment/versions, cached state, unset env vars, timezone/locale, and recent dependency bumps.
+
+## Fix and close the loop
+
+1. Apply the **smallest change that addresses the cause**, not the symptom. If the real fix is out of scope, say so explicitly rather than papering over it.
+2. Re-run the **exact repro** (and the new regression test) to confirm the fix; then run the surrounding checks per the main skill's Verify phase.
+3. Remove any temporary instrumentation you added.
+4. Report a concise **RCA** (what broke and why) and **fix summary** (what changed and how it resolves the issue). If certainty is limited, state what remains unproven and what would verify it.
+
+If blocked after genuine investigation, ask **one focused question** with the evidence you gathered—not a list of open-ended possibilities.

package/dist/core/skills/built-in/hooman-coding/new-project.md

@@ -0,0 +1,23 @@
+# Greenfield Projects And Components
+
+For creating a project, package, or substantial component from scratch (no existing house pattern to copy).
+
+## Stack and structure
+
+- Choose a **boring, standard stack**: widely used, documented, actively maintained tools that match the user's stated constraints and ecosystem. Do not invent architecture or pick niche frameworks without a stated reason.
+- Match the ecosystem's conventional layout (e.g. `src/` + entrypoint, standard config file locations) so future tools and contributors find things where they expect them.
+- Start with the **smallest scaffold that builds and runs**, verify it, then add features incrementally—never a big-bang tree of untested files.
+
+## Manifests and tooling
+
+- Create a real dependency manifest (`package.json`, `requirements.txt`/`pyproject.toml`, `go.mod`, …) with **actual current versions**—add dependencies via the package manager rather than guessing version numbers.
+- Pin the runtime where the ecosystem supports it (`.nvmrc`/`engines`, `requires-python`, …).
+- Set up the basics the ecosystem expects: formatter, linter, test runner, and the corresponding scripts/commands—configured minimally, using defaults over bespoke rule sets.
+- Add a `.gitignore` appropriate to the stack before generating build artifacts, and keep env/secrets files ignored from the start.
+
+## Deliverables
+
+- A **README** with what the project is, prerequisites, install, run, and test commands—short and accurate beats long and aspirational.
+- A working entrypoint the user can run immediately; verify the documented commands actually work before reporting.
+- For web apps: a clean, modern UI with sensible defaults (layout, spacing, typography, responsive behavior)—polish the default experience rather than shipping unstyled scaffolding.
+- Example configuration (`.env.example` or equivalent) when the project needs credentials, with placeholders instead of real values.