hyper-document

name	hyper-document
description	Updates all project documentation after code or skill changes. Always reads actual implementation before writing. Covers README, CHANGELOG, docs/, AGENTS.md, memory files, and skills-info.md. Use after completing any feature, fix, refactor, or skill update.
trigger	/hyper-document

Hyper-Document

This skill updates the full documentation suite after changes to the codebase, skills, or framework structure. It reads actual implementation before writing anything — existing documentation is treated as potentially stale.

---

When to use this skill

• After completing a feature, bug fix, refactor, or skill change.
• When README.md, CHANGELOG.md, docs/, or other docs are out of sync with the codebase.
• When the user explicitly runs /hyper-document.

---

Step 1 — Identify What Changed

Run the following to understand scope:

git log --oneline -10
git diff HEAD~1 --name-only

Identify:

• Which files were modified, added, or deleted.
• Whether the change is user-facing (affects README, CHANGELOG, docs) or internal (affects memory files, skills-info).
• Whether any skills were added, renamed, or removed.

---

Step 2 — Read Before Writing

CRITICAL: Do NOT trust existing documentation. Read the actual implementation.

• Read every changed file before updating any doc.
• Note discrepancies between existing docs and actual behavior.
• Never assume — verify.

---

Step 3 — Update Documentation by Target

Work through each target below. Skip targets that are clearly unaffected by the change.

---

README.md

Purpose: Entry point for new users and project overview.

Update when: Architecture changes, new features, new IDE support, install/uninstall changes, workflow changes, new slash commands, or directory structure changes.

Style rules:

• Lead with what it does, not how it works.
• Use H2 (##) for top-level sections, H3 (###) for subsections.
• Prefer tables for structured comparisons (IDE support, installed paths, commands).
• Use fenced code blocks with language tags for all commands and examples.
• Bullet lists for feature enumerations; numbered lists for sequential steps only.
• No marketing language. No "powerful", "robust", "seamless".
• Every slash command mentioned must use the hyper- prefix (e.g. /hyper-architect).
• Callout blocks (> **Note:**) for caveats, naming conventions, and non-obvious behaviors.

Before writing: Read the current README.md fully. Identify which sections are affected by the change. Do not rewrite unaffected sections.

Section checklist (verify each section matches current state):

Section	Update when
Core Architectural Pillars	New architectural mechanism added; existing pillar changes scope
Directory Structure	Directories added, removed, or renamed
Deterministic Tooling	New scripts added to .agents/scripts/; existing tools renamed or removed
Standard Operating Procedure	Workflow phases change; new phase added; new mandatory commands
AI Agent Integrations / slash commands	Skills added, renamed, or removed; new IDE support added
Setup / Installation	Install or uninstall behavior changes
Troubleshooting	New failure mode introduced; existing workaround changes
Roadmap	Completed items checked off; new items added

Adding a new H2 section: Only for features that introduce a distinct user-facing capability that doesn't fit under an existing section. Examples: "Token Efficiency & Cost Optimization", "Multi-IDE Support". Do not create a new H2 for routine bugfixes or small enhancements.

---

CHANGELOG.md

Purpose: Auditable history of changes following Keep a Changelog.

Find the current version: Check the most recent ## [X.Y.Z] header in CHANGELOG.md. That is the current released version. ## [Unreleased] entries are pending release.

CRITICAL: Before modifying, use AskUserQuestion:

Are we releasing a new version with this change?

- Option A: Yes — bump version (specify the new semantic version via Other)
- Option B: No — update [Unreleased] only (add changes to the Unreleased section)

Then:

• Version bump: Add a new ## [X.Y.Z] - YYYY-MM-DD block below ## [Unreleased].
• No version bump: Add entries under ## [Unreleased].

Style rules:

• Use only these categories: Added, Changed, Fixed, Removed, Security.
• One bullet per logical change. Bold the affected component: - **hyper-audit**: ...
• Use changelog-style verbs (past participial): "Added", "Fixed", "Moved", not present tense "Adds", "Fixes", "Moves".
• Be specific — name the file, skill, or behavior. No vague entries like "misc improvements".
• Never delete historical entries.

Example entry:

## [0.4.0] - 2026-05-03

### Added
- **`model_router.py`**: Routes skills to optimal Claude model tier based on META.yml metadata.
- **`hyper-clear` skill**: Idempotent context flushing at end of `/hyper-audit`.

### Changed
- **`hyper-execute` skill**: Routes to Haiku by default; logs token usage per execution.
- **`CLAUDE.md`**: Added Schema Definitions section; deprecated `.agents/schemas/` files.

### Removed
- **`.agents/schemas/` files**: Marked deprecated; will be deleted after 2026-06-17.

---

docs/ — route before you write

This project splits docs/ by audience, and the root is closed. Decide which side your file lands on before writing it.

What you are writing	Where it goes
How the shipped software behaves	one of the four product docs at the docs/ root
What this session measured, tried, or refuted	docs/agentic-notes/<release>/

Product docs — the complete allowlist: README.md, OPTIMIZERS.md, GENERATION_PIPELINE.md, KNOWN_LIMITATIONS.md. Update these in place. Do not create a fifth file at the docs/ root — a pre-commit guard (tools/check_docs_layout.sh) rejects it, and adding one needs maintainer sign-off.

Notes: measurement reports, sweep results, A/B outcomes, per-lane write-ups, refuted hypotheses, status snapshots. <release> is the release the work is for, not the one that was current when you started — create docs/agentic-notes/v0.4.7/ rather than reusing the newest existing folder. Add a row to docs/agentic-notes/README.md whenever you create a new folder.

A note never graduates by being moved. When a finding becomes something a user needs, write it into the product doc in the user's language and leave the note in place as the evidence trail.

Full rule: .agents/rules/docs-layout.md.

---

Standard Repository Documents

(CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, DEVELOPMENT.md, CITATION.cff)

Purpose: Provide consistent community, security, and development guidelines across all Hypergraph framework projects.

Update when: The framework's core policies change, testing requirements change (affecting DEVELOPMENT.md or CONTRIBUTING.md), or project authors/metadata change.

Style rules:

• These files should largely remain stable once scaffolded via /hyper-init.
• If a project-specific modification is required, ensure it doesn't violate the baseline rules established in the .agents/schemas/project-templates/ directory.
• When regenerating these files, always refer to .agents/schemas/project-templates/ as the ground truth format and apply variable substitution.

---

AGENTS.md

Purpose: Universal cross-IDE always-on manifest. Read by Windsurf, Cursor, Roo Code, GitHub Copilot, Zed.

Update when: Skills are added/renamed/removed, system mandates change, or the directory structure changes.

Style rules:

• Skills table must stay in sync with .agents/skills/hyper-*/ — one row per skill.
• Trigger column must use exact slash command with hyper- prefix.
• Directory references must use actual current paths.
• Mandates must be actionable rules, not suggestions.

---

.agents/memory/ files

Purpose: Agent-facing project context (activeContext, productContext, systemPatterns).

Update when: Core project goals, active work, or architectural patterns change.

Files:

• activeContext.md — current sprint focus, active MiniPRDs, recent decisions.
• productContext.md — what the product is, who it's for, core value proposition.
• systemPatterns.md — recurring architectural patterns, conventions, anti-patterns.

Style rules:

• Written for an agent reading cold — no assumed context.
• Short, factual, structured with headers.
• Timestamp significant updates.

---

skills-info.md

Purpose: Human-readable index of all available skills and their purpose.

Update when: Skills are added, renamed, removed, or their descriptions change.

Style rules:

• One entry per skill: name, trigger, one-line description.
• Keep aligned with actual SKILL.md frontmatter descriptions.
• Organized by workflow phase where applicable.

---

Step 4 — Style Rules (All Files)

Rule	Detail
Accurate	Verified against actual code, not assumed
Concise	Cut filler words; prefer short sentences
Current	Matches the implementation as of this change
No fluff	No "powerful", "robust", "seamlessly", "leverages"
Slash commands	Always hyper- prefixed
Paths	Always reflect actual current directory structure

---

Step 5 — Ask if Uncertain

If the intent behind a change or its user-facing impact is unclear, ask the user before writing. Never guess.