can-you-assist/AGENTS.md

# can-you-assist - Agent Instructions

## Worker Role

Primary worker agent: Grok Build / Grok Code.

Run from the repository root. When available, start with `grok inspect` to
confirm Grok has discovered this `AGENTS.md`, the repo files, and any local
`.grok/` configuration. The xAI Build docs say Grok reads the `AGENTS.md`
instruction-file family and can inspect discovered instructions, skills,
plugins, hooks, and MCPs:

- https://docs.x.ai/build/overview
- https://docs.x.ai/build/features/skills-plugins-marketplaces

This file is the canonical worker guide for this repo. Do not assume a Claude
Code MCP server is available; use the State Hub HTTP API unless the operator
explicitly provides another integration.

## Repo Identity

**Purpose:** Console-native, backend-agnostic LLM assistant for practical local
work from the shell, using user-controlled context, memory, and provider
configuration.

**Domain:** capabilities
**Repo slug:** can-you-assist
**Topic ID:** `64418556-3206-457a-ba29-6884b5b12cf3`
**Workplan prefix:** `CYA-WP-`
**Command name:** `cya`

## Product Direction

`cya` should help users express intent in natural language from a terminal and
receive useful, explainable help for command-line tasks. It should be good at
repository inspection, file and note workflows, command suggestion, command
explanation, and local context summarization.

Keep these boundaries crisp:

- `can-you-assist` owns the CLI assistant experience, local context gathering,
  safety prompts, command explanations, and orchestration of assistance.
- `llm-connect` owns provider/backend access. Do not hard-code one LLM vendor
  as the conceptual foundation.
- `phase-memory` owns user-controlled memory, preferences, history, and
  adaptation. Do not hide memory in opaque hosted state.
- State Hub tracks work, coordination, progress, and cross-repo handoffs. It
  should not become a runtime dependency of the `cya` CLI.

## State Hub Integration

The Custodian State Hub tracks work across all domains. Interact via HTTP REST.

| Context | URL |
|---------|-----|
| Local workstation | `http://127.0.0.1:8000` |
| Remote via tunnel | `http://127.0.0.1:18000` |

### Orient At Session Start

```bash
# Offline brief - generated by State Hub consistency tooling when available
cat .custodian-brief.md

# Active workstreams for this domain/topic
curl -s "http://127.0.0.1:8000/workstreams/?topic_id=64418556-3206-457a-ba29-6884b5b12cf3&status=active" \
  | python3 -m json.tool

# Inbox for this repo worker
curl -s "http://127.0.0.1:8000/messages/?to_agent=can-you-assist&unread_only=true" \
  | python3 -m json.tool
```

Mark a message read:

```bash
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
  -H "Content-Type: application/json" -d '{}'
```

### Update Task Status

```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
  -H "Content-Type: application/json" \
  -d '{"status": "in_progress"}'
```

Allowed task statuses: `todo`, `in_progress`, `done`, `blocked`.

### Log Progress

Log progress at session close and after meaningful milestones:

```bash
curl -s -X POST http://127.0.0.1:8000/progress/ \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "what changed",
    "event_type": "note",
    "author": "grok",
    "workstream_id": "<uuid>",
    "task_id": "<uuid>"
  }'
```

Omit `workstream_id` and `task_id` only when there is no applicable item.

## Session Protocol

Start:

1. Run `git status --short`.
2. Read `.custodian-brief.md` if present; if absent, use the State Hub API
   queries above.
3. Check the `can-you-assist` inbox and mark read only after acting on a
   message or carrying it forward in a workplan.
4. Scan `workplans/` if it exists. If it does not exist yet, the onboarding
   workstream should create it.
5. Pick the highest-priority active task that is unblocked and update task
   status before substantial work.

During work:

- Keep changes small and inspectable.
- Treat command execution safety as product behavior: explain destructive or
  broad filesystem commands and require explicit confirmation before suggesting
  execution.
- Before requesting API keys, SSH access, login tokens, or database passwords,
  run `warden route find` / `warden route show` per **Credential and access routing**.
- Do not commit secrets, API keys, local transcripts, private notes, or hidden
  memory contents.
- Preserve user-controlled memory as a design principle. Prefer explicit,
  inspectable local files over hidden state.
- Record significant design decisions with `POST /decisions/`.

Close:

1. Update workplan task statuses to match reality.
2. Log a progress event in State Hub.
3. Ask the custodian operator to run:

```bash
cd ~/state-hub && make fix-consistency REPO=can-you-assist
```

That syncs repo workplan files into the State Hub DB and regenerates
`.custodian-brief.md`.

## Current Grok Handoff

State Hub registration has been created for `can-you-assist` under the
`capabilities` domain. Look for active workstream
`repo-integration-can-you-assist`.

First useful worker moves:

1. Read `INTENT.md`, `README.md`, this `AGENTS.md`, and `SCOPE.md`.
2. Create `workplans/CYA-WP-0001-console-native-mvp.md` with a focused first
   implementation slice: CLI skeleton, safe command-assistance flow,
   llm-connect adapter boundary, phase-memory boundary, and test strategy.
3. Keep the first workplan `ready` until the repo state and stack choice are
   reviewed. Move it to `active` when implementation begins.
4. Run or request SBOM ingest from State Hub after the first dependency files
   exist.
5. Register obvious extension points and technical debt once there is code to
   anchor them.

## Commands

```bash
# === Packaging & Installation (CYA-WP-0004) ===

# Recommended: Stay on latest development code
make dev-install

# Build distribution packages (sdist + wheel)
make dist

# Prepare a release (tests + clean build)
make release-prep

# Verify a built wheel in isolation
make check-dist

# Run the assistant
cya "your natural language request here"
cya --help
cya --explain-context "show me what context would be collected"

# Memory features (0003 + 0005)
cya retrospect                    # Guided reflection session
# Memory: Profile 0 baseline + production Profile 1 (CYA-WP-0006).
# Profiles 2–3 (hierarchical synthesis, procedural rules) remain roadmap — see MemoryVision.md.

# Tests
python -m pytest tests/ -q

# Git / inspection
git status --short
git log --oneline -5
rg --files
```

No formal lint or build system yet (ruff is configured in pyproject.toml but not enforced in CI for the first slice). Add `make test` / `make lint` targets in a follow-on when needed.

Current primary entry point: `cya` (after editable install).

Relevant workplans:
- `workplans/CYA-WP-0002-memory-integration-roadmap.md`
- `workplans/CYA-WP-0003-contextual-memory-activation-and-retrospection.md`
- `workplans/CYA-WP-0004-dev-install-and-release-packaging.md`
- `workplans/CYA-WP-0005-agentic-memory-profiles-and-phase-memory-feedback.md`
- `workplans/CYA-WP-0006-profile-1-production-hardening.md` (finished)
- `workplans/CYA-WP-0007-interactive-shell-session.md` (ready — interactive REPL + history + hub)
- `workplans/CYA-WP-0008-llm-connect-adapter-integration.md` (ready — real LLM behind adapter seam)

---

## Credential and access routing

> Fleet template mirrored in `.claude/rules/credential-routing.md` for Claude Code.
> Re-sync both from `~/ops-warden/wiki/CredentialRouting.md` when the catalog changes.

**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect**
for inference. Run this check **before** requesting secrets, API keys, SSH access,
login tokens, or database passwords — in any repo, not only `ops-warden`.

ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every
other credential need belongs to another subsystem. **Do not** message
`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key.

### Lookup (do this first)

```bash
warden route find "<describe your need>" --json
warden route show <catalog-id> --json
```

Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`).

| Agent runtime | How to orient |
| --- | --- |
| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=can-you-assist` is for coordination, not secret vending |
| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership |
| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |

### Quick routing table

Prefer `warden route find` for repo-specific needs. Common routes:

| I need… | Owner | ops-warden executes? |
| --- | --- | --- |
| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` |
| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only |
| Login / OIDC / MFA | key-cape / Keycloak | No — route only |
| Authorization decision | flex-auth | No — route only |
| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only |

### Anti-patterns (do not do these)

- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc.
- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist
- Pasting secrets into Git, State Hub, workplans, logs, or chat

### Other capabilities (reuse-surface)

Non-credential capabilities are usually discovered through **reuse-surface** federation
(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in
every repo's agent instructions because it is high-frequency, high-risk, and easy to
get wrong.

**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`

---

## Workplan Convention

Work items originate as files in this repo. The hub is a read/cache/index
layer that rebuilds from files.

**File location:** `workplans/CYA-WP-NNNN-<slug>.md`

**Archived location:** `workplans/archived/YYMMDD-CYA-WP-NNNN-<slug>.md`

**Ad hoc tasks:** small opportunistic fixes may use
`workplans/ADHOC-YYYY-MM-DD.md` with task ids like
`ADHOC-YYYY-MM-DD-T01`. Use this only for low-risk work completed directly.

Frontmatter:

```yaml
---
id: CYA-WP-NNNN
type: workplan
title: "..."
domain: capabilities
repo: can-you-assist
status: proposed | ready | active | blocked | backlog | finished | archived
owner: grok
topic_slug: foerster-capabilities
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
state_hub_workstream_id: "<uuid>"   # written by fix-consistency - do not edit
---
```

Task block format:

````
## Task Title

```task
id: CYA-WP-NNNN-T01
status: todo | in_progress | done | blocked
priority: high | medium | low
state_hub_task_id: "<uuid>"         # written by fix-consistency - do not edit
```

Task description text.
````

Status progression: `todo` -> `in_progress` -> `done` or `blocked`.