Create DotCraft Hooks

Overview

DotCraft hooks are lifecycle event triggers that run external shell commands at key agent execution points. Hooks are configured in hooks.json and can observe, log, or block agent actions.

Workflow

1. Ask the user what they want to achieve (security guard, auto-format, logging, notification, etc.)
2. Determine which lifecycle event(s) to use
3. Determine scope: workspace (.craft/hooks.json), global (~/.craft/hooks.json), or plugin (<plugin-root>/hooks/hooks.json)
4. Generate the hooks.json config and any helper scripts
5. Place scripts in .craft/hooks/, the user's chosen global hooks directory, or the plugin's hooks/ directory

Config File Locations

Global hooks load first, workspace hooks are appended, and enabled plugin hooks run after config hooks. Plugin hooks are additive and read-only from Desktop; Desktop manages only user state.

Config Format

{
    "hooks": {
        "<EventName>": [
            {
                "matcher": "<regex for tool names>",
                "hooks": [
                    {
                        "type": "command",
                        "command": "<shell command>",
                        "timeout": 30
                    }
                ]
            }
        ]
    }
}

Fields

Trust and User State

DotCraft stores per-hook user state in global ~/.craft/config.json under Hooks.State.

{
  "Hooks": {
    "State": {
      "<hook-key>": {
        "Enabled": false,
        "TrustedHash": "sha256:..."
      }
    }
  }
}

• Enabled: false disables one hook without editing hooks.json.
• TrustedHash records the normalized hook definition the user approved.
• Config and plugin hooks must be trusted before they run. Modified hooks need trust again.
• Do not write trust state into workspace .craft/config.json; it is personal user state.

For plugin hooks, commands may use ${DOTCRAFT_PLUGIN_ROOT} and ${DOTCRAFT_PLUGIN_DATA}. DotCraft expands these variables in the command and also injects them as environment variables.

Lifecycle Events

DotCraft emits both camelCase and snake_case field names. Prefer snake_case in portable scripts.

Exit Codes

JSON Output

Hooks may print plain text or JSON. Plain text becomes additional context for context-capable events. JSON output can use:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Model-visible guidance"
  },
  "decision": "block",
  "reason": "Why the action should stop or continue with feedback",
  "systemMessage": "Optional user-visible status"
}

Use hookSpecificOutput.additionalContext for guidance that should be shown to the model without leaking raw JSON.

Built-in Tool Names (for matcher)

Matcher is case-insensitive regex. Examples: "" (all), "WriteFile|EditFile" (write ops), ".*File" (all file ops), "Exec" (shell only).

The optional if field supports portable conditions such as Bash(git commit:*). DotCraft maps common tool aliases: shell execution to Bash, full-file writes to Write, and search/replace edits to Edit.

Platform Differences

• Linux/macOS: Commands run via /bin/bash -c '<command>'. Use standard bash syntax, jq for JSON parsing.
• Windows: Commands run via powershell.exe -File <temp.ps1>. Use PowerShell syntax, ConvertFrom-Json for JSON parsing.

Windows (PowerShell) stdin reading pattern

$input_data = [Console]::In.ReadToEnd() | ConvertFrom-Json
$toolName = $input_data.toolName
$toolArgs = $input_data.toolArgs

Windows blocking pattern (exit 2)

$input_data = [Console]::In.ReadToEnd() | ConvertFrom-Json
# ... check logic ...
if ($shouldBlock) {
    [Console]::Error.WriteLine("Block reason here")
    exit 2
}
exit 0

Linux/macOS stdin reading pattern

INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName // empty')
TOOL_ARGS=$(echo "$INPUT" | jq -c '.toolArgs')

Best Practices

1. Always consume stdin — even if unused, read it (cat > /dev/null or [Console]::In.ReadToEnd() | Out-Null) to avoid broken pipe errors
2. Use jq (bash) or ConvertFrom-Json (PowerShell) for JSON parsing
3. Append || true (bash) or try/catch (PowerShell) inside helper scripts for non-critical work
4. Set reasonable timeouts — default is 30s, increase for slow operations
5. Use exit 2 intentionally — reserve it for blocking events or for asyncRewake feedback
6. Write block reasons to stderr — echo "reason" >&2 (bash) or [Console]::Error.WriteLine("reason") (PowerShell)
7. No interactive commands — hooks run in background without user input
8. Place complex logic in script files — store in .craft/hooks/ and reference from hooks.json

Generation Rules

When generating hooks for the user:

1. Detect the OS from workspace context — use PowerShell syntax on Windows, bash on Linux/macOS
2. For complex hooks, create script files in the selected hooks directory and reference them in the command field
3. Always create the hooks script directory before placing script files there
4. Merge with existing config — if .craft/hooks.json already exists, read it first and merge new hooks into the existing config rather than overwriting
5. Validate event names — use events from specs/core/lifecycle-hooks.md; common choices are SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PrePrompt, and Stop
6. Validate matcher patterns — ensure regex is valid
7. Ensure hooks are enabled — check that config.json does not have "Hooks": { "Enabled": false }
8. Leave trust to the user — mention that new or modified hooks must be trusted through Desktop Hooks settings or hooks/setState

Cron

Use Cron for scheduled background agent runs that should happen later or repeatedly. Do not use it for a short blocking wait inside the current turn.

Workflow

1. Choose action: add, list, or remove.
2. For add, always include scheduleKind.
3. Keep the schedule fields for the selected kind readable; ignore unrelated auto-filled schedule fields because scheduleKind is authoritative.
4. Use list before remove when you do not know the job id.

Add Jobs

Examples:

Cron(action: "add", scheduleKind: "at", message: "Remind me to check the build", delaySeconds: 600)
Cron(action: "add", scheduleKind: "every", message: "Summarize CI status", everySeconds: 3600)
Cron(action: "add", scheduleKind: "every", message: "Ping service", everySeconds: 3600, delaySeconds: 300)
Cron(action: "add", scheduleKind: "daily", message: "Prepare standup notes", dailyTime: "09:30", timeZone: "Asia/Hong_Kong")

Delivery

By default, deliver is true and DotCraft sends the run result back to the creator's current channel or session target. Set deliver: false only when the job should update state without notifying the user. Use channel and toUser only when the user explicitly wants a different delivery target.

List And Remove

Cron(action: "list")
Cron(action: "remove", jobId: "abc12345")

Validation Recovery

• Missing scheduleKind: retry with at, every, or daily.
• scheduleKind: "at" requires a positive delaySeconds.
• scheduleKind: "every" requires a positive everySeconds; delaySeconds is only the first-run delay.
• scheduleKind: "daily" requires dailyTime or dailyHour; dailyMinute defaults to 0.
• Daily time zones should be IANA ids such as Asia/Hong_Kong; omitted means UTC.

Heartbeat

Purpose

Heartbeat is a lightweight recurring check. DotCraft periodically reads .craft/HEARTBEAT.md and may run you on the actionable items in that file.

Use Heartbeat for simple recurring checks or standing tasks that should be reviewed on a fixed interval without creating a full automation workflow.

Maintain The Task File

Heartbeat reads .craft/HEARTBEAT.md.

• When the user wants a lightweight recurring checklist, maintain .craft/HEARTBEAT.md.
• Use ReadFile before editing it.
• Use EditFile to add, update, or remove periodic tasks.
• Use WriteFile only when replacing the whole file intentionally.

If the file contains only headings, blank lines, or HTML comments, Heartbeat treats it as empty and skips the run.

Writing Guidance

Write concrete recurring tasks in .craft/HEARTBEAT.md. Prefer short, actionable instructions that you can execute during a future heartbeat run.

Good examples:

• "Check the latest CI failures and summarize new regressions."
• "Review the inbox for urgent messages and draft a short summary."
• "Scan open PRs that are waiting for review and report blockers."

When Nothing Needs Action

If you are triggered by Heartbeat and there is nothing actionable in .craft/HEARTBEAT.md, respond with HEARTBEAT_OK.

Memory

Structure

• memory/MEMORY.md — Long-term facts (preferences, project context, relationships). Always loaded into your context.
• memory/HISTORY.md — Append-only event log. NOT loaded into context; search it with grep when you need to recall past events.

Search Past Events

Use GrepFiles to search HISTORY.md (cross-platform, no shell dependency):

GrepFiles(pattern="keyword", path="memory", include="HISTORY.md")

Regex patterns work too — e.g. pattern="meeting|deadline|project" matches any of those words.

For advanced search (e.g. context lines), use Exec with shell grep:

grep -i -C 3 "keyword" "memory/HISTORY.md"

Always search HISTORY.md when the user asks about past events, decisions, or conversations that aren't covered by MEMORY.md.

When to Update MEMORY.md

Write important facts to MEMORY.md immediately when you learn them:

• User preferences ("I prefer dark mode", "call me Alex")
• Project context ("The API uses OAuth2", "deploy target is AWS")
• Key relationships ("Alice is the project lead")
• Recurring instructions ("Always write tests before merging")

Use EditFile or WriteFile to update MEMORY.md. Keep it concise and well-organized.

Auto-consolidation

Old conversations are automatically summarized: long-term facts are extracted to MEMORY.md, and event entries are appended to HISTORY.md. You don't need to manage this process — just focus on writing important facts immediately when they come up.

Plugin Creator

Use this skill when the user wants to create, scaffold, or maintain a DotCraft plugin directory.

Quick Start

Default to a workspace-local plugin under <workspace>/.craft/plugins/<plugin-id>:

python .craft/skills/plugin-creator/scripts/create_basic_plugin.py "My Plugin"

If reading the skill from the source tree instead of a deployed workspace skill, use the source-tree script path from the repo root:

python src/DotCraft.Core/Skills/BuiltIn/plugin-creator/scripts/create_basic_plugin.py "My Plugin"

Use --path when the user asks for another parent directory, such as a user-global plugin container:

python .craft/skills/plugin-creator/scripts/create_basic_plugin.py "My Plugin" --path "$HOME/.craft/plugins"

Defaults

• Normalize plugin ids to lowercase hyphen-case, max 64 characters.
• Create <parent>/<plugin-id>/.craft-plugin/plugin.json.
• Create a skill plugin by default with skills: "./skills/".
• Create skills/<skill-name>/SKILL.md; --skill-name defaults to the plugin id.
• Add --with-mcp to create a plugin-bundled .mcp.json placeholder.
• Add --with-hooks to create a plugin-bundled hooks/hooks.json placeholder.
• Add --with-assets to create plugin-level icon/logo placeholders.

Manifest Rules

DotCraft schema version 1 allows a plugin to contribute skills, MCP servers, lifecycle hooks, interface metadata, or a combination of these.

• Skill-only plugins are valid when skills points to a plugin-contained skills directory.
• MCP-only plugins are valid when mcpServers points to a plugin-bundled MCP config or a root .mcp.json exists.
• Hooks-only plugins are valid when hooks points to plugin hook files or a root hooks/hooks.json exists.
• Interface-only plugins are valid for catalog or UI metadata.
• Manifest fields tools, functions, and processes are unsupported legacy native tool fields and must not be generated for new plugins.
• Reusable executable capabilities should be exposed through MCP.
• Thread-scoped AppServer client callbacks should use Runtime Dynamic Tools, not plugin manifest fields.
• Manifest-relative paths must start with ./, stay inside the plugin root, and never contain ...

For exact examples, read references/plugin-json-spec.md.

MCP Plugin Template

Use this when creating a plugin that bundles MCP configuration:

python .craft/skills/plugin-creator/scripts/create_basic_plugin.py review-tools --with-mcp

After generation, replace placeholder descriptions and edit .mcp.json to point at the real MCP server command or HTTPS endpoint.

Hooks Plugin Template

Use this when creating a plugin that bundles lifecycle hooks:

python .craft/skills/plugin-creator/scripts/create_basic_plugin.py audit-hooks --without-skill --with-hooks

After generation, replace placeholder descriptions, edit hooks/hooks.json, and update helper scripts under hooks/. Plugin hook commands can use ${DOTCRAFT_PLUGIN_ROOT} and ${DOTCRAFT_PLUGIN_DATA}. First run still requires user trust through Desktop Hooks settings or hooks/setState.

Validation

After scaffolding:

1. Inspect .craft-plugin/plugin.json and replace TODO placeholders.
2. Confirm every manifest-relative path starts with ./.
3. If the plugin has skills, confirm each child skill has SKILL.md.
4. If the plugin has MCP servers, confirm .mcp.json uses the same schema as workspace McpServers.
5. If the plugin has hooks, confirm hooks/hooks.json uses the same shape as .craft/hooks.json.
6. Run relevant DotCraft tests when changing the runtime, or start DotCraft and confirm plugin/list, skills/list, and hooks/list show the plugin contributions.

Skill Authoring

Overview

Skills are procedural memory: reusable, narrow instructions for task types that are likely to recur. Load this skill when you need to create, rewrite, or patch a workspace skill with SkillManage.

Do not create skills for simple one-off answers. A good skill teaches when to use it, what exact steps to follow, what pitfalls to avoid, and how to verify the result.

When To Use

Use SkillManage when:

• A complex task succeeded after several tool calls and produced a reusable workflow.
• A tricky error was fixed and the fix is likely to recur.
• The user explicitly asks you to remember a procedure.
• A user correction revealed a better stable workflow.
• An existing skill was used and found to be stale, incomplete, wrong, or missing a pitfall.

Do not use it for:

• Simple questions, one-off edits, or preferences that belong in memory.
• Speculative workflows that have not been exercised.
• Modifying built-in or user-global skills directly. Create or update a workspace skill instead.

SkillManage Actions

Prefer patch for small changes. Use edit only for major overhauls after reading the current skill.

Required Frontmatter

Every SKILL.md created through SkillManage must start with YAML frontmatter:

---
name: my-skill
description: One-sentence trigger description
version: 0.1.0
---

Rules:

• The file must start with --- with no leading whitespace.
• name must match the name parameter.
• description should describe the trigger class, not the current task.
• The body must be non-empty and actionable.

SKILL.md Structure

Use this structure unless a skill has a strong reason to differ:

# Title

## Overview
What this skill is for and why it exists.

## When To Use
- Concrete trigger conditions.
- Counter-triggers if useful.

## Workflow
1. Exact steps, commands, files, APIs, or checks.
2. Keep steps specific enough to execute later.

## Common Pitfalls
- Known mistakes and fixes.

## Verification
- How to confirm the workflow succeeded.

Supporting Files

Supporting files must stay inside the skill directory under one of:

• scripts/ for helper scripts.
• assets/ for static assets.

Use write_file for supporting files. Use patch with filePath for targeted edits to supporting files. Absolute paths and .. traversal are rejected.

Size Limits

• SkillManage enforces size limits for SKILL.md and supporting files.
• If a skill is growing too large, keep SKILL.md focused on triggers, workflow, pitfalls, and verification. Put executable helpers in scripts/ and static examples in assets/.

Common Pitfalls

1. Creating a skill before the workflow is proven. Wait until the task produced a reusable procedure.
2. Writing a broad skill that tries to cover an entire domain. Split by trigger and workflow.
3. Omitting exact commands, paths, or verification steps. Future use needs concrete instructions.
4. Editing built-in or user-global skills directly. Use a workspace skill.
5. Expecting a newly created skill to be available immediately in the current prompt. It is picked up on the next turn or session refresh.
6. Using edit for a tiny correction. Prefer patch with enough context in oldString.

Verification

Before finishing, confirm the frontmatter starts at byte 0 and includes name, description, and version; name matches the directory and the SkillManage request; the description explains when to use the skill; the body includes workflow, pitfalls, and verification guidance; supporting files stay under scripts/ or assets/; and the skill is narrow enough to be reused without confusion.

Skill Installer

Use this workflow when the user wants to install, import, test, or adapt a DotCraft skill. The installation surface is ordinary shell and file work plus the DotCraft skill verifier; there is no dedicated install tool.

Workflow

1. Prepare a candidate directory.
   • If the user provides a local directory, inspect it directly.
   • If the user provides an archive or URL, download/extract it into a temporary directory in the workspace.
   • If the skill is inside a repository, clone or copy the repository, then point at the subdirectory containing SKILL.md.
2. Ensure the candidate directory is a DotCraft skill bundle.
   • SKILL.md must be at the candidate root.
   • The frontmatter name must exist. If the user or market flow provides a local install name, use that as the CLI --name value; it does not have to match the frontmatter display name exactly.
   • Preserve supporting files where they are. Ordinary relative files such as root markdown/json files, docs/, references/, scripts/, assets/, and agents/openai.yaml can remain in the bundle when verification accepts them.
3. Run verification:

dotcraft skill verify --candidate "<candidate-dir>" --name "<local-skill-name>" --json

Omit --name only when the frontmatter name is already the desired local install name.

4. If verification fails, decide whether the failure can be solved by command arguments before editing files.
   • If the problem is a display/local-name mismatch such as name: Git but the local install name should be git, retry with --name "git".
   • Do not move or rewrite files only because they are root markdown/json files, docs/, or references/.
   • Only make minimal candidate edits for real structural or safety problems: missing SKILL.md, missing required frontmatter, unsafe paths, path traversal, hidden control files, oversized files, or genuinely broken references that the skill itself requires.
   • Never use WriteFile to regenerate a new SKILL.md just to make the skill look more like a DotCraft-native skill. Preserve the imported instructions.
5. Install after verification succeeds:

dotcraft skill install --candidate "<candidate-dir>" --name "<local-skill-name>" --source "<where this came from>" --json

Use --overwrite only when the user explicitly wants to replace the current workspace source skill.

Post-install Review

After installation, load the installed instructions with SkillView(name). Then review the skill against the current workspace and environment by doing only checks that the skill itself makes relevant.

Examples of useful checks:

• If it assumes python, check the actual Python command/version or virtual environment.
• If it assumes a CLI tool, check whether that tool exists and whether the expected command shape works.
• If it references scripts or assets, confirm those files exist in the installed skill.
• If it assumes paths, package managers, shells, or config files, check those in the workspace.

Only write a workspace adaptation when you find a concrete mismatch. If SkillManage is available, use it to patch the effective skill so future runs remember the workspace-specific fix.

Use SkillManage with complete action-specific arguments. Do not call it with placeholder or null values. If a SkillManage call fails because a required argument is missing, retry with the required argument populated.

Examples:

SkillManage(
  action: "patch",
  name: "<installed-skill-name>",
  oldString: "## Existing Section\nOriginal text that appears exactly once.",
  newString: "## Existing Section\nOriginal text plus the workspace-specific adaptation."
)

SkillManage(
  action: "edit",
  name: "<installed-skill-name>",
  content: "<the complete updated SKILL.md content>"
)

SkillManage(
  action: "write_file",
  name: "<installed-skill-name>",
  filePath: "scripts/check-environment.ps1",
  fileContent: "<complete helper script content>"
)

Never use EditFile, WriteFile, or shell redirection to modify files under .craft/skills/<installed-skill-name>/ for workspace adaptation. Those files are the installed source skill. Adaptations must go through SkillManage. If SkillManage is unavailable or keeps failing, report the mismatch and the suggested adaptation instead of editing the source skill.

Do not invent compatibility rules that the skill does not imply. Do not rewrite a freshly installed skill just to summarize the installation.