---
name: Arco system manual
version: 1.2.0
status: active
owner: Stoirm Arnold
last_updated: 15-Sep-2026
---


# Arco system manual


## Purpose


This is the universal operating manual for maintained Arco system files.


It defines rules that apply across deployments, including naming, metadata, versioning, ownership, changelogs, change control, release archives, rollback and maintenance behaviour. Specialist module READMEs define module-specific behaviour and should not duplicate these universal rules.


This standard applies to files maintained as part of the AI operating/context layer. It does not apply to ordinary working documents, articles, notes, reports, spreadsheets, source material or client deliverables merely because an AI may read them.


## Source and deployed naming


Arco Core source files use stable `arco-*.md` filenames.


When a Core operating file is deployed into an organisation, its deployed operating copy uses the equivalent stable `readme-*.md` filename unless the deployment standard explicitly defines another name.


Where deployment-specific configuration is required, keep it in a separate `readme-*-local.md` companion file. The deployed operating file should point to that local file once rather than duplicating local paths or identifiers.

### Upstream Core source and update comparison

Each deployed operating README derived from Arco Core should identify exactly one upstream Core source for update comparison. The deployed local copy remains the runtime source of truth for that deployment; the upstream reference is for maintenance and update checking, not live runtime dependency.

- Stoirm Ltd may reference the corresponding file under `/Arco`.
- External organisational deployments may reference the corresponding canonical file at `arco.stoirm.co.uk` once that distribution endpoint is live.
- Do not duplicate the upstream source pointer across routers, local configuration files or other system files.
- Generic improvements intended for Arco Core should be applied to the Core `arco-*` source and then distributed/reconciled into deployed `readme-*` copies.
- Deployment-specific configuration belongs only in the relevant `readme-*-local.md` or other designated local configuration source and must not be pushed into Core unless deliberately generalised.
- Periodic deployment housekeeping should compare deployed Core-derived files against their upstream source and surface drift; the exact housekeeping mechanism is deployment design and may evolve separately.


All maintained AI instruction files must:
- use Markdown (`.md`);
- use lowercase filenames;
- use hyphens between words;
- contain no spaces;
- use a stable filename without a version number in the canonical filename.


Examples:
- Core: `arco-skills.md`, `arco-context.md`, `arco-system-manual.md`
- Deployed: `readme-skills.md`, `readme-context.md`, `readme-system-manual.md`
- Local: `readme-skills-local.md`, `readme-system-manual-local.md`


### Subsystem README convention


Subsystem READMEs should describe their own domain without depending on an umbrella product or system name unless operationally necessary.


Use a simple human-readable name such as `Skills operating guide`, `Personas operating guide` or `Context operating guide`.


Keep each subsystem README to the minimum rules needed to understand and operate that subsystem. If substantial implementation detail can be isolated without losing operational clarity, put it in a dedicated supporting file and reference it from the README.


### Draft subsystem files


A new or materially redesigned subsystem may begin as a `0.x.x` draft before it is ready for deployment.


A draft README may capture design thinking, but it must distinguish clearly between:
- **Confirmed decisions** — agreed and safe to treat as current design constraints;
- **Provisional direction** — likely choices still requiring validation;
- **Open questions before v1** — unresolved decisions that must be confirmed, changed or removed before `1.0.0`.


Draft files must not be routed into live use merely because they exist. Add them to live routing only when intentionally used or tested in that deployment.


A `1.0.0` release means the foundational operating model is sufficiently resolved for deployment. It does not mean every future feature or edge case has been designed.


## Standard YAML frontmatter


All maintained AI instruction files must begin with the same core YAML fields:


```yaml
---
name: Human-readable file name
version: 0.1.0
status: draft
owner: Individual or system responsible for the file
last_updated: DD-MMM-YYYY
---
```


Additional fields may be added only where they serve a clear operational purpose.


### Owner


`owner` must identify the individual or system responsible for the file.


Valid examples include an individual or an AI system/model. Do not use a company, department or other organisational entity as the owner.


Where ownership is personal, resolve the individual from the relevant context layer when available.


## Date format


All dates inside maintained AI instruction files must use `DD-MMM-YYYY`.


This includes YAML metadata, changelogs, review dates, approval dates and other operational dates.


Use the date directly in YAML, for example:


`last_updated: 14-Sep-2026`


## Versioning


Use semantic versioning inside the file:
- patch: wording clarification, formatting correction or non-material fix;
- minor: backward-compatible behavioural or structural improvement;
- major: material change to purpose, triggers, behaviour or operating model.


The canonical filename remains stable when the version changes.


Every approved content change to a maintained AI operating/context file must result in a version change. There are no silent content edits.


When a maintained file changes:
1. increment the internal version appropriately;
2. update `last_updated`;
3. add a changelog entry describing the change;
4. save and verify the file;
5. tell the user the new version in the completion message.


Revision history is an additional recovery layer; it does not replace explicit release archives for minor and major versions.


### Release archive


When publishing a **minor or major** version, preserve the outgoing released version as an immutable archived copy **before** replacing the canonical file. Patch-only changes do not require a separate archived copy.


Every maintained file has its own archive subfolder. Do not mix different files' release snapshots in one flat archive folder.


The deployment's local configuration defines the actual canonical and archive roots. Within those roots:
- a file inside a subsystem/module folder uses that folder's `Archive/<canonical-file-stem>/` directory;
- a file at the deployment root uses the deployment's configured root archive directory under `<canonical-file-stem>/`.


Arco Core source files follow the same relative rule inside `/Arco`: root Core files use `/Arco/Archive/<canonical-file-stem>/`; module files use the module folder's `Archive/<canonical-file-stem>/`.


Archive filename format:


`<canonical-file-stem>-vMAJOR.MINOR.PATCH.md`


Archived releases are immutable. Rollback restores the behaviour/content of an archived release into the canonical file as a **new version**; do not reduce the version number.


## Universal change roles


Use the following terminology consistently across registers, approval workflows and maintained-system records:
- `Proposed by` — individual or system originating a proposed durable change;
- `Approved by` — individual authorising the change where approval is required;
- `Changed by` — individual or system actually applying or publishing the change.


The same individual may occupy more than one role where the deployment permits it. Do not create duplicate fields merely to record identical information where a workflow does not need all three roles.


A completed-file changelog does not require a `Proposed by` column by default because it records applied changes rather than pending proposals.


## Changelog standard


All working maintained AI instruction files must include a `## Changelog` section.


Use:


| Date | Version | Change | Approved by | Changed by |
|---|---|---|---|---|


Rules:
- dates use `DD-MMM-YYYY`;
- `Approved by` names the individual who approved the change where approval is required;
- do not use a company name where an individual approver is known or expected;
- `Changed by` identifies the individual or AI model/system that actually made the change;
- where a reliable model/configuration name is available, record it;
- never infer or invent model/configuration details;
- if a human directly changes the file, record that human.


## Creation and editing rules


Before creating a new maintained AI instruction file:
1. read the deployment's AI routing guide;
2. read the deployed system manual;
3. read the relevant subsystem README, if one exists;
4. check whether an existing file should be updated instead of creating a near-duplicate;
5. use the smallest structure necessary for the file to remain clear and operational;
6. isolate substantial supporting detail where possible rather than bloating the README.


When editing an existing maintained AI instruction file:
1. preserve the stable filename unless a rename is explicitly approved;
2. update the internal version appropriately;
3. update `last_updated`;
4. add a changelog entry;
5. preserve unrelated behaviour and content;
6. verify the saved file after writing.


### Canonical replacement fallback


If a maintained canonical file cannot be reliably rewritten in place:
1. preserve the outgoing released version in its required archive location;
2. rename or otherwise retire the outgoing canonical if necessary;
3. create a new file using the original canonical filename;
4. preserve the intended canonical path/location;
5. update the single authoritative pointer or identifier that references the canonical file;
6. verify that downstream routing still resolves correctly;
7. record the canonical file-ID replacement in the changelog/change record.


Do not duplicate updated IDs across multiple files. Update only the authoritative pointer defined by the deployment architecture.


## Validation before promotion

A maintained Arco change that materially alters purpose, scope, operating behaviour, routing, responsibilities, interpretation, dependencies or system structure must be validated before promotion according to `arco-dry-runs.md`.

A major version change normally meets this threshold. A minor version may also meet it when the behavioural or structural risk is material. Patch-only corrections normally do not.


## Routing and token efficiency


The deployment's `readme-ai-guide.md` is the routing layer, not the system manual. Keep universal operating rules in the system manual rather than duplicating them in the AI guide.


The AI guide should point assistants to the smallest relevant set of files. Specialist READMEs should be read only when the task enters their domain.


## Relationship to subsystem READMEs


This file defines universal conventions.


Subsystem READMEs define rules specific to that subsystem and should not duplicate universal standards unnecessarily.


## Changelog


| Date | Version | Change | Approved by | Changed by |
|---|---|---|---|---|
| 15-Sep-2026 | 1.2.0 | Added the single universal validation gate for material maintained-system changes and routed execution to `arco-dry-runs.md`. | Stoirm Arnold | GPT-5.6 Sol |
| 14-Sep-2026 | 1.1.0 | Added the upstream Core source/update-comparison rule so deployed Core-derived READMEs identify one authoritative Core source while remaining runtime-independent. | Stoirm Arnold | GPT-5.6 Sol (Medium) |
| 14-Sep-2026 | 1.0.0 | Extracted the universal system manual into Arco Core, added Core/deployed/local naming, generic archive-root rules, and a canonical-replacement fallback for unreliable in-place rewrites while preserving deployed behaviour. | Stoirm Arnold | GPT-5.6 Sol (Medium) |