@reunionstudio/airlock-mcp 0.1.2 → 0.1.4

package/src/airlock_mcp/bootstrap.py

@@ -16,8 +16,9 @@ This repo is an Airlock MCP workspace for drafting Airlock specs with Codex.
 The public install surface is Airlock MCP, for example
 `npx @reunionstudio/airlock-mcp install`. Airlock MCP is the single installed
 interface for building specs, using specs, pulling and pushing governed data,
-and discovering improvements from real use cases. This project repo remains
-the durable memory for the specs being drafted.
+building apps or workflows that use existing specs, and discovering
+improvements from real use cases. This project repo remains the durable memory
+for the specs being drafted.
 
 ## Repo Naming
 
@@ -45,7 +46,13 @@ installed Airlock app.
 ## Starting A Spec Project
 
 After bootstrap, welcome the user and orient before creating a workspace. Start
-with:
+by asking which delivery mode they want:
+
+1. Spec-first: design governed specs before building the app surface.
+2. App-first: build from existing specs.
+3. Co-development: develop the app and specs together.
+
+For spec-first or co-development work, ask:
 
 What process do you want to improve?
 
@@ -79,10 +86,64 @@ 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.
 
+## Building Apps With Existing Specs
+
+Use this path when the user wants to build an app, dashboard, approval queue,
+decision UI, analysis workflow, scheduled agent, or other code that uses specs
+they already have access to. Treat this as app/workflow implementation, not
+spec editing, unless the user explicitly asks to change specs.
+
+Use `airlock-mcp init-app-context` in an app repo when the app needs local
+Airlock context. It creates `airlock/specs.manifest.json`,
+`airlock/spec-snapshots/`, `airlock/sample-records/`, and generated helper
+folders. These files are app-local references, not canonical specs. Canonical
+specs live in the specs repo or installed Airlock.
+
+Identify:
+
+- the app goal and decision the app should support
+- read specs such as budgets, expenses, requests, forecasts, observations,
+  payouts, or reference data
+- write specs such as decisions, approvals, comments, commitments, actions, or
+  follow-ups
+- where the app should run, such as Streamlit, web app, CLI, notebook,
+  scheduled agent, or existing app framework
+- the Airlock access path available in this environment
+- identity, evidence, timestamp, approval, and separation-of-duties rules
+
+Installed Airlock separates procedure intent:
+
+- `observe.*`: read-only governance observation for discovery, health, access
+  explanation, governance maps, activity, billing events, and context packets.
+- `agent.*`: governed agent work in the actor's scope.
+- `admin.*`: administrative mutation and operational changes.
+
+For app-first work, use observe payloads such as `observe.procedures`,
+`observe.specs`, `observe.spec`, `observe.governance_map`,
+`observe.explain_access`, `observe.health`, `observe.activity`,
+`observe.admin_activity`, `observe.spec_admin_activity`, and
+`observe.billing_events` before inventing custom read paths. For `alter_spec`
+activity, use `CHANGED_SECTIONS` and `CHANGED_FIELDS` to triage what changed
+before fetching version snapshots. Do not call retired admin read wrappers such as `admin.list_specs`, `admin.describe_role`,
+or `admin.list_events`; use the matching observe list/detail procedure.
+
+The app may orient the user with summaries, comparisons, rankings, exception
+queues, proposals, or dashboards. It should submit governed choices back
+through an Airlock spec contract. Do not write directly to Airlock-owned tables,
+stages, generated views, or generated tables. Do not bypass spec workflow just
+because the app can connect to Snowflake. If no suitable decision or action spec
+exists, explain the gap and propose a small spec-design step.
+
+In co-development mode, keep two tracks visible:
+
+- Spec track: row grain, columns, samples, access, validation, workflow
+- App track: screens, reads, decisions, writes, user actions, runtime
+
 ## Working Style
 
 - Use the repo-scoped `$airlock-mcp` skill for spec drafting, review, and
-  pattern selection.
+  pattern selection, or for app/workflow implementation that uses existing
+  Airlock specs.
 - Keep drafts small and concrete. Prefer one useful governed output over a
   large speculative process map, then keep a plan for later specs.
 - Preserve decisions in workspace files so future Codex sessions can resume

package/src/airlock_mcp/cli.py

@@ -5,6 +5,7 @@ import sys
 from pathlib import Path
 
 from . import __version__
+from .app_context import APP_CONTEXT_MODES, format_app_context_result, init_app_context
 from .art import about_text
 from .bootstrap import bootstrap_repo, format_bootstrap_result
 from .jsonio import read_json
@@ -64,6 +65,17 @@ def init_repo(args: argparse.Namespace) -> int:
     return 0
 
 
+def init_app(args: argparse.Namespace) -> int:
+    result = init_app_context(
+        Path(args.path),
+        mode=args.mode,
+        spec_sources=[Path(source) for source in args.spec],
+        force=args.force,
+    )
+    print(format_app_context_result(result))
+    return 0
+
+
 def init_workspace(args: argparse.Namespace) -> int:
     patterns = load_patterns(repo_root())
     pattern = patterns[args.pattern]
@@ -308,6 +320,26 @@ def build_parser() -> argparse.ArgumentParser:
     init_repo_parser.add_argument("--force", action="store_true", help="Overwrite AGENTS.md and the repo-scoped skill.")
     init_repo_parser.set_defaults(func=init_repo)
 
+    init_app_parser = subparsers.add_parser(
+        "init-app-context",
+        help="Prepare an app repo airlock/ context with spec snapshots and a manifest.",
+    )
+    init_app_parser.add_argument("path", nargs="?", default=".", help="App repo path. Defaults to current directory.")
+    init_app_parser.add_argument(
+        "--mode",
+        choices=APP_CONTEXT_MODES,
+        default="app-first",
+        help="Development mode. Defaults to app-first.",
+    )
+    init_app_parser.add_argument(
+        "--spec",
+        action="append",
+        default=[],
+        help="Spec workspace directory or spec JSON file to snapshot. Repeat for multiple specs.",
+    )
+    init_app_parser.add_argument("--force", action="store_true", help="Overwrite app context files.")
+    init_app_parser.set_defaults(func=init_app)
+
     init_parser = subparsers.add_parser("init", help="Create a spec workspace.")
     init_parser.add_argument("name", help="Workspace folder name.")
     init_parser.add_argument(

package/src/airlock_mcp/summary.py

@@ -247,6 +247,7 @@ def workspace_summary(
         f"  owner_role: {_format_value(core.get('owner_role'))}",
         f"  published: {_format_value(core.get('is_published'))}",
         f"  archived: {_format_value(core.get('is_archived'))}",
+        f"  payload_adapter: {_format_value(core.get('payload_adapter'), default='default')}",
         f"  description: {_truncate(core.get('description')) or 'none'}",
         "",
         "file_rules:",

package/src/mcp.mjs

@@ -7,7 +7,7 @@ const GETTING_STARTED_URI = "airlock://getting-started";
 
 const START_TOOL = {
   name: "airlock_start",
-  description: "Return Airlock MCP setup guidance for building and using Airlock specs.",
+  description: "Return Airlock MCP setup guidance for specs and apps that use specs.",
   inputSchema: {
     type: "object",
     properties: {
@@ -44,10 +44,10 @@ export function handleMcpRequest(message) {
       },
       serverInfo: {
         name: "airlock",
-        version: "0.1.2",
+        version: "0.1.4",
       },
       instructions:
-        "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.",
+        "Airlock MCP helps agents improve processes with Airlock specs and build apps or workflows that use existing specs. Use airlock_start for orientation or the airlock_* tools to bootstrap, draft, check, summarize, export, and render specs.",
     });
   }
 
@@ -84,7 +84,7 @@ export function handleMcpRequest(message) {
         {
           name: "airlock-start",
           title: "Start Airlock",
-          description: "Bootstrap a Git-backed specs repo and choose the first Airlock path.",
+          description: "Bootstrap a Git-backed specs repo or choose an Airlock app/spec path.",
           arguments: [
             {
               name: "project",
@@ -103,7 +103,7 @@ export function handleMcpRequest(message) {
     }
     const project = params?.arguments?.project || "Home";
     return makeResponse(id, {
-      description: "Start building and using Airlock specs in a Git-backed specs repo.",
+      description: "Start building specs or apps that use Airlock specs.",
       messages: [
         {
           role: "user",

package/src/text.mjs

@@ -25,19 +25,23 @@ Set up this project as an Airlock specs repo. If this project is not already a
 Git repo, recommend storing it in version control, preferably GitHub if that is
 available. If you are creating the repo for me, ask where the ${repoName}
 directory should live before making it, then offer to initialize git and create
-or push a GitHub repo.
-
-Welcome me by asking what process I want to improve. Explain that Airlock works
+or push a GitHub repo. If I am in an app repo and want to build software that
+uses existing specs, or develop the app and specs together, do not bootstrap a
+specs repo unless I ask for spec edits.
+
+Welcome me by asking whether I want spec-first, app-first, or co-development:
+spec-first designs governed specs before the app, app-first builds from existing
+specs, and co-development evolves the app and specs together. For spec-first or
+co-development, ask 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 whether I already have artifacts:
-CSV or Excel files, JSON samples, API docs, schemas, forms, screenshots, PDFs,
-exports, message examples, or other content people already use. Treat a small
-real sample as stronger evidence than a long explanation, and remind me to
-redact secrets.
+forms, people, emails, calls, mail, websites, APIs, data feeds, or physical
+events. Actions may go back through those same places. Ask whether I already
+have artifacts: CSV or Excel files, JSON samples, API docs, schemas, forms,
+screenshots, PDFs, exports, message examples, or other content people already
+use. Treat a small real sample as stronger evidence than a long explanation,
+and remind me to redact secrets.
 
 When useful, check the reusable airlock-specs library for starting points,
 patterns, and ideas, but do not assume those library specs match current
@@ -45,7 +49,26 @@ third-party systems. Prefer current API docs, real exports, samples, and other
 artifacts when they conflict with a library shape.
 
 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.`;
+and a plan for more. Do not create the first workspace until I choose a path.
+
+If I want app-first or co-development, ask for the app goal, the specs I can
+access, which specs are read sources, which spec records decisions or actions,
+and where the app should run. Teach the installed Airlock procedure split:
+\`airlock.observe.*\` is read-only governance observation,
+\`airlock.agent.*\` is governed agent work, and \`airlock.admin.*\` is
+administrative mutation. Prefer observe payloads such as
+\`observe.procedures\`, \`observe.specs\`, \`observe.spec\`,
+\`observe.governance_map\`, \`observe.explain_access\`, \`observe.health\`,
+\`observe.activity\`, \`observe.admin_activity\`, \`observe.spec_admin_activity\`,
+and \`observe.billing_events\` before inventing custom read paths. For \`alter_spec\`
+activity, use \`CHANGED_SECTIONS\` and \`CHANGED_FIELDS\` to triage what changed
+before fetching version snapshots. Offer to run \`airlock-mcp init-app-context\`
+in the app repo to seed \`airlock/specs.manifest.json\`, spec snapshots, sample records, and
+generated helper folders. Help code the app using approved Airlock/Snowflake access paths.
+Do not use retired admin read wrappers such as
+\`admin.list_specs\`, \`admin.describe_role\`, or \`admin.list_events\`; use
+the matching observe procedure. Do not write directly to Airlock-owned tables
+or bypass spec workflow.`;
 }
 
 export function nextSteps(project) {
@@ -63,11 +86,16 @@ ${airlockPrompt(project)
 
 Airlock MCP will offer:
   - process discovery before choosing a spec pattern
+  - spec-first, app-first, and co-development planning
   - spec design with the bundled workbench
   - Airlock operating patterns for OODA loops and separation of duties
+  - read-only observe procedures for governance maps, health, access explanation, activity, billing events, and context packets
+  - app context seeding with spec snapshots and manifests
+  - app and workflow coding against existing Airlock specs
   - observe specs for controlled interface ingestion
   - orient specs for proposals, context, scoring, or exception queues
   - decision specs and action specs for governed follow-through
+  - OKF-style Markdown knowledge bundles for accepted agent context
   - artifact-grounded drafts from CSV, Excel, JSON, API docs, schemas, forms, screenshots, PDFs, or exports
   - airlock-specs library patterns as starting points, checked against current artifacts`;
 }
@@ -77,16 +105,23 @@ export function gettingStartedText(project) {
 
 Airlock MCP is the single installed interface for AI agents working with
 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.
+specs, using specs for governed data movement, planning OODA loops, and building
+apps or workflows that read from and submit through existing specs.
 
-Airlock MCP gives agents two kinds of Airlock expertise:
+Airlock MCP gives agents four kinds of Airlock help:
 
 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.
+3. App and workflow implementation: build dashboards, queues, decision UIs,
+   analyses, and agent workflows that use existing specs without bypassing
+   Airlock contracts.
+4. Governance observation: use installed Airlock's read-only \`observe.*\`
+   procedures to inspect setup, access, activity, billing events, health,
+   context packets, and governance maps before deciding what an app or agent
+   should do.
 
 Start in a Git-backed specs repo such as ${specsRepoName(project)}. GitHub is
 the recommended default when the user has it set up, but any normal repository
@@ -98,7 +133,13 @@ Use this prompt in the specs repo:
 
 ${airlockPrompt(project)}
 
-First ask: What process do you want to improve?
+First ask which delivery mode the user wants:
+
+1. Spec-first: design governed specs before building the app surface.
+2. App-first: build an app or workflow from existing specs.
+3. Co-development: develop the app and specs together.
+
+For spec-first and co-development work, ask: What process do you want to improve?
 
 Airlock works best when we can identify the loop around a process:
 
@@ -122,8 +163,34 @@ points, patterns, and ideas. Library specs are not guaranteed to match the
 current shape of any third-party system. Prefer current API docs, real exports,
 samples, and other artifacts when they conflict with the library.
 
+For governed Markdown knowledge, use the \`okf-knowledge-bundle\` pattern. It
+creates a spec with \`core_config.payload_adapter\` set to
+\`okf_knowledge_bundle\`. Installed Airlock loads locally validated bundles with
+\`airlock.admin.load_okf_bundle(...)\`, can sync parsed metadata with
+\`airlock.admin.sync_okf_bundle_metadata(...)\`, and exposes authoritative
+accepted context through \`AIRLOCK_DATA.ACTIVE.V_OKF_CONCEPT_METADATA\`.
+
 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.`;
+into a small first Airlock spec and a plan for more.
+
+For app-first and co-development work, give Codex the app goal and available
+specs. Airlock MCP should identify read specs, write specs, orienting views,
+decision capture, and safe Airlock/Snowflake access paths. Installed Airlock
+uses \`observe.*\` for read-only governance observation, \`agent.*\` for
+governed agent work, and \`admin.*\` for administrative mutation. Start
+read-side discovery with observe payloads such as \`observe.procedures\`,
+\`observe.specs\`, \`observe.spec\`, \`observe.governance_map\`,
+\`observe.explain_access\`, \`observe.health\`, \`observe.activity\`,
+\`observe.admin_activity\`, \`observe.spec_admin_activity\`, and \`observe.billing_events\`;
+for \`alter_spec\` activity, use \`CHANGED_SECTIONS\` and \`CHANGED_FIELDS\` to
+triage what changed before fetching version snapshots. Do not use retired admin
+read wrappers such as \`admin.list_specs\`, \`admin.describe_role\`, or
+\`admin.list_events\`. It can
+seed an app repo with \`airlock/specs.manifest.json\`, spec snapshots, sample
+records, and generated helper folders. The app should submit decisions,
+approvals, actions, comments, or follow-ups through Airlock spec contracts, not
+direct table writes.
+In co-development mode, keep the spec track and app track visible side by side.`;
 }
 
 export function helpText() {
@@ -148,5 +215,7 @@ Airlock MCP is the single installed interface for agents working with Airlock.
 Spec building is bundled inside that experience.
 Airlock operating patterns help connect specs into OODA loops, separation of
 duties, governed decisions, controlled actions, and feedback loops.
+Airlock MCP can also help build apps and workflows that use existing specs for
+approved reads and governed submissions.
 `;
 }

package/src/workbench.mjs

@@ -23,6 +23,8 @@ const workspaceProperty = {
   maxLength: MAX_ARG_LENGTH,
 };
 
+const appModeValues = ["spec-first", "app-first", "co-development"];
+
 export const WORKBENCH_TOOLS = [
   {
     name: "airlock_doctor",
@@ -42,6 +44,32 @@ export const WORKBENCH_TOOLS = [
       cwd: cwdProperty,
     }),
   },
+  {
+    name: "airlock_init_app_context",
+    description: "Seed an app repo with airlock/ spec snapshots, samples, generated placeholders, and a manifest.",
+    inputSchema: objectSchema({
+      path: {
+        type: "string",
+        description: "App repo path to initialize. Defaults to the current directory.",
+        maxLength: MAX_ARG_LENGTH,
+      },
+      mode: {
+        type: "string",
+        enum: appModeValues,
+        description: "Development mode. Defaults to app-first.",
+      },
+      specs: {
+        type: "array",
+        items: {
+          type: "string",
+          maxLength: MAX_ARG_LENGTH,
+        },
+        description: "Spec workspace directories or spec JSON files to snapshot.",
+      },
+      force: forceProperty,
+      cwd: cwdProperty,
+    }),
+  },
   {
     name: "airlock_list_patterns",
     description: "List bundled Airlock spec starter patterns.",
@@ -54,7 +82,7 @@ export const WORKBENCH_TOOLS = [
       {
         pattern: {
           type: "string",
-          enum: ["blank", "posts"],
+          enum: ["blank", "okf-knowledge-bundle", "posts"],
           description: "Pattern to inspect.",
         },
         files: {
@@ -78,7 +106,7 @@ export const WORKBENCH_TOOLS = [
         },
         pattern: {
           type: "string",
-          enum: ["blank", "posts"],
+          enum: ["blank", "okf-knowledge-bundle", "posts"],
           description: "Starting pattern. Defaults to blank.",
         },
         output: {
@@ -230,6 +258,28 @@ function optionalEnum(args, name, allowed, fallback) {
   return value;
 }
 
+function optionalStringArray(args, name) {
+  const value = args?.[name];
+  if (value === undefined || value === null) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`${name} must be an array`);
+  }
+  return value.map((entry, index) => {
+    if (typeof entry !== "string") {
+      throw new Error(`${name}[${index}] must be a string`);
+    }
+    if (entry.length > MAX_ARG_LENGTH || /[\u0000-\u001f\u007f]/.test(entry)) {
+      throw new Error(`${name}[${index}] must be ${MAX_ARG_LENGTH} characters or fewer with no control characters`);
+    }
+    if (entry.startsWith("-")) {
+      throw new Error(`${name}[${index}] must not start with '-'`);
+    }
+    return entry;
+  });
+}
+
 function requiredEnum(args, name, allowed) {
   const value = optionalEnum(args, name, allowed, undefined);
   if (value === undefined) {
@@ -264,6 +314,19 @@ function cliArgsForTool(name, args = {}) {
       if (force) cliArgs.push("--force");
       return { cwd, cliArgs };
     }
+    case "airlock_init_app_context": {
+      const cliArgs = [
+        "init-app-context",
+        optionalString(args, "path", "."),
+        "--mode",
+        optionalEnum(args, "mode", appModeValues, "app-first"),
+      ];
+      for (const spec of optionalStringArray(args, "specs")) {
+        cliArgs.push("--spec", spec);
+      }
+      if (force) cliArgs.push("--force");
+      return { cwd, cliArgs };
+    }
     case "airlock_list_patterns":
       return { cwd, cliArgs: ["list-patterns"] };
     case "airlock_show_pattern": {