methodology-m 0.3.1

package/dist-m/capabilities/setup-workspace/SKILL.md

@@ -0,0 +1,70 @@
+# Setup Workspace
+
+**Capability:** Create a new M-type project workspace
+
+## What it does
+
+Creates a group (or subgroup) on the SCM platform that serves as the container for an M-type project. The group is where all repos (root, managed) live.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `project-name` | string | Yes | Name of the project (becomes group name) |
+| `parent-path` | string | No | Parent group path (e.g., `methodology-m`). Creates subgroup if provided; creates top-level group if omitted. |
+| `visibility` | string | No | `public` or `private` (default: `public`) |
+| `description` | string | No | Group description |
+
+## Execution
+
+### Top-level group
+
+```
+scm.create_group(
+  name: <project-name>,
+  path: <project-name>,
+  visibility: <visibility>,
+  description: <description>
+)
+```
+
+### Subgroup under parent
+
+```
+parent_id = scm.resolve_group_id(<parent-path>)
+
+scm.create_group(
+  name: <project-name>,
+  path: <project-name>,
+  parent_id: <parent_id>,
+  visibility: <visibility>,
+  description: <description>
+)
+```
+
+## Examples
+
+**Create top-level group:**
+```
+setup-workspace
+  project-name: "todo-m-workshop"
+  visibility: "public"
+  description: "Reference implementation for Methodology M"
+```
+
+**Create subgroup under parent:**
+```
+setup-workspace
+  project-name: "todo-m-workshop"
+  parent-path: "methodology-m"
+  visibility: "public"
+  description: "Reference implementation for Methodology M"
+```
+
+## Outcome
+
+Group created at `<scm-platform>/<namespace>/<project-name>`. Ready for Story Zero.
+
+## Notes
+
+- Some SCM platforms restrict top-level group creation via API — check your provider docs.

package/dist-m/capabilities/tag-release/SKILL.md

@@ -0,0 +1,121 @@
+# tag-release
+
+**Capability:** Tag a managed repo at a version and update the root repo topology
+
+## What it does
+
+Tags a managed repo with a semver version (e.g. `v0.1.0`), then updates
+the root repo's `project.yaml` to pin that component to the new version.
+After this step, the topology manifest reflects the released state and
+the component is reproducibly referenceable.
+
+## Parameters
+
+| Parameter      | Type   | Required | Description                                        |
+|----------------|--------|----------|----------------------------------------------------|
+| sub-task-id    | string | Yes      | Sub-task identifier (e.g. TODOM-000c)              |
+| version        | string | Yes      | Semver version to tag (e.g. v0.1.0)                |
+| repo-path      | path   | No       | Local path to the managed repo (inferred from CWD if omitted) |
+| root-repo-path | path   | No       | Local path to the root repo (inferred from sibling directory if omitted) |
+
+## Prerequisites
+
+- Managed repo has a passing implementation and acceptance tests
+- All tests pass (`npm test` exits 0)
+- The managed repo's `main` branch is up to date
+- Root repo exists locally with `project.yaml`
+
+## Execution
+
+### Step 1 — Verify readiness
+
+Before tagging, confirm:
+1. Working directory is clean (no uncommitted changes)
+2. On `main` branch (or the MR has been merged to main)
+3. `npm test` passes
+
+If any check fails, stop and report. Do not tag broken code.
+
+### Step 2 — Determine component name
+
+Read `jira/<sub-task-id>.md` to extract the component name.
+This is used to find the correct entry in `project.yaml`.
+
+Alternatively, read `package.json` `name` field — the repo name
+follows the pattern `<project>-<component>` (e.g. `todo-m-api-read`
+→ component `api-read`).
+
+### Step 3 — Create annotated tag
+
+Create an annotated git tag on the current HEAD:
+
+```
+git tag -a <version> -m "Release <version> — <sub-task-id>"
+```
+
+Annotated tags (not lightweight) because:
+- They carry metadata (tagger, date, message)
+- They're the convention for release tags
+- `git describe` works with annotated tags
+
+### Step 4 — Push the tag
+
+```
+git push origin <version>
+```
+
+This pushes only the tag, not any branch changes.
+
+### Step 5 — Update project.yaml in root repo
+
+In the root repo's `project.yaml`, find the component entry and
+update its `tag` field from `~` (null) to the new version:
+
+```
+# Before
+- name: api-read
+  type: referenced
+  location: methodology-m/todo-m-workshop/todo-m-api-read
+  tag: ~
+
+# After
+- name: api-read
+  type: referenced
+  location: methodology-m/todo-m-workshop/todo-m-api-read
+  tag: v0.1.0
+```
+
+**Important:** Only update the specific component's tag. Do not
+touch other components' entries.
+
+### Step 6 — Report
+
+Output:
+- Tag created: `<version>` on `<repo-name>`
+- Tag pushed to origin
+- `project.yaml` updated: `<component>` now pinned to `<version>`
+- Reminder: commit and push the root repo `project.yaml` change
+  (this capability updates the file but does not auto-commit the
+  root repo — the presenter controls when that happens)
+
+## Notes
+
+- This capability works locally. It creates and pushes a git tag on
+  the managed repo, and edits `project.yaml` in the local root repo.
+- The root repo change (updated `project.yaml`) is NOT auto-committed.
+  In the workshop flow, the presenter commits this as part of a
+  topology update or as a standalone commit. In a real M workflow,
+  this would be part of a topology MR.
+- Version `v0.1.0` is the convention for Story Zero's first release.
+  It signals "the component exists and meets its contract" — not
+  production-ready, but validated.
+- The tag is on the managed repo's `main` branch HEAD. If the
+  implementation was done on a feature branch, it must be merged
+  to main first.
+- For the workshop fast-forward flow, this capability is called
+  once per managed repo after implementation and tests are in place.
+- This capability does NOT update the readiness tracker
+  (`stories/<story-id>.yaml`). That's a separate concern tracked
+  at the story level, not the component level.
+- If the tag already exists (re-run scenario), report it and skip.
+  Do not force-push tags.

package/dist-m/capabilities/wire-orchestration/SKILL.md

@@ -0,0 +1,351 @@
+# wire-orchestration
+
+**Capability:** Connect managed repos to the root repo's orchestration layer
+
+## What it does
+
+After all managed repos are scaffolded, this capability wires them to
+the root repo. It installs webhooks, pipeline triggers, CI variables,
+and the root repo's CI pipeline. After this step, the full Methodology M
+orchestration is operational — raising an MR on a managed repo triggers
+shadow integration on the root repo automatically.
+
+## Parameters
+
+| Parameter      | Type   | Required | Description                                          |
+|----------------|--------|----------|------------------------------------------------------|
+| project-yaml   | path   | Yes      | Path to project.yaml (source of truth for topology)   |
+| root-project-id| string | No       | SCM project ID or path for root repo (derived from project.yaml if omitted) |
+| access-tokens  | map    | Yes      | Map of component name → access token value (from scaffold-repo output) |
+
+## Prerequisites
+
+- Root repo exists (created by `bootstrap-root-repo`)
+- All managed repos exist and are scaffolded (created by `scaffold-repo`)
+- Project access tokens for each managed repo are available
+- Each managed repo has a `Dockerfile` at its root
+- Each API repo exposes a `GET /health` endpoint (convention for compose health checks)
+- Root repo has a `docker-compose.yml` defining all services with build contexts pointing to sibling directories
+
+## Execution
+
+### Step 1 — Read topology
+
+Read project.yaml. For each `type: referenced` component, extract:
+- Component name
+- Project path (from `location:` field)
+
+```
+for each component:
+  project_id = scm.resolve_project_id(<location>)
+```
+
+### Step 2 — Create pipeline trigger on root repo
+
+```
+trigger_token = scm.create_pipeline_trigger(
+  repo: <root-repo>,
+  description: "m-shadow-integration-trigger"
+)
+```
+
+This token is what managed repo webhooks use to kick off shadow
+integration pipelines on the root repo.
+
+Store the trigger token value for webhook configuration.
+
+### Step 3 — Install webhooks on managed repos
+
+For each managed repo:
+
+```
+scm.create_webhook(
+  repo: <managed-repo>,
+  url: <trigger-url-with-token>,
+  events: { merge_request: true, pipeline: true, push: false },
+  ssl_verify: true
+)
+```
+
+**Important:** Push events MUST be explicitly disabled to avoid
+triggering the root repo pipeline on every push to managed repos.
+
+Pipeline events (`pipeline: true`) are required so that when a managed
+repo's own pipeline fails, the root repo is notified and can propagate
+the failure to all story MRs. Without this, sibling MRs retain stale
+green status until the next MR event.
+
+### Step 4 — Store access tokens as CI secrets
+
+For each managed repo:
+
+```
+scm.store_ci_secret(
+  repo: <root-repo>,
+  key: "M_TOKEN_<COMPONENT_NAME_UPPER>",   # e.g. M_TOKEN_API_READ
+  value: <access-token-from-scaffold-repo>,
+  protected: true,
+  masked: true
+)
+```
+
+These tokens are used by the merge transaction pipeline to merge MRs
+on managed repos via the SCM API.
+
+### Step 5 — Push root repo CI pipeline
+
+Push `.gitlab-ci.yml` to the root repo. The pipeline has three concerns:
+
+1. **Shell lifecycle** — install/build/test for the embedded shell component
+2. **Shadow integration** — triggered by managed repo webhooks
+3. **Post-merge validation** — compose + integration-test on MR events and main
+
+#### Pipeline structure
+
+The root repo CI uses Docker-in-Docker (DinD) for the compose stages.
+This is the **reference implementation** using GitLab CI + Docker Compose.
+Other compose strategies (k8s, serverless, etc.) would replace this
+section while preserving the same lifecycle contract.
+
+**Stages:** install → build → test → compose → integration-test → report-status → merge-transaction
+
+**Shell lifecycle jobs** (run on MR events and main pushes, skip triggers):
+- `install` — `npm ci` for root and shell package
+- `build` — build the shell
+- `test` — shell unit tests
+
+**Shadow integration jobs** (run only on trigger events from managed repo webhooks):
+- `detect-trigger` — determines event type: `aot_integration`, `cascade_merge`, or `pipeline_failure`
+- `shadow:invalidate-status` — immediately pushes `pending` to ALL story MRs (including root) to block merge during AOT window
+- `shadow:integration` — clone siblings, Docker build, start, health check, run tests. Skips compose for `cascade_merge` and `pipeline_failure` (exits with failure for pipeline_failure to trigger report-failure)
+- `shadow:report-status` — push `success` commit status to ALL story MRs (including root)
+- `shadow:report-failure` — push `failed` commit status to ALL story MRs (including root)
+
+**Validation jobs** (run on MR events and main pushes, skip triggers):
+- `validate:integration` — compose, health check, run story-level tests. On MR pipelines, the `after_script` extracts the story ID from the branch name and fans out the result (success/failure) to all story MRs via `report-shadow-status.sh`. This ensures that a root MR pipeline failure makes all sibling MRs go red.
+
+**Merge transaction** (manual trigger):
+- `merge-transaction` — merge managed MRs atomically, update topology
+
+#### Compose job contract (methodology)
+
+The compose stage must:
+1. Clone all sibling repos at the appropriate ref
+2. Build the full system (all components)
+3. Start all services
+4. Verify each service is healthy (health check with timeout)
+5. Tear down on failure or after completion
+
+This contract is methodology — it applies regardless of compose strategy.
+
+#### Reference implementation: Docker Compose on GitLab DinD
+
+The reference implementation uses Docker-in-Docker on GitLab CI shared
+runners. Key configuration:
+
+```
+image: docker:latest
+services:
+  - docker:dind
+variables:
+  DOCKER_TLS_CERTDIR: "/certs"
+  GROUP: <gitlab-group-path>
+before_script:
+  - apk add --no-cache git curl
+```
+
+**Clone sibling repos** using `CI_JOB_TOKEN` for authentication:
+```
+git clone --depth 1 --branch main \
+  "https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/${GROUP}/<repo>.git" \
+  ../<repo>
+```
+
+**Build and start** via Docker Compose:
+```
+docker compose build
+docker compose up -d
+```
+
+**Health check loop** with configurable timeout:
+```
+DOCKER_GATEWAY="${DOCKER_GATEWAY:-docker}"
+TIMEOUT=60
+ENDPOINTS="http://${DOCKER_GATEWAY}:<port>/health ..."
+```
+
+**Teardown** in `after_script` (runs even on failure):
+```
+docker compose down 2>/dev/null || true
+```
+
+#### DinD networking gotcha
+
+In GitLab's DinD setup with `DOCKER_TLS_CERTDIR`, the Docker daemon
+runs in the `docker:dind` service container. Published ports bind on
+that daemon's network interface, reachable from the CI script via the
+hostname `docker` — NOT `localhost`.
+
+Health check URLs must use `docker:<port>`, not `localhost:<port>`.
+The `DOCKER_GATEWAY` variable defaults to `docker` but can be
+overridden for local testing (set to `localhost`).
+
+#### Integration test gate
+
+Shadow integration runs story-level integration tests after health
+checks pass. Three failure modes ensure no story can slip through:
+
+- **Structural failure:** the integration test framework detects that
+  a story is in-flight (open MRs with the story ID in branch names)
+  but no integration test script exists at
+  `scripts/integration-tests/<story-id>.sh`. This fails immediately
+  with a clear message telling the team to add tests.
+
+- **Completeness failure:** the integrity check verifies that ALL
+  repos in the topology have open MRs for the story — managed repos
+  AND the root repo. The root repo delivers story-level integration
+  tests; without its MR the gate is meaningless. The repo list must
+  be derived from `project.yaml` components, not hardcoded.
+
+- **Logical failure:** the integration test script exists but fails
+  because not all components have implemented their part yet. The
+  failure output shows exactly which checks failed, so devs know
+  who to talk to.
+
+- **Mergeability failure:** a constituent MR exists but is not
+  mergeable (e.g. failing pipeline, blocked by discussions, needs
+  approval). An unmergeable MR is functionally equivalent to a
+  missing MR — the story cannot proceed. The integrity check must
+  verify `detailed_merge_status` for each MR, not just its existence.
+  Acceptable statuses are `mergeable`, `checking` (pipeline in
+  progress), `approvable`, and `approved`. Anything else (e.g.
+  `ci_must_pass`, `blocked_status`, `not_approved`) means the MR
+  is not ready and the story is incomplete.
+
+The root repo always has a story branch for every story — even when
+the shell code doesn't change — because the integration tests are
+the root repo's contribution. The `decompose-story` capability
+enforces this by always generating a root repo sub-task.
+
+The shadow pipeline bootstraps from the root repo's story branch
+(resolved via `resolve-story-branches.sh`) to pick up story-specific
+integration tests, compose config, and Cypress specs.
+
+#### Health endpoint convention
+
+All API components must expose `GET /health` returning a 2xx response.
+This is the standard health check endpoint used by compose jobs.
+
+Frontend components (nginx-based) are checked via their served content:
+- Shell: `http://<host>:3000` (serves index.html)
+- MFE: `http://<host>:3001/remoteEntry.js` (Module Federation entry)
+
+#### MR pipeline rules
+
+The `validate:compose` and `validate:integration-test` jobs must include
+`merge_request_event` in their rules, not just `main` branch. Without
+this, root repo MRs have no pipeline and are blocked by the
+`only_allow_merge_if_pipeline_succeeds` setting:
+
+```
+rules:
+  - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE != "trigger"
+```
+
+#### Shadow status reporting
+
+The shadow pipeline reports results to ALL repos with open story MRs —
+managed repos AND the root repo. This is fan-out, not point-to-point.
+When shadow integration passes or fails, every constituent MR gets the
+same status simultaneously. This requires a group-level token with API
+scope (`M_GROUP_TOKEN`) as a CI secret on the root repo.
+
+Two jobs handle this:
+- `shadow:report-status` (on success) — pushes `state=success` to all story MRs
+- `shadow:report-failure` (on failure) — pushes `state=failed` to all story MRs
+
+For each repo with an open story MR, both call:
+```
+scm.post_commit_status(
+  repo: <story-repo>,
+  sha: <commit-sha>,
+  state: success | failed,
+  name: "shadow-integration",
+  description: <human-readable message>,
+  target_url: <link to root pipeline>
+)
+```
+
+### Step 6 — Protect root repo main branch
+
+```
+scm.protect_branch(
+  repo: <root-repo>,
+  branch: "main",
+  push: none,
+  merge: maintainer,
+  force_push: false
+)
+```
+
+### Step 7 — Report
+
+Output:
+- Pipeline trigger token (masked, for reference)
+- Webhook status per managed repo (created / already exists)
+- CI variables installed on root repo
+- Root repo pipeline status
+- Branch protection status
+
+## Webhook Design Notes
+
+### GitLab free tier constraints
+
+GitLab free tier supports project webhooks and pipeline triggers. The
+webhook-to-trigger pattern works without any premium features.
+
+### Trigger URL format
+
+```
+https://gitlab.com/api/v4/projects/<root-project-id>/trigger/pipeline
+  ?token=<trigger-token>
+  &ref=main
+```
+
+### Alternative: GitLab CI `trigger` keyword
+
+For projects on GitLab Premium+, managed repo pipelines can use the
+`trigger` keyword to directly trigger downstream root repo pipelines.
+The webhook approach works on all tiers.
+
+## Critical — Repo Lists Must Include Root
+
+Every script that iterates repos for a story — `integration-test.sh`,
+`report-shadow-status.sh`, `invalidate-story-status.sh` — MUST include
+the root repo alongside managed repos. The root repo is a constituent
+of every story (it delivers integration tests). Excluding it from any
+repo list creates a gap where the root MR can have stale status or
+bypass the integrity gate. Use a single `REPOS` variable derived from
+the topology, not a hardcoded list of managed repos.
+
+## Notes
+
+- This capability is idempotent — running it again updates existing
+  webhooks and variables rather than creating duplicates
+- The root repo pipeline uses `resource_group: distributed_merge`
+  to serialise merge transactions
+- CI variables are protected and masked
+- `wire-orchestration` does NOT create managed repos — that's `scaffold-repo`
+- `wire-orchestration` does NOT create the root repo — that's `bootstrap-root-repo`
+- The compose strategy (Docker Compose + DinD) is the reference
+  implementation. The methodology defines the contract (clone, build,
+  start, health-check, teardown); the strategy implements it. See I-018
+  for the plugin boundary design.
+- The shadow:compose and validate:compose jobs currently duplicate the
+  compose logic. See I-017 for the DRY refactor plan (extract to shared
+  script or YAML anchors).
+- Workflow rules prevent duplicate pipelines — trigger, MR, and main
+  branch events are handled distinctly
+- The embedded shell follows the same lifecycle as managed repos
+  (install/build/test) plus inline compose validation. See I-012.

package/dist-m/m.md

@@ -0,0 +1,126 @@
+# Methodology M — Steering
+
+**Version:** 0.3.1
+
+Methodology M is an AI-driven delivery method for distributed software systems where a single user story spans multiple repos, multiple deployable units, and can only be verified in an integrated environment. The full specification lives in `methodology-m.md` at the repo root.
+
+This directory (`.m/`) is the agent-neutral, machine-readable expression of the methodology. Any AI agent that can read markdown and call platform APIs can execute these capabilities. Agent-specific adapters (`.kiro/`, `.claude/`, etc.) provide thin wrappers for discovery — the intelligence lives here.
+
+**Path convention:** All paths in M documents are relative to the repo root, not to the file they appear in.
+
+## Key Files
+
+- `methodology-m.md` — the full methodology specification (the paper)
+- `.m/m.md` — this file: steering, capabilities, execution protocol
+- `.m/capabilities/` — standalone playbooks for each M capability
+- `.m/schemas/pat.schema.json` — JSON Schema for PAT.yaml files (story and sub-task)
+- `.m/schemas/project.schema.json` — JSON Schema for project.yaml topology manifest
+- `.m/providers/provider-interface.md` — namespace contracts and resolution protocol
+- `.m/providers/scm/gitlab.md` — GitLab SCM provider (reference implementation)
+
+## When Working in This Repo
+
+This is the methodology repo itself — not an M-type project. You are
+editing the methodology, its capabilities, and its provider implementations.
+
+When the user asks you to:
+- **Execute a capability** (e.g. "scaffold a repo") — read the capability
+  file and provider file, then execute
+- **Edit a capability** — modify `.m/capabilities/<name>.md`
+- **Edit a provider** — modify `.m/providers/scm/<provider>.md`
+- **Discuss methodology concepts** — refer to `methodology-m.md`
+
+## Capabilities
+
+Each capability follows the [Agent Skills](https://agentskills.io) standard (`<name>/SKILL.md`). Read the full file before executing — summaries below are for orientation only.
+
+| Capability | File | Description |
+|---|---|---|
+| `setup-workspace` | [SKILL.md](capabilities/setup-workspace/SKILL.md) | Create a project workspace (group/org) on the SCM platform |
+| `bootstrap-root-repo` | [SKILL.md](capabilities/bootstrap-root-repo/SKILL.md) | Create and seed the root repo with topology manifest and Story Zero |
+| `generate-pats` | [SKILL.md](capabilities/generate-pats/SKILL.md) | Transform story acceptance criteria into PAT.yaml format |
+| `decompose-story` | [SKILL.md](capabilities/decompose-story/SKILL.md) | Map story-level PATs to components, generate sub-tasks and readiness tracker |
+| `scaffold-repo` | [SKILL.md](capabilities/scaffold-repo/SKILL.md) | Create and configure a managed repo from a sub-task file |
+| `wire-orchestration` | [SKILL.md](capabilities/wire-orchestration/SKILL.md) | Connect managed repos to root repo orchestration (webhooks, CI, tokens) |
+| `generate-acceptance-tests` | [SKILL.md](capabilities/generate-acceptance-tests/SKILL.md) | Compile PAT stubs into executable acceptance tests (CATs) |
+| `tag-release` | [SKILL.md](capabilities/tag-release/SKILL.md) | Tag a managed repo at a version and update root repo topology |
+
+## Execution Protocol
+
+1. User requests a capability (by name or by describing the intent)
+2. Agent reads the corresponding `.m/capabilities/<name>/SKILL.md` — the FULL file
+3. For any namespaced function call (e.g. `scm.create_repo(...)`):
+   a. Check `project.yaml` → `providers` to find the active provider
+   b. Read `.m/providers/<category>/<provider>.md` for the concrete implementation
+   c. Execute the platform-specific operation
+4. Agent produces the report described in the capability file
+
+No shortcuts. The capability files contain critical sequences (branch protection ordering, webhook flags, CI image requirements) that cannot be skipped.
+
+## Configuration Resolution
+
+Capabilities that generate artefacts (CI configs, test setups, templates) resolve their choices through a four-tier hierarchy:
+
+```
+Repo-level override  →  Project-level (project.yaml)  →  Org Config  →  M Core Config
+```
+
+See `methodology-m.md` Section 6a for the full strategy/plugin architecture. The capabilities define the *what*. The configuration hierarchy determines the *with what tools*.
+
+## Provider Namespaces
+
+Capabilities call platform operations via namespaced functions. Each
+namespace is backed by a provider selected in `project.yaml`.
+
+| Namespace | Category | Provider interface |
+|---|---|---|
+| `scm.*` | Source code management | [provider-interface.md](providers/provider-interface.md) |
+
+New namespaces (e.g. `test.cat.*`, `compose.*`) are added as the
+methodology evolves. See the provider interface doc for the full
+function contracts and the protocol for adding new namespaces/providers.
+
+## Directory Structure
+
+```
+.m/
+  m.md                              ← this file
+  capabilities/
+    <name>/SKILL.md                 ← one per capability (Agent Skills standard)
+  schemas/
+    pat.schema.json                 ← JSON Schema for PAT.yaml files
+    project.schema.json             ← JSON Schema for project.yaml
+  providers/
+    provider-interface.md           ← namespace contracts and resolution protocol
+    scm/gitlab.md                   ← GitLab SCM provider (reference implementation)
+```
+
+Agent-specific steering (how to behave) lives in agent directories
+(`.claude/steering/`, `.kiro/steering/`). Steering templates for
+managed repos are embedded in the `scaffold-repo` capability doc.
+
+## Schemas — Mandatory Validation
+
+The `.m/schemas/` directory contains JSON Schema definitions for M
+artefacts. These are the formal contracts — capability docs describe
+*when* and *why* to generate an artefact, schemas define *what it must
+look like*.
+
+| Schema | Validates | Used by |
+|---|---|---|
+| `pat.schema.json` | `*.pat.yaml` files (story-level and sub-task) | generate-pats, decompose-story, generate-acceptance-tests |
+| `project.schema.json` | `project.yaml` topology manifest | bootstrap-root-repo, scaffold-repo, wire-orchestration |
+
+**Agent rule:** When generating or modifying a PAT.yaml or project.yaml
+file, read the corresponding schema FIRST. Validate your output against
+the schema before committing. If a field is marked `required` in the
+schema, it must be present. If a value has an `enum` constraint or
+`pattern`, use only valid values. Do not invent fields not in the schema.
+
+## Relationship to Agent Runtimes
+
+This directory is the canonical source. Agent-specific directories contain thin wrappers:
+
+- **Kiro** (`.kiro/powers/m-power/`) — a Power that bundles these capabilities with MCP servers and hooks
+- **Claude** (`.claude/skills/<name>/SKILL.md`) — thin skill wrappers pointing to `.m/capabilities/<name>/SKILL.md`
+- **Any SKILL.md-compatible agent** — can consume these files directly or via lightweight adapters