Skip to main content

Agent-assisted workflow

The AI path should still follow a deliberate workflow. Within approved scope, the agent executes these steps rather than returning them as homework for the user.

  1. Read AGENTS.md, CLAUDE.md, and other applicable repo instructions.
  2. Gather trusted source docs, implementation contracts, commands, and ownership context.
  3. Present the proposed information architecture and get approval for material choices.
  4. Edit the canonical source documentation first.
  5. Update or regenerate the docs_ui mirror, navigation, search surface, and relevant tests.
  6. Compare every command, endpoint, default, and architectural claim against the current repo.
  7. Run the required synchronization, formatting, lint, typecheck, tests, build, and local browser checks.
  8. Hand back the local changes with verification evidence, limitations, and unresolved decisions.

Do not perform a deployment or Git mutation unless the user separately authorizes it under the active repository rules.

What the agent should not do alone​

Do not let the agent invent:

  • ownership
  • commands it did not verify
  • architectural claims without source docs
  • repo-specific risk areas from intuition alone

Example​

Good AI-assisted usage:

  • provide README, runbooks, examples, and desired output shape
  • ask the agent to implement and verify the approved documentation change
  • let the agent update both canonical sources and generated or hosted surfaces
  • review the local result and evidence carefully

Bad AI-assisted usage:

  • provide only the repo path
  • accept the first output without checking it
  • ask for implementation but receive only a suggested checklist

Why this matters​

The agent-run workflow is faster, but it is not self-validating. Clear sources, approval gates, and fresh verification keep it useful without making the human execute routine repository steps manually.

Next steps​