Symbiospec: workflow guide

The issue describes the workflow guide and reusable documentation skills, but does not name specific files, tests, or entry points. Start by locating the existing Symbiospec definition and documentation skills in the repository, then compare their current guidance with the proposed Initialization, Update, and Realignment workflows. Done means the guide clearly distinguishes the format from its workflows and accurately presents the proposed process without claiming it is already implemented or verified.

Symbiospec Workflow Guide

0. Introduction

0.1. Purpose and status

Defines the purpose of the guide and distinguishes the Symbiospec format from the workflows used to put Symbiospec into practice. Introduces Initialization, Update, and Realignment as proposed workflows to develop and verify.

0.2. Initialization

Explains how to establish Symbiospec when starting new software or introducing Symbiospec into existing software. Existing software follows slow growth: validate a small, coherent foundation, then expand through repeated cycles across the relevant documentation sections. An earlier Symbiospec is preserved and migrated rather than discarded.

0.3. Update Symbiospec as the software changes

Explains how the coding agent keeps Symbiospec current within the same task as a software change. Updates follow the human's existing authorization, while additional product decisions remain explicit and unchanged product behaviour does not need to be rewritten.

0.4. Realign Symbiospec when drift is detected

Defines the periodic comparison of Symbiospec, the software, and relevant tests to detect drift that normal updates may have missed. Explains how to report differences, review corrections, apply authorized changes, and verify the results without silently replacing approved intent with observed implementation behaviour.

0.5. Symbiospec definition and structure

Points to the original design proposal explaining the purpose, concepts, and proposed documentation structure behind Symbiospec. Provides the conceptual foundation for this guide's practical workflows.

1. Purpose and status

This guide proposes how a project starts using Symbiospec, establishes an approved baseline, and keeps the software and Symbiospec aligned over time. The guide describes a workflow to develop in the reusable documentation skills; it does not claim that the workflow is already implemented or verified.

The Symbiospec format defines the content, section responsibilities, organization, and placement of the specification. This guide addresses a separate question: how to use Symbiospec in real development. The workflows use the agreed format; the workflows do not replace the definition of the format.

Symbiospec is a shared specification through which humans and artificial intelligence define and build software together. Symbiospec describes product concepts, expected behaviours, interface structure, styling, supported environments, and the overall organization of the system. Each area must have a clearly defined responsibility, explicit exclusions, and references to information owned by other areas.

Symbiospec has three operations: Initialization, Update, and Realignment. Initialization establishes Symbiospec for a project. Update keeps Symbiospec current as the software changes. Realignment periodically detects and resolves drift between Symbiospec and the software. Update and Realignment repeat throughout development; these operations are not a one-time sequence.

2. Initialization

Initialization has two main cases: the software does not exist yet, or the software already exists.

2.1. New software

Create the agreed folder structure and copy the relevant templates and coding-agent instructions. This is a small setup operation: there is no existing implementation to reconstruct. Empty templates do not count as approved product definitions.

Then move directly into Update. Define the first product concepts, expected behaviours, and relevant constraints as development begins, and develop the software and Symbiospec together. Start with the smallest useful scope rather than attempting to specify the entire future product.

2.2. Existing software

Inspect the existing project before writing authoritative specifications. Sources may include documentation, source code, tests, Git history, issues, pull requests, and direct observation of the application where permitted.

Build Symbiospec incrementally through the initialization process below. The existing implementation provides evidence, but existing implementation behaviour is not automatically the intended product behaviour.

If an earlier Symbiospec exists, preserve and migrate the existing specification rather than starting again. This is a variation of initialization, not a fourth operation.

Audit the existing specification before restructuring the documentation. Identify useful definitions, existing approvals, gaps, duplication, contradictory expectations, and sections that mix different responsibilities.

Preserve validated content and recorded decisions. Propose changes in bounded batches, explain moves and splits, and retain traceability to the previous content. An unclear approval history must remain explicit rather than being treated as evidence of approval.

2.3. Initialization process for existing software

Initialization follows slow growth: build a small, trusted foundation, review and correct that foundation, then expand progressively. The human must be able to understand the concepts, follow their relationships, and validate each increment.

A mistaken concept can affect many descriptions built on that concept. Small reviewed increments limit the propagation of errors, reduce the cost of correction, and preserve validated work. Progress is measured by coherent, human-validated coverage rather than the amount of documentation generated.

The documentation format must provide clear section responsibilities and exclusions. For example, the Glossary defines a Macro, Behaviour defines the expected result of execution, User Interface defines where execution is exposed, and Styling defines the appearance of the relevant controls. These boundaries apply within every cycle.

2.3.1. Identify a few clear concepts

Inspect the project instructions, available evidence, and a bounded part of the software without modifying the software. Start with a few of the most evident, well-supported concepts and their relationships. Priority comes from clarity and confidence, not the size of a feature. Record uncertainties and the limits of the investigation.

2.3.2. Validate the initial glossary

Prepare proposed names, definitions, relationships, and concrete examples with supporting evidence. Review the proposals with the human and correct misunderstandings before relying on those concepts for further descriptions. Establish one canonical identity and one canonical name for each accepted concept; investigate historical aliases rather than assuming equivalence.

2.3.3. Document a small, coherent part of the product

Describe the relevant behaviours, interface, and other applicable rules around the accepted concepts. Each cycle works across the relevant sections. Completing the entire Glossary before documenting any Behaviour or User Interface is not required.

Keep observed implementation, proposed specification, and approved specification distinct. Existing code and tests provide evidence, but do not automatically establish intended behaviour. Record unresolved differences explicitly.

2.3.4. Review a prepared batch

Complete the investigation and prepare proposals before requesting the human's attention. Each proposal states the decision, reason, concrete example, affected scope, and significant consequences. Group dependent decisions and explain their relationship before requesting approval.

Review the prepared proposals in quick succession. Record whether the human accepts, rejects, revises, or defers each proposal. Do not restart a lengthy investigation between short responses; questions requiring substantial new analysis go into a later batch. After review, apply approved changes and prepare the next batch.

2.3.5. Correct and establish a trusted foundation

Incorporate corrections and return changed product meaning for review. Confirm that the documented part is coherent and understood by the human. Record the approved scope, decisions, evidence, unresolved questions, and known differences. Approval of the documentation does not prove that the software has passed behavioural tests.

2.3.6. Expand and repeat

Select the next most evident concepts or deepen existing descriptions, building on the validated foundation. Repeat the cycle and check how each addition connects to the existing Symbiospec. Preserve approved work; changes to earlier decisions remain explicit. Compatibility analysis is required before changing names in public interfaces or stored data.

Each cycle leaves a useful, explicitly scoped baseline. Keep partial coverage visible, and use Update for subsequent software changes within the established scope while initialization continues elsewhere.

3. Update Symbiospec as the software changes

Update is part of the normal development task. The human discusses a change with the coding agent, and the coding agent develops the software and Symbiospec together as closely as possible.

Project-level agent instructions and relevant skills must tell the coding agent to identify which parts of Symbiospec are affected by each software change and update those parts in the same task. Changes may affect concepts, expected behaviours, interface structure, styling, platform constraints, or the System Overview. Internal implementation changes do not require rewriting unchanged product behaviour.

Existing human authorization for the requested product change applies; the process should not ask the human to approve the same decision again. New product decisions beyond that authorization must be presented for review. Routine documentation updates within the approved scope can happen automatically, but an unexpected implementation result must not silently become an approved requirement.

When additional product decisions need review, prepare the proposals together before requesting the human's attention. Include the reasons, examples, affected scope, consequences, and dependencies. Record rapid decisions to accept, reject, revise, or defer without lengthy investigations between responses. Defer questions requiring new analysis, apply authorized changes, and return revised product meaning for approval before adoption.

Update aims to prevent drift during development. Update does not guarantee that every difference has been found, which is why Realignment is a separate operation.

4. Realign Symbiospec when drift is detected

Realignment periodically compares the current Symbiospec with the current software and relevant tests to detect and resolve drift. Realignment can also be requested when a difference is suspected. Realignment examines the selected scope as a whole, including differences that individual development tasks may have missed.

4.1. Compare without modifying

Identify the approved specification and inspect the implementation and relevant tests within an explicit scope. Use direct application observation where useful and permitted. Record what was examined, what was not examined, and the limits of the available evidence.

4.2. Report differences

Report outdated or missing descriptions, undocumented capabilities, contradictory expectations, implementation regressions, and missing or conflicting test coverage. Each finding should identify the affected specification, observed result, supporting evidence, confidence, and proposed correction. Distinguish established differences from uncertain findings.

4.3. Review proposed corrections

Complete the investigation and prepare correction proposals in batches before requesting the human's attention. Each proposal states the decision, reason, concrete example, affected scope, significant consequences, and dependencies. A correction may change the software, Symbiospec, the tests, or a combination.

Review the prepared proposals in quick succession and record decisions to accept, reject, revise, or defer. Do not restart a lengthy investigation between short responses. Questions requiring new analysis go into a later batch; revised product meaning returns for approval before adoption.

Approved intent remains the reference. Never rewrite an approved specification simply to make an unintended implementation change appear correct. Conversely, do not assume that every existing description remains the desired product definition: propose a change when evidence suggests a deliberate product decision is needed, and obtain that decision before changing approved meaning.

4.4. Apply authorized corrections

Apply corrections within the human's authorization and preserve the decisions and evidence that explain the corrections. Do not reinitialize the whole Symbiospec merely because some sections have drifted.

4.5. Verify the result

Repeat the relevant comparisons and checks. Report resolved findings, unresolved findings, and remaining coverage limits. Do not claim complete alignment when only part of the product was examined.

Realignment produces a comparison report, recorded decisions, and verified corrections where authorized. The frequency, scope-selection rules, and any automation remain to be defined; this proposal does not establish a recurring schedule.

Symbiospec supports human review of meaningful product changes. Technical checks remain necessary for concerns such as security, data integrity, performance, and failure recovery.

5. Symbiospec definition and structure

The original design proposal explains the problem Symbiospec addresses, the proposed documentation areas and their responsibilities, and the relationship between human product decisions, specifications, implementation, and tests. The workflow guide describes how to use that foundation in a project.

Read the original design proposal here:

• https://github.com/jeromeetienne/coding_agent_plugin/issues/10