Repo Harness Architecture

Name: Repo Harness Architecture
Author: Ancienttwo

By Ancienttwo· Ancienttwo/repo-harness· 0

Update architecture documentation and diagrams without reinitializing your repository.

Installation

1
Make sure Claude is on your device and in your terminal.
Skills load from ~/.claude/skills/ when Claude Code starts up — so you need it on your machine first. If you don't have it yet, install it once with the command below, then run claude in any terminal to verify.
One-time setup
```
npm i -g @anthropic-ai/claude-code
```
Already have it? Skip ahead.

Paste into Claude Code or into your terminal.

Install

git clone ht•••••••••••••••••••••••••••••••••••••••••••• ••••••••••••••••••••••••••••• •• ••••• •• ••••••••••••••••••••••••••••••••••••••••••••••••••••• •• •• •• ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• ••••••••••••••••••••••••••••••••••••••••••••••••••••••

This copies the whole skill folder into ~/.claude/skills/repo-harness-architecture-ancienttwo/ — the SKILL.md plus any scripts, reference docs, or templates the skill ships with. Safe default: works for every skill.

Faster alternative (instruction-only skills)

Skips the clone and grabs only the SKILL.md file. Don't use this if the skill ships Python scripts, reference markdowns, or asset templates — they won't be downloaded and the skill will fail when it tries to load them.

Quick install (SKILL.md only)

mkdir -p ~/.•••••••••••••••••••••••••••••••••••••••••••••••••• •• •••• ••••• ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• •• ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

Restart Claude Code.
Quit and reopen Claude Code (or any other agent that loads from ~/.claude/skills/). New skills are picked up on startup.
Just ask Claude.
Skills auto-activate when your request matches the skill's description — no slash command needed. Trigger phrases live in the skill's own frontmatter; you can read them in the “What this skill does” section above.

Prefer to read the source first? Open on GitHub.

When Claude uses it

Resolves repo-harness architecture drift requests and updates architecture docs or diagrams without running full init, migrate, or upgrade.

What this skill does

repo-harness-architecture

Use this command when the harness already exists and the user wants a focused architecture documentation, drift-request, or diagram pass.

Protocol

Confirm the target repo path and architecture scope.
Inspect docs/architecture/index.md and pending files under docs/architecture/requests/.
When the scope maps to repo code or config, resolve the capability with:
- repo-harness run capability-resolver match --repo <repo> --path <path> --format json
Update the smallest relevant architecture artifact:
- umbrella status in docs/architecture/index.md
- module or snapshot docs under docs/architecture/
- Mermaid fenced block in the relevant module or snapshot Markdown when a visual flow materially helps
- optional human-readable diagram artifact under docs/architecture/diagrams/
Use Markdown Mermaid as the semantic diagram source; use mermaid only for optional human-readable HTML renderings grounded in observed repo files.
Archive handled requests with:
- repo-harness run archive-architecture-request --request <request> --status <resolved|superseded|rejected|no-change> --artifact <path> --note <text>
- For resolved, the live Pending request must declare > **Architecture Module**: and that exact existing module path must be supplied as an --artifact.
Verify with:
- repo-harness run check-architecture-sync
- repo-harness run capability-resolver validate --repo <repo> --format text
- repo-harness run check-task-workflow --strict when repo workflow surfaces changed

Failure Modes

If no pending architecture request exists, report no-change and do not invent one.
If capability resolution is ambiguous, stop at the matching paths and ask for a narrower scope.
If check-architecture-sync.sh blocks in strict mode, resolve or archive the pending request card for the touched capability before finishing the worktree.
If diagram rendering fails, keep the Mermaid Markdown source and report the render failure.

Boundaries

Does not run repo-harness adopt.
Does not install or refresh the full harness.
Does not let hooks rewrite architecture prose; hooks only record drift requests.
Does not vendor mermaid; it remains an external installed skill for optional human-readable HTML.
Keeps docs/architecture/requests/ pending-only by archiving handled requests.

Related skills

Claude API Helper

anthropics

Build, debug, and optimize Claude API applications with caching and model migration support.

OfficialComplete terms in LICENSE.txt

Documentation Co-Authoring

anthropics

Guide structured workflows for writing docs, proposals, and technical specs collaboratively.

Official

PPTX Text Extractor

axoviq-ai

Extract text and speaker notes from PowerPoint presentations.

AGPL-3.0-or-later

Memory Search

davila7

Search conversation history and recall previous discussions, decisions, and context.