[caveman] Optimize instruction verbosity — visual-regression, workflow-constraints, workflow-editing, workflow-patterns, adr-wri [Content truncated due to length]

.github/agents/adr-writer.agent.md

@@ -11,11 +11,10 @@ Expert Architecture Decision Record (ADR) writer. Follow the **Michael Nygard AD
 
 ADRs are permanent records of significant technical decisions: *"Why does the codebase look the way it does?"*
 
-Key principles:
-- **Immutable once accepted** — approved ADRs are never deleted; superseded ones are marked "Superseded by ADR-XXXX"
-- **Decision-focused** — capture the *why*, not just the *what*
-- **Honest about trade-offs** — include real negatives and costs, not just positives
-- **Written for future readers** — someone unfamiliar with the context should understand the decision 12 months later
+- **Immutable once accepted** — never deleted; superseded ones marked "Superseded by ADR-XXXX"
+- **Decision-focused** — capture *why*, not just *what*
+- **Honest about trade-offs** — include real negatives and costs
+- **Written for future readers** — understandable 12 months later
 
 ## Storage Convention
 
@@ -29,13 +28,13 @@ docs/adr/
 ```
 
 **Filename format**: `NNNN-kebab-case-title.md`
-- `NNNN` zero-padded to 4 digits (e.g., `0001`, `0042`, `0100`)
-- Title in lowercase kebab-case, derived from the ADR title
-- No special characters other than hyphens
+- `NNNN` zero-padded 4 digits (e.g., `0001`, `0042`)
+- Lowercase kebab-case title
+- Only hyphens as separators
 
 ## ADR Template
 
-Two-part structure: a **human-friendly narrative** for developers/stakeholders, then a **normative specification** in RFC 2119 language for machine-checkable conformance.
+Two parts: **human-friendly narrative**, then **RFC 2119 normative specification** for machine-checkable conformance.
 
 ```markdown
 # ADR-{NNNN}: {Concise Decision Title}
@@ -125,7 +124,7 @@ An implementation is considered conformant with this ADR if it satisfies all **M
 
 #### Context (3–5 sentences)
 - *What problem? What constraints?* (technical, organizational, timeline)
-- State of codebase at decision time
+- Codebase state at decision time
 - Problem space, not implementation
 
 #### Decision (2–4 sentences)
@@ -135,12 +134,12 @@ An implementation is considered conformant with this ADR if it satisfies all **M
 
 #### Alternatives Considered (2–4 sentences each)
 - **≥2 genuine alternatives** (no strawmen)
-- For each: what it is, why considered, why rejected
-- If a close call, say so
+- For each: what, why considered, why rejected
+- If close call, say so
 
 #### Consequences
-- **Positive**: real benefits, not marketing
-- **Negative**: real costs and trade-offs — be honest
+- **Positive**: real benefits
+- **Negative**: real costs and trade-offs
 - **Neutral**: side effects worth noting
 - ≥2 per category for non-trivial decisions
 
@@ -243,7 +242,7 @@ For each: what problem? what alternatives? what consequences?
 1. Read the ADR **Decision** — extract commitments
 2. Check code for conformance/deviation
 3. Note **divergences**: code contradicts decision
-4. Note **scope creep**: significant decisions in code the ADR doesn't cover
+4. Note **scope creep**: significant decisions in code not covered
 
 Return:
 - **Aligned**: code implements the ADR
@@ -255,7 +254,7 @@ Return:
 Warrant an ADR:
 - Database, message queue, cache, or storage choice
 - Adopting/replacing a framework
-- Auth/authorization approach change
+- Auth/authz approach change
 - API convention (REST vs GraphQL vs gRPC)
 - Architectural patterns (microservices vs monolith, event-driven vs request-driven)
 - Significant infrastructure (Kubernetes, Terraform)
@@ -266,5 +265,5 @@ Do **not** warrant an ADR:
 - Bug fixes without design trade-offs
 - Minor refactors within existing patterns
 - Documentation updates
-- Dependency version bumps (unless major new dep)
+- Dependency bumps (unless major new dep)
 - Code style/formatting changes

.github/aw/visual-regression.md

@@ -51,15 +51,15 @@ Otherwise compare each screenshot to its baseline. Post a comment summarizing: p
 
 ## Key Design Decisions
 
-- **`cache-memory` key per base branch** — scopes baselines to `main`, `develop`, etc. independently
-- **`allowed_domains: [localhost, 127.0.0.1]`** — prevents SSRF; app must be served locally
-- **`retention-days: 30`** — keeps baselines beyond the default 7-day cache expiry
-- **Filesystem-safe timestamps** — `YYYY-MM-DD-HH-MM-SS` format; colons are invalid in artifact filenames
-- **Minimal permissions** — all PR writes go through `safe-outputs`, not GitHub tools
+- **`cache-memory` key per base branch** — scopes baselines to `main`, `develop`, etc.
+- **`allowed_domains: [localhost, 127.0.0.1]`** — prevents SSRF; serve app locally
+- **`retention-days: 30`** — beyond the default 7-day cache expiry
+- **Filesystem-safe timestamps** — `YYYY-MM-DD-HH-MM-SS`; colons break artifact filenames
+- **Minimal permissions** — all PR writes go through `safe-outputs`
 
 ## Network-Minimization Reminders
 
-- Prefer local preview serving (`localhost`/`127.0.0.1`) over external preview environments when possible.
-- If external previews are required, allowlist only exact preview domains needed for the check (avoid broad wildcards).
-- Enable `network.node` only when the workflow actually installs/builds Node dependencies; scope domains to package registries and required preview hosts.
-- Keep Playwright navigation limited to app-under-test URLs and avoid loading unrelated third-party domains.
+- Prefer local preview (`localhost`/`127.0.0.1`) over external preview environments.
+- If external previews are required, allowlist exact domains (no broad wildcards).
+- Enable `network.node` only when installing/building Node deps; scope to registries and preview hosts.
+- Keep Playwright navigation limited to app-under-test URLs.

.github/aw/workflow-constraints.md

@@ -8,35 +8,33 @@ description: Shared architectural and security constraints for designing or upda
 
 Agentic workflows run as a **single GitHub Actions job** with one agent execution.
 
-## What They Can Do
+## Can Do
 
 - read GitHub data, APIs, web pages, and local repository files
 - run tools inside the single job
 - use MCP servers and safe outputs
 - create GitHub resources through `safe-outputs:`
 - persist lightweight state with `cache-memory` or other approved mechanisms
 
-## What They Cannot Do
+## Cannot Do
 
 - pause and resume for external events
 - orchestrate multi-stage pipelines with job dependencies
 - pass state between multiple AI jobs in one workflow run
 - implement built-in rollback across external systems
 - wait for another workflow or deployment to finish inside the same agent run
 
-## When to Recommend Traditional GitHub Actions Instead
-
-Use traditional Actions when the request needs:
+## Recommend Traditional GitHub Actions When
 
 - multi-stage deployment pipelines
-- fan-out or fan-in job orchestration
+- fan-out/fan-in job orchestration
 - long waits for approvals or external systems
 - rollback logic across several steps or systems
 - cross-job state transfer
 
-Suggested response pattern:
+Suggested response:
 
-> This requires capabilities that agentic workflows do not support in their single-job model. Use traditional GitHub Actions for orchestration and agentic workflows for the AI-specific step.
+> This requires capabilities the single-job agentic model does not support. Use traditional GitHub Actions for orchestration and agentic workflows for the AI-specific step.
 
 ## Security Posture
 
@@ -52,7 +50,7 @@ Suggested response pattern:
 
 When a requested feature increases risk:
 
-1. explain the risk clearly
+1. explain the risk
 2. propose the safer pattern first
 3. require explicit confirmation before relaxing safeguards
 
@@ -81,4 +79,4 @@ For the full set of requirements (Docker socket, ARC / Docker-in-Docker, network
 
 ## Shared Reminder
 
-Reference this file from creator, updater, and debugger prompts instead of repeating the same architectural explanation.
+Reference this file from creator, updater, and debugger prompts instead of repeating the architectural explanation.

.github/aw/workflow-editing.md

@@ -8,12 +8,12 @@ Agentic workflows are single markdown files at `.github/workflows/<workflow-id>.
 
 ## File Structure
 
-1. **YAML frontmatter** between `---` markers configures triggers, permissions, tools, network, imports, and safe outputs.
-2. **Markdown body** after the frontmatter is the agent prompt.
+1. **YAML frontmatter** between `---` markers: triggers, permissions, tools, network, imports, safe outputs.
+2. **Markdown body**: the agent prompt.
 
-## When Recompilation Is Required
+## Recompile When Changing Frontmatter Fields
 
-Run `gh aw compile <workflow-id>` after changing frontmatter fields such as:
+Run `gh aw compile <workflow-id>` after changing:
 
 - `on:`
 - `permissions:`
@@ -24,17 +24,17 @@ Run `gh aw compile <workflow-id>` after changing frontmatter fields such as:
 - `mcp-servers:`
 - engine, timeout, concurrency, or other YAML configuration
 
-## When Recompilation Is Not Required
+## No Recompile Needed
 
-Edit the markdown body directly when changing:
+Edit the markdown body directly for:
 
 - agent instructions
 - task descriptions
 - examples
 - formatting guidance
 - clarifications and guardrails
 
-Markdown body changes take effect on the next run without recompiling.
+Body changes take effect on the next run.
 
 ## Validation Commands
 
@@ -48,15 +48,15 @@ Use `--strict` for production-quality validation.
 
 ## Editing Rules
 
-- Make the smallest change that satisfies the request.
-- Preserve existing structure unless reorganization is part of the task.
-- Never leave a workflow in a broken state.
-- If compilation fails, fix all errors before stopping.
+- Smallest change that satisfies the request.
+- Preserve structure unless reorganization is the task.
+- Never leave a workflow broken.
+- If compile fails, fix all errors before stopping.
 - After frontmatter changes, review the generated `.lock.yml`.
 
 ## Prompt-Authoring Rules
 
-- Keep the prompt specific and imperative.
-- Prefer short examples over long tutorials.
-- Reference dedicated instruction files instead of duplicating long explanations.
-- Tell agents to use `noop` when they complete successfully and no visible action is needed.
+- Specific and imperative.
+- Short examples over long tutorials.
+- Reference dedicated instruction files instead of duplicating.
+- Tell agents to use `noop` when no visible action is needed.