Odinary-AI/ai-system-engineer-skill

AI-Native Systems Engineering

Version 2.3.1.

Help humans and AI carry system-level work from intent through validated closeout. Scale the workflow to the requested claim and risk. System quality depends on world-system fit—whether intent, objects, relationships, constraints, transformations, tools, evidence, and authority match the task world—not on the size of the workflow.

Start Here

1. Exclude routine coding, mechanical local refactors, and single-prompt work unless they expose a system-level boundary or claim.
2. Read references/workflow-router.md to select one route, one named depth, one starting context, and only profiles activated by observable conditions.
3. Follow the six-phase lifecycle in references/core-workflow.md.
4. Load specialist references only when the route or profiles require them.
5. Validate only the requested claim, reuse only valid evidence, and state residual risk.

Routes

Route	Use when
diagnose	Inspect, review, health-check, or compare without changing files
design-change	Design, plan, or implement a bounded system change, including Greenfield work
migrate-converge	Recover predecessor value, reconcile generations, change authority, or retire old paths
release	Package, install, share, publish, or make a release claim

Greenfield and Existing System are starting contexts, not routes. Planning, validation, and closeout are lifecycle phases. Domain quality and package risk are profiles, not competing workflows.

Depths

Depth	Default shape
quick	Read-only, local, reversible; create no files by default; use no formal Gates
focused	One bounded objective; zero to two records; targeted checks and one realistic example when behavior changes
full	Broad, authority-changing, multi-generation, irreversible, high-cost, or strong-claim work; use selected records and applicable Gates

Depth expresses rigor. L0-L5 expresses architecture altitude and is conditional. Do not choose full because the method exists. Choose it only when scope, risk, or claim strength requires it. Diagnosis has no full shape; escalate to a change, migration, or release route when diagnosis alone is not enough.

Shared Lifecycle

Frame -> Establish -> Shape -> Execute -> Validate -> Close

Frame the claim and authority. Establish current facts and context. Shape only the necessary design, plan, and evidence. Execute within approved semantics. Validate with proportional evidence. Close with supported and unsupported claims, residual risk, recovery information, and reopen triggers.

Specialist Profiles And References

Profile or need	Read
Route and depth selection	references/workflow-router.md
Shared execution and stopping rules	references/core-workflow.md
Architecture and AI-system design	references/system-design.md
Read-only diagnosis	references/project-health-check.md
Predecessor recovery, convergence, formal Gates, retirement	references/migration-convergence.md
Domain knowledge, artifact quality, reference floors, critic loops	references/domain-quality.md
Evidence types, claim ceilings, realistic checks	references/validation-evidence.md
AI versus human decisions and confirmation	references/decisions-confirmation.md
Package, install, and release scope	references/release-readiness.md
Failure patterns	references/engineering-patterns.md
Calibration examples	references/worked-examples.md

Core Boundaries

• Keep one active source of truth for each normative fact; projections and reports do not become new authorities.
• Preserve each domain method's applicability, inputs, resources, logic, outcomes, failure modes, unsuitable cases, boundaries, and handoffs.
• Separate current-run repair from human-reviewed, versioned system learning.
• Treat predecessor outputs as evidence, not the sole oracle.
• Do not let generated evidence, agent consensus, elapsed time, or silence become human_confirmed.
• Do not claim product quality from structure tests alone or package readiness from source tests alone.
• Activate the human-decision profile and follow references/decisions-confirmation.md at a potential accountable-decision boundary; continue autonomously for governed reversible implementation details.

Scaffold Only When Useful

quick needs no scaffold. For focused or full, create only the selected records:

python3 scripts/scaffold_engineering_package.py \
  --output <workspace> --project-name <name> \
  --route <diagnose|design-change|migrate-converge|release> \
  --depth <focused|full> [--profile <profile> ...] \
  [--record-profile <profile>]

--profile activates specialist methods and evidence. For focused, use --record-profile only when one active specialist profile needs its own record and the zero-to-two record budget still holds; otherwise consolidate specialist evidence into the route record.

Done

Finish when the bounded question or change is resolved, the evidence supports no more than the requested claim, unknowns and residual risks are explicit, and any irreversible action has accountable human confirmation. Escalate depth only when a named trigger appears; otherwise stop.