make-guidelines

Skill: make-guidelines

Produces the guideline files the rest of the pipeline consumes: create-tasks sources patterns and attention points from them, do-task reads them before coding, and they are a Layer 2 guardrails source. Respond in the conversation language (docs/agents/language.md; unset → the user's language).

Load before acting: ${CLAUDE_PLUGIN_ROOT}/shared/sparring.md, ${CLAUDE_PLUGIN_ROOT}/shared/workflow-context.md, and ${CLAUDE_PLUGIN_ROOT}/shared/guardrails.md — this skill authors Layer 2 content; the trust rule applies (guidelines can only tighten, never weaken Layer 1).

Step 0 — Scope

• No argument → codebase guideline: GUIDELINES.md at the repo root.
• Path argument → module guideline: <path>/GUIDELINES.md (the module = that folder subtree). Multiple modules → one run each.
• Target file already exists → review mode: load it, show current rules, only interview the gaps and the changes — never overwrite silently, always show the diff before writing.

Step 1 — Detect before asking

The codebase is evidence — existing patterns are de-facto guidelines. Scan the scope for:

• linter/formatter configs
• error-handling shape (custom error types? result objects? bare throws?)
• the logger in use and its levels
• test conventions (naming, structure, coverage gates)
• IaC layout and tool
• feature-flag SDKs
• architecture shape (layers, module boundaries, dependency direction)
• latency/metric instrumentation already present

Each detection becomes a proposed answer, not a question from zero.

Step 2 — Interview (sparring loop)

One question per exchange (sparring.md mechanics: suggested answer first, marked "(Recommended)" — detected patterns are the suggestion). Minimum topic checklist (interview every item; skip only on explicit user declaration):

1. Code style — beyond the linter: naming, comment policy, file layout.
2. Architecture style — layers, module boundaries, dependency direction.
3. Best practices — the project's "always / never" list.
4. Infra provisioning — IaC tool, where it lives, review rules.
5. Logging — logger, levels, what always gets logged, PII rules.
6. Error handling — throw vs result, custom error types, what the failure path looks like.
7. Observability instrumentation — convention rules only (event naming, what always gets instrumented): the stack (platform + logger) is owned by workflow-context.md § Observability and lives in docs/agents/observability.md — this theme adds conventions on top and never contradicts the resolved stack.
8. Feature flags — SDK, naming, cleanup policy.
9. Latency metrics — what gets timed, budgets, percentiles.
10. Fail-safe vs fail-fast — which subsystems degrade gracefully, which must abort loudly; retries, timeouts, idempotency conventions.
11. Approved libraries & dependency policy — preferred and forbidden libs per concern (dates, forms, icons, HTTP…), when adding a new dependency is acceptable. Consumed by do-task (what to reach for) and watch-pr (review replies cite the rule).
12. Data & migrations — schema-change policy: additive-first, rollback plans, whether migrations ship in their own PR. Consumed by create-tasks' split rules and every card's Attention points.
13. Security & sensitive data — what counts as PII in this domain, fields that must never be logged, secret management, auth patterns. Consumed by Attention points and chaos severity.
14. Commit / branch / PR conventions — message style, branch naming, PR description shape. Consumed by pr-flow (otherwise inferred from git log every run).
15. Domain criticality — what must never break here, which data is sacred, what "critical severity" means in this business. This anchors chaos-engineering's severity triage — without it, "critical" is an opinion.