# Ada AI project-management skills

Three [Agent Skills](https://agentskills.io) for pi that treat the Ada AI
**knowledge base** as the durable home for what a repository is about. The
knowledge base is a set of org-scoped **projects** of inter-connected markdown
documents, linked with Obsidian-style `[[slug]]` wikilinks that the server
treats as opaque text (no parsing, no validation, no backlinks) — see
[`../docs/content/docs/knowledge-base.mdx`](../docs/content/docs/knowledge-base.mdx)
for the contract these skills implement.

| Skill | When to load it |
|---|---|
| [`project-binding`](./project-binding/SKILL.md) | Bind this git repo to one knowledge-base project (personal or org); check, change, or unbind. Writes `.pi/kb-binding.json`. |
| [`kb-summarize`](./kb-summarize/SKILL.md) | Summarize the current conversation/transcript into the bound project as focused, inter-linked `[[slug]]` notes. |
| [`kb-retrieve`](./kb-retrieve/SKILL.md) | List documents, fetch one by slug/id with content, follow `[[slug]]` links outward, and compute Obsidian-style backlinks. |

They share [`lib/kb-client.mjs`](./lib/kb-client.mjs) — a zero-dependency client
(Node >= 18 builtins only) — and [`lib/AUTH.md`](./lib/AUTH.md) for credentials.

## Authentication (read this first)

The knowledge base lives under `/me/*`, which accepts **only a Stytch session
JWT** — a proxy key (`sk-rc-…`) is rejected with `401` (verified in
`infra/backend/serving-api/proxy`). The device flow mints a proxy key for
`/v1/*` only; there is no CLI flow that mints a knowledge-base token today.
So the skills reuse the browser session:

```sh
export ADA_SESSION_JWT='…'              # cookie `rb_session` (httpOnly) on ada.ai
export ADA_STYTCH_SESSION_TOKEN='…'     # cookie `rb_stytch_session` (7-day)
export ADA_ORG_ID='<id>'                # optional: scope to an org (else personal)
```

With `ADA_STYTCH_SESSION_TOKEN` set, `lib/kb-client.mjs` refreshes the JWT
automatically on `401` via `POST /auth/stytch/refresh`, mirroring the
dashboard BFF. See [`lib/AUTH.md`](./lib/AUTH.md) for how to copy the cookie
values from your browser and how to verify it works.

> **Backend TODO (for the ada team):** a device-flow-style route that mints a
> knowledge-base-scoped token — analogous to the proxy key for `/v1/*` — would
> remove the dependency on the browser session. Until then these skills reuse
> the two cookies above.

## Quick start

### From inside a pi session (slash commands)

The `ada-kb` extension wires these skills into `ada:*` commands (the
commands call the same shared client, so behavior is identical to the
scripts):

```
/ada:bind "ada-my-pi" --create --description "Design notes for the pi extensions."
/ada:list
/ada:get auth-model
/ada:upsert session-kb-skills --title "Session: KB skills" --content "Decided [[auth-model]]."
/ada:backlinks kb-architecture
/ada:help
```

The same extension also registers LLM-callable tools (`kb_show_binding`,
`kb_list_projects`, `kb_list_documents`, `kb_get_document`,
`kb_upsert_document`, `kb_backlinks`, `kb_resolve_links`) so the agent can
read and write the knowledge base itself during a turn. Enable/disable them
with `/tools`.

### From the shell (CLI scripts)

```sh
# 1. Authenticate (once per ~7-day session)
export ADA_SESSION_JWT='…' ADA_STYTCH_SESSION_TOKEN='…'

# 2. Bind this repo to a project (creates it if needed)
node ./skills/project-binding/scripts/bind.mjs "ada-my-pi" \
  --create --description "Design notes for the pi extensions."

# 3. Save the current session's takeaways as inter-linked notes
node ./skills/kb-summarize/scripts/upsert-doc.mjs \
  --slug session-kb-skills --title "Session: KB skills" --content "$(cat note.md)"

# 4. Ground a later task in the knowledge base
node ./skills/kb-retrieve/scripts/list-docs.mjs
node ./skills/kb-retrieve/scripts/get-doc.mjs auth-model
node ./skills/kb-retrieve/scripts/backlinks.mjs kb-architecture
```

## Layout

```
skills/
  lib/
    kb-client.mjs     # shared zero-dep client + binding + slug/wikilink helpers
    AUTH.md            # how to obtain and refresh session credentials
  project-binding/
    SKILL.md
    scripts/{bind,unbind,show}.mjs
  kb-summarize/
    SKILL.md
    scripts/{upsert-doc,format-template}.mjs
  kb-retrieve/
    SKILL.md
    scripts/{list-docs,get-doc,backlinks,resolve-links}.mjs
```

These skills are registered in `package.json` under `pi.skills` and load when
the package is installed (`pi install ./ada-my-pi -l`).