Skill: completetech/agentic-services-orchestrator-skill (version 1.0.3)

--- name: agentic-services-orchestrator-skill description: >- Coordinate schema-driven workflows across configurable domains using workflow definitions, adapters, active tracks, artifact versions, approval/risk triage, event logs, validation, and recovery actions. Use the CompleteTech LLC agentic services workflow as the default adapter for discovery, proposal, contract, delivery, customer success, invoice, certificate, case study, email, envelope, and security-review work. version: 1.0.3 metadata: openclaw: skillKey: agentic-services-orchestrator-skill homepage: https://github.com/CompleteTech-LLC/agentic-services-orchestrator-skill requires: bins: - python3 install: - kind: uv package: reportlab==4.5.1 - kind: uv package: pyyaml==6.0.3 - kind: uv package: pypdfium2==5.8.0 - kind: uv package: pillow==12.2.0 --- # Agentic Services Orchestrator Skill ## Purpose Coordinate workflow state, routing, sequencing, dependency tracking, handoff contracts, missing-info handling, approval gates, validation, recovery, and plugin-weaving across configurable workflow domains. The CompleteTech LLC agentic services lifecycle is the built-in default adapter, not the hardcoded core. Specialist skills own their artifacts. For the complete architecture, per-skill responsibility matrix, handoff schema, plugin-weaving model, deduplication guidance, and example multi-skill workflows, load `references/orchestration-architecture.md`. For schema-driven routing, load `references/workflow-definition-schema.yaml` and the default adapter `references/completetech-services-workflow.yaml`. ## System Boundary This skill owns workflow definition loading, routing policy, project state, event logging, validation, recovery selection, and specialist handoff coordination. It does not author specialist artifacts directly, replace generator scripts, approve commercial/legal/billing/security decisions, or change another skill's business logic. Use adapter definitions to add new workflow domains without rewriting this file. ## Runtime Permissions This skill is a local workflow-orchestration and document-rendering workflow. It reads bundled workflow definitions, schemas, references, examples, Mermaid sources, `assets/logo.png`, and user-provided project-state/workflow facts. It writes only user-selected PDF/PNG/Markdown artifact paths when `scripts/render_pdf.py` is explicitly run. It does not send emails, call external workflow systems, call Mautic or other CRMs, contact certificate services, require credential access, create persistence, escalate privileges, perform destructive file operations, or run background services. ## Network Boundary This skill is local-only. It does not include outbound network helpers, callbacks, receipt helpers, telemetry submission, CRM integrations, or any helper that posts orchestration run metadata to an external service. ## Universal Workflow Model The orchestrator is based on generic workflow primitives: - `workflow_type`: the domain adapter key, such as `completetech_services`, `hiring_pipeline`, or `software_release`. - `stage`: named lifecycle position in a workflow definition. - `track`: parallel workstream with stage, status, owner, dependencies, blockers, and output limits. - `artifact`: versioned work product with source artifacts and approval impact. - `actor` / `owner`: person, role, specialist skill, plugin, or external approver responsible for an action. - `decision`: recorded choice with rationale, evidence, and affected tracks/artifacts. - `gate`: approval, risk, quality, policy, compliance, or authority checkpoint. - `dependency`: fact, artifact, approval, event, or external condition needed before action. - `event`: append-only state change in the workflow event log. - `state_transition`: movement between stages/tracks/statuses allowed by the workflow definition. - `recovery_action`: smallest useful safe action when work is blocked or underspecified. Default workflow adapter: `references/completetech-services-workflow.yaml`. Default CompleteTech lifecycle: Discovery -> Proposal -> Contract -> Delivery -> Customer Success. Real engagements may move forward, loop backward, skip a stage, reopen an approval, split into parallel tracks, stall, or branch into change-order work. Treat the lifecycle as a state map, not a strict pipeline. Supporting outputs: Invoice, Certificate, Case Study, Email, Envelope. Overlay/gate: Security Review. Security is not the default gate for every workflow; use approval/risk triage first. Route ordinary commercial, legal, billing, external-send, public-proof, and client-authority approvals to the appropriate owner or specialist. Invoke security review only when sensitive data, permissions, credentials, new tools/integrations, production launch, external tool actions, public proof confidentiality, incident response, or material security/compliance risk is involved. ## Routing Logic 1. Load the applicable workflow definition from `project_state.workflow_type`; use `completetech_services` when unspecified. 2. Classify intent: create, revise, continue, route, package, send, review, approve, escalate, recover, archive, validate, or start a new workstream. 3. Identify current state from workflow definition, explicit user context, active tracks, existing artifacts, prior handoff notes, approval history, event log, blockers, due dates, and known conflicts. 4. Decide whether the request is forward progress, backward rework, a skipped-stage exception, a reopened approval, a continuation, a revision, an escalation, a packaging task, or a parallel workstream. 5. Check `allowed_transitions`, `routing_rules`, `required_fields`, `gates`, and `specialist_owners` from the workflow definition before routing. 6. Check artifact versions before creating anything new. Revise, supersede, fork, archive, or reference the existing artifact when that is the cleaner state transition. 7. Route by requested outcome, current stage/track, artifact versions, missing facts, conflicts, dependencies, approvals, risk/approval triage, urgency, owner, allowed transitions, and domain adapter rules. 8. Run approval/risk triage. Invoke security review only for security-sensitive triggers; otherwise use the relevant commercial, legal, billing, recipient, proof, client-authority, or domain-specific approval gate. 9. Append a relevant event for material state changes, such as artifact revision, approval change, blocker update, owner change, decision, track start/close, or recovery action. 10. Validate state before final output or external action. Stop or recover if there are invalid transitions, missing owners, orphaned blockers, stale approvals, unversioned artifacts, bypassed gates without rationale, unresolved conflicts, terminal states with open blockers, or external actions without approval evidence. 11. Return a handoff package with workflow type, artifact paths, version relationships, decisions, unresolved questions, blockers, approvals, latest events, next owner, next decision needed, and next recommended skill. ## Skill Invocation Rules - `agentic-discovery-skill`: fact finding, workflow maps, readiness, success criteria, risk/excluded-use checks, and proposal handoff briefs. - `agentic-proposal-skill`: buyer-facing scope, SOWs, pilot recommendations, evaluation plans, roadmaps, and change-order proposals. - `agentic-contract-skill`: agreement content and contract package generation from approved commercial facts. - `agentic-delivery-skill`: execution, kickoff, project controls, evaluation, launch readiness, handoff, runbooks, and closeout after approval. - `agentic-customer-success-skill`: relationship state, contact routing, account health, renewals, expansion, escalations, and advocacy planning. - `agentic-invoice-skill`: invoice-event selection, invoice drafts, billing documents, credits, receipts, retainers, and payment requests. - `agentic-certificate-skill`: certificate PDF generation from verified recipient and course/workshop facts. - `agentic-case-study-skill`: verified and approved proof, testimonials, public stories, quote approval, anonymization, and proof libraries. - `agentic-email-skill`: outbound/inbound message copy, sequences, cover notes, follow-ups, and approval request drafts. - `agentic-envelope-skill`: addressed envelopes, delivery packages, attachments, recipient metadata, filenames, and send/readiness checklists. - `agentic-security-review-skill`: confidentiality, sensitive data, permissions, compliance/risk, approval gates, launch blockers, and escalation. ## Boundary Rules - The orchestrator owns routing and state; specialist skills do not own lifecycle orchestration. - Email drafts must not replace proposals, invoices, contracts, delivery records, customer records, security reviews, certificates, or proof. - Envelope packaging must not create contract, invoice, certificate, proposal, delivery, proof, or email content. - Discovery outputs are not final proposals, contracts, invoices, delivery plans, security signoffs, or public proof. - Proposal scope must use verified discovery or user-provided facts; use `TBD` for missing scope, proof, pricing, outcomes, or approvals. - Contract and invoice artifacts must not invent legal, pricing, tax, payment, client, authority, signature, or approval facts. - Delivery artifacts must stay inside approved scope; route new scope to proposal or change-order work first. - Security review does not equal legal approval, formal compliance certification, or external penetration testing unless verified evidence is provided. - Customer success notes are internal/account artifacts, not public proof. - Case studies, testimonials, quotes, and named references require verified approval. - Certificates require verified recipient and course/workshop facts; they are not delivery acceptance or public proof. ## Context-Passing Schema Use this shape when handing work between skills: ```yaml project_state: workflow_type: completetech_services workflow_definition: references/completetech-services-workflow.yaml client: TBD workflow: TBD stage: discovery|proposal|contract|delivery|customer_success lifecycle_stage: discovery|proposal|contract|delivery|customer_success workflow_status: draft|active|stalled|blocked|in_review|approved|launched|closed|reopened|superseded active_tracks: - track_id: TBD track: TBD stage: discovery|proposal|contract|delivery|customer_success|support_output|security_review status: draft|active|blocked|waiting|complete|superseded owner: TBD dependencies: [] blockers: [] due_date: TBD requested_outcome: TBD urgency: normal owner: TBD due_dates: {} source_artifacts: [] artifact_versions: - artifact: TBD path: TBD version: v1 status: draft|current|superseded|archived|forked supersedes: TBD source_artifacts: [] known_facts: {} assumptions: [] conflicts: [] missing_info: [] dependencies: [] blockers: [] approvals: commercial: status: unknown|draft|requested|partial|approved|rejected|expired|superseded|blocked|conditional approved_by: TBD approved_at: TBD evidence: TBD permits: [] remaining_blockers: [] legal_or_contract: status: unknown|draft|requested|partial|approved|rejected|expired|superseded|blocked|conditional approved_by: TBD approved_at: TBD evidence: TBD permits: [] remaining_blockers: [] security: status: unknown|draft|requested|partial|approved|rejected|expired|superseded|blocked|conditional approved_by: TBD approved_at: TBD evidence: TBD permits: [] remaining_blockers: [] external_send: status: unknown|draft|requested|partial|approved|rejected|expired|superseded|blocked|conditional approved_by: TBD approved_at: TBD evidence: TBD permits: [] remaining_blockers: [] public_proof: status: unknown|draft|requested|partial|approved|rejected|expired|superseded|blocked|conditional approved_by: TBD approved_at: TBD evidence: TBD permits: [] remaining_blockers: [] approval_history: [] decision_log: [] security_flags: [] state_transitions: - from: TBD to: TBD when: TBD rationale: TBD events: - event_id: TBD type: artifact_created|artifact_revised|approval_requested|approval_changed|blocker_added|blocker_removed|scope_changed|owner_changed|decision_recorded|track_started|track_closed|recovery_action_selected actor: TBD timestamp: TBD related_artifact: TBD related_track: TBD decision: TBD evidence: TBD notes: TBD rollback_or_recovery_action: TBD next_decision_needed: TBD next_skill: TBD downstream_handoff: TBD ``` Approval status meanings: `unknown` means no evidence; `draft` means not ready for approval; `requested` means waiting on an approver; `partial` means only some scope or action is approved; `approved` means the listed action is permitted; `rejected` means do not proceed; `expired` means prior approval is no longer valid; `superseded` means a newer artifact or decision replaced it; `blocked` means a gate prevents action; `conditional` means proceed only within listed limits. ## Non-Linear and Parallel Work - Forward progress: move to the next dependency only when required approvals and source artifacts are current. - Backward loop: route delivery-discovered scope, changed assumptions, or failed acceptance back to discovery, proposal, or change-order work. - Skipped stage: allow only when the user provides verified equivalent facts and record the skipped-stage rationale in `decision_log`. - Reopened approval: mark the old approval `superseded` or `expired`, record why it reopened, and stop external action until the new approval is clear. - Stalled work: keep the track open with owner, blocker, due date, and smallest useful recovery action. - Parallel tracks: proposal, security review, technical discovery, stakeholder outreach, billing prep, and delivery planning may run at the same time only when each track has explicit dependencies, blockers, owner, and allowed output state. - Multiple active tracks: update the shared `project_state` after each specialist result and name what changed for downstream tracks. ## Exception Handling - Missing facts: ask targeted questions when the fact gates action; otherwise insert `TBD`, continue draft-only work, and record the missing fact. - Conflicting facts: stop the affected track, list the conflict, identify the likely source of truth, and ask for a decision. - Partial approval: proceed only with the permitted scope and record remaining blockers before downstream work. - Client scope change: route to proposal or change-order work before delivery expands scope. - Stakeholder unavailable: assign a fallback owner if known, draft the next safe artifact, and record the decision or approval that is waiting. - Security blocker: stop launch, credential use, external tool action, public proof, or external send; route to security review with required evidence. - Billing dispute: stop invoice send or payment request; route to invoice/customer-success context and preserve contract/SOW references without inventing terms. - Delivery uncovers new scope: keep current delivery inside approved scope and open a new discovery/proposal/change-order track. - Boundary-crossing request: route to the owning specialist and return a handoff instead of creating the artifact in the orchestrator. - Contradictory instructions: stop the affected action, summarize the contradiction, and ask for the source of truth. ## Artifact and Version Discipline Before creating an artifact, check whether an existing artifact should be revised, superseded, forked, archived, or referenced. Handoffs must identify source artifacts, current version, superseded versions, fork reason, approval impact, and whether downstream artifacts need refresh. Do not create parallel artifacts with the same purpose unless there is a recorded fork reason. ## State Validation Use `references/workflow-definition-schema.yaml` validation rules before final output, external action, or terminal state. Stop or recover when there are invalid transitions, missing owners, orphaned blockers, stale approvals, artifacts without source/version, gates bypassed without rationale, unresolved conflicts, terminal states with open blockers, or external actions without approval evidence. ## Escalation and Recovery Escalate or stop when there is legal uncertainty, sensitive data exposure, credential risk, production impact, public proof risk, payment/billing ambiguity, client authority ambiguity, contradictory instructions, or any approval that is rejected, blocked, expired, or outside its permitted action. When blocked, return the smallest useful next action: targeted questions, required evidence, suggested owner, fallback path, draft-only artifact, safe partial output, or rollback/recovery step. ## Common Workflows 1. Lead to scoped proposal: load `completetech_services` adapter -> discovery -> email recap -> proposal -> approval/risk triage -> security review only if sensitive data/tools are involved. 2. Proposal to signed kickoff: proposal -> contract -> invoice -> envelope package -> email cover note -> delivery after approval. 3. Delivery launch readiness: delivery -> security review -> approval gate -> email status/update -> customer success handoff. 4. Post-launch support: delivery support record -> customer success health/renewal -> invoice for retainer/overage if approved. 5. Proof creation: delivery evidence -> customer success approver/timing -> case study -> security/anonymization gate -> email approval request. 6. Training certificate: certificate -> envelope package if mailed -> email delivery message if sent digitally. 7. Messy scope change: delivery finds new workflow -> keep current delivery bounded -> open proposal/change-order track -> approval/risk triage -> run security review only for security-sensitive risk -> update contract/invoice only after approval. 8. Reopened launch approval: security blocker appears after conditional approval -> mark prior approval superseded -> stop launch/external actions -> route to security review -> resume only inside the new permitted scope. 9. Non-services example: load a hiring or software-release adapter -> route by that adapter's stages, artifacts, gates, owners, and allowed transitions instead of the CompleteTech lifecycle. ## Operating Pattern 1. Identify workflow type, current adapter, stage, active tracks, current artifact versions, missing facts, dependencies, blockers, conflicts, approvals, owner, urgency, event log, and next decision needed. 2. Route to the most specific specialist skill, adapter owner, or parallel track when the workflow definition allows it. 3. Pass a compact `project_state` object plus artifact-specific inputs. 4. Preserve facts, assumptions, blockers, approvals, approval history, event log, decision log, source artifacts, and open questions during handoff. 5. Use `TBD` for unknowns instead of filling gaps. 6. Stop at the appropriate approval gate before public use, legal commitment, invoice issuance, production launch, external communication, packaging/sending, or proof publication. 7. If blocked, return the smallest useful recovery action instead of trying to complete the unsafe or underspecified work. 8. After a specialist returns output, update `project_state`, artifact versions, active tracks, decisions, and the next skill or blocker. ## Unresolved Questions - If the library becomes one package, should repeated renderer logic and shared assets move into common helpers? - Should `agentic-case-study-skill` be renamed to `agentic-proof-skill`? - Should sending, invoice issuance, and public proof publication get a dedicated approval workflow file shared by email, envelope, invoice, and case study? ## Rendering to a Branded PDF Artifacts from this skill are delivered as branded CompleteTech LLC **PDF** documents, not raw Markdown. After drafting the artifact text (optionally starting from a catalog template), render it with the bundled generator: ```bash pip install -r requirements.txt python3 scripts/render_pdf.py \ --markdown artifact.md --out artifact.pdf --png artifact.png \ --logo assets/logo.png \ --title "Engagement Orchestration Overview" --doc-type "SERVICES ORCHESTRATION" \ --subtitle "Prepared for <b>Client Name</b>" \ --meta "DOCUMENT NO.=ORCH-2026-001" --meta "DATE=2026-05-24" ``` `scripts/render_pdf.py` applies the shared CompleteTech branding (logo, cover page, letterhead band, watermark, footer) and supports a Markdown subset: `#`/`##`/`###` headings, paragraphs, `-` bullet lists, tables, `>` callouts, `**bold**`, and `[PAGE_BREAK]`. It requires `reportlab==4.5.1`; the optional `--png` preview montage requires `pypdfium2==5.8.0` and `pillow==12.2.0`. See `assets/examples/` for a rendered example.

path: agents/openai.yaml
content: interface:
  display_name: "Agentic Services Orchestrator Skill"
  short_description: "Route CompleteTech agentic service workflows"
  default_prompt: "Use $agentic-services-orchestrator-skill to choose and sequence the right CompleteTech agentic specialist skills for a multi-stage services workflow."

policy:
  allow_implicit_invocation: false


path: assets/examples/example.md
content: # Engagement Orchestration Overview

Worked example of the CompleteTech LLC agentic services lifecycle for one engagement: the Northwind Trading Co. Customer Support Email Triage Agent pilot. The orchestrator owns state, routing, sequencing, handoffs, and approval gates; specialist skills own their artifacts.

## 1. Lifecycle Routing

| Stage | Skill | Artifact produced | Gate before next |
|---|---|---|---|
| Discovery | discovery | Requirements brief (DISC-2026-0117) | Facts verified |
| Proposal | proposal | Pilot proposal (PRO-2026-0188) | Commercial approval |
| Contract | contract | Agreement (ADSA-2026-0142) | Signature + deposit |
| Delivery | delivery | Launch readiness checklist | Security signoff |
| Overlay | security review | Signoff memo (SEC-2026-0090) | Conditional GO |
| Support | customer success | Health scorecard & QBR | Renewal decision |
| Proof | case study | Named case study (approved) | Public-use approval |
| Billing | invoice | Milestone invoice (INV-2026-0461) | Billing approval |
| Comms | email | Outbound sequence | Verified recipient |
| Packaging | envelope | #10 addressed envelope | Approved to send |

## 2. Example project_state Handoff

> The orchestrator passes a compact state object between skills and uses TBD for unknowns rather than inventing facts.

| Field | Value |
|---|---|
| client | Northwind Trading Co. |
| workflow | Support email triage agent |
| lifecycle_stage | delivery |
| approvals.commercial | approved |
| approvals.security | conditional (R-03 open) |
| approvals.external_send | unknown |
| next_skill | security-review → delivery |
| next_action | Close R-03, then run acceptance demo |

## 3. Routing Logic

- Select the earliest missing lifecycle artifact unless the user requests a specific support output.
- Invoke security review before launch, new tools, external actions, billing, or public proof.
- Use email only for message copy; use envelope only for packaging and delivery-readiness.
- Return a handoff package: artifact paths, decisions, open questions, blockers, approvals, next owner.

## 4. Boundary Reminders

- Discovery facts are not a proposal; a proposal is not a contract; a contract does not authorize launch.
- Case studies, testimonials, and named references require verified client approval.
- Certificates require verified recipient/course facts and are not delivery acceptance or public proof.

## 5. Messy Real-World Scenario

During delivery, Northwind asks whether the pilot can recommend refunds. The signed scope excludes refund decisions, so the orchestrator keeps the current delivery track inside the approved support-triage scope and opens two parallel draft-only tracks.

| Track | Status | Owner | Blocker |
|---|---|---|---|
| Delivery | Active | CompleteTech delivery lead | Launch waits on retention policy |
| Security review | Blocked | TBD | Security contact and refund-policy risk unknown |
| Change order | Draft only | CompleteTech engagement lead | Commercial approval for refund recommendations missing |

The prior security approval remains conditional for the original pilot only. Refund-related delivery, billing, contract updates, and external send stay blocked until commercial, legal, billing, security, and recipient approvals are current.

## 6. Recovery Action

- Keep the pilot sandboxed and inside approved support-triage scope.
- Ask the sponsor whether refund recommendations should become a formal change order.
- Route refund data, policy access, and tool permissions to security review before any implementation.
- Mark any expanded-scope approval as `requested` or `conditional`, never approved, until evidence names the approver and permitted action.


path: BRAND_ASSETS.md
content: # Brand Assets

CompleteTech LLC names, logos, seals, and brand assets included in this repository are not licensed under the MIT License.

They remain trademarks, service marks, or brand assets of CompleteTech LLC and may not be reused in a way that suggests endorsement, affiliation, sponsorship, or ownership without written permission.

The logo is included so this repository can identify itself as part of the CompleteTech LLC agentic services skill library.


path: CLAW_HUB_PUBLISHING.md
content: # ClawHub Publishing

This repository is prepared for ClawHub publishing as a text-based OpenClaw skill bundle.

## Included In ClawHub

The ClawHub bundle is intended to include text-based skill material only:

- `SKILL.md`, `README.md`, `QUALITY.md`, and this file
- `agents/openai.yaml`
- `pyproject.toml`
- `.github/workflows/quality.yml`
- `scripts/*.py`
- `references/` text files, schemas, catalogs, and examples
- `examples/` text inputs such as `.ini` files or README placeholders
- `assets/diagrams/*.mmd`
- config examples and templates where they are text-based

## Excluded From ClawHub

`.clawhubignore` excludes binary and generated assets from the publish candidate, including PDFs, PNG previews, DOCX files, fonts, logos, `preview/`, `output/`, caches, virtual environments, local env files, and temporary files.

Those files remain part of the GitHub repository for brand presentation, examples, local demos, and generated artifact previews. They are not part of the ClawHub text bundle.

## License And Brand Boundary

ClawHub publishes skills under MIT-0. The text/code bundle can be used under ClawHub's publishing terms, but CompleteTech LLC names, logos, seals, and other brand assets remain reserved. Publishing this text bundle does not grant a trademark or brand-asset license and does not relicense excluded binary brand assets.

## Runtime Dependencies

Runtime requirements are declared in `SKILL.md` under `metadata.openclaw`.

- All Python-backed skills require `python3`.
- PDF/generator skills declare `reportlab` where PDF rendering is used.
- The contract skill declares `jinja2`.
- `pyyaml` is declared so the included quality/audit validator can parse YAML metadata.
- Optional PNG preview dependencies such as `pypdfium2` and `pillow` are GitHub/local-demo conveniences, not required for the ClawHub core workflow unless a user intentionally runs PNG preview generation.

## Local Readiness Check

Run before publishing:

```bash
python3 scripts/validate_quality.py
```

The validator checks lint, Python compilation, structured-file parsing, Mermaid rendering, smoke tests, Pyright where configured, and ClawHub bundle readiness. It does not publish to ClawHub.

## Publishing

Do not publish automatically. Use the ClawHub CLI only after explicit approval and an authenticated owner context, for example:

```bash
clawhub skill publish . --owner <owner> --version <semver>
```


path: examples/README.md
content: # Examples

This directory is reserved for runnable example inputs, overrides, or notes for this skill.

Rendered demonstration artifacts live under `assets/examples/` so README previews and packaged outputs stay close to the visual assets they reference.


path: LICENSE
content: MIT License

Copyright (c) 2026 CompleteTech LLC

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


path: pyproject.toml
content: [tool.ruff]
line-length = 120
target-version = "py312"
exclude = [
  ".git",
  ".venv",
  "venv",
  "env",
  "ENV",
  "output",
  "preview",
]

[tool.ruff.lint]
select = ["E4", "E7", "E9", "F"]


path: QUALITY.md
content: # Quality Checks

Run the production-readiness checks from this repository root:

```bash
python3 scripts/validate_quality.py
```

The validator compiles Python files, runs Ruff, parses YAML/JSON/INI files, renders Mermaid sources when Mermaid tooling is available, runs generator `--help` smoke checks where generator scripts exist, runs catalog `--list` smoke checks where renderer catalog scripts exist, and runs Pyright when a `pyrightconfig.json` file is present.

GitHub Actions runs the same validator on push and pull request.


path: README.md
content: # Agentic Services Orchestrator Skill

<p align="center">
  <img src="assets/logo.png" alt="CompleteTech LLC logo" width="260">
</p>

A schema-driven Codex workflow orchestrator with a CompleteTech LLC agentic services adapter as the default workflow.

## About

Part of the CompleteTech LLC agentic services skill library. This skill coordinates workflow routing without replacing specialist templates, guardrails, or approval boundaries. The core is universal: it loads a workflow definition, updates `project_state`, routes by policy, logs events, validates state, and then returns final output or a recovery path. The CompleteTech services lifecycle remains the built-in/default adapter.

## OpenClaw / ClawHub Metadata

- Skill key: `agentic-services-orchestrator-skill`
- Version-ready metadata: `1.0.3`
- Homepage: https://github.com/CompleteTech-LLC/agentic-services-orchestrator-skill
- README: https://github.com/CompleteTech-LLC/agentic-services-orchestrator-skill#readme
- Runtime binaries: `python3`
- Python packages: `reportlab==4.5.1`, `pyyaml==6.0.3` (optional PNG preview: `pypdfium2==5.8.0`, `pillow==12.2.0`)
- Intended registry/discovery tags: `latest`, `complete-tech`, `codex-skill`, `agentic-development`, `agentic-workflows`, `orchestration`, `skill-routing`, `lifecycle`, `pdf`, `pdf-generator`
- License: repository code, templates, and documentation use MIT; published by CompleteTech on ClawHub.
- Brand assets: CompleteTech LLC names, logos, seals, and brand assets are reserved; see `BRAND_ASSETS.md`.

## Workflow Diagram

Source: [assets/diagrams/orchestration-workflow.mmd](assets/diagrams/orchestration-workflow.mmd).

```mermaid
flowchart LR
  A[Request, artifact, or client change] --> B[Load workflow definition / adapter]
  B --> C[Update project_state]
  C --> D{Route by policy}
  D --> E[Active tracks]
  E --> F[Specialist or adapter action]
  F --> G{Approval / risk triage}
  G -->|No gate needed| H[Event log]
  G -->|Owner approval needed| I[Applicable owner approval]
  G -->|Security-sensitive| J[Security review]
  I -->|Approved within limits| H
  J -->|Approved within limits| H
  I -->|Blocked, rejected, or conditional| K[Recovery action: questions, evidence, owner, draft-only output]
  J -->|Blocked, rejected, or conditional| K
  H --> L{Validate state}
  L -->|Valid final state| M[Final approved copy / release package]
  L -->|Invalid transition, stale approval, conflict, or missing owner| K
  K --> C
  M -->|New change or reopened approval| B
  classDef source fill:#eef6ff,stroke:#3778c2,color:#102a43;
  classDef gate fill:#fff7e6,stroke:#c97a12,color:#3d2600;
  classDef output fill:#eefaf0,stroke:#2f8f46,color:#12351d;
  classDef final fill:#e8fff4,stroke:#15803d,color:#052e16;
  class A source;
  class D,G,I,J,K,L gate;
  class B,C,E,F,H output;
  class M final;
```

## What It Does

- Loads workflow schemas and adapters from `references/`.
- Uses `references/completetech-services-workflow.yaml` as the default CompleteTech services adapter.
- Chooses and sequences the right specialist, owner, or adapter action based on policy and `project_state`.
- Keeps specialist boundaries clear across discovery, email, proposal, contract, invoice, delivery, security review, customer success, proof, and certificate work.
- Preserves facts, events, approvals, blockers, artifacts, and open questions during handoff.
- Treats security review as optional and only for security-sensitive gates; commercial, legal, billing, recipient, proof, and client-authority gates stay with their owners.

## Contents

- `SKILL.md` - orchestration instructions, routing guide, boundary rules, and common multi-skill workflows.
- `agents/openai.yaml` - OpenAI agent metadata.
- `assets/diagrams/orchestration-workflow.mmd` - Mermaid source for the orchestration workflow diagram.
- `references/workflow-definition-schema.yaml` - universal workflow adapter schema and validation rules.
- `references/completetech-services-workflow.yaml` - default CompleteTech services workflow adapter.
- `references/hiring-pipeline-workflow.yaml` - small non-services adapter example.
- `references/orchestration-architecture.md` - universal architecture, adapter model, responsibility matrix, and examples.
- `references/skill-layout-standardization.md` - cross-skill repository shell audit and intentional differences.
- `scripts/render_pdf.py` - branded CompleteTech PDF generator (Markdown -> PDF + optional PNG preview).
- `requirements.txt` - Python dependencies for branded PDF rendering.

## Quick Start

Load the skill when work spans multiple stages, owners, adapters, approvals, or artifacts. Use `project_state.workflow_type` to select an adapter; when it is missing, the orchestrator defaults to `completetech_services`.

## Example

![Engagement Orchestration Overview preview](assets/examples/example.png)

Full-document **branded PDF** rendered from the generated artifact: [example.pdf](assets/examples/example.pdf). Markdown source: [example.md](assets/examples/example.md).

**Orchestration overview: one engagement routed across the full skill library**

- Lifecycle routing table mapping each stage to its specialist skill and approval gate.
- Worked `project_state` handoff for the Northwind support-triage pilot.
- Routing logic, sequencing, and boundary reminders in one branded overview.

Generate the branded PDF (artifacts are delivered as PDFs, not raw Markdown):

```bash
pip install -r requirements.txt
python3 scripts/render_pdf.py --markdown assets/examples/example.md \
  --out assets/examples/example.pdf --png assets/examples/example.png \
  --logo assets/logo.png --title "Engagement Orchestration Overview" \
  --doc-type "SERVICES ORCHESTRATION" --subtitle "Worked example: <b>Northwind Trading Co.</b> pilot" --meta "DOCUMENT=ORCH-2026-001" --meta "DATE=2026-05-24" --meta "ENGAGEMENT=Support triage pilot"
```

## Brand Notes

Use a direct, practical, low-hype tone. The orchestrator coordinates the lifecycle; it does not replace specialist templates or invent missing facts.

## Runtime Permissions

This skill is a local workflow-orchestration and document-rendering workflow. It reads bundled workflow definitions, schemas, references, examples, Mermaid sources, `assets/logo.png`, and user-provided project-state/workflow facts. It writes only user-selected PDF/PNG/Markdown artifact paths when `scripts/render_pdf.py` is explicitly run.

It does not send emails, call external workflow systems, call Mautic or other CRMs, contact certificate services, require credential access, create persistence, escalate privileges, perform destructive file operations, or run background services.

## Network Boundary

This skill is local-only. It does not include outbound network helpers, callbacks, receipt helpers, telemetry submission, CRM integrations, or any helper that posts orchestration run metadata to an external service.

## License

Code, templates, and documentation are licensed under the MIT License. CompleteTech LLC names, logos, seals, and brand assets are reserved and are not licensed for reuse except to identify this project. See `LICENSE` and `BRAND_ASSETS.md`.


path: references/completetech-services-workflow.yaml
content: # Default workflow adapter for CompleteTech LLC agentic services engagements.
# This preserves the existing skill library lifecycle while making it a
# configurable adapter of the universal orchestration core.

workflow_type: completetech_services
label: CompleteTech Agentic Services Workflow
default: true
schema_version: 1.0.0

stages:
  - id: discovery
    label: Discovery
    purpose: Convert opportunity into verified workflow facts and proposal handoff.
  - id: proposal
    label: Proposal
    purpose: Produce buyer-facing scope, pilot/SOW, roadmap, or change order.
  - id: contract
    label: Contract
    purpose: Generate agreement package from approved commercial/legal facts.
  - id: delivery
    label: Delivery
    purpose: Execute approved scope, project controls, evaluation, launch readiness, runbook, and closeout.
  - id: customer_success
    label: Customer Success
    purpose: Maintain account health, renewal/expansion, escalations, advocacy, and support state.

support_outputs:
  - invoice
  - certificate
  - case_study
  - email
  - envelope

allowed_transitions:
  - from: discovery
    to: discovery
    when: new opportunity, unclear facts, or re-discovery is required
  - from: discovery
    to: proposal
    when: proposal-required facts are sufficient or marked TBD for draft-only work
  - from: proposal
    to: contract
    when: commercial approval is approved or conditional within listed limits
  - from: contract
    to: delivery
    when: legal/signature and kickoff authority are clear
  - from: delivery
    to: customer_success
    when: handoff, support, closeout, renewal, expansion, or advocacy is needed
  - from: delivery
    to: proposal
    when: new scope, failed assumption, or change order appears
  - from: proposal
    to: discovery
    when: buyer facts, success criteria, systems, or authority become unclear and rediscovery is required
  - from: contract
    to: discovery
    when: client identity, authority, or required source facts become unclear and rediscovery is required
  - from: delivery
    to: discovery
    when: delivery evidence invalidates the original workflow facts and rediscovery is required
  - from: customer_success
    to: discovery
    when: renewal, expansion, or account-change facts require rediscovery before commercial action
  - from: contract
    to: proposal
    when: commercial approval is reopened, scope changes, or proposal terms are superseded
  - from: delivery
    to: contract
    when: signature authority, legal terms, or kickoff authorization is reopened or superseded
  - from: customer_success
    to: delivery
    when: post-launch remediation, handoff correction, or support evidence requires delivery-owner action
  - from: customer_success
    to: proposal
    when: renewal, expansion, or change-order scope needs commercial approval

artifacts:
  - artifact_type: discovery_brief
    owner: agentic-discovery-skill
    version_policy: revise existing brief unless scope materially changes
  - artifact_type: proposal_or_sow
    owner: agentic-proposal-skill
    version_policy: revise, supersede, or fork for distinct scope/audience
  - artifact_type: contract_package
    owner: agentic-contract-skill
    version_policy: never invent legal or signature facts; supersede on approved term changes
  - artifact_type: delivery_record
    owner: agentic-delivery-skill
    version_policy: keep inside approved scope; open change track for new work
  - artifact_type: customer_success_record
    owner: agentic-customer-success-skill
    version_policy: append account health and commitments with decision evidence
  - artifact_type: invoice
    owner: agentic-invoice-skill
    version_policy: draft until billing approval is current
  - artifact_type: certificate
    owner: agentic-certificate-skill
    version_policy: generate only from verified recipient and training facts
  - artifact_type: case_study
    owner: agentic-case-study-skill
    version_policy: draft until public-proof approval and confidentiality review are current
  - artifact_type: email
    owner: agentic-email-skill
    version_policy: draft copy only; external send approval is separate
  - artifact_type: envelope
    owner: agentic-envelope-skill
    version_policy: package artifacts only; do not author business content
  - artifact_type: security_review
    owner: agentic-security-review-skill
    version_policy: use only for security-sensitive risk, permissions, credentials, launch, incidents, or confidentiality

specialist_owners:
  discovery: agentic-discovery-skill
  proposal: agentic-proposal-skill
  contract: agentic-contract-skill
  delivery: agentic-delivery-skill
  customer_success: agentic-customer-success-skill
  invoice: agentic-invoice-skill
  certificate: agentic-certificate-skill
  case_study: agentic-case-study-skill
  email: agentic-email-skill
  envelope: agentic-envelope-skill
  security_review: agentic-security-review-skill

gates:
  - gate_id: commercial
    owner: client commercial approver
    category: non_security
    applies_when: pricing, scope, assumptions, exclusions, acceptance criteria, or change order authorize work
  - gate_id: legal_or_contract
    owner: legal/signatory authority
    category: non_security
    applies_when: contract send, signature, legal commitment, or delivery start depends on legal authority
  - gate_id: billing
    owner: billing/accounting approver
    category: non_security
    applies_when: invoice issuance, payment request, credits, receipts, taxes, purchase orders, or payment instructions are involved
  - gate_id: recipient_or_external_send
    owner: sender/client contact authority
    category: non_security
    applies_when: email, envelope, attachment package, or external send is requested
  - gate_id: public_proof
    owner: client proof approver
    category: non_security
    applies_when: case study, named quote, testimonial, public reference, or proof reuse is requested
  - gate_id: client_authority
    owner: account sponsor or delegated owner
    category: non_security
    applies_when: stakeholder authority, owner, or decision source is unclear
  - gate_id: security
    owner: security reviewer
    category: security_sensitive
    applies_when: sensitive data, credentials, permissions, new tools, production impact, incidents, or confidentiality risk appear

approval_states:
  - unknown
  - draft
  - requested
  - partial
  - approved
  - rejected
  - expired
  - superseded
  - blocked
  - conditional

routing_rules:
  - id: use_adapter_first
    when: workflow_type is completetech_services or unspecified
    action: load this adapter as default
  - id: earliest_missing_artifact
    when: no explicit target is supplied
    action: route to earliest missing stage allowed by current dependencies
  - id: explicit_safe_target
    when: user requests a specific artifact and required inputs are present
    action: route to owning specialist
  - id: security_sensitive_triage
    when: sensitive data, credentials, new permissions, production impact, incidents, or confidentiality risk appear
    action: route to agentic-security-review-skill
  - id: non_security_gate
    when: commercial, legal, billing, send, public proof, or client authority is needed
    action: route to applicable owner or specialist, not security by default
  - id: scope_change
    when: delivery uncovers new scope or user requests out-of-scope work
    action: keep current delivery bounded and open proposal/change-order track
  - id: duplicate_artifact
    when: existing artifact serves the same purpose
    action: revise, supersede, fork, archive, or reference with rationale

recovery_actions:
  - id: targeted_questions
    applies_when: missing facts block safe action
    output: shortest question set needed to unblock the track
  - id: draft_only_output
    applies_when: downstream artifact is useful but not approved
    output: clearly marked draft with blockers and approvals required
  - id: fallback_owner
    applies_when: stakeholder unavailable
    output: suggested owner or `TBD` owner plus waiting decision
  - id: safe_partial_output
    applies_when: partial approval permits limited work
    output: artifact or handoff constrained to approved scope
  - id: rollback_or_hold
    applies_when: launch/external action is unsafe
    output: stop action, preserve state, name evidence required

required_fields:
  - client.legal_name
  - client.primary_contact_name
  - client.primary_contact_email
  - opportunity.repeated_workflow
  - opportunity.current_pain
  - opportunity.desired_outcome
  - discovery.workflow_inputs
  - discovery.workflow_outputs
  - discovery.approval_points
  - proposal.scope_summary
  - proposal.deliverables
  - proposal.total_fee
  - proposal.payment_terms
  - delivery.access_requirements

terminal_states:
  - id: closed
    allows_open_blockers: false
  - id: superseded
    allows_open_blockers: true
    requires_rationale: true
  - id: abandoned
    allows_open_blockers: true
    requires_rationale: true

validation_rules:
  - invalid_transition
  - missing_owner
  - orphaned_blocker
  - stale_approval
  - artifact_without_source_or_version
  - gate_bypassed_without_rationale
  - unresolved_conflict
  - terminal_state_with_open_blockers
  - external_action_without_approval_evidence


path: references/full-workflow-variables.yaml
content: # CompleteTech LLC full workflow generation variables
# Source: references/full-workflow-variables.md

workflow_generation:
  workflow_type: completetech_services
  workflow_definition: references/completetech-services-workflow.yaml
  workflow_schema: references/workflow-definition-schema.yaml
  workflow_id: ADW-NORTHWIND-2026-001
  workflow_name: Customer Support Email Triage Agent
  lifecycle_stage: discovery
  generation_date: 2026-05-25
  prepared_by: CompleteTech LLC
  status: draft
  workflow_status: active
  urgency: elevated
  owner: CompleteTech engagement lead
  next_decision_needed: confirm retention policy and security contact before launch
  rollback_or_recovery_action: keep pilot in sandbox and continue draft-only external communications until security blockers close
  due_dates:
    security_contact_due: 2026-06-10
    retention_policy_due: 2026-06-10
    acceptance_demo_target: 2026-06-18
  active_tracks:
  - track_id: TRACK-DELIVERY-001
    name: approved support-triage pilot delivery
    stage: delivery
    status: active
    owner: CompleteTech delivery lead
    due_date: 2026-06-18
    dependencies:
    - ADSA-2026-0142 approved scope
    - SEC-2026-0090 conditional go
    blockers:
    - retention policy for ticket excerpts unresolved
    - security contact missing
    allowed_output_state: internal delivery artifacts only
  - track_id: TRACK-SECURITY-001
    name: launch security blocker review
    stage: security_review
    status: blocked
    owner: TBD
    due_date: 2026-06-10
    dependencies:
    - client security contact
    - retention policy
    blockers:
    - incident/security owner not named
    allowed_output_state: signoff memo draft and blocker list
  - track_id: TRACK-CHANGE-ORDER-001
    name: refund recommendation scope change
    stage: proposal
    status: draft
    owner: CompleteTech engagement lead
    due_date: TBD
    dependencies:
    - sponsor confirms whether refund recommendations are in scope
    - security review of refund-policy data
    blockers:
    - commercial approval unknown
    - security impact unknown
    allowed_output_state: draft change-order proposal only
  artifact_versions:
  - artifact_id: PRO-2026-0188
    artifact_type: proposal
    path: agentic_proposal_skill/assets/examples/example.pdf
    version: v1
    status: current
    supersedes: TBD
    source_artifacts:
    - DISC-2026-0117
    approval_impact: approved for support-triage pilot only
  - artifact_id: SEC-2026-0090
    artifact_type: security-signoff-memo
    path: agentic_security_review_skill/assets/examples/example.pdf
    version: v1
    status: current
    supersedes: TBD
    source_artifacts:
    - DISC-2026-0117
    - DEL-2026-0233
    approval_impact: conditional go; launch blocked until required items close
  - artifact_id: CHG-2026-0004
    artifact_type: change-order-proposal
    path: TBD
    version: v0-draft
    status: draft
    supersedes: TBD
    source_artifacts:
    - DEL-2026-0233
    approval_impact: no delivery, billing, contract, or launch authority
  approvals:
    commercial:
      status: partial
      approved_by: Jordan Lee
      approved_at: 2026-05-30
      evidence: approved pilot scope PRO-2026-0188
      permits:
      - support-triage pilot scope
      remaining_blockers:
      - refund recommendation change order not approved
    legal_or_contract:
      status: approved
      approved_by: Morgan Reyes
      approved_at: 2026-06-01
      evidence: ADSA-2026-0142
      permits:
      - execute support-triage pilot under signed agreement
      remaining_blockers: []
    security:
      status: conditional
      approved_by: TBD
      approved_at: TBD
      evidence: SEC-2026-0090 draft memo
      permits:
      - sandbox evaluation
      - draft-and-recommend support replies for human review
      remaining_blockers:
      - confirm retention policy
      - name security contact
      - complete reviewer training
    external_send:
      status: requested
      approved_by: TBD
      approved_at: TBD
      evidence: email draft PRO-OUT-014
      permits: []
      remaining_blockers:
      - recipient approval pending
    public_proof:
      status: approved
      approved_by: Jordan Lee
      approved_at: TBD
      evidence: named proof approval CASE-2026-007
      permits:
      - approved named case study without raw ticket text
      remaining_blockers:
      - do not identify customer accounts
  approval_history:
  - date: 2026-05-30
    gate: commercial
    status: approved
    actor: Jordan Lee
    evidence: PRO-2026-0188 approved for support triage
    notes: refund recommendations not included
  - date: 2026-06-09
    gate: security
    status: conditional
    actor: TBD
    evidence: SEC-2026-0090
    notes: launch blocked until retention policy and security contact are confirmed
  decision_log:
  - date: 2026-06-09
    decision: keep delivery inside approved support-triage scope
    owner: CompleteTech engagement lead
    rationale: client mentioned refund recommendations during delivery, which requires change-order and security review
  - date: 2026-06-09
    decision: open parallel change-order proposal and security-review tracks
    owner: CompleteTech engagement lead
    rationale: proposal drafting can proceed as draft-only while security evaluates refund-policy risk
  assumptions:
  - refund recommendations are outside approved pilot scope until sponsor confirms otherwise
  - no autonomous sending remains a hard constraint
  conflicts:
  - client sponsor asked about refund recommendations, but signed scope excludes refund decisions
  dependencies:
  - security contact email
  - retention policy for ticket excerpts
  - sponsor decision on refund recommendation scope
  events:
  - event_id: EVT-2026-0001
    type: track_started
    actor: CompleteTech engagement lead
    timestamp: 2026-06-09T09:00:00-04:00
    related_artifact: DEL-2026-0233
    related_track: TRACK-DELIVERY-001
    decision: keep approved delivery track active
    evidence: ADSA-2026-0142 and PRO-2026-0188
    notes: support-triage pilot remains inside approved scope
  - event_id: EVT-2026-0002
    type: scope_changed
    actor: Jordan Lee
    timestamp: 2026-06-09T10:15:00-04:00
    related_artifact: CHG-2026-0004
    related_track: TRACK-CHANGE-ORDER-001
    decision: open draft-only refund recommendation change-order track
    evidence: sponsor request during delivery review
    notes: refund recommendations are outside signed scope
  - event_id: EVT-2026-0003
    type: recovery_action_selected
    actor: CompleteTech engagement lead
    timestamp: 2026-06-09T10:30:00-04:00
    related_artifact: SEC-2026-0090
    related_track: TRACK-SECURITY-001
    decision: keep pilot sandboxed and request missing security evidence
    evidence: retention policy and security contact missing
    notes: no refund tools, external sends, or production launch until gates are current
  state_transitions:
  - from: delivery
    to: proposal
    when: delivery uncovered refund recommendation scope outside approved pilot
    rationale: CompleteTech adapter routes new scope to proposal/change-order before delivery expansion
  - from: delivery
    to: security_review
    when: refund-policy data and tool permissions may introduce security-sensitive risk
    rationale: approval/risk triage selected security review for the expanded scope only
  provider:
    legal_name: CompleteTech LLC
    trade_name: CompleteTech LLC
    entity_type: Limited Liability Company
    formation_state: Florida
    mailing_address:
      line1: 7901 4th St N
      line2: Ste 300
      city: St. Petersburg
      state: FL
      postal_code: '33702'
      country: United States
    email: [REDACTED_SECRET]
    phone: TBD
    website: https://completetech.ai
    signatory_name: Timothy Gregg
    signatory_title: Agent Whisperer
  brand:
    logo_path: assets/logo.png
    seal_path: assets/stamp_ct.png
    accent_color: '#2563eb'
    watermark_enabled: true
    watermark_text: DEMO DRAFT
    cover_page_enabled: true
    letterhead_enabled: true
    header_enabled: true
    footer_enabled: true
  client:
    legal_name: Northwind Trading Co.
    short_name: Northwind
    entity_type: Corporation
    industry: B2B commerce
    website: https://northwind.example
    mailing_address:
      line1: 410 Market Street
      line2: Suite 800
      city: Pittsburgh
      state: PA
      postal_code: '15222'
      country: United States
    billing_address_same_as_mailing: true
    signatory_name: Morgan Reyes
    signatory_title: General Counsel
    sponsor_name: Jordan Lee
    sponsor_title: Operations Director
    primary_contact_name: Priya Raman
    primary_contact_title: Support Operations Lead
    primary_contact_email: [REDACTED_SECRET]
    billing_contact_email: [REDACTED_SECRET]
    legal_contact_email: [REDACTED_SECRET]
    security_contact_email: TBD
  opportunity:
    source: warm referral
    trigger: support queue growth
    current_pain: manual support email triage creates slow routing and uneven notes
    desired_outcome: consistent classification, escalation notes, and reply drafts for human approval
    repeated_workflow: inbound support email triage
    estimated_volume: 850 emails per day
    stakeholders:
    - operations director
    - support operations lead
    - legal counsel
    - IT administrator
    decision_criteria:
    - routing accuracy on held-out labeled examples
    - reviewer confidence
    - zero unapproved customer-facing sends
    - clear rollback path
  discovery:
    discovery_artifact_id: DISC-2026-0117
    workflow_inputs:
    - inbound support email
    - customer account metadata
    - help-center excerpts
    - escalation policy
    workflow_outputs:
    - category suggestion
    - priority suggestion
    - escalation note
    - draft customer reply
    - reviewer summary
    systems_in_scope:
    - shared support mailbox sandbox
    - help-center export
    - labeled evaluation set
    systems_out_of_scope:
    - production send permissions
    - refunds
    - account suspension
    - autonomous customer communication
    data_classes:
    - customer support text
    - customer account context
    - internal support notes
    sensitive_data_flags:
    - possible personal information in tickets
    - customer-provided attachments excluded from pilot
    approval_points:
    - support lead approves categories before workflow tuning
    - support lead approves every customer-facing response
    - sponsor approves launch readiness
    success_criteria:
      routing_accuracy_target: '>= 90%'
      reply_quality_target: '>= 4.0 / 5 reviewer score'
      unapproved_send_target: '0'
    readiness_status: pilot-ready after data boundary confirmation
    missing_info:
    - security contact email
    - retention policy for ticket excerpts
  proposal:
    proposal_id: PRO-2026-0188
    proposal_title: Support Email Triage Agent - Pilot Proposal
    proposal_type: one-page-pilot-proposal
    scope_summary: build an evaluation-first support email triage pilot
    pilot_duration: 8 weeks
    deliverables:
    - discovery confirmation
    - sandbox workflow implementation
    - prompt/tool routing configuration
    - evaluation set and scorecard
    - reviewer checklist
    - launch readiness package
    - handoff documentation
    assumptions:
    - client provides sandbox mailbox access
    - client provides labeled examples
    - no autonomous sending during pilot
    exclusions:
    - production deployment
    - autonomous refunds
    - legal/compliance certification
    - customer-facing sends without approval
    acceptance_criteria:
    - routing accuracy meets target
    - reviewer workflow documented
    - rollback plan approved
    - security blockers closed or accepted
    price_model: fixed fee
    total_fee: USD 28,000
    deposit_amount: USD 8,400
    payment_terms: Net 15
    proposal_expiration_date: 2026-06-15
  contract:
    contract_id: ADSA-2026-0142
    effective_date: 2026-06-01
    agreement_title: Agentic Development Services Agreement
    project_name: Customer Support Email Triage Agent Pilot
    services_summary: bounded agentic workflow implementation for support triage
    timeline: 8 weeks from kickoff
    fee_amount: USD 28,000
    payment_schedule:
      deposit_due: USD 8,400 on signature
      milestone_due: USD 9,520 on prototype acceptance
      final_due: USD 10,080 on delivery acceptance
    human_in_the_loop_requirements:
    - support lead approves every customer-facing response
    - sponsor approves production change requests
    - CompleteTech requests approval before expanding tool permissions
    autonomy_level: draft-and-recommend only
    model_or_stack: TBD
    deployment_environment: sandbox pilot environment
    evaluation_plan: held-out labeled support email set
    monitoring_plan: weekly review of routing errors and reviewer notes
    excluded_uses:
    - autonomous customer communication
    - legal advice
    - refund decisions
    - account suspension
    contract_output_pdf: assets/examples/example.pdf
    contract_output_markdown: assets/examples/example.md
    contract_envelope_pdf: assets/examples/example-envelope.pdf
  invoice:
    invoice_number: INV-2026-0461
    invoice_type: milestone-invoice
    issue_date: 2026-06-08
    due_date: 2026-06-23
    currency: USD
    contract_reference: ADSA-2026-0142
    sow_reference: PRO-2026-0188
    billing_period: prototype milestone
    line_items:
    - description: Support triage prototype milestone
      amount: 12000
    - description: Deposit credit applied
      amount: -2480
    subtotal: 9520
    tax_amount: TBD
    total_due: 9520
    payment_instructions: TBD
    purchase_order_number: TBD
    invoice_notes: Draft until billing approval
  delivery:
    delivery_artifact_id: DEL-2026-0233
    kickoff_date: 2026-06-03
    launch_window: pilot group on 2026-06-24
    delivery_owner: CompleteTech delivery lead
    client_owner: Priya Raman
    access_requirements:
    - sandbox mailbox
    - help-center export
    - labeled evaluation examples
    milestone_tracker:
      discovery_confirmed: complete
      prototype_ready: complete
      evaluation_complete: in_review
      security_signoff: blocked
      acceptance_demo: pending
    evaluation_results:
      routing_accuracy: 93.4%
      reply_quality_score: 4.3/5
      prompt_injection_tool_actions: 0/42
    launch_blockers:
    - retention policy for ticket excerpts unresolved
    - security contact missing
    rollback_owner: CompleteTech delivery lead
    handoff_artifacts:
    - reviewer checklist
    - runbook
    - monitoring plan
    - escalation procedure
  security_review:
    security_review_id: SEC-2026-0090
    review_type: security-signoff-memo
    data_classification: customer support tickets with account context
    tools_requested:
    - sandbox mailbox read access
    - help-center read access
    - internal evaluation spreadsheet
    credentials_required:
    - sandbox mailbox token
    - help-center export access
    external_actions:
    - draft customer-facing replies for human approval
    prohibited_actions:
    - send emails
    - delete tickets
    - issue refunds
    - modify production records
    logging_requirements:
    - prompt and response logs
    - tool-call logs
    - reviewer approval records
    - error and rollback events
    retention_policy: TBD
    rollback_plan_status: documented
    incident_contact: TBD
    security_decision: conditional go
    residual_risks:
    - personal information may appear in ticket text
    - prompt-injection attempts require reviewer training
    required_before_launch:
    - confirm retention policy
    - name security contact
    - complete reviewer training
  customer_success:
    customer_success_id: CS-2026-0051
    account_stage: post-launch support
    health_status: stable
    health_score: 82
    renewal_date: TBD
    support_cadence: weekly during pilot, monthly after handoff
    open_commitments:
    - schedule 30-day adoption review
    - confirm production change-order interest
    - collect reviewer feedback
    expansion_signals:
    - returns workflow mentioned by sponsor
    relationship_risks:
    - security contact unknown
    - billing approval route still draft
    advocacy_timing: no testimonial ask until 30-day adoption review
  case_study:
    case_study_id: CASE-2026-007
    proof_type: public-named-client-case-study
    approval_status: client-approved for named use
    attribution_allowed: true
    client_quote: The pilot gave our reviewers a cleaner starting point without removing human judgment.
    quote_approver: Jordan Lee
    measured_outcomes:
      routing_accuracy: 93.4%
      reply_quality_score: 4.3/5
      unapproved_sends: 0
    qualitative_observations:
    - reviewers reported more consistent escalation notes
    - sponsor valued approval-gate clarity
    confidentiality_constraints:
    - do not publish raw ticket text
    - do not identify customer accounts
    public_channels:
    - sales one-pager
    - website story
    - proposal proof snippet
  certificate:
    recipient_name: Dana Whitfield
    recipient_email: [REDACTED_SECRET]
    certificate_title: Building Bounded Agentic Workflows with Human Approval Gates
    issue_date: 2026-05-22
    certificate_id: COMP-BBAWW-20260522-A7B926
    signatory_name: Timothy Gregg
    signatory_title: Agent Whisperer
    certificate_output_pdf: assets/examples/example.pdf
  email:
    email_sequence_id: PRO-OUT-014
    email_stage: proposal follow-up
    recipient_name: Jordan Lee
    recipient_email: [REDACTED_SECRET]
    sender_name: Timothy Gregg
    sender_email: [REDACTED_SECRET]
    subject: Support triage pilot scope for review
    call_to_action: confirm whether the approval gate matches your process
    tone: direct, practical, low-hype
    proof_snippet_allowed: true
    send_status: draft only
    external_send_approval: required
  envelope:
    sender_name: CompleteTech LLC
    sender_address:
      line1: 7901 4th St N
      line2: Ste 300
      city: St. Petersburg
      state: FL
      postal_code: '33702'
    recipient_name: Morgan Reyes
    recipient_title: General Counsel
    recipient_organization: Northwind Trading Co.
    recipient_address:
      line1: 410 Market Street
      line2: Suite 800
      city: Pittsburgh
      state: PA
      postal_code: '15222'
    attention_line: 'Attn: Morgan Reyes, General Counsel'
    postage_box_text: FIRST-CLASS MAIL
    return_address_enabled: true
    package_manifest:
    - northwind_support_triage_agreement.pdf
    - northwind_support_triage_deposit_invoice.pdf
    - certificate_dana_whitfield.pdf
    delivery_mode: physical mail
    delivery_readiness: ready after billing approval
  generated_outputs:
    discovery_markdown: agentic_discovery_skill/assets/examples/example.md
    discovery_pdf: agentic_discovery_skill/assets/examples/example.pdf
    proposal_markdown: agentic_proposal_skill/assets/examples/example.md
    proposal_pdf: agentic_proposal_skill/assets/examples/example.pdf
    contract_markdown: agentic_contract_skill/assets/examples/example.md
    contract_pdf: agentic_contract_skill/assets/examples/example.pdf
    invoice_markdown: agentic_invoice_skill/assets/examples/example.md
    invoice_pdf: agentic_invoice_skill/assets/examples/example.pdf
    delivery_markdown: agentic_delivery_skill/assets/examples/example.md
    delivery_pdf: agentic_delivery_skill/assets/examples/example.pdf
    security_markdown: agentic_security_review_skill/assets/examples/example.md
    security_pdf: agentic_security_review_skill/assets/examples/example.pdf
    customer_success_markdown: agentic_customer_success_skill/assets/examples/example.md
    customer_success_pdf: agentic_customer_success_skill/assets/examples/example.pdf
    case_study_markdown: agentic_case_study_skill/assets/examples/example.md
    case_study_pdf: agentic_case_study_skill/assets/examples/example.pdf
    certificate_markdown: agentic_certificate_skill/assets/examples/example.md
    certificate_pdf: agentic_certificate_skill/assets/examples/example.pdf
    email_markdown: agentic_email_skill/assets/examples/example.md
    email_pdf: agentic_email_skill/assets/examples/example.pdf
    envelope_markdown: agentic_envelope_skill/assets/examples/example.md
    envelope_pdf: agentic_envelope_skill/assets/examples/example.pdf


path: references/skill-layout-standardization.md
content: # Skill Layout Standardization

This audit covers the sibling `agentic_*_skill` repositories that make up the CompleteTech LLC agentic services skill library.

## Shared Shell

Every related skill should expose this outer shell so humans, automation, and the orchestrator can find the same kinds of assets in the same places:

- `.gitattributes`
- `.gitignore`
- `LICENSE`
- `README.md`
- `SKILL.md`
- `BRAND_ASSETS.md`
- `requirements.txt`
- `agents/`
- `assets/`
- `assets/diagrams/`
- `references/`
- `scripts/`
- `examples/`

## Intentional Differences

The shared shell does not require identical internals.

| Skill family | Repositories | Intentional differences |
|---|---|---|
| Renderer/reference skills | case study, customer success, delivery, discovery, email, invoice, proposal, security review | Use `references/` catalogs and `scripts/render_*.py` helpers to render branded draft artifacts. |
| Generator/config skills | certificate, contract, envelope | Keep root-level `generate_*.py`, `config.ini`, `pyrightconfig.json`, and input override examples for backwards-compatible CLI use. Shared `references/` and `scripts/` folders exist for supporting docs and future helper automation. |
| Orchestrator | services orchestrator | Keeps workflow schemas/adapters in `references/` and coordinates routing/state instead of generating a specialist artifact directly. |

## Mermaid Sources

Each skill keeps its Mermaid workflow source under `assets/diagrams/`. README files should include the inline Mermaid for GitHub rendering and link to the `.mmd` source. PNG diagram files are not part of the standard shell.

## Placeholder Directories

When a standard directory has no active implementation files yet, keep a short `README.md` explaining the directory's intended use. This makes the layout commit-friendly without inventing unused code.

## Validation Expectations

- Mermaid sources should parse/render with Mermaid CLI when available.
- YAML, JSON, and INI files should parse with standard parsers.
- Generator-style workflows should retain their existing root CLI entry points.
- Existing business logic, templates, examples, generated previews, and outputs should not be deleted as part of shell standardization.


path: requirements.txt
content: # Branded PDF artifact rendering (scripts/render_pdf.py)
reportlab==4.5.1
pyyaml==6.0.3
# Optional: only needed to also emit a PNG preview montage (scripts/render_pdf.py --png)
pypdfium2==5.8.0
pillow==12.2.0


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)