Gezhi Template Author

gezhi Template Author

Use this skill when maintaining reusable gezhi setup material rather than configuring one user's project. The audience is future agents and advanced users who need a reliable recipe for a project family.

Do not use this skill to connect an ordinary target project to gezhi. For that job, use gezhi-project-setup. This skill only maintains the reusable material that llms.txt and gezhi-project-setup point agents toward.

Template work includes:

• new example gezhi.toml files;
• project-type setup docs;
• deterministic tik oracle scripts;
• producer wrapper templates;
• reusable prompts;
• updates to llms.txt, docs/skills.md, README links, or skill content.

Design Principles

• The artifact is the control point. Each template must name one canonical artifact shape.
• Producer first. A template is incomplete unless it explains how the artifact is rebuilt from source.
• Tik and tok stay separated. Tik reviews the artifact; tok success is measured by runtime-audited source changes.
• Defaults should be safe for non-experts: narrow write scopes, protected generated dirs, dry-run validation before real heartbeats.
• One-prompt setup material must be usable by an agent that has never seen the target project and by a user who cannot debug gezhi.toml by hand.
• Templates must include install/verification steps and a failure path for missing commands, failed producers, missing artifacts, and failed doctor checks.
• Deterministic checks beat model review when they can reject failures clearly.
• Examples should be runnable from a clean checkout or should state exactly which target project files they expect.

Template Workflow

1. Define the Project Family

Write down:

• artifact kind: PDF, site, workbook, report, benchmark, package, model metric;
• expected source directories;
• generated directories;
• likely build tools;
• whether a deterministic tik oracle is possible;
• what the user can inspect directly.

Do not create a generic "agent task" template. Every template must be tied to an artifact family.

2. Specify Producer Discovery

Each template must tell agents how to find or create the producer:

• check Makefile, justfile, package.json, pyproject.toml, README, CI workflows, and scripts/;
• prefer an existing stable command;
• otherwise create a wrapper such as scripts/goal_producer.sh;
• require the wrapper to verify artifact existence, size, and optionally sha256.

Include one minimal producer wrapper when useful.

3. Specify Tik

For oracle templates, provide or describe a script that returns a parseable gezhi verdict. The script should check the artifact and print a JSON object with:

{
  "artifact_ready": false
}

For checklist templates, use the same command-backed contract as oracle, but reserve the provider name for checklist-style reviews that should show up as checklist in tik ledgers and state.

For codex_file and claude_code_file templates, write a concise artifact-only prompt. If a slash skill is required, it must be the first line of the prompt.

For api templates, state the OpenAI package plus Packy/OpenAI-compatible API key requirements. The default model is claude-fable-5 through PackyAPI, and credentials may come from PACKYAPI_API_KEY, PACKYCODE_CODEX_KEY, OPENAI_API_KEY, or ~/.config/gezhi/api.env. Keep store = false unless the template explicitly requires stored API responses. If a local skill is required, set tik.skill instead of putting a slash command in the prompt.

4. Specify Tok Boundaries

Every template must include:

• recommended audited source write_dirs;
• generated dirs to protect;
• source dirs that look tempting but should stay read-only;
• a tok prompt template that references {tik_review_path} as the standard to meet;
• explicit language requiring tok to make source changes so the next rebuilt artifact answers tik's blocking objections;
• a note that tok cannot declare the artifact complete.

5. Provide Validation Commands

Every template must include:

gezhi validate
gezhi doctor
gezhi run --dry-run

Add smoke checks when relevant:

gezhi doctor --smoke-codex-goal
gezhi doctor --smoke-codex-app-server
gezhi doctor --smoke-codex-goal --smoke-codex-file-tik
gezhi doctor --smoke-codex-app-server --smoke-codex-file-tik

If a template includes a tik oracle script, include a direct oracle command and the expected verdict shape. If it includes a checklist runner, use provider = "checklist" and document that gezhi doctor checks the command statically.

If a template recommends unattended progress, include the system-level heartbeat command and state that each tick still runs exactly one heartbeat. Omit --every-minutes unless the template needs a fixed timer; gezhi defaults to a 5-minute wake-up for perpetual goals and a 30-minute wake-up for legacy goals:

gezhi heartbeat install --max-minutes 600
gezhi heartbeat status

File Locations

Use these repository locations unless a future repository convention replaces them:

skills/gezhi-project-setup/SKILL.md
skills/gezhi-template-author/SKILL.md
docs/skills.md
examples/<project-family>/gezhi.toml
examples/<project-family>/README.md
scripts/ (only for repository-level tooling)
llms.txt

Project-specific producer wrappers should be described in templates, not added to this repository unless they are examples.

Example Template Shape

name = "research-pdf-ready"
state_dir = ".gezhi"
runs_dir = ".gezhi/runs"

[artifact]
path = "output/full_paper.pdf"
copy_as = "full_paper.pdf"

[producer]
command = "scripts/goal_producer.sh"

[tik]
provider = "codex_file"
timeout_seconds = 1800
max_file_size_bytes = 25000000
max_output_tokens = 4096

[tik.verdict]
ready_field = "artifact_ready"
required_fields = ["artifact_ready"]

[tok]
provider = "codex_goal"
sandbox = "workspace-write"
write_dirs = ["writing", "src"]
codex_features = ["goals"]

# Use provider = "codex_app_server" for Codex app-server stdio instead of
# codex exec, or provider = "claude_code_goal" for Claude Code.

[safety]
generated_dirs = ["output", "build", "cache"]
max_blocker_repeats = 3

Review Checklist

Before finishing template work, verify:

• frontmatter name, description, and version are present for every skill;
• docs link to new skills from README or docs/skills.md;
• llms.txt lists the current agent entrypoints;
• one-prompt setup docs explain how to install or verify gezhi;
• non-expert setup docs include exact validation commands and recovery behavior when those commands fail;
• no template tells tok to edit generated outputs;
• no runtime prompt asks a human to approve or clarify during the loop;
• examples use current public config fields from docs/config-schema.md;
• validation commands are included;
• repository tests still pass or any failure is reported with exact output.

Definition of Done

• The reusable recipe can be followed by an agent that has never seen the project before.
• The recipe explains artifact choice, producer synthesis, tik choice, tok write scopes, validation, and first heartbeat.
• Documentation points users to the correct skill for their role.
• The change is committed with the docs and examples needed to use it.