---
name: Arco development
version: 0.19.0
status: draft
owner: Stoirm Arnold
last_updated: 15-Sep-2026
---

# Arco development

## Purpose

This file holds evolving Arco architecture, unresolved design questions and development direction that are not yet mature enough to become canonical operating rules.

The definition of Arco itself lives only in `arco-readme.md`.

When an item here becomes sufficiently defined and is implemented, move the durable rule to the relevant canonical Arco or subsystem file rather than maintaining two competing descriptions.

## Established decisions

### Architecture

- `readme-ai-guide.md` is deployment-specific routing only and should remain small for context/token efficiency.
- Arco Core source files use `arco-*.md`; deployed operating copies use `readme-*.md`; deployment-only configuration uses `readme-*-local.md` where required.
- Core source files are distributed into deployments rather than referenced remotely at runtime. Each deployed Core-derived README records one upstream Core source for update comparison while remaining runtime-independent.
- Deployed READMEs should own only their next-hop local pointer; downstream paths and identifiers should have one authoritative home to avoid duplicated references.
- `arco-system-manual.md` is the Core universal maintenance standard. Stoirm Ltd deploys it as `AI/readme-system-manual.md` with `AI/readme-system-manual-local.md` holding only local root/archive configuration.
- `arco-readme.md` is the Core definition of Arco; a deployment copy, where genuinely required, is named `readme-arco.md`. The Core-hosting organisation does not need a redundant deployed copy when Core itself is intentionally used directly.
- Material maintained-system changes have a formal validation layer owned beneath the System Manual; operational validation instructions stay outside development notes to preserve the routing waterfall.
- Specialist subsystems own their detailed rules through their own READMEs.
- `arco-design.md` is the Core architectural-memory artifact: it records why structural choices were made and meaningful alternatives rejected, while canonical operating files retain behavioural authority.
- Collections of independently maintained assets that may be updated by different users should normally have a structured register.
- Registers contain index/governance metadata rather than duplicating executable instructions.
- Google Sheets are currently preferred for structured registers where filtering, ownership, status and future dashboard use matter.

### Deployment extraction pattern

Confirmed through the System Manual Core/deployed/local extraction and validation on 14-Sep-2026:
- start from the working deployment file;
- extract organisation-agnostic behaviour into the Core `arco-*` source file;
- keep the deployed `readme-*` behaviour equivalent;
- move only deployment-specific paths, identifiers and roots into `readme-*-local.md`;
- archive the outgoing deployed release before a minor/major replacement;
- promote the Core file and deployed/local files only after equivalence passes;
- verify saved raw Markdown after promotion.

The System Manual is the first proven non-module implementation of this pattern. Skills and Personas are fully promoted module implementations. Skills uses `/Arco/modules/skills/arco-skills.md` → `AI/Skills/readme-skills.md` + `readme-skills-local.md`. Personas uses `/Arco/modules/personas/arco-personas.md` → `AI/personas/readme-personas.md` + `readme-personas-local.md`.

For Stoirm Ltd, upstream source pointers may resolve to `/Arco`. For external organisational deployments, the intended distribution source is `arco.stoirm.co.uk` once live. Periodic housekeeping should compare deployed Core-derived READMEs with their recorded upstream source; the exact distribution/update mechanism remains to be designed.

### Adaptation and maintenance

- Every maintained file content change produces a version change, `last_updated` change and changelog entry.
- Minor and major releases preserve the outgoing version in an immutable per-file archive folder.
- Patch changes rely on Drive revision history plus the changelog rather than creating archive files.
- Durable adaptation should be visible to the user, but reporting should stay concise.
- The system should only adapt when a real run, correction or change provides material evidence for doing so.
- `arco-modules.md` must be updated in the same development change whenever the change materially affects a module's existence, scope, lifecycle state or relationship to other modules.

### Skills

- Skills are maintained capabilities, not static prompts.
- Skills use stable canonical filenames; versions live inside the file.
- The Skills Register uses stable `SKL-###` identifiers.
- A Skill run may expose a useful change to the Skill; maintenance follows the deployment's approval policy.
- Skills Core/deployed/local extraction and promotion was completed successfully on 14-Sep-2026, with the AI guide reduced to the single Skills first-hop.

### Governance

- Governance is now treated as a foundational Arco subsystem for organisational deployments rather than a normal optional module.
- `arco-governance.md` owns the top-level authority model and routes to Roles, Permissions and Approvals without duplicating their detailed rules.
- The System Governor is a required Arco Role for an organisational deployment.
- Champion is an established optional Arco Role for trusted contributors who may propose governed changes without automatically holding publication or approval authority.
- Approval remains a reusable Governance mechanism rather than something each module should redefine.
- Decisions remains a separate optional module that may consume Governance for access, authority and approval.
- Stoirm's personal Arco deployment may still operate with minimal or no explicit approval rules where appropriate.

## Emerging components

### Context

Implemented foundation:
- `AI/context/readme-context.md` is the canonical Context operating guide;
- the org chart is the default bootstrap source of truth for organisational structure in a new organisational deployment;
- deployment identifies authoritative sources and canonical public/private storage;
- the system may maintain local machine-readable representations of authoritative sources without replacing them as authority;
- Organisation, Organisational Unit and Person are the foundational Context entities;
- Context distinguishes organisational fact, self-authored/self-verified context and private context;
- organisational deployments should maintain a structured Context Register for accountability, completeness, verification and freshness state;
- Context is loaded selectively.

Deployment state:
- the Context subsystem is not yet live in the Stoirm Ltd deployment and must not appear in `readme-ai-guide.md` routing until intentionally enabled or tested there.

Still to define or implement:
- the detailed Context Register schema;
- supporting schemas only where real deployment needs justify them;
- the Turntabl migration from the existing prototype into the canonical model;
- downstream acquisition/update skills such as `company-context-builder`;
- the relationship between foundational Context and faster-changing context such as current strategy/priorities.

### Personas

Direction established:
- a Persona defines how the AI thinks, interprets or reviews rather than a workflow;
- Personas are maintained separately from Skills;
- multiple Personas should eventually have a structured Personas Register.

Still to define:
- register schema;
- ownership/edit rules;
- whether Personas adapt through use in exactly the same way as Skills;
- deployment defaults and persistence behaviour.

### Approvals

`arco-approvals.md` is the Core draft for the reusable Governance approval mechanism.

Established direction now includes:
- Approvals is the shared consent mechanism used when an action requires consent; it does not own a separate global enable/disable model;
- `arco-module-manual.md` owns the two universal per-module controls: Automatic system updates and Output approval;
- Permissions define the authorised population for a module or action; approval requirements apply only after that authority boundary is satisfied;
- Automatic system updates governs publication of eligible validated deployed/local operating/configuration changes, while Output approval governs the module's actual outputs;
- deployment/System Setup owns the selected values for those controls and cannot grant authority over upstream Arco Core;
- real interactions may generate proposed changes against the maintained deployed/local file that owns the behaviour;
- where approval is required, proposed changes should be queued by owning file, reconciled when multiple proposals overlap, tested together through Dry Runs, then presented as one coherent candidate to the configured approving authority;
- the System Governor is a fallback for maintained system changes only when Automatic system updates are OFF and no more specific valid approving authority is configured;
- the default approval flow is one stage, with optional sequential stages where real use requires them.

Still unresolved cross-system questions include final rule precedence, delegation/absence, quorum/parallel approval semantics, the exact proposal-queue representation, and how approval configuration is represented in the canonical deployment system-setup record.

### Roles and Permissions

Core drafts now exist for `arco-roles.md`, `arco-permissions.md` and `arco-approvals.md` beneath `arco-governance.md`.

Established direction:
- System Governor is a required Arco Role for organisational deployments.
- Champion is an optional Arco Role.
- VIP is an emerging Arco Role concept for a trusted person who may receive broader or exceptional authority based on demonstrated skill/trust rather than organisational job title. VIP is not yet promoted into the Core Roles definition and its permissions remain deliberately unresolved.
- Permissions are atomic action-plus-resource/scope rights.
- Permission Groups are reusable bundles of Permissions.
- organisational attributes such as job title, team or unit may map to Roles or Permission Groups without becoming the permission system themselves;
- Context permissions should reference stable Context IDs owned by the Context Register rather than creating a duplicate resource catalogue;
- Approvals is the shared mechanism for actions requiring consent before execution.

Still to resolve through real deployment:
- default user permissions;
- baseline System Governor and Champion permissions;
- VIP scope and permission boundary;
- permission precedence/conflict rules;
- the final Approval Rule schema and any multi-approver/delegation mechanics.

### Deployment configuration

Design-stage decisions and unresolved questions live in `arco-deployment.md`.

Current direction:
- deployments likely need a small canonical system-setup/configuration record stating which modules and operating layers are enabled;
- system setup should instantiate the universal per-module controls defined by `arco-module-manual.md` rather than redefining them;
- the deployed `readme-ai-guide.md` should reflect that enabled state rather than independently defining it;
- `arco-ai-guide.md` is best treated as a deployment template for constructing the organisation-specific router, not as a runtime Core router copied verbatim;
- the exact system-setup filename/schema and automation mechanism remain unresolved and must not be promoted yet.

Cross-system questions that remain relevant here:
- how Approvals, Roles, Permissions and Deployment interact without duplicating rules;
- how future Core updates reconcile with local deployment configuration;
- how deployment health and structural drift should be surfaced.

### Module Manual and Module Builder

`arco-module-manual.md` is now the canonical universal contract inherited by every Arco module.

Established direction:
- the Module Manual owns universal module requirements and standard module configuration hooks;
- `arco-system-manual.md` remains the sole owner of maintained-file construction, versioning, archives, change control and validation triggers;
- individual module READMEs own only module-specific behaviour;
- deployment/System Setup owns the selected values for each enabled module;
- Governance owns Permission and Approval mechanics;
- a future Module Builder should consume the Module Manual and System Manual rather than embedding duplicate rules.

Module Builder remains a future capability. Its eventual interface, automation mechanism, validation flow and publishing/distribution model are unresolved.

### Policies

Emerging module candidate.

Policies would provide a maintained organisational policy layer that AI can use and help keep current. The module should support local ownership by the relevant organisational function rather than assuming every policy change needs System Governor approval.

Established direction:
- Policies should be configurable as a module in system setup and inherit the universal controls from `arco-module-manual.md`;
- its output approval setting governs whether authorised People Operations users may publish eligible Policy outputs directly or require consent before they become final/effective;
- its automatic system updates setting governs whether validated changes to the module's deployed/local operating/configuration layer may publish automatically or require the maintained-system approval route;
- Policies should consume shared Governance for authority/approval mechanics and Context for organisational ownership/membership rather than inventing its own permission or approval engine.

Still to define:
- the exact boundary between a Policy, policy source document and policy register;
- whether policy content is stored directly in Arco or references existing authoritative policy documents;
- how policy conflicts, supersession, review dates and employee acknowledgement should work;
- the eventual Core file and deployment structure.

### Arcopsy

Emerging deployment-review concept.

Arcopsy reviews the **existing local environment that Arco is being deployed into** and compares that environment with Arco before or during deployment.

Its purpose is to identify:
- existing instructions, structures or configuration that contradict Arco;
- duplicate functions or competing sources of truth;
- existing local sources Arco should reuse rather than recreate;
- local rules that would legitimately override or constrain a deployment;
- legacy structures that require reconciliation before Arco is made live.

Arcopsy is not the ongoing internal architecture review of Arco itself. It is specifically the compatibility/reconciliation review between Arco and the host environment.

Arcopsy is not yet a confirmed module. Its exact implementation, trigger, output and relationship to Deployment remain to be designed. Deployment should eventually invoke or require it without duplicating Arcopsy's review rules.

### Defrag

Promoted to Core on 15-Sep-2026.

The live maintenance function is now defined by `arco-defrag.md`. The first real Defrag established enough evidence to resolve its v1 scope, manual trigger, correction boundary, reporting shape and relationship to Dry Runs.

Future changes to Defrag belong in the canonical function unless they are genuinely unresolved architectural questions. Do not maintain a parallel operating definition here.

### Design rationale / architecture record

Promoted to Core on 15-Sep-2026.

`arco-design.md` is now Arco's architectural memory.

Established boundary:
- Design records **why** architectural choices were made;
- it records meaningful alternatives deliberately rejected or avoided, not only chosen approaches;
- it is organised by architectural area rather than as a chronological diary;
- when an architectural decision is superseded, enough prior rationale should remain visible to prevent accidental rediscovery of an already-understood failure or trade-off;
- Design references canonical operating files rather than duplicating their instructions;
- canonical operating files still govern current behaviour if wording ever conflicts;
- `arco-development.md` remains the home for unresolved/emerging architecture, while resolved durable rationale moves into Design;
- Design should be consulted for architecture changes and future Defrag work, not loaded as routine runtime instruction.

Still to learn through use:
- the right level of detail as Arco accumulates more decisions;
- whether sufficiently complex future modules need separate design records or whether the single Core Design file remains clearer;
- what future Defrag cadence should trigger explicit design-rationale review.

### Module discovery and system visibility

Provisional direction:
- maintain a single canonical Module Register listing available modules and their lifecycle state;
- module state may include active, disabled, draft, beta or testing, with exact terminology still to be confirmed;
- deployment configuration should determine which modules are enabled for a particular deployment;
- users should be able to ask a natural-language question such as `What can you do?` and receive a current view of enabled capabilities, clearly separated from draft, preview or unavailable modules;
- the eventual dashboard should read maintained registers rather than becoming a competing source of truth.

Open questions:
- whether the Module Register is itself part of Deployment, a wider system registry, or a separate maintained register;
- which module states are actually necessary before v1;
- how capabilities exposed by external systems or connected services appear alongside native modules.

### Installation and working-data boundary

Confirmed direction:
- the dedicated Arco folder represents where the operating system is installed and maintained;
- ordinary business work does not need to be moved into that folder;
- deployments should continue to use the organisation's existing working locations and authoritative systems, with the operating system storing configuration, maintained instructions, registers and local machine-readable representations where required.

### Story mode / narrative interface

Exploratory concept only.

An optional Story Mode could represent system state as a living world or kingdom. Modules might appear as towns, buildings or landmarks, while maintenance, outages, upgrades or newly available modules could be expressed as corresponding narrative events.

The narrative should be generated from real system state rather than creating a second source of truth, and it must be completely optional and switchable off.

Earlier exploration has included role metaphors such as the High Council, Arch Governor, Hands, Enforcers and Trusted Pedestrians. These remain narrative language only and must not be treated as canonical system roles unless deliberately promoted later.

### Dashboard / human interface

Concept only.

Potential role:
- show enabled/disabled Arco components;
- show current versions and health/state;
- provide human-readable access to registers and governance state;
- surface Context health such as profile verification, completeness, accountability and source freshness;
- expose live capability discovery based on deployment/module state;
- eventually allow configuration changes without requiring people to edit Markdown directly.

The dashboard should be a view/control layer, not a competing source of truth.

### Central update distribution

Concept only.

Longer-term intent is that Arco Core improvements can be published centrally and adopted by deployments without overwriting deployment-specific context or configuration.

The intended public distribution endpoint is `arco.stoirm.co.uk`, but its information architecture, publishing mechanism and update flow are not yet canonical.

Still to define:
- public Core file structure and URLs;
- update manifest/versioning;
- compatibility checks;
- conflicts and local overrides;
- opt-in/automatic update policy;
- rollback across deployments.

## Open architecture questions

- What is the exact boundary between a Skill, a playbook and the wider Arco system?
- What is the final Approval Rule schema and what granularity is actually needed after Turntabl proves the mechanism?
- Should an organisational-unit Permission grant inherit down the organisational hierarchy by default, and how should explicit restrictions interact with that inheritance?
- Which registers should exist beyond Skills and Personas?
- What belongs in deployment configuration versus the System Manual?
- What is the minimum viable `system-setup` record and where does it live?
- How should Arco Core updates be distributed and reconciled with local customisation?
- What permission and approval boundaries should VIP receive, if the Role is promoted after real deployment use?
- What is the minimum viable dashboard or human interface?
- What is the minimum viable Policies module boundary and how should it reference existing authoritative policy sources?
- How should usage/quality evidence be stored without creating excessive logging or token consumption?
- How should Arcopsy be invoked during deployment and what exactly should its output contain?
- How should Output approval apply to modules such as Personas that shape another task's output but do not normally create an independent durable domain output?

## Development discipline

- Build from demonstrated use rather than speculative completeness.
- Prefer a small number of clear components with explicit responsibilities.
- Do not turn this file into a second system manual.
- When an open question is resolved, implement it in the correct source-of-truth file and then update/remove the corresponding development note here.
- Keep proposed capability clearly separated from implemented capability.
- Treat `arco-modules.md` as a synchronized architectural catalogue: whenever development work changes module existence, scope, lifecycle state or module relationships, update it as part of the same change rather than leaving catalogue maintenance for later.

## Changelog

| Date | Version | Change | Approved by | Changed by |
|---|---|---|---|---|
| 15-Sep-2026 | 0.19.0 | Promoted Defrag out of Development into live Core `arco-defrag.md`, removed the resolved v1 trigger/intervention question and retained Development only for genuinely unresolved future architecture. | Stoirm Arnold | GPT-5.6 Sol |
| 15-Sep-2026 | 0.18.0 | Reconciled Development with the Module Manual by removing the superseded global/per-module approval-toggle model, recorded the evidence and required shape exposed by the first real Defrag, and added the remaining Output-approval/Defrag design questions rather than inventing their answers. | Stoirm Arnold | GPT-5.6 Sol |
| 15-Sep-2026 | 0.17.1 | Updated current development references to the renamed `arco-module-manual.md` while preserving historical release records. | Stoirm Arnold | GPT-5.6 Sol |
| 15-Sep-2026 | 0.17.0 | Established `arco-module-standard.md` as the universal module contract, added the future Module Builder as a consumer of that standard, removed duplicated module-control ownership from Deployment/Approvals direction, and reconciled the Policies concept with the new standard controls. | Stoirm Arnold | GPT-5.6 Sol |
| 15-Sep-2026 | 0.16.0 | Simplified module approvals to two standard System Setup controls: Automatic system updates (ON by default) and Output approval, with granular controls reserved for optional advanced mode and plain-language onboarding. | Stoirm Arnold | GPT-5.6 Sol |
| 15-Sep-2026 | 0.15.1 | Clarified that module Permissions define the authorised user population and `approvals: false` removes only the secondary approval step for that population; recorded department-scoped modules such as Policies as the key example. | Stoirm Arnold | GPT-5.6 Sol |
| 15-Sep-2026 | 0.15.0 | Established system-level and per-module approval configuration plus the proposal-queue/reconcile/Dry Run/Governor flow for maintained local/deployed changes, and added Policies as an emerging module candidate that can use the same Governance/Approvals infrastructure. | Stoirm Arnold | GPT-5.6 Sol |
| 15-Sep-2026 | 0.14.0 | Promoted `arco-design.md` from exploratory concept to Core architectural memory; established the boundary between Design and Development, the requirement to preserve meaningful rejected/superseded rationale, and Design's non-operational relationship to canonical owning files. | Stoirm Arnold | GPT-5.6 Sol |
| 15-Sep-2026 | 0.13.1 | Removed stale pre-Governance references to the legacy Approvals draft and replaced resolved Governance relationship questions with the remaining Approval Rule and VIP boundary questions. | Stoirm Arnold | GPT-5.6 Sol |
| 15-Sep-2026 | 0.13.0 | Promoted Governance into a foundational Arco subsystem with Core Roles, Permissions and Approvals drafts; confirmed System Governor as required and Champion as an optional Role; recorded VIP as an emerging Role concept whose permissions remain unresolved; and established Permissions/Permission Groups plus stable resource references through owning subsystem registers. | Stoirm Arnold | GPT-5.6 Sol |
| 15-Sep-2026 | 0.12.0 | Added Arcopsy as the host-environment compatibility review for deployment and Defrag as the ongoing internal architecture-coherence review; consolidated earlier drift/system-review ideas under Defrag, clarified both are unresolved functions rather than confirmed modules, and corrected System Governor wording so its architectural home remains unresolved. | Stoirm Arnold | GPT-5.6 Sol |
| 15-Sep-2026 | 0.11.1 | Removed legacy procedural dry-run instructions from Development so validation mechanics exist only in the dedicated standard beneath the System Manual. | Stoirm Arnold | GPT-5.6 Sol |
| 15-Sep-2026 | 0.11.0 | Recorded the Arco definition rename and Core-host deployment exception, and noted promotion of the formal validation layer while keeping its operating rules outside development documentation. | Stoirm Arnold | GPT-5.6 Sol |
| 14-Sep-2026 | 0.10.0 | Recorded successful Context Core → deployed → local extraction while deliberately keeping Context Early/draft and unrouted in Stoirm Ltd until authoritative sources and local Context infrastructure are configured. | Stoirm Arnold | GPT-5.6 Sol (Medium) |
| 14-Sep-2026 | 0.9.0 | Recorded successful Personas Core → deployed → local extraction and promotion, including the decision to retain a lightweight local Persona inventory until scale justifies a structured register. | Stoirm Arnold | GPT-5.6 Sol (Medium) |
| 14-Sep-2026 | 0.8.0 | Recorded successful Skills promotion as the first fully deployed module using the Core → deployed → local pattern, and confirmed upstream source pointers for periodic Core/deployment drift comparison (`/Arco` for Stoirm Ltd; future `arco.stoirm.co.uk` for external deployments). | Stoirm Arnold | GPT-5.6 Sol (Medium) |
| 14-Sep-2026 | 0.7.0 | Recorded the proven Core → deployed → local extraction pattern from the System Manual dry run, including singular-pointer ownership, raw-Markdown verification, and the provisional system-setup/AI-guide drift-check direction. | Stoirm Arnold | GPT-5.6 Sol (Medium) |
| 11-Sep-2026 | 0.6.0 | Added the requirement to keep `arco-modules.md` synchronized with development changes, clarified that Context is not yet live in the Stoirm Ltd deployment, and logged the emerging design-rationale/architecture-record concept for preserving and reviewing the reasons behind module design. | Stoirm Arnold | GPT-5.6 Sol (Medium) |
| 11-Sep-2026 | 0.5.0 | Recorded the then-current System Governor direction and the unresolved boundary between Roles and Governance. | Stoirm Arnold | GPT-5.6 Sol (Medium) |
| 11-Sep-2026 | 0.4.0 | Captured remaining cross-system concepts from current design work: Module Register and capability discovery, OS-install versus working-data boundary, optional Story Mode, richer dashboard visibility and the emerging system-review function now consolidated under Defrag. | Stoirm Arnold | GPT-5.6 Sol (Medium) |
| 11-Sep-2026 | 0.3.0 | Moved emerging Approvals, Roles/System Governor and Deployment design into dedicated `0.1.0` draft operating guides and reduced this file to cross-system questions. | Stoirm Arnold | GPT-5.6 Sol (Medium) |
| 11-Sep-2026 | 0.2.0 | Resolved the foundational Context architecture into `AI/context/readme-context.md` and narrowed the remaining Context work to register detail, deployment migration and downstream skills. | Stoirm Arnold | GPT-5.6 Sol (Medium) |
| 10-Sep-2026 | 0.1.0 | Created the initial Arco development ledger, separating established decisions from emerging components and unresolved architecture. | Stoirm Arnold | GPT-5.6 Sol (Medium) |