ljw1004

## HOW TO PLAN A MILESTONE

If the user asks you to plan a milestone, these are the steps to take.

1. Read all of PLAN.md (the current document) to learn about the milestone, in the context of past and future milestones. This document lists only the bare essential deliverables and validation steps for each milestone. Read ARCHITECTURE.md to learn the codebase, and LEARNINGS.md for valuable wisdom.
2. Ask any important initial clarifying questions about the milestone you might have.
  - If you're not asking any questions at all for the entire planning, something's wrong! I know that this file isn't fully specified. There must be important things for you to clarify.
  - It's better to eliminate unknowns in the milestone by discovering facts, not by asking the user. Do not ask questions that can be answered from the repo or system (for example, "where is this struct?" or "which UI component should we use?" when exploration can make it clear). Only ask once you have exhausted reasonable research.
     - **Discov

ljw1004

## HOW TO EXECUTE A MILESTONE

[Please include what follows verbatim when you write a PLAN_M{n}.md file. It will be used to guide anyone who executes on your plan.]

If the user asks you to execute on a plan, these are the steps to take.

1. Implement the plan
   - You should check your work with AI autonomous validation and testing.
   - The hope is that implementation can be done with a minimum of user interaction, preferably none at all.
   - Once it is complete, fill in the "Validation" section to the bottom of the plan showing how you have validated it and what were the results.

ljw1004

# <PROJECT TITLE>

We are working to add <PROJECT DESCRIPTION>. The following guidance files will help you do your job effectively.

- AGENTS.md -- This current file is already inserted into the start of every agent conversation, and explains how the user wants the AI to behave.
- <COMPANY-MD> -- general information about how to develop in the <COMPANY> codebase
- ai/LEARNINGS.md -- If planning or writing project code you *MUST ALWAYS* read this file, which contains your hard-won wisdom and experience, learned through costly trial and error. You must read this to avoid making the same mistakes in all work you do.
- ai/ARCHITECTURE.md -- This is where you keep your notes about the architecture of <PROJECT>, how to develop within it, and also hard-won wisdom and experience about how its functions work. If planning or writing project code, read this to understand the code you're working in.
- ai/PLAN.md -- Describes the overall context and goal of the project. You will normally only read this if asked to plan th

ljw1004

#!/usr/bin/env -S jq -n -r --unbuffered -f

# This is a script to turn Claude's stream-json output into stream-text for human consumption, to see its progress.
# e.g. claude --verbose --output-format stream-json -p "Why is the sky blue?" | ./claude_stream.jq


def trunc($s):
  if $s == null then ""
  else ($s | tostring | if length > 280 then .[0:280] + "…" else . end)
  end;

ljw1004

#!/usr/bin/env python3
"""
PostToolUse hook: periodic LEARNINGS.md reminder.

On first invocation for an agent/subagent, outputs the full LEARNINGS.md
instructions. Thereafter, outputs a short reminder about every 10 assistant turns.
Does nothing if no LEARNINGS.md exists in the project root.

This works on a per-agent or per-subagent basis. This is tricky because
hooks don't tell us who they fired for. We work around this by looking for

ljw1004

You are COAGENT, an expert at prompt engineering. You will be told a conversation
between a USER who writes prompts, and an ASSISTANT who responds. Your job is
to critique the USER's prompt if necessary.

You will respond in exactly one of two ways (strict format):

1) Line 1 must be exactly: SKIP
   - Lines 2+: one short sentence explaining why no advice is needed (≤ 30 words).

2) Line 1 must be exactly: USER

ljw1004

<system-reminder>
Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make any edits (with the exception of the plan file mentioned below), run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This supercedes any other instructions you have received.

## Plan File Info:
No plan file exists yet. You should create your plan at /home/ljw/.claude/plans/jaunty-skipping-lighthouse.md using the Write tool.
You should build your plan incrementally by writing to or editing this file. NOTE that this is the only file you are allowed to edit - other than this you are only allowed to take READ-ONLY actions.

**Plan File Guidelines:** The plan file should contain only your final recommended approach, not all alternatives considered. Keep it comprehensive yet concise - detailed enough to execute effectively while avoiding unnecessary verbosity.

## Enhanced Planning Workflow

ljw1004

#!/bin/bash
set -euo pipefail
trap 'echo "at line $LINENO, exit code $? from $BASH_COMMAND" >&2; exit 1' ERR

# This is a Claude Code hook to stop it saying "you are right".
#
# Installation:
# 1. Save this script and chmod +x it to make it executable.
# 2. Within Claude Code, /hooks / UserPromptSubmit > Add a new hook (this file)
#

ljw1004

// TUPLE MICRO-BENCHMARKS, based on https://www.dotnetperls.com/tuple-keyvaluepair
//
// Tuples are generally fastest.
// ValueTuple is fastest in the particular case of GetHashCode.
// KeyValuePair is always worst.
//
//
// RAW RESULTS
// Numbers in milliseconds (lower is better)
//

ljw1004

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Threading.Tasks;

class Program
{
    static void Main()
    {