@reunionstudio/airlock-mcp 0.1.0 → 0.1.1

package/.agents/skills/airlock-mcp/SKILL.md

@@ -29,22 +29,30 @@ the deterministic checker.
    any workspace.
    If the user opened the public `airlock-mcp` workbench repo as the entry
    point, help them create a separate `<slug>-specs` project repo beside it.
-3. If no workspace exists, welcome the user and offer three starting paths
-   before creating files:
-   - brainstorm possible specs using the OODA loop
-   - start from a known process and create a blank workspace
-   - create a `posts` feedback loop where humans and agents can submit
-     requests, observations, and responses
+3. If no workspace exists, welcome the user and ask:
+   `What process do you want to improve?`
+   Explain that Airlock works best when we can identify the loop around that
+   process:
+   - what information comes in
+   - what context helps people or agents understand it
+   - what decision needs to be made
+   - what action happens after the decision
+   Give examples before naming the concept: apps, files, forms, people, emails,
+   calls, mail, websites, APIs, data feeds, or physical events. Then call these
+   places interfaces: where the process observes from or acts through.
+   Ask for the messy version. Help turn it into a small first Airlock spec and
+   a plan for more. Do not create the first workspace until the user chooses a
+   path.
 4. Create `posts` only when the user chooses a feedback loop, asks for humans
    and agents to provide feedback, or explicitly requests the posts pattern.
-   If the user is unsure, offer OODA brainstorming first.
+   If the user is unsure, continue process discovery before creating files.
 5. Use `airlock-mcp import-spec <json-file> <name>` when starting from a
    spec-library file, an exported `SPEC_CONFIG`, or an existing canonical config.
 6. Use `airlock-mcp clone <source-workspace> <name>` when creating a related
    draft from an existing workspace. Treat clone like the old Streamlit UI:
    preserve the shape but deliberately reset spec identity.
 7. Keep the draft small. Prefer one useful governed output over a large
-   speculative system.
+   speculative system, then keep a plan for later specs.
 8. On later sessions, run `airlock-mcp list-workspaces` when the target draft
    is not obvious.
 9. Run `airlock-mcp summary <workspace>` and
@@ -63,7 +71,9 @@ the deterministic checker.
 
 ## Spec Design Questions
 
-Resolve these in order, and write the answers into `decisions.md`:
+Use these as an internal checklist. Do not dump the whole list into chat.
+Write resolved answers into `decisions.md` and ask the human only for missing
+or risky decisions:
 
 1. What is one row about?
 2. What systems, users, files, events, or reference data must be observed before
@@ -79,17 +89,33 @@ Resolve these in order, and write the answers into `decisions.md`:
 10. Which optional context can live in a validated `variant` field?
 11. Who submits, reviews, reads, delegates, and owns the process?
 
+## Interfaces
+
+Use interface to mean any place the process observes from or acts through.
+Do not lead with the word before examples. Interfaces can be apps, files, forms,
+people, emails, calls, mail, websites, APIs, data feeds, physical events,
+shared folders, payment tools, bank apps, or other systems.
+
+When a user names a process, map the interfaces both ways:
+
+- Observe: where information enters the loop.
+- Act: where a decision writes back to the world.
+
+Spot gaps gently. A user may have one dataset but need additional observations
+to orient well, or may rely on hard-to-automate interfaces such as phone calls
+or physical mail.
+
 ## OODA Loop
 
 Use the observe-orient-decide-act loop as the product frame:
 
-- Observe: source systems, human signals, files, screenshots, exports, APIs,
-  reference specs, and prior Airlock outputs.
-- Orient: row grain, field types, access model, evidence, workflow, references,
-  expectations, and risk.
-- Decide: the smallest governed output worth creating now.
-- Act: validate locally, create in Airlock, collect real records, then extend or
-  add the next spec based on feedback.
+- Observe: controlled interface ingestion and observation/reference specs.
+- Orient: context, proposals, scoring, exception queues, summaries, and gaps in
+  the observation set.
+- Decide: governed choices by people or agents, with identity, timestamp,
+  rationale, evidence, approval, and separation of duties.
+- Act: controlled writes back to interfaces, commitments, follow-ups, outputs,
+  and the next observations created by those actions.
 
 ## Pattern Guidance
 

package/.agents/skills/airlock-mcp/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Airlock MCP"
-  short_description: "Draft and review Airlock specs with Codex."
-  default_prompt: "Use $airlock-mcp to help me draft a small Airlock spec, choose a starting pattern, and check the local workspace."
+  short_description: "Improve a process with Airlock specs and OODA loop planning."
+  default_prompt: "Use $airlock-mcp to ask what process I want to improve, identify the loop around it, draft a small first Airlock spec, and keep a plan for more specs."

package/README.md

@@ -5,18 +5,21 @@ Airlock.
 
 It covers the full Airlock loop:
 
-- build specs with the bundled spec-building workbench
-- use specs to pull and push governed data with the Airlock Star capability
+- design specs with the bundled spec-building workbench
+- map the process a person wants to improve into observe, orient, decide, and act
+- use specs for governed data movement, decisions, actions, and feedback loops
 - validate, create, and revise specs against installed Airlock
-- capture real use cases and improvements so specs get better over time
 
 Spec building is not a second thing users install. It is bundled inside
 Airlock MCP.
 
-Airlock Star is not a second thing users install either. It is the capability
-inside Airlock MCP for working through real Airlock use cases,
-pulling and pushing data through specs, reading outputs, and turning experience
-back into better specs.
+Airlock MCP gives agents two kinds of Airlock expertise:
+
+1. Spec design: draft, check, revise, import, clone, and prepare specs for
+   installed Airlock validation.
+2. Airlock operating patterns: use specs to organize observations, orientation,
+   governed decisions, controlled actions, separation of duties, and feedback
+   loops.
 
 ## Install
 
@@ -26,7 +29,7 @@ Dogfood directly from GitHub:
 npx -y github:reunionstudio/airlock-mcp install --package github:reunionstudio/airlock-mcp
 ```
 
-After the npm package is published, use:
+Install from npm:
 
 ```bash
 npx @reunionstudio/airlock-mcp install
@@ -45,9 +48,9 @@ The GitHub dogfood command registers:
 codex mcp add airlock -- npx -y github:reunionstudio/airlock-mcp server
 ```
 
-The server exposes bootstrap guidance for starting a specs repo and entering
-the bundled spec-building workbench or the Airlock Star use-and-improve
-capability.
+The server exposes bootstrap guidance for starting a specs repo, coaching a
+person through process discovery, and entering the bundled spec-building
+workbench when a first spec is ready to draft.
 
 This install shape uses Node because `npx` runs npm package binaries. MCP itself
 does not require Node. Once Airlock MCP does real operational work, such as
@@ -116,11 +119,11 @@ The intended user flow is:
 2. Open Codex.
 3. Create a blank project repo named for the org or project, such as
    `home-specs`.
-4. Ask Codex to use Airlock MCP to help build specs and use specs with
-   Airlock Star.
-5. Let Airlock MCP bootstrap the project, welcome the user, and offer the next
-   useful path before creating the first workspace.
+4. Ask Codex to use Airlock MCP to help improve a process with Airlock specs.
+5. Let Airlock MCP bootstrap the project, ask what process the user wants to
+   improve, and propose a small first spec plus a plan for more.
 
 The first workspace should not be created automatically. The spec-building
-workbench should offer OODA brainstorming, a known-process draft, or a shared
-`posts` feedback loop.
+workbench should first ask for the messy process, identify where information
+comes in and actions go out, then choose a small observation, orient, decision,
+or action spec.

package/docs/architecture.md

@@ -28,9 +28,10 @@ heavier operational tools mature.
 
 The spec-building workbench lives in this repo under `src/airlock_mcp`,
 `patterns`, `workspaces`, `schemas`, and `.agents/skills/airlock-mcp`.
-Airlock Star is the use-and-improve capability inside Airlock MCP: real use
-cases, governed pull/push through specs, output review, and improvement capture.
-It is also not a second install.
+Airlock operating patterns live in the same MCP experience: real use cases,
+controlled interface ingestion, OODA loops, governed decisions, separation of
+duties, controlled actions, output review, and improvement capture. This is not
+a second install or separate product surface.
 
 ## MCP Surface
 
@@ -45,8 +46,8 @@ The bootstrap server exposes:
   `airlock_next`, `airlock_export_csv`, and `airlock_render_sql`
 
 These give the agent enough context to start a blank `<project>-specs` repo,
-enter the spec-building workbench when specs need drafting, enter Star when
-specs need to be used or improved, and avoid creating a first workspace until
+ask what process the user wants to improve, enter the spec-building workbench
+when a first spec is ready to draft, and avoid creating a first workspace until
 the user chooses a path.
 
 Workbench tools call the bundled Python package with argument arrays and a

package/docs/install-surface.md

@@ -13,8 +13,9 @@ npx @reunionstudio/airlock-mcp install
 
 Airlock MCP is the single installed interface for agents working with Airlock.
 Then the user opens Codex, creates a blank `<project>-specs` repo, and starts
-chatting with Airlock. Airlock MCP should cover building specs, using specs to
-pull and push governed data, and capturing improvements from real use cases.
+chatting with Airlock. Airlock MCP should start by asking what process the user
+wants to improve, then help design specs and operating patterns around observe,
+orient, decide, and act.
 
 The install command is not the spec workspace. It is the connector/setup entry
 point. The specs repo is still the durable memory.
@@ -107,6 +108,7 @@ The first release should optimize the user journey:
 
 1. install connector
 2. create blank `<project>-specs` Codex project
-3. bootstrap the spec-building capability when specs need drafting
-4. help the user use specs to validate, load, read, push, and pull data
-5. create the first workspace only after the user chooses a path
+3. ask what process the user wants to improve
+4. map where information comes in and actions go out
+5. create the first workspace only after the user chooses a small first spec
+6. keep a plan for later specs that improve the full loop

package/docs/ooda-loop.md

@@ -1,10 +1,16 @@
 # OODA Loop For Airlock Specs
 
-Airlock specs should support a business loop, not just a table.
+Airlock specs should support a process loop, not just a table.
+
+Airlock works best when we can identify where information comes in and where
+actions go out. Those places might be apps, files, forms, people, emails, calls,
+mail, websites, APIs, data feeds, physical events, payment tools, bank apps, or
+shared folders. After those examples are clear, call them interfaces: where the
+process observes from or acts through.
 
 ## Observe
 
-Name the evidence and systems that matter:
+Name the interfaces, evidence, and signals that matter:
 
 - human entries
 - agent observations
@@ -15,7 +21,7 @@ Name the evidence and systems that matter:
 
 ## Orient
 
-Turn observations into a governed shape:
+Turn observations into context that can support a decision:
 
 - one row grain
 - durable identifiers
@@ -27,14 +33,20 @@ Turn observations into a governed shape:
 - workflow
 - references
 - expectations
+- missing observations or quality gaps
 
 ## Decide
 
-Choose the smallest governed output worth creating now. If uncertainty is high,
-start with `posts` and let real feedback shape the next spec.
+Capture the governed choice. A decision spec should identify who or what made
+the choice, when it happened, which option was selected, what evidence or
+rationale mattered, and what separation of duties applies.
 
 ## Act
 
-Create the spec in Airlock only after local drafting is coherent. Then collect
-records, review them, and decide whether to revise the spec or add the next
-small spec.
+Model the action that follows the decision: send an email, submit payment,
+update a website, change a price, open a ticket, trigger outreach, produce a
+filing, request more evidence, or create another governed output. The action
+creates new observations and the loop spins again.
+
+Start with one small useful spec, then keep a plan for the next specs that
+complete or improve the loop.

package/docs/workflows.md

@@ -20,10 +20,13 @@ The preferred Codex prompt is:
 ```text
 I want to use Airlock MCP to start working with Airlock specs for Home.
 
-Set up this project as an Airlock specs repo. Use the Airlock MCP
-spec-building capability when we need to draft or revise specs. Welcome me,
-help me think through real Airlock use cases, and ask only for the missing
-decisions. Do not create the first workspace until I choose a path.
+Set up this project as an Airlock specs repo. Welcome me by asking what
+process I want to improve. Explain that Airlock works best when we can
+identify the loop around that process: what information comes in, what context
+helps us understand it, what decision needs to be made, and what action happens
+after the decision. Ask for the messy version, then help turn it into a small
+first Airlock spec and a plan for more. Do not create the first workspace until
+I choose a path.
 ```
 
 When dogfooding this implementation repo before the MCP package is published,
@@ -66,26 +69,43 @@ The MCP-style flow should be:
 2. Open Codex.
 3. Create a new blank project named for the org or project, such as
    `home-specs`.
-4. Tell Codex: `Use Airlock to help me build and use specs.`
-5. Airlock MCP welcomes, offers OODA brainstorming, a known-process draft, a
-   `posts` feedback loop, or installed-Airlock validation/use.
+4. Tell Codex: `Use Airlock to help me improve a process with specs.`
+5. Airlock MCP welcomes, asks what process the user wants to improve, explains
+   the loop around the process, and proposes a small first spec plus a plan for
+   more.
 
 `init-repo` creates `AGENTS.md`, `.agents/skills/airlock-mcp/SKILL.md`, and
 `workspaces/`. That is what lets Codex understand prompts such as
 `Use $airlock-mcp` inside the specs repo.
 
-After bootstrap, offer three paths before creating a workspace:
+After bootstrap, do not start with a pattern picker. Ask:
 
-- brainstorm possible specs using the OODA loop
-- start from a known process and create a blank workspace
-- create a `posts` feedback loop for humans and agents to submit requests,
-  observations, and responses
+```text
+What process do you want to improve?
+```
+
+Then explain:
+
+- Airlock works best when we can identify what information comes in.
+- Airlock works best when we can identify what context helps people or agents
+  understand that information.
+- Airlock works best when we can identify what decision needs to be made.
+- Airlock works best when we can identify what action happens after the
+  decision.
+
+Information may come from apps, files, forms, people, emails, calls, mail,
+websites, APIs, data feeds, or physical events. Actions may go back through
+those same places. After giving examples, call these places interfaces: where
+the process observes from or acts through.
+
+Ask for the messy version. Help turn it into a small first Airlock spec and a
+plan for more.
 
 ## Start From Feedback
 
 Use this when the user chooses a shared feedback loop for humans and agents.
-If they are not sure what to model yet, offer OODA brainstorming before creating
-this workspace.
+If they are not sure what to model yet, continue process discovery before
+creating this workspace.
 
 ```bash
 airlock-mcp init feedback-loop --pattern posts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reunionstudio/airlock-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Single-install MCP interface for Airlock agents.",
   "type": "module",
   "repository": {

package/setup.py

@@ -27,7 +27,7 @@ def data_files():
 
 setup(
     name="airlock-mcp",
-    version="0.1.0",
+    version="0.1.1",
     description="Codex-first workbench and CLI for drafting Airlock specs.",
     packages=find_packages("src"),
     package_dir={"": "src"},

package/src/airlock_mcp/__init__.py

@@ -1,3 +1,3 @@
 """Airlock MCP CLI package."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"

package/src/airlock_mcp/bootstrap.py

@@ -37,23 +37,35 @@ installed Airlock app.
 
 ## Starting A Spec Project
 
-After bootstrap, welcome the user and orient before creating a workspace. Ask
-whether they want to:
+After bootstrap, welcome the user and orient before creating a workspace. Start
+with:
 
-- brainstorm possible specs with the OODA loop
-- start from a known process they already have in mind
-- create a shared `posts` feedback loop for humans and agents to submit
-  requests, observations, and responses
+What process do you want to improve?
 
-Create `posts` only when the user chooses a feedback loop or explicitly asks
-for the posts pattern.
+Explain that Airlock works best when we can identify the loop around that
+process:
+
+1. what information comes in
+2. what context helps people or agents understand it
+3. what decision needs to be made
+4. what action happens after the decision
+
+Information may come from apps, files, forms, people, emails, calls, mail,
+websites, APIs, data feeds, or physical events. Actions may go back through
+those same places. After giving examples, call these places interfaces: where
+the process observes from or acts through.
+
+Ask for the messy version. Help turn it into a small first Airlock spec and a
+plan for more. Do not create the first workspace until the user chooses a path.
+Create `posts` only when the user wants a shared feedback loop or explicitly
+asks for the posts pattern.
 
 ## Working Style
 
 - Use the repo-scoped `$airlock-mcp` skill for spec drafting, review, and
   pattern selection.
 - Keep drafts small and concrete. Prefer one useful governed output over a
-  large speculative process map.
+  large speculative process map, then keep a plan for later specs.
 - Preserve decisions in workspace files so future Codex sessions can resume
   without relying on chat memory.
 - Use `airlock-mcp list-workspaces` before guessing which draft to resume.
@@ -78,6 +90,8 @@ Resolve these before final JSON:
 - workflow and pushback
 - references and expectations
 - delegation and agent identity
+- interfaces observed from or acted through
+- likely gaps in observations, orientation, decisions, or actions
 - observe-orient-decide-act loop
 
 Do not encode Airlock lifecycle state, reviewer notes, approval status, or
@@ -155,7 +169,7 @@ def format_bootstrap_result(result: BootstrapResult) -> str:
             "next:",
             "1. Open this repo in Codex.",
             "2. Ask: Use Airlock to help me build and use specs.",
-            "3. Choose OODA brainstorming, a known process, or a posts feedback loop.",
+            "3. Start with: What process do you want to improve?",
         ]
     )
     return "\n".join(lines)

package/src/airlock_mcp/manage.py

@@ -233,8 +233,24 @@ def next_steps(workspace: Path) -> str:
         lines.append(f"2. Run `airlock-mcp summary {workspace}` to confirm the shape.")
         return "\n".join(lines)
     if _text_has_open_placeholders(workspace / "decisions.md"):
-        lines.append("1. Fill in decisions.md for row grain, identifiers, time, evidence, access, and OODA.")
-        lines.append(f"2. Run `airlock-mcp next {workspace}` when the design notes are current.")
+        spec_name = ""
+        if isinstance(spec, dict):
+            core_config = spec.get("core_config")
+            if isinstance(core_config, dict):
+                spec_name = str(core_config.get("spec_name") or "")
+        if spec_name == "posts":
+            lines.append("1. Record the starter assumptions in decisions.md, or change only what is wrong.")
+            lines.append(
+                "2. Defaults: one row is one post/request/observation/response; "
+                "submitters are the owner and approved agents; evidence is optional; "
+                "posted_at is authored or captured time."
+            )
+            lines.append("3. Use posts to collect messy process feedback, then plan the first observe, orient, decide, or act spec.")
+        else:
+            lines.append("1. Record the messy process goal and first-loop assumptions in decisions.md.")
+            lines.append("2. Identify what is observed, what helps orient, what decision is governed, and what action follows.")
+            lines.append("3. Keep the first spec small and note later specs in review.md.")
+        lines.append(f"4. Run `airlock-mcp next {workspace}` when the design notes are current.")
         return "\n".join(lines)
     records = sample.get("records") if isinstance(sample, dict) else []
     if not records:

package/src/mcp.mjs

@@ -44,10 +44,10 @@ export function handleMcpRequest(message) {
       },
       serverInfo: {
         name: "airlock",
-        version: "0.1.0",
+        version: "0.1.1",
       },
       instructions:
-        "Airlock MCP helps agents build and use Airlock specs. Use airlock_start for orientation or the airlock_* tools to bootstrap, draft, check, summarize, export, and render specs.",
+        "Airlock MCP helps agents improve processes with Airlock specs. Use airlock_start for orientation or the airlock_* tools to bootstrap, draft, check, summarize, export, and render specs.",
     });
   }
 

package/src/text.mjs

@@ -21,10 +21,15 @@ export function airlockPrompt(project) {
   const repoName = specsRepoName(project);
   return `I want to use Airlock MCP to start working with Airlock specs for ${repoName}.
 
-Set up this project as an Airlock specs repo. Use Airlock MCP
-spec-building when we need to draft or revise specs. Welcome me,
-help me think through real Airlock use cases, and ask only for the missing
-decisions. Do not create the first workspace until I choose a path.`;
+Set up this project as an Airlock specs repo. Welcome me by asking what
+process I want to improve. Explain that Airlock works best when we can
+identify the loop around that process: what information comes in, what context
+helps us understand it, what decision needs to be made, and what action happens
+after the decision. Information may come from apps, files, forms, people,
+emails, calls, mail, websites, APIs, data feeds, or physical events. Actions
+may go back through those same places. Ask for the messy version, then help
+turn it into a small first Airlock spec and a plan for more. Do not create the
+first workspace until I choose a path.`;
 }
 
 export function nextSteps(project) {
@@ -40,28 +45,29 @@ ${airlockPrompt(project)
   .join("\n")}
 
 Airlock MCP will offer:
-  - spec-building with the bundled workbench
-  - spec use and improvement loops with Airlock Star
-  - guidance for pulling and pushing governed data through specs
-  - OODA brainstorming for possible specs
-  - a blank workspace for a known process
-  - a posts feedback loop for shared human/agent feedback`;
+  - process discovery before choosing a spec pattern
+  - spec design with the bundled workbench
+  - Airlock operating patterns for OODA loops and separation of duties
+  - observe specs for controlled interface ingestion
+  - orient specs for proposals, context, scoring, or exception queues
+  - decision specs and action specs for governed follow-through`;
 }
 
 export function gettingStartedText(project) {
   return `# Airlock MCP
 
 Airlock MCP is the single installed interface for AI agents working with
-Airlock. It helps a person and their agent build specs, pull and push governed data
-through specs, and improve Airlock workflows from real use cases.
+Airlock. It helps a person and their agent improve processes by designing
+specs, using specs for governed data movement, and planning OODA loops that
+can be assisted by people or agents.
 
-The Airlock MCP spec-building workbench drafts, checks, revises, imports,
-clones, and prepares specs for installed Airlock validation.
+Airlock MCP gives agents two kinds of Airlock expertise:
 
-Airlock Star is the use-and-improve capability inside Airlock MCP. Use it when
-someone wants to pull or push governed data through specs, exercise real
-Airlock workflows, inspect outputs, or turn field experience into spec
-improvements.
+1. Spec design: draft, check, revise, import, clone, and prepare specs for
+   installed Airlock validation.
+2. Airlock operating patterns: use specs to organize observations, orientation,
+   governed decisions, controlled actions, separation of duties, and feedback
+   loops.
 
 Start in a blank project specs repo such as ${specsRepoName(project)}. Do not
 work inside the Airlock MCP implementation repo unless you are changing the
@@ -71,16 +77,22 @@ Use this prompt in the blank specs repo:
 
 ${airlockPrompt(project)}
 
-After bootstrap, choose the next useful path:
+First ask: What process do you want to improve?
 
-1. Brainstorm possible specs using the OODA loop.
-2. Start from a known process and create a blank workspace.
-3. Create a posts feedback loop for humans and agents to submit requests,
-   observations, and responses.
-4. Use Airlock Star with an installed Airlock app to validate specs, load data,
-   read outputs, plan push/pull workflows, and capture improvements.
+Airlock works best when we can identify the loop around a process:
 
-Create posts only when the user chooses the feedback-loop path.`;
+1. Observe: what information comes in.
+2. Orient: what context helps people or agents understand it.
+3. Decide: what choice needs to be governed.
+4. Act: what happens after the decision.
+
+Information may come from apps, files, forms, people, emails, calls, mail,
+websites, APIs, data feeds, or physical events. Actions may go back through
+those same places. Airlock calls these places interfaces: where the process
+observes from or acts through.
+
+Give Codex the messy version of the process. Airlock MCP should help turn it
+into a small first Airlock spec and a plan for more.`;
 }
 
 export function helpText() {
@@ -103,6 +115,7 @@ Options:
 
 Airlock MCP is the single installed interface for agents working with Airlock.
 Spec building is bundled inside that experience.
-Airlock Star is the use-and-improve capability inside that experience.
+Airlock operating patterns help connect specs into OODA loops, separation of
+duties, governed decisions, controlled actions, and feedback loops.
 `;
 }