Julian Harris boxabirds

AI Coding Agent Policy Document

1. Introduction

1.1. Purpose

This document outlines the coding policy that any human or AI Coding Agent (hereafter "AI Agent") must strictly adhere to when making changes to a codebase. It covers scoping features via Product Backlog Items (PBIs) and managing the tasks required to implement those features. This policy ensures a disciplined, transparent, and human-controlled approach to software development.

This document should typically be stored in a project's documentation directory, for example, in subfolders like docs/delivery/ or docs/planning/, separate from user-facing documentation.

Deepseek r1 says this

Key Clarifications

APFS Global Kernel Lock (vfs-layer lock):
- Not fully bypassed: Even with a RAM disk formatted as APFS, macOS's global I/O lock still technically exists. However, because RAM disk operations are orders of magnitude faster than disk I/O, contention for this lock is drastically reduced. This makes the lock effectively irrelevant for most workflows, as operations complete before significant contention occurs.
- Not the same as Linux: macOS lacks a true tmpfs equivalent, so while a RAM disk helps, it’s not as seamless as Linux’s in-memory filesystem.
RAM Disk Format:
- macOS RAM disks can be formatted as HFS+ or APFS. While APFS is the default, formatting as HFS+ might slightly reduce lock contention (though benchmarks vary). Either way, the speed of RAM mitigates lock-related bottlenecks.

	# Project Policy

	This policy provides a single, authoritative, and machine-readable source of truth for AI coding agents and humans, ensuring that all work is governed by clear, unambiguous rules and workflows. It aims to eliminate ambiguity, reduce supervision needs, and facilitate automation while maintaining accountability and compliance with best practices.

	# 1. Introduction

	> Rationale: Sets the context, actors, and compliance requirements for the policy, ensuring all participants understand their roles and responsibilities.

	## 1.1 Actors

	# Project Policy

	This policy provides a single, authoritative, and machine-readable source of truth for AI coding agents and humans, ensuring that all work is governed by clear, unambiguous rules and workflows. It aims to eliminate ambiguity, reduce supervision needs, and facilitate automation while maintaining accountability and compliance with best practices.

	# 1. Introduction

	> Rationale: Sets the context, actors, and compliance requirements for the policy, ensuring all participants understand their roles and responsibilities.

	## 1.1 Actors

	# Written by Julian Harris https://makingaiagents.substack.com
	# [email protected]
	# Apache License
	# Version 2.0, January 2004
	# http://www.apache.org/licenses/

	# TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

	# 1. Definitions.

	<!DOCTYPE html>
	<html lang="en">
	<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<title>LLM Code Analysis Visualization (Final Layout)</title>
	<style>
	body { margin: 0; overflow: hidden; font-family: sans-serif; background-color: #111; color: #eee; }
	canvas { display: block; }

	#!/bin/bash
	# tries to answer the question "do I have any models installed that can be configured to return deterministic results?"

	# Get list of available models
	MODELS=$(ollama list \| awk 'NR>1 {print $1}')

	# Function to test reproducibility for a specific model
	test_model() {
	local model=$1
	local seed=42

	# pipenv is extremely slow but it's very easy to use.
	# here are two wrapper scripts to emulate pipenv shell and pipenv install

	# add to your .zshrc file

	# emulate pipenv shell
	function uvshell() {
	if [[ -d .venv ]]; then
	source .venv/bin/activate \|\| { echo "Failed to activate virtual env"; return 1; }
	else

	At this point I want you to create a design doc that describes the following things. The things below are to be made into separate .md files in a doc/ directory.

	mermaid diagrams showing the key objects and their relationships
	mermaid sequence diagram showing key interactions for the main use cases
	summarise the agent journey so far: review the entire chat history and highlight the things that were easy to implement (one prompt => feature) and things that were very hard to implement
	following this, create a maintenance guide whose sole objective is to help the next contributors to the code base. It should explain the frameworks and services used, the components, and notes on anything about the implementation that may not be obvious to someone even if they have experience with the framework used.
	finally summarise areas that need to be developed to turn this into a proper product that can be supported, maintained and expanded.E.g. logging, telemetry, security considerations etc.

	SQL:

	-- name: GetRecentPostsByTags :many
	-- $1: TagNames
	SELECT DISTINCT p.id, p.created_at, t.name AS tag_name
	FROM posts p
	JOIN post_tags pt ON p.id = pt.post_id
	JOIN tags t ON pt.tag_id = t.id
	WHERE t.name = ANY($1::text[]) AND p.created_at < $2
	ORDER BY p.created_at DESC