The standard, written down.

# AGENTS.md

<!-- generated from workflow-pack frontend-taste v1.0.0 -->

## Frontend taste discipline

### The three locks

Decide these once per page and hold them for the whole page — mixing them is the single biggest tell of unreviewed AI output:

1. **One accent color.** Pick a single accent for interactive/emphasis elements. Everything else is neutrals.
2. **One corner-radius system.** Pick a radius scale (e.g. sm/md/lg mapped to fixed px values) and use it everywhere — no ad-hoc `rounded-[7px]` next to `rounded-2xl`.
3. **One theme mode, decided at the page level.** Don't let individual components guess light/dark independently.

### Hero discipline

- Headline is 2 lines or fewer. If it doesn't fit, the message is too long, not the font too small.
- Subtext is roughly 20 words or fewer — one sentence, not a paragraph.
- Nav height is capped (~64px); it should never compete with the hero for vertical space.

### Anti-slop bans

These patterns are default outputs of ungrounded AI generation. Treat every one as a defect, not a style choice:

- No three-equal-width feature card rows. Use asymmetric layouts — different widths, different emphasis — so the page doesn't read as a template.
- No AI-purple/mesh-blob gradients unless the brand explicitly calls for them.
- No section-number eyebrows like "001 · Features" — they signal filler, not information.
- No `window.addEventListener('scroll')` for reveal/parallax effects — use `IntersectionObserver`, it's cheaper and doesn't jank.
- No emoji as section markers or bullet icons.
- Neutrals get a deliberate hue bias (warm or cool grey); never pure mid-grey (`#808080`-style), which reads as unstyled.
…

# AGENTS.md

<!-- generated from workflow-pack software-engineer-harness v1.1.0 -->
<!-- adapted from affaan-m/ECC (MIT) — https://github.com/affaan-m/ECC -->

## Engineering discipline

- Understand before building: for any non-trivial change, state the plan (what, where, how verified) before editing code.
- Test-first: write or extend a failing test before the implementation; never mark work done without a green suite you ran yourself.
- Small, reviewable steps: one logical change per commit, with a message that says why.
- Never silently swallow errors; handle them explicitly or let them propagate.
- Scope discipline: touch only what the task requires — no drive-by refactors.
- Every non-trivial change gets an independent review before merge; the reviewer's findings are addressed, not argued away.

## Workflow pack: Software engineer harness

The complete engineering workflow for AI-assisted development: understand and plan before building, implement test-first, get an independent review, and verify before declaring done.

### Roles

- **planner** — Turns a feature request or bug report into a concrete implementation plan: files to touch, interfaces, test cases, and step order. Use before starting any non-trivial change.
- **reviewer** — Reviews a completed change against its requirements and code quality standards. Use after implementation, before merge or done.
- **checker** — Independently re-runs the test suite and typecheck and reports raw results. Use before declaring any task complete.
- **architect** — Evaluates system-level design and trade-offs for larger or cross-cutting changes: patterns, scalability, maintainability. Use before designing a new subsystem or a refactor that spans multiple components.
- **code-reviewer** — Deep-dives a diff for security, quality, and framework-specific issues with confidence-based filtering — only reports findings it can back with an exact line and failure mode. Use as a stricter second pass alongside the reviewer role, especially on security-sensitive or framework-heavy changes.
- **code-simplifier** — Simplifies recently-changed code for clarity and consistency while preserving behavior exactly — extracts nested logic, removes dead code, unwinds over-abstraction. Use after a change works and is reviewed, before final merge.

### Commands

- **/plan-work** `[task description]` — Produce an implementation plan for a task before touching code.
…

# AGENTS.md

<!-- generated from workflow-pack token-efficiency-harness v1.0.0 -->

## Token-efficiency discipline

Every turn re-sends the entire session so far — cost is per message TIMES everything before it. Keep "everything before it" small:

- **One task, one session.** When a task is done, `/clear`. For genuinely long tasks, `/compact` at milestones (after a feature lands, never mid-debug).
- **Hand off instead of continuing.** End multi-day work by writing a handoff note into the repo (use `/handoff`), then start tomorrow clean from that note.
- **Tier your models.** The main conversation deserves the best model; searching, mechanical edits, and fan-out work go to haiku/sonnet subagents. Five parallel top-tier agents burn 5x top-tier rates.
- **Cap extended thinking** for routine work (`MAX_THINKING_TOKENS=10000` in settings); raise it only for genuinely hard problems.
- **Specific beats short.** One precise sentence ("the profile toggle POSTs to /api/user and gets a 400 — fix the payload shape") replaces three exploratory rounds. Grep logs first; paste the 10 relevant lines, never the 500-line dump — a paste is re-billed on every following turn.
- **Work in bursts.** The prompt cache expires after ~5 idle minutes; rapid-fire turns replay history at ~10% price, sporadic drips rebuild it at full price.
- **Budget every autonomous run.** State a token budget and a definition of done in the prompt; require a diff summary + self-review at the end so a stuck loop cannot retry forever.

## Workflow pack: Token-efficiency harness

Cuts AI token spend without cutting output: session hygiene, model tiering, thinking caps, and budgeted autonomous runs — the habits that eliminate ~97% of waste in heavy-usage audits.

### Roles

- **scout** — Cheap, fast reconnaissance: finds files, symbols, and usage sites and returns file:line references — never full file dumps. Use for any search or lookup before involving the main model.

### Commands

- **/handoff** `[note-name]` — End the session with a durable handoff note so the next session starts clean and cheap.
  - How it runs: Write a handoff note to docs/handoff/$ARGUMENTS.md (use docs/handoff/latest.md when no argument is given) covering: what was completed (with commit hashes), what remains, key files and decisions, and the exact next step. Keep it under 40 lines. Then tell the user to /clear and resume from the note next session.
- **/usage-audit** `[optional]` — Audit local Claude Code token usage and recommend the highest-impact fix.
  - How it runs: Run `npx ccusage@latest` via Bash and read the breakdown. Report: the top model by tokens, cache-read volume versus fresh input, and the single highest-impact change from the token-efficiency rules in AGENTS.md (session hygiene, model tiering, thinking cap, or run budgets). End with one concrete habit change for this user.
…

# AGENTS.md

<!-- generated from workflow-pack test-loop v1.0.0 -->

## Test-loop discipline

- Never mark a task done without running the test suite and reading the output.
- The checker role is independent: it must not trust the builder's self-report, it must re-run verification itself.
- If checker finds a failure, hand back to builder with the exact failing output, not a paraphrase.

## Workflow pack: Builder/Checker test loop

A two-role loop: the builder writes/edits code, the checker independently verifies tests pass before the change is considered done.

### Roles

- **checker** — Independently verifies the builder's change by re-running tests/build and reporting raw results. Use after any non-trivial code change, before declaring work done.

### Commands

- **/build-and-check** `[target]` — Run the builder/checker loop until the suite is green or a fixed retry budget is exhausted.
  - How it runs: Build or apply the pending change for $ARGUMENTS. Then invoke the checker subagent to verify. If it fails, fix and repeat, up to 3 rounds. Stop and report if still red after 3 rounds.

### Guardrails

- Nudge: after any file edit, remind the agent that checker verification is required before marking done.

Tool-specific implementations live alongside this file (see `CLAUDE.md` for the Claude Code implementation). Tools without a native subagent/command surface should treat the sections above as operating instructions.

…

# AGENTS.md

<!-- generated from workflow-pack security-review v1.0.0 -->
<!-- adapted from affaan-m/ECC (MIT) — https://github.com/affaan-m/ECC -->

## Security review discipline

Run this against any code that handles user input, authentication, API endpoints, or sensitive data — before it reaches production.

### Checklist

- **Injection** — Are queries parameterized? Is user input ever concatenated into a query, shell command, or template string?
- **Authorization** — Is every route/mutation checked for auth, not just authentication? Is access scoped to the resource owner, not just "logged in"?
- **Secrets** — Any hardcoded API key, password, token, or connection string in source? Are secrets read from environment/secret manager, with a startup check that they're present?
- **Unsafe deserialization** — Is untrusted input ever passed to `eval`, a pickle/deserialize call, or a dynamic `require`/`import` without validation?
- **SSRF** — Does the server ever fetch a URL supplied by the user? If so, is the destination allow-listed, not just "looks like a URL"?
- **XSS** — Is user content ever rendered as raw HTML (`innerHTML`, `dangerouslySetInnerHTML`) without sanitization?
- **Logging** — Do logs ever include a password, token, or full PII record?

### Severity

Hardcoded secrets, injection, and auth bypass are CRITICAL — block merge. XSS and SSRF without an allow-list are HIGH. Missing rate limiting or verbose error messages are MEDIUM.

### False positives to skip

`.env.example` placeholders, clearly-marked test credentials, and public API keys meant to be public are not findings — verify context before flagging.

## Workflow pack: Security review

A security review checklist and reviewer role covering injection, authz, secrets, unsafe deserialization, and SSRF — flags real vulnerabilities with severity and file:line, not theater.
…

# AGENTS.md

<!-- generated from workflow-pack database-review v1.0.0 -->
<!-- adapted from affaan-m/ECC (MIT) — https://github.com/affaan-m/ECC -->

## Database review discipline

### Query performance

- Every column in a `WHERE` or `JOIN` should be indexed — check with `EXPLAIN ANALYZE`, not by assumption.
- Watch for N+1: a query inside a loop over rows from a previous query. Batch it or join it instead.
- Composite indexes: put equality columns before range columns.

### Schema design

- Use precise types: a real timestamp-with-timezone type for timestamps, a decimal/numeric type for money, `text` over an arbitrary varchar length cap.
- Every foreign key gets an index — no exceptions.
- Constraints (`NOT NULL`, `CHECK`, foreign key `ON DELETE`) belong in the schema, not just in application code.

### Migration safety

- A migration that adds a `NOT NULL` column to a large table needs a backfill step, not just a default — check what happens to in-flight writes during the migration.
- Long-running migrations should not hold locks across an external call or a slow backfill; batch the backfill.
- Every migration needs a rollback path.

### Security

- Queries are parameterized, never string-concatenated with user input.
- Multi-tenant tables enforce row-level access control at the database layer, not only in application code.
- Application database users get least-privilege grants, never blanket admin access.
…

# AGENTS.md

<!-- generated from workflow-pack typescript-rules v1.0.0 -->
<!-- adapted from affaan-m/ECC (MIT) — https://github.com/affaan-m/ECC -->

## TypeScript/JavaScript standards

### Types

- Add explicit parameter and return types to exported functions, shared utilities, and public methods. Let TypeScript infer obvious local variable types.
- Use `interface` for object shapes that may be extended; use `type` for unions, intersections, and mapped types.
- Prefer string-literal unions over `enum` unless interoperability requires an `enum`.
- Avoid `any` in application code. Use `unknown` for external/untrusted input and narrow it before use (e.g. `error instanceof Error`).
- Type React props with a named `interface`/`type`; type callback props explicitly; skip `React.FC` unless there's a specific reason for it.

### Immutability

- Never mutate an object/array in place — return a new one via spread (`{ ...user, name }`) or array methods (`map`/`filter`), not push/splice on the original.

### Error handling

- Use `async`/`await` with `try`/`catch`; narrow `unknown` caught errors before reading `.message`.
- Never swallow an error silently — log with context and re-throw or return a typed result.

### Input validation

- Validate all external/user input at the boundary with a schema library (e.g. Zod); infer the TypeScript type from the schema rather than hand-writing both.

### Security

…

# AGENTS.md

<!-- generated from workflow-pack python-rules v1.0.0 -->
<!-- adapted from affaan-m/ECC (MIT) — https://github.com/affaan-m/ECC -->

## Python standards

### Style

- Follow PEP 8. Add type annotations to every function signature, including internal helpers.
- Format with `black`, sort imports with `isort`, lint with `ruff`.

### Immutability

- Prefer immutable data structures: `@dataclass(frozen=True)` or `NamedTuple` for value objects, instead of a mutable class with public attributes.

### Patterns

- Use `Protocol` for structural typing when a caller only needs an interface, not a concrete base class.
- Use plain `@dataclass` as request/DTO shapes at API or service boundaries.
- Use context managers (`with`) for anything that acquires a resource (files, locks, connections); use generators for lazy, memory-efficient iteration.

### Error handling

- Catch specific exception types, not bare `except:`. Re-raise with `raise ... from err` to preserve the chain when wrapping.

### Input validation

- Validate external input at the boundary (Pydantic, or manual checks) before it reaches business logic; fail fast with a clear message.

…

# AGENTS.md

<!-- generated from workflow-pack go-rules v1.0.0 -->
<!-- adapted from affaan-m/ECC (MIT) — https://github.com/affaan-m/ECC -->

## Go standards

### Style

- `gofmt` and `goimports` are mandatory — there is no style debate to have.
- Accept interfaces, return structs. Keep interfaces small (1-3 methods) and define them where they're used, not where they're implemented.

### Error handling

- Always wrap errors with context: `fmt.Errorf("failed to create user: %w", err)`, never return a bare error with no indication of where it came from.
- Check every error; an ignored `err` is a defect, not a shortcut.

### Patterns

- Use functional options (`type Option func(*Server)`) for constructors with many optional parameters, instead of a giant config struct or long parameter list.
- Inject dependencies through constructor functions (`NewUserService(repo, logger)`), not package-level globals.

### Concurrency

- Always thread `context.Context` through for cancellation and timeout control: `ctx, cancel := context.WithTimeout(ctx, 5*time.Second)` then `defer cancel()`.
- Protect shared state explicitly (mutex or channel) — never assume a value is safe to read/write from multiple goroutines without one.

### Security

- Read secrets via `os.Getenv` and fail fast (`log.Fatal`) if a required one is empty — never proceed with a blank credential.
…