system-onboarding

name	system-onboarding
description	Use when CTOX is working with any external system (codebase, platform, API, ticket system, database, CRM, infrastructure) and must build a knowledge base, skillbooks, runbooks, and operator-visible review tickets through generic primitives. This is the default onboarding path, not a special case.
metadata	{"short-description":"Onboard any system through skill-driven discovery and knowledge building"}
cluster	knowledge_bootstrap

System Onboarding

CTOX Runtime Contract

• Task spawning is allowed only for real bounded work steps that add mission progress, external waiting, recovery, or explicit decomposition. Do not spawn work merely because review feedback exists.
• The Review Gate is a quality checkpoint, not a control loop. After review feedback, continue the same main work item whenever possible and incorporate the feedback there.
• Do not create review-driven internal work cascades. If more work is needed, reuse or requeue the existing parent work item; create a new task only when it is a distinct bounded work step with a stable parent pointer.
• Every durable follow-up, queue item, plan emission, or internal work item must have a clear parent/anchor: message key, work id, thread key, ticket/case id, or plan step. Missing ancestry is a harness bug, not acceptable ambiguity.
• Rewording-only feedback means revise wording on the same artifact. Substantive feedback means add new evidence or implementation progress. Stale feedback means refresh or consolidate current runtime state before drafting again.
• Before adding follow-up work, check for existing matching internal work, queue, plan, or ticket state and consolidate rather than duplicating.

The typical CTOX work pattern is: there is a system to onboard. Codebases, CRM platforms, API integrations, ticket systems, databases, infrastructure — integration is the default mode of work, and this is the central onboarding skill that drives it.

Use this skill whenever CTOX is operating against an external system and needs to build operational understanding from scratch — whether triggered automatically by a Kanban source sync or started manually for a non-Kanban system (CRM, API, database, codebase, platform).

The kernel provides storage, references, internal work CRUD, publishing, and audit. This skill owns the onboarding behavior.

The CTOX runtime store is the only durable state plane. Ticket knowledge entries are fact/context records. Continuity commits, ticket/source bindings, verifications, communication records, and other runtime DB rows are durable mission evidence. Reusable operational knowledge requires the higher hierarchy: source skills, skillbooks, runbooks, and runbook items. Markdown files or workspace artifacts do not count as durable state by themselves.

Read the phase guide in references/onboarding-phases.md. Read the deterministic stage plan in references/onboarding-plan.md.

Default rule:

• follow the stage plan in order
• do not redesign the onboarding flow mid-run
• only change the plan when an operator explicitly asks for an adjustment or a real blocker makes the next stage impossible

When the system understanding problem is primarily driven by exports, record lists, CMDB tables, service catalogs, or other row-shaped data, first use tabular-knowledge-bootstrap so the source becomes generic discovery knowledge before you project it into the ticket knowledge plane.

When there is enough durable ticket history or an export of desk history, use dataset-skill-creator to build a desk-specific operating skill from that evidence. The goal is not only to observe the desk, but to give CTOX a reusable skill that can guide later live-ticket handling in the style of this desk.

Core Rules

No fixed onboarding choreography belongs in the ticket kernel.

Do not expect prebuilt onboarding tickets from ctox ticket sync.

Create only the internal work items that are justified by the observed source knowledge and current gaps.

The remote ticket system is only a communication and review surface. CTOX runtime knowledge remains the source of truth.

When onboarding reveals missing access rights, credentials, or monitoring blind spots, do not improvise around them. Create explicit CTOX work or requests through the ticket and secret primitives.

Visible operator work is mandatory. If you create internal CTOX work in the remote ticket system, you must work it like a teammate:

1. create the task
2. assign it to the CTOX identity when the adapter supports assignment
3. leave an initial internal note in plain human language
4. leave progress or block notes as the work evolves
5. finish or block the task with a final internal note and a state transition

Do not leave remote work items hanging without ownership, notes, or an end state.

When you need remote ticket work, you must go through the ctox ticket internal-work-* and ctox ticket access-request-put primitives.

Do not use raw HTTP calls, curl, ad hoc browser actions, or direct remote API writes to create or update ticket work during onboarding. If the generic ticket primitives are insufficient, stop and state the missing primitive instead of bypassing CTOX truth.

Knowledge System Integration — Mandatory

Onboarding is incomplete unless CTOX has both the needed fact/context registry and the reusable operating procedure for the system. Workspace markdown, plan steps, conversation history, and reply prose are not knowledge.

• Every onboarding phase starts with a knowledge inventory:

  ctox ticket knowledge-list --system "<system>"
  

• Every verified fact you learn about the system must be registered as a durable ticket_knowledge_entries row or loaded into the ticket fact/context registry through the bootstrap skills (tabular-knowledge-bootstrap, dataset-skill-creator, skillbook-runbook-bootstrap). Example:

  ctox ticket knowledge-load --ticket-key "<ticket-key>" --domains "vendor_api,operational,data_model"
  

• Skillbooks (knowledge_skillbooks), runbooks (knowledge_runbooks), and runbook items (knowledge_runbook_items) are mandatory outputs when onboarding discovers reusable operating procedure, not optional polish. A nonzero ticket_knowledge_entries count is not enough to claim that CTOX learned a skill.

• Learning is real work: produce an internal work item and a fact/context entry for each meaningful verified fact; when the fact changes how future work should be performed, promote it into the Skillbook/Runbook hierarchy. Knowledge that lives only in chat history, plan steps, or workspace files does not count.

• Sync-driven onboarding triggers (ctox ticket sync / ticket_source_controls) only fire for genuine Kanban ticket systems. For CRMs, APIs, platforms, codebases, and other non-Kanban software, you start onboarding yourself — but the knowledge-population requirements above are identical.

• Once a source-specific operating skill is justified, bind it on the source so live work routes to it:

  ctox ticket source-skill-set --system "<system>" --skill "<system>-desk-operator"
  

Required Inputs

Refresh and inspect the current source knowledge first:

ctox ticket sync --system "<system>"
ctox ticket knowledge-list --system "<system>" --limit 20
ctox ticket knowledge-show --system "<system>" --domain "source_profile" --key "observed"

Inspect any already-open CTOX internal work:

ctox ticket internal-work-list --system "<system>" --limit 20

Inspect the secure local secret inventory only through explicit local commands:

ctox secret list
ctox secret show --scope "<scope>" --name "<name>"

Primitive Used For New Work

Create an internal work item in CTOX runtime state:

ctox ticket internal-work-put --system "<system>" --kind "<kind>" --title "<title>" --body "<text>" --metadata-json '<json>'

Publish an internal work item into the remote ticket system when the operator-facing surface is useful:

ctox ticket internal-work-put --system "<system>" --kind "<kind>" --title "<title>" --body "<text>" --metadata-json '<json>' --publish

Or publish an already-created item later:

ctox ticket internal-work-publish --work-id "<work_id>"

Assign published internal work to the remote CTOX identity:

ctox ticket internal-work-assign --work-id "<work_id>" --assignee "self" --assigned-by "ctox"

Append an internal operator-facing progress note:

ctox ticket internal-work-note --work-id "<work_id>" --body "<plain human note>" --authored-by "ctox" --visibility internal

Block or finish the work visibly:

ctox ticket internal-work-transition --work-id "<work_id>" --state blocked --transitioned-by "ctox" --note "<plain human block note>" --visibility internal
ctox ticket internal-work-transition --work-id "<work_id>" --state closed --transitioned-by "ctox" --note "<plain human completion note>" --visibility internal

Create an access request when onboarding cannot continue without rights or secrets:

ctox ticket access-request-put --system "<system>" --title "<title>" --body "<text>" --required-scopes "<csv>" --secret-refs "<csv>" --channels "mail,jami" --publish

Store a newly delivered secret only in the encrypted local secret store:

ctox secret put --scope "<scope>" --name "<name>" --value "<secret>" --description "<text>" --metadata-json '<json>'

Ingest monitoring evidence into the knowledge plane when a monitoring system is available:

ctox ticket monitoring-ingest --system "<system>" --snapshot-json '<json>'

Build and activate a desk-specific operating skill when the source has enough history:

ctox ticket history-export --system "<system>" --output "runtime/output/<system>_history.jsonl"
ctox ticket knowledge-bootstrap --system "<system>"
ctox ticket source-skill-import-bundle --system "<system>" --bundle-dir "runtime/generated-skills/<system>-desk-operator"
ctox ticket source-skill-set --system "<system>" --skill "<system>-desk-operator" --status active

This tool will:

1. export canonical ticket history from the CTOX mirror
2. build the operating-model skill from that exported history
3. run the generated-skill evaluation against the same exported history
4. activate the generated skill for the source with ctox ticket source-skill-set

Recommended Onboarding Work Types

These are templates, not mandatory fixed outputs:

• system-onboarding
• label-landscape-review
• glossary-candidate-review
• service-catalog-seeding
• infrastructure-map-review
• team-model-review
• access-request
• monitoring-landscape-review
• adoption-gap-review

Create only the items that are supported by observed evidence.

Operating Pattern

The default execution path is the native CTOX ticket and internal work CLI:

ctox ticket knowledge-bootstrap --system "<system>"
ctox ticket internal-work-list --system "<system>" --state open
ctox ticket source-skills --system "<system>"

Do not execute embedded onboarding scripts from this system skill. If a stage cannot be completed through ctox ticket, ctox secret, or ctox skills, stop and add the missing CLI/API path first.

Manual building blocks remain available when the operator asks for an adjustment:

1. Sync and inspect the observed source knowledge.
2. Create or advance exactly one visible onboarding guide for the source.
3. Create only justified onboarding work items through internal-work-put.
4. Publish them only when the remote review surface is useful.
5. When published, immediately assign the work to CTOX if supported and leave an initial internal note with the concrete next step or blocker.
6. Work the item through notes and transitions instead of spawning more tickets than necessary.
7. Keep the remote ticket concise, human, and operator-facing; keep the real model in CTOX runtime state.
8. When rights or secrets are missing, create an explicit access request and use mail or Jami if the decision cannot be closed inside the ticket surface.
9. Ingest monitoring observations into the knowledge plane instead of leaving them as free-form ticket prose.
10. Once the source has enough history, build a desk-specific operating skill and bind it to the source with ctox ticket source-skill-set.
11. Re-run the onboarding guide step after new evidence appears. The guide should loosen as active source skills, confirmed runbooks, and real assigned work accumulate.
12. Do not treat a workspace analysis document as onboarding completion. Onboarding is incomplete until the relevant source controls, mirrored tickets, ticket fact/context entries, bindings, and applicable Skillbook/Runbook hierarchy are visible in CTOX runtime state.

Skill Activation Check

After building a desk-specific skill, verify that live ticket routing prefers it:

ctox ticket source-skills --system "<system>"

You are done with activation only when:

• the generated skill exists under runtime/generated-skills/
• the source binding is visible through ctox ticket source-skills
• new routed ticket work for that source receives the generated skill as the preferred skill instead of only a generic onboarding skill

The handoff rule is:

• before an active source skill exists, live work should prefer system-onboarding
• once an active source skill exists, normal work should prefer that source skill
• the onboarding skill should then remain only for the guide itself, explicit onboarding work, and exception correction

Evaluation Loop

Every onboarding round that creates or updates a desk-specific skill must be evaluated qualitatively.

Minimum loop:

1. pick 3 to 5 real open or historically representative tickets from the source
2. query the generated skill against those tickets
3. inspect whether the suggested family, next steps, escalation threshold, and note style are actually useful
4. if they are weak, rebuild or refine the skill before leaving it active

Do not treat “skill file exists” as success. Activation without qualitative usefulness is not a finished onboarding step.

Remote Writing Style

Everything written into the remote ticket system must read like a coworker update.

Good remote note shape:

• what you have actually observed
• why that matters for operations
• what the non-obvious lever is
• what is blocked or still unclear
• which exact decision you now need

Never write remote notes that mention:

• CTOX runtime knowledge
• database tables
• metadata blobs
• case IDs, bundle versions, or control schemas unless an operator truly needs them
• CLI commands for normal understanding
• parser-like field dumps

Never publish onboarding tickets that lack:

• concrete counts
• example tickets
• an operational implication
• a hidden or non-obvious lever
• a clear decision or correction request

Do not copy structured metadata into the ticket body. Remote ticket text must be authored fresh in plain language.

Important Boundaries

• Do not assume every ticket system needs the same first tickets.
• Do not encode onboarding behavior in the ticket kernel.
• Do not treat the remote ticket text as canonical source truth after publication.
• Do not create internal work spam; prefer fewer, durable review items over many one-off tickets.
• Do not store raw secret values in ticket work or ticket knowledge. Only the encrypted local secret store may hold real secret material.
• Do not leave machine-authored meta commentary in remote tickets.
• Do not bypass the generic ticket primitives with direct remote API calls.
• Do not create more than one visible onboarding guide per source system. Advance the same guide through notes and state changes.