rack-advanced
Advanced rack beyond day-to-day lifecycle: authoring a new custom backlog, and cross-project work. Use when defining a backlog beyond the built-in tasks/HYP/PROP, or registering and searching backlogs across several projects.
- License 许可
- MIT
- 所属仓库
- muratovv/ai-hats
- 最近更新
- 2026-11-05
- Stars
- ★ 3
- Forks
- 1
01 前言 Front Matter
- name
- rack-advanced
- ai_hats
- { "type": "skill", "schema_version": 1 }
- license
- MIT
- description
- Advanced rack beyond day-to-day lifecycle: authoring a new custom backlog, and cross-project work. Use when defining a backlog beyond the built-in tasks/HYP/PROP, or registering and searching backlogs across several projects.
02 资源文件 1
- 参考文档references/backlog-yaml-grammar.md11.5 KB
03 SKILL.md 正文
Rack Advanced
Advanced rack operations beyond day-to-day lifecycle:
- Authoring a new backlog — define a
backlog.yamland mount it undertracker/. → Authoring a new backlog - Cross-project work — sweep one backlog across projects: register them (Registry), then list / read across them (Search across projects).
When to Use
Reach here when the task is to define a new backlog (a distinct catalog with
its own id prefix, state machine, fields, and link kinds) — e.g. a project
decisions, experiments, or incidents backlog alongside the built-in
tasks / hypotheses / proposals.
Also reach here for cross-project work — registering projects with rack root
(Registry) or listing / reading one backlog across several projects
(Search across projects).
Not this skill when you are:
- filing a card (
rack create, or thebacklog-createshim) — that adds a card to an existing backlog, it does not define one; - driving a card's lifecycle / ops (transition, log, link, hyp/proposal verbs) — that is hatrack.
The moment you are editing backlog.yaml itself (not a task.yaml), you are here.
Authoring a new backlog
There is no rack init / register verb — a backlog is drop-a-file. Author
the definition, place it under tracker/, and it mounts on the next rack call.
-
Pick identity. A
prefix(cards become<prefix>-<n>) unique within the root, and acli_alias(the shortrack <group>name) unique across mounted backlogs. Do not reuseHATSor an existing alias (DuplicatePrefixError/DuplicateGroupNameErrorat mount). -
Make the catalog dir under
<ai_hats_dir>/tracker/— conventiontracker/<name>/, a sibling ofbacklog/. Anywhere undertracker/works except insidebacklog/, whichbacklog_write_gate.pydenies to every writer butrack(its one carve-out istasks/<ID>/plan.md). -
Author
backlog.yamlat that dir's root. Full key grammar + fail-closed invariants:references/backlog-yaml-grammar.md. Fastest start — print a shipped example (HYP / PROP) from the installed package and adapt (works in any project, no repo checkout needed):python -c "from ai_hats_rack.definition import packaged_definition_source as s; print(s('hypotheses'))" # or: proposals(If a bare
pythoncan't importai_hats_rack, use the interpreter that backsrack.) Or start from the minimum skeleton:name: decisions prefix: DEC cli_alias: decision fsm: initial: open states: [{ name: open }, { name: accepted }, { name: superseded }] edges: - { from: open, to: accepted, name: accept } - { from: open, to: superseded, name: supersede } links: kinds: # must be NON-EMPTY; a symmetric self-inverse kind is the minimum - { name: related, arity: many, inverse: related } fields: - { name: context, type: str, default: "" } -
It auto-mounts.
Workspace.discover→_scan_sibling_backlogswalkstracker/**and picks up everybacklog.yaml. No registration step. -
Verify it landed:
rack --helplists the<cli_alias>group;rack <alias> create "…"mints<PREFIX>-001(ids are zero-padded, min 3 digits);rack context <PREFIX>-001routes by prefix;rack ls --backlog <alias>filters to it.
Before you save — invariant checklist (each is a fail-closed loader error):
- Every top/section key is in the grammar — a stray key (e.g.
sections:) is rejected (UnsupportedBacklogKeyError). links.kindsis non-empty (LinksRegistryErrorotherwise) — a backlog with no cross-links still needs one kind;related(symmetric) is the minimum.- No edge
nameequals a state name (EdgeNameStateCollisionError). - Any stored inverse pair (
inverse:on both, both stored) carrieshandlers: [mirror-link](MissingMirrorReactionError). Symmetric (related) and derived (children) kinds are exempt. - Complex fields are
type: anyplus avalidator:name. - Every handler / validator / extension name resolves in the stock code-side registry — you cannot introduce one in YAML alone.
Plan sections are separate. If (and only if) the backlog uses the plan gate,
its plan-section catalog lives in a sibling plan-sections.yaml, not a
backlog.yaml key (never-drift). Most custom backlogs need neither.
What the backlog gets for free
Once mounted, the definition alone yields (no per-backlog code):
rack <alias> create …— schema-driven fromfields(required/choices enforced).rack <alias> update <ID> --<field> …— scalar (str/int) field edits.- Extension verbs any declared
extensionscontribute (e.g.append-verdict). - Prefix-routed reads/moves:
rack context <ID>,rack ls <ID>,rack transition <ID> <state|edge-name>,rack ls --backlog <alias>.
Registry
To sweep a backlog across projects (below), the projects must be known. Note the
contrast with Authoring a new backlog: a backlog
needs no registration (drop a backlog.yaml and it auto-mounts), but a project
is registered explicitly — a persistent list at ~/.ai-hats/roots.yaml (override
the path with RACK_ROOTS_FILE):
rack root add <path> # register a project root (must hold .agent/ or ai-hats.yaml)
rack root ls # list registered roots: root_id, path, reachable?
rack root rm <path> # unregister a root by path
root_id is the project's folder name (no alias). add validates the path is
a project, stores it resolved, and de-dupes (a re-add is a no-op); rm takes the
same path. Registering is optional — --root (below) sweeps ad-hoc roots without
touching the file.
Search across projects
List or read one backlog across several projects — "hypotheses of all
projects" in one command — over the registered roots (Registry)
and/or ad-hoc --root paths.
List on the no-id scan (rows gain a project marker column / project json
key; the current project is always included, roots dedup by real path):
rack ls --projects all # every registered project ∪ the current one
rack ls --projects projA,projB # a named subset (by root_id) ∪ the current one
rack ls --root ../other # ad-hoc: add a root by path (repeatable)
rack ls --backlog hyp --projects all # the hyp backlog in EVERY swept project
Read — a bare id is ambiguous when two projects share a prefix, so qualify it (or mount an unregistered project by path):
rack context projB:ACME-9 # <root_id>:<id> routes into a registered project
rack context projB:ACME-9 --root ../projB # or mount it by path
Boundaries.
- Read-only. The sweep and qualified
contextare reads; cross-project writes (qualifiedtransition, cross-projectcreate, cross-project links) are out of scope — a sweep never mutates another project. - Read-tolerant registry, fail-fast
--root. A registered root that has vanished is skipped with a non-silent footer (the sweep survives); an explicit--rootto a non-project is a hard error. - Folder-name collision (two
ai-hatsclones): the<root_id>:<id>qualifier is ambiguous — disambiguate with the full path via--root.
Completion
Authoring a backlog — done when: the backlog.yaml sits under tracker/,
rack --help shows its group, and rack <alias> create + rack context <PREFIX>-001 both work — with no loader error on any rack call.
Cross-project sweep — done when: rack root add <path> then rack root ls
shows it, and rack ls --projects all lists cards from the registered project(s)
alongside the current one, each row carrying its project marker.
Validation scenario (RED → GREEN). RED — asked to add a project decisions
backlog, an agent without this skill hunts for a rack init-backlog/register
verb that does not exist, reuses the HATS prefix (DuplicatePrefixError), puts
a sections: key in the file (rejected — unknown key), or declares a
supersedes/superseded_by pair with no mirror-link
(MissingMirrorReactionError) — a multi-error discovery loop. GREEN — with the
skill it writes tracker/decisions/backlog.yaml (unique prefix: DEC +
cli_alias: decision, valid fsm/fields/links, no sections:, mirror-link on
any stored inverse), drops it in, and rack decision create "…" works first try.
Anti-Patterns
- Searching for a create/register/init command — mounting is drop-a-file;
Workspace.discoverdoes it. - Reusing
HATS(or another backlog's prefix / alias) — collisions fail closed at mount. - Putting a
sections:(or any undeclared) key inbacklog.yaml— plan sections are a siblingplan-sections.yaml; unknown keys are rejected. - Declaring a stored inverse link pair without
mirror-link— the reverse edge would drift, so the loader refuses it. - Inventing a handler / validator name in YAML with no code-side factory — the name must resolve in the stock registry or composition fails closed.
- Expecting
--projects/--rootto route a write — the sweep is read-only; cross-project mutation is out of scope. - Leaning on a
<root_id>:<id>qualifier when two roots share a folder name — the id is ambiguous; use the full path via--root. - Hand-editing
~/.ai-hats/roots.yamlfor a bad path —rack root addvalidates and resolves; a non-project path is rejected there.
04 同仓库更多 Skills
tool-evaluation-protocol
Time-bounded protocol for evaluating new tools, libraries, or methodologies before adoption. Use when evaluating a candidate dependency for the project, researching a methodology (e.g. ML/LLM frameworks, testing approaches), or following up on a hype-driven recommendation.
systematic-debugging
4-phase bug-fix protocol (evidence, pattern, hypothesis, verify). Use when investigating any error, failure, or unexpected behavior, handling bug reports from users or monitoring, or diagnosing test failures with non-obvious causes.
skill-template
Canonical template and validation guide for ai-hats skills. Use when creating a new skill, reviewing an existing one for structural compliance, or deciding which pattern fits a new behavior.
skill-optimization
Audit and refactor library components to eliminate redundancy and staleness. Use during periodic library maintenance, after adding multiple new skills or rules, when a role's token budget is too high, or after retrospectives identify component issues.
silent-fallback-gate
PreToolUse hook — refuses an Edit or Write that adds an inert broad except. Use when a Python edit was blocked for a silent fallback.
retro-to-framework
Convert an observation about agent behavior — from a retrospective or from a single incident — into a framework-level change (hook, rule, skill, skill update). Use after a retrospective identifies problems that are not project-specific, after an incident where an agent misapplied a component it had read, when CLAUDE.md band-aids accumulate (more than 3 per-project rules that could be generic), or when the same problem recurs across multiple projects.