author	date	version	sources
Coty Beasley	dec-2025	1.5.0	Large Language Models in Bio-Ontology Research https://pmc.ncbi.nlm.nih.gov/articles/PMC12649945/ Ontology enrichment using a large language model https://www.sciencedirect.com/science/article/pii/S1532046425000942 Hard-Coding Truth into LLMs via Ontologies https://ceur-ws.org/Vol-4079/paper10.pdf

Project Bootstrap Plan: Claude Code + Encapsulated Worktrees

Executive Summary

This document describes how to bootstrap a Claude Code–optimized project that integrates knowledge management, agentic workflows, and development practices, while supporting multiple encapsulated git worktrees running in parallel. The root repository acts as a stable template and shared knowledge spine. Each worktree owns its own plans, progress logs, and session handoffs, so branches can be created, updated, resumed, and cleaned up without collisions.

It also defines how to handle Architecture Decision Records (ADRs), research/plan/implement structures, and design decisions so that short-lived branch context can be promoted into long-lived project knowledge.

---

Core Principles

1. Root Repo as Template and Shared Knowledge

The default clone (main worktree) contains:

• Global, long-lived project instructions:
  • CLAUDE.md – how Claude should work in this repo.
  • README.md – human overview and setup.
• Shared, relatively stable structures:
  • knowledge-base/** – domain ontologies and research.
  • guides/** – methodology and standards.
  • workflows/** – reusable process definitions.
  • mcp-servers/** – shared tooling.
  • schemas/** – validation contracts.
  • manifest.toon – master registry.
  • .claude/** – agent tooling, hooks, and commands.
  • docs/** – ADRs and cross-cutting design decisions (see below).

These are not used as per-branch scratchpads.

2. Per-Worktree Encapsulated State

Every feature/task/report branch lives in its own worktree directory and carries:

• PLAN.local.md – branch-specific plan.
• IMPLEMENTATION.local.md – branch-specific implementation details.
• SESSION.md – current session/handoff document.
• .session/** – internal, branch-only state (notes, timeline, snapshots).
• active-project/** – if the branch represents a “project” with status/tasks/decisions.
  • active-project/decisions.log – branch-level design decisions.
  • active-project/research.md – branch-level research summary (optional).

This avoids collisions when multiple worktrees are edited simultaneously.

3. Manifest-Driven Discovery

TOON manifests (*.toon) provide a semantic index for:

• Domains (knowledge-base/domains/domain-manifest.toon).
• Research (knowledge-base/research/research-manifest.toon).
• Guides (guides/guides-manifest.toon).
• Workflows (workflows/workflows-manifest.toon).
• Reports (reports/reports-manifest.toon).
• ADRs and design docs (docs/docs-manifest.toon, see below).

Agents rely on manifests for discovery before loading full documents.

4. GraphQL SDL for Domain Ontologies

Domain knowledge is modeled using GraphQL SDL:

• Types, fields, and relationships live in schema.graphql files per domain.
• Documentation files describe semantics, examples, and integration patterns.
• This gives LLMs a formal structure to reason over, beyond freeform docs.

5. Git Worktrees and Ephemeral Branches

Worktrees allow multiple branches to coexist on disk. Each worktree:

• Owns its local planning and session state files.
• Reads from the shared knowledge + templates.
• Promotes only stable artifacts (e.g. domain schemas, reports, workflows, ADRs) back into the root repo via PRs.

6. .claude Directory for Tooling Layer

The .claude directory provides centralized agent configuration, lifecycle hooks, and command automation without storing per-branch state:

• Configuration files define agent defaults and worktree policies.
• Hooks automate worktree creation, resumption, and cleanup.
• Commands provide CLI entrypoints for common operations.
• Prompts store reusable prompt fragments for agent operations.

7. ADRs and Design Decisions

Design decisions follow a two-level model:

• Branch-level: Quick decisions logged in active-project/decisions.log inside each worktree.
• Project-level ADRs: Stable, cross-cutting decisions promoted into docs/adr/ADR-XXXX-*.md once accepted.

Research/plan/implement structures exist both as:

• Global methods: Documented in guides/ and codified in workflows/.
• Per-branch execution: Implemented via PLAN.local.md, IMPLEMENTATION.local.md, .session/**, and active-project/** in each worktree.

8. ADR Lifecycle & Status

Status values

Use these standard statuses:

• Proposed
  Drafted and under review. Not yet binding.

• Accepted
  Approved and considered the current source of truth. New work should follow this decision.

• Rejected
  Considered but explicitly not adopted. Kept for historical context.

• Superseded
  Replaced by a newer ADR. The newer ADR must be linked.

Each ADR must declare its status near the top of the document.

When an ADR is required

Create an ADR for decisions that are:

• Cross-cutting (affecting multiple domains, systems, or teams).
• Hard to reverse or high-impact (e.g., storage formats, ontology strategy).
• Changing repo-wide conventions (manifests, worktree workflow, naming).

Local, low-impact decisions can stay in:

• active-project/decisions.log
• IMPLEMENTATION.local.md

Superseding ADRs

When a decision is changed:

1. Create a new ADR describing the new decision.
2. In the new ADR, add a Supersedes section linking to the old ADR.
3. In the old ADR:
   • Update Status to Superseded.
   • Add a Superseded by link to the new ADR.
4. Update any affected:
   • Schemas (*.schema.graphql)
   • Guides (e.g., ontology-design.md, worktree-workflow.md)
   • Workflows (workflows/**)

This keeps decision history linear, searchable, and machine-discoverable.

---

Global Repository Structure (Root Worktree)

Use this example structure for reference:

project-root/
├── CLAUDE.md
├── README.md
├── manifest.toon
│
├── .claude/
│   ├── config/
│   ├── hooks/
│   ├── prompts/
│   ├── commands/
│   └── state/
│
├── templates/
│   ├── PLAN.template.md
│   ├── IMPLEMENTATION.template.md
│   ├── SESSION.template.md
│   ├── WORKFLOW.template.md
│   └── REPORT.template.md
│
├── docs/
│   ├── docs-manifest.toon          # Registry for ADRs & design docs
│   ├── adr/
│   │   ├── ADR-0001-init-structure.md
│   │   ├── ADR-0002-use-toon-manifests.md
│   │   └── ADR-0003-use-graphql-sdl.md
│   └── design-decisions/
│       ├── knowledge-architecture.md
│       └── worktree-strategy.md
│
├── knowledge-base/
│   ├── domains/
│   │  └── design-systems/
│   │      ├── design-system.schema.graphql
│   │      ├── documentation.md
│   │      └── examples.json
│   └── research/
│       ├── research-manifest.toon
│       └── ...
│
├── guides/
│   ├── guides-manifest.toon
│   ├── research-methods.md
│   ├── data-analysis-patterns.md
│   ├── document-generation.md
│   ├── code-standards.md
│   ├── ontology-design.md
│   └── adr-process.md              # How to write and promote ADRs
│
├── workflows/
│   ├── workflows-manifest.toon
│   ├── domain-onboarding.md
│   ├── add-new-report.md
│   └── record-design-decision.md   # Workflow: when/how to create ADRs
│
├── mcp-servers/
├── reports/
│   ├── reports-manifest.toon
│   └── assets/figures/
│
├── schemas/
│   ├── manifest-schema.json
│   ├── workflow-schema.json
│   ├── project-plan-schema.json
│   ├── domain-extensions.schema.graphql
│   └── graphql-directives.schema.graphq
├── .gitignore
└── .git/

---

Per-Worktree Structure (Encapsulated Branch State)

Each worktree, created for a feature/report/domain, contains:

proj-my-task/
├── SESSION.md                      # Current session & handoff
├── PLAN.local.md                   # Plan for this branch only
├── IMPLEMENTATION.local.md         # Implementation details
├── CLAUDE.local.md                 # Optional branch-specific overrides
│
├── .session/
│   ├── meta.json
│   ├── timeline.md
│   ├── notes/
│   └── snapshots/
│
├── active-project/
│   ├── status.md
│   ├── tasks.md
│   ├── decisions.log               # Branch-level design decisions
│   └── research.md                 # Branch-level research summary (optional)
│
├── knowledge-base/                 # WIP domain changes (if any)
├── reports/                        # WIP reports (if any)
├── src/ or app/                    # Code, if this is a software project
└── (other project files on this branch)

The research/plan/implement pattern is:

• Research → active-project/research.md, .session/notes/**.
• Plan → PLAN.local.md.
• Implement → IMPLEMENTATION.local.md, active-project/status.md, tasks.md, code changes.

---

ADRs and Design Decisions

ADR Templates and Location

ADRs live in project-root/docs/adr/ and follow a consistent template:

# ADR-0003: Use GraphQL SDL for Domain Ontologies

## Status
Accepted

## Context
[What problem this solves; alternatives considered]

## Decision
[Short description of the chosen approach]

## Consequences
- [Positive consequence]
- [Negative consequence]
- [Open questions]

## Related
- [Link to relevant branches/PRs]
- [Link to domain schemas or docs]

Branch-Level Decisions → ADR Promotion

Within a worktree:

• Log decisions as they happen in active-project/decisions.log:

# Decisions

## 2025-12-10 – Choose TOON for manifests
Context: [brief]
Decision: [brief]
Alternatives: [brief]
Impact: [brief]

When a decision is clearly cross-cutting and stable:

1. Draft an ADR under active-project/adr-drafts/ADR-XXXX-*.md (optional).
2. On merge, promote that file into project-root/docs/adr/.
3. Update docs/docs-manifest.toon with a new ADR entry.
4. Reference the ADR from:
   • Relevant domain docs in knowledge-base/domains/**/documentation.md.
   • guides/adr-process.md if it affects decision practices.
   • docs/design-decisions/*.md for higher-level narratives.

docs-manifest.toon

Register ADRs and other design docs:

version: "1.0"
docs{id, title, type, path, status, tags}:[1]
  adr-0001-init-structure
  "Initialize Project Structure"
  adr
  ./docs/adr/ADR-0001-init-structure.md
  accepted
  [architecture, repo, worktrees]
  ---
  adr-0002-use-toon-manifests
  "Use TOON for Manifests"
  adr
  ./docs/adr/ADR-0002-use-toon-manifests.md
  accepted
  [manifests, storage, tokens]
  ---
  knowledge-architecture
  "Knowledge Architecture Overview"
  design-doc
  ./docs/design-decisions/knowledge-architecture.md
  informative
  [knowledge-base, domains, manifests]

You can then add a docs-registry section to manifest.toon pointing at docs/docs-manifest.toon.

---

Guides for Research / Plan / Implement

Global how-to lives in guides/:

• guides/research-methods.md – how to run and synthesize research.
• guides/adr-process.md – when to write an ADR vs. keep a local decision.
• guides/document-generation.md – how to write high-quality reports.
• guides/worktree-workflow.md – how to use worktrees and local structures.

Branch-level execution lives in each worktree:

• active-project/research.md – specific research done for that branch.
• PLAN.local.md – concrete plan for this branch.
• IMPLEMENTATION.local.md – implementation details and trade-offs.
• active-project/decisions.log – design decisions made while implementing.

This separation lets agents use global guides as instructions and local files as current state.

ADR and ontology guides

ADRs live in docs/adr/ and use the standard statuses (Proposed, Accepted, Rejected, Superseded) defined in guides/adr-process.md. That guide is the single source of truth for when to write an ADR, how to structure it, and how to promote local decisions into project-level records.

Ontology modeling, schema versioning, and deprecation rules are defined in guides/ontology-design.md. All *.schema.graphql files must follow those rules for semantic versioning, deprecation via @deprecated, and ADR-backed breaking changes.

---

Workflows Connecting Everything

Add a workflow workflows/record-design-decision.md to define when a decision should become an ADR:

# Workflow: Record Design Decision

## Purpose
Ensure important design decisions are captured, discoverable, and promoted when appropriate.

## Steps

### 1. Log Local Decision (Always)
- [ ] Add an entry to `active-project/decisions.log`:
  - Date
  - Context
  - Decision
  - Alternatives
  - Impact

### 2. Evaluate for ADR (When Significant)
Decision deserves an ADR if:
- It affects multiple domains or systems.
- It changes how future worktrees should operate.
- It is hard to reverse or has large impact.

If **yes**:
- [ ] Draft ADR in `active-project/adr-drafts/ADR-XXXX-*.md` using ADR template.
- [ ] Reference relevant branches, PRs, and domain docs.

### 3. Promote ADR on Merge
Once the branch is merged:
- [ ] Copy ADR draft to `docs/adr/` and assign final ADR number.
- [ ] Update `docs/docs-manifest.toon`.
- [ ] Link ADR from:
  - Relevant `knowledge-base/domains/**/documentation.md`
  - `docs/design-decisions/*.md` if needed.

### 4. Update Global References (If Needed)
- [ ] Update `CLAUDE.md` if ADR changes how Claude should behave.
- [ ] Update guides or workflows impacted by the decision.

---

Master Manifest (Root Repo)

Add a docs registry to manifest.toon:

version: "1.0"
last_updated: "[TODAY'S DATE]"
description: "Master knowledge registry for [PROJECT NAME]"

registries{id, title, description, path, type}:[2]
  domains-registry
  "Domain Knowledge Manifest"
  "GraphQL schemas and documentation for domain ontologies"
  ./knowledge-base/domains/domain-manifest.toon
  domains
  ---
  research-registry
  "Research Manifest"
  "Consolidated research findings and evaluations"
  ./knowledge-base/research/research-manifest.toon
  research
  ---
  guides-registry
  "Guides Manifest"
  "Methodology and how-to documentation"
  ./guides/guides-manifest.toon
  guides
  ---
  workflows-registry
  "Workflows Manifest"
  "Reusable workflow checklists"
  ./workflows/workflows-manifest.toon
  workflows
  ---
  docs-registry
  "Docs & ADR Manifest"
  "Architecture Decision Records and design documents"
  ./docs/docs-manifest.toon
  docs

mcp_servers{id, name, description, manifest_path}:[3]
  knowledge-access
  "Knowledge Access"
  "Domain schema querying and manifest parsing"
  ./mcp-servers/knowledge-access/manifest.json

---

Governance & Ownership

Roles

• Knowledge steward
  Owns knowledge-base/**, domain schemas, and research manifests. Reviews and approves changes to domain ontologies and research syntheses.

• Workflow steward
  Owns workflows/** and guides/**. Approves changes to core workflows, conventions, and process documentation.

• Architecture steward
  Owns docs/adr/** and docs/design-decisions/**. Facilitates ADR proposals, approves status changes (e.g., Proposed → Accepted), and ensures ADRs are reflected in schemas/guides.

Change control

• Changes to:
  • manifest.toon, docs/docs-manifest.toon, and other registries require review from the knowledge or architecture steward.
  • knowledge-base/domains/** schemas require knowledge steward review.
  • guides/** and workflows/** require workflow steward review.
• All such changes should be tied to:
  • A worktree branch.
  • At least one ADR (if impact is cross-cutting).
  • A short rationale in the PR description.

---

Worktree Lifecycle and Knowledge Promotion

1. Create worktree for a feature/report/domain.
2. Do research/plan/implement using:
   • active-project/research.md, PLAN.local.md, IMPLEMENTATION.local.md.
   • active-project/decisions.log for decisions.
3. Draft ADRs in active-project/adr-drafts/ when decisions are cross-cutting.
4. Promote artifacts back to root on merge:
   • Domain schemas/docs → knowledge-base/domains/**.
   • Reports → reports/**.
   • ADRs → docs/adr/** and docs/docs-manifest.toon.
   • Any global workflow/guide updates → workflows/**, guides/**.
5. Clean up worktree after promotion; local session state stays in branch history.

---

Governance, Versioning, and Deprecation

• Stewards: Assign owners for domains (knowledge-base/**), workflows/guides, and ADRs/docs to review impactful changes.
• Schema versioning: Each *.schema.graphql records version and lastUpdated in a top-level comment and follows the semantic versioning and deprecation rules in guides/ontology-design.md. Breaking changes require an ADR and a major version bump.
• ADR lifecycle: Use standard statuses (Proposed, Accepted, Superseded, Rejected) and manage promotion/supersession via guides/adr-process.md. Cross-cutting decisions must have ADR coverage, and superseding ADRs must link bidirectionally.