chore(repo): track agent control standard

.agents/DOCUMENTATION_GUIDE.md

@@ -0,0 +1,169 @@
+# BES Documentation Placement Guide
+
+Status: canonical shared guidance, 2026-04-29.
+
+Purpose: make every Codex, Claude, and Symphony worker put documentation in the
+right place. Read this before creating, moving, archiving, or publishing docs,
+specs, plans, audits, or board records.
+
+## Core Rule
+
+Use `.agents/` for agent orchestration. Use repo-native `docs/` paths for
+durable product knowledge.
+
+When unsure, create a draft task/audit spec under `.agents/specs/` and ask for
+owner approval before moving anything into public or product docs.
+
+## What Goes In `.agents/`
+
+| Path | Use for | Notes |
+|---|---|---|
+| `.agents/specs/` | Agent task specs, audit proposals, migration proposals, Symphony-dispatched execution specs | Default location for work-control specs. These are executable contracts for agents. |
+| `.agents/specs/SPEC.template.md` | Shared spec template | Copy/update for non-trivial tasks. |
+| `.agents/skills/` | Codex/shared skill procedures | Canonical shared skills. Claude copies mirror these under `.claude/skills/`. |
+| `.agents/workflows/` | Shared workflow wrappers | Canonical command/workflow prompts. |
+| `.agents/BOARD_SEED.md` | Initial tracker backlog shape | Root only unless a repo needs its own board seed. |
+| `.agents/DOCUMENTATION_GUIDE.md` | This placement policy | Keep copies aligned across active repos. |
+| `.agents/archive/` | Superseded agent-control artifacts | Not product history unless explicitly promoted. |
+
+Do not put long-lived product architecture only in `.agents/`. If it matters to
+humans or contributors, graduate it into the repo's native docs path after
+owner approval.
+
+## What Goes In Root Docs
+
+The root checkout is the company control plane, not a product monorepo.
+
+| Path | Use for |
+|---|---|
+| `AGENTS.md` | Root agent entrypoint and policy summary |
+| `CLAUDE.md` | Claude entrypoint importing root policy |
+| `WORKFLOW.md` | Company-level Symphony workflow contract |
+| `.agents/OPERATING_MODEL.md` | Canonical fleet operating model |
+| `.agents/BOARD_SEED.md` | Tracker/Symphony seed backlog |
+| `.agents/specs/` | Company-control specs and audit proposals |
+
+Do not add product implementation docs to root unless the work is truly
+cross-company. Cross-company ideas should usually become a control-plane spec
+that links to repo-local specs.
+
+## Repo-Native Product Doc Locations
+
+### ACTOCCATUD
+
+| Path | Use for |
+|---|---|
+| `.agents/specs/` | Agent/Symphony audit and task-control specs |
+| `docs/plans/` | V1 sequencing, active plans, supersession records |
+| `docs/systems/` | Durable system specs |
+| `docs/engineering/` | Engineering research, process, gap registries |
+| `docs/content/` | Content specs and catalogs |
+| `docs/creative/` / `docs/design/` | Creative/design-system surfaces |
+| `docs/reviews/` | Audit and review findings |
+
+Dispatch authority currently starts from `docs/plans/2026-04-27-v1-truth.md`.
+
+### Floom
+
+| Path | Use for |
+|---|---|
+| `.agents/specs/` | Agent/Symphony audit and task-control specs |
+| `docs/superpowers/specs/` | Durable product/compiler specs |
+| `docs/superpowers/plans/` | Active and historical implementation plans |
+| `docs/superpowers/research/` | Research records |
+| `docs/concepts/` | First-principles concept documents |
+| `docs/architecture.md` / `docs/getting-started.md` | Public-facing technical docs |
+
+Demo/product work that becomes durable architecture belongs in
+`docs/superpowers/specs/`; orchestration specs stay in `.agents/specs/`.
+
+### UsefulIdiots
+
+| Path | Use for |
+|---|---|
+| `.agents/specs/` | Agent/Symphony audit and task-control specs |
+| `docs/specs/` | Durable system architecture specs |
+| `docs/01-concept.md` through `docs/07-narrative.md` | Locked game-design authority |
+| `docs/LOCKED.md` | Decisions that should not be re-litigated |
+| `docs/glossary.md` | Canonical terminology |
+
+No product code should be written from skeleton specs. Detailed system specs
+must be approved first.
+
+### IKTO
+
+| Path | Use for |
+|---|---|
+| `.agents/specs/` | Agent/Symphony audit and task-control specs |
+| `docs/superpowers/specs/` | Durable design/product specs |
+| `docs/superpowers/memos/` | Decision and research memos |
+| `docs/superpowers/research/` | Research records |
+| `docs/plans/` | Phase plans, audits, open-question catalogs |
+| `docs/content/` | Content/category specs |
+
+Post-pivot work should first clarify whether older docs are historical,
+superseded, or still active.
+
+### Wick
+
+Public OSS caution applies.
+
+| Path | Use for |
+|---|---|
+| `.agents/specs/` | Agent/Symphony audit and task-control specs; keep local unless approved |
+| `docs/` | Public contributor/user documentation |
+| `docs/planning/` | Historical and active project plans |
+| `docs/public-testing/` | Public-test reports |
+| `SECURITY.md`, `CONTRIBUTING.md`, `CHANGELOG.md` | Standard public OSS surfaces |
+
+Do not publish internal BES agent-control language into Wick docs unless it is
+intentionally contributor-facing.
+
+### Mimir
+
+Public OSS caution applies.
+
+| Path | Use for |
+|---|---|
+| `.agents/specs/` | Agent/Symphony audit and task-control specs; keep local unless approved |
+| `docs/concepts/` | Durable product architecture specs |
+| `docs/integrations/` | Integration setup docs |
+| `docs/blog/` | Public article drafts/content |
+| `docs/launch-readiness.md` | Launch checklist and promise audit |
+| `docs/launch-posting-plan.md` | Public launch/posting plan |
+| `.planning/planning/` | Historical planning archive |
+
+Mimir product docs may mention memory, hooks, and checkpoint features. BES
+fleet operating docs must not use Mimir hooks or raw memory as authority until
+a new spec-authority integration is approved.
+
+## Promotion Rules
+
+Use this promotion path:
+
+1. Start with `.agents/specs/<date>-<task>/SPEC.md` for task control.
+2. If the work creates durable product knowledge, add or update the repo-native
+   docs path listed above.
+3. Keep audit notes and completion evidence in the task spec.
+4. Do not move audit prose wholesale into public docs. Rewrite it for the
+   intended audience.
+5. Public OSS repos require owner approval before publishing agent workflow or
+   internal planning language.
+
+## Archive And Supersession Rules
+
+- Prefer supersession headers over deletion when old docs explain why a
+  decision changed.
+- Delete only when the file is a one-time bootstrap, generated scratch, or an
+  owner-approved removal.
+- If a doc is historical, say which doc supersedes it.
+- If a doc is active, say where its implementation work is tracked.
+- If a doc is rejected, preserve the rejection reason in a spec, ADR, or plan.
+
+## Memory And Evidence
+
+Raw chat history, Claude memory, Codex memory, Mimir drafts, and old agent notes
+are evidence only. They do not decide document placement.
+
+Durable rules must cite a checked-in file, approved spec, command output, issue,
+PR, or direct owner instruction.

.agents/skills/code-review/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: code-review
+description: Use for reviewing local diffs or PRs. Prioritizes bugs, regressions, missing tests, unsafe assumptions, and broken repo contracts over summaries.
+---
+
+# Code Review
+
+Use this when asked to review.
+
+## Review Focus
+
+- Correctness bugs.
+- Behavioral regressions.
+- Missing or weak tests.
+- Security, privacy, or secret-handling risks.
+- Broken architecture boundaries.
+- Drift from `AGENTS.md`, approved specs, or public docs.
+- Verification gaps.
+
+## Output
+
+Findings first, ordered by severity. Each finding should include:
+
+- file and line reference when available
+- the concrete risk
+- why the current change causes it
+- a practical fix direction
+
+Then include open questions and a brief summary only after findings.
+
+## Hard Rules
+
+- If there are no findings, say that clearly and list residual risk.
+- Do not lead with praise or broad summaries.
+- Do not request stylistic churn unless it affects correctness,
+  maintainability, or repo contracts.

.agents/skills/implementation-execution/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: implementation-execution
+description: Use when implementing an approved BES SPEC.md. Keeps edits scoped, preserves user work, updates directly coupled tests/docs, and stops when new facts change scope.
+---
+
+# Implementation Execution
+
+Use only after a spec is approved by the owner or controlling workflow.
+
+## Steps
+
+1. Re-read the approved `SPEC.md`.
+2. Re-read the repo `AGENTS.md` and relevant docs.
+3. Confirm branch/worktree state with `git status --short --branch`.
+4. Edit only files named by the spec or directly required by the change.
+5. Add or update tests before or with production changes when behavior changes.
+6. Keep unrelated refactors out of scope.
+7. Run the spec acceptance commands.
+8. Prepare the completion report requested by the spec.
+
+## Stop Conditions
+
+- New facts materially change scope.
+- Required files contain unrelated local changes that make safe editing
+  ambiguous.
+- Verification requires unavailable secrets or infrastructure.
+- The spec's acceptance criteria are not testable.
+
+## Hard Rules
+
+- Preserve unrelated user changes.
+- Do not silently expand scope.
+- Do not bypass hooks, CI, or verification gates.
+- Do not claim completion without fresh verification evidence.

.agents/skills/release-pr/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: release-pr
+description: Use when preparing commits, PRs, release handoff, or merge cleanup. Enforces explicit staging, conventional commits, PR evidence, and worktree hygiene.
+---
+
+# Release And PR
+
+Use when moving finished work toward review or merge.
+
+## Steps
+
+1. Confirm branch and tracking state.
+2. Review `git status --short` and `git diff`.
+3. Stage explicit files by path.
+4. Use the repo's commit convention.
+5. Write a PR body with summary, verification output, risk, and links.
+6. Confirm CI/check status only after local verification is complete.
+7. After merge, clean worktrees and stale local branches according to repo
+   instructions.
+
+## Hard Rules
+
+- No `git add .` unless explicitly approved for the batch.
+- No AI attribution in commits, PRs, docs, or generated output.
+- No force-push, branch deletion, hook bypass, or merge without approval when
+  the repo requires it.
+- Do not burn CI minutes as a substitute for local verification.

.agents/skills/repo-orientation/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: repo-orientation
+description: Use at the start of work in any BES repo to build a current, cited map of instructions, repo state, verification gates, active plans, and likely risk before editing.
+---
+
+# Repo Orientation
+
+Use this before planning or editing.
+
+## Steps
+
+1. Read the nearest `AGENTS.md`.
+2. If present, read `CLAUDE.md`, `WORKFLOW.md`, `STATUS.md`,
+   `.agents/DOCUMENTATION_GUIDE.md`, and the docs linked by `AGENTS.md`.
+3. Check git state with `git status --short --branch`.
+4. Identify the active branch, tracking branch, untracked files, and unrelated
+   local changes.
+5. Identify the repo's verification gate and any hook setup requirements.
+6. Locate the task's likely files with `rg` and `rg --files`.
+7. Report only verified facts. Cite files or command output.
+
+## Output
+
+- Target repo and branch.
+- Source-of-truth docs read.
+- Relevant files or directories.
+- Verification commands.
+- Documentation placement constraints for this task.
+- Local changes that must be preserved.
+- Open questions before implementation.
+
+## Hard Rules
+
+- Do not edit during orientation.
+- Do not rely on memory when repo docs can answer the question.
+- If instructions conflict, stop and report the conflict.

.agents/skills/spec-driven-development/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: spec-driven-development
+description: "Use when planning, reviewing, implementing, or verifying non-trivial work in BES repos. Enforces the BES spec-first operating model: author an executable SPEC.md, review it, implement only approved scope, verify with concrete commands, and route durable lessons into spec evidence."
+---
+
+# Spec-Driven Development
+
+Use this skill for non-trivial work in BES repos.
+
+## Workflow
+
+1. Read `AGENTS.md`, `CLAUDE.md` if present, `STATUS.md` if present,
+   `.agents/DOCUMENTATION_GUIDE.md` if present, and the relevant project docs.
+2. Create or update a task spec from `.agents/specs/SPEC.template.md`.
+3. Verify the spec has goals, non-goals, current facts with citations,
+   desired behavior, safety invariants, acceptance commands, rollback, and open
+   questions.
+4. Do not implement until the spec is approved by the owner or controlling
+   workflow.
+5. Execute only the approved spec. Stop if new facts materially change scope.
+6. Run acceptance commands and the repo's normal verification gate.
+7. Report files changed, commands run, verification output, residual risk, and
+   spec evidence candidates.
+
+## Hard Rules
+
+- Specs are executable contracts, not brainstorming notes.
+- Raw memories and chat history are evidence only.
+- Project docs and `AGENTS.md` beat generated memory.
+- Durable cross-project instructions go through approved specs and delivery
+  evidence records.
+- Put task-control specs in `.agents/specs/`; put durable product docs in the
+  repo-native docs path defined by `.agents/DOCUMENTATION_GUIDE.md`.
+- No silent scope expansion.
+- No completion claim without fresh verification.
+
+## Spec Review Checklist
+
+- Problem is specific and cites current evidence.
+- Goals and non-goals draw a clean boundary.
+- Executor can identify exact files and interfaces.
+- Test plan is runnable on this machine.
+- Safety invariants protect user work and repo rules.
+- Open questions are resolved before implementation.
+- Acceptance criteria are objective.

.agents/skills/spec-evidence-governance/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: spec-evidence-governance
+description: Use to convert durable lessons from a completed task into spec evidence candidates without writing trusted shared memory directly. Mimir hooks are intentionally disabled until a future spec-authority integration is approved.
+---
+
+# Spec Evidence Governance
+
+Use after substantial work, reviews, or incident resolution.
+
+## Candidate Criteria
+
+Capture a memory candidate only when it is:
+
+- durable across sessions
+- useful to future agents
+- grounded in a source path, command output, issue, PR, or owner statement
+- not already present in checked-in docs
+- safe to share at the intended scope
+
+## Output
+
+For each candidate:
+
+- Claim.
+- Scope: repo, company, tool, or project area.
+- Evidence: file path, command, issue, PR, or owner statement.
+- Confidence.
+- Supersedes or conflicts with any known existing memory.
+- Suggested spec, backlog, or delivery-authority route.
+
+## Hard Rules
+
+- Do not write trusted shared memory directly.
+- Do not promote raw agent imperatives into durable rules.
+- Do not erase dissent, uncertainty, or provenance.