dnotitia/akb/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. PROJ-123).
• --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.

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 one subagent with fork_context: false — the one the classification selected (<chosen-agent> ∈ ingest-doc / ingest-confluence / ingest-commit / ingest-pr / ingest-release / ingest-jira). Open its prompt file and use the contents as the worker prompt, with model gpt-5.4-mini and reasoning effort medium:

• ./support/agents/<chosen-agent>.md

Prepend an [Ingest Context] block instructing the worker to treat the resolved target, --vault {vault_name}, and any forwarded flags as its positional + named arguments. The worker owns the fetch path and the AKB write; the router fetches and writes nothing. Relay the worker's status report block 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

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.