From 8283797ff260207a53bf453b58ffd9e5d586561e Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Sun, 15 Mar 2026 20:08:38 -0500 Subject: [PATCH] docs: update ARCHITECTURE + CONTRIBUTING for new placeholders Add {{BASE_BRANCH_DETECT}} to ARCHITECTURE.md placeholder list. Cross-reference CLAUDE.md template authoring guidance from CONTRIBUTING.md. Co-Authored-By: Claude Opus 4.6 (1M context) --- ARCHITECTURE.md | 2 +- CONTRIBUTING.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 07d03bad..12ee369b 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -179,7 +179,7 @@ gen-skill-docs.ts (reads source code metadata) SKILL.md (committed, auto-generated sections) ``` -Templates contain the workflows, tips, and examples that require human judgment. The `{{COMMAND_REFERENCE}}` and `{{SNAPSHOT_FLAGS}}` placeholders are filled from `commands.ts` and `snapshot.ts` at build time. This is structurally sound — if a command exists in code, it appears in docs. If it doesn't exist, it can't appear. +Templates contain the workflows, tips, and examples that require human judgment. Placeholders like `{{COMMAND_REFERENCE}}`, `{{SNAPSHOT_FLAGS}}`, `{{UPDATE_CHECK}}`, `{{BROWSE_SETUP}}`, and `{{BASE_BRANCH_DETECT}}` are filled from `commands.ts`, `snapshot.ts`, and `gen-skill-docs.ts` at build time. `{{BASE_BRANCH_DETECT}}` provides dynamic base branch detection for PR-targeting skills (ship, review, qa, plan-ceo-review) so they work with stacked branches and non-main targets. ### Why committed, not generated at runtime? diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 34e502ea..ca1828c2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -180,6 +180,8 @@ bun run skill:check bun run dev:skill ``` +For template authoring best practices (natural language over bash-isms, dynamic branch detection, `{{BASE_BRANCH_DETECT}}` usage), see CLAUDE.md's "Writing SKILL templates" section. + To add a browse command, add it to `browse/src/commands.ts`. To add a snapshot flag, add it to `SNAPSHOT_FLAGS` in `browse/src/snapshot.ts`. Then rebuild. ## Conductor workspaces