| name | create-cycle |
| description | This skill should be used when the user asks to "create cycle", "create the task loop", "generate the task-loop instructions", "write the per-task playbook", "scaffold task-loop", or to turn a task-loop proposal into the per-project cycle a worker follows. It renders docs/task-loop/task-loop.md — this project's tailored step-by-step worker cycle, its general rules, and its parameters (the cycle-worker agent follows this file) — from auto-detected and interviewed specifics, and scaffolds docs/task-loop/directions.md and a .gitignore entry. |
| version | 0.2.1 |
Create Cycle
Overview
Second step of the task-loop workflow (specify-aims → create-cycle → run-cycle).
It generates docs/task-loop/task-loop.md — the per-project cycle a worker follows: the
step-by-step procedure (anchor → set up worktree → rubric → spec/plan → TDD → verify → reconcile →
doc-update → open PR with the study log → report), the general rules, and this project's parameters —
by rendering assets/task-loop-skeleton.md, then scaffolds directions.md. The cycle-worker agent
contract holds the same general rules + invariants; the worker reads and follows this file
strictly. Run it once the proposal (docs/task-loop/proposal.md) exists.
The cycle template (assets/task-loop-skeleton.md) is the single source of the procedure in the
plugin; this skill renders it per project. Because the rendered task-loop.md is a snapshot,
re-run create-cycle after upgrading the task-loop plugin so the cycle stays current.
When to use / not use
- Use to (re)generate
docs/task-loop/task-loop.md and scaffold a project, after specify-aims
has produced the proposal — and to refresh it after a plugin upgrade.
- Do not use to run tasks — that is
run-cycle (orchestrator) plus the cycle-worker agent.
This skill only authors the cycle and scaffolding.
Outputs
docs/task-loop/task-loop.md — the rendered per-project cycle + general rules + parameters
(from assets/task-loop-skeleton.md).docs/task-loop/directions.md — the human steering file (from assets/directions-template.md).docs/task-loop/logs/ — the record directory (with a .gitkeep). Each cycle writes one
git-tracked study-log record <NNN>_<task>.md (<NNN> = the task seq, zero-padded) with
Outcome, Rubric, Evidence, and Findings, committed in the worker's PR.- A
.gitignore entry for goal-rubric-*.md scratch.
(There is no local runtime state and no control issue — all task state lives in the Supabase
DB, reached only by the task-loop CLI from the orchestrator.)
Process
1. Read the proposal
Read docs/task-loop/proposal.md. The Specific Aims (Aim + Success criteria) define the goal; the
Implementation Plan's stages inform what tasks look like. If the proposal is missing, stop and direct
the user to specify-aims first.
2. Auto-detect what the repo tells you (don't ask)
- Test command (
pytest, npm test, cargo test, …).
- Default branch (
git symbolic-ref --short refs/remotes/origin/HEAD or the repo's main branch)
→ {{DEFAULT_BRANCH}}.
- Git hooks that constrain workflow — branch-name prefixes, attribution/word bans, protected
default branch, staging restrictions (check
.git/hooks/ and any core-hooks plugin) →
{{BRANCH_PREFIXES}} and the commit/PR steps.
- Whether a code skeleton exists yet or the repo is docs-only →
{{BOOTSTRAP_NOTE}}.
- The compute environment — HPC scheduler (
sinfo/squeue), GPUs (nvidia-smi), core count
(nproc) — to inform {{COMPUTE_POLICY}} (it does not by itself authorize cluster submission).
3. Interview for the project specifics (finalize fuzzy ones with Codex)
Ask only for what can't be detected, one topic at a time; pressure-test ambiguous answers with
dev-skills:discuss-with-codex:
- Source-of-truth docs the worker reads every task →
{{SOURCE_DOCS}}.
- Correctness contracts — invariants that are preconditions, not polish →
{{CONTRACTS}}.
- What "tested" means here beyond smoke tests (analytic limits, golden values, conservation
checks, integration gates) →
{{TEST_CONVENTIONS}}.
- A bootstrap note if the repo has no code yet →
{{BOOTSTRAP_NOTE}}.
- The compute policy →
{{COMPUTE_POLICY}}. Never leave it raw or invent it ad hoc. Default
(use unless the user states a constraint): "Use all available local compute — every CPU core
and available GPU; parallelize independent work; never run a parallelizable job single-threaded;
background long jobs and verify their terminal state. Do not submit to a cluster/SLURM scheduler
unless this policy names an allowed account/partition — then submit heavy jobs to compute nodes
(sbatch/srun), never the shared login node. Note: several cycle-workers may share this host, so
this aggressive default can oversubscribe; if you routinely run several at once, set a per-worker cap
(e.g. cores ÷ workers) here." Only pressure-test with discuss-with-codex for shared-cluster
quota/etiquette constraints.
- The project goal phrasing →
{{GOAL}} (from the Specific Aims).
4. Render the cycle file
Copy assets/task-loop-skeleton.md to docs/task-loop/task-loop.md and replace each {{PLACEHOLDER}}
in the Project parameters list with this project's value. For an absent fill — e.g. no bootstrap
needed when a code skeleton exists — write n/a or remove that bullet; never leave a raw {{...}}.
Leave the cycle steps, the general rules, and the worktree bash verbatim — they are the fixed
procedure; only the parameters are project-specific, and the steps reference them by name. Do not
edit, reorder, or weaken the steps when rendering — copying the template faithfully is what keeps the
cycle correct.
5. Scaffold the rest
- Copy
assets/directions-template.md to docs/task-loop/directions.md.
- Create
docs/task-loop/logs/.gitkeep.
- Add a
.gitignore entry for goal-rubric-*.md scratch. The loop keeps no local runtime files.
6. Commit on a branch + PR
Commit the scaffolding with clean, attribution-free text via a branch + PR (git commit -F,
gh pr create --body-file). These are durable project files.
Key principles
- Cycle + general rules + parameters here; the same rules also in the agent. This skill renders
the per-project cycle and fills the
{{...}} parameters. The general discipline (TDD,
evidence-before-done, codex deliberation, worker-never-merges) and the non-negotiable invariants are
repeated in both the rendered task-loop.md and the cycle-worker agent contract on
purpose — they are load-bearing, and the worker turns task-loop.md's steps + rules into its todo
list.
- Detect before asking. Pull the test command, default branch, and git-hook constraints from the
repo; reserve questions for genuinely project-specific intent.
- Render faithfully, don't author. Fill placeholders only; never edit the cycle steps. Re-running
create-cycle after a plugin upgrade is how a project's cycle stays current (the rendered file is a
snapshot).
Additional resources
assets/task-loop-skeleton.md — the per-project cycle + general rules + parameters template.assets/directions-template.md — the steering-file scaffold.${CLAUDE_PLUGIN_ROOT}/references/pr-findings.md — the PR study-log contract the cycle's
step 8 writes and the orchestrator reads.
