Make your work understandable and resumable — by a person or an AI assistant.
Portable Agent Workspace (PAW) is a portable workspace profile and operating convention. It adds one small shared agreement so any project can be copied, understood, and continued — without one particular model, harness, database, or private chat history.
Current version 0.1-draft — an internal, mutable working draft. No release cut.Derived explainer
It serves a first-time project owner, a non-coding collaborator, an AI-assisted “vibe” builder who wants structure, an experienced engineer, a small team, and a program lead. They get different examples — not different PAW contracts.
The one-README default
The simplest resumable workspace normally adds or repairs a single root README.md. Nothing else is added until a real consumer, risk, or different information lifetime justifies it.
Diagram 1 · The PAW operating map — from entry to action
Entry
Human or AI assistant opens the folderreads README.md
ordinary local work proceedsconsequential action → approval
Text equivalent: a reader enters through one shared README, routes through five orientation sections to the relevant specialist page and its canonical source, reaches external systems and evidence only when the task needs them, and acts — with ordinary local work flowing freely and consequential actions gated behind approval.
PAW opens the route relevant to the work — it does not preload everything. Pick a task.
Onboarding a project →profile/START.md (or the onboard-workspace skill): establish the six foundations, show the continuation review, write one README. Open only this route.
Canonical sources
Why PAW exists
The seven problems a resumable workspace keeps hitting
Before any files or formats, PAW’s research accepted seven enduring problem families. They are a problem model — not a required folder structure. Sustainability is both its own family and a constraint on all the others: a fix is incomplete if it costs more than the failure it prevents.
01
Orientation and attention
How can a newcomer find the context that matters now without processing the whole workspace?
02
Meaning and taxonomy
How can concepts stay understandable while labels, categories, and schemas evolve?
03
Epistemic trust
How can readers tell what was captured, what is believed, and what was chosen — without pretending a label proves truth?
04
Time and knowledge lifecycle
How can information stay fit for its present use and leave active use when its value changes?
05
Authority and coordination
How can people and agents act together without confusing access, capability, permission, approval, ownership, and accountability?
06
Boundaries and evolution
What must stay stable when a project moves, changes, gains consumers, or crosses a trust boundary?
07 · also a constraint
Sustainability
How can the workspace stay useful without its documents, metadata, and checks costing more than the failures they prevent?
For a first timerYou do not need to memorise these. They are the reasons the next section keeps the setup so small: each problem is answered by orientation, not by adding machinery.
For an AI-assisted builderLosing “what works and what to do next” is problem 1 (orientation) and problem 4 (lifecycle). PAW answers both by keeping current state and next action in one place, not by adding a framework.
For an engineerThese map to familiar fields — information architecture, SKOS/vocabulary evolution, provenance, records management, security & decision-rights, configuration management, and SRE/maintainability. PAW adopts established principles rather than inventing them.
For a team / program leadProblem 5 (authority & coordination) and problem 6 (boundaries) are where multi-owner work breaks. PAW handles them with named ownership and stable boundaries, not new process.
Why seven families, and why is sustainability special?
The local problem inventory was compared with established theory, standards, mature practice, practitioner evidence, and epistemic-status research. The map organises inquiry above formats and tools. Sustainability constrains every other family because a solution to taxonomy, lifecycle, trust, or portability is incomplete if its ongoing cost exceeds its value for an individual or small team. Accepted in ADR-002 (2026-07-12) as a research basis only — it commits to no principle, field, or folder.
Canonical sources
What PAW actually asks of you
The PAW contract
An adopter picks one mode. Most people pick the first. The whole convention can ride inside a single README.md.
Mode 1 — the common case
Resumable workspace
A bounded project directory containing enough local context for a new human or agent to orient and continue. It may contain zero or more designated OKF knowledge bundles.
Minimum orientation: purpose, boundary, current state, authority, context map, and next action.
Mode 2 — knowledge only
Knowledge-only bundle
An explicitly designated directory that conforms to pinned OKF v0.1. It is the portable knowledge product.
It does not inherit the resumable workspace’s README, current-state, authority, or agent-instruction requirements. See PAW and OKF.
The default shape
Show this before the research repository. The default adds one convention file, not one total project file:
my-project/
README.md # the shared entry — the whole convention can live here
<the project's existing work> # code, docs, assets, data — unchanged, in place
A separate STATUS.md, AGENTS.md, taxonomy, knowledge/ folder, manifest, or tool registry is conditional — never part of the default tree. Each appears only when a real consumer or a different information lifetime justifies it.
Five shared-entry sections
The README answers five human questions. Use them as headings unless equally clear existing language already serves those functions.
Section
The human question it answers
Purpose
What are we trying to make or change, for whom, and what counts as useful?
Boundary
What travels with this work, what stays outside, and what may be shared?
Current State
What exists now, what is decided, and what should happen next?
Authority
Who decides, what may proceed, what requires approval, and what is sensitive?
Context Map
Where is deeper work, validation, outside context, systems, tools, and ways of working?
Six human foundations & the continuation review
Human onboarding establishes six ordinary foundations — outcome & audience, useful result, current reality, next action, people & decision ownership, and non-negotiable boundaries — and always shows a continuation review of three areas, each marked found, none identified, or uncertain:
Outside context
Information, people, repositories, services, or decisions that do not travel with the folder.
Working systems & tools
Where people create, store, discuss, track, review, or approve — plus required software or materials.
Ways of working
How work is chosen, reviewed, handed off, approved, or communicated. Shared agreements vs personal preferences.
None is a complete answer. Follow-up happens only when something required is found or uncertain. Showing the review is required; having extra content is not.
How to read the rules on this site
PAW distinguishes strength of claim, and so does this explainer. Watch for these tags:
requirementMUST / MUST NOT in the profile
recommendationSHOULD — a strong default
optionMAY — available when justified
examplean illustration, not a rule
candidateimplemented, not yet fully validated
local lessonfrom private JC-OS evidence; not a requirement
hypothesisproposed, unproven
Core requirements, recommendations, options, and non-requirements
Requirements MUST
A bounded directory that copies/clones without undocumented parent paths, absolute local paths, private chat history, provider memory, or unnamed harness behaviour.
A UTF-8 Markdown README.md at the root, identifying this profile and version.
One canonical expression for each governed claim, decision, term, or current state.
A named decision owner and the current task boundary.
Specific approval before external commitments, unrecoverable actions, sensitive transmission, credential/privilege change, security/production impact, or legal/financial consequence.
Every mandatory artifact beyond the core names its consumer, owner, update trigger, failure behaviour, repair path, and deletion condition.
Recommendations SHOULD & options MAY
rec Use Purpose · Boundary · Current State · Authority · Context Map as headings.
rec Use Git for history, attribution, diffs, and recovery.
rec Begin with only the shared README; run a fresh-reader check after setup.
optSTATUS.md when current state needs its own lifetime.
optAGENTS.md as a thin harness adapter (never a second source of state/authority).
optknowledge/ designated OKF bundle when knowledge has a real reusable consumer.
Explicit non-requirements the profile does NOT require
JSON, JSON-LD, a workspace manifest, database, dependency resolver, or generator;
a fixed folder forest or empty optional placeholders;
global fact/opinion labels, importance scores, lifecycle metadata, review dates, or promotion queues;
a governed taxonomy without a real consumer;
a central tool allowlist, lockfile, SBOM, mirror, or package dossier for ordinary low-consequence work;
named agent roles, multi-agent orchestration, telemetry, or a particular harness;
updating documents merely because they were read.
Canonical sources
Progressive disclosure
Context without bloat
PAW does not invent formal “context levels” based on repository size. It uses one retrieval path, and lets task and consequence — not raw project size — decide what gets opened.
Diagram · The retrieval path
Shared READMEalways-loaded orientation only
Task routerchoose one route
Specialist pagedetail for the task
Canonical sourcethe file that owns the rule
Evidence / historyonly when needed
Text equivalent: shared README → task router → selected specialist page → canonical source → evidence or history when needed.
Links give routes; ownership prevents competing truths
Links provide routes and relationships. Canonical ownership keeps repeated statements from becoming competing truths. Repetition is fine for short orientation or a clearly-labelled derived view — but volatile facts and durable decisions must each have one governing home.
Context is a budget
Always-loaded guidance contains only broadly applicable constraints. Task-specific detail sits behind descriptive, stable pointers with enough “information scent” to be found. Measure and remove stale, duplicated, or unused always-on context — no fixed token threshold is universal across models, harnesses, or tasks.
Task and consequence, not size
A large project does not automatically open more context; a small one with a risky action opens more. What you load is governed by what the current task and its consequence actually need.
For an AI-assisted builderThis is the discipline that stops your assistant from re-reading everything each session. Keep the README lean; let the assistant follow one route to the file that owns the answer.
For an engineerThink of the README as the always-loaded prompt surface and specialist pages as lazily-retrieved detail. Repetition is acceptable only as a labelled derived view; the canonical source stays singular.
Canonical sources
How information stays trustworthy and current
Information fitness
Information stays relevant without a cataloguing exercise. The rule is event-driven, not calendar-driven, and never triggered simply by reading a file.
Canonical vs derived · capture vs accepted knowledge
Canonical
The authored source whose meaning governs. Each governed claim, decision, term, or current state has exactly one.
Derived
Reproducible output generated from canonical sources. Useful without becoming authoritative — it must name its source or be labelled non-authoritative.
Saving or capturing information MUST NOT automatically make it accepted durable knowledge. Capture is not the same as a claim you would act on.
Diagram 3 · Information lifecycle — branches, not a truth ladder
Capturean observation, note, or source
Assessmenttriggered by evidence / purpose / consumer / risk — not by reading
Accepted / decisioncanonical, acted upon
Current usethe governing version
Supersessionretained material points to its replacement
HistoryGit may hold it — no duplicate historical document
Text equivalent: capture flows to assessment only on a real event, and may become an accepted decision; separately, current use may be superseded (with a pointer to the replacement) and pass into history, which Git can hold. Nothing here is a rank of “more true”.
One concrete before-and-after
before — capture drifts into “state”
## Current Work
The parser is complete. Next: group
entries by category. Rules live in
../shared-rules/… and the team chat.
A free-floating summary competes with any real status file, and depends on a hidden sibling path plus unnamed chat memory.
after — canonical state + named dependency
## Current State
Canonical current state: docs/status.md
(this section keeps no competing summary)
## Boundary
Required external context: Conventional
Commits 1.0.0 (stable URL). Offline:
parsing works; category changes blocked.
State points to one canonical home; the dependency is named with a stable identity and a degraded-behaviour note. Source: the existing-before → existing-after fixtures.
Epistemic distinctions — not a truth ladder
Keep these distinct where confusing them could change a consequential action. A label never proves truth; provenance, uncertainty, authority, and time stay separate concerns.
Observation
What was seen or recorded.
Source-backed claim
Backed by a cited source.
Interpretation
A reading of the evidence.
Uncertain judgment
A belief held with stated confidence.
Authoritative decision
A choice an authorised person made.
Not this
Do not collapse these into simplistic “fact vs opinion” truth tiers.
A well-sourced judgment may still be uncertain; an authoritative decision may rest on uncertain evidence; an authentic record may preserve an inaccurate claim. The dimensions are orthogonal.
Taxonomy — begins only when someone consumes it
Ordinary language is the default. A governed vocabulary begins only when repeated use or a real human/machine/external consumer depends on stable meaning. When it does, taxonomy can evolve without pretending renamed labels are new truths:
keep concept identity separate from its current label;
use aliases, deprecation, supersession, and migration for change;
edit recency does not prove validity; a lifecycle state exists only when it changes retrieval, review, use, or disposition.
JSON-LD and manifests — useful, never required
JSON-LD can express machine-readable identity and relationships using linked-data conventions.
A manifest can give software one predictable inventory or entry point.
Either may help when a real machine consumer, exchange contract, or dependency volume requires it.
Neither is required by PAW’s core resumable-workspace profile. PAW favours ordinary readable files and descriptive links until a machine consumer earns more structure.
A machine representation should be generated from — or point to — canonical human-maintained sources, not become an accidental competing truth.
Do not attribute JSON-LD requirements to pinned OKF v0.1; the pinned spec does not state them.
For a first timerIn plain terms: write in normal language, keep “what’s true now” in one place, and only update when something actually changes — not because you re-read a note.
Canonical sources
What an agent may do, and what needs approval
Authority and safe action
Six ideas are routinely confused. PAW keeps them distinct — and only one of them is “authority”.
Diagram 4 · Six dimensions — kept separate
VisibilityThe agent can see an action or resource.
CapabilityThe tool can technically perform it.
PermissionPolicy allows it within a defined scope.
ApprovalA human authorises one consequential action.
AccountabilityA named party stays answerable for the outcome.
ConfidenceEvidence supports a belief — this is not authority.
Text equivalent: visibility, capability, permission, approval, accountability, and confidence are six independent concepts. Seeing or being able to do a thing is not permission; being confident is not authority.
Ordinary local work — no repeated approval SHOULD proceed
reading workspace files;
editing within the current task scope;
creating normal task files;
running local, reversible validation.
Specific approval MUST come first MUST
creating an external commitment;
an action lacking straightforward recovery;
transmitting sensitive material across the boundary;
changing credentials or privilege;
affecting security or production;
expanding persistent access;
legal or financial consequence.
An approval is limited to the stated action, target, effect, and scope. Editing an authority declaration or tool configuration MUST NOT grant the acting agent broader authority during the same run. When documentation and enforcement disagree, the more restrictive boundary MUST NOT be bypassed — the mismatch is reported for repair.
Enforcement postures — the label never replaces the controls
A workspace may select a posture, but the posture MUST be accompanied by its concrete permissions and controls.
Posture
Use when
Minimum meaning
minimal
One owner, low-consequence local work
Core action contract using existing harness and OS controls plus consequential approval boundaries.
protected
Shared, sensitive, or externally integrated work
Scoped tools, credentials, branches, destinations, approvals, and relevant logs.
controlled
Regulated, production, financial, or high-impact work
Default-deny access, separation of duties, change control, and durable evidence.
Deterministic boundaries SHOULD be enforced as close to the resource as practical — harness permissions, sandboxes, credentials, branches, OS controls, and downstream authorization — not by documentation alone.
For a team / program leadThe posture ladder lets one contract serve solo work and regulated work. You raise minimal → protected → controlled by writing concrete controls into the Authority section, not by changing the orientation contract.
Why consequence-based instead of tiered roles?
ADR-009: inferring authority from tool availability creates excessive agency (OWASP LLM06); approving every harmless read/edit/test creates interruption without reducing meaningful risk. So the model scopes approval to consequence, and offers three optional enforcement postures over the same contract rather than a fixed role hierarchy. Revisit if agents repeatedly interrupt ordinary work, cross consequential boundaries despite correct enforcement, or owners routinely grant overly broad approvals.
Canonical sources
What travels, and what happens offline
Portability and dependencies
A workspace should copy, clone, or archive as a bounded unit — and keep working when an external system is unreachable.
The bounded workspace MUST
No dependence on undocumented parent paths, absolute local paths, private conversation history, provider memory, or unnamed harness behaviour. Purpose, active state, next action, and authority stay locally discoverable even when a dependency is down.
Named external dependencies MUST identify
why it is required;
a location-independent source (repo URL or persistent identifier);
a selected revision when reproducibility matters;
what is blocked or degraded when it is unavailable.
Absolute local paths and assumed sibling-folder placement MUST NOT be a dependency’s only identity. Required dependencies SHOULD be materialised with source and revision when offline operation is required.
Git, submodules, and native manifests
rec Use Git for history, attribution, diffs, and recovery — but Git history is not required to understand current PAW state.
opt Prefer immutable dependency revisions when exact reproduction matters. This repository materialises upstream OKF as a Git submodule pinned to one commit.
rec Native package/runtime manifests stay canonical for software dependencies — the workspace entry points to them rather than duplicating them.
opt A machine dependency manifest MAY be added only when a real tool consumer or dependency volume makes the context map inadequate.
Relocation is a first-class test
PAW’s fixtures were relocated into a blank parent with no path repair, no questionnaire replay, no network, and no provider memory — and still passed their native tests and OKF validation. If a copy can’t stand alone, the boundary wasn’t clean.
Canonical sources
Choosing tools · mapping external systems
Tools and working systems
Tools are chosen by job fit — not by a central allowlist. External systems are mapped by role and canonical content, never duplicated into the workspace.
Job-fit tool selection
A tool’s presence, popularity, signature, or registry publication MUST NOT by itself establish job fit, trust, or permission. Selection SHOULD weigh:
Fidelity
Required accuracy for the job.
Consequence
Cost of an incorrect result.
Access
Authority the tool needs.
Lifetime & verification
One-off vs persistent; how you test it.
Among tools that fully meet those needs, prefer the least authority, new-dependency burden, and maintenance cost. Persistent software dependencies stay visible in the native manifest — no duplicate package registry. Registry availability is not approval; provenance/attestation/scan results never prove code is suitable or permitted.
PAW requires no central tool allowlist, lockfile, SBOM, mirror, or package dossier for ordinary low-consequence work. Locks, hashes, provenance, and monitoring SHOULD scale with an artifact’s consumers and the selected posture — they are not universal baseline requirements.
Mapping external systems by role — None is a complete answer
Represent Google Drive, Confluence, Notion, Slack/Teams, Jira/Trello, Figma, email, GitHub, specialist software, and physical materials without duplicating their contents. Record only systems the work actually uses. For each, answer six questions:
System
Role
Canonical content
Stable location
Access owner
Agent boundary
Degraded behaviour
Local repo
The workspace itself
Purpose, state, authority, source
This directory / repo URL
Maintainer
Read & task-scoped edits; approval to publish
—
Google Drive
Shared documents & assets
Final brief & approved assets
Drive folder link (not a machine path)
Content owner
Read named files; approval to write
Latest assets unavailable; local drafts continue
Confluence
Team knowledge base
Policy & decisions of record
Space URL
Space admin
Read; no edits without approval
Policy lookups blocked; work continues on cached decisions
GitHub
Code, review, CI/CD
Source & deployment controls
Repo URL
Repo admin
Branch edits; approval for merge/deploy
Review/deploy paused; local build continues
Slack / Teams
Communication
None authoritative
Channel reference
Workspace admin
None without approval
Coordination slows; no canonical loss
Jira
Task tracking
Task status & priority
Board / project URL
Project lead
Read; approval to change status
Task state stale; next action still in README
This is an example, not a mandatory application inventory. A system with no authoritative content is recorded as such; a project that uses none writes None.
For an engineerAdopting PAW does not replace your issue tracker, CI, or deployment controls. Those platforms stay canonical for their content; the README points to them and names the agent boundary and degraded behaviour for each.
Why no central allowlist?
ADR-012: a universal approved-tool catalog duplicates native manifests and goes stale, while unstructured local judgment hides persistent dependencies and gives agents no stable basis for choosing between a built-in utility, a domain package, local code, or a remote service. So selection evaluates four independent fits (job, authority, trust, operations) and keeps persistent dependencies in the ecosystem’s native manifest. Validated once in the PyYAML pilot: a justified dependency (PyYAML>=6.0,<7, MIT, no runtime deps) plus a one-off audit tool — no second registry, no permanent audit stack.
Canonical sources
Getting started as a human
Human onboarding
There is no beginner, engineer, or non-coder edition. The same shared entry serves everyone; what changes is how much can be inferred and how much control is needed now.
recommended
Run the skill
Invoke $onboard-workspace. It inspects existing material first, asks only for missing decisions, previews changes, and waits for approval.
assistant-neutral
Ask any assistant
Paste the provided message. It works without the skill and produces the same plain files.
manual
Fill it in yourself
Answer six questions, review three optional areas, use the starter README. None is valid.
advanced / existing
Show every choice
The setup guide controls where state lives, in-place adoption, postures, and multi-project composition.
How a good assistant behaves
Inspect first, then infer safely — don’t re-ask what the work already answers.
Ask one consequential question at a time, in ordinary language, saying why it matters.
Accept “I’m not sure” and recommend the safe, low-maintenance default.
Preview the recommended shape and every file change; then obtain approval before editing.
Don’t save the questionnaire as a second configuration file — the workspace is the source of truth.
Seven walkthroughs — novice to program lead
Each shows the starting problem, the smallest PAW intervention, the resulting shape, the authority boundary, external context, and why no extra machinery was added.
1 · novice, non-coding
A personal meal-planning guide
Problem: no files yet; can’t describe structure or AI permissions. Intervention: one README via the skill. Shape: a single README.md. Authority: one owner; notes stay private; ask before sharing. External:None. Why nothing more: no status file, classification, software setup, or knowledge collection is justified.
2 · three people, documents
A community workshop
Problem: drafts, quotes, a schedule, a contact list, unclear ownership. Intervention: adopt one existing project; inspect first. Shape: one README naming who owns venue/content/outreach and one final decision owner. Authority: stronger controls only for personal data & external commitments. External: venue + private registration service, named with degraded behaviour. Why nothing more: files stay ordinary documents and spreadsheets.
3 · AI-assisted builder
A working app that lost its thread
Problem: can build by prompting but keeps losing “what works / what’s next”. Intervention: onboarding skill; technical questions only after the six human foundations. Shape: existing README preserved & completed; pointers to app, tests, package setup. Authority: safe AI boundaries named. External: native dependency file stays canonical. Why nothing more:AGENTS.md added only if a tool genuinely consumes distinct instructions.
4 · engineering team, in place
Adopting PAW without replacing anything
Problem: a service with architecture docs, CI, an issue tracker, deployment controls. Intervention: advanced existing-work path. Shape: README becomes the common entry, pointing to existing canonical state & native validation. Authority: stronger approval for deployment & sensitive data; existing platform controls enforce it. External: tracker, CI, deploy stay canonical. Why nothing more: a thin agent adapter routes tools to the same entry — no files move.
5 · multi-system collaboration
Local + Drive + Confluence + GitHub + chat
Problem: work spread across systems with no single orientation. Intervention: one README with a working-systems map (see the table above). Shape: each system recorded by role & canonical content, not copied in. Authority: per-system agent boundary + degraded behaviour. External: all named with stable locations, not machine paths. Why nothing more: the systems stay authoritative for their own content.
6 · program lead
A launch coordinating child projects
Problem: event, publication, and outreach projects must line up. Intervention: a program parent (see Several projects). Shape: parent README owns outcome, shared deadline, cross-project decisions, and a Project Map. Authority: parent owner for shared scope; each child owner within their own. External: children may be separate repos/services, linked stably. Why nothing more: detailed child state is never copied upward.
7 · knowledge only
A designated OKF bundle
Problem: durable knowledge to distribute, not ongoing work. Intervention: a knowledge-only bundle (mode 2). Shape: a directory conforming to pinned OKF v0.1; each concept has YAML frontmatter with a non-empty type. Authority: no resumable-workspace README requirement is inherited. External: tolerant consumers accept unknown fields & broken links. Why nothing more: workspace instructions are not silently called OKF law.
controlled variation
Higher consequence — same orientation
Problem: the work becomes regulated, production-facing, or handles sensitive data. Change: move from minimal to protected/controlled — default-deny access, separation of duties, change control, durable evidence. Unchanged: Purpose / Boundary / Current State / Authority / Context Map. Stricter protection changes the controls, not the basic orientation contract.
Canonical sources
One project, program, or collection
Several projects
Several folders do not automatically make a program. More files, tasks, people, or a longer schedule do not by themselves require one. candidate extension
Diagram 5 · Project vs program vs collection
One project
One outcome with many tasks or workstreams.
Parent keeps: one purpose, state, and next action.
Program
Related projects need active coordination to produce one shared result.
Independent projects that only need one place to find or prioritise them.
Parent keeps: a navigation view, without an invented shared outcome.
Text equivalent: use one project for a single outcome; a program only when independently-resumable related projects need coordination for a shared result; a project collection when independent projects just need one place to be found. Don’t invent a shared outcome.
Consider a program only when all three are true: at least two projects can be resumed on their own; they share an outcome/dependency/resource/decision that needs active coordination; and managing that relationship together creates value separate entries would miss.
Ownership — the parent coordinates; it is not a database
Information
Canonical home
Shared outcome or reason for grouping
Parent entry
Cross-project priority, dependency, handoff, or decision
Parent entry or one linked shared source
Next coordination action
Parent entry
Detailed project state & next project action
Child project entry
Project-specific material & review method
Child project
Each child stays understandable without the parent. Projects may be local folders or separate repos/services. Do not move, nest, merge, rename, or monorepo projects merely to adopt the pattern — repository topology and coordination topology are separate choices.
The Project Map (from the program-parent fixture)
## Project Map
| Project | Reason included | Owner | Location | Depends on |
|----------|------------------------------|--------|----------------------|------------|
| Workshop | Teaches the safety sequence | Morgan | projects/workshop/ | Venue |
| Guide | Gives riders the same sequence| Riley | projects/guide/ | Workshop |
Canonical sources
Two scopes, cleanly separated
PAW and OKF
PAW and Open Knowledge Format (OKF) have different scopes. PAW governs the broader resumable workspace. Exact pinned OKF v0.1 applies only inside directories explicitly designated as OKF knowledge bundles.
Diagram 2 · A PAW workspace surrounds zero or more OKF bundles
PAW resumable workspace — the whole directoryREADME.md · source · docs · data · tests
The workspace root makes no OKF conformance claim. Only the inner directory does.
Text equivalent: an outer boundary (the PAW workspace) contains ordinary project files and, nested inside it, zero or more explicitly designated OKF bundles. Only a designated inner directory claims OKF conformance.
Mode
Portable product
Minimum orientation
Resumable workspace
A project directory + documented external dependencies
Purpose, boundary, current state, authority, context map, next action
Pinned at commit d44368c1…a801d. A designated bundle conforms when — and only when — three things hold:
rule 1
Every non-reserved Markdown concept has parseable YAML frontmatter.
rule 2
Every frontmatter block has a non-empty string type.
rule 3
Any present index.md / log.md follows its reserved shape.
Tolerant consumers — the matched pair
Exact OKF consumers MUST tolerate unknown types and fields, missing optional indexes, and broken links. A broken link may simply be not-yet-written knowledge. OKF does not require title, description, resource, tags, timestamp, valid links, a taxonomy, provenance, lifecycle states, or workspace instructions. Additional PAW quality guidance is never silently called OKF law.
Reference implementation vs specification. Google Knowledge Catalog is upstream evidence and the source of pinned OKF — it is an official implementation, not extra normative law, and not PAW-owned code. It rides as an independently licensed Git submodule at commit d44368c15e38e7c92481c5992e4f9b5b421a801d. The pinned upstream spec remains normative where this summary and the upstream text differ.
Canonical sources
How the files map together
Repository anatomy
This research repository dogfoods PAW while developing it. Its internal complexity is not the default adopter structure. Select a node to see its role and what changes when one canonical decision changes.
canonical — owns a rule derived / adapter — no independent authority upstream — independently licensed
Select a node to see its role and update impact. Every node maps to the authority hierarchy below.
Authority hierarchy — who owns what
When sources appear to contradict, resolve by this priority. The site itself is priority 9: a derived explanation with no independent authority.
Normative OKF behaviour for designated bundles only
3
README.md
Current state, next action, authority, boundary, dependencies
4
decisions/register.md & ADRs
Durable decisions and revisit conditions
5
standards/okf-boundary.md
Exact local explanation of the PAW/OKF boundary
6
Evidence, principles, design areas
Rationale, alternatives, tradeoffs, confidence
7
Fixtures & examples
Non-normative demonstrations of valid shapes
8
Practices
Optional guidance and preferences — never profile law
9
This site
Derived explanation with no independent authority
Canonical sources
Every claim traces to a class of evidence
Evidence and sources
PAW admits sources into a register before they support a decision, and labels each by evidence class and confidence. A practitioner signal is never turned into normative authority.
Seven evidence classes
normative-standard
A requirement owned by a published specification. May justify baseline conformance.
official-implementation
Behaviour in first-party source/tests. May show practice; cannot silently expand a spec.
empirical-research
Peer-reviewed or institutional evidence with a stated method. May support benefits, risks, constraints.
mature-practice
Repeated practice in maintained systems. May support recommendations when scope is comparable.
practitioner-signal
First-hand but non-normative field report. May identify hypotheses; cannot alone justify a core rule.
local-evidence
Observed behaviour in the private case study. May define a problem; does not establish generality.
hypothesis
Proposed explanation. Requires assessment; test only when evidence stays unsettled.
Treatments & confidence
Each source is treated adopt / adapt / investigate, and carries high / moderate / low confidence — with the full scope qualifier kept intact.
Matt Pocock (AI Hero) is source S-010, admitted as a practitioner-signal at moderate confidence — a discovery source for current agent-engineering vocabulary whose prescriptive claims require corroboration. It is not normative authority. Private JC-OS material appears only through sanitized IDs (L-001, L-002); raw notes and paths stay private.
The source register
48 admitted external sources (S-001–S-048) plus two local-evidence sources. Filter by evidence class, confidence, and design area. Where a URL is recorded it links out in a new tab; early sources show “link not recorded”.
Showing all 50 sources.
ID
Source
Owner
Class
Confidence
Area
S-001
Open Knowledge Format SPEC.md · link not recorded
v0.1 @ d44368c1
GoogleCloudPlatform
normative-standard
high
OKF baseline
S-002
OKF reference-agent document parser · link not recorded
same pin
GoogleCloudPlatform
official-implementation
high
OKF baseline
S-003
RO-Crate Metadata Specification 1.3 · link not recorded
1.3 (2026-06)
RO-Crate community
normative-standard
high
Portability
S-004
RO-Crate Metadata Specification 1.2 · link not recorded
1.2 (2025-06)
RO-Crate community
normative-standard
high
Portability
S-005
FAIR Guiding Principles · link not recorded
Sci Data 2016
Wilkinson et al.
mature-practice
high
Portability
S-006
FAIR Principles · link not recorded
living page
GO FAIR Initiative
mature-practice
high
Portability
S-007
Git documentation · link not recorded
2.55.0
Git project
official-implementation
high
Portability
S-008
URI Generic Syntax (RFC 3986) · link not recorded
RFC 3986
IETF / RFC Editor
normative-standard
high
Portability
S-009
BagIt File Packaging (RFC 8493) · link not recorded
RFC 8493
IETF / RFC Editor
normative-standard
high
Portability
S-010
AI Hero corpus (context, sessions, AGENTS.md, skills) · link not recorded
Private workspace evolution corpus · link not recorded
private snapshot
Private case-study owner
local-evidence
moderate
cross-cutting
L-002
Repository PyYAML declaration & observed env · link not recorded
py3.12 / PyYAML 6.0.1
Portable Agent Workspace
local-evidence
high
Tools
How sources become admissible
A source receives an ID before it supports a decision dossier. A mutable web page records its retrieval date and any visible version; a repository source records a commit or release. A later source may supersede an earlier one but does not erase it. Disagreement is recorded in the dossier rather than resolved silently. The term “best practice” is allowed only when evidence shows broad agreement across comparable settings — otherwise the precise class is used.
Canonical sources
Draft now · immutable later
Evolution and release
The project continues; a release does not. Freezing a version does not mean the research project — or the owner’s way of working — is finished.
Diagram 8 · The immutable-release timeline
Mutable draft0.1-draft — where we are now
Accepted checkpointowner accepts the exact profile
Exact tagged commitannotated paw-v<version>
Release recordreleases/<version>.md
Next draftfresh Unreleased opens
Text equivalent: the active line is a mutable draft; the owner accepts a checkpoint, which becomes one exact tagged commit plus an immutable release record, after which a fresh next-draft opens. Released text and its tag are never edited or moved.
Two different lifetimes
The project continues: evidence, design areas, practices, decisions, fixtures, and the active profile may keep changing. A release does not: a released PAW version is an exact checkpoint, never silently rewritten. Corrections and changed contracts receive a new version.
Governance & contribution classification
Lightweight, maintainer-led while it is a 0.x draft; Jens Christian Norgaard is the initial maintainer and final decision owner. A change updates only the surfaces whose contract or lifetime actually changes — research, profile, an ADR, the pinned upstream, or an immutable release — per the change-impact rule.
Why a version does not freeze the whole project. The repository uses profile/SPEC.md as both active profile and integration point. Only the decision owner may cut a release — one exact commit, an immutable annotated paw-v<version> tag, and one human-readable record. A release is never described as an industry standard unless that status is independently obtained.
Canonical sources
Validated · uncertain · blocking
Current status
Non-authoritative notice. This is a derived explanation, not a specification. Status below is a commit-scoped observation. As of PAW repository commit 6455eed · 2026-07-13 · branch main. Publication posture: not-ready.
Completed foundations done
Problem landscape and foundational principles accepted (ADR-002 → ADR-004).
The practical 0.1-draft profile separates requirements, recommendations, options, non-requirements, and exact OKF behaviour (ADR-011).
Default / guided / existing-repository setup paths produce real files with no retained questionnaire (ADR-010).
Reference bundle passes exact pinned OKF v0.1 validation; the permissive and intentionally-invalid fixtures behave as expected.
Full test suite passes; independent validator does not import upstream code.
Job-fit tool selection accepted and applied once (PyYAML pilot, ADR-012).
Original work licensed Apache-2.0; upstream OKF pinned as an independently licensed submodule (ADR-006, ADR-013).
Passing checks & pilots established: orientation only
Two fresh cold-agent pilots identified purpose, canonical state, authority, next action, and the OKF boundary without private/parent context — verdict pass.
A bounded evolution pilot preserved canonical state, vocabulary aliases, supersession, history, and offline degraded behaviour.
A relocation pilot moved default/guided/existing paths into a blank parent with no path repair — verdict pass.
Known limitations & what would block a public release open
No immutable release cut
The repository stays on the mutable 0.1-draft line while dogfooding continues.
Real-human pilot gap
The human-onboarding protocol (status: planned) has not been run with real people across the five participant shapes.
Sustained-use gap
No longer-lived project has yet exercised repeated capture, evidence change, decision promotion, and resumption cycles.
Multi-project gap
The program parent has structural tests but no fresh human coordination & child-relocation pilot.
Maintenance-cost gap
Accumulated maintenance cost beyond the bounded evolution pilot is not yet known.
Final review pending
A privacy and upstream-drift review must repeat once public materials exist.
Onboarding and multi-project composition may currently be described only as candidates built from mature guidance — not as validated across experience levels or work domains.
Canonical sources
A non-destructive preview
Try it
Answer only the consequential choices. This previews the recommended minimum files. It writes nothing and saves no second configuration.
Recommended minimum
my-project/
README.md # Purpose · Boundary · Current State · Authority · Context Map
<existing work>
Enforcement posture: minimal. Add nothing else until a real need changes the recommendation.
Where to go next
Start a workspace
profile/START.md — the recommended first-use path, or invoke $onboard-workspace.