Skip to main content

​
scripts/worktree-feature/ — MDX Prompt Templates

Ghost doc — Real MDX prompt files from scripts/worktree-feature/components/.

​
Usage

Each .mdx file is imported as a JSX component and rendered as children of <Task>. Props interpolate via {props.xxx}: 
import ImplementPrompt from "./Implement.mdx";

<Task id="implement" output={outputs.implement} agent={codex}>
  <ImplementPrompt
    ticketId="vcs-jj-rewrite"
    ticketTitle="Rewrite VCS layer"
    ticketDescription="Full rewrite of the VCS abstraction"
    acceptanceCriteria="Tests pass"
  />
</Task>

​
Discover.mdx

TICKET DISCOVERY — Break PRD into Ordered Implementation Tickets

GOAL: Break the PRD into ordered, independently-implementable tickets.

STEPS:
1. Read the PRD thoroughly
2. Explore the codebase to understand current state
3. Break the PRD into tickets ordered by dependency
4. Each ticket should be the smallest independently testable unit

TICKET ID RULES:
- IDs MUST be lowercase kebab-case slugs (e.g. "vcs-jj-rewrite")
- NEVER use numeric IDs like T-001 — they collide across runs

​
Implement.mdx

IMPLEMENTATION — Ticket: {props.ticketId} — {props.ticketTitle}

Implement FULLY end-to-end. Do NOT stop until fully implemented + ALL tests pass.

TICKET DESCRIPTION:
{props.ticketDescription}

ACCEPTANCE CRITERIA:
- {props.acceptanceCriteria}

FILES TO MODIFY: {JSON.stringify(props.filesToModify)}
FILES TO CREATE: {JSON.stringify(props.filesToCreate)}

{props.previousImplementation ? `
PREVIOUS ATTEMPT:
What was done: ${props.previousImplementation.whatWasDone}
Fix issues from previous attempt.` : ""}

{props.reviewFixes ? `
REVIEW FIXES NEEDED:
${props.reviewFixes}` : ""}

IMPLEMENTATION RULES:
1. Implement ticket FULLY — nothing unfinished
2. Follow existing framework patterns exactly
3. ALL commits go directly on main. NEVER create branches.
4. After implementing, run tests
5. If tests fail, fix before moving on.

​
Review.mdx

CODE REVIEW — Ticket: {props.ticketId} — {props.ticketTitle} — Reviewer: {props.reviewer}

EXTREMELY strict code reviewer.

FILES CHANGED:
Created: {JSON.stringify(props.filesCreated)}
Modified: {JSON.stringify(props.filesModified)}

Review against:
1. CORRECTNESS — Matches PRD exactly?
2. CODE QUALITY — DRY? Follows patterns?
3. TEST COVERAGE — Every edge case?
4. TYPE SAFETY — No `any` or unsafe casts?

APPROVAL POLICY:
- ANY way to improve the code → MUST be improved.
- approved: true ONLY when there are genuinely ZERO issues.

​
Validate.mdx

VALIDATION — Ticket: {props.ticketId} — {props.ticketTitle}

Independently verify implementation correctness.
Don't trust implementation agent claims — run everything yourself.

CANONICAL CHECK: Run `bun test`
ALL tests must pass.

ZERO TOLERANCE:
- ALL tests pass. No exceptions.
- Type errors count as failures.

​
ReviewFix.mdx

REVIEW FIX — Ticket: {props.ticketId} — {props.ticketTitle}

REVIEW ISSUES:
{JSON.stringify(props.issues, null, 2)}

REVIEW FEEDBACK:
{props.feedback}

RULES:
1. Fix every legitimate issue
2. If FALSE POSITIVE: record in output JSON
3. Run tests after fixes

​
Report.mdx

REPORTING — Ticket: {props.ticketId} — {props.ticketTitle}

IMPLEMENTATION SUMMARY:
{props.whatWasDone}

PRE-COMPUTED METRICS (echo these back exactly):
- filesChanged: {props.filesChanged}
- reviewRounds: {props.reviewRounds}

Assess: Anything go wrong? Agent struggle? Lessons for future?

​
System Prompt — system-prompt.mdx

The top-level system prompt uses custom MDX components to inject context: 
# Smithers Framework — Worktree + MergeQueue Implementation

## PRD
<Prd />

## Smithers Framework Context
<SmithersContext />

## Coding Conventions
- Follow existing patterns exactly
- Run `bun test` to validate changes
- Atomic commits with emoji prefixes
Components are injected at render time via renderMdx(): 
import { renderMdx } from "smithers-orchestrator";
import SystemPromptMdx from "./prompts/system-prompt.mdx";

export const SYSTEM_PROMPT = renderMdx(SystemPromptMdx, {
  components: { Prd: () => prdContent, SmithersContext: () => contextContent },
});

​
Key Patterns

  • MDX as prompt templates — structured prompts with JSX interpolation for dynamic content.
  • Props-driven — ticket data, previous results, and feedback pass as props.
  • Conditional sections — {props.previousImplementation ? ... : ""} adds context only when iterating.
  • renderMdx() — composes system prompts from multiple sources using custom MDX components.