AI Engineering Workflows

Reusable .ai workflow system for AI workers, repo groups, repos, roles, logs, impact reports, and handoffs.

Install Into Any Repo

Use the npm scaffolding CLI from any project, including Node, Go, Python, mobile, infra, or documentation repos:

npx @iamohmcub/ai-orchestration init \
  --repo-group-id acme-platform \
  --repo-group-name "Acme Platform" \
  --repo-id checkout-service \
  --repo-name "Checkout Service" \
  --type product-service \
  --phase okr \
  --workspace-profile web-saas

This creates or updates .ai/ and AGENTS.md. It does not add command docs or local scripts by default because the main UX is natural-language AI chat.

Use --commands when you also want COMMANDS.md.

What This Repo Gives You

Copy this into a project and the AI worker gets:

• AGENTS.md: root instruction file.
• .ai/manifest.yml: canonical load order.
• .ai/project.yml: project identity and current phase.
• .ai/workspace/: shared company standards for stack, style, structure, tools, and QA.
• .ai/role/<role-id>/: role modules with config, interface, playbook, checklist, and workspace overlay.
• .ai/global/agent.positions.yml: 15 agent positions and commit authority.
• .ai/global/worker.contract.yml: provider-neutral AI worker contract.
• .ai/global/event.contract.yml: portable event trigger contract for humans, AI workers, CLIs, plugins, and local runners.
• .ai/global/trigger.words.yml: natural-language trigger guide for mapping chat requests to workflow events.
• .ai/global/routing.matrix.yml: RACI-style routing for phase work and impact types.
• .ai/global/git.collaboration.yml: provider-neutral branch, PR/MR, review, approval, merge, and conflict workflow.
• .ai/global/parallel.delivery.yml: MVP/work item lanes so product, design, engineering, QA, release, and learning can move in parallel.
• .ai/runtime/state.yml: project runtime context that can change per repo or sprint.
• npx @iamohmcub/ai-orchestration: central CLI for init, status, phase logs, impact reports, handoffs, agent commits, and validation.

Quick Start

npx @iamohmcub/ai-orchestration init \
  --repo-group-id acme-platform \
  --repo-group-name "Acme Platform" \
  --repo-id checkout-service \
  --repo-name "Checkout Service" \
  --type product-service \
  --phase okr \
  --workspace-profile web-saas \
  --frontend-stack nextjs-typescript \
  --backend-stack node-api-typescript \
  --infra-stack netlify-or-container \
  --qa-profile playwright-vitest

npx @iamohmcub/ai-orchestration status
npx @iamohmcub/ai-orchestration start okr
npx @iamohmcub/ai-orchestration start technical-design --mvp mvp-1 --lane engineering-delivery --depends-on ".ai/runtime/handoffs/<handoff>.md"
npx @iamohmcub/ai-orchestration commit --agent Conway --feature checkout --message "route checkout idea" --evidence ".ai/runtime/logs/<phase-log>.md"
npx @iamohmcub/ai-orchestration validate

Optional command docs:

npx @iamohmcub/ai-orchestration init --commands

AI Worker Startup

Use .ai/templates/worker-startup-prompt.md as the single startup prompt. It points workers to the manifest, runtime state, provider-neutral worker contract, event contract, trigger words, routing matrix, Git collaboration policy, role modules, workspace standards, logs, reports, handoffs, and commit rule.

Git Collaboration

The workflow understands parallel Git work across GitHub pull requests, GitLab merge requests, or equivalent change requests:

• Create a dedicated branch for feature, fix, hotfix, chore, docs, test, refactor, or workflow work.
• Open a PR/MR with phase log, evidence, tests, impact reports, handoffs, and decisions linked.
• Route reviewers from .ai/global/routing.matrix.yml.
• Do not self-approve as the only reviewer.
• Merge only after approval, CI, tests, lint, secret scan, and impact acknowledgement pass.
• Resolve conflicts by routing file/domain decisions to owners, recording evidence, and rerunning impacted tests.

Portable Runtime Model

.ai is the source of truth. It does not require a specific AI vendor, IDE, adapter, or hosted model.

.ai policy and runtime files
  -> readable by any AI or human
  -> optionally enforced by CLI, plugin, CI, MCP, or local LLM runner

No adapter is required for the workflow to make sense. An adapter only makes event processing, dispatch, validation, and notifications faster.

File Type Rule

Use YAML for structured config that tools should parse.

Use Markdown for behavior, explanation, templates, playbooks, and human/AI reading.

File mapping:

• .yml: manifest.yml, project.yml, workspace.yml, interface.yml, role.yml, trigger.words.yml
• .md: AGENTS.md, SKILLS.md, playbook.md, checklist.md, COMMANDS.md

Main Docs

• AGENTS.md: root worker protocol.
• COMMANDS.md: command reference.
• ai-orchestration-map.html: single presentation/overview.
• .ai/README.md: .ai folder map.
• .ai/PROJECT_SETUP.md: new project checklist.