align

Files (1)

• SKILL.md

SKILL.md (first lines)

# align

Bring a repo's conventions into alignment with the KB standards. **Assess everything, fix nothing without approval.**

The defining design principles:

> **The CHANGELOG is the source of truth.** The KB's `CHANGELOG.md` carries dated, stateless migration instructions. The skill reads them, assesses which apply to the current repo, and presents the gaps. It does not hardcode conventions — it follows whatever the CHANGELOG says.
>
> **Resources, not just files.** Convention changes affect multiple resource types: files, repo settings, tickets, CI/CD, infrastructure, databases, observability, external services. The skill infers affected resources from what each convention change assumes about the world, and checks all of them.
>
> **Critical by default.** The skill pushes back when migration scope is incomplete — if a CHANGELOG entry implies a resource type that the repo hasn't addressed, the skill flags it rather than silently skipping. It also flags destructive operations and requires explicit confirmation before proceeding.
>
> **Safe and reversible.** Destructive operations (file deletions, renames, config changes that affect all contributors) are flagged with warnings and require explicit confirmation. The skill prefers additive changes (create new files, append sections) over destructive ones (delete, overwrite). When a migration step can't be undone, say so before executing.
>
> **Interactive, not autonomous.** Every migration step is presented, explained, and approved before execution. The operator can skip, defer, or modify any step. Batch approval is available for mechanical steps, but destructive or ambiguous steps are always individual.

## How this skill relates to other skills

```
KB repo (source of truth)
  │
  ├── CHANGELOG.md — dated migration entries with resource-typed steps
  ├── templates/ — canonical file templates
  └── skills/ — skill definitions (including this one)
        │
        ▼
/align (this skill) — reads CHANGELOG, assesses target repo, presents gaps
  │
  ├── File migrations → Edit/Write directly
  ├── Repo settings → surface gh CLI commands (HITL)
  ├── Ticket migrations → /issue for title/scope fixes
  └── Manual steps → surface instructions, can't automate
```

## Phase 0 — Locate the KB

The skill needs access to the KB repo's `CHANGELOG.md`. Discover it in this order:

1. **Symlink at repo root:** check for `./kb` or `./knowledge-base` symlink. If present, use it.
2. **Explicit path:** if the user passed a path argument (e.g. `/align ~/Code/asabina-de/kb`), use it.
3. **Environment variable:** check `$KB_PATH` if set.
4. **Ask:** if none of the above, ask the operator: "Where is the KB repo? Provide a path, or set up a `./kb` symlink."

Verify the path by checking for `CHANGELOG.md` at the root. If missing, refuse: "No CHANGELOG.md found at {path} — this doesn't look like the KB repo."

Read the full `CHANGELOG.md`. Parse each dated section, extracting:
- **Date** — when the change landed
- **Changed/Added/Removed items** — what changed
- **Migration steps** — grouped by resource type (or ungrouped in older entries)

## Phase 1 — Assess the target repo

Read the target repo's current state in parallel:

- **Repo docs:** `CONTRIBUTING.md`, `AGENTS.md` / `CLAUDE.md`, `README.md`, `CHANGELOG.md`
- **CI/CD:** `.github/workflows/`, `.pre-commit-config.yaml`
- **Repo config:** `.github-settings.yaml`, `.gitignore`, `.envrc`
- **Templates vs local:** compare local files against KB `templates/` to detect drift
- **Git config:** merge strategy, branch protection (via `gh api` if available)
- **Recent history:** `git log --oneline -20` for convention compliance in recent commits

### Infer resource scope

For each CHANGELOG migration entry, infer what resource types it affects:

1. Read the migration steps — they may already be grouped by resource type (newer entries).
2. For ungrouped entries (older format), infer: does this change affect files? Repo settings? Tickets? CI? Read the "Changed" description to understand what the convention assumes.
3. Build a resource map: `{changelog_date: [{resource_type, migration_step, applies: bool, status: done|gap|partial|unknown}]}`

### Detect gaps

For each migration step, check whether the target repo has already applied it:

**Files:**
- Does the file exist? Does its content match the expected pattern?
- Search file contents for pattern matches (e.g. "does CONTRIBUTING.md have an 'AI Co-authorship' section?")
- Compare against the KB template version for drift

**Repo settings:**
- Read `.github-settings.yaml` if present — compare declared settings against the KB template (`templates/github-settings.yaml`), respecting its norm levels:
  - **REQUIRED fields** (`squash_title: pr_title`, `squash_message: commit_messages`): the KB template's value is the only valid one. A deviating spec is a gap **even when the spec matches the repo's live GitHub settings** — matching a misconfigured reality is not compliance; it usually means a generate-from-live flow laundered a footgun into the spec. The fix direction is always spec-and-live → norm, never norm → spec.
  - **PREFERENCE fields**: repo-level choices — only flag when the spec and live settings disagree with each other.
- **Never overwrite an existing `.github-settings.yaml`.** Reconcile field-wise: REQUIRED fields converge to the KB norm (propose the spec edit plus the matching live-settings `gh` fix), PREFERENCE fields keep the downstream repo's value, and fields that are new upstream are proposed as additive edits. Regenerating the file from the template or from live settings discards project-specific configuration — edit in place, never replace.
- If no `.github-settings.yaml`, flag as "repo settings not declared — unknown compliance"
- Check observable settings via `gh api repos/{owner}/{repo}` if `gh` is available — validate REQUIRED fields against the norm value directly, not just against the local spec

**Tickets:**
- Fetch open issues from Linear (e.g. `list_issues` filtered by project/team)
- Run each title through the quality gate: imperative voice, verb tiers, statement detection, truncation check
- Check descriptions for DoD presence
- Flag scope issues: overly broad tickets, missing breakdown

**CI/CD:**
- Check for expected workflows (e.g. `lint-pr.yaml`)
- Compare workflow content against the KB template — the canonical copy lives in `templates/`, **never** in the KB's own `.github/workflows/`. Reading the KB's live copy instead happens to work today only because CI keeps the two identical; it is not the contract, and it breaks the moment a workflow is KB-specific.

**Workflow templates are bundles, not files.** A workflow may depend on sibling files — a pattern it reads, a schema it validates against, a fixture and script its red-case job runs — so a template is a **directory mirroring the exact paths its files take downstream**. A bundle root mirrors the **repo root**, not `.github/`: files may live anywhere the workflow needs them.

```
templates/github-workflow-lint-pr/        templates/github-workflow-lint-settings/
└── .github/                              ├── .github/
    ├── workflows/lint-pr.yaml            │   └── workflows/lint-settings.yaml
    ├── pr-title-pattern.txt              └── schemas/
    ├── fixtures/pr-titles.tsv                ├── github-settings.schema.json
    └── scripts/                              └── fixtures/
        └── check-pr-title-pattern.mjs            ├── valid/*.yaml
                                                  └── invalid/*.yaml
```

Adopt with a recursive copy from the repo root, and detect drift with a direct diff per top-level directory the bundle carries:

```bash
cp -R "{kb-path}/templates/github-workflow-lint-pr/." .
diff -r "{kb-path}/templates/github-workflow-lint-pr/.github" .github

cp -R "{kb-path}/templates/github-workflow-lint-settings/." .
diff -r "{kb-path}/templates/github-workflow-lint-settings/.github" .github
diff -r "{kb-path}/templates/github-workflow-lint-settings/schemas" schemas
```

From asabina-de/kb, CC-BY-4.0.

More from asabina-de/kb