forked from diegoecab/oci-deal-accelerator
ca93a0aa4e
Why this set of changes:
- KB pricing was drifting silently — domain files (database.yaml,
storage.yaml, etc.) had prices 30-800% off the live Oracle API and
nobody read them. The skill was auditing as stale on every check
with no path to fix it.
- The skill itself violated Anthropic's spec (`name` field had
uppercase/spaces) and was over the 500-line guideline (647 lines),
hurting discovery and load performance.
- Welcome flow occasionally improvised the menu instead of reading
SKILL.md, missing options.
Pricing — single source of truth, fully automated:
- Extend tools/refresh_sku_catalog.py with --refresh-domain compute,
pulls shape-level prices from the Oracle public pricing API
(apexapps.oracle.com), preserves manual fields (notes, GPU specs,
free-tier annotations, estimation_helpers), recomputes derived
monthly values, and protects $0 free-tier prices from overwrite.
- Delete 12 redundant pricing/<domain>.yaml files. They duplicated
oci-sku-catalog.yaml with worse abstractions and were nobody's
source of truth (no tool consumed them).
- Migrate the genuinely valuable knowledge from those 12 files
(billing models, BYOL rules, free-tier rules, ECPU vs OCPU,
X11M elastic model, hyperscaler comparisons, service nuances)
into kb/field-knowledge/pricing-knowledge.yaml — non-numeric,
no refresh needed.
- Result: pricing freshness check goes from 13 stale files to 0.
KB freshness automation:
- Add tools/kb_freshness.py — wrapper around kb_linter.check_freshness()
with --check, --auto-refresh, --json, --quiet modes. Bridges stale
files to their refresh tools (SKU catalog, compute domain, arch
center). Wired into the welcome flow as a pre-flight banner that
asks the user before refreshing.
- Fix pre-existing kb_linter bug: it crashed on the 45 multi-doc
YAML files (frontmatter + body pattern) because it used safe_load
instead of safe_load_all. Freshness check was effectively dead.
- Standardize timestamp field: linter now accepts last_verified,
last_updated, and last_refreshed; refresh_arch_catalog writes
last_verified instead of last_refreshed.
- Add make freshness / make freshness-refresh targets.
Skill alignment with Anthropic Agent Skills best practices:
- Rename `name: OCI Deal Accelerator` to `oci-deal-accelerator`
to comply with the [a-z0-9-]{1,64} spec.
- Refactor SKILL.md from 674 to 445 lines via progressive disclosure:
extract WA review output format, ECAL readiness format, and output
conventions into docs/skill/*.md referenced from the main file.
- Add scripts/sync-skill.py + make sync-skill: source of truth is
root SKILL.md, .agents/skills/oci-deal-accelerator/SKILL.md is
auto-generated. make lint validates sync.
- Add evaluations/ with 3 manual baseline scenarios (welcome-flow,
full-proposal, wa-review) per the Anthropic best-practices guidance
to "build evaluations first."
Welcome flow hardening:
- Tighten CLAUDE.md to MANDATE reading SKILL.md before showing the
menu (no improvising), and document the freshness pre-flight check
with the ask-before-refresh user flow.
- Update SKILL.md welcome flow to instruct: parse kb_freshness JSON,
show banner with stale count + oldest file, prompt user to refresh
(only when an automated tool exists), fall back silently on errors.
Linter hygiene (zero remaining issues):
- Expand config/kb-tags.yaml taxonomy with features, operations,
metrics, limitations sections covering 31 previously-unknown tags
used in field findings (rac, ecpu, refreshable-clone, hnsw, etc.).
- Assign owners for kb/compatibility/, kb/competitive/,
kb/well-architected/ (Diego Cabrera as default until team grows);
kb/pricing/ marked as "Auto-refreshed" since it no longer needs
human ownership.
- kb_linter accepts top-level `date` as fallback for contributor
block; migrate FF-202603-008 from legacy `reported_by` to
contributor block.
- Result: linter goes from 45 issues to 0.
Other:
- Recompute estimation_helpers monthly values in compute.yaml after
the price refresh (they were derived from the old E5/A1 numbers).
- Add kb/README.md — contributor guide (directory map, frontmatter
spec, refresh tooling, review cadence).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
11 KiB
11 KiB
OCI Deal Accelerator
AI skill aligned with Oracle ECAL framework (Define → Design → Deliver) that compresses the OCI SA's cycle from customer discovery to architecture proposal and delivery handover — from days to hours.
Project Structure
├── SKILL.md # LLM system prompt (the skill itself)
├── AGENTS.md # Codex agent instructions (mirrors CLAUDE.md)
├── .agents/skills/oci-deal-accelerator/
│ └── SKILL.md # Codex skill definition (full skill, Codex format)
├── README.md # Project overview and quick start
├── CLAUDE.md # This file (dev guide)
├── Makefile # Build automation (make help for commands)
├── docs/ # ECAL phase guides (progressive disclosure from SKILL.md)
│ ├── define-phase.md # DEFINE phase detailed guide
│ ├── design-phase.md # DESIGN phase detailed guide
│ ├── deliver-phase.md # DELIVER phase detailed guide
│ ├── engagement-tiers.md # Tier definitions and artifact matrix
│ └── ecal-gaps-backlog.md # Remaining ECAL gaps to implement (20 items)
├── kb/ # Knowledge Base
│ ├── architecture-center/ # Oracle Architecture Center reference catalog
│ │ └── catalog.yaml # 123 curated reference architectures
│ ├── services/ # One YAML per OCI service (what, when, gotchas)
│ ├── patterns/ # Composable architecture blocks
│ │ ├── business-patterns.yaml # Business-level patterns (DEFINE)
│ │ ├── application-patterns.yaml # Application architecture patterns (DESIGN)
│ │ ├── service-tiering.yaml # Service tier model (Platinum/Gold/Silver/Bronze)
│ │ ├── architecture-principles.yaml # ECAL principles (Design/Deployment/Service)
│ │ ├── operational-raci.yaml # RACI matrix templates (3 operational models)
│ │ ├── engagement-raci.yaml # ECAL engagement RACI (10 roles, all 9 steps)
│ │ ├── business-drivers.yaml # 4-pillar business drivers + hypothesis families
│ │ ├── ecal-artefacts-catalog.yaml # Complete ECAL 3.1 artefacts catalog (60 items)
│ │ ├── environment-catalogue.yaml # Environment templates per tier
│ │ ├── database-ha-adb-s.yaml
│ │ ├── database-dr-cross-region.yaml
│ │ ├── networking-basic.yaml
│ │ └── (dirs: database-ha/, database-dr/, networking-hub-spoke/, etc.)
│ ├── sizing/ # CPU conversion ratios, IOPS, scaling rules
│ ├── pricing/ # Auto-refreshed from Oracle public pricing API
│ │ ├── oci-sku-catalog.yaml # 200+ OCI SKUs across 20 categories (BOM source of truth)
│ │ └── compute.yaml # Shape-level estimation pricing
│ ├── competitive/ # AWS/Azure/GCP service mapping
│ ├── well-architected/ # 5-pillar WA Framework checklists
│ ├── compatibility/ # Feature matrices (ADB, etc.)
│ ├── diagram/ # Diagram styles (OCI Toolkit v24.2)
│ └── field-knowledge/ # Real-world gotchas and lessons learned
├── tools/ # Python tooling
│ ├── oci_deck_gen.py # .pptx slide deck generator (DEFAULT output)
│ ├── oci_pdf_gen.py # .pdf customer-facing document (branded, no internal refs)
│ ├── oci_diagram_gen.py # .drawio diagram generator
│ ├── oci_bom_gen.py # .xlsx Bill of Materials generator (SA tool)
│ ├── oci_output.py # Output orchestrator
│ ├── refresh_sku_catalog.py # SKU catalog refresh from Oracle pricing API
│ └── refresh_arch_catalog.py # Architecture Center catalog refresh tool
├── scripts/ # Validation and utilities
│ └── validate-architecture.py # WA validation engine
├── config/
│ ├── service-categories.yaml # Service → color/category mapping
│ ├── output-formats.yaml # Output format specs and design standards
│ ├── engagement-tiers.yaml # Tier definitions (small/standard/complex)
│ ├── workload-profile-schema.yaml # Workload profile field definitions
│ └── oracle-pptx-layouts.yaml # Oracle FY26 POTX layout mapping for deck generation
├── templates/ # ECAL phase templates
│ ├── Oracle_PPT-template_FY26.pptx # Official Oracle FY26 PowerPoint template
│ ├── workload-profile.yaml # DEFINE: Discovery capture
│ ├── customer-profile.yaml # DEFINE: Strategic customer profiling (internal)
│ ├── strategy-map.yaml # DEFINE: Goals→Strategies→Capabilities→Enablers
│ ├── discovery-questionnaire.yaml # DESIGN: Structured customer IT collection
│ ├── business-case.yaml # DEFINE: Business case for customer approval
│ ├── value-story.yaml # DEFINE: Business value hypothesis
│ ├── joint-engagement-plan.yaml # DEFINE: Engagement scoping
│ ├── scorecard.yaml # DESIGN: WA validation results
│ ├── adr-template.md # DESIGN: Architecture Decision Records
│ ├── operations-model.yaml # DESIGN: Day-2 operations design
│ ├── handover-document.yaml # DELIVER: Implementation handover
│ ├── go-live-checklist.yaml # DELIVER: Pre-cutover verification
│ ├── success-criteria.yaml # DELIVER: Post go-live metrics
│ ├── lessons-learned.yaml # DELIVER: Engagement retrospective
│ └── bom-spec.yaml # SA TOOL: BOM input spec template
├── codex/ # Codex setup guide (README only)
└── examples/ # Example specs and generated outputs
ECAL-Aligned Workflow
DEFINE (Ideate → Validate → Plan) → DESIGN (Current → Future → Confirm) → DELIVER (Adopt → Operate → Improve)
- DEFINE: Discovery notes → Workload Profile + Value Story + Joint Engagement Plan
- DESIGN: Current state (people/process/tech) → Architecture + Operations Model → Solution Proposal
- DELIVER: Handover Document → Go-Live Checklist + Success Criteria → Lessons Learned
Phase details in docs/ — SKILL.md references them via progressive disclosure.
Output Formats
Default output is a slide deck (.pptx) — adapts to engagement tier (6-8 / 10-12 / 12-16 slides).
deck ← default
deck + drawio ← + editable diagram
deck + doc ← + technical document
deck + xlsx ← + cost spreadsheet
deck + pdf ← + customer-facing PDF (branded, no internal refs)
pdf ← customer PDF only
full ← everything (pptx + drawio + docx + xlsx + pdf)
doc only ← technical doc without slides
deliver ← handover + go-live checklist + success criteria
Running Tools
# Generate slide deck (default output)
python tools/oci_deck_gen.py --spec examples/proposal-spec.yaml --output proposal.pptx
# Generate customer-facing PDF (branded, no internal KB refs)
python tools/oci_pdf_gen.py --spec examples/proposal-spec.yaml --output proposal.pdf
python tools/oci_pdf_gen.py --spec examples/proposal-spec.yaml --output proposal.pdf --diagram arch.png
# Generate BOM (.xlsx Bill of Materials)
python tools/oci_bom_gen.py --spec examples/bom-spec.yaml --output customer-bom.xlsx
# Generate diagram
python tools/oci_diagram_gen.py --spec examples/diagram-spec.yaml --output arch.drawio
# Run WA validation
python scripts/validate-architecture.py \
--profile examples/sample-workload-profile.yaml \
--architecture examples/sample-architecture.yaml \
--output scorecard.yaml
# Output orchestrator (multiple formats at once)
python tools/oci_output.py --spec examples/proposal-spec.yaml --format full --output-dir output/
# Refresh SKU catalog from Oracle pricing API
python tools/refresh_sku_catalog.py --refresh # update all prices
python tools/refresh_sku_catalog.py --refresh --diff # update + show changes
python tools/refresh_sku_catalog.py --validate # check for stale prices
python tools/refresh_sku_catalog.py --sku B110627 # inspect single SKU
# Refresh Architecture Center catalog
python tools/refresh_arch_catalog.py --whats-new # crawl What's New pages
python tools/refresh_arch_catalog.py --url <url> # add single entry
python tools/refresh_arch_catalog.py --validate # validate catalog
# Build automation
make help # show all commands
make full # generate all outputs
make validate # run WA validation
make lint # check YAML syntax
Key Principles
- Empirical over theoretical — cite metrics, not marketing
- Simplicity first — complexity must be earned
- Honest about limitations — acknowledge OCI gaps
- Composable — patterns combine, not monolithic templates
- KB is the moat — field experience, not documentation regurgitation
- ECAL-aligned — Define → Design → Deliver with iterative checkpoints
Welcome Flow
When the user starts a conversation without providing discovery notes or a specific request (e.g., a greeting like "hola", "hey", or empty context):
MANDATORY: Use the Read tool to open SKILL.md and read the entire ## Welcome Flow section before showing anything to the user. Reproduce the welcome banner and the 14-option capability menu verbatim from that file. Do NOT paraphrase, reorder, summarize, translate, or reconstruct the menu from memory, folder structure, or prior conversations. If SKILL.md cannot be read for any reason, tell the user instead of improvising a menu.
Pre-flight check (also defined in SKILL.md): Before showing the welcome message, run python tools/kb_freshness.py --check --json. If stale_count > 0, follow the banner-and-prompt logic in SKILL.md § Welcome Flow → Pre-flight. If the tool errors, silently skip the banner — never block the user.
Then:
- Show the welcome banner and numbered capability menu exactly as defined in SKILL.md (14 options across DESIGN & PROPOSE, VALIDATE & CHECK, STRATEGY & BUSINESS, KNOWLEDGE BASE, ECAL GOVERNANCE, SA TOOLS)
- Follow the behavior rules in SKILL.md for each option (1-14)
- After completing any task, offer the next-step menu (A-E) as defined in SKILL.md
- If the user sends discovery notes directly, skip the menu and go straight to full proposal flow
- If the user asks a specific question, skip the menu and answer directly