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

# 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:

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

Update Task Status

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:

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:

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

# === 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 --offline "..."   # deterministic fake adapter (CI / no API keys)
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 (finished — 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)

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:

---
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.