Phelan164/codex-howto

# Evidence Review

1. Read the requested diff and applicable repository guidance.
2. Trace each suspected problem to a concrete file, behavior, or broken contract.
3. Return actionable findings ordered by impact.
4. Include a precise location, failing scenario, evidence, and fix direction.
5. Omit style preferences and unsupported speculation.
6. State explicitly when no actionable finding is verified.

# Choose Engineering Flow

Use this explicit-only skill as an educational example of workflow routing. It
is not part of the recommended installable catalog; prefer clear specialist
descriptions and direct activation in normal work.

Recommend one entry skill and only the supporting skills that materially change
the work. Do not perform the requested engineering task.

## Route the request

1. Identify the requested outcome: implement, test, review, secure, operate, or
   coordinate.
2. Prefer one entry skill:

# Build Backend

## Domain contract

- Trace changed behavior from input through validation, authorization, domain
  logic, persistence, side effects, and response mapping.
- Preserve published contracts unless the request explicitly changes them.
- Enforce authorization at a trustworthy server-side boundary.
- Validate untrusted input before domain or persistence operations.
- Keep multi-write operations atomic where partial state would violate invariants.
- Design external calls for timeouts, retries, idempotency, and duplicate delivery where applicable.
- Do not query or mutate production data without explicit authorization.
- Do not fabricate migration, framework, or API behavior; verify version-sensitive details.
- Avoid broad service abstractions that are used once.

# Build Frontend

## Domain contract

- Preserve the project’s framework, styling system, and component conventions.
- Do not invent API response fields or silently change backend contracts.
- Do not replace an established design system with custom one-off styling.
- Define loading, empty, error, success, and disabled states that the changed
  flow can reach.
- Keep semantic HTML, keyboard navigation, focus behavior, labels, and contrast in scope.
- Avoid speculative shared abstractions for a single component.
- Treat screenshots and mockups as visual references, not proof of interaction behavior.
- Do not claim visual verification unless the UI was rendered or inspected.

# Engineering Loop

Deliver a verified change with minimal supervision and proportionate checking.
Start with one agent. Delegate only when authorized and independent work or
review coverage justifies the overhead. Follow applicable repository and team
requirements; this skill adds no ticketing or mandatory-agent process.

## Establish the baseline

1. Read applicable `AGENTS.md` files and repository documentation.
2. Record the requested behavior, constraints, and observable done conditions.
3. Inspect the branch and working tree; preserve unrelated user-owned changes.
4. Before changing shared behavior, trace affected callers, consumers, and tests
   using targeted search or an available code graph. Expand along relevant paths.

# Maintain Codex Wiki

Treat the wiki as compiled maintainer knowledge, not as an automatic source of
truth. Keep official documentation authoritative and require human review
before shared knowledge or curriculum changes land.

## Choose one operation

- **Query**: read `knowledge/index.md`, search candidate pages, and answer with
  links. Do not write unless the user explicitly asks.
- **Capture**: preserve a durable lesson from repository evidence such as a
  merged change, incident, review finding, or measured run.
- **Ingest**: register one source, update affected wiki pages, run lint, and
  prepare a reviewable diff.

# Operate DevOps

## Workflow

1. Read repository and environment guidance before changing configuration.
2. Identify the target environment, current state, owning tool, blast radius, and approval boundary.
3. Separate diagnosis, proposed change, apply, verification, and rollback.
4. Prefer a dry run, plan, diff, render, lint, or local build before any apply step.
5. Make the smallest reversible change.
6. Validate configuration syntax and policy.
7. Test failure behavior and rollback in the safest available environment.
8. Review the diff for secrets, broad permissions, unpinned behavior, and unintended targets.

## Guardrails

# Orchestrate Engineering

## Start with the delegation decision

1. Read applicable `AGENTS.md` files and the task’s acceptance criteria.
2. Map dependencies before creating workers.
3. Use one agent when the task is small, tightly coupled, or dominated by shared-file edits.
4. Delegate only when at least two workstreams are genuinely independent, noisy investigation should be isolated, or specialized review materially improves coverage.
5. Explain the chosen topology briefly before starting workers.

Subagents normally consume more total tokens than a comparable single-agent run. Optimize for fewer failed loops, cleaner context, better coverage, or lower elapsed time—not the highest agent count.

## Choose a topology

# Review Code

## Workflow

1. Establish the review target and comparison base.
2. Inspect the diff, then trace changed behavior through callers, contracts,
   persistence, side effects, and tests.
3. Inspect the target, isolation, fixtures, and side effects before running a
   narrow check that materially confirms a suspected issue.
4. Rank findings by impact and confidence; remove duplicates and speculation.
5. Return findings first, followed by open questions and a short summary.

Use correctness as the default lens. For large, risky, or requirement-heavy
changes, add the standards and specification lenses in

# Review Security

## Workflow

1. Establish the review target, intended behavior, and relevant threat model.
2. Identify assets, trust boundaries, actors, entry points, and sensitive operations.
3. Trace attacker-controlled data to security-relevant sinks.
4. Inspect authentication, authorization, tenant isolation, and privilege changes.
5. Evaluate realistic exploitability and existing controls.
6. Validate suspected findings safely with read-only analysis or sandboxed tests when authorized.
7. Return prioritized findings with evidence, impact, prerequisites, and remediation direction.

## Guardrails

# Test Software

## Test contract

- Define the behavior, invariant, or defect before selecting a test layer.
- Use the lowest layer that observes the risk without hiding the integration
  boundary under test.
- Test behavior rather than private implementation details.
- Avoid snapshots that hide meaningful assertions.
- Do not mock the component whose integration contract is under test.
- Control time, randomness, concurrency, and external dependencies explicitly.
- Keep fixtures minimal and readable.
- Do not “fix” flaky tests by adding blind retries or sleeps.
- Do not claim a regression test without proving it fails against the broken behavior when feasible.