Skip to content

INSTALL.md

Latest commit

 

History

History
215 lines (166 loc) · 10.3 KB

INSTALL.md

File metadata and controls

215 lines (166 loc) · 10.3 KB
Raw

INSTALL — AI Agent Instructions

Read this file FIRST. Follow phases in order. Do NOT skip phases. Each phase builds on the previous one.

Overview

You are installing an Obsidian-compatible documentation system into this repository. You will:

  1. Analyze the repo (do NOT assume anything)
  2. Design a doc tree tailored to this specific codebase
  3. Implement docs, hub, stable rules, and decisions log
  4. Optimize links in CLAUDE.md and docs/ for graph cleanliness and token efficiency
  5. Clean up installer artifacts and obsolete files (optional, user-approved)

Hybrid Operating Model (mandatory)

Execute all work with this model:

  • Installer core (required): keep phase order, approval gates, stable rules separation, migration safety, and validation checklists
  • Inspired layer (recommended): create small focused docs, preserve meaningful cross-links, keep docs as living knowledge, and write context/rationale first

Do not treat the inspired layer as a replacement for installer core requirements.

Constraints

  • Do NOT create empty placeholder files — every doc must have real content
  • Do NOT duplicate information — link to existing docs instead of copying
  • Do NOT hardcode assumptions — analyze the repo to discover its structure
  • Do NOT skip human approval — present your design before implementing
  • Do NOT overwrite existing docs unless the human explicitly approves
  • Do NOT mix stable rules into CLAUDE.md — keep stable rules in ./.claude/rules/
  • Do NOT create low-signal doc sprawl — every new doc must have clear value and maintenance intent
  • Do NOT replace rationale with file summaries — capture why/tradeoffs, not only where code lives

Installation Mode (required)

Choose one mode before Phase 2 and include it in the design proposal.

Mode: strict (full-standard structure)

  • Create the standard category structure from [[README]]: project, architecture, features, integrations, build, testing, reference
  • Create at least one real-content doc in each category, or explicitly link existing docs that satisfy the category
  • Use this mode when the human expects the full standardized structure

Mode: adaptive

  • Keep the current behavior from [[PRINCIPLES]]: create only categories justified by the repo analysis
  • Skip non-applicable categories
  • Use this mode when minimal, structure-following documentation is preferred

If the human does not specify a mode, default to strict.

Phase Sequence

Phase File Description
1: ANALYZE [[PHASES/01-analyze]] Explore repo structure, identify key folders, subsystems, entry points
2: DESIGN [[PHASES/02-design]] Propose doc tree, CLAUDE.md outline, migration plan
3: IMPLEMENT [[PHASES/03-implement]] Create docs, write content, add links, set up hub, stable rules, and decisions log
4: OPTIMIZE LINKS [[PHASES/04-optimize-links]] Final link-quality pass: remove duplicate/valueless links, keep graph clean
5: CLEANUP [[PHASES/05-cleanup]] Remove installer artifacts and obsolete files (after human approval)

How to Execute

  1. Read [[PRINCIPLES]] to understand the design philosophy
  2. Read [[PHASES/01-analyze]] and execute it fully
  3. Present your analysis to the human, wait for acknowledgment
  4. Read [[PHASES/02-design]] and execute it fully
  5. Present your proposed doc tree to the human, wait for approval
  6. Read [[PHASES/03-implement]] and execute it fully
  7. Ensure decisions.md is updated with notable design choices from Phase 3
  8. Present the result for final review
  9. Read [[PHASES/04-optimize-links]] and run the link optimization pass
  10. Read [[PHASES/05-cleanup]] and execute it after human approves the review

Hybrid Practicality Gate (apply in every phase)

Before moving to the next phase, verify:

  1. Systematic: required phase outputs and checks are complete
  2. Flexible: chosen docs reflect repo reality, not template pressure
  3. Signal over volume: no unnecessary doc proliferation
  4. Rationale present: important docs include context/decision reasoning

Templates

Use files in [[TEMPLATES/]] as structure guides. Each template defines:

  • What sections a doc type should have
  • What questions it should answer
  • How it should link to other docs
Template Purpose
[[TEMPLATES/architecture-doc]] Structural patterns and subsystem design
[[TEMPLATES/build-doc]] Build process, packaging, release
[[TEMPLATES/feature-doc]] User-facing feature workflows
[[TEMPLATES/hub-claude-md]] CLAUDE.md hub structure
[[TEMPLATES/index-doc]] Documentation navigation hub
[[TEMPLATES/integration-doc]] External tools and libraries
[[TEMPLATES/migration-map]] Section-by-section migration mapping (AGENTS.md and other docs)
[[TEMPLATES/project-doc]] Project-level knowledge
[[TEMPLATES/reference-doc]] Config, constants, conventions
[[TEMPLATES/testing-doc]] Testing strategy and conventions

Templates are NOT pre-filled content. You must fill them with real information from the repo.

Completion Checklist

High-level verification — see [[PHASES/03-implement]] for the full detailed checklist.

  • All approved docs created with real content
  • CLAUDE.md and docs/_index.md created as hubs
  • Stable rules created/updated in ./.claude/rules/
  • decisions.md created/updated with key design decisions
  • Mode requirements satisfied (strict full standard categories OR adaptive justified subset)
  • Wiki links connect related docs
  • AGENTS.md migration coverage is 100% (if AGENTS.md exists)
  • No critical information from AGENTS.md is lost
  • No empty placeholder files or hardcoded assumptions
  • Link optimization completed for CLAUDE.md + docs/ (duplicate/valueless links removed)
  • Cleanup completed (installer and obsolete files removed or preserved per user choice)
  • Hybrid practicality gate passed at each phase (systematic + flexible + high-signal + rationale-first)

Definition of Done

Installation is complete only when all of the following are true:

  1. CLAUDE.md exists and is usable as the project hub
  2. docs/_index.md exists and links to the full documentation set
  3. Stable rules exist in ./.claude/rules/ and are referenced by CLAUDE.md
  4. decisions.md exists for persistent design rationale
  5. Core docs exist per selected mode:
    • strict: all standard categories from [[README]] are represented
    • adaptive: only analysis-justified categories are present (with rationale in Phase 2 output)
  6. If AGENTS.md exists, all meaningful sections are mapped and migrated with evidence
  7. Final link optimization pass completed on CLAUDE.md + docs/
  8. Cleanup completed (installer and obsolete files removed or preserved per user choice)
  9. Post-install validation checklist is complete with no unresolved critical failures
  10. Hybrid model is respected: installer core preserved and inspired layer applied without drift
  11. updating-docs skill installed at ./.claude/skills/updating-docs/SKILL.md and referenced by CLAUDE.md Read First

Post-Install Validation (mandatory)

Run this checklist before closing the installation:

  • CLAUDE.md exists and links to [[docs/_index]]
  • CLAUDE.md includes an authoritative directory tree
  • docs/_index.md links to every created doc
  • Every created doc has real content (no placeholders)
  • Every created doc has at least 2 useful related links
  • No broken wiki links to missing files
  • Selected mode validation passed (strict or adaptive)
  • Stable rules are placed in ./.claude/rules/ (not mixed into CLAUDE.md)
  • updating-docs skill installed at ./.claude/skills/updating-docs/SKILL.md
  • updating-docs skill referenced by CLAUDE.md Read First section
  • decisions.md records key design choices
  • Verification command for affected stack passed (tsc --noEmit for TypeScript repos)
  • Work was committed in issue-scoped chunks
  • CLAUDE.md was updated at end of session
  • AGENTS.md migration coverage report included (if AGENTS.md exists)
  • Duplicate/valueless wiki links were removed from CLAUDE.md and docs/
  • Cleanup decisions were human-approved item by item
  • Link graph remains navigable and hub docs are still connected
  • No low-signal doc sprawl or duplicate-topic docs were introduced
  • Key docs include context/rationale where code alone is insufficient

Troubleshooting & Edge Cases

Repo has no clear structure

If the repo is a single-file project or lacks identifiable directories:

  • Create a minimal doc tree: CLAUDE.md + docs/_index.md + docs/project/overview.md
  • Skip categories that don't apply (no architecture doc if there's no architecture)

Repo already has CLAUDE.md

  • Read the existing CLAUDE.md first
  • Preserve its content — merge with the new structure rather than overwriting
  • Add the Documentation Map and Doc Workflow sections if missing
  • Present the merge plan to the human for approval

Phase 1 analysis is incomplete

  • Report what you could and could not determine
  • Mark uncertain findings explicitly
  • Proceed with what you know — the human can fill gaps during the approval step

Repo uses a non-standard language/framework

  • Identify entry points based on the framework's conventions
  • Note the unfamiliar stack in your analysis
  • Use the generic [[PRINCIPLES]] guidelines — they apply to any stack

Existing docs conflict with proposed structure

  • Never delete existing docs without human approval
  • Link existing docs from the new navigation hub
  • Propose a migration plan in Phase 2

AGENTS.md exists but migration is incomplete

  • Do NOT proceed to Phase 3 until every meaningful AGENTS.md section is mapped to a destination
  • Use [[TEMPLATES/migration-map]] to track section-level coverage
  • Mark unknown or risky mappings explicitly and escalate to the human

Related

  • [[README]] — Project overview and usage guide
  • [[PRINCIPLES]] — Design philosophy that governs all decisions
  • [[CONTRIBUTING]] — How to contribute changes
  • [[CHANGELOG]] — Version history
  • [[.claude/skills/updating-docs]] — Generic doc-update skill shipped with this installer

Start by reading [[PRINCIPLES]], then [[PHASES/01-analyze]].