Agentic dev preflight

Agentic Dev Preflight

Goal

Before development starts, determine whether the repository is ready for agentic engineering: can an agent understand the project rules, make a bounded change, verify it locally or through runtime evidence, and hand it back for review?

The output is a readiness judgment, bootstrapping order, and minimum workflow build plan, not only a task brief.

Operating Boundary

Treat preflight as read-only by default. Read files, inspect configuration, and run non-mutating discovery commands when useful. Do not edit files, install dependencies, change configuration, run migrations, delete content, push, rebase, or reset during preflight.

If the user asks to add missing rules, CI, tests, or configuration, first report the proposed changes and affected files. Stop for explicit confirmation when the action touches user or project safety boundaries.

If the project already has AGENTS.md, CLAUDE.md, .cursor/rules, README files, architecture docs, plans, or local workflow docs, read them first and treat project rules as authoritative.

Readiness Gates

Check each gate in order. Mark every gate as present, missing, partial, or not_applicable, and include evidence such as paths, commands, or observed absence.

For every missing or partial gate, state the smallest durable workflow artifact that would close the gap. Prefer concrete files, commands, report fields, or review roles over general advice.

Gate	What to Check
1. Rule Files	AGENTS.md, CLAUDE.md, .cursor/rules, or equivalent; directory rules, redlines, validation checklist, engineering discipline
2. Task Brief	Goal, scope, exclusions, validation criteria, and whether large changes require a plan
3. Local Verification	Discoverable lint, typecheck, test, build, smoke, or equivalent commands
4. Runtime Evidence	Browser checks, screenshots, curl, logs, examples, sample input/output, or other observable acceptance paths
5. CI / Automation	.github/workflows, pre-commit, Makefile, justfile, scripted validation entrypoints, or documented local-only fallback
6. Review Workflow	Implementer / Tester / Reviewer / Orchestrator perspectives; whether they are assigned as agents, sessions, separate passes, or explicit review focus areas
7. Done Standard	Fresh verification evidence, remaining risks, environment state, and review conclusion instead of only "done"
8. Checkpoint / Rollback	Commit, branch, PR, rollback point, or staged gate expectations

Review Role Model

Treat role separation as a workflow requirement, not a requirement to always launch multiple agents. Check whether the workflow creates independent perspectives at the right moments:

• Implementer: makes the bounded change.
• Tester: proves behavior with commands, runtime checks, and failure follow-up.
• Reviewer: checks direction, boundaries, architecture, security, regression risk, and irrelevant changes.
• Orchestrator: chooses the task slice, keeps alignment with product goals, decides entry conditions, and judges done.

Classify the review workflow:

• present: the four perspectives are explicitly assigned as agents, separate sessions, separate passes, or documented review focus areas.
• partial: code review exists, but implementation, verification, direction, boundary, or risk perspectives are mixed together.
• missing: the implementer self-reviews without independent verification, direction review, or risk review.

Workflow Bootstrap Plan

When the repository is not fully ready, propose the minimum workflow changes needed before or alongside development. Keep this plan read-only unless the user explicitly asks for implementation.

Cover only the gaps that apply:

• Rule files: what project rules, directory boundaries, redlines, validation commands, or engineering discipline should be added.
• Task slicing: the smallest verifiable increment that can be implemented with the current workflow.
• Verification entrypoints: how lint, typecheck, tests, build, smoke checks, or local-only fallbacks should be exposed.
• Runtime evidence: which browser path, screenshot, curl command, log, sample input/output, or observable acceptance path should prove behavior.
• Review roles: current role model, missing perspectives, minimum split to add before development or before merge, and fallback when no multi-agent runtime exists.
• Done report: which fresh commands, runtime checks, failures, risk notes, environment state, and review conclusions should be reported.
• Checkpoint / rollback: where branch, commit, PR, staged gate, or rollback expectations should be documented.

Capability Discovery

Probe only capabilities relevant to the current project. Prefer evidence from project files over assumptions.

• Web / UI: inspect package.json, Vite or Next config, Playwright or Vitest setup, browser automation, screenshots, and documented smoke paths.
• Backend / API: inspect test framework, health checks, curl smoke commands, Docker or compose files, and logs.
• Data / DB: inspect migrations, schema docs, seeds, read/write boundaries, and rollback expectations.
• Agent workflow: inspect review, test, browser validation, CI feedback, and done-report paths.
• Local tools: when relevant, confirm whether Codex Browser, Chrome, web access, agent browser tooling, multi-agent support, GitHub CLI, or similar capabilities are available.

Classify missing capabilities:

• required_before_development: continuing would make the change unverifiable or likely to cross boundaries.
• recommended_before_merge: local work can proceed, but merge or release should wait.
• optional_later: improves speed or quality but is not a current gate.

Guidance Order

Give evidence before asking for user guidance. Ask only questions that change engineering direction, bootstrapping cost, or safety boundaries.

1. Workflow gaps: missing rule files, validation commands, CI, runtime evidence, review process, or done standard.
2. Bootstrap priority: what must be added now, what can follow the current task, and what can wait.
3. Task slicing: the smallest verifiable development slice possible with current workflow capability.
4. Verification path: commands to run, pages to open, API calls to make, logs or screenshots to collect.
5. Review focus: who checks direction and boundary, who checks implementation and tests, who decides done.
6. Entry condition: what must be true before moving from preflight into coding.

When the workflow is incomplete, prefer bootstrapping the workflow before business implementation.

Output Format

Preflight: READY_FOR_DEVELOPMENT | NEEDS_BOOTSTRAP | BLOCKED

Workflow Readiness:
- Rule files:
- Task brief standard:
- Local verification:
- Runtime evidence:
- CI / automation:
- Review workflow:
- Done standard:
- Checkpoint / rollback:

Capability Gaps:
- Required before development:
- Recommended before merge:
- Optional later:

Workflow Bootstrap Plan:
- Rule files:
- Task slicing:
- Verification entrypoints:
- Runtime evidence:
- Review roles:
  - Current model:
  - Missing perspectives:
  - Minimum split:
  - No multi-agent fallback:
- Done report:
- Checkpoint / rollback:

Guidance Needed:
- ...

Proposed Next Step:
- ...

Decision Standard

• READY_FOR_DEVELOPMENT: key gates exist, verification is clear, and the current task can be sliced into a verifiable increment.
• NEEDS_BOOTSTRAP: work can continue, but rules, verification, runtime evidence, review workflow, or done standard should be added first.
• BLOCKED: critical context, safety boundary, verification path, branch state, or repository state is missing; continuing would be unsafe or unverifiable.

Common Failure Modes

• Clarifying only the feature request without checking whether the project can verify agent work.
• Writing a prompt instead of establishing rule files, test commands, runtime evidence, and CI feedback.
• Using only an implementer perspective with no independent review or test perspective.
• Requiring multiple live agents when separate sessions, passes, or review focus areas would provide enough role separation.
• Treating "it runs locally" as done without commands, screenshots, logs, or risk notes.
• Reporting workflow gaps without telling the user the smallest artifact that would close each gap.
• Ignoring dirty worktrees, untracked files, stale branches, or unsynchronized rule files.
• Continuing into implementation after a missing workflow gate should have stopped or bootstrapped the work.