init

name	init
description	Initialize a new task module in AiTasks/ directory with system files, git branch, and optional worktree. Use when starting a new feature, bug fix, or refactoring task that needs structured lifecycle tracking.
arguments	[{"name":"module_name","description":"Name of the task module directory to create (e.g., auth-refactor, add-search)","required":true},{"name":"title","description":"Human-readable title for the task (defaults to module_name)","required":false},{"name":"tags","description":"Comma-separated tags (e.g., feature,backend,urgent)","required":false},{"name":"worktree","description":"Create isolated git worktree for parallel execution (flag, no value)","required":false}]

/moonview:init — Initialize Task Module

Create a new task module under the project's AiTasks/ directory with the standard system file structure.

Usage

/moonview:init <module_name> [--title "Task Title"] [--tags feature,backend] [--worktree]

Directory Structure Created

AiTasks/
└── <module_name>/
    ├── .index.json       # Task metadata (JSON) — machine-readable
    └── .target.md      # Task target / requirements — human-authored

.index.json JSON Schema

The .index.json file uses JSON as the single source of truth for task state:

{
  "title": "Human-readable task title",
  "type": "",
  "status": "draft",
  "phase": "",
  "completed_steps": 0,
  "created": "2024-01-01T00:00:00Z",
  "updated": "2024-01-01T00:00:00Z",
  "depends_on": [],
  "tags": [],
  "branch": "task/module-name",
  "worktree": ".worktrees/task-module-name"
}

Status Values

Status	Description
draft	Initial state, task target being defined
planning	Implementation plan being researched
review	Plan complete, awaiting feasibility evaluation
executing	Implementation in progress
re-planning	Execution hit issues, plan being revised
complete	Task finished and verified
blocked	Blocked by dependency or unresolved issue
cancelled	Task abandoned

depends_on Format

Dependencies reference other task modules. Two formats — simple string (requires complete) and extended object (custom minimum status):

"depends_on": [
  "auth-refactor",
  { "module": "api-design", "min_status": "review" }
]

System Files (dot-prefixed)

File	Purpose	Created by
.index.json	Task metadata, state machine	init (always)
.target.md	Task requirements / objectives	init (always)
.analysis/	Evaluation history (one file per assessment)	check (on demand)
.test/	Test criteria & results (one file per phase)	plan/exec/check (on demand)
.bugfix/	Issue history (one file per mid-exec issue)	check (on demand)
.notes/	Research notes & experience log (one file per entry)	plan/exec (on demand)
.summary.md	Condensed context summary	plan/check/exec (on demand)
.report.md	Completion report	report (on demand)
.tmp-annotations.json	Transient annotation transport	Frontend (ephemeral)
.plan-superseded.md	Archived plan on re-plan (renamed from .plan.md)	plan (on re-plan)

.plan.md is the implementation plan, generated by plan and editable through the Plan annotation panel.

Root AiTasks/.index.json Format

The root AiTasks/.index.json is a JSON array of module entries, auto-managed by init:

[
  { "module": "auth-refactor", "title": "User auth refactoring" },
  { "module": "add-search-v2", "title": "Add search functionality v2" }
]

Each entry: { "module": "<module_name>", "title": "<title>" }.

Created automatically by init if AiTasks/ directory does not exist (initialized as []). init appends one entry per new module. No other sub-command modifies this file.

Execution Steps

1. Validate module_name: ASCII letters, digits, hyphens, underscores ([a-zA-Z0-9_-]+), no whitespace, no leading dot, no path separators
2. Check AiTasks/ directory exists; create with root .index.json if missing (initialized as []). Also create AiTasks/.type-registry.md with seed types if missing (read references/seed-types/.summary.md for the predefined type index; see plan/references/type-profiling.md for registry format). First-time setup: if AiTasks/ was just created, append gitignore entries to project .gitignore (create if missing): .worktrees/, AiTasks/**/.tmp-annotations.json, AiTasks/**/.auto-signal, AiTasks/**/.auto-signal.tmp, AiTasks/**/.auto-stop, AiTasks/**/.lock, AiTasks/.experiences/.lock, AiTasks/.references/.lock, AiTasks/.type-profiles/.lock
3. Check AiTasks/<module_name>/ does not already exist; abort with error if it does
4. Check branch collision: verify task/<module_name> branch does not already exist (git branch --list task/<module_name>). If exists, abort with error suggesting --cleanup the old task or choose a different name
5. Check working tree clean: verify no uncommitted changes to tracked files (git status --porcelain then filter out ?? untracked entries). Untracked and gitignored files (e.g., stale .auto-signal, AiTasks/ ephemeral files) do NOT block init. If tracked files have modifications, abort with error — branch should be created from a clean state to avoid mixing unrelated changes. User should commit or stash first
6. Git: create branch task/<module_name> from current HEAD
7. If --worktree: git worktree add .worktrees/task-<module_name> task/<module_name>
8. If not worktree: git checkout task/<module_name>
9. Create AiTasks/<module_name>/ directory (in worktree if applicable)
10. Create AiTasks/<module_name>/.index.json with JSON:

• title: from --title argument or module_name
• status: draft
• phase: "" (empty)
• completed_steps: 0
• created: current ISO timestamp
• updated: current ISO timestamp
• depends_on: []
• tags: parsed from --tags argument or []
• branch: task/<module_name>
• worktree: .worktrees/task-<module_name> (or empty if no worktree)

11. Create AiTasks/<module_name>/.target.md with default template (type is auto-discovered by research during planning):

    # Task Target: <title>
    
    ## Objective
    
    <!-- Describe the goal of this task -->
    
    ## Requirements
    
    <!-- List specific requirements -->
    
    ## Constraints
    
    <!-- Any constraints or limitations -->
    

12. Update AiTasks/.index.json: append { "module": "<module_name>", "title": "<title>" } entry to the array (if not already listed)
13. Git commit: -- ai-cli-task(<module_name>):init initialize task module
14. Report: path, files created, branch name, worktree path (if any), next step hint

Git

• Creates branch: task/<module_name> from current HEAD
• Without worktree: git checkout task/<module_name> before creating files
• Optional worktree: .worktrees/task-<module_name>
• Commit: -- ai-cli-task(<module_name>):init initialize task module

Notes

• Module names are ASCII only: letters, digits, hyphens, underscores ([a-zA-Z0-9_-]+). No whitespace, no leading dot, no path separators. Examples: auth-refactor, add-search-v2
• The .target.md is for human authoring — users fill in requirements via the Plan annotation panel. The default template (Objective / Requirements / Constraints) is domain-generic; users may freely restructure it for their domain (e.g., Synopsis / Characters for literary tasks). The plan skill reads .target.md content, not its structure
• System files (dot-prefixed) should not be manually edited except .target.md
• After init, the typical workflow is: edit .target.md → /moonview:plan → /moonview:check → /moonview:exec
• With --worktree, the task runs in an isolated directory; multiple tasks can execute simultaneously
• Branch collision check: if task/<module_name> branch already exists (from a previous cancelled/completed task), init aborts. User should delete the old branch first (git branch -d task/<name>) or choose a different module name
• Clean working tree: init requires no uncommitted changes to tracked files — untracked/gitignored files are allowed. User should git commit or git stash tracked changes first