Symbiospec: definition and structure

Start by checking the docs-folder-system and docs-folder-agents-rules-system skills in the coding agent plugin, then inspect Heidrun Code’s /docs, /docs/agent_rules, and AGENTS.md as the proposal describes. Confirm the existing directory spelling and review the current files before proposing a structure. Done means a documented, maintainable specification system that separates concepts, behaviour, UI structure, styling, and any agreed supporting areas.

Naming "Symbiotic Spec"

SymbioSpec for short

Symbiotic Spec is a shared specification that enables humans and artificial intelligence to build software together. Symbiotic Spec explicitly describes the product’s concepts, expected behaviours, interface, and rules for development. Humans can understand and approve the definition of the software; the AI has a precise reference for building the software and verifying the results.

The word Symbiotic draws on biology and evokes cooperation between different organisms. Applied to human–AI collaboration, the metaphor describes two different ways of working finding common ground. Like the synthesizer music in Close Encounters of the Third Kind, Symbiotic Spec provides a common language for expressing intent, establishing shared understanding, and coordinating actions.

The word Spec, short for specification, gives that encounter a rigorous structure. Each section has a clearly defined responsibility, and each expected behaviour can be reviewed and verified. Symbiotic Spec evolves through explicit decisions: the AI prepares concrete proposals, humans review the proposals in batches, and approved changes guide development. When the software differs from Symbiotic Spec, the discrepancy must be reported rather than silently changing the specification to justify the result.

---

Music

Symbiotic Spec is like the music in Close Encounters of the Third Kind: a common language that makes collaboration possible across a profound difference. In the film, a short musical sequence opens communication between humans and extraterrestrial visitors. In software development, Symbiotic Spec plays a similar role between humans and AI: an explicit description of what the software should do, which humans can understand and approve, and AI can use to build and verify the software. Neither side needs to work like the other; collaboration begins with a shared reference.

---

Design Proposal: /docs and /docs/agent_rules — AI-Native Documentation, Behavioural Specifications, and Agent Rules

Date: 2026-10-26
Status: Brainstorming / Architecture Proposal
Target project: Heidrun Code
Objective: Formalize, audit, initialize, maintain, and continuously improve an AI-native documentation system that remains understandable and controllable by humans, even when AI agents produce code at extremely high velocity.

1. Related Repositories

Two repositories are involved:

Coding Agent Plugin
https://github.com/jeromeetienne/coding_agent_plugin

This repository contains reusable skills and instructions for coding agents.

Two existing skills are particularly relevant:

• docs-folder-system — manages the broader /docs documentation system.
• docs-folder-agents-rules-system — specializes in maintaining the documentation and rules under /docs/agent_rules.

These are the skill names discussed during the conversation. Their exact filesystem paths and current implementations should be checked before modifying them.

Heidrun Code
https://github.com/heidrun-org/heidrun_code

This is the application in which the documentation system is already being used.

Relevant locations:

• /docs — the application's documentation hierarchy.
• /docs/agent_rules — the area containing the structured definitions, concepts, UI rules, behaviours, and styling information discussed here.
• AGENTS.md — repository-level instructions for coding agents.

Important: The exact spelling of the existing agent_rules directory should be confirmed against the repository before implementation. The conversation also referred to it as agents_rules.

The plugin repository defines reusable methods. Heidrun Code is the concrete project where those methods are applied.

---

2. Background: Why This System Is Necessary

2.1 AI radically changes software production velocity

The starting observation is that AI coding agents can produce and modify software at a rate that makes traditional development practices increasingly difficult to scale.

In the current Heidrun Code development process:

• The project has been developed very rapidly, over roughly 20 days.
• The reported recent development rate is approximately 55,000 changed lines per day.
• Thousands of automated tests have already been created.
• Approximately 200 additional tests can be generated per day.
• A single experienced developer, using AI agents, can perform work that would previously have required a substantially larger team.

These are observations and estimates from the current project, not independently benchmarked productivity measurements.

The implications become even more substantial with multiple developers.

For example:

• One AI-assisted developer produces 25 pull requests per day.
• Five developers produce 125 pull requests per day.
• At 50,000 changed lines per developer per day, this represents 250,000 changed lines daily.

A conventional human code-review process cannot realistically inspect all of this line by line.

Even if the numbers vary, the underlying scaling problem remains.

2.2 The traditional pull request review becomes a bottleneck

Traditional pull request review assumes that another developer can:

1. Read the code changes.
2. Understand the implementation.
3. Identify potential problems.
4. Request corrections.
5. Approve the change.

This is valuable when humans produce code at human speed.

But when coding agents produce much larger volumes of code, the review capacity does not automatically increase.

Simply assigning more human reviewers would eliminate much of the productivity benefit.

The key proposal is to move a significant part of human supervision from code-level review to product-level and behavioural review.

This does not mean removing all technical verification.

It means separating the responsibilities:

• AI agents produce and inspect implementation details.
• Automated systems verify correctness, quality, and consistency.
• Humans retain control over what the product does and how it behaves at a high level.

2.3 Humans must retain an overview of the product

An essential requirement is that the human developer or product owner must maintain a clear overall understanding of:

• What the application does.
• How its major concepts relate to one another.
• How the application behaves.
• How users interact with it.
• How the major components work together at a high level.
• What consequences architectural and product decisions may have.

The human does not need to read every implementation detail.

However, the human must understand the system sufficiently to make informed decisions about its future.

This is a fundamental design principle:

The human controls the product by understanding and approving its high-level model, rather than supervising every line of implementation.

The documentation system should make this possible.

---

3. Current Situation

3.1 The current system already exists

The existing documentation is not starting from zero.

Heidrun Code already contains a significant documentation structure.

During the conversation, approximately 121 documentation/rule files were counted in the relevant existing rules system.

The existing approach was described as promising but insufficiently formalized.

The assessment was roughly:

• The general concept is good.
• The overall direction is correct.
• The current structure already contains useful information.
• The existing documentation is substantial.
• However, its organization and maintenance rules need to become more rigorous.
• The conceptual design was estimated to be around 25–30% mature.

This percentage is a subjective design assessment, not a measure of documentation coverage.

The goal is therefore not to throw away the existing documentation, but to understand it, improve its structure, and progressively migrate it into a more rigorous system.

3.2 Existing documentation dimensions

Three primary dimensions already exist.

A. Glossary

The glossary defines the important concepts of the application.

For example, if the application has a concept called Macro, the glossary should explain:

• What a Macro is.
• What purpose it serves.
• What capabilities it provides.
• How it relates to other concepts.
• What terminology should be used consistently.

This definition should be independent of where a button is placed or how a screen is organized.

The glossary is not merely a dictionary of words.

It defines the application's domain model at a conceptual level.

B. Web Styling

This describes how the application should look and how visual decisions should be made.

Examples:

• Colors.
• Typography.
• Spacing.
• Visual hierarchy.
• Warning and error presentation.
• How different control types should be represented.
• When a switch is appropriate versus a radio button.
• Visual consistency between features.

The styling rules allow an AI coding agent to create new interfaces that remain visually consistent with the rest of the application.

C. User Interface

The existing user-interface documentation combines two different concerns:

1. Where elements appear and how the UI is structured.
2. What happens when users interact with those elements.

For example:

• Where is the Save button?
• What happens when the user clicks Save?

Currently, these two kinds of information are mixed together.

This makes the documentation more difficult to reason about, audit, and maintain.

A major proposed improvement is to separate User Interface structure from Behaviour.

---

4. Proposed Documentation Architecture

The documentation should be organized around clearly separated concerns.

The following is a conceptual architecture proposal, not a claim that these directories already exist.

Area	Responsibility	Main question
Glossary	Domain concepts and terminology	What are the concepts?
Behaviour	Expected application behaviour	What should happen?
User Interface	UI structure, navigation and placement	Where and how can users interact?
Styling	Design system and visual consistency	What should it look like?
Platform Support	Supported environments and constraints	Where must it work?
System Overview	High-level product and system understanding	How does the overall system work?

The first four areas are the core concepts identified during the discussion.

Platform Support and System Overview are proposed complementary areas.

They may eventually be independent sections or integrated into the other sections.

4.1 Glossary — the foundation

The glossary should be established first.

It contains the canonical definitions of the application's significant domain concepts.

Example:

Concept: Code Hosting

Definition

A system that provides access to hosted source-code repositories and their associated development information.

Purpose

Allow users to explore and work with repository-related information.

Capabilities

• Search and browse repositories.
• Search and consult issues.
• Search and consult pull requests.
• Retrieve information about relevant repository activity.

Related concepts

• Repository
• Issue
• Pull Request
• Commit

Aliases

Historical or alternative terminology, where applicable.

The glossary defines these concepts once.

Other documentation must refer to these definitions rather than repeatedly redefining them.

Important glossary principles

One concept, one canonical identity.

Different words should not silently represent the same concept.

One canonical name.

The documentation and code should use consistent terminology.

Explicit relationships.

Concepts should be linked to related concepts.

No unnecessary UI details.

The definition of a concept should not depend on the location of its buttons.

No unnecessary implementation details.

The glossary should describe the domain, not how individual functions are implemented.

Human validation.

Major concepts should be explicitly validated by a human during initialization.

4.2 Behaviour — what the application does

Behavioural Documentation specifies what the application is expected to do.

This is the central new idea.

It should be understandable to someone who knows the product but does not necessarily know how to program.

Examples:

• When the user clicks Save, the current document is saved.
• When a user selects a repository, its issues and pull requests become accessible.
• When an operation fails, the application displays an understandable error message.
• When a user opens an existing workspace, its previous state is restored.

Behaviour is defined using concepts from the glossary.

For example:

When the user selects a Repository, the application displays the Issues associated with that Repository.

The words Repository and Issue refer to canonical glossary definitions.

The Behavioural Documentation does not need to explain those concepts again.

A behavioural specification should describe

• The relevant concepts.
• The triggering action or event.
• The applicable conditions.
• The expected result.
• Any important state transition.
• Observable failures or error behaviours.
• Relevant platform differences.
• Constraints or invariants that must remain true.

Example

BEH-042: Save Document

Concepts: Document, Workspace

Trigger: The user invokes Save.

Expected behaviour:

1. The current document content is persisted.
2. The document remains associated with its workspace.
3. The application confirms that saving succeeded.

Failure behaviour:

If saving fails, the application informs the user and does not falsely report success.

This describes the product contract.

It does not specify the database, function names, or code architecture.

4.3 User Interface — how the interaction is exposed

The User Interface documentation describes the structure of the application from the user's perspective.

For example:

• Available screens.
• Navigation hierarchy.
• Panels.
• Dialogs.
• Menus.
• Buttons.
• Input controls.
• Where controls appear.
• Which interactions expose particular behaviours.

The UI references Behavioural Documentation rather than duplicating it.

Example

UI: Document Editor

• Contains a File menu.
• The File menu contains a Save action.
• The Save action invokes BEH-042.
• The document content appears in the main editor.
• The workspace navigation appears in the designated navigation area.

The UI document explains where the action is found.

The Behaviour document explains what the action must accomplish.

This separation avoids having multiple inconsistent descriptions of the same behaviour.

4.4 Styling — the design system

Styling should define reusable visual rules rather than isolated screenshots.

Examples:

• Primary and secondary colors.
• Text hierarchy.
• Component sizes.
• Layout spacing.
• Borders.
• Selection states.
• Disabled states.
• Warning colors.
• Error colors.
• Success indicators.
• Dark and light themes.
• Appropriate choice of UI widgets.

Example: radio button versus switch

A rule might specify:

• Use a switch for a binary on/off setting.
• Use radio buttons when selecting one option from several explicit alternatives.
• Use a dropdown when many options are available and displaying them all would be impractical.

These are illustrative examples, not previously agreed project-specific rules.

The agent should follow the project's actual design conventions once established.

Main objective

When the AI creates a new feature, it should not invent an arbitrary visual design.

It should apply the established design system consistently.

4.5 Platform Support

Platform requirements should also be explicit.

A desktop application may need to support access from a mobile browser.

Relevant environments might include:

• macOS.
• Windows.
• Linux.
• Desktop web browsers.
• Android browsers.
• iOS browsers.

The system should describe which environments are actually supported, rather than assuming every platform must be supported.

Platform documentation may specify:

• Minimum supported environments.
• Responsive layout requirements.
• Touch input behaviour.
• Keyboard interaction requirements.
• Platform-specific capabilities.
• Differences in behaviour or limitations.

These requirements should inform both implementation and automated verification.

4.6 System Overview

A supplementary high-level overview may help humans understand the structure of the application.

This is distinct from detailed implementation documentation.

It may describe:

• Major subsystems.
• Their responsibilities.
• Important data flows.
• Significant dependencies.
• Architectural boundaries.
• Important technical constraints.
• Major design decisions and their consequences.

The objective is to support informed decision-making without requiring a detailed code review.

This section should remain small enough to be read and understood by a human.

---

5. Documentation Relationships

The documentation areas should not be independent collections of unrelated text.

They should form a coherent network of references.

A proposed dependency structure is:

                     PRODUCT OWNER
                          |
                          v
                VALIDATED CONCEPTS
                          |
                          v
                       GLOSSARY
                          |
              +-----------+-----------+
              |                       |
              v                       v
           BEHAVIOUR             SYSTEM OVERVIEW
              |
              v
        USER INTERFACE
              |
              v
           STYLING

     PLATFORM REQUIREMENTS
       apply where relevant

This is a conceptual dependency model, not necessarily a filesystem hierarchy.

For example:

• Behaviour references glossary concepts.
• UI references behaviours and glossary concepts.
• Styling defines how UI elements are presented.
• Platform requirements constrain applicable behaviours and interfaces.
• System Overview provides the human-readable big picture.

A documentation file should not duplicate definitions owned by another file.

Instead, it should reference them.

5.1 Stable concept identifiers

A possible improvement would be to assign stable identifiers.

Examples:

CONCEPT-REPOSITORY
CONCEPT-ISSUE
CONCEPT-PULL-REQUEST

BEH-042-SAVE-DOCUMENT

UI-DOCUMENT-EDITOR
UI-FILE-MENU

These identifiers would allow documentation to be reorganized without breaking its conceptual references.

Their exact format remains to be decided.

5.2 Single source of truth

Each piece of information should have an authoritative location.

For example:

• The meaning of Repository belongs to the Glossary.
• The result of saving a document belongs to Behaviour.
• The position of the Save action belongs to UI.
• The appearance of its button belongs to Styling.

This reduces duplication and documentation drift.

---

6. Two Existing Skills and Their Responsibilities

The existing separation into two skills is useful and should be preserved unless repository inspection reveals a reason to change it.

6.1 docs-folder-system

This is the general documentation-management layer.

Its intended responsibilities could include:

• Define the overall /docs structure.
• Define the purpose of every major folder.
• Establish documentation conventions.
• Maintain indexes and navigation.
• Detect missing or misplaced documentation.
• Detect duplicates.
• Identify obsolete documents.
• Check consistency across documentation areas.
• Coordinate documentation initialization and maintenance.

This skill should not need to understand the complete domain model of every application.

It should provide reusable documentation infrastructure.

6.2 docs-folder-agents-rules-system

This is the specialized layer for structured agent rules and product definitions.

Its intended responsibilities could include:

• Manage the glossary.
• Manage behavioural specifications.
• Manage UI descriptions.
• Manage styling rules.
• Check dependencies between those areas.
• Extract domain knowledge from a codebase.
• Audit the quality and completeness of definitions.
• Propose improvements.
• Coordinate human approval.
• Maintain terminology consistency.
• Identify conflicts between specifications and implementation.

The specialization should build upon the general /docs system rather than duplicating it.

6.3 Relationship between skills and project files

The desired relationship is:

coding_agent_plugin
    |
    +-- docs-folder-system
    |      |
    |      +-- General documentation conventions
    |      +-- Folder organization
    |      +-- Documentation lifecycle
    |
    +-- docs-folder-agents-rules-system
           |
           +-- Glossary management
           +-- Behaviour management
           +-- UI rules management
           +-- Styling management
           +-- Auditing and initialization


heidrun_code
    |
    +-- AGENTS.md
    |
    +-- docs/
           |
           +-- Existing documentation
           |
           +-- agent_rules/
                  |
                  +-- Project-specific concepts
                  +-- Project-specific behaviours
                  +-- Project-specific UI definitions
                  +-- Project-specific styling rules

The structure above is conceptual. It must be reconciled with the actual repository layout.

---

7. Required Feature: Formal Folder Definitions

Every folder and significant subfolder should have a clearly defined responsibility.

This was identified as the first concrete requirement.

For each folder, the system should be able to answer:

1. What is the purpose of this folder?
2. What kind of information belongs here?
3. What information must not be placed here?
4. Which other folders does it depend on?
5. Which other folders depend on it?
6. What conventions apply to files inside it?
7. How is its content initialized?
8. How is it updated?
9. How is it audited?
10. Who or what approves significant changes?

This should be explicit and machine-readable enough for coding agents to follow.

7.1 Folder contracts

A possible design is to give every important folder a folder contract.

For example:

name: behaviour
purpose: >
  Define the externally observable behaviour
  expected from the application.

depends_on:
  - glossary

contains:
  - behavioural specifications
  - expected outcomes
  - state transitions
  - error behaviours

excludes:
  - detailed code implementations
  - repeated glossary definitions
  - visual styling rules

human_approval:
  - new product behaviours
  - changed product behaviours
  - removed product behaviours

The YAML format is only illustrative.

A Markdown format could also work.

The final format should fit the existing skills and repository conventions.

7.2 Why folder contracts matter

Without clearly defined folder responsibilities, an AI can place valid information in the wrong location.

Over time, this creates:

• Duplication.
• Contradictions.
• Documentation that becomes difficult to navigate.
• Unclear ownership.
• Unpredictable agent behaviour.
• Unnecessary context consumption.

Folder contracts should make the documentation structure predictable.

---

8. Required Feature: Audit

The system must be capable of auditing an existing documentation hierarchy.

This is especially important for Heidrun Code, which already contains a substantial body of documentation.

8.1 Audit scope

The audit should examine:

Structure

• Are all folders clearly defined?
• Are files located in appropriate places?
• Are naming conventions consistent?
• Are indexes complete?
• Are dependencies understandable?

Glossary

• Are concepts precisely defined?
• Are important concepts missing?
• Are different names used for the same concept?
• Are different concepts incorrectly merged under the same name?
• Are relationships defined?
• Are definitions duplicated?

Behaviour

• Are expected behaviours explicit?
• Are behaviours ambiguous?
• Are important scenarios missing?
• Are failure cases described?
• Are behaviours consistent with glossary concepts?
• Are there contradictory expectations?

User Interface

• Is the navigation structure documented?
• Are controls connected to behaviours?
• Are UI descriptions precise enough?
• Are obsolete interface descriptions present?
• Are UI details incorrectly mixed into concept definitions?

Styling

• Are visual conventions coherent?
• Are rules sufficiently explicit for AI-generated interfaces?
• Are design decisions duplicated or contradictory?
• Are there undefined component types or states?

Implementation alignment

• Does the existing implementation match the documentation?
• Does the implementation contain capabilities absent from the documentation?
• Does the documentation describe capabilities that no longer exist?
• Have significant behaviours changed without documentation updates?

8.2 Audit report

An audit must produce a report before making substantial modifications.

The report should identify:

• What is correct.
• What is missing.
• What is unclear.
• What is contradictory.
• What is obsolete.
• What can be improved automatically.
• What requires human judgment.

A proposed severity classification:

Severity	Meaning
Critical	Contradictory or dangerously misleading specification
High	Missing or incorrect major concept/behaviour
Medium	Structural inconsistency, ambiguity, or duplication
Low	Minor naming, formatting, or clarity issue

Each finding should preferably include:

• A stable finding ID.
• Affected files.
• Explanation.
• Supporting evidence.
• Confidence level.
• Proposed correction.
• Estimated impact.
• Whether human approval is required.

8.3 Example audit finding

### AUDIT-014: Inconsistent terminology

Severity: Medium

Concept: Workspace

Observed aliases:
- Workspace
- Project Space
- Working Area

Evidence:
- docs/...
- src/...
- git history: ...

Problem:
Multiple terms appear to refer to the same domain concept.

Recommendation:
Investigate whether these names describe the same concept.
If confirmed, establish "Workspace" as the canonical name.

Confidence: Medium

Human validation required: Yes

The audit must distinguish evidence from inference.

It should not silently assume that two similar names describe the same concept.

8.4 Report-driven improvement

The intended workflow is:

Existing Documentation
          |
          v
         AUDIT
          |
          v
      Audit Report
          |
          v
     Human Review
          |
          v
   Improvement Plan
          |
          v
   Apply Improvements
          |
          v
       Re-Audit

The audit should be repeatable.

This allows progress to be measured over time.

---

9. Required Feature: Initialization from an Existing Codebase

The system must be capable of initializing documentation when:

• Documentation is missing.
• Documentation is incomplete.
• Documentation is obsolete.
• Documentation is poorly structured.
• A project is adopting the system for the first time.

Crucially, initialization should not be a single fully automatic operation.

It should be an incremental process with human validation.

9.1 Phase 0 — Inventory

Before generating anything, inspect the project.

Potential sources:

• Existing documentation.
• Source code.
• Git history.
• Commit messages.
• GitHub issues.
• Pull requests.
• Tests.
• Existing coding-agent instructions.

The objective is to understand what information already exists.

Outputs:

• Documentation inventory.
• Initial structural map.
• Existing concept candidates.
• Missing-information report.
• Areas of uncertainty.

Do not overwrite existing documentation during this phase.

9.2 Phase 1 — Discover major concepts

The first real initialization step is to identify significant domain concepts.

The AI examines available evidence and proposes candidate concepts.

For example:

Workspace
Repository
Commit
Issue
Pull Request
Coding Agent
Conversation
Macro

These are illustrative concepts from the surrounding Heidrun context.

They must not automatically be considered the complete or validated concept inventory.

The AI should classify its confidence.

For example:

• High confidence.
• Medium confidence.
• Low confidence.

Each concept should have supporting evidence.

9.3 Phase 2 — Human validation

The human reviews the candidates.

The important principle discussed was:

The human first selects only the major concepts they are confident are real and meaningful.

The goal is not to approve everything.

The goal is to establish a trusted conceptual foundation.

Possible decisions:

• Accept.
• Reject.
• Defer.
• Merge with another concept.
• Split into multiple concepts.
• Rename.

Only validated concepts become authoritative glossary entries.

This creates a high-confidence starting point.

9.4 Phase 3 — Investigate each accepted concept

Once a concept has been validated, the AI investigates how it appears throughout the project.

For example, suppose Workspace is accepted.

The agent searches:

• Source code.
• Tests.
• Documentation.
• Git history.
• Issues.
• Pull requests.

It tries to determine:

• What the concept means.
• What capabilities it provides.
• How it is implemented at a high level.
• Where it appears in the product.
• Which other concepts it depends on.
• Which concepts depend on it.
• How its meaning evolved over time.

9.5 Phase 4 — Discover aliases and historical terminology

This is especially important.

A concept may have been called different things during development.

For example:

Initial name: Project Space
Later name: Working Area
Current name: Workspace

The AI should identify these names and their historical relationships.

Git history is valuable because it may reveal:

• Renames.
• Architectural migrations.
• Changes in terminology.
• Previous meanings.
• Concepts that were split or merged.

However, historical naming similarity is not proof of semantic equivalence.

An agent must investigate rather than blindly replacing strings.

9.6 Phase 5 — Establish canonical terminology

Once aliases are understood, the human confirms the canonical name.

The glossary then becomes the authoritative definition.

Example:

Canonical concept: Workspace

Historical aliases:
- Project Space
- Working Area

Preferred term:
Workspace

After confirmation, the agent can propose changes to improve naming consistency.

Targets may include:

• Documentation.
• Code identifiers.
• Test names.
• API names where appropriate.
• UI text.
• Agent instructions.

The objective is for the application to use one coherent vocabulary.

Important safety constraint

Renaming should not be performed blindly.

Some names may be part of:

• Public APIs.
• Persisted data formats.
• Database schemas.
• External integrations.
• Backward-compatibility contracts.

Such changes require compatibility analysis and appropriate migration.

9.7 Phase 6 — Expand to related concepts

After establishing trusted concepts, the system can discover related concepts.

The process repeats:

1. AI proposes.
2. Evidence is provided.
3. Confidence is reported.
4. Human validates.
5. Glossary is updated.

This progressively grows the conceptual model.

The process should favor correctness and coherence over generating the maximum number of definitions.

9.8 Phase 7 — Extract behaviours

Once the glossary is sufficiently reliable, the AI can identify major behaviours.

Evidence can come from:

• Existing tests.
• Source-code paths.
• User-interface flows.
• Historical changes.
• Existing product documentation.
• GitHub issues.

The agent proposes behavioural specifications referencing the glossary.

A human reviews significant product behaviours.

9.9 Phase 8 — Extract UI structure

Next, the agent documents:

• Screens.
• Panels.
• Menus.
• Controls.
• Navigation.
• Layout structure.
• References to behaviours.

The goal is to describe the interface without duplicating complete behaviour definitions.

9.10 Phase 9 — Extract styling conventions

The agent examines the existing interface and styling rules.

It identifies:

• Common components.
• Repeated layout patterns.
• Visual conventions.
• Design inconsistencies.
• Existing tokens and style decisions.

Then it proposes explicit, reusable design rules.

9.11 Phase 10 — Validation and baseline

After initialization, the system should produce:

• A validated glossary.
• A first set of behavioural specifications.
• UI documentation.
• Styling rules.
• Folder definitions.
• A consistency report.
• A list of unresolved questions.
• A traceability map to source evidence.

This becomes the initial documentation baseline.

---

10. Confidence-Based, Incremental Initialization

Confidence is a central aspect of the proposed design.

The workflow should not treat all extracted information equally.

For example:

Level	Interpretation	Default action
Confirmed	Explicitly validated by a human	May become authoritative
High confidence	Supported by strong evidence	Propose for validation
Medium confidence	Reasonably inferred, some uncertainty	Investigate further
Low confidence	Weak or conflicting evidence	Do not promote automatically

These categories are proposed conventions.

The key idea is the progressive promotion of evidence into validated knowledge.

Source Code / History / Existing Docs
                 |
                 v
           AI Extraction
                 |
                 v
         Candidate Knowledge
                 |
                 v
        Evidence + Confidence
                 |
                 v
          Human Validation
                 |
                 v
      Authoritative Documentation

This prevents AI-generated guesses from silently becoming product requirements.

It also keeps the amount of human review manageable.

---

11. Behavioural Documentation as a Product Contract

The Behavioural Documentation is more than ordinary documentation.

It should serve as a high-level product contract.

A human can read it and understand:

• What the software is intended to do.
• What its features mean.
• What behaviour users should expect.
• How the application responds to important actions.
• What behaviour is guaranteed.
• What changes are being introduced.

This contract should drive implementation.

An implementation may change dramatically while its documented behaviour stays the same.

Conversely, a small code change may create an important behavioural change.

This distinction is essential.

11.1 Normative versus descriptive information

The system should distinguish two kinds of knowledge.

Normative specification

What the application is supposed to do.

Observed implementation

What the current application actually does.

These are not always identical.

If the code behaves differently from the specification, the system should report a discrepancy.

It should not automatically rewrite the specification to match the code.

Otherwise, an unintended regression could silently become an accepted product behaviour.

11.2 Human authority

The human is responsible for important product decisions.

The AI may:

• Discover behaviours.
• Suggest behaviours.
• Implement behaviours.
• Generate tests.
• Identify inconsistencies.
• Propose documentation updates.

But material changes to the product contract should be approved by a human.

The human should not need to approve every formatting adjustment or implementation detail.

---

12. Adversarial Design: Application, Tests, and Documentation

An important part of the discussion was the use of adversarial verification.

The current development model already uses a large automated test suite.

The general idea is that independently checked artifacts can detect each other's mistakes.

12.1 First adversarial relationship

Implementation versus Test Suite

The agent implements functionality.

The test suite checks its correctness.

If implementation and tests disagree, the discrepancy must be investigated.

       IMPLEMENTATION
              |
              v
        EXECUTE TESTS
              |
       +------+------+
       |             |
      PASS          FAIL
       |             |
       v             v
    Continue     Investigate
                     |
                     v
                  Correct
                     |
                     v
                   Retest

This already provides substantial protection against regressions.

12.2 The shared-error problem

However, there is a weakness.

If the same AI misunderstands the requirement while writing both implementation and tests, both may agree with each other while being wrong.

For example:

• The intended behaviour is A.
• The AI mistakenly implements B.
• The AI also writes tests expecting B.
• All tests pass.
• The product is still incorrect.

Therefore, passing tests is necessary but not sufficient.

12.3 Second adversarial relationship

Test Suite versus Behavioural Documentation

The Behavioural Documentation supplies an additional reference.

The system checks:

• Do the tests cover the specified behaviours?
• Do the expected results match the specification?
• Are there documented behaviours without corresponding verification?
• Do any tests contradict the documentation?
• Do any tests encode unintended behaviour?

This creates a second verification layer.

       BEHAVIOURAL DOC
                |
                v
       SPECIFICATION AUDIT
                |
                v
            TEST SUITE
                |
                v
        IMPLEMENTATION

The actual verification need not be strictly linear.

It can compare these artifacts in multiple directions.

12.4 Independence matters

The strength of adversarial verification depends on the independence of the checks.

If one AI generates the specification, tests, and implementation using the same faulty assumptions, all three can still agree incorrectly.

Potential mitigations:

• Independent agents for implementation and verification.
• Explicit human approval of important behaviours.
• Tests derived separately from approved specifications.
• Independent execution of user scenarios.
• Review of discrepancies by a different agent.
• Preserving approved specifications as stable references.

The goal is not to make errors mathematically impossible.

It is to make shared errors less likely and easier to discover.

12.5 The temporal aspect

An additional point emphasized in the discussion is that this is not merely about having three artifacts.

The order of updates matters.

If an agent introduces an incorrect behaviour and immediately updates both tests and documentation to match, the verification system loses its independence.

The workflow must therefore distinguish:

1. An approved behaviour.
2. An intended change to that behaviour.
3. An implementation change.
4. A test update.
5. Independent validation of the resulting state.

An approved specification should not silently change simply because the code changed.

This temporal separation is part of the intended adversarial design.

---

13. Automatic User Documentation

A particularly interesting consequence of this architecture is automatic generation of user-facing documentation.

Heidrun Code can be operated by AI agents.

This creates opportunities to combine:

• Behavioural specifications.
• UI descriptions.
• Actual application execution.
• Automated screenshots.

13.1 Example workflow

Suppose the application contains a feature for saving a document.

The system knows:

• What a Document is.
• What saving means.
• Where the Save action is located.
• What should happen when Save is invoked.

An AI agent can:

1. Launch the application.
2. Navigate to the relevant screen.
3. Take a screenshot.
4. Identify the Save action.
5. Perform the action.
6. Capture the resulting state.
7. Generate user-facing instructions.

The generated documentation could explain:

Open the File menu, select Save, and wait for the confirmation that your document has been saved.

Screenshots illustrate the process.

13.2 Updating screenshots automatically

If the application UI changes, screenshots can be regenerated.

For example:

• A button moves.
• A menu changes.
• A panel is redesigned.
• Colors change.
• A workflow receives an additional step.

The documentation system can run the relevant scenarios again and capture updated images.

However, this should happen after verifying that the underlying behavioural or UI change is intentional.

Automatic screenshot regeneration should not hide accidental UI regressions.

13.3 Separate product specifications from user documentation

Two kinds of documentation should remain distinct.

Behavioural Documentation

Describes the product's intended behaviour.

• Normative.
• Version-controlled.
• Human-supervised.
• Used for verification.
• Refers to canonical concepts.

User Documentation

Explains how to use the actual application.

• User-oriented.
• Illustrated.
• Procedure-focused.
• Potentially generated automatically.
• Updated when validated UI workflows change.

The first is a source of truth.

The second is a derived artifact.

---

14. Continuous Maintenance

Initialization is only the beginning.

The system must maintain documentation as the software evolves.

14.1 Development workflow

A possible future workflow:

Developer + Coding Agent
          |
          v
    Proposed Feature
          |
          v
    Code Modification
          |
          v
  Behavioural Difference Analysis
          |
          v
  Proposed Documentation Changes
          |
          v
    Human Review
    (when needed)
          |
          v
  Behaviour / UI / Glossary Update
          |
          v
    Independent Verification
          |
          v
     Commit / Integration

The precise order may differ depending on whether implementation follows a new specification or the system is documenting existing behaviour.

The important requirement is that significant changes to approved behaviour receive explicit validation.

14.2 Detect documentation drift

The system should detect mismatches such as:

• Code contains a new feature absent from the documentation.
• A documented feature no longer exists.
• A UI control has moved without an updated UI description.
• A behaviour has changed without approval.
• A concept was renamed inconsistently.
• A test no longer corresponds to an approved behaviour.
• A screenshot no longer matches the application.

14.3 Avoid unnecessary documentation updates

Not every code modification requires a documentation change.

For example:

• Refactoring an internal function.
• Adding an index.
• Improving performance without changing the observable contract.
• Renaming an internal variable.
• Reorganizing an internal module.

These may change implementation without affecting the Behavioural Documentation.

That separation is a fundamental reason the system can scale.

---

15. Replacing Traditional Human Code Review with Behavioural Review

This is a longer-term consequence of the proposed architecture.

Instead of asking a human to review thousands of changed lines, the system could present:

Behavioural changes

What does the product do differently?

Conceptual changes

Were any domain concepts added, removed, or redefined?

UI changes

What will users see or interact with differently?

Architectural changes

Were there significant changes to the system's high-level organization or technical commitments?

Verification results

Which automated checks passed or failed?

Unresolved risks

What remains uncertain?

The human primarily reviews the product-level changes.

An illustrative review summary:

# Behavioural Review

## Added
- Users can filter Issues by status.
- Users can reopen the last selected Repository.

## Modified
- Saving a Workspace now shows a confirmation message.

## Removed
- None.

## UI Changes
- New filter control in the Issues panel.

## Concepts
- No new canonical concepts.

## Tests
- 42 new tests.
- Existing test suite passed.

## Behavioural Coverage
- New behaviours have linked verification scenarios.

## Risks
- Mobile filter layout requires validation.

## Human Decisions Required
- Approve the new Issues filtering behaviour.

These numbers and changes are illustrative.

15.1 Review should focus on the difference

The human should review the changes in the Behavioural Documentation rather than rereading its entirety every day.

For example:

• 50,000 code lines changed.
• A few hundred lines of behaviour or UI documentation changed.
• Only a subset contains actual product decisions requiring approval.

These are illustrative magnitudes based on the development discussion, not a guaranteed reduction ratio.

The important point is that the volume of human review should be driven primarily by the number and complexity of meaningful decisions, rather than the number of code lines changed.

15.2 Technical review still has a role

Behavioural verification does not replace every technical concern.

Some errors may not be visible in ordinary UI scenarios.

Examples:

• Security vulnerabilities.
• Data corruption.
• Concurrency errors.
• Privacy violations.
• Resource leaks.
• Unacceptable performance regressions.
• Incorrect failure recovery.

These require additional automated checks, specialist review, or both.

The proposal is to reduce human review of routine implementation details, not to assume that functional testing proves every aspect of correctness.

---

16. Proposed System Capabilities

The documentation-management system should eventually expose several distinct operations.

These are conceptual capabilities, not necessarily existing command names.

16.1 Inspect

Analyze the current documentation structure.

Outputs:

• Folder inventory.
• File inventory.
• Relationship map.
• Detected documentation categories.

Read-only by default.

16.2 Audit

Evaluate documentation quality and consistency.

Outputs:

• Structured findings.
• Evidence.
• Severity.
• Confidence.
• Recommendations.

Read-only by default.

16.3 Initialize

Build the documentation foundation for a new or existing project.

Interactive and incremental.

Core process:

1. Inspect.
2. Discover major concepts.
3. Obtain human validation.
4. Investigate validated concepts.
5. Resolve aliases.
6. Define canonical terminology.
7. Extract behaviours.
8. Extract UI structure.
9. Extract styling.
10. Establish baseline.

16.4 Improve

Use an audit report to propose and apply corrections.

Possible improvements:

• Remove duplication.
• Clarify ambiguous definitions.
• Reorganize misplaced files.
• Add missing cross-references.
• Standardize terminology.
• Split mixed concerns.
• Update outdated descriptions.

Changes that alter product meaning require approval.

16.5 Synchronize

Compare source code, tests, and documentation.

Detect:

• Missing specifications.
• Stale descriptions.
• Undocumented features.
• Behavioural mismatches.
• Outdated screenshots.

Synchronization should propose changes rather than blindly assuming that source code is authoritative.

16.6 Verify

Check that the documentation remains internally consistent and aligned with approved behaviour.

Examples:

• Every referenced glossary concept exists.
• Every behaviour uses valid concept references.
• UI actions reference valid behaviours.
• No duplicate canonical identifiers exist.
• Folder contracts are respected.
• No unresolved contradictory product requirements remain.

16.7 Generate User Documentation

Produce user-oriented explanations, scenarios, and screenshots from validated specifications and application execution.

---

17. Migration Strategy for Heidrun Code

The existing system contains substantial work.

Migration should be incremental, controlled, and reversible.

Phase A — Understand the existing skills

First inspect:

• docs-folder-system.
• docs-folder-agents-rules-system.
• Their instructions.
• Their templates.
• Their internal conventions.
• Their dependencies.
• How they are invoked.
• How they create and update documentation.

Do not redesign them before understanding their actual behaviour.

Phase B — Inventory the existing documentation

Inspect /docs and the existing agent-rules directory.

Determine:

• Actual folder structure.
• Actual file count.
• Existing documentation categories.
• Duplicate concepts.
• Missing folder definitions.
• Unclear boundaries.
• Current generated versus human-maintained artifacts.

Produce a map of the current system.

Phase C — Produce the first audit

Create a report without editing the documentation.

Focus especially on:

• Glossary quality.
• Naming consistency.
• Mixed UI and Behaviour definitions.
• Missing cross-references.
• Duplicated information.
• Folder responsibility.
• Obsolete rules.

Phase D — Formalize the target architecture

Define:

• Folder contracts.
• Canonical concept format.
• Behaviour specification format.
• UI specification format.
• Styling conventions.
• Cross-reference rules.
• Ownership and approval rules.

Do not reorganize 121 files before agreeing on the target architecture.

Phase E — Establish the glossary

This should be the first major content migration.

Process:

1. Extract concept candidates.
2. Rank by confidence.
3. Ask for human validation.
4. Investigate aliases and historical meanings.
5. Establish canonical definitions.
6. Correct references and naming inconsistencies.

The glossary becomes the foundation for subsequent work.

Phase F — Separate Behaviour from UI

Analyze existing documents mixing layout and behaviour.

Extract:

• Product behaviour into Behavioural Documentation.
• Screen structure and control placement into UI Documentation.

Preserve references between them.

Avoid duplicating definitions.

Phase G — Normalize Styling

Review existing visual rules.

Consolidate them into a coherent design system.

Identify rules that are currently implicit in the UI implementation.

Phase H — Connect the Test Suite

Map tests to documented behaviours where practical.

Report:

• Behaviours with no relevant tests.
• Tests without an identified product behaviour.
• Conflicting expectations.
• Missing major user scenarios.

Initially, this can be a traceability and audit task.

More advanced adversarial verification can be introduced later.

Phase I — Continuous Maintenance

Integrate documentation checks into the development workflow.

The objective is to keep the documentation synchronized without creating a new productivity bottleneck.

---

18. Acceptance Criteria

A successful first implementation should satisfy the following conditions.

Structural

• Existing documentation and skills have been inspected.
• Every important documentation folder has a defined purpose.
• File placement rules are explicit.
• Documentation categories have clear boundaries.
• Cross-references can be checked automatically.

Auditing

• The system can produce a read-only audit report.
• Findings include evidence and confidence levels.
• Contradictions and duplication are detected.
• Missing or outdated information is identified.
• A human can review findings before corrective changes.

Initialization

• The system can extract concepts from an existing codebase.
• The system can consult Git history.
• Concepts are presented for human validation.
• Historical aliases can be investigated.
• Canonical terminology can be established.
• Initialization can proceed incrementally.
• Uncertain findings are not silently promoted into authoritative documentation.

Glossary

• Major concepts have canonical names and definitions.
• Relationships between concepts are represented.
• Historical aliases can be recorded.
• Other documentation can reference canonical concepts.
• Duplicated definitions are minimized.

Behaviour and UI

• Expected behaviour is separate from UI placement.
• Behavioural specifications reference glossary concepts.
• UI specifications reference behaviours.
• Important behaviour changes require human approval.
• The system can detect inconsistencies between specifications and implementation.

Maintenance

• A documentation audit can be repeated.
• The system proposes improvements from audit findings.
• Product-level changes can be summarized for human review.
• Purely internal code changes do not unnecessarily rewrite behaviour specifications.
• Existing documentation is migrated incrementally rather than destructively.

---

19. Open Design Questions

These questions remain unresolved and should not be treated as decisions already made.

19.1 Final folder layout

Should Glossary, Behaviour, UI, and Styling be direct subfolders of /docs/agent_rules, or should some areas be placed elsewhere under /docs?

19.2 Documentation representation

Should folder contracts and specifications be:

• Pure Markdown?
• Markdown with YAML frontmatter?
• Structured YAML or JSON?
• A hybrid?

The format should favor human readability while supporting automated validation.

19.3 Granularity

How large should a Behaviour document be?

Possible units:

• One user action.
• One user scenario.
• One feature.
• One bounded capability.

This needs experimentation.

19.4 Human approval policy

Which changes require explicit approval?

For example:

• New canonical concepts.
• Changed concept meanings.
• New behaviours.
• Removed behaviours.
• Major UI changes.
• Important architectural decisions.

Routine formatting should probably not require approval.

19.5 Evidence and traceability

How should documentation refer back to:

• Source code.
• Tests.
• Commits.
• GitHub issues.
• Pull requests.
• UI screenshots?

Stable references would be useful, but should not make the documents unnecessarily technical.

19.6 Behavioural test generation

Should tests be generated directly from Behavioural Documentation?

Should independent agents produce different test suites?

How should independence between specification, implementation, and tests be preserved?

19.7 Architectural documentation

How much internal system architecture must the human understand?

Where is the boundary between:

• Product-level overview.
• Important architectural commitments.
• Internal implementation details?

19.8 Scaling

How can the documentation remain compact enough for human review as the application grows?

Possible techniques include:

• Hierarchical summaries.
• Domain-specific documents.
• Change-focused reviews.
• Canonical references.
• Independent specification modules.

19.9 Ownership of the generated documentation

How does the system distinguish:

• Human-approved content.
• AI-generated proposals.
• Evidence extracted from implementation.
• Automatically generated user documentation?

This distinction is critical to preserving human control.

---

20. Recommended Implementation Order

The priority should be to improve the existing system before implementing every possible advanced capability.

Priority	Task	Rationale
P0	Inspect existing skills and directory structure	Understand what already works
P0	Define responsibilities of /docs and /docs/agent_rules	Establish clear boundaries
P0	Implement read-only audit and report	Make problems visible
P1	Define canonical glossary structure	Establish a stable conceptual foundation
P1	Implement concept discovery and human validation	Support reliable initialization
P1	Implement alias discovery and terminology normalization	Improve consistency
P1	Separate Behaviour from UI documentation	Establish clear ownership
P2	Normalize Styling and UI conventions	Improve generated UI consistency
P2	Establish traceability between behaviours and tests	Strengthen verification
P2	Integrate behavioural-change review into development	Reduce human review workload
P3	Generate user documentation and screenshots	Automate derivative documentation
P3	Extend independent adversarial verification	Improve long-term correctness

These priorities are a proposed order, not a previously finalized roadmap.

---

21. Immediate Next Task for a Coding Agent

Before writing a new implementation, perform a focused investigation of the existing repositories.

Task

Analyze the current /docs management architecture and propose an incremental evolution toward the system described in this document.

Repositories

• https://github.com/jeromeetienne/coding_agent_plugin
• https://github.com/heidrun-org/heidrun_code

Instructions

Step 1 — Inspect existing skills

Read the actual implementation of the existing general documentation skill and specialized agent-rules skill.

Determine:

• Their real locations.
• Their current responsibilities.
• How they interact.
• What they already support.
• What they do not support.
• Whether any responsibilities overlap.

Step 2 — Inspect the current project

Analyze the actual /docs hierarchy in Heidrun Code.

Focus on the existing agent-rules directory.

Produce a structural inventory.

Step 3 — Map the existing content to the proposed model

Classify existing content into:

• Glossary.
• Behaviour.
• User Interface.
• Styling.
• Platform Support.
• System Overview.
• Other.

Identify content that spans multiple categories.

Step 4 — Evaluate gaps

Determine which capabilities already exist and which must be implemented.

Focus on:

• Folder contracts.
• Auditing.
• Report generation.
• Initialization.
• Concept extraction.
• Human validation.
• Alias management.
• Behaviour/UI separation.

Step 5 — Propose a migration plan

Design an incremental plan that preserves existing useful documentation.

Explicitly identify:

• Files to preserve unchanged.
• Files that should move.
• Files that should be split.
• Missing documents.
• Changes required in the plugin skills.
• Human decisions required.
• Risks and compatibility considerations.

Step 6 — Report before modifying

Do not begin mass refactoring.

First produce a detailed proposal containing:

1. Current architecture.
2. Existing capabilities.
3. Structural problems.
4. Proposed target architecture.
5. Migration steps.
6. Relevant file paths.
7. Estimated scope.
8. Open questions.

Wait for human approval before making significant structural or semantic changes.

---

22. Long-Term Vision

The goal is not simply to write better documentation.

The goal is to establish a new development process adapted to AI-native software production.

Traditional development often follows:

Human writes code
       |
       v
Another human reviews code
       |
       v
Code is merged

The envisioned process is closer to:

Human defines product intent
             |
             v
       Validated Concepts
             |
             v
    Behavioural Specifications
             |
             v
      AI Implementation
             |
             v
    Automated Verification
             |
             v
    Behavioural Difference
             |
             v
    Human Product Review
             |
             v
       Integration

The human remains responsible for the product's direction, its conceptual coherence, and its intended behaviour.

The AI handles much of the implementation, detailed checking, and documentation maintenance.

The documentation system becomes the connection between human intent and AI implementation.

Core Principles

1. Human control at the right level

Humans must understand the product and make consequential decisions without needing to read all implementation details.

2. The glossary is foundational

A shared, precise conceptual vocabulary prevents ambiguity and inconsistency.

3. Behaviour is separate from implementation

What the application should do is not the same as how the code implements it.

4. Behaviour is separate from UI layout

What happens when an action occurs should not be unnecessarily duplicated wherever that action appears.

5. Styling is a reusable system

Visual consistency should come from explicit rules rather than repeated invention.

6. Auditing is a first-class capability

Documentation quality must be measurable and improvable.

7. Initialization is incremental and human-validated

AI extracts knowledge, but uncertain assumptions must not become authoritative without validation.

8. Adversarial verification reduces shared errors

Implementation, tests, and approved behavioural specifications should provide complementary checks.

9. Approved specifications must not silently follow implementation mistakes

Documentation must distinguish intended behaviour from observed behaviour.

10. Human review must scale with meaningful decisions, not code volume

This is the central motivation of the entire system.

---

23. Final Summary

The current Heidrun documentation system already has a useful foundation.

The existing separation into a general /docs skill and a specialized /docs/agent_rules skill provides a promising starting architecture.

The immediate objective is to formalize this system, not rebuild it blindly.

The first major capabilities to develop are:

1. Clearly define every important folder and subfolder.
2. Audit existing documentation and produce actionable reports.
3. Initialize documentation from source code, Git history, and existing artifacts.
4. Build a human-validated canonical glossary.
5. Detect aliases and enforce terminology consistency.
6. Separate Behaviour from User Interface descriptions.
7. Maintain consistent Styling rules.
8. Preserve relationships between concepts, behaviours, interfaces, and tests.
9. Support independent automated verification.
10. Make the system suitable for human review at AI development velocity.

The first concrete step should be a read-only inspection and audit of the current implementation, followed by a migration proposal.

The longer-term ambition is to transform documentation from a secondary artifact into the human-readable specification that governs AI-generated software.

The essential idea: humans should supervise the evolution of the product, while AI agents handle much of the rapidly growing implementation detail.

---

Discussion captured: October 26, 2026.
This document records the brainstorming and proposed architecture. It is not a verified audit of the current repository contents. Actual paths, implemented capabilities, and migration details must be checked against the source code before execution.

Add an executive summary and decisionsRemove repetition and shorten the document