Skip to content

docs: canonical development flow, HEADY.md, and daily agent context pack#222

Open
HeadyMe wants to merge 12 commits into
mainfrom
claude/artifact-creation-criteria-b8kmsf
Open

docs: canonical development flow, HEADY.md, and daily agent context pack#222
HeadyMe wants to merge 12 commits into
mainfrom
claude/artifact-creation-criteria-b8kmsf

Conversation

@HeadyMe

@HeadyMe HeadyMe commented Jun 19, 2026

Copy link
Copy Markdown
Member

Why

The dev flow was defined but not discoverable: it lived in docs/REPO_ROLES.md and docs/REPO_LANDSCAPE.md, which (1) weren't referenced from CLAUDE.md — the file every agent reads on boot, (2) contradicted each other, and (3) had drifted from the live repos. So no agent was ever guided toward it. This PR wires the flow into the boot files, reconciles the conflict, and makes the whole thing self-maintaining.

What changed

Authoritative flow

  • docs/DEVELOPMENT_FLOW.md — single source of truth for repo roles (source-of-truth / staging / production / product / docs / sandbox), branching model, PR/merge, and promotion. Declares HeadySystems/heady-ai as the platform source of truth.
  • docs/REPO_ROLES.md + docs/REPO_LANDSCAPE.md — marked SUPERSEDED with banners pointing at the new doc.

Two boot files, permanently in sync

  • HEADY.md (new) — Heady-native instructions governing all Heady agents, mirroring CLAUDE.md. Section 0 is the permanent sync rule: any shared-convention change applies to both files in the same change. Customizing Claude benefits the whole Heady system.
  • CLAUDE.md — added DEVELOPMENT FLOW + ARTIFACT CREATION CRITERIA sections and the sync rule, so agents are guided from the entry point.

Daily-fresh context pack

  • docs/AGENT_CONTEXT_PACK.md — the optimal single bundle to feed any agent at task start (identity, source of truth, flow, rules, meta-rules). Has a DAILY_REFRESH block that's regenerated daily.
  • scripts/refresh-agent-context.mjs — idempotent generator (--check doubles as a CI staleness gate); pulls live state from package.json, git, and HEADY_CONTEXT.md.
  • .github/workflows/agent-context-refresh.yml — daily cron (06:00 UTC) regenerates and auto-commits the pack.

Enforcement

  • .claude/hooks/heady-sync-check.sh + a PostToolUse hook in .claude/settings.json — when CLAUDE.md is edited, the agent is reminded to propagate to HEADY.md and regenerate the pack. Committed to the repo so it travels with every clone.

Verification

  • scripts/refresh-agent-context.mjs runs and stamps the block; --check reports current.
  • .claude/settings.json validated as JSON.
  • Hook tested against CLAUDE.md (emits reminder) and a non-matching path (no-op).

🤖 Generated with Claude Code

https://claude.ai/code/session_018ekBf2Tvqg9UnocbnvDYgg

Generated by Claude Code

claude added 12 commits June 19, 2026 02:03
@claude
docs: codify canonical dev flow, HEADY.md, and daily agent context pack
8a6feca 
Make the Heady development flow discoverable and enforced from the boot files,
and establish a permanent CLAUDE.md <-> HEADY.md sync so customizing Claude
benefits the whole Heady system.

- docs/DEVELOPMENT_FLOW.md: authoritative repo roles + branching + promotion;
  declares HeadySystems/heady-ai as source of truth; supersedes REPO_ROLES.md
  and REPO_LANDSCAPE.md (both now carry superseded banners).
- HEADY.md: Heady-native agent instructions for all agents, with the permanent
  HEADY.md <-> CLAUDE.md sync rule (section 0).
- CLAUDE.md: wired in DEVELOPMENT FLOW + ARTIFACT CREATION CRITERIA sections and
  the sync rule, so agents are guided to the flow from the entry point.
- docs/AGENT_CONTEXT_PACK.md: single daily-fresh bootstrap bundle for any agent.
- scripts/refresh-agent-context.mjs: idempotent generator (+ --check CI gate).
- .github/workflows/agent-context-refresh.yml: daily regeneration + auto-commit.
- .claude/hooks/heady-sync-check.sh + settings.json PostToolUse hook: reminds
  to propagate CLAUDE.md changes to HEADY.md and regenerate the pack.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018ekBf2Tvqg9UnocbnvDYgg
@claude
docs: add evidence-based repo inventory and archive assessment
e418692 
Companion to DEVELOPMENT_FLOW.md. Per-repo functionality assessment with
keep/verify/archive recommendations based on activity, file counts, and
structure. Flags Heady-Main-ddb9351d (redundant duplicate) and headydocs
(empty shell) as archive candidates pending deploy-wiring confirmation.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018ekBf2Tvqg9UnocbnvDYgg
@claude
docs: standardize agent stop-notice as an archive step
0ba9021 
Require CLAUDE.md/AGENTS.md stop-notices on every soft-archived repo.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018ekBf2Tvqg9UnocbnvDYgg
@claude
docs: add system audit + remediation plan; harden gitignore (S1)
732bc07 
Evidence-based audit isolating functional/connected services (37 CF workers,
1 Vercel project, 19 Sentry projects) from legacy/redundant artifacts. Buckets
files/services into keep/archive/eliminate with a staged execution plan;
destructive stages gated on owner confirmation. S1 (preventive .gitignore for
zips/_downloads/binary-docs/dupes) applied — no tracked files removed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018ekBf2Tvqg9UnocbnvDYgg
@claude
chore: execute audit file cleanup S2-S5 (untrack binaries, dedup, con…
b7677f0 
…solidate status)

S2: untrack 254 .zip build bundles + _downloads/ scratch (kept locally).
S4: untrack 181 .docx/.pdf binaries (move to object storage out-of-band).
S3: content-hash dedup of (1)/(2) files — removed only byte-identical twins;
    kept 21 unique-content files for manual review (no blind deletion).
S5: consolidated scattered status/report dumps into docs/STATUS.md; removed 14
    transient root dumps (refs were CSV inventories / regenerating scripts, not
    structural deps; none in heady-registry.json) and git-ignored regenerated ones.

Net: 646 files untracked, source code untouched. History bytes remain (purge planned
separately). See docs/SYSTEM_AUDIT_AND_REMEDIATION_PLAN.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018ekBf2Tvqg9UnocbnvDYgg
@claude
docs: worker consolidation proposal + staged history-purge script
0ccfbf2 
Record the Cloudflare worker consolidation proposal (survivors vs retire) and the
MCP tooling limitation (no route/delete tools -> elimination needs wrangler/dashboard).
Add scripts/history-purge.sh: guarded, dry-run-by-default git history rewrite for
S-HIST size reclamation; never auto-executes (requires --execute + explicit env confirm).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018ekBf2Tvqg9UnocbnvDYgg
@claude
docs: correct worker consolidation — code review shows routers are no…
18d05d9 
…t duplicates

Inspecting worker code (workers_get_worker_code) disproved the naming-based
duplicate assumption: heady-intent-router is a live multi-domain site server,
not a redundant router. Mark worker elimination as hands-on review only (do not
delete on naming evidence); MCP cannot list routes or delete workers.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018ekBf2Tvqg9UnocbnvDYgg
@claude
security: untrack 4 committed GCP service-account keys + document rot…
a7ff788 
…ation

Audit found live GCP SA keys (real private_key material) tracked at
configs/secrets/gen-lang-client-*.json. Untracked via git rm --cached (path
already gitignored; local copies retained). Keys remain in history and MUST be
rotated in GCP console. Verified design_*.pem and cloudflare-credentials.md are
not raw secrets (left tracked). See docs/SYSTEM_AUDIT_AND_REMEDIATION_PLAN.md §8a.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018ekBf2Tvqg9UnocbnvDYgg
@claude
feat: Human Understanding & Flow Protocol (trigger hook + convention)
d62ada5 
Encode how to calibrate to the user's cognitive state across CLAUDE.md, HEADY.md,
and the agent context pack, plus a UserPromptSubmit hook:
- Silence is ambiguous (flow/thought-wave, not necessarily a gap) — add energy, don't dam.
- Explicit triggers are the only interrupts: probe (okay so/wait/...) -> deep grounded
  explanation; alarm (wtf/makes no sense) -> full stop, ground-up diagnosis.
- Diagnose the root to a comfortable level (depth = comfort, not exhaustiveness).
- Grounding/anti-hallucination always: separate verified vs inferred vs guessed.
- Name unknowables/immaterial so the user can let them go.
- Recommendations are droppable, not deleted: no nagging in the moment; a single
  well-timed, lightly-cute callback later is welcome.

Bound CLAUDE.md <-> HEADY.md per the sync rule; hook wired in .claude/settings.json.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018ekBf2Tvqg9UnocbnvDYgg
@claude
fix: cue-triggered recommendation resurfacing (not 'cute' / not time-…
b2baf32 
…based)

Correct the flow protocol: a dropped recommendation is kept and repeated later when a
CUE makes it relevant again (topic recurs, user exits flow, related blocker, or they
ask) — cue-triggered, never time-based nagging. Synced across CLAUDE.md, HEADY.md, the
context pack, and the understanding-workflow hook.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018ekBf2Tvqg9UnocbnvDYgg
@claude
feat: tone-as-hallucination-vector — pre-label epistemic status
42dfebc 
Strengthen the grounding rule: it's not enough to flag when wrong; confident
teacher-tone can launder an improvised riff into perceived established fact. Require
pre-labeling epistemic status in the moment ('riffing' vs 'grounded/retrieved'). The
user's high trust amplifies the risk, so the labeling duty is greater for a trusted
source. Don't make the user run a 'wait, is that real?' check. Synced across CLAUDE.md,
HEADY.md, context pack, and the understanding-workflow hook.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018ekBf2Tvqg9UnocbnvDYgg
@claude
refine: epistemic labeling timing is flexible, guarantee is firm
e911513 
Correct the just-added rule: labeling serious-vs-riff does NOT have to be in the
moment (that would kill the joke). A riff may breathe, but it must never be left
ambiguously taken as real — the user must find out at some point (after the fact is
fine). Timing flexible, guarantee firm. Synced across CLAUDE.md, HEADY.md, context
pack, and the understanding-workflow hook.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018ekBf2Tvqg9UnocbnvDYgg
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@HeadyMe @claude