A shared way for people and AI to work Early draft

Portable Agent Workspace

Give any project a clear, source-linked way of working without requiring everyone involved to be technical.

PAW turns scattered work into shared, source-linked understanding. A newcomer gets a plain overview, a specialist can trace the detail, and an AI assistant can help without relying on hidden chat history.

See the difference Show me an example

What a shared project structure changes

More people can contributePlain language lowers the barrier to entry

Expertise stays availableSources and decisions remain traceable

Technology is easier to usePeople do not need to master every tool first

Control stays humanSensitive actions still need approval

What you change: one overview page. What you keep: your existing files, folders, apps, and way of working.

A shared project structure lowers the barrier to contributing, keeps expertise traceable, makes technology easier to use, and leaves consequential decisions with people.

Why it matters

The work survives. The understanding does not.

Project knowledge usually lives partly in files and partly in someone’s head. That makes every return, handover, and new helper depend on the same person explaining everything again.

Without a reliable overviewWith PAW

Search old messages and ask which file is currentStart from one trusted project overview

Depend on the owner to explain what happenedRead the current situation and important decisions

Guess what to do or wait for instructionsContinue with a clear next action

Give an assistant broad access and hope it asksState what it may do and what needs approval

The value is continuity without dependency on one person’s memory. People and AI can become useful sooner, while the project owner keeps control of consequential decisions.

Useful at every skill level

One project. Different depths.

People should not need the same background to work from the same reliable understanding. PAW puts the simple explanation first and keeps detail one clear step away.

New to the workUnderstand the point

See the goal, current situation, next step, and who to ask in ordinary language.

Ready to contributeFind the right place

Follow clear links to the document, task, discussion, or tool needed for the job.

Experienced or responsibleCheck the reasoning

Trace important claims to their sources, evidence, decisions, and owners.

Using an AI assistantShare useful context safely

Give the assistant the same routes and limits without making private chat memory the project’s foundation.

What this can equalise

Access to context, a clear starting point, understandable choices, and the ability to ask an informed question.

What it does not pretend to equalise

Experience, judgment, subject expertise, authority, or access rights.

The same truth can serve different people at different depths. A beginner does not have to read the research. An expert does not have to trust a simplified summary. Both can work from the same project without creating competing versions of it.

A real-world example

Planning a community workshop

The organiser has a budget spreadsheet, a venue email, a poster in Google Drive, and a group chat. Nothing is wrong with those tools. The problem is that no single place explains how they fit together.

Before

Another organiser opens the folder and has to ask five questions before they can do anything.

After

A short project page explains the goal, current status, next step, useful links, and which actions need approval.

Workshop overview

What are we doing?: Run a bicycle repair workshop for 20 first-time riders on 12 September.
Where are we now?: The venue is booked. The poster is ready. Registration has not opened.
What happens next?: Ask Maya to approve the registration form, then share it with the community group.
Where is everything?: Budget in Google Sheets. Poster in Drive. Venue agreement in email. Tasks in Trello.
When should someone ask?: Ask before spending money, sharing participant details, or publishing an announcement.

No database, special software, or new collection of documents was needed.

The smallest useful setup

Write down five answers

1What is this project trying to achieve?

Use a sentence a new person would understand.

2Where does it stand today?

Describe what is done, decided, blocked, or uncertain.

3What should happen next?

Name one useful action, not a complete plan.

4Where is the rest of the work?

Link to the files, apps, or people someone actually needs.

5What needs approval?

Call out spending, publishing, private information, and hard-to-reverse changes.

For most projects, this is enough. Put the answers in the main project description or README. Keep your existing files and tools exactly where they are.

Choose my starting point Read the detailed reference

Detailed referenceRules, research, standards, evidence, and advanced cases

Read through your lens

Start here: make the next action and decision owner easy to find. No software knowledge is required.

Look for: one reliable current state, explicit tool boundaries, and a route back into the application.

Adopt in place: keep architecture, tests, CI, issue tracking, and deployment controls.

Coordinate without copying: parents own shared outcomes; children keep detailed state.

Why it exists

Continuation fails before the work does

Projects become hard to resume when orientation, meaning, evidence, authority, and dependencies live in different places or only in memory. PAW addresses seven accepted problem families without prescribing one project method.

Orientation and attention

Find what matters without loading everything.

Meaning and taxonomy

Keep terms understandable as labels evolve.

Epistemic trust

Separate source, interpretation, uncertainty, and decision.

Time and lifecycle

Know what is current, superseded, historical, or unresolved.

Authority and coordination

See who decides and what needs approval.

Boundaries and evolution

Move work without hidden paths or private memory.

Sustainability

Make every artifact and review earn its upkeep.

PAW is not an AI harness, orchestration framework, database, knowledge graph, mandatory folder tree, project-management method, or new industry standard.

The contract

One profile, two modes

Mode

Resumable workspace

A bounded project directory with enough local context to orient and continue. It may contain zero or more designated OKF bundles.

Mode

Knowledge-only bundle

An explicitly designated directory governed by pinned Open Knowledge Format v0.1. It does not inherit workspace state or authority requirements.

The default shape

my-project/
  README.md
  <the project's existing work>

PurposeWhat are we making or changing, for whom, and what counts as useful?

BoundaryWhat travels, stays outside, and may be shared?

Current StateWhat exists, what is decided, and what happens next?

AuthorityWho decides, what may proceed, and what requires approval?

Context MapWhere are deeper work, checks, systems, tools, and ways of working?

The six human foundations are outcome and audience, useful result, existing state, next action, people and final say, and consequential boundaries. Setup also reviews outside context, working systems, and ways of working.

RequirementRecommendationOptionCandidateLocal lessonHypothesis

Required A bounded directory, root README in resumable mode, profile marker, orientation, one canonical expression per concern, and consequence-based approval.

Recommended The five headings, Git for ordinary history, task-scoped local action, and established domain tools for complex formats.

Optional Separate STATUS.md, AGENTS.md, knowledge folders, vocabulary, manifests, generated views, or stricter enforcement when justified.

Not required Taxonomy, tool registry, questionnaire record, recurring review calendar, universal confidence score, fixed topology, JSON-LD, or a repository-wide OKF claim.

Context without bloat

Open by task and consequence, not project size

Progressive disclosure

shared README→task router→selected specialist page→canonical source

↳ evidence or history when needed

Text equivalent: start at the shared README, route to one specialist page, then open the source that owns the answer. Evidence and history are conditional.

Links provide routes and relationships. Canonical ownership prevents repeated statements becoming competing truths. Short orientation may repeat when clearly derived; volatile state and durable decisions still have one governing home.

Task-based context explorer

Onboarding: README → profile/START.md → profile/SPEC.md

All task routes
Onboarding	README → profile/START.md → profile/SPEC.md
Operating work	README → index.md → task material → canonical source
Evidence review	README → evidence policy → source register → decision dossier
Tool selection	README → design area 06 → native manifest and tests
Program coordination	README → profile/PROGRAMS.md → parent and child entries
Release work	README → publication readiness → release policy → exact commit

Information fitness

Keep information fit for a real use

A branched lifecycle, not a truth ladder

Capture→Assess source, purpose, and risk→Interpret or judge

Retain as evidence or discardAccept as canonical decisionExpose uncertainty and trigger

Current use→Meaningful change→Review, supersede, or retain→Git history

Text equivalent: capture is assessed before acceptance. It may remain evidence, become a decision, or stay uncertain. A meaningful event triggers review; content is retained, superseded, or left to Git history.

Before: recency as validity

A note says “venue seats 30,” and every read updates its review date. The date looks fresh although the venue changed.

After: event-driven fitness

The booking service owns capacity. The README records its role and degraded behavior. A booking change triggers review; reading does not.

Current state, durable knowledge, decisions, evidence, and history have different lifetimes. Edit time does not prove validity. Known currentness limits remain visible. Git may preserve history instead of duplicate documents.

Ordinary language is the default. Taxonomy begins only when repeated use or a consumer needs stable terms. Evolve it through stable identity, aliases, deprecation, supersession, and migration; a renamed label is not a new truth.

Observation“The venue page displayed capacity 30 on 13 July.”

Source-backed claim“The signed booking caps attendance at 24.”

Interpretation“The lower number probably reflects the layout.”

Uncertain judgment“Twenty should fit, pending confirmation.”

Authoritative decision“The event owner sets capacity to 20.”

These are roles, not simplistic fact-versus-opinion tiers. Provenance, uncertainty, time, confidence, and authority answer different questions.

Why this choice?

Reading supplies no new evidence by itself. Silent rewriting blurs provenance. Review when evidence, purpose, consumer contract, decision, or a risk trigger changes.

Authority and action

Seeing and doing are not permission

Six dimensions that must remain separate
Dimension	Meaning	Example
Visibility	The agent can see an action or resource.	A connector lists production.
Capability	A tool can technically perform it.	The tool supports deletion.
Permission	Policy allows it within scope.	Read-only access is permitted.
Approval	A human authorizes one action.	Publish this named release.
Accountability	A named party remains answerable.	The release owner accepts the outcome.
Confidence	Evidence supports belief, not authority.	Tests cannot approve publication.

Normal local work

Read workspace files
Edit within the task
Create ordinary task files
Run reversible checks

Approval first

External commitments or publication
Hard-to-recover changes
Sensitive transmission or privilege
Security, production, legal, or financial effects

Approval is limited to the stated action, target, effect, and scope. Editing an authority statement or tool configuration cannot grant broader authority during the same run. Deterministic restrictions belong near the protected resource.

MinimalExisting harness and operating-system controls.

ProtectedScoped tools, credentials, branches, approvals, and logs.

ControlledDefault-deny access, separation of duties, change control, and durable evidence.

Portability and dependencies

The folder travels; dependencies remain findable

A PAW boundary can be copied, cloned, or archived without undocumented parent paths, private conversation history, provider memory, or unnamed harness behavior. Purpose, state, next action, and authority remain locally discoverable when external systems fail.

Stable identityUse repository URLs or persistent service links, not private machine paths as the only locator.

Selected revisionPin a commit or version when reproducibility matters.

Degraded behaviorSay what becomes blocked when a dependency is absent.

Materialize when neededBring dependencies into the boundary when offline operation requires it.

Native manifestsSoftware ecosystems keep dependency truth; PAW points rather than duplicates.

Git, submodules, JSON-LD, and manifests

Git supplies history, attribution, diffs, and revision identity. A submodule can materialize independently licensed source at an exact commit. JSON-LD can express machine-readable identity and relationships. A manifest can give software a predictable inventory or entry point.

JSON-LD or a manifest may be useful when a machine consumer, exchange contract, or dependency volume earns the structure. Neither is required by PAW. Machine representations should be generated from or point to human-maintained canonical sources. Pinned OKF v0.1 does not impose JSON-LD.

Tools and working systems

Select for the job, consequence, and boundary

Required fidelityConsequence of errorNecessary accessExpected lifetimeVerification method

Among tools that fully meet the need, prefer the least authority, dependency burden, and maintenance cost. Registry presence, popularity, signatures, hashes, provenance, or a clean vulnerability scan do not establish suitability or permission.

Use repository-declared commands and project-local environments. Persistent dependencies belong in the native manifest. One-off tools run disposably, and their output stays noncanonical until reviewed or tested. PAW has no central package allowlist.

A realistic collaboration stack, not a mandatory inventory
System	Role / canonical content	Stable location / owner	Agent boundary	When unavailable
Local folder	Orientation, authority, drafts	Portable root / project owner	Read and task-scoped edit	Core work unavailable
Google Drive	Approved documents	Stable folder / content owner	Read; ask before external edits	Approval copy unavailable
Confluence	Organizational policy	Persistent page / policy owner	Read if permitted; no policy edits	Policy check blocked
GitHub	Code, review, CI	Repository URL / engineering owner	Local changes normal; remote actions follow authority	Remote review blocked
Slack or Teams	Conversation, not durable state	Named channel / team owner	Read if allowed; ask before posting	Live coordination pauses
Task service	Assignments and queue	Project URL / delivery owner	Read task; ask before consequential changes	Queue updates pause

None is a complete answer. Record a system only when it has a real continuation role.

Human onboarding

Inspect first, then ask only what changes the result

Inspect existing work. Preserve useful names, files, links, history, and controls.
Infer safely. Show what the material already establishes.
Ask one consequential question. Only behavior, risk, ownership, lifetime, sharing, or interoperability justify it.
Preview the result. Show foundations, continuation review, defaults, files, and uncertainties.
Obtain approval. Only then change canonical files.

Skill pathUse the optional onboarding skill; the result remains plain files.

Assistant-neutral pathGive any assistant the provider-neutral setup prompt.

Manual pathAnswer six foundations and three optional operating areas.

Advanced pathChoose distinct lifetimes, stricter controls, or multi-project composition.

Existing projectAdopt in place; do not reshape useful architecture to match an example.

Use cases

Same contract, proportionate shapes

1. Personal non-coding project

Problem: notes but no clear result. Minimum: one README with outcome, next action, owner, privacy, and links. Shape: README plus existing work. Authority: local edits normal; sharing asks first. External: none. No software scaffolding.

2. Three-person community workshop

Problem: documents, spreadsheet, venue, and communication have different owners. Minimum: one README plus existing brief and checklist. Authority: participant data stays private; communication and spending need approval. No app inventory.

3. AI-assisted application with lost state

Problem: code exists, but state and next action live in chat. Minimum: repair README and point to code and tests. Authority: local edits and tests normal; hosted services and real data ask first. No agent framework.

4. Engineering team adopting in place

Problem: architecture, CI, issues, and deployment exist but governing state is hard to find. Minimum: identify entry, state, authority, and routes. Existing architecture and controls remain canonical.

5. Multi-system collaboration

Problem: local files, Drive, Confluence, GitHub, chat, and tasks own different concerns. Minimum: map role, canonical content, stable location, owner, agent boundary, and degraded behavior. Do not duplicate contents.

6. Launch program

Problem: resumable workshop and guide projects share a launch and handoff. Minimum: parent README with shared outcome, project map, coordination state, and next handoff. Children keep detail and authority.

7. Knowledge-only OKF collection

Problem: a portable concept corpus needs an exchange contract. Minimum: designate the bundle and meet pinned OKF document and reserved-file behavior. No PAW workspace README is inherited.

Controlled variation: high consequence

The five orientation functions stay the same, while enforcement adds default-deny access, separation of duties, change control, durable evidence, scoped credentials, and explicit publication approval.

Several projects

Coordination topology is not repository topology

Choose the relationship first

One projectOne outcome, owner, state, and useful next actionNo parent

ProgramIndependent projects coordinate one shared resultParent owns shared outcome, handoffs, and coordination state

Project collectionIndependent projects need navigation or prioritizationParent indexes without inventing a shared outcome

Child A owns purpose, state, next action, and authorityChild B owns purpose, state, next action, and authority

Text equivalent: a program parent owns shared coordination; a collection parent owns navigation. In both, each child remains independently resumable.

Projects may live together or separately. Promote only when at least two resumable projects share something that needs active coordination.

PAW and OKF

Nested scopes, separate contracts

A PAW workspace may contain zero or more designated OKF bundles

PAW resumable workspacePurpose · boundary · current state · authority · context map · next action

Designated OKF bundleConcept Markdown plus exact pinned rules

Ordinary project materialNo OKF claim

Text equivalent: the wider workspace governs resumability. Only explicitly designated directories inherit OKF requirements.

Mode	Portable product	Minimum orientation
Resumable workspace	Project directory plus documented dependencies	Purpose, boundary, state, authority, context map, next action
Knowledge-only bundle	Designated OKF tree	Exact pinned OKF document and reserved-file behavior

The exact pinned OKF core

Every ordinary concept Markdown file has parseable YAML frontmatter with a non-empty string type. Present reserved index.md or log.md files follow their required shape. Consumers tolerate unknown fields and types, missing optional indexes, and broken links.

The upstream specification is normative. Reference code may demonstrate behavior but cannot add law. PAW quality guidance is not renamed as OKF conformance. Google Knowledge Catalog is independently licensed upstream evidence pinned at d44368c15e38e7c92481c5992e4f9b5b421a801d; the repository as a whole makes no OKF claim.

Repository anatomy

Ownership and change impact

Select a repository surface

README — project operating state

Owns current state, next action, authority, boundary, and dependencies. A change may affect derived routes, but not profile law.

README: Current project state, boundary, authority, and context.
index.md: Task router; copies no state.
AGENTS.md: Thin harness adapter.
profile/: Normative rules and adopter guidance.
decisions/: Durable choices and revisit conditions.
design, principles, evidence: Rationale, claims, confidence, and pilots.
practices/: Optional guidance, never profile law.
fixtures and tests: Examples and deterministic checks.
release surfaces: Pending changes, immutable checkpoints, publication gate.
external/: Independently versioned upstream source.

Readable fixture excerpts

Default coding

Current State
Extraction works.
Next: design OCR fallback.

Non-coding

Purpose
Run a bicycle-maintenance
workshop for new riders.

Existing repository

README → canonical state
src/   → preserved work
tests/ → preserved checks

Program

Parent → handoff
Workshop → own state
Guide → own state

Text equivalent: default and non-coding fixtures add orientation. Existing adoption preserves implementation. Program parents store only shared coordination.

Evidence and sources

Claims inherit the limits of their evidence

Normative standardOfficial implementationEmpirical researchMature practicePractitioner signalLocal evidenceHypothesis

Adopt mature and applicable evidence; adapt established principles to context; investigate weak, disputed, novel, or altered claims. Matt Pocock is S-010, a moderate-confidence practitioner signal and discovery source, not normative authority. Local evidence may identify a problem but does not prove generality; private material stays private.

Full admitted source register. The canonical register owns complete version, date, owner, scope, and limitation records.
ID	Source	Class	Confidence	Area
S-001	Open Knowledge Format SPEC	normative-standard	high	Portability
S-002	OKF reference parser	official-implementation	high	Portability
S-003	RO-Crate 1.3	normative-standard	high	Portability
S-004	RO-Crate 1.2	normative-standard	high	Portability
S-005	FAIR Guiding Principles	mature-practice	high	Portability
S-006	GO FAIR principles	mature-practice	high	Portability
S-007	Git documentation	official-implementation	high	Portability
S-008	URI Generic Syntax	normative-standard	high	Portability
S-009	BagIt RFC 8493	normative-standard	high	Portability
S-010	Matt Pocock / AI Hero corpus	practitioner-signal	moderate	Canonical surfaces
S-011	GitHub repository practices	mature-practice	high	Canonical surfaces
S-012	AGENTS.md format	mature-practice	moderate	Canonical surfaces
S-013	OpenAI AGENTS.md behavior	official-implementation	high	Canonical surfaces
S-014	NIST AI RMF Core	mature-practice	high	Authority
S-015	MCP authorization	normative-standard	high	Authority
S-016	OWASP Excessive Agency	mature-practice	high	Authority
S-017	GitHub templates	official-implementation	high	Setup
S-018	BCP 14	normative-standard	high	Canonical surfaces
S-019	NIST SSDF	mature-practice	high	Tools
S-020	Python package metadata	normative-standard	high	Tools
S-021	Managed environments	normative-standard	high	Tools
S-022	Python install guidance	mature-practice	high	Tools
S-023	pylock.toml	normative-standard	high	Tools
S-024	pip secure installs	official-implementation	high	Tools
S-025	PyPI metadata	official-implementation	high	Tools
S-026	PyPI attestations	official-implementation	high	Tools
S-027	pip-audit	official-implementation	high	Tools
S-028	SLSA 1.2	normative-standard	high	Tools
S-029	OpenSSF Scorecard	official-implementation	high	Tools
S-030	npm provenance	official-implementation	high	Tools
S-031	Homebrew supply chain	official-implementation	high	Tools
S-032	APT trust	official-implementation	high	Tools
S-033	PyYAML	official-implementation	moderate	Tools
S-034	W3C step instructions	mature-practice	high	Onboarding
S-035	W3C forms	mature-practice	high	Onboarding
S-036	GOV.UK question pages	mature-practice	high	Onboarding
S-037	GOV.UK good questions	mature-practice	high	Onboarding
S-038	GOV.UK content and transactions	mature-practice	high	Onboarding
S-039	Diátaxis	mature-practice	moderate	Onboarding
S-040	Agent Skills specification	normative-standard	high	Onboarding
S-041	PMI Lexicon	mature-practice	high	Several projects
S-042	GovS 002	normative-standard	high	Several projects
S-043	Teal Book	mature-practice	high	Several projects
S-044	Git configuration	official-implementation	high	Operating context
S-045	VS Code settings	official-implementation	high	Operating context
S-046	Working Agreements Play	practitioner-signal	moderate	Operating context
S-047	Personal user manuals	practitioner-signal	moderate	Operating context
S-048	Scrum Guide	normative-standard	high	Operating context
L-001	Sanitized workspace evolution corpus	local-evidence	moderate	Canonical surfaces
L-002	Repository PyYAML observation	local-evidence	high	Tools

Evolution and release

A release freezes a checkpoint, not the research project

Immutable release lifecycle

Mutable draft0.1-draft changes under Unreleased
Owner checkpointExact profile accepted
Tagged commitAnnotated paw-v<version> tag
Release recordCommit, validation, limits, migration
Next draftResearch and profile development continue

Text equivalent: the draft changes until an exact checkpoint is accepted. A tag and record preserve it while the project moves to the next draft.

Contributions are classified before change. Profile, ADR, evidence, fixture, validation, changelog, and release surfaces update only when affected by the change-impact rule.

Current status

Validated foundations, open human evidence

Derived, non-authoritative explanation. Assessed against repository commit a66d11cd7eb43c1b39fb0bcca885abd914193f2b. Follow canonical sources when wording differs.

Completed or implemented

Accepted problem families, principles, profile, OKF boundary, tool rule, and release lifecycle
Default, guided, existing-repository, non-coding, and program fixtures
Cold-agent orientation, bounded evolution, and relocation checks
Human onboarding, multi-project, and operating-context candidates
Repository tests and exact OKF validation

Still uncertain or incomplete

No immutable PAW release
No sustained-use lifecycle evidence
Accumulated maintenance cost unknown
Real first-time onboarding pilots outstanding
Program and continuation-review human pilots outstanding
Final privacy and upstream-drift review due after public materials exist

The research repository dogfoods PAW. Its ADRs, evidence, design areas, fixtures, and release machinery are research infrastructure, not the default adopter tree. Publication posture is not ready.