# Warestack — agent brief

> Source of truth for Claude, Codex, and a future Warestack MCP. Propose a pack. Do not enable anything. Do not invent IDs.

Canonical JSON: https://documentation.warestack.com/catalog.json
How to propose: https://documentation.warestack.com/agents
Human setup: https://documentation.warestack.com/start
Use-case map: https://documentation.warestack.com/use-cases
Worked examples: https://documentation.warestack.com/examples

## Protocol

1. Read `/catalog.json`; its IDs and availability statuses are canonical.
2. Inspect the organization’s own GitHub, Linear, and Slack evidence for the last 14 days.
3. Separate a Warestack association from a ticket string and a human approval from a bot review.
4. Map observations to existing rule, chain-kind, and report-intent IDs only.
5. Label every recommendation `week_one`, `on`, `off`, `later`, `candidate_only`, `not_generally_available`, or `unknown`.
6. Cite concrete repository/PR examples. If evidence is missing, write `unknown`.
7. Propose only. Stop before creating, enabling, inviting, messaging, assigning, or changing branch protection.

Availability:

- `available`: shipped surface or authorable template.
- `week_one`: recommended for the bounded first enablement.
- `later`: shipped, but left off first enablement.
- `candidate_only`: name eligible people; each person opts in.
- `not_generally_available`: not a self-serve control yet.
- `unknown`: readiness or evidence cannot be established.

## Product

Warestack runs change management inside GitHub, Linear, and Slack while work happens. It connects ticket, pull request, human review, checks, follow-up, and production deployment into an evidence trail. Vanta remains the GRC system of record. Warestack does not attest SOC 2.

## ID collision — read this

Do **not** number the recommended first-enablement rules 1–8. Catalog rule **1** is “Require concise pull requests.” A Linear issue in Warestack’s store is `custom.linear_issue_required`, which tightens catalog **6**.

Week-one rule IDs:

- `custom.linear_issue_required`
- **7**
- **8**
- **12**
- `custom.conventions`
- `custom.feature_test_evidence`
- **13**
- `custom.evidence_in_approval_body`

Week-one chain-kind IDs:

- `pull_request_slack_live_card`
- `pull_request_review_sla` after Slack identity readiness
- `scheduled_report`
- `production_rollout_changelog` on the deploy-producing repository

`personal_digest` is `candidate_only`; it is hidden from admin create/list and only the member can enable it.

Merge-blocking stays **off**. A failing Warestack Rules check is not a proven merge gate until GitHub branch protection requires it.

## Shipped operating surfaces

- `/overview`: Needs attention, with For me and For the space. Customize owns source preferences and personal digest.
- `/events`: space activity, attention filtering, event detail, timeline, and rule findings.
- `/events/stacks`: GitHub-native or Warestack-detected pull-request stacks; same repository only.
- `/rules`: findings on pull-request evidence and head SHA; merge-blocking is explicit.
- `/chains`: opinionated When → Then automation authoring.
- `/chains/dry-run`: supported historical PR/review/rule replay with no side effects. Required for current definitions that write to GitHub.
- `/chains/activity`: real executions, steps, target delivery, skipped/failed status, and terminal outcome.
- `/slack`: one live card per PR, updated in place; Request Update replies in its thread.
- `/linear`: stored PR association plus an optional mention-only workspace agent.
- `/reports`: natural-language prompt to reviewable SQL, preview, save, Run now history, CSV.
- `/metrics`: analytics and Overview movement with units/direction where evidence exists.
- `/people`: members, identities, access requests, invitations, and roles.
- `/repositories`: monitored repositories, individual owners, and branch-protection visibility.

## Inspect the last 14 days

- Open and merged PRs in production-path repositories.
- Linear association in Warestack’s store versus string-only evidence versus none.
- Issue assignee and confirmed active workflow states.
- PR title/body/branch/commit shape; tests and concrete Testing evidence.
- Requested reviewers, submitted reviews, actor type, and approval-body evidence.
- CODEOWNERS/GitHub teams versus who actually reviewed.
- Slack channels that already receive deploy or review noise.
- GitHub deployments: environment, success/failure, SHA, associated PRs.
- Default-branch workflow failures and waiting deployment reviews.
- Same-repository PR stacks and blocked layers.
- Repository pairs that often move together, labelled `not_generally_available`.
- People with plausible GitHub↔Slack identity for DMs or candidate digest.

Prefer one or two production repositories. Put extras in `later`.

## Observation → proposal

- No Linear association, or only a key in branch/title/body/`Refs:` → `custom.linear_issue_required`, **7**, **8**, **12**.
- `feat/` or `refactor/` below two human approvals → **13**, `custom.evidence_in_approval_body`.
- LGTM/“tested” approval body with no named result → `custom.evidence_in_approval_body`.
- `feat/` source changes with neither tests nor a concrete reason → `custom.feature_test_evidence`.
- Branch, PR, body, or commit trail misses the agreed shape → `custom.conventions`.
- Requested review waits without a human review → `pull_request_review_sla`; require an individual owner and confirmed identities.
- One stable PR channel already exists → `pull_request_slack_live_card`.
- Successful production/`prod` deployments exist → `production_rollout_changelog` on the repo that emits them.
- Weekly sampling is needed → `scheduled_report` plus one report-intent ID.
- A person already uses Slack but misses GitHub attention → `personal_digest` as `candidate_only`.
- One team clearly owns several in-scope repos → team scope; keep one individual owner per repo.
- Repositories must remain isolated → repository scope.
- API/frontend or schema/migrations repeatedly move together → named repository IDs as `not_generally_available`, not a cross-repository stack.
- A same-repository branch chain exists → use `/events/stacks`; every layer is governed separately.
- A GitHub-writing chain needs proof before enablement → use `/chains/dry-run`.
- Delivery success or failure is disputed → use `/chains/activity`.
- Huge PRs, mixed commits, review routing/fatigue, stale PRs, failed main workflows, or bot-only approval → relevant catalog rule or later chain kind.

## Rule catalog

- **1** Require concise pull requests — size routinely stalls review.
- **2** Require atomic commits — tune a lines-per-commit threshold and exclusions.
- **3** Route review requests based on branch prefixes.
- **4** Route review requests based on file paths.
- **5** Detect review fatigue.
- **6** Require a linked ticket — any stored provider; the recommended Linear-first set uses the Linear-only custom rule.
- **7** Require linked ticket to be assigned.
- **8** Require active linked ticket — ask which workflow states are active.
- **9** Require timely acknowledgment of review requests — finding, not a Slack DM.
- **10** Require timely updates for draft pull requests.
- **11** Require timely acknowledgment of high-priority linked tickets.
- **12** Detect pull-request scope drift.
- **13** Require approvals by branch prefix — bots and author do not count.

Custom IDs:

- `custom.linear_issue_required`: requires a Linear association in Warestack’s store.
- `custom.conventions`: `<type>/<linear-issue>-<imperative-description>`, Conventional Commit title, summary/bullets/Testing/`Refs:`, matching commit trail.
- `custom.feature_test_evidence`: relevant tests or a concrete Testing reason; generic “N/A” and “not tested” fail; no fake coverage percentage.
- `custom.evidence_in_approval_body`: approval names the reviewed evidence/result.

## Chain-kind catalog

Recommended first enablement:

- `pull_request_slack_live_card`: selected PR events → one Slack live card; optional 12-hour no-review reminder.
- `pull_request_review_sla`: `review_requested` → requested reviewer DM at 4 hours, individual owner DM at 24 hours by default.
- `production_rollout_changelog`: successful production deployment → wait up to 300 seconds for PR association, then announce PRs or preserve the unassociated commit.
- `scheduled_report`: calendar → run saved report → announce summary/CSV. Report Run now does not announce.

Self-serve:

- `personal_digest`: private Overview › Needs attention › For me snapshot. Empty run skips; last seven final runs; at most two delivery attempts with one retry around ten minutes later.

Available but `later`:

- `urgent_pr_needs_reviewer`
- `reviewer_at_capacity`
- `breaking_schema_change`
- `cicd_change_without_owner_review`
- `rule_fired_act`
- `stale_pull_request`
- `deployment_review_waiting`
- `failed_workflow_default_branch`
- `large_pr_without_tests`
- `issue_live_card`
- `deployment_review_live_card`
- `review_feedback_follow_up`
- `bot_approval_needs_human`
- `repository_without_owner`

`from_scratch` appears separately after the opinionated templates. Prefer a named kind; use scratch only when no named kind fits.

Review defaults before enablement: `urgent_pr_needs_reviewer`, `breaking_schema_change`, and `cicd_change_without_owner_review` include `block_merge`; `rule_fired_act` includes `fail_check`. `breaking_schema_change` evaluates one repository; cross-repository enforcement is `not_generally_available`.

## Report-intent IDs

- `report.failed_workflow_runs_7d`
- `report.merged_prs_open_findings`
- `report.prs_missing_linear`
- `report.reviews_waiting`
- `report.sla_breaches`
- `report.repos_missing_owner`
- `report.failed_production_deploys`

Report evidence is the saved SQL, rows, timestamps, run history, and CSV. Delivery is always a `scheduled_report` chain.

## Scope and identity

Scope types: `repository`, `team`, `path`, `space`.

- Repository is the recommended first-enablement default.
- Team is useful when one engineering team clearly owns multiple in-scope repos.
- Path is a changed-file boundary inside authorized repositories and only for compatible conditions.
- Space is for genuinely space-owned objects such as saved report schedules.
- Repository owner is an individual person, not a team.
- A connected Slack workspace does not prove a person binding. Unconfirmed DM readiness is `unknown`.

## Hard limits

- Ticket strings are not stored associations.
- A Linear parent does not cover child issues or sibling PRs. Associate each PR with the issue that describes its diff.
- Bots and the PR author are not human approvals.
- A Slack reminder is not proof of GitHub review.
- Personal digest is owner-only. An admin cannot create or inspect another member’s digest.
- Production changelog fires on GitHub `deployment_succeeded` in production/`prod`, not merge or a waiting gate.
- Dry-run has no side effects and does not support deployment, workflow, issue, repository-ownership, or schedule replay.
- Enabling a chain does not backfill historical PR notifications.
- Pull-request stacks never span repositories.
- Cross-repository guards are `not_generally_available`.
- Dedicated SOC 2 period export and a complete exception-register UI are `not_generally_available`.
- Linear agent is mention-only and read-only in its default governance turn. When no PR is linked, write `unknown`; do not invent `owner/repo#n`.
- Do not invent a seventh funnel, new card shape, second scheduler, event, ID, owner, channel, ticket, or environment.

## Output

Return:

- `in_scope_repos_or_team`
- `individual_owner_per_repo` with Slack `confirmed` or `unknown`
- `reviewer_pool`
- `rules` with catalog/custom ID, status, reason, and PR evidence
- `chains` with kind ID, status, scope, destination/readiness, reason, and evidence
- `report_intents` with ID, status, schedule/destination, reason, and evidence
- `live_card_channel`
- `digest_and_changelog_channels`
- `personal_digest_candidates`
- `production_environment_name`
- `linear_active_states`
- `cross_repo_pairs` labelled `not_generally_available`
- `readiness_gaps`
- `open_questions`

First reply, exactly three bullets:

1. In-scope repositories.
2. Slack channel for live cards.
3. Individual owner per repository.

## MCP — not shipped

`/catalog.json` is the intended shared payload. Planned names are `warestack.catalog`, `warestack.propose_pack` (no side effects), `warestack.explain_rule`, and `warestack.explain_chain`. These names describe the future interface; do not claim the MCP exists today.