tiagovilasboastiagovilasboas/downshift-ai/skills/architecture-coverage/SKILL.md

architecture-coverage

Skill4 starsChanged 9 days agoApache-2.0View on GitHub

Fill the architecture coverage inventory before proposing a roadmap phase that touches the Downshift binary. Triggers on: roadmap, architecture, BDI, accounting, compaction, "the whole thing", or any plan with multiple phases. Only applies when the workspace is the Downshift repository.

In this repository12 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- llms.txtllms.txt
- downshift-layeringSkill
- downshift-auditSkill
- downshift-effortSkill
- downshift-orchestratorSkill
- downshift-setupSkill
- downshift-squadSkill
- downshift-tuneSkill
- harness-engineerSkill
- ponytailSkill

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Every internal/<pkg>/ and cmd/<pkg>/ directory on disk must appear in docs/contrib/coverage.md or AGENTS.md.
line 55
Distinctive:
Every package path in AGENTS.md must exist on disk.
line 57

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Architecture coverage — procedure

When to load: a roadmap phase, an architecture question, a BDI question, a compaction plan, an accounting plan, or any request that says "the whole thing".

This skill does not ship in the plugin. Operators who install Downshift do not pay this context. It is a contributor-only procedure.

Step 1 — read the three sources (do not use `docs/architecture/`)

docs/design/architecture.md — current import graph, domain map, known gaps.
docs/domains/README.md — per-domain boundaries and invariants.
docs/reference/capability-matrix.md — what each harness can and cannot do today.

docs/architecture/ files are historical. Do not cite them as current.

Step 2 — fill the inventory

Copy this table into the plan. Mark each row in, out, or unknown. A blank cell or an unknown cell means the plan is not ready to implement.

Surface	Packages	Effect	Account	This phase
Routing	`core`, `classify`, `fuse`, `session`, `catalog`, `quota`	writes child model	`telemetry.Aggregate`
Shell	`execwrap`, `shellwrap`	rewrites command / advises retry	bytes, outside `Saved`
Telemetry	`telemetry`, `childend`, `hookport`	measures	token, no dollar
Accounting	`accounting`	CLI does not import; ADR Proposed	dollar, +15% bias
Adapters	`internal/adapters/*`	translates the wire	honor + usage per harness
Quality	`outcome`, `benchmark`	offline	acceptance suite

Step 3 — check the two accounts

The token account (telemetry.Aggregate) and the dollar account (accounting, ADR Proposed) are not the same number. Never merge them in a claim or plan.

Step 4 — confirm doubt stays allow

An unconfident routing decision (!Decision.Confident) allows the spawn unchanged (held by internal/routing/guard, called from internal/routing/decide: R7 on doubt, R8 never widen). No phase in this plan changes that.

What CI enforces (`internal/docscheck`)

Every internal/<pkg>/ and cmd/<pkg>/ directory on disk must appear in docs/contrib/coverage.md or AGENTS.md.
Every package path in AGENTS.md must exist on disk.
AGENTS.md must be ≤ 200 lines.

A phase that adds a package without updating the inventory will fail CI.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free