Skip to content

aws-samples/sample-oh-my-aidlcops

BranchesTags

Repository files navigation

sample-oh-my-aidlcops

Make AIDLC reliable. OMA is a Claude Code · Kiro plugin marketplace that turns the AIDLC methodology's two reliability axes — Ontology Engineering (correctness) and Harness Engineering (safety) — into installable plugins, with AIDLC Workflows as the process spine and AgenticOps closing the feedback loop back into the ontology.

한국어 README · Documentation · Plugins · Steering · Releases · References

The easy button for Ontology + Harness Engineering

OMA's goal is a one-install easy button: add the marketplace, install the plugins, and the AIDLC methodology's two reliability axes — Ontology Engineering and Harness Engineering — are active in Claude Code or Kiro without hand-rolling any schemas, policies, or hooks. You approve at checkpoints; agents do the rest.

/plugin marketplace add https://github.com/aws-samples/sample-oh-my-aidlcops
/plugin install ai-infra@oh-my-aidlcops agenticops@oh-my-aidlcops aidlc@oh-my-aidlcops modernization@oh-my-aidlcops
# → typed ontology + harness DSL + AWS hosted MCP wiring, ready to use

Where this is going — an enterprise operations open toolset

OMA is being built into an open toolset for enterprise operations automation. The trajectory:

  1. Today — Ontology + Harness Engineering as installable plugins, AWS Hosted MCP (awslabs/mcp) as the default runtime data layer, AgenticOps closing the feedback loop.
  2. Next — deeper AWS Hosted MCP coverage plus first-class DevOps agent and Security agent integrations, so deploy, observability, and security review run as governed agents inside the same approval model.
  3. The promise — install a few plugins and get enterprise-grade operations automation that is auditable, policy-gated, and harness-constrained by default — not a bespoke platform you assemble yourself.

What's new in v0.4

Release v0.4.0-preview.1 repositions the project around the reliability dual-axis and renames plugins for clarity, building on the enterprise ontology + harness surface introduced in v0.3:

  • Reliability dual-axis docs — dedicated Ontology Engineering (correctness) and Harness Engineering (safety) pages mapping each axis to its OMA implementation, with honest partial/roadmap status for harness patterns.
  • Plugin renames — agentic-platform → ai-infra, and aidlc-inception + aidlc-construction merged into a single aidlc plugin.
  • 8 ontology entities — Agent, Skill, Deployment, Incident, Budget, Risk, plus Spec and ADR (Draft 2020-12) closing the Phase-1 → Construction traceability chain.
  • Harness DSL v2 — optional workflows (DAG), telemetry (OpenTelemetry), policies (declarative runtime deny rules), metadata.labels. version: 1 files compile unchanged.
  • Pure-CC policy enforcement — a plugin's policies block compiles into a PreToolUse hook (hooks/enforce.py + hooks/harness-rules.json) that blocks matching tool calls before they run. Pure Claude Code, no external policy engine, no opa binary.
  • Enterprise gates — oma doctor --enterprise (8 probes), oma compile --strict-enterprise, oma validate <entity.yaml>, and JSON-L audit events via python -m tools.oma_audit.append.

Full details in CHANGELOG.md and on the Releases page.

What is OMA?

oh-my-aidlcops (OMA) is the sibling project of oh-my-claudecode (OMC). Where OMC orchestrates generic Claude Code workflows, OMA specializes in making the AIDLC loop — Inception → Construction → Operations — reliable enough to run with agents.

The problem: agentic AIDLC fails on reliability, not capability

The AIDLC methodology identifies that AI-driven development breaks down in three recurring ways, and none of them are about model quality:

  • Hallucination & drift — concepts mean different things across prompts and sessions, so handoffs only work because a human re-interprets them.
  • Runaway execution — without architectural limits an agent loop can fire hundreds of retries (the methodology's fintech case: 847 retries, ~$2,200, a 3-hour outage) before anyone notices.
  • Self-grading — the agent that wrote the code also writes the tests, so its own blind spots survive verification.

The methodology answers these with a reliability dual-axis: Ontology Engineering guarantees the correctness of what agents produce (the WHAT/WHEN), and Harness Engineering enforces the safety of how they execute (the HOW). OMA is the installable implementation of that dual-axis on AWS.

The three pillars OMA installs

Methodology axis Guarantees OMA implementation Entry point
Ontology Engineering Correctness (WHAT · WHEN) 8 JSON-Schema entities in schemas/ontology/, oma validate, schema-evolution rules /oma:inception, oma validate
Harness Engineering Safety (HOW) Harness DSL v2 (policies → PreToolUse enforcement, telemetry), oma compile --strict-enterprise, pinned MCP, sandboxed budget eval oma doctor --enterprise, oma compile
AgenticOps (Outer Loop) Living ontology self-improving-loop, continuous-eval, incident-response feeding operational signal back into the ontology /oma:agenticops, /oma:self-improving

AIDLC Workflows — the AWS-official awslabs/aidlc-workflows 3-phase loop — is the process spine these pillars hang on. OMA contributes only *.opt-in.md extensions to it and never forks the core. The result: AIDLC stops being "design and build, then hope," and becomes a lifecycle where every artifact is a validated ontology document and every agent action runs inside a harness.

Who is this for?

  • Platform engineers building agentic AI on AWS EKS.
  • Teams running LLM/agent workloads who want AIDLC to cover operations, not just design and construction.
  • Teams modernizing legacy workloads onto AWS using a repeatable 6R workflow.
  • Claude Code or Kiro users who want a drop-in marketplace rather than hand-rolling skills.

Plugins

Plugin What it does Example skills
ai-infra Build & run the Agentic AI Platform on EKS agentic-eks-bootstrap, vllm-serving-setup, inference-gateway-routing, langfuse-observability, gpu-resource-management, ai-gateway-guardrails
agenticops Operate it with agents self-improving-loop, autopilot-deploy, incident-response, continuous-eval, cost-governance, audit-trail, anomaly-detection, root-cause-analysis, automated-remediation, slo-management, predictive-scaling
aidlc AIDLC Phase 1 (Inception) + Phase 2 (Construction) extensions requirements-analysis, user-stories, workflow-planning, component-design, code-generation, test-strategy, risk-discovery, quality-gates
modernization Legacy workload modernization to AWS (6R strategy) workload-assessment, modernization-strategy, to-be-architecture, containerization, cutover-planning

Tier-0 workflows

OMA inherits the Tier-0 pattern from OMC — high-leverage workflows you invoke once and let run, with human approval only at checkpoints.

Command Purpose
/oma:autopilot Full AIDLC loop autopilot (Inception → Construction → Operations)
/oma:aidlc-loop Single-feature AIDLC one-pass
/oma:agenticops Operations mode (continuous-eval + incident-response + cost-governance)
/oma:self-improving Feedback loop — traces (via your opt-in trace MCP) to skill/prompt improvement PR
/oma:platform-bootstrap 5-checkpoint Agentic AI Platform build on EKS
/oma:modernize Legacy workload modernization (6R decision → cutover)
/oma:review AIDLC artifact review (ADR, spec, design, PR)
/oma:cancel Terminate active Tier-0 mode

Install

⚡ One-liner (Tech Preview — recommended)

install.sh downloads the pinned release tarball, extracts to ~/.oma, and symlinks ~/.local/bin/oma. oma setup then writes a project profile, seeds the ontology, installs the plugins, and runs oma doctor to confirm the environment.

curl -fsSL https://raw.githubusercontent.com/aws-samples/sample-oh-my-aidlcops/v0.4.0-preview.1/install.sh | bash
cd my-project
oma setup
oma doctor

See the Easy Button docs for what oma setup writes, how the 12 doctor probes work, and how the ontology + harness DSL get enforced at runtime.

Tech Preview notice — v0.4.0-preview.1 treats profile.yaml v1, the 8 ontology schemas, and Harness DSL v2 as stable. Everything else (CLI UX, doctor report shape) may evolve before GA. See Support Policy.

Claude Code (native marketplace — Claude Code 2.0+)

claude

Inside the Claude Code session:

/plugin marketplace add https://github.com/aws-samples/sample-oh-my-aidlcops
/plugin install ai-infra@oh-my-aidlcops
/plugin install agenticops@oh-my-aidlcops
/plugin install aidlc@oh-my-aidlcops
/plugin install modernization@oh-my-aidlcops
/plugin list

/plugin install accepts a single plugin id per invocation. Pasting the six lines above lets Claude Code run them sequentially. For a shell one-liner, use claude <<'EOF' ... EOF to feed the commands via stdin.

Claude Code (manual script — legacy / MCP-only)

git clone https://github.com/aws-samples/sample-oh-my-aidlcops
bash sample-oh-my-aidlcops/scripts/install/claude.sh

The manual script creates ~/.claude/plugins/ symlinks and merges MCP servers + hooks into settings.json. On Claude Code 2.0+ this alone does NOT register plugins with /plugin list. Use it only for legacy 1.x environments, offline CI, or when you want to wire MCP servers without activating the marketplace.

Kiro

git clone https://github.com/aws-samples/sample-oh-my-aidlcops
bash sample-oh-my-aidlcops/scripts/install/kiro.sh

Initialize .omao/ in your project

cd <your-project>
bash <path-to-oma>/scripts/init-omao.sh

AIDLC extensions (opt-in)

bash scripts/install/aidlc-extensions.sh
# Clones awslabs/aidlc-workflows into ~/.aidlc and symlinks OMA's opt-in extensions.

Quick start — enterprise flags

After oma setup, four commands are worth exercising on day one:

# 1. Diagnostic only — 8 probes, never changes state.
oma doctor --enterprise
# → [doctor:enterprise] 8 probes OK (0 warnings)

# 2. Enforce the gate — rejects DSL v1, missing approval_chain, legacy
#    string artifacts, and unclassified Risks.
oma compile --strict-enterprise
# → compiled ai-infra: plugins/ai-infra/.mcp.json ...

# 3. Validate an ontology entity (Spec / ADR / Deployment / Incident /
#    Budget / Risk / Agent / Skill) against its JSON Schema.
oma validate path/to/deployment.yaml
# → [oma validate] path/to/deployment.yaml: schema OK

# 4. Print the execution plan for a DSL v2 workflow (stub: no runtime yet).
oma run-workflow ai-infra platform-bootstrap
# → execution order: preflight -> provision -> verify

Adoption is one flag away — every enterprise field is optional until you opt in via --strict-enterprise. See Enterprise readiness for the phased adoption checklist.

Compliance frameworks

OMA aligns ontology entities with four authoritative references so audit-facing conversations work without invented vocabulary:

Framework Where it lands in OMA Docs
Model Context Protocol v1.0 Agent.mcp_uri (canonical MCP server URI) Foundation
SLSA v1.1 Provenance Deployment.artifact.{digest,provenance_uri,signing} SLSA provenance
NIST AI RMF (AI 100-1) Risk.nist_ai_rmf_subcategory, AuditEvent.compliance.nist_ai_rmf NIST AI RMF mapping
OWASP Top 10 for LLM Apps Risk.owasp_llm_top10_id (LLM01..LLM10) OWASP LLM Top 10 mapping

OpenTelemetry (traces/metrics/logs) and FinOps Framework cost categories feed the DSL v2 telemetry and Budget surfaces respectively.

Liked it? Give the repo a Star

If OMA was useful, a ⭐ on the GitHub repository helps us prioritize maintenance and keeps release notifications flowing to you. It is entirely optional — nothing in the CLI changes based on your star status.

Architecture

User request
    │
    ▼
Tier-0 trigger  ─── matches keyword? ──▶ /oma:<workflow>
    │
    ▼
Plugin dispatch
    │
    ├─▶ ai-infra        (build/run runtime)
    ├─▶ agenticops      (operate)
    ├─▶ aidlc           (Phase 1 + Phase 2)
    └─▶ modernization   (legacy → AWS)
    │
    ▼
Skills execute, calling AWS Hosted MCP
    │
    ├─▶ eks, cloudwatch, prometheus, aws-iac, cost-explorer, ...
    │
    ▼
Checkpoint — human approves
    │
    ▼
Operations phase continues autonomously
    │
    └─▶ self-improving-loop feeds corrections back to Construction

Foundation: ontology + harness DSL

OMA plugins rest on two shared layers:

  1. Ontology (ontology/, schemas/ontology/) — eight JSON Schemas that define the vocabulary every plugin and skill agrees on: Agent, Skill, Deployment, Incident, Budget, Risk, plus Spec and ADR. A handoff between Construction and Operations is no longer a prose description; it is a validated Deployment document. See ontology/README.md and ontology/glossary.md.
  2. Harness DSL (schemas/harness/dsl.schema.json, tools/oma_compile/) — one <plugin>.oma.yaml per plugin is the single source of agents, MCP servers, hooks, and triggers. python -m tools.oma_compile translates it to the native .mcp.json and kiro-agents/*.agent.json files that Claude Code and Kiro already consume, so marketplace installs stay unchanged.
<plugin>.oma.yaml  ──(oma-compile)──▶  .mcp.json
                                   ▶  kiro-agents/<agent>.agent.json
                                   ▶  .omao/triggers.json  (merged across plugins)

CI (.github/workflows/oma-foundation.yml) validates every schema fixture and runs oma-compile --check to reject drift between DSL sources and committed native files.

Security posture

This repository ships with conservative defaults. A few things are worth calling out before you use it in production:

  • MCP servers are pinned to exact PyPI versions in every .mcp.json and kiro-agents/*.agent.json. @latest is not used anywhere — a compromised upstream release cannot silently land alongside AWS credentials.
  • EKS MCP is read-only by default. The bundled Kiro agent profile does not pass --allow-write or --allow-sensitive-data-access to awslabs.eks-mcp-server. Add them explicitly when you need to provision or mutate EKS resources, and audit that change.
  • IAM is least-privilege. The langfuse-observability skill uses a customer-managed policy scoped to the Langfuse bucket ARN; AWS managed AmazonS3FullAccess (s3:* account-wide) is explicitly rejected with a "Bad Example" block in the skill.
  • budget.yaml expressions are sandboxed. The cost-governance skill evaluates rule["when"] via simpleeval (AST walker, zero builtins, zero callables). A documented Bad Example shows why Python eval() on a user-editable file is an RCE vector.
  • Session state stays local. .omao/state/, .omao/plans/, .omao/logs/, .omao/notepad.md, and .omao/project-memory.json are gitignored — audit-trail captures prompts verbatim (PII, approver identity, SOC2 retention content) and must never leave the machine.
  • Hooks require a real JSON encoder. hooks/session-start.sh uses jq (with python3 / python as ordered fallbacks) and exits non-zero rather than emitting shell-interpolated JSON, preventing state-file injection into the session context.

Reused assets

OMA stands on top of existing AWS and community work rather than reinventing.

Source License How OMA uses it
awslabs/agent-plugins Apache-2.0 Adopts plugin, skill-frontmatter, mcp, marketplace JSON schemas.
awslabs/aidlc-workflows MIT-0 Consumed as AIDLC core; OMA contributes only *.opt-in.md extensions.
awslabs/mcp Apache-2.0 11 hosted MCP servers referenced via uvx stdio.
aws-samples/sample-apex-skills MIT-0 Workflow 5-checkpoint template pattern.
aws-samples/sample-ai-driven-modernization-with-kiro MIT-0 Risk-discovery, audit-trail, quality-gates, 6R strategy methodology.
Atom-oh/oh-my-cloud-skills MIT Eval script patterns, Kiro conversion reference.
oh-my-claudecode — Tier-0 orchestration and .omc/ state inheritance.

Full attribution in NOTICE. See REFERENCES.md for the complete catalogue of every upstream repo, authoritative spec, framework, and runtime tool that OMA touches.

License

MIT No Attribution (MIT-0). See LICENSE.

Contributing

OMA is in Tech Preview (v0.4.0-preview.1). See CONTRIBUTING.md for the working agreement (English-only artifacts, no AI attribution, commit per unit of work) plus the PR/branch-naming guidelines, and CODE_OF_CONDUCT.md for the Amazon Open Source Code of Conduct. Issues and PRs are especially welcome for skill quality, MCP coverage gaps, and Kiro compatibility testing.

For security issues, do not open a public GitHub issue — follow the AWS vulnerability reporting process instead.

About

AIDLC × AgenticOps — plugin marketplace that extends Claude Code and Kiro with agentic operations for the AWS AI-Driven Development Lifecycle (Inception → Construction → Operations).

aws-samples.github.io/sample-oh-my-aidlcops/

Topics

aws mcp eks aws-samples agentic-ai claude-code kiro plugin-marketplace aidlc agenticops

Resources

Readme

License

MIT-0 license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

14 stars

Watchers

0 watching

Forks

4 forks
Report repository

Releases

3 tags

Packages

 
 
 

Contributors

Languages

Generated from amazon-archives/__template_Apache-2.0