1. Philosophy

Context

Reject the dogma and instead forge a middle path — one that respects the narrative density of Lore while demanding the rigorous purity of Code.

LychD needs lore and engineering, but neither can substitute for the other. Its telos seeks a bounded, relational intelligence: answerable to consequence, capable of memory and repair, and unwilling to mistake power for totality. Architecture, implementation, delivery, and evidence are distinct kinds of truth.

Phylactery, Vessel, and Invocation are cognitive cartography: names that make jurisdiction easier to remember. They must not obscure exact commands, schemas, logs, recovery steps, or contracts. Methodologies are tools, not chains. Only necessary elements are imported into the workflow.

Decision

LychD adopts eXtreme Documentation Driven Development (xDDD):

establish the Logos → derive the domain → prove the contract → manifest code → return observed consequence.

Exploration may precede a stable test. Completion requires executable behavior, architectural law, the public delivery boundary, and routes into that truth to agree.

xDDD distills these practices, utilizing AI to dial the knobs to 11.

1. eXtreme Programming (XP)

The Navigator may be an LLM. Close feedback and engineering judgment still govern the work.

Abstract Spec is written first. The vision must be solidified in text to guide the summoning. Code is the Documentation regarding implementation details. Low-level mechanics are not duplicated in the prose.

Travel light, but prepared.

2. Domain-Driven Design (DDD)

Software structure reflects the Vision. Lore (Map) and Code (Territory) remain distinct, with their shared vocabulary kept in the Lexicon.

Domain Isolation: Separation of concerns is mandatory. The Domain is isolated from the Infrastructure. Bounded domains keep ownership clear and separate intent from effects.

Lore is welcome in documentation, docstrings, and CLI messages where it helps understanding. Commands, schemas, operational logs, and low-level contracts must stay exact. A metaphor earns its place by making the boundary easier to see.

3. Test-Driven Development (TDD)

Tests bind the manifestation to the intent through executable examples and regression checks. Blind adherence to the order of operations is rejected.

Strict Test First can stifle exploration. Prototyping is encouraged, provided tests are backfilled before the final commit. Test order cannot substitute for judgment.

4. Readme/Specification-Driven Development (RDD/SDD)

Write the user-visible contract before committing to its implementation. This ensures the right thing is being built before the thing is built right.

Documentation deals in abstract ideas and interfaces, avoiding redundant repetition of code logic.

5. Agile Methodology

Rapid iteration and adaptation are prioritized. Change is not feared. TDD loops and prototyping keep feedback close to the work.

The Ritual (Scrum/Sprints): Artificial time-boxes are viewed as fractures in the vision. Flow is prioritized over sprinting.

6. Waterfall Model

Adopt Waterfall's demand for foresight. Writing the Prophecy (Documentation) before code exposes architectural mistakes while they are still cheap to change. Deliberate before an irreversible act, and revise the plan when implementation contradicts it.

Constitutional telos

“Plain truth opens the door. The symbol opens the cosmos. The cosmos returns to the next exact act.”

LychD is the software body. The Lich is the recurrent whole: Vessel, Phylactery, identity, orchestration, action, consequence, memory, repair, and relation. A model is one organ.

Myth establishes its own register. When it returns to engineering, it returns as an invariant that can be implemented, observed, refused, or repaired. The Covenant registry maps constitutional meaning into its technical owners.

Documentation Topology

This section owns current placement. ADR 02 preserves the historical choice of documentation stack and registers; it does not compete for topology law.

Tracked .agents/scopes/** cards route agents but own no truth. Tracked .agents/workflows/** playbooks preserve procedure, load after scope, and yield to canonical owners.

Router delegation

A router exposes task triggers and explicit links to scope branches, canonical owners, or workflow playbooks. It identifies the destination's role so a reader knows whether to continue discovery, establish truth, or load procedure. A route may lead to another router, which owns its deeper routes; the parent keeps that branch discoverable without duplicating its contents.

Follow only the branches required by the task. Cross-domain links make another scope tree reachable without requiring its wholesale ingestion. Workflows load after the matching scope. Routing grants no new authority, launches no work, and does not itself assemble a fresh Context. Discovery in Spellweaver shows the passage from scope discovery to workflow selection and a bounded task handoff.

One home per truth

Other pages summarize once and link. Begin at the fitting door, use parent indexes as maps, then read the smallest owner. Executable claims terminate in source, tests, lockfiles, artifacts, or maintained receipts; scratch notes, searches, and generated indexes own nothing.

Architecture and application pages describe one coherent system: responsibilities, records, handoffs, decisions, and recovery. Use direct contract language without maturity badges or Designed suffixes on headings. State of Work collects implementation evidence and missing pieces. Mention a local limitation only when it changes an operation the reader can perform, an exact compatibility boundary, or the interpretation of a worked example; explain that concrete limit and link its evidence instead of repeating a delivery category.

Repository Source Topology

The repository contains one authoritative LychD system and separately tooled delivery clients. src/lychd/** is the Python distribution and domain source. Native first-party Composition truth enters src/lychd/compositions/<identity>/**; a Portfolio page alone remains design, not delivery.

A delivery client keeps its complete project root under clients/<target>/**. It may own presentation, platform integration, connection mechanics, and bounded local interaction state, but its separate toolchain does not grant it Composition records, policy, effect authority, or finish judgment. The web project lives at clients/web/**; the Android project lives at clients/android/**. Each project keeps the source layout native to its toolchain. The current web source lives at clients/web/src/**; the Android application module uses clients/android/app/src/main/**. Repeated inner src names express separate build ownership rather than one mixed repository source tree.

Consequences

The Path Remains Local.

The method is not the magic. The ultimate goal is the fulfillment of the Prophecy, not religious adherence to this document.

Lore can remain vivid without pretending to prove a feature, and engineering can remain exact without abandoning constitutional purpose. A change that alters several kinds of truth may require several owners to change.

Use the ritual to manifest the Vision. If the rules bind, break them.