decompose

Files (3)

• SKILL md.bak
• SKILL.md
• split_test_suite.sh · scripts/

SKILL.md (first lines)

## Phase 0: Preflight

```bash
bd bootstrap
```

If bootstrap fails, run `bd doctor --agent` for diagnostics.

## Phase 1: Decompose

Break the plan into a beads task graph.

1. `bd create "Epic: <summary>" -p 0 --json`
2. `bd create "<title>" --description "<details + verify cmd>" --parent <epic-id> --metadata domain=frontend --metadata complexity=small --json`
   - Use `--design-file <path>` for tasks that reference design docs.
3. `bd dep add <child> <parent>` (if there are blocking dependencies)
4. Review task boundaries and decompose further if needed

### Task sizing

Estimate complexity using:
- Number of files and components involved.
- Cross-component dependencies and shared interfaces.
- Amount of independent design or architectural reasoning.
- Verification requirements and failure impact.
- Expected implementation size.

Use line counts as rough indicators, not hard boundaries.

- SMALL: Localized change, straightforward behavior, easy verification.
- MEDIUM: Several related files, bounded design decisions, clear acceptance
  criteria and verification.
- LARGE: Cross-component behavior, significant design decisions, multiple
  independently verifiable parts, or substantial uncertainty.

Split LARGE tasks when the resulting tasks have clear interfaces and can be
implemented or verified independently. Do not split tightly coupled changes
just to maximize parallelism.

If splitting a large task, create subtasks with:
```
bd create "<subtask>" --parent <large-task-id> --json
```

### Task Granularity

Create subtasks when:
- Clear interface boundaries exist (e.g., "define schema" ← → "implement parser")
- Multiple parts could genuinely be parallelized
- Different expertise/concerns needed (e.g., "backend" vs "frontend")
- Separate verification steps required
- >2 people could meaningfully work on different parts simultaneously

Keep together when:
- Tightly coupled (changes in one part require changes in another)
- Shared state/context (parsing + validating same structure)
- Sequential dependencies (B blocks on A's completion)
- Single unified verification point

Child tasks inherit labels from their parent automatically.

### Shared interfaces

If a task defines interfaces that other tasks consume (types, schemas, API contracts), make it a separate task and add it as a dependency for the consumers. Merge it to main before dispatching consumers — otherwise they build against nothing.

### Task Format

Each task description should include:
- Clear scope and acceptance criteria
- Any APIs/interfaces it depends on from other tasks
- A verification command (e.g., `pytest tests/module.py`, `npm run lint`, etc.)

Example:
```
Title: Implement user authentication

Description:
Implement JWT-based auth with:
- Login endpoint (POST /auth/login)
- Token validation middleware
- Refresh token rotation

Depends on: user schema task (for table structure)

Verification:
  pytest tests/auth/test_login.py -v
```

Show `bd list --parent <epic-id>`. Wait for user approval.

Epic close guards: `bd close <epic>` validates all children are closed before allowing the close.

## Phase 2: Dispatch and manage

**CRITICAL: ALL dispatch, merge, status, and cleanup operations MUST go through
`agent-dispatch`. NEVER run raw `git merge`, `wt merge`, `bd close`, or
`bd claim` directly.**

### Commands

| Command | What it does |
|---------|-------------|
| `agent-dispatch dispatch <task-id> --prepare` | Claim task, create worktree, output JSON with `worktree_path` and `prompt`. |
| `agent-dispatch status <epic-id>` | Print tasks, ready queue, active worktrees, and current policies. |
| `agent-dispatch merge <task-id>` | Merge task branch to main and mark the task done via `bd done`. Lock file conflicts are resolved automatically; non-lock-file conflicts are reported for manual resolution. |
| `agent-dispatch cleanup <epic-id>` | Remove all task- worktrees, reset in-progress tasks to open. |
| `agent-dispatch config` | Show current policies. |
| `agent-dispatch help` | Print usage and policy reference. |

### Dispatching agents

For each ready task, dispatch in two steps:

1. **Prepare** — creates the wt-managed worktree and claims the task:
   ```bash
   agent-dispatch dispatch <task-id> --prepare
   ```
   This outputs JSON: `{ task_id, branch, worktree_path, session, prompt_file, launch_cmd, prompt }`

From Igosuki/agentic-sdlc, MIT.

More from Igosuki/agentic-sdlc