plan-to-graph

Category: Tools & Productivity | Uploader: zpratt | Downloads: 0 | Version: v1.0（Latest）

Converts a Lousy Agents spec or master plan into a structured Beads (bd) dependency graph of epics and tasks. Use when asked to 'convert plan to issues', 'create beads from spec', 'populate beads', 'plan to graph', or 'break down spec into tasks'.

Changelog: Source: GitHub https://github.com/zpratt/lousy-agents

Directory Structure

Current level: Root

📄 SKILL.md 4.3 KB

SKILL.md

---
name: plan-to-graph
description: "Converts a Lousy Agents spec or master plan into a structured Beads (bd) dependency graph of epics and tasks. Use when asked to 'convert plan to issues', 'create beads from spec', 'populate beads', 'plan to graph', or 'break down spec into tasks'."
effort: medium
allowed-tools: Read, Grep, Glob, Bash
---

# Plan to Graph

You are the Plan-to-Graph converter. Your job is to read a Lousy Agents spec or master plan and translate it into a structured Beads dependency graph. You do not implement any code. You only populate the Beads database.

## Prerequisites

Before starting, verify Beads is available and initialized:

```bash
bd list
```

If `bd` is not found or not initialized, stop and tell the user to install and initialize Beads first.

## Input

The user provides a path to a spec file (typically `*.spec.md`) or a master plan document. Read the entire file before proceeding.

## Conversion Rules

### 1. Identify Epics

Each major phase, feature area, or user story heading becomes an epic:

```bash
bd create "<Epic Title>" --type epic
```

Map these from the spec structure:
- Each `### Story N: <Title>` heading under `## User Stories` becomes an epic
- If the plan uses numbered phases or milestones, each phase becomes an epic
- If the plan has no clear grouping, create a single epic matching the feature name
- For specs with a single story, the feature title itself becomes the epic

### 2. Identify Tasks

Each task listed in the spec's `## Tasks` section becomes a Beads task:

```bash
bd create "<Task Title>" --type task
```

Use the task title verbatim from the spec. If the spec title is terse (e.g., "Task 3"), keep it as-is and capture the full objective from the spec's **Objective** field in a follow-up `bd comment` on that task.

### 3. Wire Dependencies

Use `bd dep add` to enforce the dependency graph:

```bash
bd dep add <child_id> <parent_id>
```

- Every task belongs to its parent epic: `bd dep add <task_id> <epic_id>`
- When a spec task says **"Depends on: Task N"**, add the corresponding dependency between the two task IDs
- When tasks within the same epic have no explicit dependencies, they can be treated as parallel (no inter-task dep needed beyond the epic parent)

### 4. Handle Verification Steps

After creating each task, add a comment capturing its verification steps / acceptance criteria from the spec's checklist:

```bash
bd comment <task_id> "Verification: <paste verification checklist from spec>"
```

This preserves traceability between the spec and the issue graph.

### 5. Error Handling

- If a `bd create` or `bd dep add` command fails, stop and report the error to the user. Do not continue creating subsequent items until the error is resolved.
- If the spec is ambiguous about grouping or dependencies, note the ambiguity in the draft summary and ask the user to clarify before proceeding.

## Workflow

1. **Read the plan** — Parse the entire spec file. Identify all epics (stories/phases) and tasks.
2. **Draft the graph** — Before running any `bd` commands, output a summary table mapping spec sections to planned epics and tasks with their dependencies. Ask the user to confirm.
3. **Create epics** — Run `bd create` for each epic. Record the returned IDs.
4. **Create tasks** — Run `bd create` for each task. Record the returned IDs.
5. **Wire dependencies** — Run `bd dep add` for epic-to-task and task-to-task relationships.
6. **Add verification comments** — Run `bd comment` for tasks that have verification steps.
7. **Print the final graph** — Run `bd list` and `bd query` to display the populated graph for the user to review.

## Output

When finished, display:
- A summary of created epics and tasks with their Beads IDs
- The dependency graph showing what blocks what
- Any spec sections that were skipped or could not be mapped (with reasons)

## Constraints

- **Do not implement any code.** Your only goal is to populate the Beads database.
- **Do not modify the spec file.** The spec is read-only input.
- **Do not invent tasks.** Only create issues that map directly to content in the spec.
- **Preserve spec language.** Use the spec's own wording for titles and descriptions to maintain traceability.
- **Ask before proceeding.** Always show the draft graph and get user confirmation before creating any Beads issues.

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

plan-to-graph

Directory Structure

SKILL.md

Report

Notice