The adoption guide

Adopting ACOS

Start with a small, useful core — a front door, an identity, one folder that matters. Agents grow the rest as real work demands it. This guide shows you the day-one core and the growth path that follows.

Small day-one core Grows as you work

ACOS is a company context system, not a README exercise — READMEs are just the front doors that route agents to the records underneath. You don't need to read the whole framework manual first: skim it for the vocabulary, then work through the day-one core below. When you want to see any pattern fully populated, tPPOS — theProductPath's own instance — is the reference implementation.

What ACOS asks of you

ACOS is deliberately thin. It assumes three things and provides the rest — the README patterns, templates, skills, and house rules all come from the framework.

A synced folder tree

Google Drive, OneDrive, Dropbox, or a git repo — ACOS never touches the storage layer.

Tools that read markdown

Any model or platform that can read markdown and walk a folder tree can use your instance.

A seed of judgment

You supply the identity, scope, and decision-makers. Agents document the rest as work happens.

The shape of an instance

An ACOS instance has an instance root and a set of sibling folders that hold the slices of your business. The root is the front door every agent reads first; the siblings are where the actual work lives.

At the root you'll end up with a README.md (the entry point), a company-brief.md (your stable identity), an optional dashboard.md (your current state), and an optional overlays/ directory (per-skill configuration). Alongside the root sit the folders that matter to your company — Clients/, Products/, Projects/, Brand/, Research/, or whatever you actually run on. You don't need all of them, and you can add more later.

companyOS/
├─ README.md            # entry point — every agent reads this first
├─ company-brief.md     # stable identity, voice, principals
├─ dashboard.md         # current state (optional)
├─ overlays/            # per-skill configuration (optional)
├─ Clients/
├─ Products/
├─ Projects/
└─ Brand/
Hold that picture in mind: everything below is about seeding that shape — not filling it all in yourself.
Phase one

Day one: the small core

Four steps, one sitting. The goal isn't finished documentation — it's agents working inside your company by the end of the day.

Choose your folder tree, create the instance root

Pick the folder that will be the top of your company's operating tree — usually the root of a synced drive or a dedicated company folder. Then make a fresh copy of the framework's folder-readme-root.md template, save it in that folder as README.md, and fill in its sections for your company: what the instance is, which sibling folders are in scope, and the pointer back at ACOS for the framework rules. It's the front door every agent reads first.

Fill in your company brief

Copy the brief-company.md template into the root as company-brief.md, then work through its sections: positioning, offers, voice, defaults, and your principals — the humans agents act for and escalate to. If there's more than one principal, designate exactly one primary stakeholder so escalation is never ambiguous. This is the one record worth real care on day one: it gives every agent your identity, voice, and decision path.

Instrument your first high-value area

Pick the one folder where agents will do the most work — for most companies that's Clients/ or Products/. Copy the folder-readme-container.md template into it as README.md and fill in its sections: an index of what's inside plus the conventions every child follows. You don't instrument everything; an unlabeled folder just means an agent has less context there, not that anything breaks.

Point an agent at the root and run the first check

Now prove the core works. Point an agent at your instance root and ask it to check instance health. The framework's acos-integrity skill walks your tree and confirms your READMEs, frontmatter, and naming follow the rules — and to do that, the agent first has to orient itself through the cascade. A clean report means your front door, brief, and container README are doing their jobs.

Have it save the report to _progress/ — and that's your instance's first agent-generated artifact, minutes after setup. See exactly how the agent orients itself →

That's the whole upfront ask.Everything below happens as you operate — and mostly, agents do it.
Phase two

As you work: the instance grows

You keep working the way you always have. But now, when work reveals a durable need, your agents fortify the instance with the right kind of record — and every task that follows starts from a stronger foundation.

  • A new client engagement landsagentyou review

    An agent scaffolds the client README, brief (brief.md, the substantive relationship record), and manifest from framework templates. The relationship record compounds from there.

  • Incoming material needs routingagent

    A manifest gives agents the aliases, email domains, and project keywords to match a stray transcript or email to the right client — instead of guessing or inventing a new one.

  • A company-specific quirk shows upagent

    It becomes an overlay at overlays/<skill>.md — not a fork. The shared skill stays reusable; your account names, paths, and routing quirks live in the overlay.

  • A recurring choice gets settledagentyou decide

    A decision record preserves why, the alternatives considered, and when to revisit — so future agents don't blindly reopen settled questions.

  • A deliverable repeats itselfagent

    It becomes a template — the next proposal, invoice, or client area starts from a proven shape instead of a blank page.

  • You want a morning glanceagent

    A dashboard (dashboard.md) carries current state — active work, slipping commitments, what needs a principal. The dashboard-refresh skill re-rolls its structured sections on a cadence where your environment supports it, propose-first elsewhere. The markdown stays canonical; every rendered view is a surface over the same company memory.

~95%

In tPPOS — theProductPath's own instance — roughly 95% of these supporting records were created by agents in the course of real work, inside the instance's rules, with humans supplying judgment and approvals.

ACOS never asks you to predict every record your company will need. It gives agents the vocabulary and the rules to add the right kind of record when the work reveals the need — and each one leaves the company better documented than the task found it.

Adoption checklist

Day one — you

  • ✓Instance root with a README.md listing in-scope siblings.
  • ✓company-brief.md with principals and a primary stakeholder.
  • ✓Container README on your first high-value folder.
  • ✓First integrity check run — report saved by the agent.

Earned over time — mostly agent-built

  • Item READMEs, briefs, and manifests on active clients or products.
  • Overlays for company specifics; templates for repeated deliverables.
  • Decision records where recurring choices got settled.
  • dashboard.md in place, on a refresh cadence.

Extensions

Everything above is the whole ask — nothing on this page is required to run an instance. Past that, some companies build optional capabilities on top of a working instance. They're always separate from core adoption, and never a prerequisite for one.

Retrieval (RAG)Bonus guide

Once an instance is large enough that folder-walking feels slow, the same conventions that make it easy for an agent to orient itself — consistent frontmatter, lifecycle signals, a canonical topology — make it unusually easy to index for retrieval. The guide covers why, a reference stack, the pitfalls a real corpus hits, and a brief you can hand to a coding agent to build one over your own instance.

Read the guide →

More will land here as they prove out.

Where to go next

Framework on GitHub Back to home