Awareness - what this project has, how it runs, how it is built, what it is bound to
Five deliberate captures share this skill. Each part is a reference the run reads and follows; the first word picks
one part, and the typed command with no topic word runs the chain behind one ask.
| Part |
Topic words |
Its own arguments |
Writes |
Seats |
| project |
project |
none, refresh, or any text (a NOTE) |
awareness/PROJECT-INFO-AWARENESS.md, awareness/RUN-AND-DEBUG-AWARENESS.md, awareness/RESOURCES-AWARENESS.md, awareness/USER-AWARENESS.md (created once) |
none |
| related-projects |
related-projects, related |
none, refresh, or sibling locations (each with an optional relation hint) |
awareness/RELATED-PROJECTS-AWARENESS.md |
related-project-analyzer |
| project-code-style |
project-code-style, code-style |
none, or refresh |
preferences/PROJECT-CODE-PREFERENCES.md |
code-style-analyzer |
| architecture |
architecture |
none, refresh, or a target (a path that exists) |
awareness/ARCHITECTURE-AWARENESS.md, awareness/references/, awareness/history/, awareness/ARCHITECTURE-ORIENTATION-AWARENESS.md |
architecture-analyzer |
| agents |
agents |
none, or refresh |
awareness/AGENTS-AWARENESS.md |
none |
Every path is under <docs-path>/. The rule .claude/rules/alfred-awareness.md is no part's. Every run that ran the
project, related-projects, architecture or agents part closes with ONE --rule call after its last part (section 5),
so a lone /capture-awareness project writes the imports of the docs it just made. agents is the table's last row,
so a chain takes the inventory after the seat parts wrote their rules. A lone architecture run closes with the same
call, which writes the map's pointer line; a lone code-style run takes no inventory and leaves the awareness rule
alone.
<docs-path>/awareness/ is one docs domain with one watch.json. Its notOwned entry keeps the docs engine from
sectioning or writing AGENTS-AWARENESS.md, which only the script writes. Each doc's shape is fixed verbatim in its
reference - no formatting skill loads for them (the docs root belongs to the skill that writes it). The rule imports
these into every session and every subagent:
| File |
Holds |
Written by |
In git |
<docs-path>/awareness/AGENTS-AWARENESS.md |
the house usage policy and the real inventory |
the script, whole |
never - it names this machine's plugins |
<docs-path>/awareness/PROJECT-INFO-AWARENESS.md |
what the project is, who uses it, its stack and where it runs |
the project part, from the repo and the user's answers |
with the docs |
<docs-path>/awareness/RUN-AND-DEBUG-AWARENESS.md |
the run book |
the project part, from the repo and the user's answers |
with the docs |
<docs-path>/awareness/RESOURCES-AWARENESS.md |
the issue tracker, the wiki, the error monitor, the git host and CI |
the project part, from the repo and the user's answers |
with the docs |
<docs-path>/awareness/RELATED-PROJECTS-AWARENESS.md |
the sibling repos and their seams |
the related-projects part, from the siblings the user names |
with the docs |
<docs-path>/awareness/USER-AWARENESS.md |
the user's own notes |
the user alone - the project part creates it once |
never |
.claude/rules/alfred-awareness.md |
one @ import per doc |
the script |
where the project commits .claude/rules/ |
The rule stays out of the installer's catalog and no installer ledger records the generated files, so
/alfred-code:update never overwrites them - it only moves an older install's files into this layout.
When to use
- A topic word picks one part:
/capture-awareness project, /capture-awareness architecture src/api,
/capture-awareness code-style, /capture-awareness related ../backend, /capture-awareness agents.
- After an install, an update, a configure run or a trim (the inventory moved), when the run book is missing or
stale, to add or refresh a sibling repo, or to map the structure or the code style.
- The chain of all five runs only on the typed
/capture-awareness with no topic word (or refresh), or a request
that asks in words for the whole awareness capture. A description match runs the one part the request names.
- A re-run is cheap: the inventory is one script call, and each other part asks or reads only what moved.
- Not for judging the code, the architecture or the coverage (capture-quality), or dynamic cross-repo findings -
those go to Claude Code's own memory, naming the sibling.
Modes. Mode flags right after the command - --mode-auto-run-on, --mode-auto-run-off, --mode-output-scorer-on, --mode-output-scorer-off - are switches, not the request: strip them; with only flags typed, run as with no arguments. Under the hook's auto-run contract, follow it. With no hook line (hooks off, Cursor), -on holds for this run only: each stop takes its (Recommended) option, listed in the close, an unmarked one waits, nothing goes outward, no fresh-session hand-off, and the close says auto-run ended; --mode-output-scorer-on grades this run's output like a typed stack.
0. The script - resolve it once
scripts/awareness-state.js reads every part's state (--state), writes AGENTS-AWARENESS.md (--write, the
agents part) and the rule (--rule, section 5). It has TWO homes - this skill's copy under .claude/skills/, or
the stack's plugin cache, where several versions can sit side by side and the newest is taken (after a core update it
can be newer than the copies) - so resolve it ONCE, before the first part, in any run but a lone code-style one: the
block prints the path, and every later call pastes that literal as <caps> (each Bash call is its own shell, so a
variable set here is gone by the next). Run all of it from the project root:
CAPS=.claude/skills/capture-awareness/scripts/awareness-state.js
[ -f "$CAPS" ] || CAPS=$(for d in "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/*/*/*; do # one glob: zsh aborts the loop when any named glob matches nothing
PN=${d%/*}; PN=${PN##*/}; [ "$PN" = alfred-code ] || continue
f="$d/stack/skills/capture-awareness/scripts/awareness-state.js"
[ -f "$f" ] && [ ! -e "$d/.orphaned_at" ] && printf '%s\t%s\n' "$(basename "$d")" "$f"
done 2>/dev/null | sort -V | tail -1 | cut -f2)
echo "caps: ${CAPS:-absent}"
caps: absent means neither home has it: say so and stop - never hand-tally the inventory or hand-write the rule.
1. The topic word
Read the arguments in this order.
- Strip the mode flags (
--mode-auto-run-on, --mode-auto-run-off, --mode-output-scorer-on,
--mode-output-scorer-off).
- Take the first remaining word, compared whole and case-insensitively against the topic words. A word holding
/,
\ or ., or a git URL, never matches.
- A match picks that part. A mode word next,
DELEGATED or INLINE (case-insensitive), marks a calling flow: the
part skips its run gate and its seats-or-inline ask and inherits that mode, and every word after it is the part's
own argument. A person may type the same form, and has then chosen. Without a mode word the rest is the part's own
argument. On the TYPED command the rest must fit the part's column above; when it does not, the whole text is a
NOTE for the project part, and the run's first line says so - 'Read as a note: . To run the part,
type /capture-awareness .' A caller's Skill call (section 4) is never re-read as a note: its topic wins and
the rest is its argument.
- No match - who started the load decides:
- On a description match (the model loaded the skill on a request), section 3's load rule decides, and none of
the bullets below applies: the part is the one the request names, a path that exists is that part's argument,
and the chain never runs.
- On the typed command or a caller's Skill call:
- a path that exists or a git URL first: the related part with those siblings;
refresh alone: the chain, with every part's run recommended whatever its state;
- nothing: the chain;
- any other text: a NOTE for the project part - never the chain.
| Arguments (typed, unless marked) |
Result |
| none |
the chain |
refresh |
the chain, every part recommended |
Agents |
the agents part |
architecture |
the architecture part, whole repo |
architecture src/api |
the architecture part, target src/api (it exists) |
architecture DELEGATED src/api |
the architecture part through its seats, no run gate or mode ask, target src/api |
architecture is hexagonal |
a NOTE, 'architecture is hexagonal' (the rest is no path) |
project uses pnpm 9 |
the project part, NOTE 'uses pnpm 9' |
code-style |
the code-style part |
style guide lives in Confluence |
a NOTE (style is no topic word) |
../backend provides-to |
the related part, sibling ../backend |
related ../backend |
the related part, sibling ../backend |
the API needs a VPN |
a NOTE for the project part |
| (model-loaded) 'document the architecture of src/api' |
the architecture part, target src/api - never the related part, never a NOTE |
capture-quality's architecture topic is another skill's word; the two never meet, since a topic is read only
after the command or Skill call that names its skill.
2. One part
The part runs alone, with its arguments, by its own reference - its run gate, mode ask, steps and field template as
written there:
- project: read
references/project.md and follow it.
- related-projects: read
references/related-projects.md and follow it.
- project-code-style: read
references/project-code-style.md and follow it.
references/project-code-style-doc-shape.md - the section format and write mechanics, read before MERGE.
- architecture: read
references/architecture.md and follow it.
references/architecture-doc-shapes.md - the map's shape and write protocol, read before AGGREGATE.
references/architecture-hazards.md - the stack-keyed hazard catalog, read before AGGREGATE.
references/architecture-vocabulary-roles.md - what the vocabulary step loads, read at AGGREGATE.
references/architecture-report-fields.md - what each close field means, read at REPORT.
- agents: read
references/agents.md and follow it.
Each part's contract file is read in full at its step, never from the part's mention alone. Then the close (section 5).
3. The chain
Who started the load decides what a run with no topic word does:
- The user's message is the typed
/capture-awareness command (no arguments, or refresh), or asks in words for the
whole awareness capture: the chain runs.
- Otherwise the model loaded the skill on a request (a description match). The part is the one the request names,
matched against the router table's Writes and topic words ('document the architecture' names the architecture part,
'capture how we build and log in' the project part). When it names none, or more than one, ONE single-select
question picks the part, the closest first and Recommended. The chain never runs on a description match: five
captures, three of them with seats, are never what one request asked for.
- On a description match the remaining words are a part's argument only when they name a path that exists or a git
URL; otherwise there is none. The part's own run gate still applies, because no calling flow started it.
- A calling flow's Skill call (section 4) is none of these: it always names its part, so it reaches the part through
section 1 step 3 and never the chain.
The part pick, when a description match names none of the five parts or more than one:
Which awareness part should run? The request names none of the five, or more than one.
- '<the part closest to the request's words> (Recommended)' - its Writes or topic words come nearest the request
- '<the next closest part>' - writes <its docs>
- '<the third closest part>' - writes <its docs>
The chain:
Run node "<caps>" --state. It reads, never writes, always exits 0, and prints one line per part in the router
table's order - absent (no <doc>), unstamped (<doc>), current <branch>@<sha> or stale <branch>@<sha> (<why>),
and agents: run last. A line ending (no docs engine) read each doc by presence alone; one ending
(docs engine failed) kept the stamps and could not read the drift. With refresh, read every part as needing a run.
Put ONE AskUserQuestion call of at most two questions, each a single-select ask template:
Run the awareness capture? <n> of the five parts need it: <part - state, one per part>.
- 'Run the <n> that need it (Recommended)' - <those parts>; the current ones stay as they are
- 'Pick the parts' - one more question, part by part
- 'Run all five' - every part, the current ones refreshed
The recommended set is never empty, since the agents part always runs. The second question, only when dispatch is
available and a seat part (related-projects, project-code-style, architecture) can run:
Run the seat parts through their analyzer seats or in this session?
- 'Through the seats (Recommended)' - the cheap seats absorb the reads; the reasoning and the write stay here
- 'In this session' - bounded, no dispatch
With no dispatch every part runs INLINE and the second question is not asked.
'Pick the parts' opens ONE more call of two multi-select questions, grouped by the table's Seats column: 'Which
docs from this repo?' (agents, project) and 'Which analyses?' (related-projects, project-code-style,
architecture), each option labelled with its state. Under auto-run the first option of each single-select is
taken, so the Pick call never opens.
The answers are each part's run gate and mode answer, so no part asks either again; a part's content questions (the
run book's asks, the siblings to add) still come. Run each chosen part by reading its reference and following it,
in the router table's order, each in the same skill load: the parts are read, not re-invoked.
The close (section 5), with one Skipped: line naming the parts not run.
4. Callers
- A calling flow hands
<topic> <DELEGATED|INLINE> <target>: the mode word right after the topic skips the part's run
gate and mode ask, and the part inherits the mode.
- A person may type
/capture-awareness <topic> (init's capture rows print that form) and gets the part's run gate.
5. The close
RULE - one script call
After the last part of any run but a lone code-style one, node "<caps>" --rule composes
.claude/rules/alfred-awareness.md from the copy target below - one @ import per awareness doc that exists, the
related doc only once it holds an entry, then the map's pointer line when the map exists - compares it, writes it on
differs, puts back the notOwned entry in watch.json, and removes the rules it supersedes (alfred-agent-awareness.md,
alfred-project-awareness.md, alfred-related-context.md, the 1.x baseline-project-capabilities.md, and the legacy
architecture marker once the map's line is written) once their content is imported. It prints one size: line per
imported doc and an over budget: line past a cap - the project part's budgets are counted there, never by hand. A
RULE: FAIL line is a stack defect: report it as it stands, never hand-write the rule.
COPY TARGET - the script fills the import slot and the map slot; every <docs-path> is the literal docs root:
---
description: Project awareness - generated by /capture-awareness; edit via a re-run, not by hand.
---
# Project awareness
Imported below at every session start, from `<docs-path>/awareness/`: what this install carries and how to use it, the project's facts, the run book - follow it before you build, start, log into or hand-check the app - its resources, the related repos and your own notes. If a file's text is not below, Read it before you act on its area.
<the script's import lines, one per awareness doc>
<the script's map line, when the map exists>
REPORT
One part: its field template, as its reference writes it, then the lines below. The chain: one block per part run,
in table order, each in its part's own field template, then:
Landed: <git | overlay> - the mode line of `node .claude/hooks/docs.js status`, for each doc this run wrote
Rule: <the script's RULE: line, and its size: lines> | not run - a lone code-style run
Live from: next session - the rule is read at session start, so it does not govern this one
Skipped: <the parts the chain did not run, or none>
Then the agents reference's prose lines, and - when the capture surfaced work a sibling owns - the task card the
related reference describes. No re-paste of any doc - point to the files. The rule ships only where the project
commits .claude/rules/ (the installers gitignore .claude/* but .claude/AGENTS.md), so a fresh clone re-runs
this capture.
Don't game it
Every fact in the awareness docs traces to a line the script printed, a file the run read, or the user's own answer: a
gap stays unknown, an unreachable sibling stays an UNVERIFIED entry, an unreadable source is reported as
unreadable, and a credential appears only as the place it lives.
Old installs
/alfred-code:update moves an older install into this layout: the run book from project-awareness/ (or
project-capabilities/) with its section ids and branch versions, the sibling doc from
related-projects/RELATED-PROJECTS.md, the architecture map and its orientation block from architecture/, the
inventory rule's body into AGENTS-AWARENESS.md, and it writes the rule. When a doc still sits at an old home, name
/alfred-code:update in the report rather than moving it by hand.
1---2name: capture-awareness3description: "Use when asked to capture or note project awareness - run book, Jira/Sentry, architecture map, module boundaries, code style, siblings. Not for judging quality."4metadata:5 source: https://skillmd.com/skills/envoydev/capture-awareness6---78# Awareness - what this project has, how it runs, how it is built, what it is bound to910Five deliberate captures share this skill. Each part is a reference the run reads and follows; the first word picks11one part, and the typed command with no topic word runs the chain behind one ask.1213| Part | Topic words | Its own arguments | Writes | Seats |14|---|---|---|---|---|15| project | `project` | none, `refresh`, or any text (a NOTE) | `awareness/PROJECT-INFO-AWARENESS.md`, `awareness/RUN-AND-DEBUG-AWARENESS.md`, `awareness/RESOURCES-AWARENESS.md`, `awareness/USER-AWARENESS.md` (created once) | none |16| related-projects | `related-projects`, `related` | none, `refresh`, or sibling locations (each with an optional relation hint) | `awareness/RELATED-PROJECTS-AWARENESS.md` | related-project-analyzer |17| project-code-style | `project-code-style`, `code-style` | none, or `refresh` | `preferences/PROJECT-CODE-PREFERENCES.md` | code-style-analyzer |18| architecture | `architecture` | none, `refresh`, or a target (a path that exists) | `awareness/ARCHITECTURE-AWARENESS.md`, `awareness/references/`, `awareness/history/`, `awareness/ARCHITECTURE-ORIENTATION-AWARENESS.md` | architecture-analyzer |19| agents | `agents` | none, or `refresh` | `awareness/AGENTS-AWARENESS.md` | none |2021Every path is under `<docs-path>/`. The rule `.claude/rules/alfred-awareness.md` is no part's. Every run that ran the22project, related-projects, architecture or agents part closes with ONE `--rule` call after its last part (section 5),23so a lone `/capture-awareness project` writes the imports of the docs it just made. `agents` is the table's last row,24so a chain takes the inventory after the seat parts wrote their rules. A lone architecture run closes with the same25call, which writes the map's pointer line; a lone code-style run takes no inventory and leaves the awareness rule26alone.2728`<docs-path>/awareness/` is one docs domain with one `watch.json`. Its `notOwned` entry keeps the docs engine from29sectioning or writing `AGENTS-AWARENESS.md`, which only the script writes. Each doc's shape is fixed verbatim in its30reference - no formatting skill loads for them (the docs root belongs to the skill that writes it). The rule imports31these into every session and every subagent:3233| File | Holds | Written by | In git |34|---|---|---|---|35| `<docs-path>/awareness/AGENTS-AWARENESS.md` | the house usage policy and the real inventory | the script, whole | never - it names this machine's plugins |36| `<docs-path>/awareness/PROJECT-INFO-AWARENESS.md` | what the project is, who uses it, its stack and where it runs | the project part, from the repo and the user's answers | with the docs |37| `<docs-path>/awareness/RUN-AND-DEBUG-AWARENESS.md` | the run book | the project part, from the repo and the user's answers | with the docs |38| `<docs-path>/awareness/RESOURCES-AWARENESS.md` | the issue tracker, the wiki, the error monitor, the git host and CI | the project part, from the repo and the user's answers | with the docs |39| `<docs-path>/awareness/RELATED-PROJECTS-AWARENESS.md` | the sibling repos and their seams | the related-projects part, from the siblings the user names | with the docs |40| `<docs-path>/awareness/USER-AWARENESS.md` | the user's own notes | the user alone - the project part creates it once | never |41| `.claude/rules/alfred-awareness.md` | one `@` import per doc | the script | where the project commits `.claude/rules/` |4243The rule stays out of the installer's catalog and no installer ledger records the generated files, so44`/alfred-code:update` never overwrites them - it only moves an older install's files into this layout.4546## When to use4748- A topic word picks one part: `/capture-awareness project`, `/capture-awareness architecture src/api`,49 `/capture-awareness code-style`, `/capture-awareness related ../backend`, `/capture-awareness agents`.50- After an install, an update, a configure run or a trim (the inventory moved), when the run book is missing or51 stale, to add or refresh a sibling repo, or to map the structure or the code style.52- The chain of all five runs only on the typed `/capture-awareness` with no topic word (or `refresh`), or a request53 that asks in words for the whole awareness capture. A description match runs the one part the request names.54- A re-run is cheap: the inventory is one script call, and each other part asks or reads only what moved.55- Not for judging the code, the architecture or the coverage (capture-quality), or dynamic cross-repo findings -56 those go to Claude Code's own memory, naming the sibling.5758**Modes.** Mode flags right after the command - `--mode-auto-run-on`, `--mode-auto-run-off`, `--mode-output-scorer-on`, `--mode-output-scorer-off` - are switches, not the request: strip them; with only flags typed, run as with no arguments. Under the hook's auto-run contract, follow it. With no hook line (hooks off, Cursor), `-on` holds for this run only: each stop takes its `(Recommended)` option, listed in the close, an unmarked one waits, nothing goes outward, no fresh-session hand-off, and the close says auto-run ended; `--mode-output-scorer-on` grades this run's output like a typed stack.5960## 0. The script - resolve it once6162`scripts/awareness-state.js` reads every part's state (`--state`), writes `AGENTS-AWARENESS.md` (`--write`, the63agents part) and the rule (`--rule`, section 5). It has TWO homes - this skill's copy under `.claude/skills/`, or64the stack's plugin cache, where several versions can sit side by side and the newest is taken (after a core update it65can be newer than the copies) - so resolve it ONCE, before the first part, in any run but a lone code-style one: the66block prints the path, and every later call pastes that literal as `<caps>` (each Bash call is its own shell, so a67variable set here is gone by the next). Run all of it from the project root:6869```bash70CAPS=.claude/skills/capture-awareness/scripts/awareness-state.js71[ -f "$CAPS" ] || CAPS=$(for d in "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/*/*/*; do # one glob: zsh aborts the loop when any named glob matches nothing72 PN=${d%/*}; PN=${PN##*/}; [ "$PN" = alfred-code ] || continue73 f="$d/stack/skills/capture-awareness/scripts/awareness-state.js"74 [ -f "$f" ] && [ ! -e "$d/.orphaned_at" ] && printf '%s\t%s\n' "$(basename "$d")" "$f"75done 2>/dev/null | sort -V | tail -1 | cut -f2)76echo "caps: ${CAPS:-absent}"77```7879`caps: absent` means neither home has it: say so and stop - never hand-tally the inventory or hand-write the rule.8081## 1. The topic word8283Read the arguments in this order.84851. Strip the mode flags (`--mode-auto-run-on`, `--mode-auto-run-off`, `--mode-output-scorer-on`,86 `--mode-output-scorer-off`).872. Take the first remaining word, compared whole and case-insensitively against the topic words. A word holding `/`,88 `\` or `.`, or a git URL, never matches.893. A match picks that part. A mode word next, `DELEGATED` or `INLINE` (case-insensitive), marks a calling flow: the90 part skips its run gate and its seats-or-inline ask and inherits that mode, and every word after it is the part's91 own argument. A person may type the same form, and has then chosen. Without a mode word the rest is the part's own92 argument. On the TYPED command the rest must fit the part's column above; when it does not, the whole text is a93 NOTE for the project part, and the run's first line says so - 'Read as a note: <text>. To run the <part> part,94 type /capture-awareness <topic>.' A caller's Skill call (section 4) is never re-read as a note: its topic wins and95 the rest is its argument.964. No match - who started the load decides:97 - On a description match (the model loaded the skill on a request), section 3's load rule decides, and none of98 the bullets below applies: the part is the one the request names, a path that exists is that part's argument,99 and the chain never runs.100 - On the typed command or a caller's Skill call:101 - a path that exists or a git URL first: the related part with those siblings;102 - `refresh` alone: the chain, with every part's run recommended whatever its state;103 - nothing: the chain;104 - any other text: a NOTE for the project part - never the chain.105106| Arguments (typed, unless marked) | Result |107|---|---|108| none | the chain |109| `refresh` | the chain, every part recommended |110| `Agents` | the agents part |111| `architecture` | the architecture part, whole repo |112| `architecture src/api` | the architecture part, target `src/api` (it exists) |113| `architecture DELEGATED src/api` | the architecture part through its seats, no run gate or mode ask, target `src/api` |114| `architecture is hexagonal` | a NOTE, 'architecture is hexagonal' (the rest is no path) |115| `project uses pnpm 9` | the project part, NOTE 'uses pnpm 9' |116| `code-style` | the code-style part |117| `style guide lives in Confluence` | a NOTE (`style` is no topic word) |118| `../backend provides-to` | the related part, sibling `../backend` |119| `related ../backend` | the related part, sibling `../backend` |120| `the API needs a VPN` | a NOTE for the project part |121| (model-loaded) 'document the architecture of src/api' | the architecture part, target `src/api` - never the related part, never a NOTE |122123`capture-quality`'s `architecture` topic is another skill's word; the two never meet, since a topic is read only124after the command or Skill call that names its skill.125126## 2. One part127128The part runs alone, with its arguments, by its own reference - its run gate, mode ask, steps and field template as129written there:130131- project: read `references/project.md` and follow it.132- related-projects: read `references/related-projects.md` and follow it.133- project-code-style: read `references/project-code-style.md` and follow it.134 - `references/project-code-style-doc-shape.md` - the section format and write mechanics, read before MERGE.135- architecture: read `references/architecture.md` and follow it.136 - `references/architecture-doc-shapes.md` - the map's shape and write protocol, read before AGGREGATE.137 - `references/architecture-hazards.md` - the stack-keyed hazard catalog, read before AGGREGATE.138 - `references/architecture-vocabulary-roles.md` - what the vocabulary step loads, read at AGGREGATE.139 - `references/architecture-report-fields.md` - what each close field means, read at REPORT.140- agents: read `references/agents.md` and follow it.141142Each part's contract file is read in full at its step, never from the part's mention alone. Then the close (section 5).143144## 3. The chain145146Who started the load decides what a run with no topic word does:147148- The user's message is the typed `/capture-awareness` command (no arguments, or `refresh`), or asks in words for the149 whole awareness capture: the chain runs.150- Otherwise the model loaded the skill on a request (a description match). The part is the one the request names,151 matched against the router table's Writes and topic words ('document the architecture' names the architecture part,152 'capture how we build and log in' the project part). When it names none, or more than one, ONE single-select153 question picks the part, the closest first and Recommended. The chain never runs on a description match: five154 captures, three of them with seats, are never what one request asked for.155- On a description match the remaining words are a part's argument only when they name a path that exists or a git156 URL; otherwise there is none. The part's own run gate still applies, because no calling flow started it.157- A calling flow's Skill call (section 4) is none of these: it always names its part, so it reaches the part through158 section 1 step 3 and never the chain.159160The part pick, when a description match names none of the five parts or more than one:161162```ask163Which awareness part should run? The request names none of the five, or more than one.164- '<the part closest to the request's words> (Recommended)' - its Writes or topic words come nearest the request165- '<the next closest part>' - writes <its docs>166- '<the third closest part>' - writes <its docs>167```168169The chain:1701711. Run `node "<caps>" --state`. It reads, never writes, always exits 0, and prints one line per part in the router172 table's order - `absent (no <doc>)`, `unstamped (<doc>)`, `current <branch>@<sha>` or `stale <branch>@<sha> (<why>)`,173 and `agents: run` last. A line ending `(no docs engine)` read each doc by presence alone; one ending174 `(docs engine failed)` kept the stamps and could not read the drift. With `refresh`, read every part as needing a run.1752. Put ONE AskUserQuestion call of at most two questions, each a single-select ask template:176177 ```ask178 Run the awareness capture? <n> of the five parts need it: <part - state, one per part>.179 - 'Run the <n> that need it (Recommended)' - <those parts>; the current ones stay as they are180 - 'Pick the parts' - one more question, part by part181 - 'Run all five' - every part, the current ones refreshed182 ```183184 The recommended set is never empty, since the agents part always runs. The second question, only when dispatch is185 available and a seat part (related-projects, project-code-style, architecture) can run:186187 ```ask188 Run the seat parts through their analyzer seats or in this session?189 - 'Through the seats (Recommended)' - the cheap seats absorb the reads; the reasoning and the write stay here190 - 'In this session' - bounded, no dispatch191 ```192193 With no dispatch every part runs INLINE and the second question is not asked.1943. 'Pick the parts' opens ONE more call of two multi-select questions, grouped by the table's Seats column: 'Which195 docs from this repo?' (agents, project) and 'Which analyses?' (related-projects, project-code-style,196 architecture), each option labelled with its state. Under auto-run the first option of each single-select is197 taken, so the Pick call never opens.1984. The answers are each part's run gate and mode answer, so no part asks either again; a part's content questions (the199 run book's asks, the siblings to add) still come. Run each chosen part by reading its reference and following it,200 in the router table's order, each in the same skill load: the parts are read, not re-invoked.2015. The close (section 5), with one `Skipped:` line naming the parts not run.202203## 4. Callers204205- A calling flow hands `<topic> <DELEGATED|INLINE> <target>`: the mode word right after the topic skips the part's run206 gate and mode ask, and the part inherits the mode.207- A person may type `/capture-awareness <topic>` (init's capture rows print that form) and gets the part's run gate.208209## 5. The close210211### RULE - one script call212213After the last part of any run but a lone code-style one, `node "<caps>" --rule` composes214`.claude/rules/alfred-awareness.md` from the copy target below - one `@` import per awareness doc that exists, the215related doc only once it holds an entry, then the map's pointer line when the map exists - compares it, writes it on216differs, puts back the `notOwned` entry in `watch.json`, and removes the rules it supersedes (`alfred-agent-awareness.md`,217`alfred-project-awareness.md`, `alfred-related-context.md`, the 1.x `baseline-project-capabilities.md`, and the legacy218architecture marker once the map's line is written) once their content is imported. It prints one `size:` line per219imported doc and an `over budget:` line past a cap - the project part's budgets are counted there, never by hand. A220`RULE: FAIL` line is a stack defect: report it as it stands, never hand-write the rule.221222COPY TARGET - the script fills the import slot and the map slot; every `<docs-path>` is the literal docs root:223224```markdown225---226description: Project awareness - generated by /capture-awareness; edit via a re-run, not by hand.227---228229# Project awareness230231Imported below at every session start, from `<docs-path>/awareness/`: what this install carries and how to use it, the project's facts, the run book - follow it before you build, start, log into or hand-check the app - its resources, the related repos and your own notes. If a file's text is not below, Read it before you act on its area.232233<the script's import lines, one per awareness doc>234235<the script's map line, when the map exists>236```237238### REPORT239240One part: its field template, as its reference writes it, then the lines below. The chain: one block per part run,241in table order, each in its part's own field template, then:242243```text244Landed: <git | overlay> - the mode line of `node .claude/hooks/docs.js status`, for each doc this run wrote245Rule: <the script's RULE: line, and its size: lines> | not run - a lone code-style run246Live from: next session - the rule is read at session start, so it does not govern this one247Skipped: <the parts the chain did not run, or none>248```249250Then the agents reference's prose lines, and - when the capture surfaced work a sibling owns - the task card the251related reference describes. No re-paste of any doc - point to the files. The rule ships only where the project252commits `.claude/rules/` (the installers gitignore `.claude/*` but `.claude/AGENTS.md`), so a fresh clone re-runs253this capture.254255## Don't game it256257Every fact in the awareness docs traces to a line the script printed, a file the run read, or the user's own answer: a258gap stays `unknown`, an unreachable sibling stays an UNVERIFIED entry, an unreadable source is reported as259unreadable, and a credential appears only as the place it lives.260261## Old installs262263`/alfred-code:update` moves an older install into this layout: the run book from `project-awareness/` (or264`project-capabilities/`) with its section ids and branch versions, the sibling doc from265`related-projects/RELATED-PROJECTS.md`, the architecture map and its orientation block from `architecture/`, the266inventory rule's body into `AGENTS-AWARENESS.md`, and it writes the rule. When a doc still sits at an old home, name267`/alfred-code:update` in the report rather than moving it by hand.