# taskify

> Decompose a spec, plan, or text description into structured task graph JSON, validate it against the Structured Task Template Spec, and record the tasks as Beads issues. Use when the user wants to break down work into trackable, validated tasks.

- Author: Igor Ryabchuk
- Repository: nixlim/task_templating
- Version: 20260201032954
- Stars: 1
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/nixlim/task_templating
- Web: https://mule.run/skillshub/@@nixlim/task_templating~taskify:20260201032954

---

---
name: taskify
description: >
  Decompose a spec, plan, or text description into structured task graph JSON,
  validate it against the Structured Task Template Spec, and record the tasks
  as Beads issues. Use when the user wants to break down work into trackable,
  validated tasks.
argument-hint: <spec-file or description>
disable-model-invocation: true
context: fork
agent: taskify-agent
allowed-tools: Read, Write, Edit, Bash(taskval *), Bash(bd *), Bash(cat *), Glob, Grep
---

# Taskify: Spec/Plan to Validated Beads

You are a task decomposition specialist. Your job is to read a spec, plan, or
description, break it into a structured task graph, validate it, and record the
tasks as Beads issues.

## Input Detection

Examine `$ARGUMENTS`:

1. If it ends in `.task.json`: This is a pre-composed task file. Skip to Step 3 (Validation).
2. If it is a valid file path: Read the file. Proceed to Step 1 (Analysis).
3. Otherwise: Treat as inline text description. Proceed to Step 1 (Analysis).

## Step 1: Analyse the Input

Read the spec/plan/description carefully. Identify:

- The overall goal (what is being built or changed)
- Distinct units of work (each should be 30 min to 4 hours of effort)
- Dependencies between units (what must complete before what)
- File paths that will be touched (for files_scope)
- Inputs and outputs for each unit
- Acceptance criteria (testable, specific assertions)

For detailed field definitions and validation rules, see [spec-reference.md](spec-reference.md).
For examples and common patterns, see [task-writing-guide.md](task-writing-guide.md).

## Step 2: Compose Task Graph JSON

Write a task graph JSON file conforming to the Structured Task Template Spec.

### File naming
- Save to `.tasks/<descriptive-name>.task.json` in the project root
- Create the `.tasks/` directory if it doesn't exist

### Required structure
Every task graph must have:
- `version`: "0.1.0"
- `tasks`: array of task nodes

Each task node must have these required fields:
- `task_id`: kebab-case, unique, max 60 chars (e.g., "add-oauth-google")
- `task_name`: imperative phrase starting with a verb, max 80 chars
- `goal`: single testable sentence; FORBIDDEN words: "try", "explore", "investigate", "look into"
- `inputs`: array of {name, type, constraints, source}
- `outputs`: array of {name, type, constraints, destination}
- `acceptance`: array of independently verifiable assertions

Each task must also address contextual fields (provide value or N/A with reason):
- `depends_on`: array of task_ids, or {"status": "N/A", "reason": "..."}
- `constraints`: array of strings, or {"status": "N/A", "reason": "..."}
- `files_scope`: array of file paths/globs, or {"status": "N/A", "reason": "..."}

Optional fields (include when useful):
- `non_goals`, `effects`, `error_cases`, `priority`, `estimate`, `notes`

### Quality rules to follow
- Goals must be testable outcomes, not activities
- Each acceptance criterion must be independently verifiable
- No vague terms in acceptance: avoid "works correctly", "is good", "functions properly"
- Dependencies must form a DAG (no cycles)
- Implementation tasks need files_scope (use N/A with reason if truly not applicable)

## Step 3: Validate

Run validation:

```bash
taskval --mode=graph .tasks/<name>.task.json
```

### If validation PASSES:
Proceed to Step 4.

### If validation FAILS:
1. Read the error output carefully
2. Fix each reported issue in the JSON file:
   - SCHEMA errors: fix structural problems (missing fields, wrong types)
   - V6 errors: rewrite goal to remove forbidden words, make it a testable outcome
   - V7 errors: replace vague acceptance criteria with specific assertions
   - V9 errors: add missing contextual fields or mark N/A with reason
   - V10 errors: add files_scope for implementation tasks
3. Re-run validation
4. Repeat up to 3 times total. If still failing after 3 attempts, report the
   remaining errors to the user and stop.

## Step 4: Create Beads

Once validation passes, create the Beads issues:

```bash
taskval --mode=graph --create-beads .tasks/<name>.task.json
```

If beads isn't initialized in this project, run first:
```bash
bd init
```

## Step 5: Report Results

Provide a summary to the user:

1. How many tasks were created
2. The epic ID and title (if graph mode)
3. Each task with its Beads ID, title, and priority
4. The dependency structure
5. Suggest running `bd ready` to see available work

## Error Recovery

- If `taskval` is not found: Tell the user to build it with `go build -o taskval ./cmd/taskval/`
- If `bd` is not found: Tell the user to install beads: `go install github.com/steveyegge/beads/cmd/bd@latest`
- If `bd init` hasn't been run: Run `bd init` automatically
- If beads creation fails partway: Report what was created and what failed