# Samples & Templates

The [`samples/`](https://github.com/DotHarness/dotcraft/tree/master/samples) directory ships ready-to-copy examples and templates. Each one focuses on a single capability — copy what you need.

> First-time validation: run [Workspace](#workspace) first, then pick Automations / Hooks / Bootstrap / Skills as needed.

## Configuration Templates

| Name | Purpose | Repository |
|---|---|---|
| Workspace | A complete workspace template with `start.sh`, `config.template.json`, optional OpenSandbox launchers | [samples/workspace](https://github.com/DotHarness/dotcraft/tree/master/samples/workspace) |
| Bootstrap · `senior-engineer` | English senior engineer template for architecture, review, debugging | [samples/bootstrap/senior-engineer](https://github.com/DotHarness/dotcraft/tree/master/samples/bootstrap/senior-engineer) |
| Bootstrap · `qq-group-assistant` | Chinese QQ group assistant template for chat Q&A and project support | [samples/bootstrap/qq-group-assistant](https://github.com/DotHarness/dotcraft/tree/master/samples/bootstrap/qq-group-assistant) |

## Workspace Behavior Examples

| Name | Purpose | Repository |
|---|---|---|
| Automations · example-local-task | Local task template (`task.md` + `workflow.md`) | [samples/automations](https://github.com/DotHarness/dotcraft/tree/master/samples/automations) |
| Hooks · windows | PowerShell hooks (block dangerous Exec, log file writes) | [samples/hooks/windows](https://github.com/DotHarness/dotcraft/tree/master/samples/hooks/windows) |
| Hooks · linux | Bash hooks (block dangerous Exec, log file writes) | [samples/hooks/linux](https://github.com/DotHarness/dotcraft/tree/master/samples/hooks/linux) |

## Skills Templates

| Name | Purpose | Repository |
|---|---|---|
| `dev-guide` | Project development standards example with module references | [samples/skills/dev-guide](https://github.com/DotHarness/dotcraft/tree/master/samples/skills/dev-guide) |
| `feature-workflow` | Large feature workflow for breakdown, implementation, validation | [samples/skills/feature-workflow](https://github.com/DotHarness/dotcraft/tree/master/samples/skills/feature-workflow) |
| `dotcraft-llm-error-diagnosis` | Read-only diagnosis flow for LLM / agent / tool / session failures | [samples/skills/llm-error-diagnosis](https://github.com/DotHarness/dotcraft/tree/master/samples/skills/llm-error-diagnosis) |

## Plugin Templates

[`samples/plugins/`](https://github.com/DotHarness/dotcraft/tree/master/samples/plugins) collects reference DotCraft plugin scaffolds. When building your own plugin, scaffold via the built-in `$plugin-creator` first, then refine using these examples.

## Common Workflows

### Workspace

```bash
cd /path/to/your-project
dotcraft setup --language English --provider-mode create \
  --provider-protocol anthropic --provider-id anthropic \
  --model claude-sonnet-4-5 --api-key <anthropic-api-key> \
  --profile developer
```

This is the safest first-time path. After setup, `.craft/` contains workspace config and bootstrap files. If you want a reusable source-tree workspace or a long-running workspace on a server, use `samples/workspace`:

```bash
cd samples/workspace
mkdir -p .craft
cp config.template.json .craft/config.json
bash start.sh
```

The template's most-edited fields:

| Field | Recommendation |
|---|---|
| `DashBoard.Host` / `DashBoard.Port` | Adjust to local bind address or port |
| `Tools.Sandbox.Enabled` | Only enable when actually running OpenSandbox |
| `Tools.Sandbox.Domain` | Point to your OpenSandbox; do not collide with the Dashboard port |
| `Tools.Sandbox.Image` | Replace with your sandbox container image |

### Bootstrap

`.template.md` files need to be copied into your workspace `.craft/` and renamed to `.md`:

```text
samples/bootstrap/senior-engineer/AGENTS.template.md
  → <workspace>/.craft/AGENTS.md
samples/bootstrap/senior-engineer/SOUL.template.md
  → <workspace>/.craft/SOUL.md
samples/bootstrap/senior-engineer/USER.template.md
  → <workspace>/.craft/USER.md
```

Mix-and-match across templates and adjust as needed.

### Hooks

Copy the platform directory under `samples/hooks/<platform>/` to your workspace:

```text
<workspace>/.craft/hooks.json
<workspace>/.craft/hooks/...
```

On Linux / macOS, make scripts executable:

```bash
chmod +x hooks/*.sh
```

> Creating or editing Hooks requires restarting DotCraft to take effect.

If you do not want to write hook config by hand, describe the need in chat and let the built-in `create-hooks` skill scaffold it.

### Skills

```text
.craft/skills/dev-guide/
.craft/skills/feature-workflow/
```

Keep the structure after copying and gradually replace placeholders with project-specific terminology, paths, and acceptance criteria.

## Troubleshooting

### Sample config does not take effect

Confirm the config is in the current workspace's `.craft/config.json`, then restart the relevant host. Startup-level fields do not hot-reload — see [Settings Lifecycle](../developing/settings-lifecycle.md).

### Cannot find sample source files

Confirm you are at the repository root. Source samples live under `samples/`; doc pages live under `docs/`.

### Not sure which sample to run first

Follow [Getting Started](../getting-started.md) for Desktop + model config, then pick a sample matching your goal.

## Related

- [Getting Started](../getting-started.md)
- [Plugins & Tools](../features/plugins-tools.md)
- [Configuration Reference](../developing/configuration.md)
