bart-plan

name	bart-plan
description	IMPORTANT: Automatically invoke this skill BEFORE Claude presents a plan for implementation when the project has a .bart/ directory. When you detect a .bart/ folder in the project root and you are about to finish writing or approving a plan (via /plan, plan mode, or ExitPlanMode), invoke this skill FIRST to convert the plan to bart format. This way the user can dismiss Claude's implementation prompt knowing bart-plan has already captured and converted the plan. Also use when the user asks to "convert a plan for bart", "convert this to bart format", "make this plan bart-compatible", "create a bart plan", "plan this project for bart", "break this down into bart tasks", "create a plan for parallel execution", "plan workstreams", or wants to structure work for automated AI agent execution via bart-loop. Also activates when the user invokes /bart-plan.
version	4.0.0

Bart Plan Converter

You convert existing plans into bart-loop format — a structured plan.md that bart plan parses into tracked tasks with requirements coverage, specialist assignment, and dependency resolution.

You are not a planner. The user has already planned using Claude's native planning (/plan, conversation, or an external document). Your job is to locate that plan and restructure it into bart-compatible format.

Auto-Trigger (Hook Before Plan Completion)

This skill auto-triggers as a pre-implementation hook when:

1. Claude has just finished writing a plan (via /plan, plan mode, or ExitPlanMode)
2. AND the project has a .bart/ directory in its root

Timing is critical: Run this skill BEFORE presenting the plan for implementation. The user expects bart-plan to catch every plan automatically so they can dismiss Claude's "shall I implement?" prompt — the plan is already saved in .bart/plans/ for bart run to execute later.

When auto-triggered, skip asking the user for plan source — proceed directly with conversion using the plan that was just created. However, always pause at Step 3c to confirm skill/agent assignments with the user before writing the final plan.

Tool Restrictions

CRITICAL: During Steps 1–6, you MUST NOT use Edit, Write, or Bash tools. You are in conversation mode only. The system will block these tool calls, but you should not attempt them. Only use file-writing tools in Step 7 to write the plan file.

Read-only tools (Read, Glob, Grep) are allowed at any step for research. Bash is permitted only in Step 3a for specialist discovery commands (bart specialists).

How It Works

The user triggers this skill manually or it auto-triggers before plan implementation. You then:

1. Locate source plan — Find the plan just created in .claude/plans/ or ~/.claude/plans/, or accept a path argument
2. Analyze source plan — Parse the freeform plan's structure, goals, files, and work items
3. Discover skills & propose assignments — Find local specialists + search find-skills if installed, propose skill/agent per task, ask user to confirm
4. Derive requirements — Extract [REQ-XX] requirements from the plan's goals and context
5. Structure — Reorganize into bart workstreams with confirmed specialist tags and file references
6. Validate — Ensure full requirements coverage, correct specialist tags, and proper workstream ordering
7. Write — Save to .bart/plans/<date>-<slug>.md and confirm. The user then runs bart plan → bart run.

Input

Query: $ARGUMENTS

If a path is provided, use it as the source plan. Otherwise, search for the latest Claude plan.

Step 1: Locate Source Plan

Find the source plan to convert. Check in order:

1. Path argument — If the user provided a file path, use it directly
2. Just-created plan — If auto-triggered after plan mode, use the plan file that was just written (check .claude/plans/ for the most recently modified .md file)
3. Latest Claude plan — Search ./.claude/plans/ then ~/.claude/plans/ for the most recently modified .md file

If no source plan is found, tell the user:

No source plan found. Please either:
1. Create a plan first using Claude's /plan command or in conversation
2. Provide a path: /bart-plan path/to/your/plan.md

Do NOT proceed to gather requirements from scratch — that is Claude's job, not yours.

Step 2: Analyze Source Plan

Read the source plan and extract:

• Goals / objectives — What the plan aims to achieve (these become requirements)
• Work items — Individual tasks, steps, or changes described (these become ### tasks)
• File references — Any files, paths, or directories mentioned (these become Files: lines)
• Dependencies — Any ordering or sequencing implied between work items
• Technical context — Stack, constraints, patterns mentioned
• Testing context — Test commands, test frameworks, existing test patterns, test file locations, and any validation/verification criteria mentioned in the source plan. Look for references to test runners (jest, vitest, pytest, go test), test directories, CI config with test steps, and any package.json test scripts.

Do not discard information. Every meaningful work item in the source plan should map to a task in the output.

Step 3: Discover Skills & Propose Assignments

For each task, determine the best skill or agent to execute it. This is a critical step — the right specialist assignment directly impacts execution quality.

3a. Discover available skills

First, collect all available skills/agents/commands from two sources:

Local specialists — always check:

bart specialists --history 2>/dev/null || echo "No local specialists discovered"

Use history stats when proposing assignments: prefer high completion-rate specialists for critical tasks, flag high reset-rate specialists, note untested specialists in the confidence column.

Remote skill search — check if find-skills is installed:

claude -p "Use the find-skills skill to search for: test" 2>/dev/null | head -5

If find-skills responds with skill results, it's available. If it errors or is not recognized, skip remote search and rely on local specialists only.

3b. Analyze each task and propose a skill/agent

For every task extracted from the source plan:

1. Look at the task context — what is the task doing? (writing code, running tests, deploying, configuring, designing, documenting, etc.)
2. Check local specialists first — is there a local skill/agent/command that matches this task's domain?
3. Search remotely if needed — if no strong local match exists AND find-skills is available, search for a relevant skill:

   Use the find-skills skill to search for: <task domain keywords>
   

4. Fall back to default — if no specialist matches, leave the task untagged (it will run with the default claude/opencode agent)

3c. Present assignments and ask for confirmation

Before proceeding, present the user with a summary table of proposed assignments:

Proposed skill/agent assignments:

  Task                              | Proposed Skill/Agent     | Confidence
  ----------------------------------|--------------------------|------------
  Initialize project config         | (default agent)          | —
  Build REST API endpoints          | backend-developer        | High
  Create React dashboard            | frontend                 | High
  Write integration tests           | test-runner              | Medium
  Set up CI pipeline                | ?                        | Low

Tasks marked "?" or "Low" confidence — I'm not sure which skill fits best.

Ask refinement questions when confidence is low or medium:

• "Task X involves both database migrations and API changes — should I use backend-developer or split it into two tasks?"
• "I found a remote skill vercel-deploy that could handle Task Y — should I use it, or keep the default agent?"
• "Task Z is ambiguous — it could be handled by frontend (UI work) or test-runner (component tests). Which fits better?"

Wait for the user to confirm or adjust assignments before proceeding to Step 4. The user may:

• Approve all assignments as-is
• Override specific assignments
• Ask you to search for additional skills
• Decide to split or merge tasks based on specialist availability

3d. Apply confirmed assignments

After user confirmation, use the confirmed specialist names as [specialist-name] tags in the ### task headings. Tasks with no specialist assignment get no tag.

Step 4: Derive Requirements

Extract requirements from the source plan's goals, objectives, and context. Each requirement should be a concrete, verifiable outcome:

• Map high-level goals to [REQ-XX] identifiers
• Keep requirements atomic — one testable thing per requirement
• Ensure every work item from the source plan is covered by at least one requirement
• When the source plan mentions testing, validation, or verification criteria, capture those as explicit requirements (e.g., "All API endpoints have integration tests", "Performance benchmarks verified under load")

Step 5: Structure into Bart Format

The plan MUST follow this exact structure. The bart plan parser uses ## headings as workstream boundaries and ### headings as individual tasks.

Format Reference

# Plan: [Project Name]

## Requirements
- [REQ-01] First requirement description
- [REQ-02] Second requirement description
- [REQ-03] Third requirement description

## Testing
Test command: npm test
Framework: vitest
Conventions: tests live in __tests__/ directories, named *.test.ts

## Section Name (becomes Workstream A)
### Task title [REQ-01]
Description of what to do.

**Test first:**
- Create `tests/path/to/test.ts`
- Test: [description of what the test verifies]
```typescript
// Complete test code here

• Run: npm test -- tests/path/to/test.ts
• Expected: FAIL (function not defined / behavior not implemented)

Implementation:

• Modify path/to/file.ts
• [Description of implementation steps]

Verify:

• Run: npm test -- tests/path/to/test.ts
• Expected: PASS

Files: path/to/file.ts, tests/path/to/test.ts

[specialist-name] Another task title [REQ-02]

Description with specialist tag for routing.

Test first:

• Create tests/components/Thing.test.tsx
• Test: [description of what the test verifies]

// Complete test code here

• Run: npm test -- tests/components/Thing.test.tsx
• Expected: FAIL

Implementation:

• Modify src/components/Thing.tsx
• [Description of implementation steps]

Verify:

• Run: npm test -- tests/components/Thing.test.tsx
• Expected: PASS

Files: src/components/Thing.tsx, tests/components/Thing.test.tsx

Another Section (becomes Workstream B after every 2 sections)

Task in next workstream [REQ-03]

Description of the task.

Test first:

• Create tests/api/endpoint.test.ts
• Test: [description of what the test verifies]

// Complete test code here

• Run: npm test -- tests/api/endpoint.test.ts
• Expected: FAIL

Implementation:

• Modify src/api/endpoint.ts
• [Description of implementation steps]

Verify:

• Run: npm test -- tests/api/endpoint.test.ts
• Expected: PASS

Files: src/api/endpoint.ts, tests/api/endpoint.test.ts

### Parser Rules (how `bart plan` interprets this)

These rules are baked into the parser — your plan must conform to them:

1. **`## Requirements` section** — Parsed as explicit requirements. Each line must match: `- [REQ-XX] description`. If this section exists, tasks must reference requirements with `[REQ-XX]` markers. If omitted, requirements are auto-generated from `##` section headings (lower fidelity).

2. **`## Testing` section** — Parsed as testing metadata (skipped for workstream calculation, injected into task context). Contains free-text fields: `Test command:` (how to run tests), `Framework:` (test framework in use), `Conventions:` (where tests live, naming patterns). This section appears between `## Requirements` and the first workstream section.

3. **`##` headings** — Define workstream boundaries. The first `##` section becomes workstream A, and the workstream letter increments every 2 sections (sections 1-2 → A, sections 3-4 → B, etc.). The `## Requirements` and `## Testing` sections are skipped.

4. **`###` headings** — Each becomes an individual task. The task ID is `{workstream}{number}` (e.g., A1, A2, B1).

5. **`[specialist-name]` in `###` headings** — Tags a task for a specific specialist. Must match a discovered specialist name.

6. **`[REQ-XX]` in `###` headings or nearby lines** — Links the task to that requirement for coverage tracking.

7. **File references** — The parser extracts file paths (pattern: `word/word.ext`) from the 10 lines after each `###` heading. List target files explicitly.

8. **Dependencies** — The parser detects dependency keywords ("depends", "after", "requir") in task titles to create dependency links to the previous task in the same section.

### Workstream Separation Rules

Follow these rules when organizing tasks into `##` sections:

1. **Group by independence** — Tasks in different `##` sections can run in parallel. If task X must finish before task Y, put them in the same section (Y after X), or use dependency keywords in Y's title.

2. **Foundation first** — Setup, scaffolding, and config tasks go in the first section (workstream A). Everything else builds on these.

3. **Feature verticals** — Group by feature domain, not technical layer. Don't create a "Models" section and an "API" section — create a "User Auth" section with both.

4. **File affinity** — Tasks touching the same files belong in the same workstream to avoid merge conflicts during parallel execution.

5. **Testing after features** — Integration tests and E2E tests go in a later section that depends on feature workstreams completing.

6. **3-5 tasks per section** — If a section would have 6+ tasks, split it into two sections.

7. **Specialist clustering** — Group tasks for the same specialist together when possible (all `[frontend]` tasks in one section, all `[backend]` in another) to enable one specialist per workstream.

## Step 6: Validate Before Writing

Before outputting the plan, verify:

- [ ] Every `[REQ-XX]` in the Requirements section has at least one task referencing it
- [ ] No task references a `[REQ-XX]` that doesn't exist in the Requirements section
- [ ] Sections are ordered by dependency (later sections can depend on earlier ones completing)
- [ ] Specialist tags (if used) match discovered specialist names — warn if using unknown tags
- [ ] Each section has 3-5 tasks (split or merge if needed)
- [ ] File paths are realistic and specific (not generic placeholders)
- [ ] Every work item from the source plan is represented in the output
- [ ] Every task has associated test files in its `Files:` line (both source and test files listed)
- [ ] Every task includes **Test first**, **Implementation**, and **Verify** blocks with complete test code
- [ ] A `## Testing` section exists with test command, framework, and conventions

## Step 7: Write and Review

Save the converted plan into its own directory under `.bart/plans/`:

.bart/plans/-/plan.md

For example: `.bart/plans/2026-02-15-fix-dashboard-performance/plan.md`

The slug is derived from the plan's `# Plan: ...` title, lowercased and hyphenated. Create the directory if it doesn't exist, then write `plan.md` inside it. Do NOT write a flat `.md` file directly in `.bart/plans/`.

Note: `tasks.json` is generated separately when the user runs `bart plan` — do not create it yourself. The `bart plan` command parses `plan.md` and produces a co-located `tasks.json` in the same directory.

After writing the file, **auto-invoke bart-plan-review** with the plan path as the argument. Do NOT print a completion summary — the review skill handles validation, user checkpoint, and final output with next steps.

/bart-plan-review .bart/plans//plan.md

## Conversion Example

### Before: Freeform Claude Plan

```markdown
# Fix dashboard performance

## Context
The dashboard page loads slowly due to unoptimized API calls and missing caching.
Users report 5-8 second load times. Target is under 2 seconds.

## Root Cause
1. The Overview component makes 6 sequential API calls that could be parallelized
2. No client-side caching — every navigation re-fetches all data
3. The metrics chart re-renders on every state change due to missing memoization

## Fix
- Refactor API calls in `src/pages/Overview.tsx` to use `Promise.all`
- Add React Query for data caching in `src/providers/QueryProvider.tsx`
- Memoize chart component with `React.memo` and `useMemo` for computed data
- Add loading skeletons to improve perceived performance

## Verification
- Lighthouse performance score > 90
- Dashboard loads in under 2 seconds on throttled 3G

After: Bart-Compatible Plan

# Plan: Fix Dashboard Performance

## Requirements
- [REQ-01] Dashboard loads in under 2 seconds
- [REQ-02] API calls are parallelized, not sequential
- [REQ-03] Client-side caching prevents redundant fetches
- [REQ-04] Chart component does not re-render unnecessarily

## Testing
Test command: npm test
Framework: vitest
Conventions: tests in __tests__/ directories, named *.test.ts

## API & Caching
### Parallelize API calls in Overview [REQ-01] [REQ-02]
Refactor the 6 sequential API calls in Overview to use Promise.all for parallel fetching.

**Test first:**
- Create `__tests__/pages/Overview.test.tsx`
- Test: API calls are made in parallel, not sequentially
```typescript
import { render, waitFor } from '@testing-library/react';
import { Overview } from '../src/pages/Overview';

test('fetches all API data in parallel', async () => {
  const fetchSpy = vi.spyOn(global, 'fetch');
  render(<Overview />);
  await waitFor(() => {
    expect(fetchSpy).toHaveBeenCalledTimes(6);
    // All calls should start before any resolve
    const callTimes = fetchSpy.mock.invocationCallOrder;
    expect(Math.max(...callTimes) - Math.min(...callTimes)).toBeLessThan(2);
  });
});

• Run: npm test -- __tests__/pages/Overview.test.tsx
• Expected: FAIL (calls are still sequential)

Implementation:

• Modify src/pages/Overview.tsx
• Replace sequential await calls with Promise.all

Verify:

• Run: npm test -- __tests__/pages/Overview.test.tsx
• Expected: PASS

Files: src/pages/Overview.tsx, tests/pages/Overview.test.tsx

Add React Query provider for data caching [REQ-03]

Set up React Query with appropriate stale times to cache dashboard data across navigations.

Test first:

• Create __tests__/providers/QueryProvider.test.tsx
• Test: data is cached and not re-fetched on navigation

import { renderHook } from '@testing-library/react';
import { QueryProvider } from '../src/providers/QueryProvider';

test('caches dashboard data across navigations', async () => {
  const fetchSpy = vi.spyOn(global, 'fetch');
  const { rerender } = renderHook(() => useDashboardData(), {
    wrapper: QueryProvider,
  });
  rerender();
  expect(fetchSpy).toHaveBeenCalledTimes(1); // not refetched
});

• Run: npm test -- __tests__/providers/QueryProvider.test.tsx
• Expected: FAIL (no caching exists yet)

Implementation:

• Modify src/providers/QueryProvider.tsx and src/main.tsx
• Add React Query provider with stale time configuration

Verify:

• Run: npm test -- __tests__/providers/QueryProvider.test.tsx
• Expected: PASS

Files: src/providers/QueryProvider.tsx, src/main.tsx, tests/providers/QueryProvider.test.tsx

Rendering & UX

[frontend] Memoize chart component [REQ-04]

Wrap chart with React.memo and use useMemo for computed data to prevent unnecessary re-renders.

Test first:

• Create __tests__/components/MetricsChart.test.tsx
• Test: chart does not re-render when parent state changes unrelated to chart data

import { render } from '@testing-library/react';
import { MetricsChart } from '../src/components/MetricsChart';

test('does not re-render on unrelated state changes', () => {
  const renderSpy = vi.fn();
  const { rerender } = render(
    <MetricsChart data={mockData} onRender={renderSpy} />
  );
  rerender(<MetricsChart data={mockData} onRender={renderSpy} />);
  expect(renderSpy).toHaveBeenCalledTimes(1);
});

• Run: npm test -- __tests__/components/MetricsChart.test.tsx
• Expected: FAIL (component re-renders every time)

Implementation:

• Modify src/components/MetricsChart.tsx
• Wrap with React.memo and useMemo for computed data

Verify:

• Run: npm test -- __tests__/components/MetricsChart.test.tsx
• Expected: PASS

Files: src/components/MetricsChart.tsx, tests/components/MetricsChart.test.tsx

[frontend] Add loading skeletons [REQ-01]

Add skeleton placeholders for dashboard panels to improve perceived performance during data fetch.

Test first:

• Create __tests__/components/Skeleton.test.tsx
• Test: skeleton is shown while data is loading

import { render, screen } from '@testing-library/react';
import { Overview } from '../src/pages/Overview';

test('shows skeleton placeholders while loading', () => {
  render(<Overview />);
  expect(screen.getAllByTestId('skeleton-placeholder')).toHaveLength(4);
});

• Run: npm test -- __tests__/components/Skeleton.test.tsx
• Expected: FAIL (no skeleton component exists)

Implementation:

• Create src/components/Skeleton.tsx
• Modify src/pages/Overview.tsx to show skeletons during loading

Verify:

• Run: npm test -- __tests__/components/Skeleton.test.tsx
• Expected: PASS

Files: src/pages/Overview.tsx, src/components/Skeleton.tsx, tests/components/Skeleton.test.tsx

Verification

Run Lighthouse performance audit [REQ-01]

Verify Lighthouse performance score exceeds 90 and load time is under 2 seconds on throttled 3G.

Test first:

• Create __tests__/performance/lighthouse.test.ts
• Test: Lighthouse score meets performance threshold

import { runLighthouse } from '../test-utils/lighthouse';

test('dashboard Lighthouse performance score > 90', async () => {
  const result = await runLighthouse('http://localhost:3000/dashboard');
  expect(result.performance).toBeGreaterThan(90);
});

• Run: npm test -- __tests__/performance/lighthouse.test.ts
• Expected: FAIL (performance not yet optimized)

Implementation:

• No new code — this task verifies the cumulative effect of all previous tasks

Verify:

• Run: npm test -- __tests__/performance/lighthouse.test.ts
• Expected: PASS

Files: tests/performance/lighthouse.test.ts