ayoubben18/ab-method / .agents/skills/sync-architecture
sync-architecture
UnverifiedPost-implementation documentation-sync detector. Spins up ONE read-only subagent on a completed task's diff to find everything the change introduced that the architecture docs don't yet know about — new endpoints, patterns, seams, dependencies, domain terms, ADR-worthy decisions — routed to the exact doc each belongs in. Autonomous runs apply only in-place safe edits that pass the check-docs budget gate and defer domain/ADR reshapes; interactive runs present the proposed doc deltas to pick. Use after a task's missions are done (from create-task / start-task / start-roadmap) or standalone on a diff.
Sync Architecture (post-implementation)
Detect, from a completed task's diff, what the change introduced that the architecture and domain docs don't know yet — then fold it into the docs in place. It runs beside ../review-implementation/SKILL.md but asks a different question: that skill asks "is this diff good code?", this one asks "are the docs now wrong or incomplete?"
It is the automated detection half of /update-architecture and reuses its routing table. Talk to the
user per .ab-method/rules/communication.md; every doc write follows .ab-method/rules/docs.md.
Silence is the default output. A bug fix, styling, or CRUD that follows existing patterns produces no deltas. A finding survives only if a doc is genuinely now wrong or incomplete. Never invent churn.
ALWAYS check .ab-method/structure/index.yaml FIRST for where the docs live — paths are
user-configurable. Use the project root's copy; only if the project has none (plugin install), read the
bundled default at ../../../.ab-method/structure/index.yaml relative to this SKILL.md. Every path it
names is relative to the project root. Sweep only this task's diff (its commit range) plus its
progress-tracker.md mission summaries — never a whole-repo audit.
Process
1. Gather diff + context
- The task's
git difffor its commit range and its Mission Summaries (Files / Built / Integrates with). - The current docs, so only what's missing is proposed (skip absent files):
tech-stack.md, theindex.mdofdocs/architecture/frontend/andbackend/(then only the topic files the diff touches),UBIQUITOUS_LANGUAGE.md,CONTEXT.md,docs/adr/, anddocs/seams/index.md(then only the seam docs the diff touches). - Legacy single-file
frontend-patterns.md/backend-patterns.mdinstead of the split folders: route to them as they are, and note once in the report that/ab-cleanupmigrates them.
2. Spin up ONE read-only detector subagent
Spawn a single subagent, architecture-sync, with the diff, the mission summaries, the current docs, and
the task's unresolved-questions.md if present. It returns a routed findings list (often empty) and edits
nothing. On Codex spawn it at the orchestrator's level; on Claude it may nest.
Its brief — detect only what the docs don't already capture, routed with /update-architecture's table:
| Finding | Routes to (update-architecture step) |
|---|---|
| New / renamed / moved endpoint, CLI command, cron, webhook, queue consumer | tech-stack.md Entry Points (2a) — plus the backend api topic if a convention shifted |
| New or swapped component / service / state / auth pattern | the closest topic file under docs/architecture/<layer>/ (2b) |
| New dependency, third-party API/queue, new limit, test-framework shift | tech-stack.md Stack / External Services / Constraints / Testing (2c) |
| New domain term, or a term whose meaning shifted | UBIQUITOUS_LANGUAGE.md (+ CONTEXT.md if meaning shifted) (2d) |
| A hard-to-reverse, surprising, trade-off-carrying decision | ADR candidate (2e) — never written inline; defer to /domain-model |
| A seam doc's files, interface or adapters changed | that docs/seams/<slug>.md (2f) |
A seam's status moved (format: codebase-design's SEAM-FORMAT.md) | that seam doc's Status line (2f): set from the seam's Check per the lifecycle there (introducing → migrating once most callers go through it → settled once Check is empty) |
| A new module that clears the seam bar | a new docs/seams/<slug>.md + its index.md line (2f) |
For each finding return: What (the thing introduced, citing file/mission), Doc (target file + section or topic), Proposed delta (the in-place edit: which entry it merges into or replaces, and the new wording), Class (Step 3).
Example: "New endpoint
POST /charges(src/api/charges.ts, mission 2) — missing from tech-stack.md Entry Points. Delta: addPOST /charges — create a charge (bearer auth)to the Entry Points list. Class: safe-edit."
Deltas obey .ab-method/rules/docs.md: the rule plus one exemplar path, never a list of instances;
no task names, "added in", or dated blocks; no [DEPRECATED] — what stopped being true is deleted; the
why is an ADR link, not prose. A new topic file only when no existing topic fits, plus its one line in
that layer's index.md.
Never document a black box as established practice. A placeholder behind a TODO(UQ-n) seam recorded
in unresolved-questions.md is provisional: don't write it as a constraint, a pattern, or a term, and a
parked question is never an ADR candidate. Route what the change built around it (the endpoint, the
dependency, the seam's existence) and describe the placeholder only as what it is ("currency fixed to USD
pending UQ-1").
Out of scope: code quality (review-implementation), whole-repo deepening
(/improve-codebase-architecture). With nothing missing, return exactly:
Docs in sync — no architecture updates needed.
3. Classify each finding
safe-edit— an in-place edit that makes the doc match the diff with no judgment call: add a line to an existing list, merge into the closest entry, replace an entry the diff made untrue (the old pattern is gone from the code), add a glossary term, update a seam doc's files / interface / adapters, or move a seam's status when its Check proves it (run it; cite its result).needs-judgment— a term's meaning shifted, a new bounded context, an ADR candidate, a new seam whose name, interface or bar needs deciding, or an edit that can't pass the budget gate without deciding what else to cut. Route to/domain-model(domain / ADR) or/update-architecture(larger reshapes); don't apply here.
4. Act — by mode
After applying any edit, run the gate:
node .ab-method/scripts/check-docs.js # plugin installs: npx ab-method check-docs
Interactive (create-task tail, or standalone): present deltas grouped by target doc, each marked
safe-edit / needs-judgment. Apply the safe-edits the user approves, run the gate, and compact any
failing file under .ab-method/rules/docs.md before reporting. Point needs-judgment findings at the
right workflow.
Autonomous (start-task / start-roadmap) — the orchestrator, not the detector, applies:
- Apply every
safe-editin place, then run the gate. - If a touched file fails and can only pass by cutting content that needs a judgment call, revert that file's edit and record the delta as open. Pre-existing failures in files this run didn't touch are noted, not fixed.
- Commit what passed as one
docs(<task>): sync architecture docs. Nothing applied → no commit. - Record every open finding (
needs-judgmentand reverted deltas) in the task'sreview.mdunder an Architecture sync heading, or in the run report if noreview.mdexists. Never write an ADR and never prompt.
Remember
- Index first; the mission summaries already list Files / Built — start there, confirm against the diff.
- Always check Entry Points for API drift, even when routing wasn't obviously touched.
- Always check seam docs the diff touched: files, interface, status.
- Edit in place, never append; a doc write isn't done until
check-docspasses. - Silent by default; scoped to the task's diff; domain reshapes and ADRs always go to a human.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 196k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |