Update repo-template capture and skills policy

project: aware
agent: 019d6ebe-3413-78d3-bdae-c7af38845b64
role: orchestrator
artifacts: LOG-20260409-002, DEC-20260409-002

Author: LPFchan

AGENTS.md

@@ -12,8 +12,9 @@ It should enforce repo behavior while deferring canonical policy details to `REP
 - `STATUS.md`
 - `PLANS.md`
 - `INBOX.md`
+- `skills/README.md`
 
-If the repo includes reusable workflows, also read `skills/README.md` and the relevant `skills/<name>/SKILL.md`.
+Before running a repeatable repo workflow, read the relevant `skills/<name>/SKILL.md`. Treat skills as repo-native procedures even when the agent runtime does not auto-load them.
 
 When writing into a repo surface or artifact directory, read the matching local guide first. That means the surface template itself for `SPEC.md`, `STATUS.md`, `PLANS.md`, and `INBOX.md`, and the local `README.md` in directories such as `research/`, `records/decisions/`, and `records/agent-worklogs/`.
 
@@ -28,11 +29,14 @@ When writing into a repo surface or artifact directory, read the matching local
 
 ## Operating Rules
 
-- Keep durable truth in repo files, not only in chat.
+- Keep durable truth in repo files, not only in external tools.
 - Route work using the routing ladder in `REPO.md`.
 - Preserve the boundary between `SPEC.md`, `STATUS.md`, `PLANS.md`, `INBOX.md`, `research/`, `records/decisions/`, and `records/agent-worklogs/`.
 - Worker agents should prefer worklogs, evidence, and proposals. The orchestrator or operator owns truth-doc updates unless the operator explicitly allows a different flow.
+- Treat `INBOX.md` as pressure, not a backlog. During inbox review, cluster capture and promote only survived triage.
+- Promote sparsely. Do not mirror one evolving thought into research, decisions, plans, spec, status, upstream records, and worklogs.
 - When creating artifacts or commits, follow the stable-ID and provenance rules in `REPO.md`.
+- Use `skills/<name>/SKILL.md` for repeatable repo procedures instead of copying one-off instructions into repo-wide policy.
 - Prefer appending to the current relevant `LOG-*` instead of creating a new one unless the work is materially distinct or reuse would harm clarity.
 - When hooks or CI are enabled, normal commits must satisfy the provenance checks; bootstrap or migration exceptions must be explicit exceptions only.
 - Prefer the local surface template or directory `README.md` shape over ad hoc formatting when it defines one.
@@ -42,6 +46,15 @@ When writing into a repo surface or artifact directory, read the matching local
 When you write or update repo artifacts, adherence to the repo's ruleset is required.
 
 - Do not invent a new document shape when the repo already provides a canonical surface, directory `README.md`, or explicit template.
-- Do not collapse truth, plans, decisions, research, inbox intake, and worklogs into one mixed artifact.
-- Do not replace normalized repo artifacts with freeform chat summaries.
+- Do not collapse truth, plans, decisions, research, inbox capture, and worklogs into one mixed artifact.
+- Do not promote exploratory debate into `SPEC.md`, `STATUS.md`, `PLANS.md`, or `records/decisions/` until there is a concise accepted outcome for that layer.
+- Do not turn an inbox review into a giant digest of every low-confidence idea. Report counts or clusters when full detail does not protect focus.
 - If an artifact needs a justified local variation, keep the core fields and section order intact and make the smallest possible deviation.
+
+## Skills
+
+`skills/<name>/SKILL.md` files are reusable procedures for bounded workflows.
+
+- Keep them procedural.
+- Do not duplicate canonical repo policy inside them.
+- Use them to standardize repeatable tasks, escalation triggers, and output shape.

AWARE-AGENT-PROMPT.md

@@ -8,8 +8,9 @@ Use this file as a pointer, not as the canonical product spec.
 - `SPEC.md` holds durable product truth.
 - `STATUS.md` holds current operational reality.
 - `PLANS.md` holds accepted future direction only.
-- `INBOX.md` is the scratch surface for untriaged intake.
+- `INBOX.md` is the scratch surface for untriaged capture.
 - `records/decisions/` and `records/agent-worklogs/` store durable decisions and execution history.
+- `skills/README.md` and `skills/<name>/SKILL.md` store required repo-native procedures.
 
 ## Working Rules
 

INBOX.md

@@ -1,17 +1,23 @@
 # Aware Inbox
 
-This file is an ephemeral scratch disk for intake waiting to be triaged.
+This file is an ephemeral scratch disk for capture waiting to be triaged.
 
 Rules:
 
-- Keep it easy to append to from messenger, operator notes, or agent capture.
+- Keep it easy to append to from external capture, operator notes, or agent capture.
+- Use it as a pressure valve for untriaged capture, not as a backlog or brainstorm graveyard.
+- Group related raw source events into one meaningful inbox entry when possible.
+- Triage meaningful capture packets or clusters, not every raw source event and not an entire external history.
+- During daily review, route, research, plan, discard, or leave capture; do not produce a giant project digest.
+- It is okay to report counts or clusters of held, noisy, stale, or discarded items without summarizing every item.
+- Do not update truth docs directly from inbox. Route through the orchestrator or an operator-approved decision.
 - Remove entries once they are reflected into durable repo artifacts.
 - Keep the stable `IBX-*` id even after the inbox entry itself is later deleted.
 - Do not treat this file as durable truth.
 
-## Active Intake
+## Active Capture
 
-No active intake items are currently recorded.
+No active capture items are currently recorded.
 
 When the next item arrives, use this default shape:
 
@@ -20,13 +26,32 @@ When the next item arrives, use this default shape:
 - Opened: `YYYY-MM-DD HH-mm-ss KST`
 - Recorded by agent:
 - Source:
+- Source / capture ids:
+- Capture packet:
 - Received:
 - Summary:
-- Triage status: `new` | `in review` | `reflected` | `dropped`
+- Confidence: `low` | `medium` | `high`
+- Triage status: `new` | `held` | `in review` | `reflected` | `dropped`
+- Triage decision: `route` | `research` | `plan` | `discard` | `leave`
 - Suggested destination:
 - Related ids:
 - Notes:
 
+## Daily Pressure Review Scratch
+
+Use this section during a daily IBX review, then clear it after entries are routed, held, discarded, or escalated.
+
+- Review date:
+- Reviewer:
+- Inbox pressure summary:
+- Clusters reviewed:
+- Promotion candidates:
+- Research candidates:
+- Plan candidates:
+- Discard or purge candidates:
+- Held without full summary:
+- Operator route questions:
+
 ## Purge Rule
 
-Once an item has been reflected into `SPEC.md`, `STATUS.md`, `PLANS.md`, `research/`, `records/decisions/`, `records/agent-worklogs/`, or a future `upstream-intake/` module if the repo later adds one, remove the inbox entry.
+Once an item has been reflected into `SPEC.md`, `STATUS.md`, `PLANS.md`, `research/`, `records/decisions/`, `records/agent-worklogs/`, a future `upstream-intake/` module if the repo later adds one, or a deliberate discard/hold note, remove the inbox entry.

REPO.md

@@ -18,6 +18,7 @@ The goal is simple:
 - Project id: `aware`
 - Canonical user-facing docs remain in `README.md`, `docs/`, and `release-notes/`.
 - Canonical repo-operating docs live in `SPEC.md`, `STATUS.md`, `PLANS.md`, `INBOX.md`, `research/`, `records/decisions/`, and `records/agent-worklogs/`.
+- Canonical repo procedures live in `skills/`.
 - `AGENTS.md` is the canonical editable agent-instructions entrypoint for tools that require one.
 - `CLAUDE.md` is a thin compatibility shim that points to `AGENTS.md`.
 - `AWARE-AGENT-PROMPT.md` is a legacy bootstrap pointer, not a second policy layer.
@@ -32,10 +33,36 @@ Every repo using this system should separate these surfaces:
 | `SPEC.md` | Durable statement of what the project is supposed to be. | rewritten |
 | `STATUS.md` | What is true right now operationally. | rewritten |
 | `PLANS.md` | Accepted future direction that is not current truth yet. | rewritten |
-| `INBOX.md` | Ephemeral intake waiting for triage. | append then purge |
+| `INBOX.md` | Ephemeral capture waiting for triage. | append then purge |
 | `research/` | Curated research memos worth keeping. | append by new file |
 | `records/decisions/` | Durable decision records with rationale. | append-only by new file |
 | `records/agent-worklogs/` | Execution history for runs, agents, and subagents. | append-only |
+| `skills/` | Required procedural workflows for repeatable agent tasks. | edit by skill |
+
+## Agent Compatibility Files
+
+Some coding agents look for repo-root instruction files such as `AGENTS.md` or `CLAUDE.md`.
+
+When a repo using this model includes them:
+
+- they should act as entrypoints into the canonical rules, not competing policy documents
+- they should stay short enough that they do not drift from `REPO.md`
+- `AGENTS.md` should be the main editable agent-instructions file when both files exist
+- `CLAUDE.md` should be a thin shim that points to `AGENTS.md` when the tool supports it
+- `SKILL.md` stays separate because it defines a bounded reusable procedure, not repo-wide policy
+- `skills/` should ship with adopted repos as repo-native procedural documentation, even when the agent runtime does not auto-load skills
+- optional repo subsystems may have optional companion skills
+
+Recommended split:
+
+- `REPO.md`
+  - canonical rules
+- `AGENTS.md`
+  - canonical editable agent-instructions file
+- `CLAUDE.md`
+  - Claude Code shim that points to `AGENTS.md`
+- `skills/<name>/SKILL.md`
+  - procedure for one repeatable workflow
 
 ## Separation Rules
 
@@ -71,12 +98,13 @@ The orchestrator owns synthesis and routing.
 It may:
 
 - triage inbox items
+- run daily inbox pressure reviews
 - classify work into the right artifact layer
 - update `SPEC.md`, `STATUS.md`, and `PLANS.md`
 - create research memos
 - create decision records
 - append to the current relevant worklog or create a new one when the work is materially distinct
-- translate messenger intake into repo artifacts
+- translate external capture into repo artifacts
 - escalate non-obvious product, architecture, workflow, or policy calls
 
 ### Worker Agents
@@ -91,24 +119,96 @@ They may:
 
 They should not update `SPEC.md`, `STATUS.md`, or `PLANS.md` directly unless the operator explicitly allows that flow.
 
-### Messenger Surfaces
+### External Capture Surfaces
 
-Messenger surfaces are intake and control channels.
+External capture surfaces are capture and control channels.
 
 They may:
 
-- create or append inbox intake
+- create or append inbox capture
 - request approvals
 - deliver summaries
 - surface blocked states
 
 They must not write truth docs directly.
 
+### Capture Packets
+
+Raw external source events are immutable Off-Git events.
+Do not treat every raw source event as a separate repo artifact.
+Do not treat a full external-tool history as one giant inbox item.
+
+Use capture packets as mutable working envelopes around one or more relevant raw source events.
+
+A capture packet may be:
+
+- appended as new related source events arrive
+- edited into a clearer operator-intent summary
+- split when it contains multiple independent asks
+- merged when several source events are one meaningful thread
+- summarized into `INBOX.md` as an `IBX-*`
+- routed into durable repo artifacts after triage
+
+Triage should happen per meaningful capture packet.
+Routed repo artifacts should copy a short summary, the stable inbox ID, and any needed external provenance handle instead of relying on raw external source staying visible.
+
+## Inbox Pressure Review
+
+`INBOX.md` is an ephemeral scratch disk for untriaged capture.
+It is not a backlog, roadmap, brainstorm archive, or project digest.
+
+Run a daily inbox pressure review when the project receives substantial capture.
+This review is focus-protecting triage.
+It is not an unconditional digest of every random idea.
+
+During the review:
+
+- group related `IBX-*` entries and capture packets into meaningful clusters
+- identify stale, duplicate, low-confidence, noisy, or "maybe later" capture
+- ask whether each meaningful cluster should route, research, plan, discard, or stay held
+- promote only items that survived triage and have an accepted destination
+- report counts or clusters of held, discarded, stale, or noisy capture instead of summarizing every low-signal item
+- preserve `IBX-*` as a permanent provenance ID even if the inbox line is deleted
+
+Do not update `SPEC.md`, `STATUS.md`, `PLANS.md`, `research/`, or `records/decisions/` directly from raw inbox pressure.
+The orchestrator or operator-approved routing step owns promotion.
+
+## Promotion Discipline
+
+Promotion should be sparse.
+Do not mirror one evolving thought into every repo surface.
+
+Raw shaping may stay in external capture, generic notes, off-Git capture packets, or `INBOX.md` while the thought is still forming.
+Repo artifacts are a refinery: each layer should receive only the part that belongs there, when it is ready.
+
+Use each layer for its distinct job:
+
+- `INBOX.md`
+  - ephemeral routed capture
+- `research/`
+  - reusable exploration, evidence, framing, rejected paths, and open questions
+- `records/decisions/`
+  - meaningful accepted choices and why the winning choice won
+- `PLANS.md`
+  - accepted future work that survived triage
+- `SPEC.md`
+  - concise durable product or system truth after the argument is settled
+- `STATUS.md`
+  - current operational reality
+- `records/agent-worklogs/`
+  - execution history, not truth, decision, plan, or research mirrors
+
+A research memo may remain research forever.
+A decision record should exist only when a real product, architecture, workflow, trust, upstream, or repo-operating choice has been made.
+`SPEC.md`, `STATUS.md`, and `PLANS.md` should receive concise outcomes, not copied debate.
+
+One task may touch multiple layers, but each touched layer must have its own distinct job.
+
 ## Orchestrator Routing Ladder
 
 When new work arrives, the orchestrator should classify it in this order:
 
-1. Is this untriaged intake?
+1. Is this untriaged capture?
    - Route to `INBOX.md`.
 2. Is this durable truth about what the project is?
    - Route to `SPEC.md`.
@@ -129,10 +229,14 @@ One task may legitimately touch multiple layers. For example:
 - a product choice can create `DEC-*` and update `PLANS.md`
 - implementation progress can append to an existing relevant `LOG-*` and update `STATUS.md`
 
+Touch multiple layers only when each layer receives distinct information.
+Do not copy the same evolving thought into research, decision, plan, spec, status, upstream, and log surfaces.
+
 ## Write Rules
 
 - `SPEC.md`, `STATUS.md`, and `PLANS.md` should be updated only by the operator or orchestrator.
-- `INBOX.md` is an aggressive scratch disk. Purge entries once they are reflected elsewhere.
+- `INBOX.md` is an aggressive scratch disk. Purge entries once they are reflected elsewhere or explicitly discarded.
+- Daily inbox review should reduce pressure by clustering, routing, holding, or purging capture; it should not generate a larger digest by default.
 - `research/` keeps curated findings only.
 - `records/decisions/` is append-only by new decision file.
 - `records/agent-worklogs/` is append-only by appended entries or, when clarity requires it, a new log file.
@@ -228,11 +332,15 @@ The Off-Git runtime should answer:
 
 - which conversation or run the `agent-id` maps to
 - whether the agent was top-level or a subagent
-- which messages or events produced the artifact
+- which source events produced the artifact
 - which commits belong to that `agent-id`
 
 ## Scaffold Rule
 
 This repo uses the repo-template skeleton as a canonical layout, not a loose grab-bag of snippets.
 
 Keep the operating surfaces recognizable so future operators and agents can recover context quickly.
+
+In repo-template source, scaffold files live under `scaffold/`.
+After adoption, the scaffold contents belong at the target repo root.
+For example, `scaffold/skills/repo-orchestrator/SKILL.md` becomes `skills/repo-orchestrator/SKILL.md` in the adopted repo.

records/agent-worklogs/LOG-20260409-002-normalize-repo-template-docs.md

@@ -61,3 +61,21 @@ Introduce repo-root `AGENTS.md` and `CLAUDE.md`, then normalize the touched repo
 - Output: replaced the generic spec outline with an Aware-native durable spec, preserved current accepted facts from the source tree, restored durable privacy/capture/detection contracts from the pre-adoption README and agent prompt where still current, and relaxed `research/README.md` to the current memo-oriented guidance because this repo has no `RSH-*` memos yet
 - Blockers: none
 - Next: hand off the reconciled docs and call out old-source facts that were intentionally not restored because they conflict with current runtime
+
+## Entry 2026-04-09 20-23-25 KST
+
+- Action: adopted repo-template's sparse promotion discipline and capture packet vocabulary in Aware's live operating-policy surfaces
+- Files touched: `REPO.md`, `AGENTS.md`, `INBOX.md`, `AWARE-AGENT-PROMPT.md`, `skills/repo-orchestrator/SKILL.md`, `records/agent-worklogs/LOG-20260409-002-normalize-repo-template-docs.md`
+- Checks run: live-policy `rg` scans for old `messenger`, `chat`, `raw message`, `intake span`, and `Active Intake` vocabulary; live-policy `rg` scan for new capture / capture packet / promotion discipline vocabulary; `git diff --check`; targeted verbatim-block check for imported repo-template text
+- Output: replaced live generic intake/messenger/chat wording with current capture vocabulary, added capture-packet, inbox-pressure, and sparse-promotion policy, aligned the inbox skeleton's generic labels, and kept `upstream-intake/` omitted because Aware still has no upstream-review module
+- Blockers: none
+- Next: summarize the targeted policy adoption, preserved local adaptations, and checks run
+
+## Entry 2026-04-09 20-35-32 KST
+
+- Action: migrated Aware to repo-template's mandatory repo-native skills layer
+- Files touched: `REPO.md`, `AGENTS.md`, `AWARE-AGENT-PROMPT.md`, `skills/README.md`, `skills/daily-inbox-pressure-review/SKILL.md`, `records/agent-worklogs/LOG-20260409-002-normalize-repo-template-docs.md`
+- Checks run: root-skill Markdown link validation, stale optional-skills wording scan, `test ! -e scaffold`, root `skills/` inventory
+- Output: kept `skills/` at the adopted repo root, made `skills/README.md`, `skills/repo-orchestrator/SKILL.md`, and `skills/daily-inbox-pressure-review/SKILL.md` the required baseline, documented skills as repo-native procedures, and continued omitting `skills/upstream-intake/` because Aware does not use `upstream-intake/`
+- Blockers: none
+- Next: run final link, stale wording, vocabulary, and diff hygiene checks

skills/README.md

@@ -1,17 +1,37 @@
 # Skills
 
-This directory is optional.
+This directory is part of Aware's repo-template operating layer.
 
-Use it when the environment supports reusable procedural skills or workflows.
+Use it as repo-native procedural documentation.
+Agents should read the relevant workflow even when their runtime does not auto-load skills.
 
-## What Lives Here
+Each reusable workflow should live at `skills/<name>/SKILL.md`.
+
+## Required Baseline Skills
 
 - `repo-orchestrator/`
   - Routes work into `SPEC.md`, `STATUS.md`, `PLANS.md`, `INBOX.md`, `research/`, `records/decisions/`, and `records/agent-worklogs/`.
+- `daily-inbox-pressure-review/`
+  - Focus-protecting daily triage for `IBX-*` capture and capture packets.
 
-## Omitted For Now
+## Conditional Skills
 
-- `upstream-intake/` is not included because Aware is not currently using the optional upstream-review module.
+- `upstream-intake/`
+  - Companion workflow for the optional upstream-review module.
+  - Omitted because Aware is not currently using the optional upstream-review module.
 
 Keep skills procedural.
 Do not duplicate the canonical rules from `REPO.md` inside them.
+
+Use `SKILL.md` for:
+
+- step-by-step procedures
+- required inputs and expected outputs
+- escalation triggers
+- links to supporting templates or reference docs
+
+Do not use `SKILL.md` for:
+
+- repo-wide policy
+- general project truth
+- local or personal preferences that belong in tool-specific memory files