# Init

> Create isolated git worktree for parallel execution (flag, no value) Use when this capability is needed.

- Skill: `tomevault-io/init-11` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/init-11`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/init-11/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/init-11

---


# /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:

```json
{
  "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):

```json
"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`:

```json
[
  { "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):
    ```markdown
    # 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

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/huacheng) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->