@reunionstudio/airlock-mcp 0.1.2 → 0.1.3

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

@@ -1,13 +1,16 @@
 ---
 name: airlock-mcp
-description: Design, draft, review, and iterate Airlock specs in the Airlock MCP spec-building workbench. Use when Codex is helping a person choose a small starting spec, work through row grain and OODA-loop decisions, import reusable patterns such as posts or guest access setups, validate local draft files, or prepare an Airlock spec config before installed Airlock validation.
+description: Design, draft, review, and iterate Airlock specs in the Airlock MCP spec-building workbench, or help build apps and workflows that use existing Airlock specs safely. Use when Codex is helping a person choose a small starting spec, work through row grain and OODA-loop decisions, import reusable patterns such as posts or guest access setups, validate local draft files, prepare an Airlock spec config before installed Airlock validation, or code an app that reads from and submits through existing specs.
 ---
 
-# Airlock MCP Spec Builder
+# Airlock MCP
 
 Use this skill to help a human develop Airlock specs over multiple sessions.
-The repo is the workbench; Codex is the conversational interface; the CLI is
-the deterministic checker.
+Also use it when a human wants to build an app or workflow that uses existing
+Airlock specs. The specs repo is the durable workbench for spec drafts; an app
+repo is the right place for code that reads, orients, decides, and submits
+through existing specs. Codex is the conversational interface; the CLI is the
+deterministic checker for local spec drafts.
 
 ## Default Path
 
@@ -16,6 +19,13 @@ the deterministic checker.
    `sample.records.json`, and `review.md`.
 2. If the current repo is not yet an Airlock MCP specs repo, run or suggest:
    `airlock-mcp init-repo`.
+   Exception: if the user asks to build an app, dashboard, approval queue,
+   decision UI, agent workflow, or other code that uses existing specs, do not
+   bootstrap a specs repo just because the current repo lacks `workspaces/`.
+   Treat the current repo as an app repo unless the user asks to create specs.
+   Ask for the development mode, available specs, app goal, and read/write
+   contract instead. Use `airlock-mcp init-app-context` when the app repo needs
+   an `airlock/` folder with spec snapshots and an app manifest.
    When helping create that repo from scratch, ask for the project or
    organization name and suggest `<slug>-specs`; for example, `Home` becomes
    `home-specs`. Reserve `airlock-specs` for the canonical reusable spec
@@ -35,7 +45,9 @@ 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 ask:
+3. If no workspace exists, welcome the user and ask which mode they want:
+   spec-first, app-first from existing specs, or co-development.
+   For spec-first or co-development, ask:
    `What process do you want to improve?`
    Explain that Airlock works best when we can identify the loop around that
    process:
@@ -159,6 +171,84 @@ Use the observe-orient-decide-act loop as the product frame:
 - Act: controlled writes back to interfaces, commitments, follow-ups, outputs,
   and the next observations created by those actions.
 
+## Apps And Workflows Using Existing Specs
+
+Use this path when the user wants to vibe-code an app, dashboard, queue,
+decision UI, analysis workflow, or agent workflow that uses specs they already
+have access to. This is not spec editing by default.
+
+Use three delivery modes:
+
+- Spec-first: design governed specs, samples, access, and validation before
+  building the app surface.
+- App-first: use existing specs to build an app, dashboard, queue, or workflow.
+- Co-development: develop the app and specs together, keeping the contract and
+  experience visible side by side.
+
+Start by identifying:
+
+1. The app goal: what the user needs to orient around or decide.
+2. Read specs: existing specs the app reads from, such as budgets, expenses,
+   requests, forecasts, observations, payouts, or reference data.
+3. Write specs: existing specs the app submits to, such as decisions,
+   approvals, comments, commitments, actions, or follow-ups.
+4. The app surface: Streamlit, web app, CLI, notebook, scheduled agent, or
+   other runtime.
+5. The Airlock access path: installed Airlock procedures, approved MCP tools,
+   generated read surfaces, stages, or documented SQL helpers available in the
+   user's environment.
+6. Identity, evidence, timestamps, approval, and separation-of-duties rules.
+
+Help the app follow the loop:
+
+- Observe/read: fetch existing governed data through approved Airlock or
+  Snowflake surfaces.
+- Orient: summarize, compare, rank, flag exceptions, propose options, or build
+  dashboards and queues.
+- Decide: capture human or agent choices with rationale and evidence.
+- Act/write: submit the decision, approval, action, or follow-up through an
+  Airlock spec contract.
+
+Keep the boundary clear:
+
+- Do not edit specs unless the user asks for spec changes.
+- Do not write directly to Airlock-owned tables, stages, generated views, or
+  generated tables.
+- Do not treat Snowflake as an unrestricted database just because the app can
+  connect to it.
+- Prefer existing Airlock contracts for reads and writes. If no suitable write
+  spec exists, explain the gap and propose a small decision/action spec as a
+  separate spec-design step.
+- Keep secrets and credentials out of repo files. Use the app's existing secret
+  management pattern.
+
+### App Context Seeding
+
+Use `airlock-mcp init-app-context` in an app repo when the app needs local
+Airlock context. The command creates:
+
+```text
+airlock/
+  AGENTS.md
+  README.md
+  specs.manifest.json
+  spec-snapshots/
+  sample-records/
+  generated/
+    types/
+    sql/
+```
+
+The manifest and snapshots help the app develop against stable local references.
+They are not canonical. Canonical specs live in the specs repo or installed
+Airlock. When seeding from draft workspaces, pass `--spec <workspace>` for each
+spec to copy `spec.config.json` and `sample.records.json` into the app context.
+
+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.
+
 ## Pattern Guidance
 
 Read only the relevant pattern files:

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "Airlock MCP"
-  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, gather any existing artifacts, identify the loop around it, draft a small first Airlock spec, and keep a plan for more specs."
+  short_description: "Design specs or build apps that use Airlock specs."
+  default_prompt: "Use $airlock-mcp to ask whether I want to design specs, improve an OODA loop, or build an app/workflow that uses existing specs; then gather artifacts or available specs and help me move safely."

package/README.md

@@ -8,18 +8,22 @@ It covers the full Airlock loop:
 - 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
+- build apps and workflows that read from and submit through existing specs
 - validate, create, and revise specs against installed Airlock
 
-Spec building is not a second thing users install. It is bundled inside
-Airlock MCP.
+Spec building and spec-using app guidance are not second things users install.
+They are bundled inside Airlock MCP.
 
-Airlock MCP gives agents two kinds of Airlock expertise:
+Airlock MCP gives agents three 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 through Airlock
+   contracts.
 
 ## Install
 
@@ -50,7 +54,8 @@ codex mcp add airlock -- npx -y github:reunionstudio/airlock-mcp server
 
 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.
+workbench when a first spec is ready to draft. It also guides agents building
+apps or workflows that use specs the user already has access to.
 
 Workspace summaries are structured spec cards. They present the current spec
 core, file rules, attachment policy, guest access, column rules, sample record
@@ -90,6 +95,8 @@ The server exposes orientation plus local spec-building tools:
 - `airlock_start`: return setup guidance for a project.
 - `airlock_doctor`: verify bundled workbench assets.
 - `airlock_init_repo`: bootstrap a Git-backed specs repo.
+- `airlock_init_app_context`: seed an app repo with spec snapshots, sample
+  records, generated helper folders, and an app manifest.
 - `airlock_list_patterns` and `airlock_show_pattern`: inspect starter patterns.
 - `airlock_init_workspace`: create a workspace from `blank` or `posts`.
 - `airlock_list_workspaces`: inspect active or archived drafts.
@@ -127,13 +134,48 @@ The intended user flow is:
 4. If Codex is creating the repo, choose where the `home-specs` directory should
    live before files are written.
 5. Ask Codex to use Airlock MCP to help improve a process with Airlock specs.
-6. 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.
+6. Choose a delivery mode: spec-first, app-first from existing specs, or
+   co-development of specs and app together.
+7. Let Airlock MCP bootstrap the project, ask what process the user wants to
+   improve when specs are involved, and propose a small first spec plus a plan
+   for more.
+
+The first workspace should not be created automatically. Airlock MCP should
+first ask whether the user wants spec-first, app-first from existing specs, or
+co-development of specs and app together. For spec-building work, it should ask
+for the messy process, identify where information comes in and actions go out,
+then choose a small observation, orient, decision, or action spec.
+
+For app-building work, Airlock MCP should identify the app goal, read specs,
+write specs, orienting views, decision capture, and approved Airlock/Snowflake
+access paths. The app should submit decisions, approvals, actions, comments, or
+follow-ups through Airlock spec contracts. It should not write directly to
+Airlock-owned tables or bypass spec workflow.
+
+When an app repo needs local Airlock context, use:
 
-The first workspace should not be created automatically. The spec-building
-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.
+```bash
+airlock-mcp init-app-context . --mode app-first --spec ../home-specs/workspaces/expenses
+```
+
+That creates:
+
+```text
+airlock/
+  AGENTS.md
+  README.md
+  specs.manifest.json
+  spec-snapshots/
+  sample-records/
+  generated/
+    types/
+    sql/
+```
+
+The snapshots are for coding, tests, and UI planning. They are not canonical.
+Canonical specs live in the specs repo or installed Airlock. In
+co-development, keep a visible spec track and app track so changes to row
+grain, access, workflow, screens, reads, and governed writes stay aligned.
 
 When the user already has artifacts, Airlock MCP should ask for them early:
 CSV or Excel files, JSON samples, API docs, schemas, forms, screenshots, PDFs,

package/docs/architecture.md

@@ -30,8 +30,9 @@ The spec-building workbench lives in this repo under `src/airlock_mcp`,
 `patterns`, `workspaces`, `schemas`, and `.agents/skills/airlock-mcp`.
 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.
+duties, controlled actions, output review, improvement capture, and app/workflow
+implementation against existing specs. This is not a second install or separate
+product surface.
 
 ## MCP Surface
 
@@ -41,14 +42,24 @@ The bootstrap server exposes:
 - resource: `airlock://getting-started`
 - orientation tool: `airlock_start`
 - workbench tools: `airlock_doctor`, `airlock_init_repo`,
-  `airlock_list_patterns`, `airlock_show_pattern`, `airlock_init_workspace`,
-  `airlock_list_workspaces`, `airlock_check_workspace`, `airlock_summary`,
-  `airlock_next`, `airlock_export_csv`, and `airlock_render_sql`
+  `airlock_init_app_context`, `airlock_list_patterns`,
+  `airlock_show_pattern`, `airlock_init_workspace`, `airlock_list_workspaces`,
+  `airlock_check_workspace`, `airlock_summary`, `airlock_next`,
+  `airlock_export_csv`, and `airlock_render_sql`
 
 These give the agent enough context to start a Git-backed `<project>-specs`
 repo in a user-chosen location, 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.
+avoid creating a first workspace until the user chooses a path. They also give
+the agent enough product guidance to work in an app repo when the user wants to
+build software that reads from existing specs and submits governed decisions or
+actions through Airlock contracts.
+
+`airlock_init_app_context` is the bridge for app-first and co-development work.
+It creates an app-local `airlock/` folder with spec snapshots, sample records,
+generated helper placeholders, and `specs.manifest.json`. Those files support
+coding, tests, and UI planning, but they are not canonical. Canonical specs
+remain in the specs repo or installed Airlock.
 
 Workbench tools call the bundled Python package with argument arrays and a
 controlled `PYTHONPATH`. They do not expose update commands over MCP. Tool

package/docs/install-surface.md

@@ -16,8 +16,10 @@ Then the user opens Codex, creates or opens a Git-backed `<project>-specs`
 repo, and starts chatting with Airlock. GitHub is the recommended default when
 available. If Codex is creating the repo, it should ask where the directory
 should live before writing files. 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.
+delivery mode the user wants: spec-first, app-first from existing specs, or
+co-development of specs and app together. Then it should help design specs and
+operating patterns around observe, orient, decide, and act, or help code an app
+that reads and submits through Airlock contracts.
 
 The install command is not the spec workspace. It is the connector/setup entry
 point. The specs repo is still the durable memory.
@@ -119,3 +121,31 @@ The first release should optimize the user journey:
 7. map where information comes in and actions go out
 8. create the first workspace only after the user chooses a small first spec
 9. keep a plan for later specs that improve the full loop
+
+For users who already have specs and want to build software, optimize a second
+journey:
+
+1. install connector
+2. open the app repo in Codex
+3. ask for the app goal and available specs
+4. identify read specs and write specs
+5. seed app-local Airlock context with `airlock-mcp init-app-context` when the
+   app needs spec snapshots, samples, generated helpers, and a manifest
+6. build orienting views, dashboards, queues, proposals, or recommendations
+7. capture decisions, approvals, actions, comments, or follow-ups through
+   Airlock spec contracts
+8. avoid direct writes to Airlock-owned tables and avoid bypassing spec workflow
+
+For users who are developing the app and specs together, optimize a third
+journey:
+
+1. open the app repo or specs repo in Codex
+2. choose co-development explicitly
+3. keep a spec track for row grain, columns, access, samples, validation, and
+   workflow
+4. keep an app track for screens, reads, orienting summaries, decision capture,
+   governed writes, runtime, and tests
+5. seed the app repo with `airlock/` snapshots and a manifest when the app needs
+   local contract context
+6. treat app snapshots as development references while canonical specs remain
+   in the specs repo or installed Airlock

package/docs/spec-workbench-architecture.md

@@ -14,6 +14,8 @@ Airlock MCP is intentionally small:
 - `art.py`: small terminal identity and about text.
 - `bootstrap.py`: specs-repo bootstrap files, including `AGENTS.md` and the
   repo-scoped Codex skill.
+- `app_context.py`: app-repo Airlock context seeding for spec snapshots,
+  sample records, generated helper placeholders, and `specs.manifest.json`.
 - `manage.py`: workspace discovery, archive, restore, rename, and next-action
   helpers.
 - `project.py`: checkout discovery and environment override handling.
@@ -55,6 +57,8 @@ The old Airlock Streamlit editor used mode-specific hydration:
 Airlock MCP maps that to files:
 
 - `init-repo`: prepare a separate specs repo for Codex and Airlock MCP
+- `init-app-context`: prepare an app repo `airlock/` folder for app-first or
+  co-development work against existing specs
 - `init`: create from a pattern
 - `import-spec`: edit/import an existing canonical or spec-library config in a
   new workspace
@@ -68,6 +72,12 @@ Airlock MCP maps that to files:
 This repo does not try to be the installed Airlock editor. It gives Codex and
 humans a careful drafting surface before Airlock receives the final config.
 
+`init-app-context` does not make app-local snapshots canonical. It gives an app
+repo stable development references for coding, tests, UI planning, and generated
+helpers. Canonical specs remain in the specs repo or installed Airlock. Use
+`--force` to refresh snapshots from canonical workspace files after the spec
+changes.
+
 ## Update Boundary
 
 `self-update` supports two intentionally simple paths:
@@ -119,9 +129,10 @@ npx @reunionstudio/airlock-mcp install
 
 The connector implementation belongs in `reunionstudio/airlock-mcp`. Airlock
 MCP is the single installed interface for agents working with Airlock: building
-specs, using specs to pull and push governed data, and capturing improvements
-from real use cases. This workbench owns the spec-building implementation:
-patterns, bootstrap, workspace files, local checks, and the Codex skill.
+specs, using specs to pull and push governed data, building apps or workflows
+that use existing specs, and capturing improvements from real use cases. This
+workbench owns the spec-building implementation: patterns, bootstrap, workspace
+files, local checks, and the Codex skill.
 
 That command is the agent connector/setup entry point, not the user's spec
 workspace. After installing or registering the connector, the user still creates

package/docs/workflows.md

@@ -87,9 +87,13 @@ The MCP-style flow should be:
 4. If Codex is creating it, choose where the repo directory should live before
    files are written.
 5. Tell Codex: `Use Airlock to help me improve a process with specs.`
-6. 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.
+6. Airlock MCP welcomes and asks which delivery mode the user wants:
+   spec-first, app-first from existing specs, or co-development.
+7. For spec-first or co-development, Airlock MCP 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.
+8. For app-first or co-development, Airlock MCP identifies the app goal,
+   available specs, read specs, write specs, runtime, and approved access path.
 
 `init-repo` creates `AGENTS.md`, `.agents/skills/airlock-mcp/SKILL.md`, and
 `workspaces/`. That is what lets Codex understand prompts such as
@@ -130,6 +134,86 @@ current artifacts and record the divergence.
 Ask for the messy version. Help turn it into a small first Airlock spec and a
 plan for more.
 
+## Build An App From Existing Specs
+
+Use this when the user already has access to specs and wants to build an app,
+dashboard, approval queue, decision UI, analysis workflow, scheduled agent, or
+other code that reads from and submits through Airlock.
+
+Do not bootstrap or edit a specs workspace by default. Work in the app repo
+unless the user asks to change specs. Start by asking for:
+
+- the app goal and decision the app should support
+- the specs the user can access
+- 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 an existing framework
+- the available Airlock/Snowflake access path
+- identity, evidence, timestamp, approval, and separation-of-duties needs
+
+The app should follow the loop:
+
+1. Observe/read governed records through approved Airlock or Snowflake surfaces.
+2. Orient with summaries, comparisons, ranked options, recommendations,
+   exception queues, dashboards, or proposals.
+3. Decide by capturing the human or agent choice with rationale and evidence.
+4. Act/write by submitting the decision, approval, action, comment, or follow-up
+   through an Airlock spec contract.
+
+Keep the boundary explicit: 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.
+
+If the app repo needs local context for coding, seed it with spec snapshots and
+a manifest:
+
+```bash
+airlock-mcp init-app-context . --mode app-first --spec ../home-specs/workspaces/expenses
+```
+
+Use `--mode co-development` when the app and specs will evolve together. Repeat
+`--spec` for each workspace or spec JSON file the app should know about. The
+command creates:
+
+```text
+airlock/
+  AGENTS.md
+  README.md
+  specs.manifest.json
+  spec-snapshots/
+  sample-records/
+  generated/
+    types/
+    sql/
+```
+
+The app repo can import or generate helper code from these snapshots, but the
+snapshots are not canonical. Canonical specs remain in the specs repo or
+installed Airlock. Mark each manifest spec as read, write, or read_write for
+the app before building data access and submission flows.
+
+## Co-Develop Specs And App
+
+Use this when the app surface and the Airlock contracts need to shape each
+other. This is common when a dashboard, queue, approval flow, or agent workflow
+reveals which observations, proposals, decisions, or actions need governed
+records.
+
+Keep two tracks visible:
+
+- Spec track: row grain, columns, samples, attachments, access, validation,
+  workflow, and installed Airlock validation.
+- App track: screens, reads, summaries, ranked options, decision capture,
+  governed writes, runtime, and tests.
+
+Start with the smallest useful contract. The app may expose a thin prototype
+against samples while the spec is being drafted, but live submissions should
+wait for installed Airlock validation and the approved read/write path.
+
 ## Start From Feedback
 
 Use this when the user chooses a shared feedback loop for humans and agents.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reunionstudio/airlock-mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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.2",
+    version="0.1.3",
     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.2"
+__version__ = "0.1.3"

package/src/airlock_mcp/app_context.py

@@ -0,0 +1,271 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .jsonio import read_json, write_json, write_text
+from .specs import extract_spec_config, spec_name
+
+
+APP_CONTEXT_MODES = ("spec-first", "app-first", "co-development")
+
+
+APP_README = """# Airlock App Context
+
+This folder is app-local context for building software that uses Airlock specs.
+
+The canonical specs live in the specs repo or installed Airlock. Files here are
+snapshots, samples, generated helpers, and planning context for app development.
+Refresh them when the canonical spec changes.
+
+Use:
+
+- `specs.manifest.json` to track which specs the app reads from or writes to.
+- `spec-snapshots/` for app-local copies of spec configs.
+- `sample-records/` for app-local sample records used in UI and test fixtures.
+- `generated/types/` for generated application types.
+- `generated/sql/` for reviewed SQL helpers or query templates.
+
+Do not store credentials here. Do not write directly to Airlock-owned tables,
+stages, generated views, or generated tables. Use approved Airlock/Snowflake
+access paths and submit governed decisions or actions through spec contracts.
+"""
+
+
+APP_AGENTS = """# Airlock App Guidance
+
+This repo may contain application code that uses Airlock specs.
+
+## Modes
+
+- Spec-first: design governed specs before building the app surface.
+- App-first: use existing specs to build an app, dashboard, queue, or workflow.
+- Co-development: evolve the app and specs together while keeping the contract
+  explicit.
+
+## App Context
+
+The `airlock/` folder is app-local. Its spec snapshots are references for
+development, not canonical specs. Canonical specs live in the specs repo or
+installed Airlock.
+
+Keep two tracks visible during co-development:
+
+- Spec track: row grain, columns, samples, access, validation, and workflow.
+- App track: screens, reads, decisions, writes, user actions, and runtime.
+
+Use approved Airlock/Snowflake access paths. Do not bypass spec workflow or
+write directly to Airlock-owned tables, stages, generated views, or generated
+tables. If the app needs to submit a decision or action and no suitable write
+spec exists, propose a small spec-design step.
+"""
+
+
+@dataclass(frozen=True)
+class AppContextResult:
+    root: Path
+    mode: str
+    created: tuple[Path, ...]
+    updated: tuple[Path, ...]
+    kept: tuple[Path, ...]
+    specs: tuple[str, ...]
+
+
+def _safe_name(value: str) -> str:
+    cleaned = re.sub(r"[^a-zA-Z0-9_.-]+", "_", value.strip())
+    cleaned = cleaned.strip("._-").lower()
+    return cleaned or "spec"
+
+
+def _write_text_if_needed(path: Path, text: str, *, force: bool) -> str:
+    if path.exists() and not force:
+        return "kept"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    write_text(path, text, force=True)
+    return "created"
+
+
+def _write_json_if_needed(path: Path, value: Any, *, force: bool) -> str:
+    if path.exists() and not force:
+        return "kept"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    write_json(path, value, force=True)
+    return "created"
+
+
+def _load_spec_source(source: Path) -> tuple[dict[str, Any], dict[str, Any] | None]:
+    if source.is_dir():
+        raw_spec = read_json(source / "spec.config.json")
+        if not isinstance(raw_spec, dict):
+            raise ValueError(f"invalid spec workspace: {source}")
+        raw_sample = read_json(source / "sample.records.json")
+        return raw_spec, raw_sample if isinstance(raw_sample, dict) else None
+
+    raw = read_json(source)
+    if raw is None:
+        raise FileNotFoundError(source)
+    return extract_spec_config(raw), None
+
+
+def _manifest(mode: str, entries: list[dict[str, Any]]) -> dict[str, Any]:
+    return {
+        "schema_version": 1,
+        "mode": mode,
+        "canonical_source": "specs repo or installed Airlock",
+        "snapshot_policy": "Snapshots are app-local development references, not canonical specs.",
+        "specs": entries,
+        "tracks": {
+            "spec_track": "row grain, columns, samples, access, validation, workflow",
+            "app_track": "screens, reads, decisions, writes, user actions, runtime",
+        },
+    }
+
+
+def _merge_manifest(existing: Any, new_manifest: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(existing, dict):
+        return new_manifest
+
+    merged = dict(existing)
+    merged.update(
+        {
+            "schema_version": new_manifest["schema_version"],
+            "mode": new_manifest["mode"],
+            "canonical_source": new_manifest["canonical_source"],
+            "snapshot_policy": new_manifest["snapshot_policy"],
+            "tracks": new_manifest["tracks"],
+        }
+    )
+
+    existing_entries = existing.get("specs")
+    by_name: dict[str, dict[str, Any]] = {}
+    if isinstance(existing_entries, list):
+        for entry in existing_entries:
+            if isinstance(entry, dict) and isinstance(entry.get("spec_name"), str):
+                by_name[entry["spec_name"]] = dict(entry)
+
+    for entry in new_manifest["specs"]:
+        previous = by_name.get(entry["spec_name"], {})
+        merged_entry = {**previous, **entry}
+        if previous.get("role") and entry.get("role") == "unknown":
+            merged_entry["role"] = previous["role"]
+        by_name[entry["spec_name"]] = merged_entry
+
+    merged["specs"] = list(by_name.values())
+    return merged
+
+
+def init_app_context(
+    target: Path,
+    *,
+    mode: str = "app-first",
+    spec_sources: list[Path] | None = None,
+    force: bool = False,
+) -> AppContextResult:
+    if mode not in APP_CONTEXT_MODES:
+        raise ValueError(f"mode must be one of: {', '.join(APP_CONTEXT_MODES)}")
+
+    root = target.expanduser().resolve()
+    if root.exists() and not root.is_dir():
+        raise NotADirectoryError(str(root))
+    root.mkdir(parents=True, exist_ok=True)
+
+    airlock_root = root / "airlock"
+    created: list[Path] = []
+    updated: list[Path] = []
+    kept: list[Path] = []
+
+    for directory in (
+        airlock_root,
+        airlock_root / "spec-snapshots",
+        airlock_root / "sample-records",
+        airlock_root / "generated",
+        airlock_root / "generated" / "types",
+        airlock_root / "generated" / "sql",
+    ):
+        if directory.exists():
+            kept.append(directory)
+        else:
+            directory.mkdir(parents=True)
+            created.append(directory)
+
+    entries: list[dict[str, Any]] = []
+    spec_names: list[str] = []
+    for source in spec_sources or []:
+        spec_config, sample_records = _load_spec_source(source.expanduser())
+        name = spec_name(spec_config)
+        safe = _safe_name(name)
+        snapshot_path = airlock_root / "spec-snapshots" / f"{safe}.spec.config.json"
+        bucket = created if _write_json_if_needed(snapshot_path, spec_config, force=force) == "created" else kept
+        bucket.append(snapshot_path)
+
+        sample_relative: str | None = None
+        if sample_records is not None:
+            sample_path = airlock_root / "sample-records" / f"{safe}.sample.records.json"
+            bucket = created if _write_json_if_needed(sample_path, sample_records, force=force) == "created" else kept
+            bucket.append(sample_path)
+            sample_relative = str(sample_path.relative_to(root))
+
+        core = spec_config.get("core_config")
+        core = core if isinstance(core, dict) else {}
+        entries.append(
+            {
+                "spec_name": name,
+                "spec_alias": core.get("spec_alias"),
+                "source": str(source),
+                "snapshot": str(snapshot_path.relative_to(root)),
+                "sample_records": sample_relative,
+                "role": "unknown",
+                "snapshot_only": True,
+            }
+        )
+        spec_names.append(name)
+
+    for path, content in (
+        (airlock_root / "README.md", APP_README),
+        (airlock_root / "AGENTS.md", APP_AGENTS),
+        (airlock_root / "generated" / "types" / ".gitkeep", ""),
+        (airlock_root / "generated" / "sql" / ".gitkeep", ""),
+    ):
+        bucket = created if _write_text_if_needed(path, content, force=force) == "created" else kept
+        bucket.append(path)
+
+    manifest_path = airlock_root / "specs.manifest.json"
+    manifest = _manifest(mode, entries)
+    if manifest_path.exists() and not force:
+        write_json(manifest_path, _merge_manifest(read_json(manifest_path), manifest), force=True)
+        updated.append(manifest_path)
+    else:
+        bucket = created if _write_json_if_needed(manifest_path, manifest, force=force) == "created" else kept
+        bucket.append(manifest_path)
+
+    return AppContextResult(
+        root=airlock_root,
+        mode=mode,
+        created=tuple(created),
+        updated=tuple(updated),
+        kept=tuple(kept),
+        specs=tuple(spec_names),
+    )
+
+
+def format_app_context_result(result: AppContextResult) -> str:
+    lines = [f"initialized app context {result.root}", f"mode: {result.mode}"]
+    for path in result.created:
+        lines.append(f"created {path.relative_to(result.root.parent)}")
+    for path in result.updated:
+        lines.append(f"updated {path.relative_to(result.root.parent)}")
+    for path in result.kept:
+        lines.append(f"kept {path.relative_to(result.root.parent)}")
+    lines.append("seeded_specs: " + (", ".join(result.specs) if result.specs else "none"))
+    lines.extend(
+        [
+            "",
+            "next:",
+            "1. Treat spec snapshots as app-local references, not canonical specs.",
+            "2. Mark each manifest spec as read, write, or read_write for the app.",
+            "3. Build app reads and governed submissions through approved Airlock/Snowflake access paths.",
+        ]
+    )
+    return "\n".join(lines)

package/src/airlock_mcp/art.py

@@ -21,6 +21,6 @@ def about_text() -> str:
     return f"""{MCP_MARK.rstrip()}
 
 version: {__version__}
-commands: init-repo, init, import-spec, clone, rename, archive, restore, list-workspaces, summary, next, check, export-csv, render-sql, self-update
+commands: init-repo, init-app-context, init, import-spec, clone, rename, archive, restore, list-workspaces, summary, next, check, export-csv, render-sql, self-update
 principle: Codex is the conversation; files are memory; Airlock is authority.
 """

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,48 @@ 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
+
+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/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.3",
       },
       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,15 @@ 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. 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 write directly to Airlock-owned tables
+or bypass spec workflow.`;
 }
 
 export function nextSteps(project) {
@@ -63,8 +75,11 @@ ${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
+  - 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
@@ -77,16 +92,19 @@ 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 three 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.
 
 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 +116,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:
 
@@ -123,7 +147,15 @@ current shape of any third-party system. Prefer current API docs, real exports,
 samples, and other artifacts when they conflict with the library.
 
 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. 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 +180,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.",
@@ -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": {