MotleyAI/living-architecture

**Preflight:** run `la-doctor --plugin <this skill's base directory> --require-config` once per session before using any `la-*` or `dr-*` command. If it reports the missing-config finding (the one naming `/la:init`), run the fast path of the `la:init` skill, then re-run this preflight; stop and show the user its output on anything it still reports, or on any other failure.

# Carve one boundary slice

A slice moves code until a batch of grandfathered edges dies, with a
deterministic gate proving nothing dangles. It is behaviour-preserving: no new
behaviour, no new tests, no OpenSpec spec deltas. The legacy-arrow ratchet plus
the green suite ARE the spec, so the /la:pr stage flow does not apply — but
each slice still gets its own issue, branch, and PR.

## Procedure

1. **Pick the slice.** List the model's `#legacy` arrows (their count is
   `legacy_arrows.baseline` in `index.yaml`); propose a coherent batch — one

**Preflight:** run `la-doctor --plugin <this skill's base directory> --require-config` once per session before using any `la-*` or `dr-*` command. If it reports the missing-config finding (the one naming `/la:init`), run the fast path of the `la:init` skill, then re-run this preflight; stop and show the user its output on anything it still reports, or on any other failure.

# Build the first architecture model

The syntax of the model, `index.yaml`, views and arc42 files, and every check `la-arch-check` runs, are in
the `la:living-architecture` skill; read it first. Everything this skill writes is normative, like tests:
show each model, arc42 and `index.yaml` edit and get the user's OK before landing it.

## 1. Preconditions

- `architecture/index.yaml` does not exist (otherwise this is maintenance: use `la:living-architecture`).
- `openspec: true` in the config means `openspec/` is healthy; if not, run `la:openspec-init` first.
- A type check with a baseline: run `la-typecheck`. If it checks a language that has no baseline, offer
  `la-typecheck --write-baseline` (the one legitimate recording; afterwards the baseline only shrinks). If it

**Preflight:** run `la-doctor --plugin <this skill's base directory>` once per session before using any `la-*` or `dr-*` command; if it fails, stop and show the user its output.

If `la-config get reviewers.codex` prints `false`, this repo has turned Codex reviews off: say so, and run the
review only if the user confirms. If the Codex MCP server (`mcp__codex__codex`) is not available, stop and tell
the user; never substitute another reviewer.

Use the codex MCP server to review the current git diff.
Focus on correctness, regressions, security issues, tests, and maintainability.
Return only actionable findings with file/line references and severity.
Do not modify files.

**Preflight:** run `la-doctor --plugin <this skill's base directory>` once per session before using any `la-*` or `dr-*` command; if it fails, stop and show the user its output.

# Concise comments & docstrings

Prevention: follow these when writing. Cleanup: run the pass below when invoked as `/la:concise-comments`.

## The test
Keep a comment only if a competent reader of THIS codebase couldn't infer it from the code and names. Otherwise delete it, or cut it to the one missing fact in one line.

## For / not for
For: the non-obvious *why* (constraint, invariant, footgun, edge-case gotcha) and a one-line *what* on public APIs.
Not for: design narrative, alternatives-considered, defending the approach, repro steps, byte-count walkthroughs, ticket history, or restating the code. Those go in the PR description, the issue, or a test.

## Limits (defaults; exceed only with a stated reason)

**Preflight:** run `la-doctor --plugin <this skill's base directory> --require-config` once per session before using any `la-*` or `dr-*` command. If it reports the missing-config finding (the one naming `/la:init`), run the fast path of the `la:init` skill, then re-run this preflight; stop and show the user its output on anything it still reports, or on any other failure.

# Deterministic refactor

The mutator is best-effort — no tool reliably rewrites every annotated
`obj.attr`, `super()` call, and override. The **type-check gate is the
guarantee**, and it is only sound on code that meets the compliance conditions
(`docs/deterministic-refactoring.md`). If the blast radius is not typed, run `la:make-refactor-target-compliant`
first.

The file's language decides the mutator and its idioms: read
`<this skill's base directory>/../../languages/<language>.md` for each language
the refactor touches (`la-config get languages` lists the repo's).

**Preflight:** run `la-doctor --plugin <this skill's base directory>` once per session before using any `la-*` or `dr-*` command; if it fails, stop and show the user its output.

# Fetch unresolved CodeRabbit review threads from a PR

## How to run

```bash
la-fetch-coderabbit-threads <PR_NUMBER> [--repo OWNER/REPO] [--all-authors]
```

Works in any repo; it does not read `living-architecture.yaml`.

- `<PR_NUMBER>` — required, the PR number.
- `--repo OWNER/REPO` — optional; defaults to the repo of the current git directory (auto-detected via `gh repo view`).

**Preflight:** run `la-doctor --plugin <this skill's base directory>` once per session before using any `la-*` or `dr-*` command; if it fails, stop and show the user its output.

# Fetch failed CI checks (and their failed-step logs) for a PR

## How to run

```bash
la-fetch-failed-pr-checks <PR_NUMBER> [--repo OWNER/REPO] [--max-log-lines N]
```

- `<PR_NUMBER>` — required.
- `--repo OWNER/REPO` — optional; defaults to the cwd repo via `gh repo view`.
- `--max-log-lines N` — cap each failed job's log excerpt at N lines (default 200). Pass `0` to skip log fetching entirely.

**Preflight:** run `la-doctor --plugin <this skill's base directory>` once per session before using any `la-*` or `dr-*` command; if it fails, stop and show the user its output — unless the only failure is the existing `living-architecture.yaml` being invalid or declaring an older format, which this skill converts (steps 1 and 5).

# Onboard a repo

`living-architecture.yaml` records each gate of the flow as an explicit decision; its presence means the repo
is onboarded. Keys, defaults and the doctor's consistency checks are in `docs/configuration.md` of the plugin
repo; `la-config show` prints the resolved values.

**Fast path.** When another skill's preflight reports the missing config, run steps 1–6 only, then hand back
to that skill. A full run (the user invoked `/la:init`) continues to step 7.

## 1. Detect

Read, don't ask. For each key note the value and where it came from:

**Preflight:** run `la-doctor --plugin <this skill's base directory>` once per session before using any `la-*` or `dr-*` command; if it fails, stop and show the user its output.

# Living architecture

Four layers, one element id everywhere. Behaviour lives in OpenSpec; everything
cross-cutting lives here:

| Layer | Question | Artifact | Property |
|---|---|---|---|
| Behaviour | what does it do, now? | `openspec/specs/<id>/spec.md` | living, merged by OpenSpec |
| Structure | how is it arranged, now? | LikeC4 model + views | living; ONE model, diagrams are projected views |
| Rationale | why is it this way, and what must all code here obey? | arc42 file per element that earns prose | living, edited in place |
| Enforcement | is the code actually like this? | `arch_check` model-truth (the one import law) + LikeC4 model validation, run in the flow gates | executable, blocking |

**Preflight:** run `la-doctor --plugin <this skill's base directory>` once per session before using any `la-*` or `dr-*` command; if it fails, stop and show the user its output.

# Make the diff compliant

Raise compliance one PR at a time instead of a big-bang migration: every diff
leaves the files it touched fully refactor-verifiable.

## Steps

1. **Changed source files:**
   `git diff --name-only <base>...HEAD` (base = the PR's target branch), kept to
   the repo languages' sources (`la-config get languages`, then
   `la-config get lang.<language>.source_globs`).
2. **Report:** `dr-compliance <changed files>` — each file gets its language's

**Preflight:** run `la-doctor --plugin <this skill's base directory>` once per session before using any `la-*` or `dr-*` command; if it fails, stop and show the user its output.

# Make a refactor's blast radius compliant

A rename is only provable over code the type checker can resolve. This closes
the blind spots first, so the `la:deterministic-refactor` gate afterwards is sound.
The idioms for each language are in
`<this skill's base directory>/../../languages/<language>.md`.

## Steps

1. **Identify the target:** the symbol, and for a member rename the attribute
   NAME and its owning class.
2. **Enumerate blind spots (checking machinery):**

Bring the current repo to a valid OpenSpec state: the `openspec` CLI resolvable
and an `openspec/` corpus (`specs/` + `changes/`) present and healthy. Corpus
only — no `/opsx:*` slash commands or AGENTS wiring, because the `/la:pr` flow
replaces propose/apply.

## Step 1 — Resolve the CLI (set `OPENSPEC_CMD`)

1. If `command -v openspec` succeeds → `OPENSPEC_CMD=openspec`.
2. Else install globally: `npm i -g @fission-ai/openspec` (no sudo where the npm
   global prefix is user-writable — nvm/fnm/`~/.local`-style node). Re-check
   `command -v openspec`.
3. If the global install fails (non-writable prefix, no permission, or offline):
   fall back to `OPENSPEC_CMD="npx -y @fission-ai/openspec@1.11.0"` (bump the pin
   as needed). If even npx can't fetch, STOP and tell me — do not proceed.

**Preflight:** run `la-doctor --plugin <this skill's base directory> --require-config` once per session before using any `la-*` or `dr-*` command. If it reports the missing-config finding (the one naming `/la:init`), run the fast path of the `la:init` skill, then re-run this preflight; stop and show the user its output on anything it still reports, or on any other failure.

I want a detailed spec-driven flow. The brief is the union of:
1. The tracker issue tied to the current branch (see "Rehydrate" below), AND
2. Whatever I just typed when invoking this skill.

## The four stages

The flow runs as four stage skills in this fixed order, and I reset the
session (`/clear`) between stages. Each stage ends at a hard stop; everything
a fresh session needs is on disk or in the tracker, so any stage can resume from
just the branch name:

1. **`pr-plan`** — interview me, Codex-review the plan (when

**Preflight:** run `la-doctor --plugin <this skill's base directory> --require-config` once per session before using any `la-*` or `dr-*` command. If it reports the missing-config finding (the one naming `/la:init`), run the fast path of the `la:init` skill, then re-run this preflight; stop and show the user its output on anything it still reports, or on any other failure.

**Stage 3 of 4 of the `/la:pr` flow.** Prerequisite: `/la:pr` has run in this
session and established `BRANCH`, `CHANGE_ID`, `OPENSPEC`, and the full tracker
issue (body + comments), if there is one. If any of that is missing, invoke the `la:pr` skill
instead — it rehydrates and dispatches back here. The `/la:pr` stopping policy
applies throughout this stage.

Before writing anything, recover the durable plan (the
`openspec/changes/<CHANGE_ID>/` folder when `OPENSPEC=1`, else the plan
comment on the tracker issue) and the failing tests already on disk from
`pr-tests`.

## Step 1 — Implement until tests pass

**Preflight:** run `la-doctor --plugin <this skill's base directory> --require-config` once per session before using any `la-*` or `dr-*` command. If it reports the missing-config finding (the one naming `/la:init`), run the fast path of the `la:init` skill, then re-run this preflight; stop and show the user its output on anything it still reports, or on any other failure.

**Stage 1 of 4 of the `/la:pr` flow.** Prerequisite: `/la:pr` has run in this
session and established `BRANCH`, `CHANGE_ID`, `OPENSPEC`, and the full tracker
issue (body + comments), if there is one. If any of that is missing, invoke the `la:pr` skill
instead — it rehydrates and dispatches back here. The `/la:pr` stopping policy
applies throughout this stage.

## Step 1 — Combine and interview

Treat the tracker issue body + comments AND whatever I typed when invoking
`/la:pr` as the combined brief. In case of conflict, what I typed has higher
priority but ask to be sure.

**Preflight:** run `la-doctor --plugin <this skill's base directory> --require-config` once per session before using any `la-*` or `dr-*` command. If it reports the missing-config finding (the one naming `/la:init`), run the fast path of the `la:init` skill, then re-run this preflight; stop and show the user its output on anything it still reports, or on any other failure.

**Stage 4 of 4 of the `/la:pr` flow.** Prerequisite: `/la:pr` has run in this
session and established `BRANCH`, `CHANGE_ID`, `OPENSPEC`, and the full tracker
issue (body + comments, if there is one), and the PR for `BRANCH` exists. If any of that is
missing, invoke the `la:pr` skill instead — it rehydrates and dispatches back
here. The `/la:pr` stopping policy applies throughout this stage.

**Review sources.** `la:process-reviews` owns everything per source: which bots
are on this PR (`la-pr-reviewers`), waiting for them, fetching, validating, and
handling invalid findings. Every step below that names CodeRabbit or Sonar
applies only when that bot is on the PR. Codex follows `reviewers.codex`: when
`la-config get reviewers.codex` prints `false` there is no Codex gate; when it
is on and the Codex MCP server (`mcp__codex__codex`) is missing, STOP and tell

**Preflight:** run `la-doctor --plugin <this skill's base directory> --require-config` once per session before using any `la-*` or `dr-*` command. If it reports the missing-config finding (the one naming `/la:init`), run the fast path of the `la:init` skill, then re-run this preflight; stop and show the user its output on anything it still reports, or on any other failure.

**Stage 2 of 4 of the `/la:pr` flow.** Prerequisite: `/la:pr` has run in this
session and established `BRANCH`, `CHANGE_ID`, `OPENSPEC`, and the full tracker
issue (body + comments), if there is one. If any of that is missing, invoke the `la:pr` skill
instead — it rehydrates and dispatches back here. The `/la:pr` stopping policy
applies throughout this stage.

Before writing anything, recover the durable plan from `pr-plan`:
- `OPENSPEC=1` — read the whole change folder
  `openspec/changes/<CHANGE_ID>/` (proposal, design, tasks, delta specs).
- `OPENSPEC=0` — the finalized plan is a comment on the tracker issue.

## Step 1 — Write the tests first

**Preflight:** run `la-doctor --plugin <this skill's base directory>` once per session before using any `la-*` or `dr-*` command; if it fails, stop and show the user its output.

# Process unresolved review feedback (CodeRabbit + SonarQube + Codex + failed CI)

Combine CodeRabbit, SonarQube, Codex, and failed CI feedback into a single triage workflow: one sweep over every source. Run standalone, it stops at a written plan and does not start fixing. Invoked from `la:pr-review`, it returns the triaged list and `la:pr-review` fixes it.

**Sources on this PR.** Run `la-pr-reviewers <PR>` first. It prints `{"coderabbit": <bool>, "sonar": {"present": <bool>, "project_key": <key|null>}}`, detected from the PR itself, never from the repo config. Skip every step for a bot that is not on the PR (its fetches, validation, invalid-handling, and plan header count — show it as `off`). Re-run it at each sweep: CodeRabbit can first appear after a push.

**Codex follows `reviewers.codex`.** If `la-config get reviewers.codex` prints `false`, skip every Codex step and show Codex as `off`. Otherwise, if the Codex MCP server (`mcp__codex__codex`) is not available, STOP and tell me: this repo requires Codex reviews, so never skip one silently.

## Inputs

- PR number. If the user didn't say, infer from the cwd: `gh pr view --json number -q .number`. If that fails, ask the user.
- Repository (auto-detected from cwd via `gh repo view`, or pass explicitly).

**Preflight:** run `la-doctor --plugin <this skill's base directory>` once per session before using any `la-*` or `dr-*` command; if it fails, stop and show the user its output.

# Reply to a GitHub PR review thread

Wraps the GitHub `POST /repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies` endpoint. Works for any review thread on any PR, but the canonical use case is replying to CodeRabbit threads — never resolve them, always reply with rationale.

## How to run

```bash
# Form 1 — paste the discussion URL straight from the CodeRabbit comment:
echo "@coderabbitai <reason>" | \
  la-reply-to-pr-thread https://github.com/OWNER/REPO/pull/<PR>#discussion_r<COMMENT_ID>

# Form 2 — explicit IDs: