跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
搜索与研究

ai-agents-docs-of-record

Runbook for this repo's documents of record. Session logs, ADRs, retrospectives, Serena memories, per-issue handoffs, plus the templates, validators, naming rules, and house prose style that bind them. Use when you say `write the session log`, `create an ADR`, `fill the retro`, `save this to memory`, `which document of record`. Do NOT use for authoring skills (use `SkillForge`) or research write-ups (use `ai-agents-research-methodology`).

rjmurillo · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add rjmurillo/ai-agents --skill ai-agents-docs-of-record

技能说明


name: ai-agents-docs-of-record version: 1.0.0 license: MIT description: Runbook for this repo's documents of record. Session logs, ADRs, retrospectives, Serena memories, per-issue handoffs, plus the templates, validators, naming rules, and house prose style that bind them. Use when you say write the session log, create an ADR, fill the retro, save this to memory, which document of record. Do NOT use for authoring skills (use SkillForge) or research write-ups (use ai-agents-research-methodology). metadata: routing: role: conditional-adjunct invoker: ai-agents-research-methodology trigger: ai-agents-research-methodology routes write-ups through the documents of record user-facing: false

ai-agents-docs-of-record

This repo runs on verification-based governance. Continuity lives in per-issue handoffs and Serena memory. Session log creation is discontinued; transcript and pull request evidence remain valid, and the ~1,500 historical logs under .project-toolkit/sessions/ stay in the repo as history.

Triggers

  • write the session log
  • create an ADR
  • fill the retro
  • save this to memory
  • which document of record does this go in

The Record System Map

RecordLocationCreate withValidated by
Session log (historical only, creation discontinued).project-toolkit/sessions/YYYY-MM-DD-session-NN[-slug].jsondo not create new onesscripts/validate_session_json.py, validate-if-present via the session-policy pre-commit hook, applies only if one is somehow staged
Per-issue handoff.project-toolkit/sessions/handoffs/{YYYY-MM-DD}-{ISSUE}-handoff.mdcopy .agents/templates/HANDOFF.mdresume-verification checklist at next session start
ADR.project-toolkit/architecture/ADR-NNN-slug.mdadr-generator skillscripts/validation/check_adr_uniqueness.py; adr-review debate gate
Retrospective.project-toolkit/retrospective/retrospective skill on one of the four triggers (HIGH-tier reflect finding, main red, reverted or force-fixed merge, explicit user correction), or /retro fill on a historical skeletonINDEX.md row (auto-appended, incomplete; see Phase 4)
Serena memory.serena/memories/[domain]-[name].mdmemory skill write conventionscurating-memories skill; memory-index routing

Process

Phase 1: Pick the right record

SituationRecordWhy
Issue spans multiple sessionsPer-issue handoffCold-start continuity (Issue #1725: 95.8% protocol failure without file-based gates)
Architectural or irreversible decisionADRFires adr-review multi-agent debate
Incident, failure, or "what went wrong"RetrospectiveFeeds the failure canon; see ai-agents-failure-archaeology
Reusable pattern, correction, gotchaSerena memoryOnly memories are read by future sessions at start
User corrected you mid-sessionreflect skill, then memoryCorrections not persisted are lost
A doc you touched is staleFix on contact (Phase 7)Broken-windows rule

One fact can need two records: an incident gets a retrospective AND a memory distilling the rule. The retro is the evidence; the memory is the searchable lesson.

Phase 2: Session logs (historical only)

Session log creation is discontinued (.claude/rules/session-logs.md MUST 1): do not create a new .project-toolkit/sessions/*.json file. The ~1,500 existing logs stay in the repo as history, schema at .agents/schemas/session-log.schema.json (top-level required: session, protocolCompliance with sessionStart and sessionEnd subsections), and remain readable by retrospective, memory extraction, and the PreCompact hook.

If a historical log is staged anyway (for example, cherry-picked from an older branch), it still needs to pass:

uv run python3 scripts/validate_session_json.py .project-toolkit/sessions/<file>.json

Hard requirements enforced by scripts/validate_session_json.py:

  • Required session fields: number, date, branch, startingCommit, objective.
  • Branch must match ^(feat|fix|docs|chore|refactor|test|ci)/.
  • startingCommit must be a 7-40 char lowercase hex SHA.

Historical naming may carry a slug: 2026-06-30-session-2600-skill-tooling-hygiene-taste-lints-naming.json. Never resolve a session-log merge conflict with git checkout --ours; the settled rule from the session 1187 incident is take --theirs and rename your own log to the next free number (see ai-agents-failure-archaeology).

Phase 3: ADRs

Numbering collides here; treat numbers as claims, not identity. History: concurrent ADR PRs each picked the same "next" number (Issue #2253), and ADR-058/062/063 each existed twice until the duplicates were renumbered to 069/070/071 (Issue #2228, per the docstring of scripts/validation/check_adr_uniqueness.py). ADR-055 and ADR-024 share the slug github-actions-runner-selection (055 supersedes 024). Rule: when citing an ADR, verify the file content says what you claim, not just the number.

python3 scripts/validation/check_adr_uniqueness.py --print-next

Workflow:

  1. Search first: memory-search for prior decisions, then read neighbors in .project-toolkit/architecture/ (ADR-007 memory-first: retrieval precedes reasoning).
  2. Generate with adr-generator against .project-toolkit/architecture/ADR-TEMPLATE.md.
  3. Claim the number from --print-next at the last moment before commit.
  4. Expect the gate: any ADR-*.md create or edit fires the adr-review multi-agent debate (AGENTS.md, "ADR Review"). Governance-level changes additionally need human appr
阅读完整来源 ↗