Skip to main content

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.