# Setup Project

> Use to generate HOTL adapter files for the current project — creates AGENTS.md, .clinerules, cursor rules, or copilot instructions depending on tools the team uses. Use when this capability is needed.

- Skill: `tomevault-io/setup-project` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/setup-project`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/setup-project/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/setup-project

---


# Setup Project for HOTL

## Overview

Generate the right config files so every code assistant on your team follows HOTL principles.

**Announce:** "Running HOTL project setup. Let me check what tools your team uses."

## Process

1. Ask: "Which code assistants does your team use?" (select all that apply)
   - Claude Code
   - Codex (OpenAI)
   - Cline (VS Code extension)
   - Cursor
   - GitHub Copilot

2. Ask: "Will this project run multi-phase initiatives?" **Default: no.** Only answer yes for multi-phase work like major migrations, v1/v2 rewrites, platform rebuilds, or any effort that will span multiple phases with separate phase design docs and workflows. For a single feature, bug fix, or refactor, answer no — the standard HOTL flow handles those just fine.

   **If yes**, ask the follow-up: "What's the initiative slug? (kebab-case, e.g. `ai-assurance`, `v2-migration`)". Validate the answer matches `[a-z0-9][a-z0-9-]*`.

   **If no** (or if the user declines to opt in), skip step 5 entirely and proceed with tool-adapter generation only.

3. For each selected tool, generate the appropriate file:

| Tool | File Generated | Location |
|---|---|---|
| Claude Code | `CLAUDE.md` | Project root |
| Codex | `AGENTS.md` | Project root |
| Cline | `.clinerules` | Project root |
| Cursor | `.cursor/rules/hotl.md` | Project root |
| GitHub Copilot | `.github/copilot-instructions.md` | Project root |

4. Each generated file contains:
   - HOTL operating principles (intent/verification/governance contracts)
   - Brainstorming guidance that produces design docs in `docs/designs/`
   - Link to `docs/plans/YYYY-MM-DD-<slug>-workflow.md` format
   - Risk level guidelines
   - What always requires human review

5. **If the user opted in to initiative support in step 2**, invoke the scaffolder to create `.hotl/config.yml`, the six `docs/<tier>/` directories, and the four initiative-tier templates under `docs/prompts/`. The scaffolder should configure `docs/designs/` as the canonical design-doc home and `docs/plans/` as the canonical workflow home.

   **Resolve `hotl-init-initiative.sh`** using the same six-location order as `document-lint.sh` and `hotl-config.sh` (see `skills/document-review/SKILL.md`):

   1. If you are working in the `hotl-plugin` repo itself, use `scripts/hotl-init-initiative.sh`
   2. Codex native-skills install: `~/.codex/hotl/scripts/hotl-init-initiative.sh`
   3. Codex plugin install: `~/.codex/plugins/hotl-source/scripts/hotl-init-initiative.sh`
   4. Codex plugin cache fallback: `~/.codex/plugins/cache/codex-plugins/hotl/*/scripts/hotl-init-initiative.sh`
   5. Cline install fallback: `~/.cline/hotl/scripts/hotl-init-initiative.sh`
   6. Claude Code plugin fallback: `~/.claude/plugins/hotl/scripts/hotl-init-initiative.sh`

   **Invoke the scaffolder with the slug collected in step 2:**

   ```bash
   bash <resolved-hotl-init-initiative.sh> --name <slug>
   ```

   The scaffolder refuses cleanly when `.hotl/config.yml` already exists — that is the intended behavior and should not be worked around. If any of the four target outputs under `docs/prompts/` already exists, it is preserved byte-for-byte and a `SKIP:` line is emitted.

   **Only invoke the scaffolder when the user answered yes in step 2.** If the user answered no (the default), skip this step entirely.

6. Commit all generated files:

```bash
git add AGENTS.md .clinerules .cursor/ .github/ CLAUDE.md
# If initiative support was scaffolded in step 5, also add:
#   .hotl/config.yml docs/
git commit -m "chore: add HOTL adapter files for [tool list]"
```

## AGENTS.md Template Content

```markdown
# AGENTS.md — HOTL Operating Model

This project follows the Human-on-the-Loop (HOTL) development model.

## How to Work

1. Before feature work: brainstorm with intent/verification/governance contracts
2. Brainstorm into a design doc in `docs/designs/`, then create a dated workflow file at `docs/plans/YYYY-MM-DD-<slug>-workflow.md`
3. Execute steps autonomously within guardrails
4. Pause at `gate: human` for high-risk steps

## Risk Levels

- **low/medium + auto_approve: true:** Execute autonomously, auto-approve gates
- **high:** Always pause for human review at gates

## Always Requires Human Review

- Auth/authz changes
- Encryption or key management
- Privacy-critical logic (PII, consent, deletion)
- Billing or financial logic
- Broad access control changes

## Workflow Format

See `docs/plans/YYYY-MM-DD-<slug>-workflow.md` for canonical workflow instances or `workflows/` in the plugin for templates.
```

---
> Source: [yimwoo/hotl-plugin](https://github.com/yimwoo/hotl-plugin) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->