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

1. 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.

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

| Tool | File Generated | Location |

|---|---|---|

| Claude Code | CLAUDE.md | Project root |

| Codex | AGENTS.md; optional .codex/agents/*.toml | Project root |

| Cline | .clinerules | Project root |

| Cursor | .cursor/rules/hotl.md | Project root |

| GitHub Copilot | .github/copilot-instructions.md | Project root |

1. 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

1. If Codex was selected, ask whether to install HOTL Codex custom agent templates. Default: yes. These templates make the bundled reviewer, architect, researcher, QA, dev, and PM roles available to the target project as Codex project-scoped custom agents.

Resolve hotl-install-codex-agents.sh using the same six-location install-path order as the initiative scaffolder below:

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

Invoke the installer from the project root:

   bash <resolved-hotl-install-codex-agents.sh>

The installer creates .codex/agents/ and copies the tracked HOTL templates from adapters/codex-agents/ into it. Existing agent files are preserved by default and emitted as SKIP: lines. Only use --force when the user explicitly approves overwriting existing project agent files.

1. 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 <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.

1. Commit all generated files:

git add AGENTS.md .clinerules .cursor/ .github/ CLAUDE.md
# If Codex custom agents were installed, also add:
#   .codex/agents/
# If initiative support was scaffolded in step 6, also add:
#   .hotl/config.yml docs/
git commit -m "chore: add HOTL adapter files for [tool list]"

AGENTS.md Template Content

# 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.