Core Concepts

Intent

intent defines the outcome, not the implementation details. A good intent is specific enough to validate and broad enough to allow reasonable implementation choices.

Good: "Migrate docs navigation to grouped sections without breaking existing routes."
Weak: "Improve docs."

Constraints

constraints are non-negotiable boundaries: security limits, architectural boundaries, prohibited behaviors, and compatibility requirements.

Examples:

• do not break existing URLs
• no destructive git operations
• keep diffs scoped to requested feature area

Preferences

preferences express style and process defaults when multiple valid options exist.

Examples:

• prefer small incremental edits
• prefer readability over abstraction
• keep explanations concise and actionable

Workflow

workflow is an ordered process that turns intent into execution. It should be short, repeatable, and observable.

Typical workflow:

1. inspect existing state
2. implement focused changes
3. run checks
4. report outcomes and residual risks

Failure traps

failure_traps capture known patterns that often cause regressions or wasted effort.

Examples:

• editing generated files directly
• changing unrelated modules during a fix
• skipping route/test verification after refactors

Success checks

success_checks define objective completion criteria. These must be testable and explicit.

Examples:

• typecheck passes
• key routes return 200
• no linter errors in changed files

Keep it concrete

If a line cannot be validated or observed, rewrite it. The best AEPs are compact, concrete, and reusable across similar tasks.