| 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:
- Claude has just finished writing a plan (via
/plan, plan mode, or ExitPlanMode)
- 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:
- Locate source plan — Find the plan just created in
.claude/plans/ or ~/.claude/plans/, or accept a path argument
- Analyze source plan — Parse the freeform plan's structure, goals, files, and work items
- Discover skills & propose assignments — Find local specialists + search
find-skills if installed, propose skill/agent per task, ask user to confirm
- Derive requirements — Extract
[REQ-XX] requirements from the plan's goals and context
- Structure — Reorganize into bart workstreams with confirmed specialist tags and file references
- Validate — Ensure full requirements coverage, correct specialist tags, and proper workstream ordering
- 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:
- Path argument — If the user provided a file path, use it directly
- 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)
- 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:
- Look at the task context — what is the task doing? (writing code, running tests, deploying, configuring, designing, documenting, etc.)
- Check local specialists first — is there a local skill/agent/command that matches this task's domain?
- 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>
- 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]
- 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]
- 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);
});
- 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
