Help
Get help with HALOS—validation, proposals, contributing, and the spec
Get help via chat or explore the guides below.
Get help in chat
Ask the HALOS agent. Example prompts:
| You want to… | Try |
|---|---|
| Get started | “help” |
| Validate the spec | “How do I validate?” |
| Build and serve locally | “How do I build and serve the site?” |
| Draft a proposal | “Help me draft a proposal” |
| Fix a typo or improve docs | “How do I contribute a small edit?” |
| Understand a principle | “What is HALOS-CORE-1?” or “Explain HALOS-CORE-4” |
| Adopt HALOS | “How do I adopt HALOS in my project?” |
| Explore what HALOS means for you | explore.html — build a seeded prompt and open in Claude, ChatGPT, etc. |
| Publish after acceptance | “What’s the publishing checklist?” |
| Review a proposal | “What should I check when reviewing?” |
FAQ
How do I validate the spec?
Run validation with Docker (no local Node/Ruby needed):
docker run --rm -v "$(pwd):/workspace" halos validate
Or run the steps locally: validate JSON schema, run node scripts/generate-spec.js, verify spec/spec.md and spec/CHANGELOG.md. See docker/README.md for options.
How do I run integration tests?
./scripts/integration-test.sh
Starts the server in Docker, tests all paths (pages, spec, skills, assets), then stops. Run before deploying.
How do I build and serve the site locally?
Option 1 — Script (requires Jekyll locally):
./scripts/serve.sh
Option 2 — Docker (one-time build):
docker run --rm -v "$(pwd):/workspace" -p 3000:3000 halos serve
Option 3 — Docker with live reload (best for interactive editing):
./scripts/serve-watch.sh
On your computer, visit http://localhost:3000.
Before checking on your phone, you can generate local desktop and mobile previews with Playwright:
./scripts/preview-local.sh /2026/04/11/your-post-slug.html
That writes screenshots to /tmp/halos-preview/ so you can review the page in desktop and mobile sizes first.
To check the site on your phone while on the same LAN, use:
http://<your-mac-lan-ip>:3000
The local ./scripts/serve.sh output now prints the phone-check URLs it detects so you can copy one directly.
If you want an interactive browser window before checking your phone, ./scripts/preview-local.sh also prints matching npx playwright open ... commands for desktop and mobile.
With live reload, edits to docs or spec trigger an automatic rebuild and browser refresh.
How do I propose a change?
- Copy proposals/TEMPLATE.md
- Create
proposals/NNNN-short-title.md - Fill each section; ensure alignment with principles
- Open a pull request
Full process: proposals/README and Governance.
How do I make a small doc fix?
Typos and clarity fixes go directly to a PR. See CONTRIBUTING. Substantive changes use the proposal process.
What is the publishing checklist?
After a proposal is accepted: update manifest version, append changelog, run node scripts/generate-spec.js, push PR, merge, tag release. Full checklist: spec/PUBLISHING.md.
What should I check when reviewing a proposal?
- Alignment with principles
- Scope: focused and actionable
- Completeness: all TEMPLATE sections filled
- For spec changes: schema validation will run in CI
Agent skills
The HALOS agent has skills for specific tasks:
| Skill | When to use |
|---|---|
| halos-help | General questions, routing |
| proposal-assist | Drafting or structuring proposals |
| validation-and-build | Validation, build, Docker issues |
| spec-explainer | Principles, adoption, core requirements |
| agent-convention-sync | Updating discovery files (FOR_AGENTS.md, etc.) |
Learn HALOS in any AI
Paste the prompt in LEARN_HALOS.md into ChatGPT, Claude, Gemini, or any AI chat. The AI will have the full HALOS framework. Try: “Explain HALOS”, “How do I adopt HALOS?”, “Help me write a proposal that aligns with HALOS.”
Explore what HALOS means for you: Use the Explore tool to describe your role and concerns, then get a seeded prompt and a clickable link to open in Claude, ChatGPT, or any AI chatbot.