scripts/worktree-feature/: MDX Prompt Templates
Ghost doc. Source MDX prompt files live in .worktrees/12-feature-flag-gate-all-non-mvp/scripts/worktree-feature/components/ (a worktree branch, not on main). The excerpts below reflect that source.
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
- Keep slugs short but descriptive (2-5 words)
..._(excerpt abridged; real file also includes an EXPECTED TICKET BREAKDOWN guide and a required `{props.schema}` JSON output block)_
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}
Test output: ${props.previousImplementation.testOutput}
Fix issues from previous attempt.` : ""}
{props.validationFeedback ? `
VALIDATION RESULTS FROM PREVIOUS ATTEMPT:
- All passed: ${props.validationFeedback.allPassed}
- Failures: ${props.validationFeedback.failingSummary ?? "none"}
Fix ALL validation failures before proceeding.` : ""}
{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.
The “all commits on main” rule is specific to the worktree-feature pipeline, which uses Git worktrees for isolation so each ticket runs in its own filesystem sandbox. Standard Smithers workflows do not restrict branching strategy.
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:
- There is NO such thing as a non-blocking nit.
- ANY way to improve the code → MUST be improved.
- Every issue, critical, major, minor, OR nit, MUST be fixed before approval.
- approved: true ONLY when there are genuinely ZERO issues of any severity.
- Do not "let things slide" because they seem small.
..._(excerpt abridged; real file also includes VALIDATION RESULT, ARCHITECTURE, and DOCUMENTATION review sections)_
Validate.mdx
VALIDATION. Ticket: {props.ticketId}, {props.ticketTitle}
Independently verify implementation correctness.
Don't trust implementation agent claims; run everything yourself.
CANONICAL CHECK: Run `cd submodules/smithers && 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}
- testsAdded: {props.testsAdded}
- 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";
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.