claude-flightdeck CLAUDE.md

CLAUDE.md — AI-Workflows (template repo)

This file is for Claude Code instances editing the template itself. It is NOT shipped to installed projects — the installer renders core/CLAUDE.md.tmpl into the target instead. Treat that as the "user-facing" CLAUDE.md and this one as the "maintainer" view.

What this repo is

A portable control-plane template, copied into other projects by install.sh. Two production codebases informed it (idip-platform, aggegator). See README.md for user-facing usage.

Layout

.
├── install.sh                # one-shot installer (placeholder render + preset merge)
├── template.config.example   # config var skeleton
├── core/                     # ALWAYS installed
├── presets/                  # opt-in via --preset
└── docs/                     # docs about THIS template (not what install ships)

Anything inside core/ lands in every target. Anything inside presets/<name>/ lands only when --preset <name> is selected. Anything inside docs/ (top level here) stays in this repo.

Rules for editing the template

1. De-domain-specify everything in core/. No mention of idip-, agg-, IDIP-XXX, TG-AGG-S*, specific PRD IDs, or tech-stack opinions. Opinions go in presets/. If you find yourself writing "Postgres" or "Vue" in core/, you're in the wrong folder.
2. Use the placeholder convention. Files needing project-specific values get the .tmpl suffix and use {{PROJECT_NAME}}, {{PROJECT_SLUG}}, {{AGENT_PREFIX}}, {{TECH_STACK_DESC}}, {{BRAIN_PATH}}, {{TASK_ID_PREFIX}}. If you add a new placeholder, add it to the sed block in install.sh.
3. Process over content. Lift the workflow (pre-task ritual, 6-gate review, contract-first, parallel conflict prevention, design-first, live mini-retro) — not the specific lessons. Per-project lessons land in the consumer's brain-hot.md under ## Project-specific rules.
4. Skill SKILL.md headers must include name, description, and ## Token budget. No skill without a budget section. The description must be trigger/symptom-based (CSO), not a workflow summary — lead with the user phrases / slash-commands / failure symptoms that should auto-load it. The ## Token budget exists because context is a finite, degrading resource — a skill should deliver "the smallest set of high-signal tokens" (Anthropic): keep SKILL.md lean, split rarely-co-used material into references/ (progressive disclosure), and mark each script execute-vs-read. Full guide: core/docs/setup/skill-authoring.md (also shipped to projects); maintainer notes in CONTRIBUTING.md "Improving a skill".
5. Each agent file MUST reference agent-pre-task-ritual.md and brain-hot.md as mandatory reads in its body — that's the contract between orchestrator and subagent.
6. Never write or run code in core/.claude/memory/ — that folder is shipped empty (with a README explaining the in-repo Brain fallback). Same for core/docs/project/sprints/.gitkeep and retros/.gitkeep.
7. Document every change — always. No change to core/, presets/, install.sh, or this repo's docs lands without a written record of what changed, why, and how it makes the template better. Three places, every time:
   • CHANGELOG.md — an ## Unreleased entry (Added / Changed / Fixed / Removed) with the why + upgrade impact.
   • The doc the change lives in — the rule/skill/doc itself must explain its own rationale (a > Why this exists line or section), so a future reader understands intent without git archaeology.
   • If research-driven — close the loop in docs/research/: the synthesis/ note states the evidence + expected improvement, and the change graduates apply/proposed/ → apply/shipped/ with the INDEX scoreboard row. This is how we know research actually improved the template, not just accumulated. A change you can't explain the why and how-it's-better for isn't ready to ship.