A complete AI-powered documentation system that keeps docs, issues, and code in sync. Built with Claude Code, GitHub Actions, and Linear.
Contributor edits docs
│
▼
┌─────────────────────────┐
│ analyze-doc-changes │ AI reads diffs, groups semantically,
│ (push to main) │ creates/updates Linear issues
└────────────┬────────────┘
│
▼
Linear Issues
(natural requirements)
│
▼
┌─────────────────────────┐
│ Developer implements │ Picks up issue, writes code,
│ (your dev workflow) │ completes the feature
└────────────┬────────────┘
│
▼
┌─────────────────────────┐
│ consolidate-docs │ AI reads source material,
│ (PR trigger) │ updates docs, cleans up tracking
└────────────┬────────────┘
│
▼
Docs are up to date
Tracking files cleaned
Loop complete
.claude/
├── agents/
│ ├── docs-consolidator.md # Merges source material into docs
│ └── docs-change-analyzer.md # Analyzes doc edits, creates issues
├── skills/
│ ├── consolidate-docs/SKILL.md # /consolidate-docs skill
│ └── analyze-doc-changes/SKILL.md # /analyze-doc-changes skill
.github/workflows/
├── consolidate-docs.yml # Runs on PR with source changes
└── analyze-doc-changes.yml # Runs on push to main with doc changes
docs/
├── INDEX.md # Machine-readable file registry
└── .changes/ # Tracking files (auto-managed)
└── .gitkeep
Search all files for {{PLACEHOLDER}} patterns and replace with your values:
| Placeholder | Description | Example |
|---|---|---|
{{TEAM_KEY}} |
Linear team key (short) | ENG |
{{PROJECT_ID}} |
Linear project ID for auto-created issues | 239a2aed-... |
{{PROJECT_NAME}} |
Linear project name | My Project: Auto Issues |
{{LABEL_NAME}} |
Linear label for auto-created issues | Automatic |
{{SOURCE_DIR}} |
Directory that triggers consolidation on PR | features, design/completed |
{{DOCS_DIR}} |
Root documentation directory | docs |
{{DOC_BRANCHES}} |
Your documentation branches (see below) | — |
Adapt docs/INDEX.md to your project's documentation structure. The template uses a three-branch layout — adjust to fit your needs:
{{DOCS_DIR}}/
├── INDEX.md # Required — the AI reads this first
├── .changes/ # Required — tracking files live here
│ └── .gitkeep
│
│ -- Define your own branches below --
│
├── technical/ # Example: developer docs
│ ├── architecture/
│ ├── systems/
│ └── contracts/
├── design/ # Example: design docs
│ ├── mechanics/
│ └── schemas/
└── user/ # Example: end-user docs
Add these secrets in your repo (Settings → Secrets → Actions):
| Secret | Description | How to get it |
|---|---|---|
CLAUDE_CODE_OAUTH_TOKEN |
Claude Code authentication | Run claude setup-token and copy the token |
LINEAR_API_KEY |
Linear API key | Linear → Settings → Account → API → Create key |
Create the following in Linear before using:
- A project for auto-created issues (note its ID for
{{PROJECT_ID}}) - A label called
{{LABEL_NAME}}(e.g. "Automatic")
Copy the .claude/ and .github/ directories into your repo root. Copy docs/INDEX.md and docs/.changes/.gitkeep into your docs directory.
The agent files (.claude/agents/) contain detailed instructions. Review and adjust:
- Language rules — the template defaults to English; change if your docs are multilingual
- Issue writing style — adjust the tone to match your team's culture
- Grouping heuristics — the analyzer groups changes by semantic topic; add domain-specific hints if needed
When someone edits docs and pushes to main:
- AI reads the actual diffs (not just file names)
- Reads existing tracking files in
docs/.changes/ - Semantically groups changes by topic
- Creates Linear issues that read like natural requirements
- Writes tracking files with full context for future runs
Key behaviors:
- Same topic edited again → existing issue updated (description rewritten, comment added)
- Unrelated changes in one commit → separate issues
- Related changes across files → one issue
- Whitespace/cosmetic changes → ignored
When source material is ready and a PR is created:
- AI reads
docs/INDEX.mdto understand the structure - Reads the source material (feature docs, design notes, technical writeups)
- Extracts permanent reference information, skips process artifacts
- Updates relevant documentation files
- Updates INDEX.md Sources columns
- Cleans up tracking files for completed Linear issues
docs/.changes/*.yaml files bridge the two workflows:
linear_issue: ENG-42
title: "Descriptive issue title"
context: |
Detailed description of what this topic is about.
Used by the AI to determine if future changes belong here.
files:
- docs/design/mechanics.md
- docs/technical/systems/engine.md
changes:
- date: "2025-01-15"
commit: abc1234
diff_summary: "What changed in this commit"- Created by analyze-doc-changes when a new topic is detected
- Updated when the same topic is edited again
- Deleted by consolidate-docs when the Linear issue is Done/Canceled
# Analyze last commit's doc changes
/analyze-doc-changes
# Analyze a specific range
/analyze-doc-changes HEAD~5..HEAD
# Consolidate source material into docs
/consolidate-docs path/to/feature-doc/
/consolidate-docs path/to/design-notes.md- analyze-doc-changes: Triggers on push to main when
docs/changes (excludes bot commits and tracking files) - consolidate-docs: Triggers on PR when
{{SOURCE_DIR}}/changes
| Dependency | Purpose | Install |
|---|---|---|
| Claude Code | AI agent runtime (CLI + OAuth token) | curl -fsSL https://claude.ai/install.sh | bash |
| Linear | Issue tracking (account + API key) | Sign up at linear.app |
| linear-cli | Linear API from the command line (Rust) | cargo install linear-cli |
| GitHub Actions | CI/CD for automated workflows | Enabled by default on GitHub repos |
Note: linear-cli is installed locally for the /analyze-doc-changes and /consolidate-docs skills. The CI workflow installs it automatically (with cargo caching for fast subsequent runs).
Instead of replacing placeholders manually, copy the prompt below into Claude Code (or any AI assistant) and answer the questions. It will fill in all placeholders and generate your customized files.
Click to expand the setup prompt
I need you to customize the Living Documentation Workflow template for my project.
All template files are in the current directory (or I'll paste them).
Ask me the following questions one at a time, then replace ALL placeholders
across all template files with my answers.
## Questions
1. **What is your documentation directory?**
(Where your docs live, e.g. `docs`, `documentation`, `wiki`)
→ fills {{DOCS_DIR}}
2. **What directory triggers doc consolidation on PR?**
(e.g. a feature docs folder, design notes, completed specs — any directory
whose changes should be merged into the living docs when a PR is created)
→ fills {{SOURCE_DIR}}
3. **What is your Linear team key?**
(The short prefix on your issue IDs, e.g. `ENG`, `PRO`, `ACME`)
→ fills {{TEAM_KEY}}
4. **What is the Linear project name and ID for auto-created issues?**
(Run: linear-cli projects list --output ndjson --fields name)
(Pick one or create a new project in Linear for auto-created issues)
→ fills {{PROJECT_ID}} and {{PROJECT_NAME}}
5. **What label should auto-created issues get?**
(e.g. "Automatic", "Docs Change", "Design Request")
(Run: linear-cli labels list --output ndjson — to see existing labels)
→ fills {{LABEL_NAME}}
6. **Describe your documentation structure.**
(What branches/directories do you have? e.g. "technical docs for devs,
design docs for designers, user guides for customers")
→ fills {{DOC_BRANCHES}}, {{STRUCTURE}}, and generates your INDEX.md
7. **What languages do your docs use?**
(e.g. "All English", "Technical in English, user docs in Spanish",
"English with Japanese game terms kept as-is")
→ fills {{WRITING_GUIDELINES}} and {{ISSUE_LANGUAGE}}
8. **Describe your team and who edits docs.**
(e.g. "I'm the only dev, my co-founder edits design docs",
"Design team edits specs, engineering implements")
→ fills {{CONTRIBUTOR_CONTEXT}}
9. **List your main documentation topics and which files they map to.**
(e.g. "Auth system → technical/systems/auth.md, API changes → technical/api.md")
→ fills {{ROUTING_GUIDE}} and {{FILE_REGISTRY}}
## After all questions are answered
1. Replace every {{PLACEHOLDER}} in every file with the actual values.
2. For block-level placeholders ({{WRITING_GUIDELINES}}, {{STRUCTURE}}, etc.),
remove the placeholder markers and the example text — write the real content.
3. Generate a complete INDEX.md with the file registry tables and routing guide.
4. Show me a summary of all files modified and the values used.