Skip to main content
The init subcommand creates the .agent/tasks/<TASK_ID>/ directory, writes all required artifact files from templates, installs Codex and Claude subagent files, and inserts or updates managed workflow blocks in AGENTS.md and the repo’s Claude guide file.
init is a serial prerequisite. Never overlap it with freeze, build, evidence, verify, fix, or subagent spawning. Wait for init to complete and confirm .agent/tasks/<TASK_ID>/spec.md exists before continuing.

​
Usage

python3 "$SKILL_PATH/scripts/task_loop.py" init --task-id <TASK_ID> [options]

​
Flags

​
--task-id
string
required
Task identifier. Allowed characters: letters, numbers, dot, underscore, and hyphen. Path separators and .. are rejected. Example: feature-auth-hardening.
​
--task-file
string
Optional path to a task description file. The file’s content is read and used to seed spec.md as the initial task statement.
​
--task-text
string
Optional inline task text to seed spec.md. Use this instead of --task-file when you want to supply the task statement directly on the command line.
​
--repo-root
string
Optional working directory inside the repo. Defaults to the current directory. The script walks up from this path to discover the git repository root.
​
--guides
string
default:"auto"
Which guide files to create or update. Accepted values: auto, agents, claude, both, none.
  • auto: Preserves existing guide files and ensures the product-native guide exists when its agent set is being installed. Creates both guides when neither exists.
  • agents: Write or update AGENTS.md only.
  • claude: Write or update the Claude guide (CLAUDE.md or .claude/CLAUDE.md) only.
  • both: Write or update both guide files unconditionally.
  • none: Skip all guide file updates.
​
--install-subagents
string
default:"both"
Which project-scoped subagent sets to install or refresh. Accepted values: both, codex, claude, none.
  • both: Install subagent files into both .codex/agents/ and .claude/agents/.
  • codex: Install into .codex/agents/ only.
  • claude: Install into .claude/agents/ only.
  • none: Skip subagent installation.
​
--force
boolean
Overwrite existing task artifact templates. Without this flag, existing files are left untouched. Guide files are always upserted regardless of --force.

​
What init creates

1

Task artifact directory

Creates .agent/tasks/<TASK_ID>/ and writes all required files from templates:
.agent/tasks/<TASK_ID>/
  spec.md
  evidence.md
  evidence.json
  verdict.json
  problems.md
  raw/
    build.txt
    test-unit.txt
    test-integration.txt
    lint.txt
    screenshot-1.png
evidence.json and verdict.json are created with valid placeholder content so validate can run immediately. raw/screenshot-1.png is created as a minimal placeholder PNG.
2

Subagent files

Installs project-scoped subagent templates (controlled by --install-subagents):
.codex/agents/
  task-spec-freezer.toml
  task-builder.toml
  task-verifier.toml
  task-fixer.toml

.claude/agents/
  task-spec-freezer.md
  task-builder.md
  task-verifier.md
  task-fixer.md
3

Guide file updates

Inserts or refreshes managed workflow blocks in (controlled by --guides):
  • AGENTS.md
  • CLAUDE.md or .claude/CLAUDE.md
Content outside the managed markers is preserved on re-run. If both CLAUDE.md and .claude/CLAUDE.md exist, the repo-root CLAUDE.md is updated and .claude/CLAUDE.md is left untouched.
In Claude Code, if init created or refreshed .claude/agents/ during a running session, start a new Claude Code session before expecting those agents to appear. Use /agents to inspect available agents.

​
JSON output

init prints a JSON object to stdout: 
{
  "repo_root": "/path/to/repo",
  "task_id": "feature-auth-hardening",
  "task_dir": "/path/to/repo/.agent/tasks/feature-auth-hardening",
  "created_or_overwritten_task_files": [
    "/path/to/repo/.agent/tasks/feature-auth-hardening/spec.md",
    "/path/to/repo/.agent/tasks/feature-auth-hardening/evidence.md",
    "/path/to/repo/.agent/tasks/feature-auth-hardening/evidence.json",
    "/path/to/repo/.agent/tasks/feature-auth-hardening/verdict.json",
    "/path/to/repo/.agent/tasks/feature-auth-hardening/problems.md",
    "/path/to/repo/.agent/tasks/feature-auth-hardening/raw/build.txt",
    "/path/to/repo/.agent/tasks/feature-auth-hardening/raw/test-unit.txt",
    "/path/to/repo/.agent/tasks/feature-auth-hardening/raw/test-integration.txt",
    "/path/to/repo/.agent/tasks/feature-auth-hardening/raw/lint.txt",
    "/path/to/repo/.agent/tasks/feature-auth-hardening/raw/screenshot-1.png"
  ],
  "installed_or_refreshed_subagent_files": [
    "/path/to/repo/.codex/agents/task-spec-freezer.toml",
    "/path/to/repo/.codex/agents/task-builder.toml",
    "/path/to/repo/.codex/agents/task-verifier.toml",
    "/path/to/repo/.codex/agents/task-fixer.toml",
    "/path/to/repo/.claude/agents/task-spec-freezer.md",
    "/path/to/repo/.claude/agents/task-builder.md",
    "/path/to/repo/.claude/agents/task-verifier.md",
    "/path/to/repo/.claude/agents/task-fixer.md"
  ],
  "guide_file_actions": {
    "/path/to/repo/AGENTS.md": "created",
    "/path/to/repo/CLAUDE.md": "created"
  }
}
guide_file_actions values are "created", "appended", or "updated" depending on whether the guide file was new, had no managed block yet, or already contained a managed block that was replaced. Files already present and not overwritten are omitted from created_or_overwritten_task_files.

​
Examples

Initialize from a task file: 
python3 "$SKILL_PATH/scripts/task_loop.py" init \
  --task-id feature-auth-hardening \
  --task-file docs/tasks/auth-hardening.md
Initialize from inline text: 
python3 "$SKILL_PATH/scripts/task_loop.py" init \
  --task-id feature-auth-hardening \
  --task-text "Implement auth hardening for session refresh and logout."
Install only Claude subagents and update only the Claude guide file: 
python3 "$SKILL_PATH/scripts/task_loop.py" init \
  --task-id feature-auth-hardening \
  --install-subagents claude \
  --guides claude
Force overwrite of existing task artifact templates: 
python3 "$SKILL_PATH/scripts/task_loop.py" init \
  --task-id feature-auth-hardening \
  --force
Skip subagent installation and guide updates entirely: 
python3 "$SKILL_PATH/scripts/task_loop.py" init \
  --task-id feature-auth-hardening \
  --install-subagents none \
  --guides none

Build docs developers (and LLMs) love

Get started for freeTalk to us