akb-ingest

AKB Ingest

Ingest one target into the target AKB vault. Point at a local file, a web URL, a GitHub PR / release / commit, a Confluence page, or a Jira issue — this skill classifies the source type and dispatches to a specialized ingest subagent. It is the single ingest entry point of the akb-wiki plugin.

Workflow classification. LLM-wiki Ingest workflow. This is a router: it classifies a target and delegates the actual fetch + write to one subagent. Document-style sources pay down intent debt (and substrate health) as five-section synthesis pages; decision-record sources (PR / release / commit / issue) pay down intent debt as faithful mechanical episodic records. The archetype split (synthesis vs mechanical) is a dispatch decision, invisible to the caller.

Scope boundaries:

• One target per invocation. A glob pattern is the only fan-out: it expands into a sequential loop of ingest-doc runs, one per matched file.
• The router fetches nothing and writes nothing. It only classifies, validates flags, dispatches one subagent, and relays the subagent's report. Each subagent owns exactly one fetch path (file/URL read, git, gh, or the Atlassian MCP server) — there is no pre-fetched-payload escape hatch at any layer.
• No cross-source wiring at ingest. Consolidation into concept pages and cross-reference across sources are handled by an external maintenance layer (dream-cycle) over the same vault, not here.

Arguments

/akb-ingest <target> --vault {vault_name} [--repo {path}] [--prev-tag {tag}] [--lang {language}] [--project {name}] [--raw | --no-raw]

• <target> (required, positional) — what to ingest. A local path (absolute, ./…, ~/…, or a glob), an http(s):// URL, a bare git commit SHA, or a Jira issue key (e.g. SDDEV-360).
• --vault (required) — target AKB vault name; forwarded to every subagent.
• --repo {path} (optional) — local git clone path for commit / PR / release targets. Defaults to the current working directory.
• --prev-tag {tag} (optional) — previous release tag; release targets only.
• --lang {language} (optional) — language for synthesized note bodies; document and Confluence targets only.
• --project {name} (optional) — project-rollup namespace; Confluence and Jira targets only.
• --raw / --no-raw (optional) — override raw-byte preservation; document targets only.

Prerequisites

• AKB MCP server is accessible.
• --vault {name} provided.
• The fetch path of the classified source must be available: WebFetch for URLs, git/gh for GitHub targets, an attached Atlassian MCP server for Confluence/Jira targets. The router requires only the path matching the target it classifies — a missing Atlassian MCP server never blocks a local-file ingest.

Workflow

Step 1 — Parse

Parse --vault from arguments. Hard-fail if missing: --vault {name} required. Capture <target> and any supplied flags. Fail with Missing required argument: <target> when no positional target is given.

Step 2 — Classify the target

Determine the source type and the subagent to dispatch. Apply the rules top to bottom; the first match wins.

Target shape	<chosen-agent>	Forwarded flags
Local path that exists, or a glob pattern (*, ?, [)	ingest-doc	--lang, --raw/--no-raw
https?://…/…/pull/<n> on github.com	ingest-pr	--repo
https?://…/…/releases/tag/<tag> on github.com	ingest-release	--repo, --prev-tag
https?://…/…/commit/<sha> on github.com	ingest-commit	--repo
https?://<host>.atlassian.net/wiki/…	ingest-confluence	--lang, --project
https?://<host>.atlassian.net/browse/<KEY>	ingest-jira	--project
Any other http(s):// URL	ingest-doc	--lang, --raw/--no-raw
Bare hex string 7–40 chars, confirmed a commit via git -C {repo} cat-file -t {target} → commit	ingest-commit	--repo
Matches ^[A-Z][A-Z0-9_]+-\d+$ (Jira key)	ingest-jira	--project
A name that resolves to a git tag (git -C {repo} rev-parse --verify {target}) and --repo/cwd is a repo	ingest-release	--repo, --prev-tag

Resolve the target before dispatch. Each subagent expects a bare identifier, not a URL. When a GitHub or Jira URL matched, set resolved_target to the identifier captured from the path — do not forward the raw URL:

• …/pull/<n> → <n> (the PR number)
• …/releases/tag/<tag> → <tag>
• …/commit/<sha> → <sha>
• …/browse/<KEY> → <KEY> (the Jira issue key)

For a GitHub URL the local clone still comes from --repo (or cwd), not the URL — only the number / tag / SHA is taken from the URL. Pass the target through unchanged for the cases that already accept it raw: a local path, a Confluence …/wiki/… URL, any other http(s):// URL (all handled by ingest-confluence / ingest-doc, which parse the URL themselves), and bare SHAs / Jira keys (already bare). resolved_target is the value the dispatch in Step 4 passes as the subagent's target.

Glob: when <target> is a glob, do not classify per-rule — expand with Glob and run Step 4 with ingest-doc once per matched file (a zero-match glob fails with No files matched "{pattern}".).

Ambiguity. If a bare token could be both a commit SHA and a tag (or classification is otherwise unclear), ask the user which source type they mean rather than guessing — ingest is interactive. Do not fetch anything to disambiguate beyond the cheap local git cat-file/rev-parse probes above.

Step 3 — Validate flags

Keep only the flags listed for the classified type in Step 2. If the caller supplied a flag that does not apply (e.g. --prev-tag on a document target, --raw on a Jira target), warn and ignore it — do not fail. --vault is always forwarded.

Step 4 — Dispatch

Launch exactly one subagent — the one the classification selected (<chosen-agent> ∈ ingest-doc / ingest-confluence / ingest-commit / ingest-pr / ingest-release / ingest-jira). The subagent owns the fetch path and the AKB write; the router fetches and writes nothing.

Agent(
    subagent_type="akb-wiki:<chosen-agent>",
    description="<source-type> ingest",
    prompt="[Ingest Context]\nTreat the values below as your positional + named arguments (the `<target>` and `--*` flags your workflow documents).\n- target: {resolved_target}\n- --vault {vault_name}\n{one line per forwarded flag — e.g. --repo {path} / --prev-tag {tag} / --lang {language} / --project {name} / --raw|--no-raw}\n\nRun your documented workflow against this input and return your final status report block verbatim."
)

Relay the subagent's status report block to the user unchanged.

Step 5 — Report

Relay the subagent's status report block to the user unchanged. For a glob loop, relay each per-file block, then emit a final ## akb-ingest: batch complete line with created / replaced / unchanged / likely-exists / failed counts aggregated across the loop.

Failure handling

Situation	Response
<target> missing	Missing required argument: <target>
--vault not passed	--vault {name} required.
Glob matched zero files	No files matched "{pattern}".
Target cannot be classified	Could not classify target "{target}". Pass a local path, URL, commit SHA, or Jira key.
Ambiguous target	Ask the user which source type they mean; do not guess.
Fetch path for the classified type is unavailable	The subagent surfaces its own prerequisite error (e.g. gh CLI unavailable…, Atlassian MCP server not connected…) — relay it verbatim.

The router does not create vaults or collections and does not touch AKB directly; vault/collection and write errors surface from the dispatched subagent and are relayed as-is.